![]() |
S32 SDK
|
This section describes the programming interface of the Peripheral driver for LIN.
The LIN (Local Interconnect Network) Driver is an use-case driven High Level Peripheral Driver. The driver is built on HAL drivers and provides users important key features. NXP provides LIN Stack as a middleware software package that is developed on LIN driver. Users also can create their own LIN applications and LIN stack that are compatible with LIN Specification.
In this release package, LIN Driver is built on LPUART interface.
The driver uses instantiations of the lin_state_t to maintain the current state of a particular LIN Hardware instance module driver.
The user is required to provide memory for the driver state structures during the initialization. The driver itself does not statically allocate memory.
The driver implements transmit and receive functions to transfer buffers of data by blocking and non-blocking modes.
The blocking transmit and receive functions include LIN_DRV_SendFrameDataBlocking() and the LIN_DRV_ReceiveFrameDataBlocking() functions.
The non-blocking (async) transmit and receive functions include the LIN_DRV_SendFrameData() and the LIN_DRV_ReceiveFrameData() functions.
Master nodes can transmit frame headers in non-blocking mode using LIN_DRV_MasterSendHeader().
In all these cases, the functions are interrupt-driven.
AUTOBAUD is an extensive feature in LIN Driver which allows a slave node to automatically detect baudrate of LIN bus and adapt its original baudrate to bus value. Auto Baud is applied when the baudrate of the incoming data is unknown. Currently autobaud feature is supported to detect LIN bus baudrates 2400, 4800, 9600, 14400, 19200 bps.
If autobaud feature is enabled, at LIN driver initialization slave's baudrate is set to 19200bps. The application should use a timer interrupt in input capture mode of both rising and falling edges(E.g FTM), call LIN_DRV_AutoBaudCapture(uint32_t instance) function to calculate and set Slave's baudrate like Master's baudrate. When receiving a frame header, the slave detect LIN bus's baudrate based on the synchronization byte and adapts its baudrate accordingly. On changing baudrate, the slave set current event ID to LIN_BAUDRATE_ADJUSTED and call the callback function. In that callback function users might change the frame data count timeout. Users can look at CallbackHandler() in lin.c of lin middleware for a reference.
Note: Lin driver should be initiated before initiating a timer interrupt( E.g FTM).
Data Structures | |
struct | lin_user_config_t |
LIN hardware configuration structure Implements : lin_user_config_t_Class. More... | |
struct | lin_state_t |
Runtime state of the LIN driver. More... | |
Macros | |
#define | SLAVE 0U |
#define | MASTER 1U |
#define | MAKE_PARITY 0U |
#define | CHECK_PARITY 1U |
Typedefs | |
typedef uint32_t(* | lin_timer_get_time_interval_t) (uint32_t *nanoSeconds) |
Callback function to get time interval in nanoseconds Implements : lin_timer_get_time_interval_t_Class. More... | |
typedef void(* | lin_callback_t) (uint32_t instance, void *linState) |
LIN Driver callback function type Implements : lin_callback_t_Class. More... | |
Enumerations | |
enum | lin_event_id_t { LIN_NO_EVENT = 0x00U, LIN_WAKEUP_SIGNAL = 0x01U, LIN_BAUDRATE_ADJUSTED = 0x02U, LIN_RECV_BREAK_FIELD_OK = 0x03U, LIN_SYNC_OK = 0x04U, LIN_SYNC_ERROR = 0x05U, LIN_PID_OK = 0x06U, LIN_PID_ERROR = 0x07U, LIN_FRAME_ERROR = 0x08U, LIN_READBACK_ERROR = 0x09U, LIN_CHECKSUM_ERROR = 0x0AU, LIN_TX_COMPLETED = 0x0BU, LIN_RX_COMPLETED = 0x0CU } |
Defines types for an enumerating event related to an Identifier. Implements : lin_event_id_t_Class. More... | |
enum | lin_node_state_t { LIN_NODE_STATE_UNINIT = 0x00U, LIN_NODE_STATE_SLEEP_MODE = 0x01U, LIN_NODE_STATE_IDLE = 0x02U, LIN_NODE_STATE_SEND_BREAK_FIELD = 0x03U, LIN_NODE_STATE_RECV_SYNC = 0x04U, LIN_NODE_STATE_SEND_PID = 0x05U, LIN_NODE_STATE_RECV_PID = 0x06U, LIN_NODE_STATE_RECV_DATA = 0x07U, LIN_NODE_STATE_RECV_DATA_COMPLETED = 0x08U, LIN_NODE_STATE_SEND_DATA = 0x09U, LIN_NODE_STATE_SEND_DATA_COMPLETED = 0x0AU } |
Define type for an enumerating LIN Node state. Implements : lin_node_state_t_Class. More... | |
LIN DRIVER | |
status_t | LIN_DRV_Init (uint32_t instance, lin_user_config_t *linUserConfig, lin_state_t *linCurrentState) |
Initializes an instance LIN Hardware Interface for LIN Network. More... | |
status_t | LIN_DRV_Deinit (uint32_t instance) |
Shuts down the LIN Hardware Interface by disabling interrupts and transmitter/receiver. More... | |
lin_callback_t | LIN_DRV_InstallCallback (uint32_t instance, lin_callback_t function) |
Installs callback function that is used for LIN_DRV_IRQHandler. More... | |
status_t | LIN_DRV_SendFrameDataBlocking (uint32_t instance, const uint8_t *txBuff, uint8_t txSize, uint32_t timeoutMSec) |
Sends Frame data out through the LIN Hardware Interface using blocking method. This function will calculate the checksum byte and send it with the frame data. Blocking means that the function does not return until the transmission is complete. This function checks if txSize is in range from 1 to 8. If not, it will return STATUS_ERROR. This function also returns STATUS_ERROR if node's current state is in SLEEP mode. This function checks if the isBusBusy is false, if not it will return LIN_BUS_BUSY. The function does not return until the transmission is complete. If the transmission is successful, it will return STATUS_SUCCESS. If not, it will return STATUS_TIMEOUT. More... | |
status_t | LIN_DRV_SendFrameData (uint32_t instance, const uint8_t *txBuff, uint8_t txSize) |
Sends frame data out through the LIN Hardware Interface using non-blocking method. This enables an a-sync method for transmitting data. Non-blocking means that the function returns immediately. The application has to get the transmit status to know when the transmit is complete. This function will calculate the checksum byte and send it with the frame data. The function will return immediately after calling this function. If txSize is equal to 0 or greater than 8 or node's current state is in SLEEP mode then the function will return STATUS_ERROR. If isBusBusy is currently true then the function will return LIN_BUS_BUSY. More... | |
status_t | LIN_DRV_GetTransmitStatus (uint32_t instance, uint8_t *bytesRemaining) |
Get status of an on-going non-blocking transmission While sending frame data using non-blocking method, users can use this function to get status of that transmission. The bytesRemaining shows number of bytes that still needed to transmit. More... | |
status_t | LIN_DRV_ReceiveFrameDataBlocking (uint32_t instance, uint8_t *rxBuff, uint8_t rxSize, uint32_t timeoutMSec) |
Receives frame data through the LIN Hardware Interface using blocking method. This function receives data from LPUART module using blocking method, the function does not return until the receive is complete. The interrupt handler LIN_LPUART_DRV_IRQHandler will check the checksum byte. If the checksum is correct, it will receive the frame data. If the checksum is incorrect, this function will return STATUS_TIMEOUT and data in rxBuff might be wrong. This function also check if rxSize is in range from 1 to 8. If not, it will return STATUS_ERROR. This function also returns STATUS_ERROR if node's current state is in SLEEP mode. This function checks if the isBusBusy is false, if not it will return LIN_BUS_BUSY. More... | |
status_t | LIN_DRV_ReceiveFrameData (uint32_t instance, uint8_t *rxBuff, uint8_t rxSize) |
Receives frame data through the LIN Hardware Interface using non-blocking method. This function will check the checksum byte. If the checksum is correct, it will receive it with the frame data. Non-blocking means that the function returns immediately. The application has to get the receive status to know when the reception is complete. The interrupt handler LIN_LPUART_DRV_IRQHandler will check the checksum byte. If the checksum is correct, it will receive the frame data. If the checksum is incorrect, this function will return STATUS_TIMEOUT and data in rxBuff might be wrong. This function also check if rxSize is in range from 1 to 8. If not, it will return STATUS_ERROR. This function also returns STATUS_ERROR if node's current state is in SLEEP mode. This function checks if the isBusBusy is false, if not it will return LIN_BUS_BUSY. More... | |
status_t | LIN_DRV_AbortTransferData (uint32_t instance) |
Aborts an on-going non-blocking transmission/reception. While performing a non-blocking transferring data, users can call this function to terminate immediately the transferring. More... | |
status_t | LIN_DRV_GetReceiveStatus (uint32_t instance, uint8_t *bytesRemaining) |
Get status of an on-going non-blocking reception. This function returns whether the data reception is complete. When performing non-blocking transmit, the user can call this function to ascertain the state of the current receive progress: in progress (STATUS_BUSY) or timeout (STATUS_TIMEOUT) or complete (STATUS_SUCCESS). In addition, if the reception is still in progress, the user can obtain the number of bytes that still needed to receive. More... | |
status_t | LIN_DRV_GoToSleepMode (uint32_t instance) |
Puts current LIN node to sleep mode This function changes current node state to LIN_NODE_STATE_SLEEP_MODE. More... | |
status_t | LIN_DRV_GotoIdleState (uint32_t instance) |
Puts current LIN node to Idle state This function changes current node state to LIN_NODE_STATE_IDLE. More... | |
status_t | LIN_DRV_SendWakeupSignal (uint32_t instance) |
Sends a wakeup signal through the LIN Hardware Interface. More... | |
lin_node_state_t | LIN_DRV_GetCurrentNodeState (uint32_t instance) |
Get the current LIN node state. More... | |
void | LIN_DRV_TimeoutService (uint32_t instance) |
Callback function for Timer Interrupt Handler Users may use (optional, not required) LIN_DRV_TimeoutService to check if timeout has occurred during non-blocking frame data transmission and reception. User may initialize a timer (for example FTM) in Output Compare Mode with period of 500 micro seconds (recommended). In timer IRQ handler, call this function. More... | |
void | LIN_DRV_SetTimeoutCounter (uint32_t instance, uint32_t timeoutValue) |
Set Value for Timeout Counter that is used in LIN_DRV_TimeoutService. More... | |
status_t | LIN_DRV_MasterSendHeader (uint32_t instance, uint8_t id) |
Sends frame header out through the LIN Hardware Interface using a non-blocking method. This function sends LIN Break field, sync field then the ID with correct parity. This function checks if the interface is Master, if not, it will return STATUS_ERROR.This function checks if id is in range from 0 to 0x3F, if not it will return STATUS_ERROR. More... | |
status_t | LIN_DRV_EnableIRQ (uint32_t instance) |
Enables LIN hardware interrupts. More... | |
status_t | LIN_DRV_DisableIRQ (uint32_t instance) |
Disables LIN hardware interrupts. More... | |
void | LIN_DRV_IRQHandler (uint32_t instance) |
Interrupt handler for LIN Hardware Interface. More... | |
uint8_t | LIN_DRV_ProcessParity (uint8_t PID, uint8_t typeAction) |
Makes or checks parity bits. If action is checking parity, the function returns ID value if parity bits are correct or 0xFF if parity bits are incorrect. If action is making parity bits, then from input value of ID, the function returns PID. This is not a public API as it is called by other API functions. More... | |
uint8_t | LIN_DRV_MakeChecksumByte (const uint8_t *buffer, uint8_t sizeBuffer, uint8_t PID) |
Makes the checksum byte for a frame. More... | |
status_t | LIN_DRV_AutoBaudCapture (uint32_t instance) |
Captures time interval to capture baudrate automatically when enable autobaud feature. This function should only be used in Slave. The timer should be in input capture mode of both rising and falling edges. The timer input capture pin should be externally connected to RXD pin. More... | |
#define CHECK_PARITY 1U |
Definition at line 53 of file lin_driver.h.
#define MAKE_PARITY 0U |
Definition at line 52 of file lin_driver.h.
#define MASTER 1U |
Definition at line 51 of file lin_driver.h.
#define SLAVE 0U |
Definition at line 50 of file lin_driver.h.
typedef void(* lin_callback_t) (uint32_t instance, void *linState) |
LIN Driver callback function type Implements : lin_callback_t_Class.
Definition at line 115 of file lin_driver.h.
typedef uint32_t(* lin_timer_get_time_interval_t) (uint32_t *nanoSeconds) |
Callback function to get time interval in nanoseconds Implements : lin_timer_get_time_interval_t_Class.
Definition at line 60 of file lin_driver.h.
enum lin_event_id_t |
Defines types for an enumerating event related to an Identifier. Implements : lin_event_id_t_Class.
Definition at line 77 of file lin_driver.h.
enum lin_node_state_t |
Define type for an enumerating LIN Node state. Implements : lin_node_state_t_Class.
Definition at line 97 of file lin_driver.h.
status_t LIN_DRV_AbortTransferData | ( | uint32_t | instance | ) |
Aborts an on-going non-blocking transmission/reception. While performing a non-blocking transferring data, users can call this function to terminate immediately the transferring.
instance | LIN Hardware Interface instance number |
Definition at line 257 of file lin_driver.c.
status_t LIN_DRV_AutoBaudCapture | ( | uint32_t | instance | ) |
Captures time interval to capture baudrate automatically when enable autobaud feature. This function should only be used in Slave. The timer should be in input capture mode of both rising and falling edges. The timer input capture pin should be externally connected to RXD pin.
instance | LIN Hardware Interface instance number |
Definition at line 484 of file lin_driver.c.
status_t LIN_DRV_Deinit | ( | uint32_t | instance | ) |
Shuts down the LIN Hardware Interface by disabling interrupts and transmitter/receiver.
instance | LIN Hardware Interface instance number |
Definition at line 83 of file lin_driver.c.
status_t LIN_DRV_DisableIRQ | ( | uint32_t | instance | ) |
Disables LIN hardware interrupts.
instance | LIN Hardware Interface instance number |
Definition at line 446 of file lin_driver.c.
status_t LIN_DRV_EnableIRQ | ( | uint32_t | instance | ) |
Enables LIN hardware interrupts.
instance | LIN Hardware Interface instance number |
Definition at line 428 of file lin_driver.c.
lin_node_state_t LIN_DRV_GetCurrentNodeState | ( | uint32_t | instance | ) |
Get the current LIN node state.
instance | LIN Hardware Interface instance number |
Definition at line 354 of file lin_driver.c.
status_t LIN_DRV_GetReceiveStatus | ( | uint32_t | instance, |
uint8_t * | bytesRemaining | ||
) |
Get status of an on-going non-blocking reception. This function returns whether the data reception is complete. When performing non-blocking transmit, the user can call this function to ascertain the state of the current receive progress: in progress (STATUS_BUSY) or timeout (STATUS_TIMEOUT) or complete (STATUS_SUCCESS). In addition, if the reception is still in progress, the user can obtain the number of bytes that still needed to receive.
instance | LIN Hardware Interface instance number |
bytesRemaining | Number of bytes still needed to receive |
Definition at line 280 of file lin_driver.c.
status_t LIN_DRV_GetTransmitStatus | ( | uint32_t | instance, |
uint8_t * | bytesRemaining | ||
) |
Get status of an on-going non-blocking transmission While sending frame data using non-blocking method, users can use this function to get status of that transmission. The bytesRemaining shows number of bytes that still needed to transmit.
instance | LIN Hardware Interface instance number |
bytesRemaining | Number of bytes still needed to transmit |
Definition at line 178 of file lin_driver.c.
status_t LIN_DRV_GotoIdleState | ( | uint32_t | instance | ) |
Puts current LIN node to Idle state This function changes current node state to LIN_NODE_STATE_IDLE.
instance | LIN Hardware Interface instance number |
Definition at line 318 of file lin_driver.c.
status_t LIN_DRV_GoToSleepMode | ( | uint32_t | instance | ) |
Puts current LIN node to sleep mode This function changes current node state to LIN_NODE_STATE_SLEEP_MODE.
instance | LIN Hardware Interface instance number |
Definition at line 300 of file lin_driver.c.
status_t LIN_DRV_Init | ( | uint32_t | instance, |
lin_user_config_t * | linUserConfig, | ||
lin_state_t * | linCurrentState | ||
) |
Initializes an instance LIN Hardware Interface for LIN Network.
The caller provides memory for the driver state structures during initialization. The user must select the LIN Hardware Interface clock source in the application to initialize the LIN Hardware Interface.
instance | LIN Hardware Interface instance number |
linUserConfig | user configuration structure of type lin_user_config_t |
linCurrentState | pointer to the LIN Hardware Interface driver state structure |
Definition at line 62 of file lin_driver.c.
lin_callback_t LIN_DRV_InstallCallback | ( | uint32_t | instance, |
lin_callback_t | function | ||
) |
Installs callback function that is used for LIN_DRV_IRQHandler.
instance | LIN Hardware Interface instance number. |
function | the LIN receive callback function. |
Definition at line 102 of file lin_driver.c.
void LIN_DRV_IRQHandler | ( | uint32_t | instance | ) |
Interrupt handler for LIN Hardware Interface.
instance | LIN Hardware Interface instance number |
Definition at line 466 of file lin_driver.c.
uint8_t LIN_DRV_MakeChecksumByte | ( | const uint8_t * | buffer, |
uint8_t | sizeBuffer, | ||
uint8_t | PID | ||
) |
Makes the checksum byte for a frame.
buffer | Pointer to Tx buffer |
sizeBuffer | Number of bytes that are contained in the buffer. |
PID | Protected Identifier byte. |
Definition at line 102 of file lin_common.c.
status_t LIN_DRV_MasterSendHeader | ( | uint32_t | instance, |
uint8_t | id | ||
) |
Sends frame header out through the LIN Hardware Interface using a non-blocking method. This function sends LIN Break field, sync field then the ID with correct parity. This function checks if the interface is Master, if not, it will return STATUS_ERROR.This function checks if id is in range from 0 to 0x3F, if not it will return STATUS_ERROR.
instance | LIN Hardware Interface instance number |
id | Frame Identifier |
Definition at line 409 of file lin_driver.c.
uint8_t LIN_DRV_ProcessParity | ( | uint8_t | PID, |
uint8_t | typeAction | ||
) |
Makes or checks parity bits. If action is checking parity, the function returns ID value if parity bits are correct or 0xFF if parity bits are incorrect. If action is making parity bits, then from input value of ID, the function returns PID. This is not a public API as it is called by other API functions.
PID | PID byte in case of checking parity bits or ID byte in case of making parity bits. |
typeAction | 1 for Checking parity bits, 0 for making parity bits |
Definition at line 58 of file lin_common.c.
status_t LIN_DRV_ReceiveFrameData | ( | uint32_t | instance, |
uint8_t * | rxBuff, | ||
uint8_t | rxSize | ||
) |
Receives frame data through the LIN Hardware Interface using non-blocking method. This function will check the checksum byte. If the checksum is correct, it will receive it with the frame data. Non-blocking means that the function returns immediately. The application has to get the receive status to know when the reception is complete. The interrupt handler LIN_LPUART_DRV_IRQHandler will check the checksum byte. If the checksum is correct, it will receive the frame data. If the checksum is incorrect, this function will return STATUS_TIMEOUT and data in rxBuff might be wrong. This function also check if rxSize is in range from 1 to 8. If not, it will return STATUS_ERROR. This function also returns STATUS_ERROR if node's current state is in SLEEP mode. This function checks if the isBusBusy is false, if not it will return LIN_BUS_BUSY.
instance | LIN Hardware Interface instance number |
rxBuff | buffer containing 8-bit received data |
rxSize | the number of bytes to receive |
Definition at line 235 of file lin_driver.c.
status_t LIN_DRV_ReceiveFrameDataBlocking | ( | uint32_t | instance, |
uint8_t * | rxBuff, | ||
uint8_t | rxSize, | ||
uint32_t | timeoutMSec | ||
) |
Receives frame data through the LIN Hardware Interface using blocking method. This function receives data from LPUART module using blocking method, the function does not return until the receive is complete. The interrupt handler LIN_LPUART_DRV_IRQHandler will check the checksum byte. If the checksum is correct, it will receive the frame data. If the checksum is incorrect, this function will return STATUS_TIMEOUT and data in rxBuff might be wrong. This function also check if rxSize is in range from 1 to 8. If not, it will return STATUS_ERROR. This function also returns STATUS_ERROR if node's current state is in SLEEP mode. This function checks if the isBusBusy is false, if not it will return LIN_BUS_BUSY.
instance | LIN Hardware Interface instance number |
rxBuff | buffer containing 8-bit received data |
rxSize | the number of bytes to receive |
timeoutMSec | timeout value in milliseconds |
Definition at line 205 of file lin_driver.c.
status_t LIN_DRV_SendFrameData | ( | uint32_t | instance, |
const uint8_t * | txBuff, | ||
uint8_t | txSize | ||
) |
Sends frame data out through the LIN Hardware Interface using non-blocking method. This enables an a-sync method for transmitting data. Non-blocking means that the function returns immediately. The application has to get the transmit status to know when the transmit is complete. This function will calculate the checksum byte and send it with the frame data. The function will return immediately after calling this function. If txSize is equal to 0 or greater than 8 or node's current state is in SLEEP mode then the function will return STATUS_ERROR. If isBusBusy is currently true then the function will return LIN_BUS_BUSY.
instance | LIN Hardware Interface instance number |
txBuff | source buffer containing 8-bit data chars to send |
txSize | the number of bytes to send |
Definition at line 153 of file lin_driver.c.
status_t LIN_DRV_SendFrameDataBlocking | ( | uint32_t | instance, |
const uint8_t * | txBuff, | ||
uint8_t | txSize, | ||
uint32_t | timeoutMSec | ||
) |
Sends Frame data out through the LIN Hardware Interface using blocking method. This function will calculate the checksum byte and send it with the frame data. Blocking means that the function does not return until the transmission is complete. This function checks if txSize is in range from 1 to 8. If not, it will return STATUS_ERROR. This function also returns STATUS_ERROR if node's current state is in SLEEP mode. This function checks if the isBusBusy is false, if not it will return LIN_BUS_BUSY. The function does not return until the transmission is complete. If the transmission is successful, it will return STATUS_SUCCESS. If not, it will return STATUS_TIMEOUT.
instance | LIN Hardware Interface instance number |
txBuff | source buffer containing 8-bit data chars to send |
txSize | the number of bytes to send |
timeoutMSec | timeout value in milliseconds |
Definition at line 128 of file lin_driver.c.
status_t LIN_DRV_SendWakeupSignal | ( | uint32_t | instance | ) |
Sends a wakeup signal through the LIN Hardware Interface.
instance | LIN Hardware Interface instance number |
Definition at line 336 of file lin_driver.c.
void LIN_DRV_SetTimeoutCounter | ( | uint32_t | instance, |
uint32_t | timeoutValue | ||
) |
Set Value for Timeout Counter that is used in LIN_DRV_TimeoutService.
instance | LIN Hardware Interface instance number |
timeoutValue | Timeout Value to be set |
Definition at line 389 of file lin_driver.c.
void LIN_DRV_TimeoutService | ( | uint32_t | instance | ) |
Callback function for Timer Interrupt Handler Users may use (optional, not required) LIN_DRV_TimeoutService to check if timeout has occurred during non-blocking frame data transmission and reception. User may initialize a timer (for example FTM) in Output Compare Mode with period of 500 micro seconds (recommended). In timer IRQ handler, call this function.
instance | LIN Hardware Interface instance number |
Definition at line 374 of file lin_driver.c.