CAN.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018, 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      <b>PRELIMINARY</b> CAN driver interface
 *
 *  <b>WARNING</b> These APIs are <b>PRELIMINARY</b>, and subject to
 *  change in the next few months.
 *
 *  To use the CAN driver, ensure that the correct driver library for your
 *  device is linked in and include this header file as follows:
 *  @code
 *  #include <ti/drivers/CAN.h>
 *  @endcode
 *
 *  This module serves as the main interface for applications.  Its purpose
 *  is to redirect the CAN APIs to specific driver implementations
 *  which are specified using a pointer to a #CAN_FxnTable.
 *
 *  # Overview #
 *  The Controller Area Network (CAN) driver is a generic driver that allows
 *  for communication on a CAN bus. It is a two-wire, half-duplex, LAN system
 *  that is collision free. The main method of transfer is by broadcasting.
 *  The CAN protocol defines the format of data transfer, and this CAN driver
 *  allows full functionality as a transmitting and receiving node on a bus.
 *  However, there can be higher-level software layers and stacks that use this
 *  driver to enable more advanced features.
 *  Functional modes available in this driver include blocking and non-blocking.
 *
 *  The APIs in this driver serve as an interface to a typical RTOS
 *  application. The specific peripheral implementations are responsible for
 *  creating all the RTOS specific primitives to allow for thread-safe
 *  operation.
 *
 *  # Usage #
 *
 *  The CAN driver interface provides device independent APIs, data types,
 *  and macros.  The following code example opens a CAN instance, creates
 *  an incrementing CAN frame, and continually writes them to the CAN bus.
 *  NOTE: a CAN receiver on this bus is needed, or else this transmitter will
 *  continually throw an error if it does not detect an ACK.
 *
 *  @code
 *    uint8_t i;
 *    // Initialize the CAN driver
 *    CAN_init();
 *
 *    CAN_Handle canHandle;
 *    CAN_Params canParams;
 *    CAN_Params_init(&canParams);
 *    canHandle = CAN_open(Board_CAN0, &canParams);
 *
 *    if (canHandle == NULL) {
 *        // CAN_open() failed
 *        while (1);
 *    }
 *
 *    for (i = 0; ; ++i) {
 *        CAN_Frame canFrame[1];
 *        canFrame[0].can_id = i;
 *        canFrame[0].err = 0;
 *        canFrame[0].rtr = 0;
 *        canFrame[0].eff = 1;
 *        canFrame[0].dlc = i % 9;
 *        canFrame[0].data[0] = i;
 *        canFrame[0].data[1] = i + 1;
 *        canFrame[0].data[2] = i + 2;
 *        canFrame[0].data[3] = i + 3;
 *        canFrame[0].data[4] = i + 4;
 *        canFrame[0].data[5] = i + 5;
 *        canFrame[0].data[6] = i + 6;
 *        canFrame[0].data[7] = i + 7;
 *
 *        CAN_write(canHandle, canFrame, sizeof(canFrame));
 *    }
 *  @endcode
 *
 *  Details for the example code above are described in the following
 *  subsections.
 *
 *
 *  ### CAN Driver Configuration #
 *
 *  In order to use the CAN APIs, the application is required
 *  to provide device-specific CAN configuration in the Board.c file.
 *  The CAN driver interface defines a configuration data structure:
 *
 *  @code
 *  typedef struct CAN_Config_ {
 *      CAN_FxnTable  const    *fxnTablePtr;
 *      void                   *object;
 *      void          const    *hwAttrs;
 *      CAN_Frame              *rxBufPtr;
 *      CAN_frame              *txBufPtr;
 *      size_t                  rxBufSize;
 *      size_t                  txBufSize;
 *  } CAN_Config;
 *  @endcode
 *
 *  You will need to check the device-specific CAN driver implementation's
 *  header file for example configuration.  Please also refer to the
 *  Board.c file of any of your examples to see the CAN configuration.
 *
 *  ### Initializing the CAN Driver #
 *
 *  CAN_init() must be called before any other CAN APIs.  This function
 *  calls the device implementation's CAN initialization function, for each
 *  element of CAN_config[].
 *
 *  ### Opening the CAN Driver #
 *
 *  Opening a CAN requires four steps:
 *  1.  Create and initialize a CAN_Params structure.
 *  2.  Fill in the desired parameters.
 *  3.  Call CAN_open(), passing the index of the CAN in the CAN_config
 *      structure, and the address of the CAN_Params structure.  The
 *      CAN instance is specified by the index in the CAN_config structure.
 *  4.  Check that the CAN handle returned by CAN_open() is non-NULL,
 *      and save it.  The handle will be used to read and write to the
 *      CAN you just opened.
 *
 *  Only one CAN index can be used at a time; 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().
 *  In the example code, Board_CAN0 is passed to CAN_open().  This macro
 *  is defined in the example's Board.h file.
 *
 *
 *  ### Modes of Operation #
 *
 *  The CAN driver can operate in blocking mode or nonblocking mode, by
 *  setting the mode parameters passed to CAN_open().
 *  If these parameters are not set, as in the example code, the CAN
 *  driver defaults to blocking mode.  Options for the mode parameter are
 *  #CAN_MODE_BLOCKING and #CAN_MODE_NONBLOCKING:
 *
 *  - #CAN_MODE_BLOCKING uses a semaphore to block while data is being sent
 *    or read. The context of calling CAN_read() or CAN_write() must be a Task
 *    when using #CAN_MODE_BLOCKING. The CAN_write() or CAN_read() call
 *    will block until all data is sent or received, or the write timeout or
 *    read timeout expires, whichever happens first.
 *
 *  - #CAN_MODE_NONBLOCKING is non-blocking and CAN_read() and CAN_write()
 *    will return either with the number of bytes successfully read/written,
 *    or a negative error number.
 *
 *  ### Reading and Writing data #
 *
 *  The example code reads one CAN frame from the CAN instance, and then writes
 *  one CAN frame back to the same instance:
 *
 *  @code
 *  CAN_read(can, &canFrame, sizeof(canFrame));
 *  CAN_write(can, &canFrame, sizeof(canFrame));
 *  @endcode
 *
 *  The CAN driver allows CAN_read() and CAN_write() calls to happen for any
 *  node at any time from the CAN bus. Please see the CAN protocol for how it
 *  handles collisions. The ability to filter incoming messages are also
 *  available through CAN_Params.
 *
 *  # Implementation #
 *
 *  The CAN driver interface module is joined (at link time) to an
 *  array of CAN_Config data structures named *CAN_config*.
 *  CAN_config is implemented in the application with each entry being an
 *  instance of a CAN peripheral. Each entry in *CAN_config* contains a:
 *  - (CAN_FxnTable *) to a set of functions that implement a CAN peripheral
 *  - (void *) data object that is associated with the CAN_FxnTable
 *  - (void *) hardware attributes that are associated with the CAN_FxnTable
 *
 *  The CAN APIs are redirected to the device specific implementations
 *  using the CAN_FxnTable pointer of the CAN_config entry.
 *  In order to use device specific functions of the CAN driver directly,
 *  link in the correct driver library for your device and include the
 *  device specific CAN driver header file (which in turn includes CAN.h).
 *  For example, for the MSP432 family of devices, you would include the
 *  following header file:
 *    @code
 *    #include <ti/drivers/can/CANMSP432.h>
 *    @endcode
 *
 *  ============================================================================
 */

