CAN.h

Go to the documentation of this file.

/*
 * Copyright (c) 2023-2024, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!*****************************************************************************
 *  @file       CAN.h
 *
 *  @brief      Controller Area Network (CAN) Driver Interface
 *
 *  @anchor ti_drivers_CAN_Overview
 *  # Overview
 *  The Controller Area Network (CAN) driver is a single instance driver
 *  that provides a simple interface to transmit and receive messages on a CAN bus.
 *  Messages are broadcast to the entire CAN network and each device is responsible
 *  for filtering and handling the received messages as necessary.
 *  The application is responsible for interpreting the received data.
 *
 *  # Power Management
 *  For devices with an integrated CAN controller, the CAN driver sets a power
 *  constraint when the driver is opened to prevent the device from entering
 *  standby when all tasks are blocked. This is required to allow the CAN
 *  controller and its clock source to remain powered to receive CAN messages
 *  from the external CAN transceiver. When the driver is closed, the power
 *  constraint is released. The application should close the CAN driver whenever
 *  the CAN transceiver enters sleep mode and re-open the CAN driver when the CAN
 *  transceiver wakes from sleep mode.
 *
 *  <hr>
 *  @anchor ti_drivers_CAN_Usage
 *  # Usage
 *
 *  To use the CAN driver to send and receive messages over the CAN bus, the
 *  application calls the following APIs:
 *    - CAN_open(): Open the CAN driver instance and configure the CAN
 *      controller, placing it in normal operational mode.
 *    - CAN_write(): Transmit a message using the Tx FIFO/Queue. This is the
 *      typical method of transmission.
 *    - CAN_writeBuffer(): Transmit a message using a dedicated Tx Buffer. This
 *      method of transmission requires a custom message RAM configuration and
 *      should only be used if there is an application-specific need that cannot
 *      be met by using the Tx FIFO/Queue.
 *    - CAN_read(): Receive a message. This should be called in a task context
 *      and triggered by the event callback when CAN_EVENT_RX_DATA_AVAIL occurs.
 *    - CAN_close(): Close the CAN driver instance and reset the CAN controller,
 *      placing it in standby operational mode.
 *
 *  @anchor ti_drivers_CAN_Synopsis
 *  ## Synopsis
 *  The following code example initializes the CAN driver with the default
 *  configuration, transmits a CAN FD message, and waits to read any received
 *  messages.
 *
 *  @code
 *  // Payload data size indexed by Data Length Code (DLC) field.
 *  static const uint32_t dlcToDataSize[16] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 16, 20, 24, 32, 48, 64};
 *
 *  // Rx semaphore.
 *  static SemaphoreP_Handle rxSemHandle;
 *
 *  void eventCallback(CAN_Handle handle, uint32_t event, uint32_t data, void *userArg)
 *  {
 *      if (event == CAN_EVENT_RX_DATA_AVAIL)
 *      {
 *          SemaphoreP_post(rxSemHandle);
 *      }
 *      // Handle more events here if enabled via the event mask...
 *  }
 *
 *  void thread(arg0, arg1)
 *  {
 *     int_fast16_t status;
 *     CAN_RxBufElement rxElem;
 *     CAN_TxBufElement txElem;
 *
 *     // Initialize driver(s).
 *     CAN_init();
 *
 *     // Create callback semaphore.
 *     SemaphoreP_Params semParams;
 *     SemaphoreP_Params_init(&semParams);
 *     semParams.mode    = SemaphoreP_Mode_BINARY;
 *     callbackSemHandle = SemaphoreP_create(0, &(semParams));
 *
 *     if (callbackSemHandle == NULL)
 *     {
 *         // SemaphoreP_create() failed.
 *         while (1) {}
 *     }
 *
 *     // Open CAN driver with default configuration.
 *     CAN_Params_init(&canParams);
 *     canParams.eventCbk  = eventCallback;
 *     // Setup event mask for events the application is interested in receiving
 *     // the callback for. Typically, only the CAN_EVENT_RX_DATA_AVAIL is required.
 *     canParams.eventMask = CAN_EVENT_RX_DATA_AVAIL;
 *
 *     canHandle = CAN_open(CONFIG_CAN_0, &canParams);
 *     if (canHandle == NULL)
 *     {
 *         // CAN_open() failed.
 *         while (1) {}
 *     }
 *
 *     // Setup Tx buffer element:
 *     //   CAN FD without Bit Rate Switching
 *     //   Extended Message ID = 0x12345678
 *     //   Data Length of 64-bytes
 *     //   Message marker = 5
 *     txElem.id  = 0x12345678U;
 *     txElem.rtr = 0U;
 *     txElem.xtd = 1U;
 *     txElem.esi = 0U;
 *     txElem.brs = 1U;
 *     txElem.dlc = CAN_DLC_64B;
 *     txElem.fdf = 1U;
 *     txElem.efc = 0U;
 *     txElem.mm  = 5U;
 *
 *     // Fill data payload with incrementing values.
 *     for (i = 0; i < dlcToDataSize[txElem.dlc]; i++)
 *     {
 *         txElem.data[i] = i;
 *     }
 *
 *     // Transmit message.
 *     CAN_write(canHandle, &txElem);
 *
 *     while (1)
 *     {
 *         // Wait for Rx data available event.
 *         SemaphoreP_pend(rxSemHandle, (uint32_t)SemaphoreP_WAIT_FOREVER);
 *
 *         // Read all available messages.
 *         while (CAN_read(canHandle, &rxElem) == CAN_STATUS_SUCCESS)
 *         {
 *             // Process received message.
 *         }
 *     }
 *  }
 *
 *  @endcode
 *
 *  More details on usage are provided in the following subsections.
 *
 *  @anchor ti_drivers_CAN_Examples
 *  ## Examples #
 *  * @ref ti_drivers_CAN_Synopsis "Usage Synopsis"
 *  * @ref ti_drivers_CAN_Example_initMsgRam "Initialize with custom message RAM configuration"
 *  * @ref ti_drivers_CAN_Example_initRawBitRate "Initialize with raw bit rate timing"
 *
 *  ## Initializing the CAN Driver
 *
 *  CAN_init() must be called before any other CAN APIs.  This function
 *  initializes common driver resources and calls the device-specific
 *  initialization function to configure the bit rate and message RAM.
 *
 *  ## Opening the CAN Driver
 *  After initializing the CAN driver by calling CAN_init(), the application
 *  can open a CAN instance by calling CAN_open().  This function
 *  takes an index into the @p CAN_config[] array, and a CAN parameters data
 *  structure. The CAN instance is specified by the index of the CAN in
 *  @p CAN_config[]. Calling CAN_open() a second time with the same index
 *  previously passed to CAN_open() will result in an error.  You can,
 *  though, re-use the index if the instance is closed via CAN_close().
 *
 *  If no #CAN_Params structure is passed to CAN_open(), default values are
 *  used. If the open call is successful, it returns a non-NULL value.
 *  The CAN driver APIs are non-blocking; there is no configurable return behavior.
 *
 *  @anchor ti_drivers_CAN_Example_initMsgRam
 *  Example initializing the CAN driver with a custom message RAM configuration
 *  to receive only filtered message IDs:
 *
 *  @note CAN driver SysConfig must be setup with 'Reject Non-Matching Messages' enabled.
 *
 *  @code
 *  #define STD_MSG_FILTER_NUM 2U
 *  #define EXT_MSG_FILTER_NUM 1U
 *
 *  static MCAN_StdMsgIDFilterElement stdMsgIDFilter[STD_MSG_FILTER_NUM] =
 *      {{.sfid1 = 0x555, .sfid2 = 0x444, .sfec = CAN_FEC_STORE_RXFIFO0, .sft = CAN_FILTER_DUAL_ID},
 *       {.sfid1 = 0x123, .sfid2 = 0U, .sfec = CAN_FEC_STORE_RXBUF, .sft = 0U}};
 *
 *  static MCAN_ExtMsgIDFilterElement extMsgIDFilter[EXT_MSG_FILTER_NUM] =
 *      {{.efid1 = 0x1234578, .efid2 = 0x1234600, .efec = CAN_FEC_STORE_RXFIFO1, .eft = CAN_FILTER_RANGE}};
 *
 *  const CAN_MsgRamConfig msgRamConfig = {
 *      .stdFilterNum       = STD_MSG_FILTER_NUM,
 *      .extFilterNum       = EXT_MSG_FILTER_NUM,
 *      .stdMsgIDFilterList = &stdMsgIDFilter[0],
 *      .extMsgIDFilterList = &extMsgIDFilter[0],
 *
 *      .rxFifoNum[0] = 10U,
 *      .rxFifoNum[1] = 2U,
 *      .rxBufNum     = 1U,
 *      .txBufNum     = 1U,
 *      .txFifoQNum   = 5U,
 *      .txFifoQMode  = 1U,
 *  };
 *
 *  int_fast16_t status;
 *
 *  // Initialize driver(s).
 *  CAN_init();
 *
 *  // Open CAN driver with custom message filters.
 *  CAN_Params_init(&canParams);
 *  canParams.msgRamConfig = &msgRamConfig;
 *  canParams.eventCbk  = eventCallback;
 *  // Setup event mask for events the application is interested in receiving
 *  // the callback for. Typically, only the CAN_EVENT_RX_DATA_AVAIL is required.
 *  canParams.eventMask = CAN_EVENT_RX_DATA_AVAIL;
 *
 *  canHandle = CAN_open(CONFIG_CAN_0, &canParams);
 *  if (canHandle == NULL)
 *  {
 *      // CAN_open() failed.
 *      while (1) {}
 *  }
 *  @endcode
 *
 *  @anchor ti_drivers_CAN_Example_initRawBitRate
 *  Example initializing the CAN driver with a specific raw bit rate timing:
 *  @note For this example, CAN driver SysConfig should be setup with 'CAN FD
 *  Operation' and 'Bit Rate Switching' enabled. The nominal and data bit rates
 *  selected in SysConfig will be ignored since raw bit rate timing parameters
 *  are provided to CAN_open().
 *
 *  @code
 *  const CAN_DataBitRateTimingRaw rawDataBitRateTiming = {
 *      // 1Mbps with 40MHz clk and 80% sample point ((40E6 / 2) / (15 + 4 + 1) = 1E6)
 *      // Add 1 to each programmed bit time to get functional value and +1 for for prop segment
 *      .dbrp            = 1U,
 *      .dtSeg1          = 14U,
 *      .dtSeg2          = 3U,
 *      .dsjw            = 3U,
 *      .tdcOffset       = 14U,
 *      .tdcFilterWinLen = 0U
 *  };
 *
 *  const CAN_BitRateTimingRaw rawBitTiming = {
 *      // 500kbps nominal with 40MHz clk and 87.5% sample point ((40E6 / 1) / (69 + 10 + 1) = 500E3)
 *      // Add 1 to each programmed bit time to get functional value and +1 for for prop segment
 *      .nbrp       = 0U,
 *      .ntSeg1     = 68U,
 *      .ntSeg2     = 9U,
 *      .nsjw       = 9U,
 *      .dataTiming = &rawDataBitRateTiming
 *  };
 *
 *  int_fast16_t status;
 *
 *  // Initialize driver(s).
 *  CAN_init();
 *
 *  // Open CAN with specific raw bit timing.
 *  CAN_Params_init(&canParams);
 *  canParams.bitTiming = &rawBitTiming;
 *  canParams.eventCbk  = eventCallback;
 *  // Setup event mask for events the application is interested in receiving
 *  // the callback for. Typically, only the CAN_EVENT_RX_DATA_AVAIL is required.
 *  canParams.eventMask = CAN_EVENT_RX_DATA_AVAIL;
 *
 *  canHandle = CAN_open(CONFIG_CAN_0, &canParams);
 *  if (canHandle == NULL)
 *  {
 *      // CAN_open() failed.
 *      while (1) {}
 *  }
 *  @endcode
 *
 *  ## CAN Message RAM Configuration
 *
 *  The default message RAM configuration is as follows:
 *  - No Rx filters.
 *  - Tx Queue (message with lowest ID in the queue will be transmitted first)
 *    with a fixed device-specific number of Tx buffers.
 *  - No Tx event FIFO.
 *  - Fixed device-specific number of Rx FIFO0 buffers.
 *  - No Rx FIFO1 buffers.
 *  - No dedicated Rx buffers.
 *
 *  The number of default Tx and Rx buffers varies depending on the size of the
 *  device's message RAM. Check the doxygen for the device-specific CAN
 *  implementation to find the message RAM size. If using a custom message RAM
 *  configuration, utilize the entire space by maximizing the number of Rx/Tx
 *  buffers for optimal performance.
 *
 *  ## CAN Write Behavior
 *  CAN_write() will return immediately after the message is loaded into the CAN
 *  controller's message RAM and pending transfer; it does not wait for the CAN
 *  message to be transmitted on the bus before returning. The CAN controller will
 *  automatically handle transmission retries in the event of a failure.
 *
 *  ## CAN Read Behavior
 *  When a message is received in Rx FIFO0/1 or a dedicated Rx buffer, the CAN
 *  driver's IRQ handler automatically reads the Rx buffer element from the CAN
 *  controller's message RAM and stores it in a ring buffer whose size is
 *  configurable in SysConfig. When CAN_read() is called, the Rx buffer element
 *  is copied from the ring buffer to the application. If the ring buffer becomes
 *  full, any new messages received will be lost until the application frees
 *  space in the ring buffer by calling CAN_read().
 *******************************************************************************
 */
