/**
@defgroup can_pal Controller Area Network - Peripheral Abstraction Layer (CAN PAL)
@brief The S32 SDK provides a Peripheral Abstraction Layer for Controller Area
Network (CAN) modules of S32 SDK devices.
<p>
  The CAN PAL driver allows communication over a CAN bus. It was designed to be
  portable across all platforms and IPs which support CAN communication.
</p>

  ## How to integrate CAN PAL in your application ##
<p>
  Unlike the other drivers, CAN PAL modules need to include a configuration
  file named can_pal_cfg.h, which allows the user to specify which IPSs are used
  and how many resources are allocated for each of them (state structures).
  The following code example shows how to configure one instance for each
  available CAN IP.
</p>

 @code
 #ifndef can_pal_cfg_H
 #define can_pal_cfg_H

 /* Define which IP instance will be used in current project */
 #define CAN_OVER_FLEXCAN

 /* Define the resources necessary for current project */
 #define NO_OF_FLEXCAN_INSTS_FOR_CAN    1U

 #endif /* can_pal_cfg_H */
 @endcode

 The following table contains the matching between platforms and available IPs
    IP/MCU     |S32K116|S32K118|S32K142|S32K144|S32K146|S32K148|S32V234|MPC5748G|MPC5746C|MPC5744P|S32R274|S32R372|
 -------------:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:------:|:------:|:------:|:-----:|:------|
    FlexCAN    |  YES  |  YES  |  YES  |  YES  |  YES  |  YES  |  YES  |  YES   |  YES   |  YES   |  YES  |  YES  |

<p>
  ## Features ##
   - Standard data frames
   - Extended data frames
   - Flexible data rate (FD)
   - Bitrate switch inside FD format frames (BRS)
   - Zero to sixty four bytes data length
   - Programmable bit rate
   - Flexible buffers configurable to store 0 to 8, 16, 32 or 64 bytes data length depending of platform support
   - Each buffer configurable as receive or transmit, all supporting standard and
   extended messages
   - Individual Rx Masking per buffer
   - Loop-Back mode
   - Remote request frames

    The following table contains the matching between platforms and available features
      FEATURE/MCU    |S32K116|S32K118|S32K142|S32K144|S32K146|S32K148|S32V234|MPC5748G|MPC5746C|MPC5744P|S32R274|S32R372|
  ------------------:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:-----:|:------:|:------:|:------:|:-----:|:------|
        FD/BRS       |  YES  |  YES  |  YES  |  YES  |  YES  |  YES  |  YES  |  YES   |  YES   |   NO   |  YES  |  YES  |
   data length > 8B  |  YES  |  YES  |  YES  |  YES  |  YES  |  YES  |  YES  |  YES   |  YES   |   NO   |  YES  |  YES  |
                             
  ## Functionality ##

  ### Initialization ###
<p>
  In order to use the CAN PAL driver it must be first initialized, using
  <b>CAN_Init()</b> function. Once initialized, it cannot be initialized again
  for the same CAN module instance until it is de-initialized, using <b>CAN_Deinit()</b>.
  Different CAN modules instances can function independently of each other.

  The <b>can_user_config_t</b> structure allows you to configure the following:
      - the number of buffers needed;
      - the operation mode, which can be one of the following:
         - normal mode;
         - loopback mode;
         - disable mode;
      - the Protocol Engine clock source:
         - oscillator clock;
         - peripheral clock;
      - the payload size of the buffers:
         - 8 bytes;
         - 16 bytes (only available with the FD feature enabled);
         - 32 bytes (only available with the FD feature enabled);
         - 64 bytes (only available with the FD feature enabled);
      - enable/disable the Flexible Data-rate feature;
      - the bitrate used for standard frames or for the arbitration phase of FD frames;
      - the bitrate used for the data phase of FD frames;

   The bitrate is represented by a <b>can_time_segment_t</b> structure, with the following fields:
      - propagation segment;
      - phase segment 1;
      - phase segment 2;
      - clock prescaler division factor;
      - resync jump width.

   In order to use a buffer for transmission/reception, it has to be initialized using either
   <b>CAN_ConfigRxBuff</b> or <b>CAN_ConfigTxBuff</b>.

   After having the buffer configured, you can start sending/receiving data by calling one
   of the following functions:
      - CAN_Send;
      - CAN_SendBlocking;
      - CAN_Receive;
      - CAN_ReceiveBlocking.
</p>

  ### FlexCAN Rx FIFO extension ###
