can.h

Go to the documentation of this file.

#ifndef DRIVER_CAN_H
#define DRIVER_CAN_H
/**********************************************************************/
/*
 * Copyright (c) 2015-2016, Jetro AS
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. 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.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONRIBUTORS ``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 AUTHOR 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.
 *
 * This file is part of the EVE platform.
 */

/**
 * \file
 * \brief Driver for CAN MCP2562x in EVE.
 *
 * \author SE, Jetro AS
 */ /******************************************************************/

#include <dev/spi.h>

/**
 * \defgroup MCP2562x MCP2562x CAN chip driver
 * \ingroup extdrv
 * This CAN driver supports MCP2562x CAN chip connected with EVE SPI driver.
 *
 * Public functionality included:
 * - Init, HW and SW reset, full range of MCP2562x operation modes selection.
 * - Preconfigured setup of GPIO assignments, available interrupts and chip behavior.
 * - Run-time setup of desired CAN bus speed and address filtering.
 * - Transmission and reception of full CAN frames.
 *
 * \{
 */

/******************************************************************************
 *  CAN driver public constants
 *****************************************************************************/

/**
 * @name MCP2562x "Read Status" command result bit masks
 * @{
 */
#define STAT_RX0IF  (1 << 0) //!< Rx0 buffer interrupt flag (Rx0 is ready to be read)
#define STAT_RX1IF  (1 << 1) //!< Rx1 buffer interrupt flag (Rx1 is ready to be read)
#define STAT_TX0REQ (1 << 2) //!< Tx0 RTS flag (Tx0 is pending)
#define STAT_TX0IF  (1 << 3) //!< Tx0 buffer interrupt flag (Tx0 being sent)
#define STAT_TX1REQ (1 << 4) //!< Tx1 RTS flag (Tx1 is pending)
#define STAT_TX1IF  (1 << 5) //!< Tx1 buffer interrupt flag (Tx1 being sent)
#define STAT_TX2REQ (1 << 6) //!< Tx2 RTS flag (Tx2 is pending)
#define STAT_TX2IF  (1 << 7) //!< Tx2 buffer interrupt flag (Tx2 being sent)
/** @} */

/**
 * @name MCP2562x TXBnCTRL register (Transmit Buffer [n] Control) bit masks
 * @{
 */
#define TXB_TXP_MASK (3 << 0) //!< Transmit Buffer Priority mask
#define TXB_TXP0     (1 << 0) //!< Transmit Buffer Priority low bit
#define TXB_TXP1     (1 << 1) //!< Transmit Buffer Priority high bit
#define TXB_TXREQ    (1 << 3) //!< Message Transmit Request
#define TXB_TXERR    (1 << 4) //!< Transmission Error Detected
#define TXB_MLOA     (1 << 5) //!< Message Lost Arbitration
#define TXB_ABTF     (1 << 6) //!< Message Aborted Flag
/** @} */

/**
 * @name MCP2562x interrupt bit masks
 * @{
 */
#define INT_RX0IF (1 << 0)  //!< Rx0 Full Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
#define INT_RX1IF (1 << 1)  //!< Rx1 Full Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
#define INT_TX0IF (1 << 2)  //!< Tx0 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
#define INT_TX1IF (1 << 3)  //!< Tx1 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
#define INT_TX2IF (1 << 4)  //!< Tx2 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
#define INT_ERRIF (1 << 5)  //!< Error Interrupt Flag bit (multiple sources in the EFLG register) - must be cleared by MCU to reset interrupt condition
#define INT_WAKIF (1 << 6)  //!< Wake-up Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
#define INT_MERRF (1 << 7)  //!< Message Error Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
/** @} */


/******************************************************************************
 *  CAN driver public types
 *****************************************************************************/

/**
 * @brief defines possible MCP2562x modes of operation for CanSetMode() function.\n
 * NB: values correspond to REQOP bits in CANCTRL register (except CAN_MODE_RESET and CAN_MODE_SPI_BUSY)
 */
