Xilinx Processor IP Library

Software Drivers

xcanps.c File Reference

Detailed Description

Functions in this file are the minimum required functions for the XCanPs driver. See xcanps.h for a detailed description of the driver.

Note:
None.
 MODIFICATION HISTORY:

 Ver   Who    Date	Changes
 ----- -----  -------- -----------------------------------------------
 1.00a xd/sv  01/12/10 First release
 1.01a bss    12/27/11 Added the APIs XCanPs_SetTxIntrWatermark and
 			XCanPs_GetTxIntrWatermark.

#include "xcanps.h"

Functions

void XCanPs_Reset (XCanPs *InstancePtr)
u8 XCanPs_GetMode (XCanPs *InstancePtr)
void XCanPs_EnterMode (XCanPs *InstancePtr, u8 OperationMode)
u32 XCanPs_GetStatus (XCanPs *InstancePtr)
void XCanPs_GetBusErrorCounter (XCanPs *InstancePtr, u8 *RxErrorCount, u8 *TxErrorCount)
u32 XCanPs_GetBusErrorStatus (XCanPs *InstancePtr)
void XCanPs_ClearBusErrorStatus (XCanPs *InstancePtr, u32 Mask)
int XCanPs_Send (XCanPs *InstancePtr, u32 *FramePtr)
int XCanPs_Recv (XCanPs *InstancePtr, u32 *FramePtr)
int XCanPs_SendHighPriority (XCanPs *InstancePtr, u32 *FramePtr)
void XCanPs_AcceptFilterEnable (XCanPs *InstancePtr, u32 FilterIndexes)
void XCanPs_AcceptFilterDisable (XCanPs *InstancePtr, u32 FilterIndexes)
u32 XCanPs_AcceptFilterGetEnabled (XCanPs *InstancePtr)
int XCanPs_AcceptFilterSet (XCanPs *InstancePtr, u32 FilterIndex, u32 MaskValue, u32 IdValue)
void XCanPs_AcceptFilterGet (XCanPs *InstancePtr, u32 FilterIndex, u32 *MaskValue, u32 *IdValue)
int XCanPs_SetBaudRatePrescaler (XCanPs *InstancePtr, u8 Prescaler)
u8 XCanPs_GetBaudRatePrescaler (XCanPs *InstancePtr)
int XCanPs_SetBitTiming (XCanPs *InstancePtr, u8 SyncJumpWidth, u8 TimeSegment2, u8 TimeSegment1)
void XCanPs_GetBitTiming (XCanPs *InstancePtr, u8 *SyncJumpWidth, u8 *TimeSegment2, u8 *TimeSegment1)
int XCanPs_SetRxIntrWatermark (XCanPs *InstancePtr, u8 Threshold)
u8 XCanPs_GetRxIntrWatermark (XCanPs *InstancePtr)
int XCanPs_SetTxIntrWatermark (XCanPs *InstancePtr, u8 Threshold)
u8 XCanPs_GetTxIntrWatermark (XCanPs *InstancePtr)

Function Documentation

void XCanPs_AcceptFilterDisable (  XCanPs *  InstancePtr,
u32  FilterIndexes
) 
 

This routine disables individual acceptance filters. Up to 4 filters could be disabled. If all acceptance filters are disabled then all the received frames are stored in the RX FIFO.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
FilterIndexes specifies which filter(s) to disable. Use any XCANPS_AFR_UAF*_MASK to disable one filter, and "Or" multiple XCANPS_AFR_UAF*_MASK values if multiple filters need to be disabled. Any filter not specified in this parameter will keep its previous enable/disable setting. If all acceptance filters are disabled then all received frames are stored in the RX FIFO.
Returns:
None.
Note:
None.

void XCanPs_AcceptFilterEnable (  XCanPs *  InstancePtr,
u32  FilterIndexes
) 
 

This routine enables individual acceptance filters. Up to 4 filters could be enabled.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
FilterIndexes specifies which filter(s) to enable. Use any XCANPS_AFR_UAF*_MASK to enable one filter, and "Or" multiple XCANPS_AFR_UAF*_MASK values if multiple filters need to be enabled. Any filter not specified in this parameter will keep its previous enable/disable setting.
Returns:
None.
Note:
None.

