4.15. LIN¶
4.15.1. About This Document¶
Document Title |
User Guide of MCAL LIN Driver |
Document Version |
Version 1.1 |
Company |
Texas Instruments |
Document Name |
LIN User Guide |
4.15.2. Revision History¶
Version # |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
07-Sep-2023 |
Initial Release. |
Approved |
Version 1.1 |
15-Feb-2024 |
Updated Description of Non Standard API’s |
Approved |
4.15.3. Table of contents¶
4.15.4. Acronyms and Definitions¶
Acronyms and Definitions Used are presented in below table.
Acronyms |
Descriptions |
|---|---|
BSW |
Basic Software |
DET |
Default Error Tracer |
EcuM |
ECU Manager |
LIN |
Local Interconnect Network |
MCU |
Micro Controller Unit |
OS |
Operating System |
4.15.5. Functional Overview¶
4.15.5.1. Brief Overview¶
This document describes the functionality, API and configuration of the AUTOSAR BSW module LIN.
Supported AUTOSAR Release |
4.3.1 |
Supported Configuration Variants |
Pre-Compile, Post-build |
Vendor ID |
LIN_VENDOR_ID (44) |
Module ID |
LIN_MODULE_ID (82) |
Supported Platform |
AM263x |
The LIN module initializes and controls the Lin peripheral. It provides services to send, receive data, sleep and wakeup of the Lin peripheral.
4.15.5.1.1. Initialization¶
Lin_Init () must be called to initialize the LIN driver at power on and sets controller independent init values. This will also set the Lin controllers to IDLE state.
4.15.5.1.2. States¶
Refer Chapter 7.3.3 State Diagrams in [2] for more details.
4.15.5.2. Supported and Not Supported Features¶
IP Supported Features |
AUTOSAR Supported Features |
Not Supported Features |
|---|---|---|
Compatibility with LIN 1.3 protocols |
Conformance to LIN 2.1 protocol; operation in Master Mode only. |
Abort of ongoing transmission |
Configurable baud rate up to 20 kpbs |
Support of upto 5 Lin Channels |
Automatic transmission of Goto Sleep command |
Two external pins: LINRX and LINTX. |
Sleep / wakeup functionality |
|
Multibuffered receive and transmit units |
Enhanced and Classic checksum model |
|
Identification masks for message filtering |
Transmission / Reception of upto 8 bytes of Data |
|
Automatic commander header generation |
PDU Directions supported : LIN_MASTER_RESPONSE, LIN_SLAVE_RESPONSE, LIN_SLAVE_TO_SLAVE |
|
Wake up on LINRX dominant level from transceiver |
Use of EcuM wakeup source |
|
Automatic wake up support |
Use of Det for reporting of development errors |
|
Error detection |
||
2 interrupt lines with priority encoding |
||
Support for LIN 2.0 checksum |
||
Enhanced baud rate generator |
4.15.5.3. Assumptions¶
Only one LIN channel of an ECU is allowed to connect to a particular LIN cluster.
4.15.5.4. Limitations¶
Abort of current ongoing transmission [SWS_Lin_00021].
Automatic transmission of Goto Sleep command [SWS_Lin_00089].
4.15.5.5. Design overview¶
Please refer SITARA MCU MCAL Architecture Document and AM26x MCAL: LIN Detailed Design Document provided as part of CSP.
4.15.5.6. File Structure¶
Static source C Files are defined below in the table.
Static source C Files |
Description |
|---|---|
Lin.c |
Contains interface for Lin Drv functions |
Lin_Irq.c |
Contains Interrupt Service Routines for Lin Drv |
Lin.h |
Contains interface header for Lin Drv functions |
Lin_Priv.c |
Contains controller dependent local functions and private functions to be used in Lin.c |
Lin_Priv.h |
Contains interface header for Lin private functions |
cslr_lin.h |
Contains Register definitions required for accessing Lin peripherals. |
Plugin files are defined below in the table.
Plugin Files |
Descriptions |
|---|---|
Lin_Cfg.h |
Contains the Precompile switches, Macros for LIN channels etc. |
Lin_PBcfg.c |
Contains all channels Post-Build Configuration parameters |
Lin_Cfg.c |
Contains all channels Pre-Compile Configuration parameters |
The below diagram shows the files structure for the LIN driver.
Fig1: Lin header file include structure
4.15.6. Deviations to requirements (Requirement Traceability)¶
4.15.6.1. Module Requirements¶
Please refer Software Product Specification document provided as part of CSP.
4.15.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.15.7. Integration Details¶
4.15.7.1. Dependency on Other Software Modules¶
4.15.7.1.1. MCU¶
The hardware of the internal LIN hardware unit depends on the system clock, prescaler(s) and PLL. Hence, the length of the LIN bit timing depends on the clock settings made in module MCU. The LIN driver module will not take care of setting the registers that configure the clock, prescaler(s) and PLL (e.g. switching on/off the PLL) in its init functions. The MCU module must do this.
4.15.7.1.2. Port¶
The Port driver configures the port pins used for the LIN driver as input or output. Hence, the Port driver has to be initialized prior to the use of LIN functions. Otherwise, LIN driver functions will exhibit undefined behavior.
4.15.7.1.3. OS¶
The LIN driver uses interrupts and therefore there is a dependency on the OS, which configures the interrupt sources.
4.15.7.1.4. LIN Driver Users¶
The LIN Interface is the only user of the LIN driver services.
4.15.7.1.5. Error Handling module¶
4.15.7.1.5.1. DET¶
In development mode, the Lin module reports development error through the Det_ReportError function of module DET.
AUTOSAR requires that API functions shall check the validity of their respective parameters. These checks are for development error reporting and can be enabled or disabled.
Relevance |
Related Error Code |
Value |
|
|---|---|---|---|
API service used without module initialization |
Development |
LIN_E_UNINIT |
0x00 |
API service used with an invalid or inactive channel parameter |
Development |
LIN_E_INVALID_CHANNEL |
0x02 |
API service called with invalid configuration pointer |
Development |
LIN_E_INVALID_POINTER |
0x03 |
Invalid state transition for the current state |
Development |
LIN_E_STATE_TRANSITION |
0x04 |
API service called with a NULL pointer |
Development |
LIN_E_PARAM_POINTER |
0x05 |
4.15.7.1.5.2. Runtime Errors¶
None
4.15.7.1.6. Callback Notification¶
None
4.15.7.2. Hardware - Software - ISR API name mapping¶
Lin driver provides ISR for wakeup detection. The interrupt vector lines to be used is configurable in Lin driver. The interrupt category must be configured in Lin Driver and OS modules. The ISR’s are implemented in the file Lin_Irq.c.
Respective ISRs for each Lin Instances in AM263x are as follows:
Lin Instances |
ISR Routines |
|---|---|
LIN0 Wakeup Line 0 (IE0) |
Lin_0_Int0ISR() |
LIN0 Wakeup Line 1 (IE1) |
Lin_0_Int1ISR() |
LIN1 Wakeup Line 0 (IE0) |
Lin_1_Int0ISR() |
LIN1 Wakeup Line 1 (IE1) |
Lin_1_Int1ISR() |
LIN2 Wakeup Line 0 (IE0) |
Lin_2_Int0ISR() |
LIN2 Wakeup Line 1 (IE1) |
Lin_2_Int1ISR() |
LIN3 Wakeup Line 0 (IE0) |
Lin_3_Int0ISR() |
LIN3 Wakeup Line 1 (IE1) |
Lin_3_Int1ISR() |
LIN4 Wakeup Line 0 (IE0) |
Lin_4_Int0ISR() |
LIN4 Wakeup Line 1 (IE1) |
Lin_4_Int1ISR() |
Lin_0_Int0ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 0 for the LIN0 controller.
Lin_0_Int1ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 1 for the LIN0 controller.
Lin_1_Int0ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 0 for the LIN1 controller.
Lin_1_Int1ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 1 for the LIN1 controller.
Lin_2_Int0ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 0 for the LIN2 controller.
Lin_2_Int1ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 1 for the LIN2 controller.
Lin_3_Int0ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 0 for the LIN3 controller.
Lin_3_Int1ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 1 for the LIN3 controller.
Lin_4_Int0ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 0 for the LIN4 controller.
Lin_4_Int1ISR For AM263x device, this ISR is called on detection of wakeup event on interrupt line 1 for the LIN4 controller.
4.15.7.3. Scheduling Strategy¶
4.15.7.3.1. SchM¶
Beside the OS the BSW Scheduler provides functions that module LIN calls at begin and end of critical sections.
4.15.7.3.2. Critical Sections¶
There is only one critical section in this driver. Within these sections all read/ modify/ write accesses to internal Lin status variables must be protected. Therefore, switching to tasks that also access LIN must be avoided and all LIN interrupts must be suspended. This is managed internally by Lin Driver.
4.15.8. API Description¶
4.15.8.1. Description of the API’s¶
Please refer MCAL_AM263_ApiGuide.CHM document provided as part of CSP.
4.15.8.2. API’s with Service ID¶
The following table presents the service IDs and the related services:
Service ID |
Service |
|---|---|
0x00 |
Lin_Init |
0x01 |
Lin_GetVersionInfo |
0x04 |
Lin_SendFrame |
0x06 |
Lin_GoToSleep |
0x07 |
Lin_Wakeup |
0x08 |
Lin_GetStatus |
0x09 |
Lin_GoToSleepInternal |
0x0a |
Lin_CheckWakeup |
0x0b |
Lin_WakeupInternal |
4.15.8.3. Description on Non Standard API’s¶
Lin_RegisterReadback API
This function is Non- Autosar based and is used to read the data in the registers of LIN.
This functionality is enabled, if parameter LinEnableRegisterReadbackApi is TRUE (The Parameter sets LIN_REGISTER_READBACK_API Macro as STD_ON ).
Service Id is 0x0C.
4.15.9. Configuration Description¶
4.15.9.1. Configuration Variants¶
The LIN is configured through GUI in Post-Build and Pre-Compile Variants.
Variants |
Configured Files |
|---|---|
PostBuild |
Lin_PBcfg.c , Lin_Cfg.h |
Pre-Compile |
Lin_Cfg.c , Lin_Cfg.h |
4.15.9.2. Parameter Description¶
4.15.9.2.1. Standard Configuration¶
Will be updated in future release
4.15.9.2.2. IP Specific Configuration¶
Will be updated in future release
4.15.9.3. Symbolic Names deviations¶
None
4.15.9.4. Configuration rules and constraints to enable plausibility checks¶
None
4.15.10. Memory Mapping¶
Memory Mapping Sections |
LIN_CODE |
LIN_CODE_ISR |
LIN_VAR_NO_INIT |
LIN_VAR |
LIN_CONST |
LIN_PBCFG |
|---|---|---|---|---|---|---|
LIN_START_SEC_VAR_INIT_UNSPECIFIED(.bss) |
x |
|||||
LIN_STOP_SEC_VAR_INIT_UNSPECIFIED |
x |
|||||
LIN_START_SEC_CONFIG_DATA (.const) |
x |
|||||
LIN_STOP_SEC_CONFIG_DATA |
x |
|||||
LIN_START_SEC_CODE(.text) |
x |
|||||
LIN_STOP_SEC_CODE |
x |
|||||
LIN_START_SEC_VAR_INIT_32(.bss) |
x |
|||||
LIN_STOP_SEC_VAR_INIT_32 |
x |
|||||
LIN_START_SEC_VAR_NO_INIT_UNSPECIFIED(.data) |
x |
|||||
LIN_STOP_SEC_VAR_NO_INIT_UNSPECIFIED |
x |
|||||
LIN_START_SEC_ISR_CODE |
x |
|||||
LIN_STOP_SEC_ISR_CODE |
x |
4.15.11. Memory footprint¶
Please refer Memory Footprint for more details.
4.15.12. Performance¶
Will be updated in future release
4.15.13. Example Usage¶
4.15.13.1. Steps to build and run example¶
LIN example application demonstrating the MCAL LIN driver features is in folder <MCAL_ROOT>/examples/Lin.
This application can be built from the build folder by giving “gmake –s lin_app PLATFORM=am263.”
Once the build is completed we get a binary file, which is loaded in our controller and executed.
4.15.13.2. Document external set up Information¶
Locate SW9 on the board and set it to ON.
Locate the LIN, LIN-GND and VBat-LIN pins on both the PLIN device and the board. Refer to the documentation or user manual for both the PLIN device and the board to find the correct pins.
Select appropriate cables with the necessary connectors to connect between the PLIN device and the board. Ensure the cables have the correct connectors to fit securely into both the PCAN device and board’s connectors.
Fig2: LIN Hardware Connectivity with PLIN USB
Open the PLIN configuration software on your PC. The software is usually provided by the manufacturer of the PLIN device.
Locate the settings for baud rate configuration.
Set the baud rate to 19200 and select mode as Slave.
Apply the changes and save the configuration.
Ensure all connections are secure and properly plugged into their respective connectors on both the PLIN device and the board.
Before powering on the system, double-check all connections to ensure they are correctly made, and there are no loose or improperly connected cables.
After making the connections and configuring the PLIN device, power on both the board and the PLIN device.
Once the system is powered on, verify that the LIN communication is established between the board and the PLIN device.
If Slave to Slave mode example needs to be run; we would need 2 PLIN channels to be connected to the same LIN bus.
Reference PLIN configs are placed at path (mcal/examples/Lin/Peak_PLIN_Config); these can be loaded for ease of use.
4.15.13.3. Flow of the example application¶
For AM263x “PROC110E2A” board:
LIN1 pins are exposed and LIN1 is configured with a 19200 baud.
While running the example code :
First, it asks to select the example to run.
For Master Response example 8 Lin Frames are transmitted with varying PIDs, length and data.
For Slave Response example LIN1 will transmit header with PID (0x20h) and slave will respond with data. Received data will be printed on screen and user can confirm if the data is correct.
For Slave to Slave example LIN1 will transmit header with PID (0x30h); then one of the slaves will send response with data which should be recived by the other slave connected on same cluster. User can confirm if the second slave receives the data.
User can also select ‘a’ in console to run all examples sequentially.
4.15.13.4. Configuration used to test this example¶
LIN1 instance is configured as Channel_1.
Baudrate of 19200 is configured.
4.15.13.5. Example Logs¶
AM263x
LIN_APP: Sample Application - STARTS !!!
LIN_APP: LIN MCAL Version Info
---------------------
LIN_APP: Vendor ID: 44
LIN_APP: Module ID: 124
LIN_APP: SW Major Version: 9
LIN_APP: SW Minor Version: 0
LIN_APP: SW Patch Version: 1
LIN_APP: Variant - Post Build being used !!!
LIN_APP: Using LinChannel_1 -> LIN_INSTANCE_1
LIN_APP: Waking LinChannel_1 from sleep
LIN_APP: LinChannel_1 Wakeup Successful
LIN_APP: Enter one of the following
LIN_APP: m - Send Master Response Lin Request
LIN_APP: s - Send Slave Response Lin Request
LIN_APP: x - Send Slave to Slave Lin Request
LIN_APP: a - Send all types Lin Request
LIN_APP: q - to quit the application
LIN_APP: LinChannel_1 operating in Master Response mode
LIN_APP: LinChannel_1 Transmission successful for 0 data frame
LIN_APP: LinChannel_1 Transmission successful for 1 data frame
LIN_APP: LinChannel_1 Transmission successful for 2 data frame
LIN_APP: LinChannel_1 Transmission successful for 3 data frame
LIN_APP: LinChannel_1 Transmission successful for 4 data frame
LIN_APP: LinChannel_1 Transmission successful for 5 data frame
LIN_APP: LinChannel_1 Transmission successful for 6 data frame
LIN_APP: LinChannel_1 Transmission successful for 7 data frame
LIN_APP: LinChannel_1 operating in Slave Response mode
LIN_APP: Received Data : 0xa5 0x55 0xaa 0x55 0xaa 0x55 0xaa 0x55
LIN_APP: Does the data received match the data sent by the Slave? (y/n)
LIN_APP: LinChannel_1 Reception successful
LIN_APP: LinChannel_1 operating in Slave to Slave mode
LIN_APP: Did Slave to Slave communication happen? (y/n)
LIN_APP: LinChannel_1 Slave to Slave communication successful
LIN_APP: Enter one of the following
LIN_APP: m - Send Master Response Lin Request
LIN_APP: s - Send Slave Response Lin Request
LIN_APP: x - Send Slave to Slave Lin Request
LIN_APP: a - Send all types Lin Request
LIN_APP: q - to quit the application
LIN_APP:All sample test case pass
4.15.14. FAQ’s¶
None
4.15.15. Test Report¶
Please refer AM26x LIN Driver Test Case Report provided as part of CSP.
4.15.16. References¶
4.15.17. TI Disclaimer¶
Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.
TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.
Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.
TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm
Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265