enum can_mode_t
{
  CAN_MODE_NORMAL     = 0x00,  //!< Switch to normal operational mode
  CAN_MODE_SLEEP      = 0x01,  //!< Switch to sleep mode
  CAN_MODE_LOOPBACK   = 0x02,  //!< Switch to loopback mode
  CAN_MODE_LISTENONLY = 0x03,  //!< Switch to listen-only mode
  CAN_MODE_CONFIGURE  = 0x04,  //!< Switch to configuration mode
  CAN_MODE_RESET      = 0x0F,  //!< Perform SW reset; after that MCP is in configuration mode
  CAN_MODE_SPI_BUSY   = 0xFF   //!< SPI failed to communicate with MCP
};

/**
 * @brief defines MCP2562x TX/RX buffers for data transmission/reception.
 */
enum can_xbuffer_t
{
  CAN_TX0 = 0,  //!< Write data to / get status of TX0
  CAN_TX1,      //!< Write data to / get status of TX1
  CAN_TX2,      //!< Write data to / get status of TX2
  CAN_RX0,      //!< Read data from / get status of RX0
  CAN_RX1,      //!< Read data from / get status of RX1
  CAN_FIFO      //!< Write data to the first available TX / Read data from the RX which came first
};

/**
 * @brief defines MCP2562x Rx filter Ids and Masks.
 */
enum can_filter_t
{
  CAN_RXF0 = 0,  //!< Identifier of filter #0 for RX0
  CAN_RXF1,      //!< Identifier of filter #1 for RX0
  CAN_RXF2,      //!< Identifier of filter #0 for RX1
  CAN_RXF3,      //!< Identifier of filter #1 for RX1
  CAN_RXF4,      //!< Identifier of filter #2 for RX1
  CAN_RXF5,      //!< Identifier of filter #3 for RX1
  CAN_RXM0,      //!< Mask of filter for RX0
  CAN_RXM1       //!< Mask of filter for RX1
};

/**
 * @brief defines possible outgoing CAN frame priorities as in MCP2562x TXBnCTRL register.
 */
enum can_priority_t
{
  CAN_PRIORITY_LOW     = 0,
  CAN_PRIORITY_MEDIUM  = 1,
  CAN_PRIORITY_HIGH    = 2,
  CAN_PRIORITY_HIGHEST = 3
};

struct can_t;

/**
 * @brief The callback is called on CAN frame reception
 * @param Can       CAN driver descriptor
 * @param BufNum    Buffer with received data (Rx0/Rx1)
 */
typedef void
  (*can_rx_callback_t)(const struct can_t* Can, enum can_xbuffer_t BufNum);

/**
 * @brief The callback is called at CAN transmission ready and transmission error
 * @param Can       CAN driver descriptor
 * @param BufNum    Buffer transmitted (Tx0/Tx1/Tx2)
 * @param TXBnCTRL  MCP2562x Transmit buffer control register
 *                  Masks:
 *                  TXB_TXP0  - Transmit Buffer Priority low bit
 *                  TXB_TXP1  - Transmit Buffer Priority high bit
 *                  TXB_TXREQ - Message Transmit Request
 *                  TXB_TXERR - Transmission Error Detected
 *                  TXB_MLOA  - Message Lost Arbitration
 *                  TXB_ABTF  - Message Aborted Flag
 */
typedef void (*can_tx_callback_t)(const struct can_t* Can,
                                  enum can_xbuffer_t BufNum,
                                  uint8_t TXBnCTRL);

/**
 * @brief The callback is called at CAN chip wakeup
 * @param Can       CAN driver descriptor
 */
typedef void (*can_wake_callback_t)(const struct can_t* Can);

/**
 * @brief The callback is called at CAN chip error
 * @param Can       CAN handling structure
 * @param EREG      MCP2562x EREG register
 */
typedef void (*can_err_callback_t)(const struct can_t* Can, uint8_t EREG);

/**
 * @brief CAN driver descriptor: static structure for configuration of driver instance.
 */