#ifndef ti_drivers_can__include
#define ti_drivers_can__include

#include <stdint.h>
#include <stddef.h>

#include <ti/drivers/utils/StructRingBuf.h>
#include <ti/devices/DeviceFamily.h>

#include <third_party/mcan/MCAN.h>

#ifdef __cplusplus
extern "C" {
#endif

#define CAN_STATUS_SUCCESS ((int_fast16_t)0)

#define CAN_STATUS_ERROR ((int_fast16_t)-1)

#define CAN_STATUS_NOT_SUPPORTED ((int_fast16_t)-2)

#define CAN_STATUS_TX_BUF_FULL ((int_fast16_t)-3)

#define CAN_STATUS_NO_RX_MSG_AVAIL ((int_fast16_t)-4)

#define CAN_STATUS_NO_TX_EVENT_AVAIL ((int_fast16_t)-5)

#define CAN_EVENT_SPI_XFER_ERROR (0x800U)

#define CAN_EVENT_BIT_ERR_UNCORRECTED (0x400U)

#define CAN_EVENT_RX_RING_BUFFER_FULL (0x200U)

#define CAN_EVENT_RX_FIFO_MSG_LOST (0x100U)

#define CAN_EVENT_ERR_PASSIVE (0x80U)

#define CAN_EVENT_ERR_ACTIVE (0x40U)

#define CAN_EVENT_BUS_OFF (0x20U)

#define CAN_EVENT_BUS_ON (0x10U)

#define CAN_EVENT_TX_EVENT_LOST (0x08U)

#define CAN_EVENT_TX_EVENT_AVAIL (0x04U)

#define CAN_EVENT_TX_FINISHED (0x02U)

#define CAN_EVENT_RX_DATA_AVAIL (0x01U)

#define CAN_DLC_0B  ((uint32_t)0U)
#define CAN_DLC_1B  ((uint32_t)1U)
#define CAN_DLC_2B  ((uint32_t)2U)
#define CAN_DLC_3B  ((uint32_t)3U)
#define CAN_DLC_4B  ((uint32_t)4U)
#define CAN_DLC_5B  ((uint32_t)5U)
#define CAN_DLC_6B  ((uint32_t)6U)
#define CAN_DLC_7B  ((uint32_t)7U)
#define CAN_DLC_8B  ((uint32_t)8U)
#define CAN_DLC_12B ((uint32_t)9U)  
#define CAN_DLC_16B ((uint32_t)10U) 
#define CAN_DLC_20B ((uint32_t)11U) 
#define CAN_DLC_24B ((uint32_t)12U) 
#define CAN_DLC_32B ((uint32_t)13U) 
#define CAN_DLC_48B ((uint32_t)14U) 
#define CAN_DLC_64B ((uint32_t)15U) 
#define CAN_FEC_DISABLE_FILTER         ((uint32_t)0U)
#define CAN_FEC_STORE_RXFIFO0          ((uint32_t)1U)
#define CAN_FEC_STORE_RXFIFO1          ((uint32_t)2U)
#define CAN_FEC_REJECT_ID              ((uint32_t)3U)
#define CAN_FEC_SET_PRIO               ((uint32_t)4U)
#define CAN_FEC_SET_PRIO_STORE_RXFIFO0 ((uint32_t)5U)
#define CAN_FEC_SET_PRIO_STORE_RXFIFO1 ((uint32_t)6U)
#define CAN_FEC_STORE_RXBUF            ((uint32_t)7U)

#define CAN_FILTER_RANGE     ((uint32_t)0U)
#define CAN_FILTER_DUAL_ID   ((uint32_t)1U)
#define CAN_FILTER_WITH_MASK ((uint32_t)2U)
#define CAN_FILTER_DISABLE   ((uint32_t)3U)

typedef MCAN_RxBufElement CAN_RxBufElement;

typedef MCAN_TxBufElement CAN_TxBufElement;

typedef MCAN_TxEventFifoElement CAN_TxEventElement;

typedef MCAN_BitTimingParams CAN_BitTimingParams;

typedef struct CAN_Config_ *CAN_Handle;

typedef void (*CAN_EventCbk)(CAN_Handle handle, uint32_t event, uint32_t data, void *userArg);

typedef struct
{
    uint32_t stdFilterNum;
    uint32_t extFilterNum;
    MCAN_StdMsgIDFilterElement *stdMsgIDFilterList;
    MCAN_ExtMsgIDFilterElement *extMsgIDFilterList;
    /*
     * Note: All Rx and Tx buffer elements include a 64-byte payload if CAN FD
     *       is enabled. Otherwise, they include an 8-byte payload.
     */

    uint32_t rxFifoNum[2];
    uint32_t rxBufNum;
    uint32_t txBufNum;
    uint32_t txFifoQNum;
    uint32_t txFifoQMode;
    uint32_t txEventFifoNum;
} CAN_MsgRamConfig;

typedef struct
{
    uint32_t dbrp;
    uint32_t dtSeg1;
    uint32_t dtSeg2;
    uint32_t dsjw;
    uint32_t tdcOffset;
    uint32_t tdcFilterWinLen;
} CAN_DataBitRateTimingRaw;

typedef struct
{
    uint32_t nbrp;
    uint32_t ntSeg1;
    uint32_t ntSeg2;
    uint32_t nsjw;
    const CAN_DataBitRateTimingRaw *dataTiming;
} CAN_BitRateTimingRaw;

typedef struct
{
    const CAN_MsgRamConfig *msgRamConfig;  
    const CAN_BitRateTimingRaw *bitTiming; 
    uint32_t tsPrescaler;                  
    CAN_EventCbk eventCbk;                 
    uint32_t eventMask;                    
    void *userArg;                         
} CAN_Params;

typedef struct
{
    CAN_EventCbk eventCbk; 
    uint32_t eventMask;    
    void *userArg;         
    uint32_t intMask;      
    uint32_t txBufNum;       
    uint32_t txFifoQNum;     
    uint32_t txEventFifoNum; 
    uint32_t rxBufNum;       
    uint32_t rxFifoNum[2];   
    StructRingBuf_Object rxStructRingBuf; 
    StructRingBuf_Object txStructRingBuf; 
    bool isOpen;
} CAN_Object;

typedef struct
{
    bool enableCANFD;           
    bool enableBRS;             
    bool rejectNonMatchingMsgs; 
    uint32_t nominalBitRate;    
    uint32_t dataBitRate;       
    void *rxRingBufPtr;   
    void *txRingBufPtr;   
    size_t rxRingBufSize; 
    size_t txRingBufSize; 
#if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX)
    uint32_t intPriority; 
    uint32_t rxPinMux;    
    uint32_t txPinMux;    
    uint_least8_t rxPin;  
    uint_least8_t txPin;  
#endif
} CAN_HWAttrs;

typedef struct CAN_Config_
{
    CAN_Object *object;

    const CAN_HWAttrs *hwAttrs;
} CAN_Config;

extern const CAN_Config CAN_config[];
extern const uint_least8_t CAN_count;

void CAN_init(void);

void CAN_Params_init(CAN_Params *params);

CAN_Handle CAN_open(uint_least8_t index, CAN_Params *params);

void CAN_close(CAN_Handle handle);

int_fast16_t CAN_read(CAN_Handle handle, CAN_RxBufElement *elem);

int_fast16_t CAN_write(CAN_Handle handle, const CAN_TxBufElement *elem);

int_fast16_t CAN_writeBuffer(CAN_Handle handle, uint32_t bufIdx, const CAN_TxBufElement *elem);

int_fast16_t CAN_readTxEvent(CAN_Handle handle, CAN_TxEventElement *elem);

void CAN_getBitTiming(CAN_Handle handle, CAN_BitTimingParams *bitTiming, uint32_t *clkFreq);

int_fast16_t CAN_enableLoopbackExt(CAN_Handle handle);

int_fast16_t CAN_enableLoopbackInt(CAN_Handle handle);

int_fast16_t CAN_disableLoopback(CAN_Handle handle);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_can__include */