void XCanPs_AcceptFilterGet (  XCanPs *  InstancePtr,
u32  FilterIndex,
u32 *  MaskValue,
u32 *  IdValue
) 
 

This function reads the values of the Acceptance Filter Mask and ID Register for the specified Acceptance Filter. Use XCANPS_IDR_* defined in xcanps_hw.h to interpret the values. Read the xcanps.h file and device specification for details.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
FilterIndex defines which Acceptance Filter Mask Register to get Mask and ID from. Use any single XCANPS_FILTER_* value.
MaskValue is a pointer to the data in which the Mask value read from the chosen Acceptance Filter Mask Register is returned.
IdValue is a pointer to the data in which the ID value read from the chosen Acceptance Filter ID Register is returned.
Returns:
None.
Note:
None.

u32 XCanPs_AcceptFilterGetEnabled (  XCanPs *  InstancePtr  ) 
 

This function returns enabled acceptance filters. Use XCANPS_AFR_UAF*_MASK defined in xcanps_hw.h to interpret the returned value. If no acceptance filters are enabled then all received frames are stored in the RX FIFO.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
The value stored in Acceptance Filter Register.
Note:
None.

int XCanPs_AcceptFilterSet (  XCanPs *  InstancePtr,
u32  FilterIndex,
u32  MaskValue,
u32  IdValue
) 
 

This function sets values to the Acceptance Filter Mask Register (AFMR) and Acceptance Filter ID Register (AFIR) for the specified Acceptance Filter. Use XCANPS_IDR_* defined in xcanps_hw.h to create the values to set the filter. Read the xcanps.h file and device specification for details.

This function should be called only after:

  • The given filter is disabled by calling XCanPs_AcceptFilterDisable();
  • And the CAN device is ready to accept writes to AFMR and AFIR, i.e., XCanPs_IsAcceptFilterBusy() returns FALSE.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
FilterIndex defines which Acceptance Filter Mask and ID Register to set. Use any single XCANPS_AFR_UAF*_MASK value.
MaskValue is the value to write to the chosen Acceptance Filter Mask Register.
IdValue is the value to write to the chosen Acceptance Filter ID Register.
Returns:
  • XST_SUCCESS if the values were set successfully.
  • XST_FAILURE if the given filter was not disabled, or the CAN device was not ready to accept writes to AFMR and AFIR.
Note:
None.

void XCanPs_ClearBusErrorStatus (  XCanPs *  InstancePtr,
u32  Mask
) 
 

This function clears Error Status bit(s) previously set in Error Status Register (ESR). Use the XCANPS_ESR_* constants defined in xcanps_hw.h to create the value to pass in. If a bit was cleared in Error Status Register before this function is called, it will not be modified.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Mask is he 32-bit mask used to clear bits in Error Status Register. Multiple XCANPS_ESR_* values can be 'OR'ed to clear multiple bits.
Note:
None.

void XCanPs_EnterMode (  XCanPs *  InstancePtr,
u8  OperationMode
) 
 

This function allows the CAN device to enter one of the following operation modes:

  • Configuration Mode: Pass in parameter XCANPS_MODE_CONFIG
  • Sleep Mode: Pass in parameter XCANPS_MODE_SLEEP
  • Normal Mode: Pass in parameter XCANPS_MODE_NORMAL
  • Loop Back Mode: Pass in parameter XCANPS_MODE_LOOPBACK.
  • Snoop Mode: Pass in parameter XCANPS_MODE_SNOOP.

Read the xcanps.h file and device specification for detailed description of each operation mode.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
OperationMode specify which operation mode to enter. Valid value is any of XCANPS_MODE_* defined in xcanps.h. Multiple modes can not be entered at the same time.
Returns:
None.
Note:
This function does NOT ensure CAN device enters the specified operation mode before it returns the control to the caller. The caller is responsible for checking current operation mode using XCanPs_GetMode().

u8 XCanPs_GetBaudRatePrescaler (  XCanPs *  InstancePtr  ) 
 

This routine gets Baud Rate Prescaler value. The system clock for the CAN controller is divided by (Prescaler + 1) to generate the quantum clock needed for sampling and synchronization. Read the device specification for details.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
Current used Baud Rate Prescaler value. The value's range is from 0 to 255.
Note:
None.