struct can_t
{
  const struct spi_t* Spi;       //!< Pointer to the SPI interface instance
  const struct spi_cs_t SpiCs;   //!< SPI CS settings
  uint32_t SpiBaudrate;          //!< SPI speed
  struct can_state_t* State;     //!< Pointer to the CAN state
  uint8_t PinReset;              //!< Pin number for MCP2562x HW RESET
  union {
    struct {
      uint8_t CanCfgCLKPRE :2;  //!< CLKOUT Pin Prescaler bits
      uint8_t CanCfgCLKEN  :1;  //!< 1 : CLKOUT pin is enabled
      uint8_t CanCfgOSM    :1;  //!< 1 : one-shot mode is on
      uint8_t CANCTRLx     :4;  //!< Not used in configuration
    };
    uint8_t CanCfgCANCTRL; //!< CANCTRL register content
  };
  union {
    struct {
      uint8_t CanCfgRX0IE :1;  //!< Rx0 Full Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
      uint8_t CanCfgRX1IE :1;  //!< Rx1 Full Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
      uint8_t CanCfgTX0IE :1;  //!< Tx0 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
      uint8_t CanCfgTX1IE :1;  //!< Tx1 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
      uint8_t CanCfgTX2IE :1;  //!< Tx2 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
      uint8_t CanCfgERRIE :1;  //!< Error Interrupt Flag bit (multiple sources in the EFLG register) - must be cleared by MCU to reset interrupt condition
      uint8_t CanCfgWAKIE :1;  //!< Wake-up Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
      uint8_t CanCfgMERRE :1;  //!< Message Error Interrupt Flag bit - must be cleared by MCU to reset interrupt condition
    };
    uint8_t CanCfgCANINTE; //!< CANINTE register content
  };
  union {
    struct {
      uint8_t CanCfgB0BFM  :1;  //!< RX0BF Pin Operation mode bit: 1 = Rx0 interrupt, 0 = Digital Output mode
      uint8_t CanCfgB1BFM  :1;  //!< RX1BF Pin Operation mode bit: 1 = Rx1 interrupt, 0 = Digital Output mode
      uint8_t CanCfgB0BFE  :1;  //!< RX0BF Pin Function Enable bit: 1 = Pin function enabled, operation mode determined by B0BFM bit
      uint8_t CanCfgB1BFE  :1;  //!< RX1BF Pin Function Enable bit: 1 = Pin function enabled, operation mode determined by B1BFM bit
      uint8_t BFPCTRLx     :4;  //!< Not used in configuration
    };
    uint8_t CanCfgBFPCTRL;
  };
  union {
    struct {
      uint8_t CanCfgB0RTSM :1; //!< TX0RTS Pin mode bit: 1 = RTS of Tx0 on falling edge, 0 = Digital input
      uint8_t CanCfgB1RTSM :1; //!< TX1RTS Pin mode bit: 1 = RTS of Tx1 on falling edge, 0 = Digital input
      uint8_t CanCfgB2RTSM :1; //!< TX2RTS Pin mode bit: 1 = RTS of Tx2 on falling edge, 0 = Digital input
      uint8_t TXRTSCTRLx   :5; //!< Not used in configuration
    };
    uint8_t CanCfgTXRTSCTRL;
  };
  union {
    struct {
      uint8_t CNF3x        :6; //!< Not used in configuration
      uint8_t CanCfgWAKFIL :1; //!< 1 : Wake-up filter enabled
      uint8_t CanCfgSOF    :1; //!< Start-of-Frame Signal bit (!!!only if CLKOUT pin is enabled!!!)
    };
    uint8_t CanCfgCNF3;
  };
  union {
    struct {
      uint8_t RXB0CTRLx1   :6; //!< Not used in configuration
      uint8_t CanCfgBUKT   :1; //!< Rollover Enable bit: 1 = Rx0 message will rollover to Rx1 if Rx0 is full
      uint8_t RXB0CTRLx2   :2; //!< Not used in configuration
    };
    uint8_t CanCfgRXB0CTRL;
  };

  can_rx_callback_t CanRxReadyCb[2];  //!< Rx0/Rx1 interrupt handlers
  can_wake_callback_t CanWakeCb;      //!< CAN wakeup interrupt handler
  can_err_callback_t CanErrorCb;      //!< CAN error interrupt handler
};

/**
 * @brief holds current CAN instance state variables.
 */
struct can_state_t
{
  can_tx_callback_t CanTxReadyCb[3]; //!< Tx ready callbacks for TX0/TX1/TX2
};

/**
 * @brief holds CAN frame and is used in driver's API to transfer
 * frames between the driver and an application
 */