<p>
  When used over FlexCAN, the PAL allows extending the basic configuration with an Rx FIFO feature.
  The Rx FIFO is receive-only and 6-message deep. The application can read the received messages
  sequentially, in the order they were received, by repeatedly reading the data from buffer 0 (zero).
  A powerful filtering scheme is provided to accept only frames intended for the target application.
  The FIFO and filtering criteria are configured by passing a structure of <b>extension_flexcan_rx_fifo_t</b> type,
  through the extension field of the user configuration structure.

  @code

  /* ID Filter table */
  flexcan_id_table_t filterTable[] = {
    {
     .isExtendedFrame = false,
     .isRemoteFrame = false,
     .id = 1U
    },
    ...
  };

  /* Rx FIFO extension */
  extension_flexcan_rx_fifo_t  can_pal1_rx_fifo_ext0 = {
    .numIdFilters = FLEXCAN_RX_FIFO_ID_FILTERS_8,
    .idFormat = FLEXCAN_RX_FIFO_ID_FORMAT_A,
    /* User must pass reference to the ID filter table. */
    .idFilterTable = NULL
  };

  can_pal1_rx_fifo_ext0.idFilterTable = filterTable;

  @endcode

  The number of elements in the ID filter table is defined by the following formula:
    - for format A: the number of Rx FIFO ID filters
    - for format B: twice the number of Rx FIFO ID filters
    - for format C: four times the number of Rx FIFO ID filters
  The user must provide the exact number of elements in order to avoid
  any misconfiguration.

  Each element in the ID filter table specifies an ID to be used as
  acceptance criteria for the FIFO as follows:
    - for format A: In the standard frame format, bits 10 to 0 of the ID
      are used for frame identification. In the extended frame format, bits
      28 to 0 are used.
    - for format B: In the standard frame format, bits 10 to 0 of the ID
      are used for frame identification. In the extended frame format, only
      the 14 most significant bits (28 to 15) of the ID are compared to the
      14 most significant bits (28 to 15) of the received ID.
    - for format C: In both standard and extended frame formats, only the 8
      most significant bits (7 to 0 for standard, 28 to 21 for extended) of
      the ID are compared to the 8 most significant bits (7 to 0 for
      standard, 28 to 21 for extended) of the received ID.

  When Rx FIFO feature is enabled, buffer 0 (zero) cannot be used for transmission or reconfigured for reception
  using <b>CAN_ConfigRxBuff()</b> and <b>CAN_SetRxFilter()</b> functions.
</p>

  ## Important Notes ##
<p>
  - Before using the CAN PAL driver the module clock must be configured. Refer to <b>Clock Manager</b> component for clock configuration.
  - The driver enables the interrupts for the corresponding CAN module, but any interrupt priority
    must be done by the application.
  - The board specific configurations must be done prior to driver calls; the driver has no influence on the
    functionality of the RX/TX pins - they must be configured by application. Refer to <b>PinSettings</b> component for pin configuration.
  - Some features are not available for all platforms (see the table above for the matching between platforms and available features).
  - When used <b>CAN_ReceiveBlocking()</b> and <b>CAN_SendBlocking()</b> with timeout parameter 0 and the message is already in mailbox 
    configured will report timeout and successful transmit or receive the message.
</p>
  </p>
 ## Example code ##
 @code

 #define TX_BUFF_IDX    0U
 #define RX_BUFF_IDX    1U

  uint32_t msgID = 0xAB;

  /* CAN PAL instance information */
  const can_instance_t can_pal1_instance = {CAN_INST_TYPE_FLEXCAN, 0U};

  /* User configuration structure */
  can_user_config_t config = {
    .maxBuffNum = 2U,
    .mode = CAN_LOOPBACK_MODE,
    .peClkSrc = CAN_CLK_SOURCE_OSC,
    .enableFD = false,
    .payloadSize = CAN_PAYLOAD_SIZE_8,
    .nominalBitrate = {
        .propSeg = 7,
        .phaseSeg1 = 4,
        .phaseSeg2 = 1,
        .preDivider = 0,
        .rJumpwidth = 1
    },
    .dataBitrate = {
        .propSeg = 7,
        .phaseSeg1 = 4,
        .phaseSeg2 = 1,
        .preDivider = 0,
        .rJumpwidth = 1
    },
    .extension = NULL
  };

  /* Initialize CAN */
  CAN_Init(&can_pal1_instance, &config);

  /* Buffer configuration */
  can_buff_config_t buffConfig = {
    .enableFD = false,
    .enableBRS = false,
    .fdPadding = 0xCC,
    .idType = CAN_MSG_ID_STD,
    .isRemote = false
  };

  CAN_ConfigTxBuff(&can_pal1_instance, TX_BUFF_IDX, &buffConfig);
  CAN_ConfigRxBuff(&can_pal1_instance, RX_BUFF_IDX, &buffConfig, msgID);

  can_message_t recvMsg, sendMsg = {
    .id = msgID,
    .length = 5U,
    .data = {"Hello"}
  };

  /* Send data using buffer configured for transmission */
  CAN_Send(&can_pal1_instance, TX_BUFF_IDX, &sendMsg);
  while(CAN_GetTransferStatus(&can_pal1_instance, TX_BUFF_IDX) == STATUS_BUSY);

  /* Receive data using buffer configured for reception */
  CAN_Receive(&can_pal1_instance, RX_BUFF_IDX, &recvMsg);
  while(CAN_GetTransferStatus(&can_pal1_instance, RX_BUFF_IDX) == STATUS_BUSY);

  /* De-initialize CAN */
  CAN_Deinit(&can_pal1_instance);

 @endcode
 
   ## Integration guideline ##
 
### Compilation units ###

The following files need to be compiled in the project:
\verbatim
${S32SDK_PATH}\platform\pal\src\can\can_pal.c
\endverbatim

### Include path ###

The following paths need to be added to the include path of the toolchain:
\verbatim
${S32SDK_PATH}\platform\pal\inc\
\endverbatim

### Preprocessor symbols ###

No special symbols are required for this component

### Dependencies ###
\ref flexcan
\ref clock_manager
\ref interrupt_manager
\ref edma 
@}*/