canps
Vitis Drivers API Documentation
canps Documentation

The Xilinx CAN driver component. This component supports the Xilinx CAN Controller.

The CAN Controller supports the following features:

  • Confirms to the ISO 11898-1, CAN 2.0A and CAN 2.0B standards.
  • Supports both Standard (11 bit Identifier) and Extended (29 bit Identifier) frames.
  • Supports Bit Rates up to 1 Mbps.
  • Transmit message object FIFO with a user configurable depth of up to 64 message objects.
  • Transmit prioritization through one TX High Priority Buffer.
  • Receive message object FIFO with a user configurable depth of up to 64 message objects.
  • Watermark interrupts for Rx FIFO with configurable Watermark.
  • Acceptance filtering with 4 acceptance filters.
  • Sleep mode with automatic wake up.
  • Loop Back mode for diagnostic applications.
  • Snoop mode for diagnostic applications.
  • Maskable Error and Status Interrupts.
  • Readable Error Counters.
  • External PHY chip required.
  • Receive Timestamp.

The device driver supports all the features listed above, if applicable.

Driver Description

The device driver enables higher layer software (e.g., an application) to communicate to the CAN. The driver handles transmission and reception of CAN frames, as well as configuration of the controller. The driver is simply a pass-through mechanism between a protocol stack and the CAN. A single device driver can support multiple CANs.

Since the driver is a simple pass-through mechanism between a protocol stack and the CAN, no assembly or disassembly of CAN frames is done at the driver-level. This assumes that the protocol stack passes a correctly formatted CAN frame to the driver for transmission, and that the driver does not validate the contents of an incoming frame

Operation Modes

The CAN controller supports the following modes of operation:

  • Configuration Mode: In this mode the CAN timing parameters and Baud Rate Pre-scalar parameters can be changed. In this mode the CAN controller loses synchronization with the CAN bus and drives a constant recessive bit on the bus line. The Error Counter Register are reset. The CAN controller does not receive or transmit any messages even if there are pending transmit requests from the TX FIFO or the TX High Priority Buffer. The Storage FIFOs and the CAN configuration registers are still accessible.
  • Normal Mode:In Normal Mode the CAN controller participates in bus communication, by transmitting and receiving messages.
  • Sleep Mode: In Sleep Mode the CAN Controller does not transmit any messages. However, if any other node transmits a message, then the CAN Controller receives the transmitted message and exits from Sleep Mode. If there are new transmission requests from either the TX FIFO or the TX High Priority Buffer when the CAN Controller is in Sleep Mode, these requests are not serviced, and the CAN Controller continues to remain in Sleep Mode. Interrupts are generated when the CAN controller enters Sleep mode or Wakes up from Sleep mode.
  • Loop Back Mode: In Loop Back mode, the CAN controller transmits a recessive bit stream on to the CAN Bus. Any message that is transmitted is looped back to the �Rx� line and acknowledged. The CAN controller thus receives any message that it transmits. It does not participate in normal bus communication and does not receive any messages that are transmitted by other CAN nodes. This mode is used for diagnostic purposes.
  • Snoop Mode: In Snoop mode, the CAN controller transmits a recessive bit stream on to the CAN Bus and does not participate in normal bus communication but receives messages that are transmitted by other CAN nodes. This mode is used for diagnostic purposes.

Buffer Alignment

It is important to note that frame buffers passed to the driver must be 32-bit aligned.

Receive Address Filtering

The device can be set to accept frames whose Identifiers match any of the 4 filters set in the Acceptance Filter Mask/ID registers.

The incoming Identifier is masked with the bits in the Acceptance Filter Mask Register. This value is compared with the result of masking the bits in the Acceptance Filter ID Register with the Acceptance Filter Mask Register. If both these values are equal, the message will be stored in the RX FIFO.

Acceptance Filtering is performed by each of the defined acceptance filters. If the incoming identifier passes through any acceptance filter then the frame is stored in the RX FIFO.

If the Accpetance Filters are not set up then all the received messages are stroed in the RX FIFO.

PHY Communication

This driver does not provide any mechanism for directly programming PHY.

Interrupts

The driver has no dependencies on the interrupt controller. The driver provides an interrupt handler. User of this driver needs to provide callback functions. An interrupt handler example is available with the driver.

Threads

This driver is not thread safe. Any needs for threads or thread mutual exclusion must be satisfied by the layer above this driver.

Device Reset

Bus Off interrupt that can occur in the device requires a device reset. The user is responsible for resetting the device and re-configuring it based on its needs (the driver does not save the current configuration). When integrating into an RTOS, these reset and re-configure obligations are taken care of by the OS adapter software if it exists for that RTOS.

Device Configuration

The device can be configured in various ways during the FPGA implementation process. Configuration parameters are stored in the xcanps_g.c files. A table is defined where each entry contains configuration information for a CAN device. This information includes such things as the base address of the memory-mapped device.

Asserts

Asserts are used within all Xilinx drivers to enforce constraints on argument values. Asserts can be turned off on a system-wide basis by defining, at compile time, the NDEBUG identifier. By default, asserts are turned on and it is recommended that users leave asserts on during development.

Building the driver

The XCanPs driver is composed of several source files. This allows the user to build and link only those parts of the driver that are necessary. 

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.
                Updated the Register/bit definitions
                      Changed XCANPS_RXFWIR_RXFLL_MASK to XCANPS_WIR_FW_MASK
                      Changed XCANPS_RXWIR_OFFSET to XCANPS_WIR_OFFSET
                Added XCANPS_IXR_TXFEMP_MASK for Tx Fifo Empty
                Changed XCANPS_IXR_RXFLL_MASK to
                XCANPS_IXR_RXFWMFLL_MASK
                        Changed
                XCANPS_TXBUF_ID_OFFSET to XCANPS_TXHPB_ID_OFFSET
                        XCANPS_TXBUF_DLC_OFFSET to XCANPS_TXHPB_DLC_OFFSET
                XCANPS_TXBUF_DW1_OFFSET to XCANPS_TXHPB_DW1_OFFSET
                XCANPS_TXBUF_DW2_OFFSET to XCANPS_TXHPB_DW2_OFFSET
2.1 adk                 23/08/14 Fixed CR:798792 Peripheral test for CANPS IP in
                SDK claims a 40kbps baud rate but it's not.
3.0 adk     09/12/14  Added support for Zynq Ultrascale Mp.Also code
                modified for MISRA-C:2012 compliance.
3.1 adk     10/11/15  Fixed CR#911958 Add support for Tx Watermark example.
                Data mismatch while sending data less than 8 bytes.
3.1 nsk     12/21/15  Updated XCanPs_IntrHandler in xcanps_intr.c to handle
                error interrupts correctly. CR#925615
    ms      03/17/17  Added readme.txt file in examples folder for doxygen
                      generation.
3.3 sne     08/06/19    Fixed coverity warnings.
3.5 sne     06/29/20  Fixed MISRA-C violations.
3.5 sne     06/29/20  Fix multiple packets send issue CR-1066438.
3.5 sne     08/28/20  Modify Makefile to support parallel make execution.
3.7 ht      06/28/23  Added support for system device-tree flow.