struct can_frame_t
{
  union {
    struct {
      uint32_t ID      :29; //!< Device ID (11 or 29 bit)
      uint32_t ERR     : 1; //!< error message frame flag
      uint32_t RTR     : 1; //!< remote transmission request flag
      uint32_t EXT     : 1; //!< 29bit Id flag
    };
    uint32_t IDFull;
  };
  uint8_t Data[8];          //!< CAN frame payload (0 to 8 bytes)
  uint8_t Length;          //!< actual frame data length (0-8)
};

/**
 * @brief CAN timing initialisation structure definition
 */
struct can_bittime_t
{
  uint8_t BRP;     //!< Baud Rate Prescaler (5 bit). TQ = 2*(BRP+1)/Freq
  uint8_t SJW;     //!< Synchronisation Jump Width Length = (SJW+1)*TQ (0-3)
  uint8_t PRSEG;   //!< Propagation Segment Length bits = (PRSEG+1)*TQ (0-7)
  uint8_t PHSEG1;  //!< Phase Segment 1 Length bits = (PHSEG1+1)*TQ (0-7)
  uint8_t PHSEG2;  //!< Phase Segment 2 Length bits = (PHSEG2+1)*TQ (1-7)
  uint8_t BTLMODE; //!< PS2 mode (0: PS2=max(PS1,2*TQ) ; 1: PS2 determined by PHSEG2).
  uint8_t SAM;     //!< Sample Point Configuration bit (0: 1 sample ; 1: 3 samples).
};


/******************************************************************************
 *  CAN driver public functions
 *****************************************************************************/

/**
 * @brief Driver's HW interrupt callback to be exposed to EVE config
 * @param Can       Pointer to CAN instance structure
 */
void CanInterruptCb(const struct can_t* Can);

/**
 * @brief Initialises CAN instance structure, connects it to SPI.\n
 *        Powers up MCP2562x if supported
 * @param Can       CAN driver descriptor
 */
extern bool CanInit(const struct can_t* Can);

/**
 * @brief Disables interrupts from MCP2562x and releases SPI.\n
 * Powers down MCP2562x if supported by product HW.
 * @param Can       CAN driver descriptor
 */
extern bool CanDisable(const struct can_t* Can);

/**
 * @brief Performs MCP2562x HW reset. MCP2562x switches to configuration mode after reset.\n
 * NB! It should be verified that MCP2562x is in configuration mode with
 * CanGetMode() function after reset before any subsequent operation.
 * @param Can       CAN driver descriptor
 */
extern void CanReset(const struct can_t* Can);

/**
 * @brief Sets up MCP2562x registers according to preconfigured parameters.\n
 * NB! MCP2562x should be in configuration mode.
 * @param Can       CAN driver descriptor
 */
extern bool CanSetup(const struct can_t* Can);

/**
 * @brief Sets up MCP2562x CAN timing parameters.\n
 * NB! MCP2562x should be in configuration mode.
 * @param Can       CAN driver descriptor
 * @param BitTime   Pointer to can_bittime_t structure containing the configuration information.
 */
extern bool CanSetBitTime(const struct can_t* Can,
                          struct can_bittime_t* BitTime);

/**
 * @brief Sets up MCP2562x acceptance filters.\n
 * NB! MCP2562x should be in configuration mode.
 * @param Can     CAN driver descriptor
 * @param Id      Filter identification number / mask number (11 or 29 bit)
 * @param Filter  RX filter Id or Mask
 */
extern bool CanSetFilter(const struct can_t* Can,
                         uint32_t Id,
                         enum can_filter_t Filter);

/**
 * @brief Reads current MCP2562x mode of operation.
 * @param Can       CAN driver descriptor
 * @return          Current mode of operation..
 */
extern enum can_mode_t CanGetMode(const struct can_t* Can);

/**
 * @brief Sets current MCP2562x mode of operation.\n
 * NB! After setting new mode it should be verified that MCP2562x is in
 * desired mode (in configuration mode after SW reset) with CanGetMode()
 * function before any subsequent operation.
 * @param Can       CAN driver descriptor
 * @param Mode      Mode of operation to set.
 */
extern bool CanSetMode(const struct can_t* Can, enum can_mode_t Mode);