void XCanPs_GetBitTiming (  XCanPs *  InstancePtr,
u8 *  SyncJumpWidth,
u8 *  TimeSegment2,
u8 *  TimeSegment1
) 
 

This routine gets Bit time. Time segment 1, Time segment 2 and Synchronization Jump Width values are read in this function. According to device specification, the actual value of each of these fields is one more than the value read. Read the device specification for details.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
SyncJumpWidth will store the Synchronization Jump Width value after this function returns. Its value ranges from 0 to 3.
TimeSegment2 will store the Time Segment 2 value after this function returns. Its value ranges from 0 to 7.
TimeSegment1 will store the Time Segment 1 value after this function returns. Its value ranges from 0 to 15.
Returns:
None.
Note:
None.

void XCanPs_GetBusErrorCounter (  XCanPs *  InstancePtr,
u8 *  RxErrorCount,
u8 *  TxErrorCount
) 
 

This function reads Receive and Transmit error counters.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
RxErrorCount is a pointer to data in which the Receive Error counter value is returned.
TxErrorCount is a pointer to data in which the Transmit Error counter value is returned.
Returns:
None.
Note:
None.

u32 XCanPs_GetBusErrorStatus (  XCanPs *  InstancePtr  ) 
 

This function reads Error Status value from Error Status Register (ESR). Use the XCANPS_ESR_* constants defined in xcanps_hw.h to interpret the returned value.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
The 32-bit value read from Error Status Register.
Note:
None.

u8 XCanPs_GetMode (  XCanPs *  InstancePtr  ) 
 

This routine returns the current operation mode of the CAN device.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
  • XCANPS_MODE_CONFIG if the device is in Configuration Mode.
  • XCANPS_MODE_SLEEP if the device is in Sleep Mode.
  • XCANPS_MODE_NORMAL if the device is in Normal Mode.
  • XCANPS_MODE_LOOPBACK if the device is in Loop Back Mode.
  • XCANPS_MODE_SNOOP if the device is in Snoop Mode.
Note:
None.

u8 XCanPs_GetRxIntrWatermark (  XCanPs *  InstancePtr  ) 
 

This routine gets the Rx Full threshold from the Watermark Interrupt Register.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
The Rx FIFO full watermark threshold value. The valid values are 1 to 63.
Note:
None.

u32 XCanPs_GetStatus (  XCanPs *  InstancePtr  ) 
 

This function returns Status value from Status Register (SR). Use the XCANPS_SR_* constants defined in xcanps_hw.h to interpret the returned value.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
The 32-bit value read from Status Register.
Note:
None.

u8 XCanPs_GetTxIntrWatermark (  XCanPs *  InstancePtr  ) 
 

This routine gets the Tx Empty threshold from Watermark Interrupt Register.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
The Tx Empty FIFO threshold value. The valid values are 1 to 63.
Note:
None.

int XCanPs_Recv (  XCanPs *  InstancePtr,
u32 *  FramePtr
) 
 

This function receives a CAN Frame. This function first checks if RX FIFO is empty, if not, it then reads a frame from the RX FIFO into the given buffer. This function returns error code immediately if there is no frame in the RX FIFO.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
FramePtr is a pointer to a 32-bit aligned buffer where the CAN frame to be written.
Returns:
  • XST_SUCCESS if RX FIFO was not empty and a frame was read from RX FIFO successfully and written into the given buffer.
  • XST_NO_DATA if there is no frame to be received from the FIFO.
Note:
None.

void XCanPs_Reset (  XCanPs *  InstancePtr  ) 
 

This function resets the CAN device. Calling this function resets the device immediately, and any pending transmission or reception is terminated at once. Both Object Layer and Transfer Layer are reset. This function does not reset the Physical Layer. All registers are reset to the default values, and no previous status will be restored. TX FIFO, RX FIFO and TX High Priority Buffer are also reset.

When a reset is required due to an internal error, the driver notifies the upper layer software of this need through the error status code or interrupts. The upper layer software is responsible for calling this Reset function and then re-configuring the device.

The CAN device will be in Configuration Mode immediately after this function returns.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Returns:
None.
Note:
None.