#ifndef ti_drivers_CAN__include
#define ti_drivers_CAN__include

#ifdef __cplusplus
extern "C" {
#endif

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

#include <ti/drivers/can/types.h>

#define CAN_CMD_RESERVED           (32)

#define CAN_STATUS_RESERVED        (-32)

#define CAN_STATUS_SUCCESS         (0)

#define CAN_STATUS_ERROR           (-1)

#define CAN_STATUS_UNDEFINEDCMD    (-2)

#define  CAN_WAIT_FOREVER           (~(0U))

typedef struct CAN_Config_    *CAN_Handle;

typedef enum CAN_Mode_ {
    CAN_MODE_BLOCKING,
    CAN_MODE_NONBLOCKING
} CAN_Mode;

typedef enum CAN_Direction_ {
    CAN_DIRECTION_READ        = 0x1,
    CAN_DIRECTION_WRITE       = 0x2,
    CAN_DIRECTION_READWRITE   = 0x3,
} CAN_Direction;

typedef struct CAN_Params_ {
    CAN_Mode  mode;         
    CAN_Direction  direction; 
    uint32_t  filterID;     
    uint32_t  filterMask;   
    uint32_t  readTimeout;  
    uint32_t  writeTimeout; 
} CAN_Params;

typedef struct can_frame CAN_Frame;

typedef void (*CAN_CloseFxn) (CAN_Handle handle);

typedef int_fast16_t (*CAN_ControlFxn) (CAN_Handle handle, uint_fast16_t cmd, void *arg);

typedef void (*CAN_InitFxn) (CAN_Handle handle);

typedef CAN_Handle (*CAN_OpenFxn) (CAN_Handle handle, CAN_Params *params);

typedef int_fast32_t (*CAN_ReadFxn) (CAN_Handle handle, void *buffer,
    size_t size);

typedef int_fast32_t (*CAN_WriteFxn) (CAN_Handle handle, const void *buffer,
    size_t size);

typedef void (*CAN_TxMsgFxn) (CAN_Handle handle);

typedef struct CAN_FxnTable_ {
    CAN_CloseFxn        closeFxn;

    CAN_ControlFxn      controlFxn;

    CAN_InitFxn         initFxn;

    CAN_OpenFxn         openFxn;

    CAN_ReadFxn         readFxn;

    CAN_WriteFxn        writeFxn;

    CAN_TxMsgFxn        txMsgFxn;
} CAN_FxnTable;

typedef struct CAN_Config_ {
    CAN_FxnTable   const *fxnTablePtr;

    void                 *object;

    void           const *hwAttrs;

    CAN_Frame            *rxBufPtr;

    CAN_Frame            *txBufPtr;

    size_t                rxBufSize;

    size_t                txBufSize;
} CAN_Config;

extern void CAN_close(CAN_Handle handle);

extern void CAN_init(void);

extern int_fast16_t CAN_control(CAN_Handle handle, uint_fast16_t cmd, void *arg);

extern CAN_Handle CAN_open(uint_least8_t index, CAN_Params *params);

extern void CAN_Params_init(CAN_Params *params);

extern int_fast32_t CAN_write(CAN_Handle handle, const void *buffer, size_t size);

extern int_fast32_t CAN_read(CAN_Handle handle, void *buffer, size_t size);

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_CAN__include */