/**
 * @brief Loads 1 full CAN frame to MCP2562x TX register.
 * @param Can     CAN driver descriptor
 * @param Frame   Structure holding the data to send.
 * @param Buffer  MCP2562x TX buffer to use.
 * @return TX buffer actually used for transmission.\n
 *         CAN_FIFO is returned on busy TX buffer / busy SPI
 */
extern enum can_xbuffer_t CanUploadFrame(const struct can_t* Can,
                                         struct can_frame_t* Frame,
                                         enum can_xbuffer_t Buffer);

/**
 * @brief Sets priority and RTS flag to one of MCP2562x TX registers initiating transfer.
 * @param Can      CAN driver descriptor
 * @param Buffer   MCP2562x TX buffer to use
 * @param Priority Message priority
 * @param TransmitReadyCb Callback to call when transmission is done
 * @return false on error
 */
extern bool CanSendFrame(const struct can_t* Can,
                         enum can_xbuffer_t Buffer,
                         enum can_priority_t Priority,
                         can_tx_callback_t TransmitReadyCb);

/**
 * @brief Receives 1 full CAN frame from MCP2562x after Rx1/Rx2 is ready.
 * @param Can    CAN driver descriptor
 * @param Frame  Structure to copy received data to
 * @param Buffer MCP2562x RX buffer to read from
 * @return RX buffer actually been read.\n
 *         CAN_FIFO is returned on RX buffer not ready / busy SPI
 */
extern enum can_xbuffer_t CanDownloadFrame(const struct can_t* Can,
                                           struct can_frame_t* Frame,
                                           enum can_xbuffer_t Buffer);

/**
 * @brief Gets MCP2562x TX/RX buffers status (IF/RTS).
 * @param Can     CAN driver descriptor
 * @param Status  Pointer to result: TX/RX buffers status as returned by MCP2562x "READ STATUS" command.\n
 *        Masks:\n
 *        STAT_TX2IF  - Tx2 buffer interrupt flag (Tx2 was sent)\n
 *        STAT_TX2REQ - Tx2 RTS flag (Tx2 is pending)\n
 *        STAT_TX1IF  - Tx1 buffer interrupt flag (Tx1 was sent)\n
 *        STAT_TX1REQ - Tx1 RTS flag (Tx1 is pending)\n
 *        STAT_TX0IF  - Tx0 buffer interrupt flag (Tx0 was sent)\n
 *        STAT_TX0REQ - Tx0 RTS flag (Tx0 is pending)\n
 *        STAT_RX1IF  - Rx1 buffer interrupt flag (Rx1 is ready to be read)\n
 *        STAT_RX0IF  - Rx0 buffer interrupt flag (Rx0 is ready to be read)
 * @return false on error.
 */
extern bool CanReadStatus(const struct can_t* Can, uint8_t* Status);

/**
 * @brief Clear MCP2562x interrupt flag(s) by mask.
 * @param Can     CAN driver descriptor
 * @param Mask    MCP2562x interrupt register mask\n
 *        Masks:\n
 *        INT_RX0IF - Rx0 Full Interrupt Flag bit - must be cleared by MCU to reset interrupt condition\n
 *        INT_RX1IF - Rx1 Full Interrupt Flag bit - must be cleared by MCU to reset interrupt condition\n
 *        INT_TX0IF - Tx0 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition\n
 *        INT_TX1IF - Tx1 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition\n
 *        INT_TX2IF - Tx2 Empty Interrupt Flag bit - must be cleared by MCU to reset interrupt condition\n
 *        INT_ERRIF - Error Interrupt Flag bit (multiple sources in the EFLG register) - must be cleared by MCU to reset interrupt condition\n
 *        INT_WAKIF - Wake-up Interrupt Flag bit - must be cleared by MCU to reset interrupt condition\n
 *        INT_MERRF - Message Error Interrupt Flag bit - must be cleared by MCU to reset interrupt condition\n
 * @return false on error.
 */
extern bool CanClearIF(const struct can_t* Can, uint8_t Mask);

/**
 * @brief Sets/resets all the preconfigured interrupts.
 * @param Can      CAN driver descriptor
 * @param Enable   true - enable some (preconfigured) interrupts,
 *                 false - disable all interrupts
 * @return false on error
 */
extern bool CanInterrupts(const struct can_t* Can, bool Enable);

/** \} MCP2562x */

#endif // DRIVER_CAN_H