int XCanPs_Send (  XCanPs *  InstancePtr,
u32 *  FramePtr
) 
 

This function sends a CAN Frame. If the TX FIFO is not full then the given frame is written into the the TX FIFO otherwise, it returns an error code immediately. This function does not wait for the given frame being sent to CAN bus.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
FramePtr is a pointer to a 32-bit aligned buffer containing the CAN frame to be sent.
Returns:
  • XST_SUCCESS if TX FIFO was not full and the given frame was written into the FIFO.
  • XST_FIFO_NO_ROOM if there is no room in the TX FIFO for the given frame.
Note:
None.

int XCanPs_SendHighPriority (  XCanPs *  InstancePtr,
u32 *  FramePtr
) 
 

This routine sends a CAN High Priority frame. This function first checks if TX High Priority Buffer is empty. If yes, it then writes the given frame into the Buffer. If not, this function returns immediately. This function does not wait for the given frame being sent to CAN bus.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
FramePtr is a pointer to a 32-bit aligned buffer containing the CAN High Priority frame to be sent.
Returns:
  • XST_SUCCESS if TX High Priority Buffer was not full and the given frame was written into the buffer;
  • XST_FIFO_NO_ROOM if there is no room in the TX High Priority Buffer for this frame.
Note:
If the frame needs to be sent immediately and not delayed by processor's interrupt handling, the caller should disable interrupt at processor level before invoking this function.

int XCanPs_SetBaudRatePrescaler (  XCanPs *  InstancePtr,
u8  Prescaler
) 
 

This routine sets Baud Rate Prescaler value. The system clock for the CAN controller is divided by (Prescaler + 1) to generate the quantum clock needed for sampling and synchronization. Read the device specification for details.

Baud Rate Prescaler can be set only if the CAN device is in Configuration Mode. Call XCanPs_EnterMode() to enter Configuration Mode before using this function.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Prescaler is the value to set. Valid values are from 0 to 255.
Returns:
  • XST_SUCCESS if the Baud Rate Prescaler value is set successfully.
  • XST_FAILURE if CAN device is not in Configuration Mode.
Note:
None.

int XCanPs_SetBitTiming (  XCanPs *  InstancePtr,
u8  SyncJumpWidth,
u8  TimeSegment2,
u8  TimeSegment1
) 
 

This routine sets Bit time. Time segment 1, Time segment 2 and Synchronization Jump Width are set in this function. Device specification requires the values passed into this function be one less than the actual values of these fields. Read the device specification for details.

Bit time can be set only if the CAN device is in Configuration Mode. Call XCanPs_EnterMode() to enter Configuration Mode before using this function.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
SyncJumpWidth is the Synchronization Jump Width value to set. Valid values are from 0 to 3.
TimeSegment2 is the Time Segment 2 value to set. Valid values are from 0 to 7.
TimeSegment1 is the Time Segment 1 value to set. Valid values are from 0 to 15.
Returns:
  • XST_SUCCESS if the Bit time is set successfully.
  • XST_FAILURE if CAN device is not in Configuration Mode.
Note:
None.

int XCanPs_SetRxIntrWatermark (  XCanPs *  InstancePtr,
u8  Threshold
) 
 

This routine sets the Rx Full threshold in the Watermark Interrupt Register.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Threshold is the threshold to be set. The valid values are from 1 to 63.
Returns:
  • XST_FAILURE - If the CAN device is not in Configuration Mode.
  • XST_SUCCESS - If the Rx Full threshold is set in Watermark Interrupt Register.
Note:
The threshold can only be set when the CAN device is in the configuration mode.

int XCanPs_SetTxIntrWatermark (  XCanPs *  InstancePtr,
u8  Threshold
) 
 

This routine sets the Tx Empty Threshold in the Watermark Interrupt Register.

Parameters:
InstancePtr is a pointer to the XCanPs instance.
Threshold is the threshold to be set. The valid values are from 1 to 63.
Returns:
  • XST_FAILURE - If the CAN device is not in Configuration Mode.
  • XST_SUCCESS - If the threshold is set in Watermark Interrupt Register.
Note:
The threshold can only be set when the CAN device is in the configuration mode.
Copyright @ 1995-2014 Xilinx, Inc. All rights reserved.