1 /******************************************************************************
3 * Copyright (C) 2010 - 2014 Xilinx, Inc. All rights reserved.
5 * Permission is hereby granted, free of charge, to any person obtaining a copy
6 * of this software and associated documentation files (the "Software"), to deal
7 * in the Software without restriction, including without limitation the rights
8 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 * copies of the Software, and to permit persons to whom the Software is
10 * furnished to do so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
15 * Use of the Software is limited solely to applications:
16 * (a) running on a Xilinx device, or
17 * (b) that interact with a Xilinx device through a bus or interconnect.
19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 * XILINX BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
23 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
24 * OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27 * Except as contained in this notice, the name of the Xilinx shall not be used
28 * in advertising or otherwise to promote the sale, use or other dealings in
29 * this Software without prior written authorization from Xilinx.
31 ******************************************************************************/
32 /*****************************************************************************/
36 * @addtogroup canps_v2_0
40 * The Xilinx CAN driver component. This component supports the Xilinx
43 * The CAN Controller supports the following features:
44 * - Confirms to the ISO 11898-1, CAN 2.0A and CAN 2.0B standards.
45 * - Supports both Standard (11 bit Identifier) and Extended (29 bit
47 * - Supports Bit Rates up to 1 Mbps.
48 * - Transmit message object FIFO with a user configurable depth of
49 * up to 64 message objects.
50 * - Transmit prioritization through one TX High Priority Buffer.
51 * - Receive message object FIFO with a user configurable depth of
52 * up to 64 message objects.
53 * - Watermark interrupts for Rx FIFO with configurable Watermark.
54 * - Acceptance filtering with 4 acceptance filters.
55 * - Sleep mode with automatic wake up.
56 * - Loop Back mode for diagnostic applications.
57 * - Snoop mode for diagnostic applications.
58 * - Maskable Error and Status Interrupts.
59 * - Readable Error Counters.
60 * - External PHY chip required.
61 * - Receive Timestamp.
63 * The device driver supports all the features listed above, if applicable.
65 * <b>Driver Description</b>
67 * The device driver enables higher layer software (e.g., an application) to
68 * communicate to the CAN. The driver handles transmission and reception of
69 * CAN frames, as well as configuration of the controller. The driver is simply a
70 * pass-through mechanism between a protocol stack and the CAN. A single device
71 * driver can support multiple CANs.
73 * Since the driver is a simple pass-through mechanism between a protocol stack
74 * and the CAN, no assembly or disassembly of CAN frames is done at the
75 * driver-level. This assumes that the protocol stack passes a correctly
76 * formatted CAN frame to the driver for transmission, and that the driver
77 * does not validate the contents of an incoming frame
79 * <b>Operation Modes</b>
81 * The CAN controller supports the following modes of operation:
82 * - <b>Configuration Mode</b>: In this mode the CAN timing parameters and
83 * Baud Rate Pre-scalar parameters can be changed. In this mode the CAN
84 * controller loses synchronization with the CAN bus and drives a
85 * constant recessive bit on the bus line. The Error Counter Register are
86 * reset. The CAN controller does not receive or transmit any messages
87 * even if there are pending transmit requests from the TX FIFO or the TX
88 * High Priority Buffer. The Storage FIFOs and the CAN configuration
89 * registers are still accessible.
90 * - <b>Normal Mode</b>:In Normal Mode the CAN controller participates in bus
91 * communication, by transmitting and receiving messages.
92 * - <b>Sleep Mode</b>: In Sleep Mode the CAN Controller does not transmit any
93 * messages. However, if any other node transmits a message, then the CAN
94 * Controller receives the transmitted message and exits from Sleep Mode.
95 * If there are new transmission requests from either the TX FIFO or the
96 * TX High Priority Buffer when the CAN Controller is in Sleep Mode, these
97 * requests are not serviced, and the CAN Controller continues to remain
98 * in Sleep Mode. Interrupts are generated when the CAN controller enters
99 * Sleep mode or Wakes up from Sleep mode.
100 * - <b>Loop Back Mode</b>: In Loop Back mode, the CAN controller transmits a
101 * recessive bit stream on to the CAN Bus. Any message that is transmitted
102 * is looped back to the
\91Rx
\92 line and acknowledged. The CAN controller
103 * thus receives any message that it transmits. It does not participate in
104 * normal bus communication and does not receive any messages that are
105 * transmitted by other CAN nodes. This mode is used for diagnostic
107 * - <b>Snoop Mode</b>: In Snoop mode, the CAN controller transmits a
108 * recessive bit stream on to the CAN Bus and does not participate
109 * in normal bus communication but receives messages that are transmitted
110 * by other CAN nodes. This mode is used for diagnostic purposes.
113 * <b>Buffer Alignment</b>
115 * It is important to note that frame buffers passed to the driver must be
118 * <b>Receive Address Filtering</b>
120 * The device can be set to accept frames whose Identifiers match any of the
121 * 4 filters set in the Acceptance Filter Mask/ID registers.
123 * The incoming Identifier is masked with the bits in the Acceptance Filter Mask
124 * Register. This value is compared with the result of masking the bits in the
125 * Acceptance Filter ID Register with the Acceptance Filter Mask Register. If
126 * both these values are equal, the message will be stored in the RX FIFO.
128 * Acceptance Filtering is performed by each of the defined acceptance filters.
129 * If the incoming identifier passes through any acceptance filter then the
130 * frame is stored in the RX FIFO.
132 * If the Accpetance Filters are not set up then all the received messages are
133 * stroed in the RX FIFO.
135 * <b>PHY Communication</b>
137 * This driver does not provide any mechanism for directly programming PHY.
141 * The driver has no dependencies on the interrupt controller. The driver
142 * provides an interrupt handler. User of this driver needs to provide
143 * callback functions. An interrupt handler example is available with
148 * This driver is not thread safe. Any needs for threads or thread mutual
149 * exclusion must be satisfied by the layer above this driver.
151 * <b>Device Reset</b>
153 * Bus Off interrupt that can occur in the device requires a device reset.
154 * The user is responsible for resetting the device and re-configuring it
155 * based on its needs (the driver does not save the current configuration).
156 * When integrating into an RTOS, these reset and re-configure obligations are
157 * taken care of by the OS adapter software if it exists for that RTOS.
159 * <b>Device Configuration</b>
161 * The device can be configured in various ways during the FPGA implementation
162 * process. Configuration parameters are stored in the xcanps_g.c files.
163 * A table is defined where each entry contains configuration information
164 * for a CAN device. This information includes such things as the base address
165 * of the memory-mapped device.
169 * Asserts are used within all Xilinx drivers to enforce constraints on argument
170 * values. Asserts can be turned off on a system-wide basis by defining, at
171 * compile time, the NDEBUG identifier. By default, asserts are turned on and it
172 * is recommended that users leave asserts on during development.
174 * <b>Building the driver</b>
176 * The XCanPs driver is composed of several source files. This allows the user
177 * to build and link only those parts of the driver that are necessary.
181 * MODIFICATION HISTORY:
183 * Ver Who Date Changes
184 * ----- ----- -------- -----------------------------------------------
185 * 1.00a xd/sv 01/12/10 First release
186 * 1.01a bss 12/27/11 Added the APIs XCanPs_SetTxIntrWatermark and
187 * XCanPs_GetTxIntrWatermark.
188 * Updated the Register/bit definitions
189 * Changed XCANPS_RXFWIR_RXFLL_MASK to XCANPS_WIR_FW_MASK
190 * Changed XCANPS_RXWIR_OFFSET to XCANPS_WIR_OFFSET
191 * Added XCANPS_IXR_TXFEMP_MASK for Tx Fifo Empty
192 * Changed XCANPS_IXR_RXFLL_MASK to
193 * XCANPS_IXR_RXFWMFLL_MASK
195 * XCANPS_TXBUF_ID_OFFSET to XCANPS_TXHPB_ID_OFFSET
196 * XCANPS_TXBUF_DLC_OFFSET to XCANPS_TXHPB_DLC_OFFSET
197 * XCANPS_TXBUF_DW1_OFFSET to XCANPS_TXHPB_DW1_OFFSET
198 * XCANPS_TXBUF_DW2_OFFSET to XCANPS_TXHPB_DW2_OFFSET
201 ******************************************************************************/
202 #ifndef XCANPS_H /* prevent circular inclusions */
203 #define XCANPS_H /* by using protection macros */
209 /***************************** Include Files *********************************/
212 #include "xcanps_hw.h"
214 /************************** Constant Definitions *****************************/
216 /** @name CAN operation modes
219 #define XCANPS_MODE_CONFIG 0x00000001 /**< Configuration mode */
220 #define XCANPS_MODE_NORMAL 0x00000002 /**< Normal mode */
221 #define XCANPS_MODE_LOOPBACK 0x00000004 /**< Loop Back mode */
222 #define XCANPS_MODE_SLEEP 0x00000008 /**< Sleep mode */
223 #define XCANPS_MODE_SNOOP 0x00000010 /**< Snoop mode */
226 /** @name Callback identifiers used as parameters to XCanPs_SetHandler()
229 #define XCANPS_HANDLER_SEND 1 /**< Handler type for frame sending interrupt */
230 #define XCANPS_HANDLER_RECV 2 /**< Handler type for frame reception interrupt*/
231 #define XCANPS_HANDLER_ERROR 3 /**< Handler type for error interrupt */
232 #define XCANPS_HANDLER_EVENT 4 /**< Handler type for all other interrupts */
235 /**************************** Type Definitions *******************************/
238 * This typedef contains configuration information for a device.
241 u16 DeviceId; /**< Unique ID of device */
242 u32 BaseAddr; /**< Register base address */
245 /******************************************************************************/
247 * Callback type for frame sending and reception interrupts.
249 * @param CallBackRef is a callback reference passed in by the upper layer
250 * when setting the callback functions, and passed back to the
251 * upper layer when the callback is invoked.
252 *******************************************************************************/
253 typedef void (*XCanPs_SendRecvHandler) (void *CallBackRef);
255 /******************************************************************************/
257 * Callback type for error interrupt.
259 * @param CallBackRef is a callback reference passed in by the upper layer
260 * when setting the callback functions, and passed back to the
261 * upper layer when the callback is invoked.
262 * @param ErrorMask is a bit mask indicating the cause of the error. Its
263 * value equals 'OR'ing one or more XCANPS_ESR_* values defined in
265 *******************************************************************************/
266 typedef void (*XCanPs_ErrorHandler) (void *CallBackRef, u32 ErrorMask);
268 /******************************************************************************/
270 * Callback type for all kinds of interrupts except sending frame interrupt,
271 * receiving frame interrupt, and error interrupt.
273 * @param CallBackRef is a callback reference passed in by the upper layer
274 * when setting the callback functions, and passed back to the
275 * upper layer when the callback is invoked.
276 * @param Mask is a bit mask indicating the pending interrupts. Its value
277 * equals 'OR'ing one or more XCANPS_IXR_* defined in xcanps_hw.h
278 *******************************************************************************/
279 typedef void (*XCanPs_EventHandler) (void *CallBackRef, u32 Mask);
282 * The XCanPs driver instance data. The user is required to allocate a
283 * variable of this type for every CAN device in the system. A pointer
284 * to a variable of this type is then passed to the driver API functions.
287 XCanPs_Config CanConfig; /**< Device configuration */
288 u32 IsReady; /**< Device is initialized and ready */
291 * Callback and callback reference for TXOK interrupt.
293 XCanPs_SendRecvHandler SendHandler;
297 * Callback and callback reference for RXOK/RXNEMP/RXFLL interrupts.
299 XCanPs_SendRecvHandler RecvHandler;
303 * Callback and callback reference for ERROR interrupt.
305 XCanPs_ErrorHandler ErrorHandler;
309 * Callback and callback reference for RXOFLW/RXUFLW/TXBFLL/TXFLL/
310 * Wakeup/Sleep/Bus off/ARBLST interrupts.
312 XCanPs_EventHandler EventHandler;
318 /***************** Macros (Inline Functions) Definitions *********************/
320 /****************************************************************************/
323 * This macro checks if the transmission is complete.
325 * @param InstancePtr is a pointer to the XCanPs instance.
328 * - TRUE if the transmission is done.
329 * - FALSE if the transmission is not done.
331 * @note C-Style signature:
332 * int XCanPs_IsTxDone(XCanPs *InstancePtr);
334 *******************************************************************************/
335 #define XCanPs_IsTxDone(InstancePtr) \
336 ((XCanPs_ReadReg(((InstancePtr)->CanConfig.BaseAddr), \
337 XCANPS_ISR_OFFSET) & XCANPS_IXR_TXOK_MASK) ? TRUE : FALSE)
340 /****************************************************************************/
343 * This macro checks if the transmission FIFO is full.
345 * @param InstancePtr is a pointer to the XCanPs instance.
348 * - TRUE if TX FIFO is full.
349 * - FALSE if the TX FIFO is NOT full.
351 * @note C-Style signature:
352 * int XCanPs_IsTxFifoFull(XCanPs *InstancePtr);
354 *****************************************************************************/
355 #define XCanPs_IsTxFifoFull(InstancePtr) \
356 ((XCanPs_ReadReg(((InstancePtr)->CanConfig.BaseAddr), \
357 XCANPS_SR_OFFSET) & XCANPS_SR_TXFLL_MASK) ? TRUE : FALSE)
360 /****************************************************************************/
363 * This macro checks if the Transmission High Priority Buffer is full.
365 * @param InstancePtr is a pointer to the XCanPs instance.
368 * - TRUE if the TX High Priority Buffer is full.
369 * - FALSE if the TX High Priority Buffer is NOT full.
371 * @note C-Style signature:
372 * int XCanPs_IsHighPriorityBufFull(XCanPs *InstancePtr);
374 *****************************************************************************/
375 #define XCanPs_IsHighPriorityBufFull(InstancePtr) \
376 ((XCanPs_ReadReg(((InstancePtr)->CanConfig.BaseAddr), \
377 XCANPS_SR_OFFSET) & XCANPS_SR_TXBFLL_MASK) ? TRUE : FALSE)
380 /****************************************************************************/
383 * This macro checks if the receive FIFO is empty.
385 * @param InstancePtr is a pointer to the XCanPs instance.
388 * - TRUE if RX FIFO is empty.
389 * - FALSE if the RX FIFO is NOT empty.
391 * @note C-Style signature:
392 * int XCanPs_IsRxEmpty(XCanPs *InstancePtr);
394 *****************************************************************************/
395 #define XCanPs_IsRxEmpty(InstancePtr) \
396 ((XCanPs_ReadReg(((InstancePtr)->CanConfig.BaseAddr), \
397 XCANPS_ISR_OFFSET) & XCANPS_IXR_RXNEMP_MASK) ? FALSE : TRUE)
400 /****************************************************************************/
403 * This macro checks if the CAN device is ready for the driver to change
404 * Acceptance Filter Identifier Registers (AFIR) and Acceptance Filter Mask
407 * AFIR and AFMR for a filter are changeable only after the filter is disabled
408 * and this routine returns FALSE. The filter can be disabled using the
409 * XCanPs_AcceptFilterDisable function.
411 * Use the XCanPs_Accept_* functions for configuring the acceptance filters.
413 * @param InstancePtr is a pointer to the XCanPs instance.
416 * - TRUE if the device is busy and NOT ready to accept writes to
418 * - FALSE if the device is ready to accept writes to AFIR and
421 * @note C-Style signature:
422 * int XCanPs_IsAcceptFilterBusy(XCanPs *InstancePtr);
424 *****************************************************************************/
425 #define XCanPs_IsAcceptFilterBusy(InstancePtr) \
426 ((XCanPs_ReadReg(((InstancePtr)->CanConfig.BaseAddr), \
427 XCANPS_SR_OFFSET) & XCANPS_SR_ACFBSY_MASK) ? TRUE : FALSE)
430 /****************************************************************************/
433 * This macro calculates CAN message identifier value given identifier field
436 * @param StandardId contains Standard Message ID value.
437 * @param SubRemoteTransReq contains Substitute Remote Transmission
439 * @param IdExtension contains Identifier Extension value.
440 * @param ExtendedId contains Extended Message ID value.
441 * @param RemoteTransReq contains Remote Transmission Request value.
443 * @return Message Identifier value.
445 * @note C-Style signature:
446 * u32 XCanPs_CreateIdValue(u32 StandardId,
447 * u32 SubRemoteTransReq,
448 * u32 IdExtension, u32 ExtendedId,
449 * u32 RemoteTransReq);
451 * Read the CAN specification for meaning of each parameter.
453 *****************************************************************************/
454 #define XCanPs_CreateIdValue(StandardId, SubRemoteTransReq, IdExtension, \
455 ExtendedId, RemoteTransReq) \
456 ((((StandardId) << XCANPS_IDR_ID1_SHIFT) & XCANPS_IDR_ID1_MASK) | \
457 (((SubRemoteTransReq) << XCANPS_IDR_SRR_SHIFT) & XCANPS_IDR_SRR_MASK)|\
458 (((IdExtension) << XCANPS_IDR_IDE_SHIFT) & XCANPS_IDR_IDE_MASK) | \
459 (((ExtendedId) << XCANPS_IDR_ID2_SHIFT) & XCANPS_IDR_ID2_MASK) | \
460 ((RemoteTransReq) & XCANPS_IDR_RTR_MASK))
463 /****************************************************************************/
466 * This macro calculates value for Data Length Code register given Data
469 * @param DataLengCode indicates Data Length Code value.
471 * @return Value that can be assigned to Data Length Code register.
473 * @note C-Style signature:
474 * u32 XCanPs_CreateDlcValue(u32 DataLengCode);
476 * Read the CAN specification for meaning of Data Length Code.
478 *****************************************************************************/
479 #define XCanPs_CreateDlcValue(DataLengCode) \
480 (((DataLengCode) << XCANPS_DLCR_DLC_SHIFT) & XCANPS_DLCR_DLC_MASK)
483 /****************************************************************************/
486 * This macro clears the timestamp in the Timestamp Control Register.
488 * @param InstancePtr is a pointer to the XCanPs instance.
492 * @note C-Style signature:
493 * void XCanPs_ClearTimestamp(XCanPs *InstancePtr);
495 *****************************************************************************/
496 #define XCanPs_ClearTimestamp(InstancePtr) \
497 XCanPs_WriteReg((InstancePtr)->CanConfig.BaseAddr, \
498 XCANPS_TCR_OFFSET, XCANPS_TCR_CTS_MASK)
500 /************************** Function Prototypes ******************************/
503 * Functions in xcanps.c
505 int XCanPs_CfgInitialize(XCanPs *InstancePtr, XCanPs_Config *ConfigPtr,
508 void XCanPs_Reset(XCanPs *InstancePtr);
509 u8 XCanPs_GetMode(XCanPs *InstancePtr);
510 void XCanPs_EnterMode(XCanPs *InstancePtr, u8 OperationMode);
511 u32 XCanPs_GetStatus(XCanPs *InstancePtr);
512 void XCanPs_GetBusErrorCounter(XCanPs *InstancePtr, u8 *RxErrorCount,
514 u32 XCanPs_GetBusErrorStatus(XCanPs *InstancePtr);
515 void XCanPs_ClearBusErrorStatus(XCanPs *InstancePtr, u32 Mask);
516 int XCanPs_Send(XCanPs *InstancePtr, u32 *FramePtr);
517 int XCanPs_Recv(XCanPs *InstancePtr, u32 *FramePtr);
518 int XCanPs_SendHighPriority(XCanPs *InstancePtr, u32 *FramePtr);
519 void XCanPs_AcceptFilterEnable(XCanPs *InstancePtr, u32 FilterIndexes);
520 void XCanPs_AcceptFilterDisable(XCanPs *InstancePtr, u32 FilterIndexes);
521 u32 XCanPs_AcceptFilterGetEnabled(XCanPs *InstancePtr);
522 int XCanPs_AcceptFilterSet(XCanPs *InstancePtr, u32 FilterIndex,
523 u32 MaskValue, u32 IdValue);
524 void XCanPs_AcceptFilterGet(XCanPs *InstancePtr, u32 FilterIndex,
525 u32 *MaskValue, u32 *IdValue);
527 int XCanPs_SetBaudRatePrescaler(XCanPs *InstancePtr, u8 Prescaler);
528 u8 XCanPs_GetBaudRatePrescaler(XCanPs *InstancePtr);
529 int XCanPs_SetBitTiming(XCanPs *InstancePtr, u8 SyncJumpWidth,
530 u8 TimeSegment2, u8 TimeSegment1);
531 void XCanPs_GetBitTiming(XCanPs *InstancePtr, u8 *SyncJumpWidth,
532 u8 *TimeSegment2, u8 *TimeSegment1);
534 int XCanPs_SetRxIntrWatermark(XCanPs *InstancePtr, u8 Threshold);
535 u8 XCanPs_GetRxIntrWatermark(XCanPs *InstancePtr);
538 * Diagnostic functions in xcanps_selftest.c
540 int XCanPs_SelfTest(XCanPs *InstancePtr);
543 * Functions in xcanps_intr.c
545 void XCanPs_IntrEnable(XCanPs *InstancePtr, u32 Mask);
546 void XCanPs_IntrDisable(XCanPs *InstancePtr, u32 Mask);
547 u32 XCanPs_IntrGetEnabled(XCanPs *InstancePtr);
548 u32 XCanPs_IntrGetStatus(XCanPs *InstancePtr);
549 void XCanPs_IntrClear(XCanPs *InstancePtr, u32 Mask);
550 void XCanPs_IntrHandler(void *InstancePtr);
551 int XCanPs_SetHandler(XCanPs *InstancePtr, u32 HandlerType,
552 void *CallBackFunc, void *CallBackRef);
555 * Functions in xcanps_sinit.c
557 XCanPs_Config *XCanPs_LookupConfig(u16 DeviceId);
563 #endif /* end of protection macro */