Home

STM-STM8-STM8AF51A9-Learning Centre MCU-User

Contents

1. lt lt 80 Document revision history lt e mr 82 Doc ID 17460 Rev 1 ky UM0941 List of figures List of figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Figure 10 Master slave node communications 2 4 44 re 9 successful configuration request and response cece eee eee 24 Lingen workflow eo erria 00 RR IH He e Rr 43 Interleaving of a diagnostic master request schedule table 53 Interleaving of a diagnostic slave response schedule table 54 No diagnostic communication lt m rn 55 Diagnostic Interleaved mode 0 ce re 56 Continued execution of diagnostic slave response schedule table until response received lt tiy ia i ienesa EE aatia 57 Diagnostic only Mode sirsenis rsrsisess kudt tees 58 Default schedule in the Diagnostic Only mode 2 61 Doc ID 17460 Rev 1 7 83 Abbreviations UM0941 1 2 1 2 2 8 83 Abbreviations Table 1 Description of abbreviated forms Abbreviation Description API Application Programming Interface CAN Controller Area Network LDF LIN description LIN Local Interconnect Network RSID Response Service Identifier SID Service Identifier Overview LIN concept LIN local interconnect network is a concept that has been developed by a group of well known car manufactu
2. K K A k k A A k k A k k A k k A A a a RR RR RRR KK KR RR RR kk undef LIN FORCE STANDALONE BREAK Additionally a longer break signal is required for drivers in a Cooling v2 1 network and so the standard 13 bit break signal can be lengthened to 36 bits for a 19200 baud rate network or 18 bits in a 9600 baud rate network or equivalent The Cooling feature must be activated before being used BORK RRR RK KK KK KK KR kk kk RR k k RR RR RR RK KR KK KK KR RRR RK Activate the Cooling option with define LIN USE COOLING Deactivate it with undef LIN USE COOLING HK KK RR KR RR RR RR RR KKK RR RRR Re define LIN USE COOLING and the break length set ifdef LIN_USE_COOLING 3 Doc ID 17460 Rev 1 UM0941 Driver configuration 4 BRR KK KK KK KK KK KK ke ke RR RR RK KKK KKK RRR kk length of the break signal in bit times nr of bits Please adjust LIN FRAME TIME MULTIPLIER if necessary KK KK RK KR RR RK KK KK RRR ke x define LIN COOLING BREAK DURATION BITS 36 dendif Activating the Cooling feature provides the user with an additional interface function l ifc set cooling break that can be called from the application when a longer break is required This interface function can be used to toggle the length of the break between the configured cooling break length and the configured normal break length as required Configuring LIN node startup behavior The startup behavior of LIN nodes
3. LD_QUEUE_FULL transmit queue is full and cannot accept further frames LD QUEUE EMPTY transmit queue is empty i e all frames in the queue have been transmitted LD QUEUE AVAILABLE transmit queue contains entries but is not full and is consequently ready to receive additional frames for transmission LD TRANSMIT ERROR LIN protocol errors occurred during transfer Reinitialize and redo the transmission Table 33 Query raw receive queue status Id raw rx status Prototype l u8 ld raw rx status 1 ifc handle ifc Availability Master and slave nodes Include lin h Description This function returns the status of the raw frame receive gueue see LIN 2 1 section 7 4 3 4 Parameters ifc interface handle Return value LD DATA AVAILABLE receive gueue contains data that can be read LD NO DATA receive gueue is empty LD RECEIVE ERROR LIN protocol errors occurred during transfer Reinitialize and redo the transmission 30 83 3 Doc ID 17460 Rev 1 UM0941 API 3 4 5 Table 34 Diagnostic Transport Layer COOKED API Send message Prototype Id send message void ld send message l u8 const pData 1 ifc handle ifc 1 u16 length 1 u8 nad const Availability Master and slave nodes Include lin h Description This function packs the information given by data and length into one or more diagnostic frames and sends them If this function is called from
4. 2 4 4444 32 Schedule tick issia ona aa a Eaa ehh 33 Set schedule table 0 0 00 ccc teas 33 Goto Sleep cog Shei ad Raia ob ues acd cheba ee wees Bia Cees 34 Slave synchronize ius nar da n aod RE usw a YE WIR EX RR AERE Parker ene 35 Read by ID callout 00 RR III I 3 er 35 Software Timer function lt 36 Protocol Eire 36 Data Dump iac de e e uy bo aed Gawd Pade PR Rare Duabus Papers 36 Set Cooling Break l l 37 Set baud rate secco dee pera ato pras edu utor dU wie o Bb qe E d 37 Raw Tx delete sess see lm hdek aen whe Ree k cae nega e REOR TR UR RR a 37 Doc ID 17460 Rev 1 5 83 List of tables UM0941 Table 49 Table 50 Table 51 Table 52 Table 53 Table 54 Table 55 Table 56 Table 57 Table 58 Table 59 Table 60 Table 61 Table 62 Table 63 6 83 Directory Structure eee 39 Top level makefile predefined variable definition llle 40 op MEER TT 44 Disable Interrupts 0 0 0c m Dph 61 Restore Interrupts oeer eirda neie a e a a a a E EA A 61 Protocol switch function callback lt 62 Id read by id callback ee tenets 63 ld data dump callback ee RR RI I AES 63 Baud rate detection callback cect ere 64 Handler for character rx 2 eee eee 64 Handler for character tx 2 0 0 ee tees 65 Syntax description lt 67 Hardware timer configuration lt Rr 79 Hardware timer interrupt service routine
5. Prototype static l u8 1 sch tick iii void where iii denotes the interface for which transmission of frames is to be initiated e g for the configured interface SCIO then the prototype u8 1 sch tick SCIO void Table 39 Set schedule table I sch set Prototype void 1 sch set 1 ifc handle ifc 1 schedule handle schedule iii dynamic l u8 entry Availability Master node only Include lin h Doc ID 17460 Rev 1 33 83 API UM0941 Table 39 Set schedule table continued sch set This function sets up the next schedule to be followed by the 1 sch tick function for the given interface The entry given specifies the starting point in the new schedule see LIN 2 1 section 7 2 4 2 The interface is optional It can be used to solve naming conflicts when the node is a master on more than one LIN cluster Pepo The entry specified must lie in the range of 0 to n for a table with n entries Values of 0 or 1 specify the beginning of the schedule table This function can also be used to set the next frame to be transmitted in the current schedule A predefined schedule table L NULL SCHEDULE must exist and can be used to stop all transfers on the LIN cluster ifc interface handle Parameters schedule iii new schedule handle for the interface ifc entry entry point in the new schedule Return value None Prototype static void 1 sch set iii 1 schedule
6. lingen control file defining two interfaces Interfaces SCIO home LIN src lin config lin sciO ldf IFCO SCI1 home LIN src lin config lin scil ldf IFC1 The interface entries consist of three parts the interface name the corresponding LDF file and an optional tag field The location of the LDF file should be completely specified by giving the absolute path The tag entry is concatenated with all frame names and signal names when the lingen tool processes the LDF files As an example a signal name s1_sig1 in the LDF file in_sci0 ldf listed above will appear in the code as LIN SIGNAL IFCO sl sig For the master node the tag field must be used to resolve naming conflicts when two LDF files have common signal names The number of interfaces that can be listed in the control file and their names depend on the hardware The tag names can be freely chosen by the user Slave node A slave node only supports one interface and therefore only one LDF file is required for a slave The lingen control file then specifies this interface and the name of the corresponding LDF file In addition to this interface definition the user can also define default frame Doc ID 17460 Rev 1 41 83 Driver configuration UM0941 42 83 identifiers in the slave lingen control file In this case the default values given in the LDF file will be used for all slave frames This means that the slave nodes can start commun
7. 58 83 Doc ID 17460 Rev 1 ky UM0941 Driver configuration BOR KK KK KK RK KK KK RR RR RR RR KK KK KR KR kk kk choose Diagnostic Class mandatory for LIN 2 1 slave node LIN 2 1 slave nodes must have a Diagnostic Class value defined This value can be 1 2 or 3 other values will involve in an error HK KKK KK A A KR RRR RR k k k k k k k k k ek DIAGNOSTIC CLASS 1 Only the node configuration services are supported The slave does not support any other diagnostic services Single frames SF transport protocol support is sufficient Node Identification is limited to the mandatory read by identifier service DIAGNOSTIC CLASS 2 Node configuration and identification services are supported Full transport layer implementation is reguired to support multi frame transmissions Node Identification is extended to all the Read By Id services Slave nodes will support a set of ISO 14229 1 diagnostic services like Node identification SID 0x22 Reading data parameter SID 0x22 if applicable Writing parameters SID 0x2E if applicable DIAGNOSTIC CLASS 3 Node configuration and identification services are supported Full transport layer implementation is reguired to support multi frame transmissions Node Identification is extended to all the Read By Id services Slave nodes shall support all services as of Class II Additionally other services may be supported depending on the features which a
8. N UM0941 J User manual STMicroelectronics LIN 2 1 driver June 2010 Introduction Purpose This user manual provides application programmers with detailed information on how to use STMicroelectronics LIN 2 1 driver for master and slave nodes It gives a detailed description of the API implemented together with some examples of important files required for getting started and configuring the driver It then explains how to configure the LIN 2 1 driver to operate with STM8 microcontrollers Scope STMicroelectronics implementation is compliant with the LIN API specification rev 2 1 User profile The users should be familiar with the concept of networks and in particular LIN networks As STMicroelectronics LIN 2 1 driver is written in C programming language they should be experienced in the development of C applications References e LIN specification package revision 2 0 23 September 2003 e LIN specification package revision 2 1 24 November 2006 Doc ID 17460 Rev 1 1 83 www st com Contents UM0941 Contents 1 Abbreviations sea s neni eo aerae dia Lao dar arm mac 8 2 OVGFVIGW cic rd dv cae deca dn rok n dohad cy nde ud 8 2 1 LIN CONCEDE 422s invented soka a ERR AEMEEREEGE 8 2 2 LIN communications PR 8 23 Signal management 2 2 2 lt cscssepessanexaaes caseee vanes vawese 10 2 4 Using THE GIVE uso aee REIR nios Reb Roa e Ro d ee bd 10 2 5 Driver VGISION 1265484 Pepe i ia a hrs Pda ib re SS Edu Rad 11 3
9. undef LIN INCLUDE ASSIGN FRAME ID BORK KK KK KK kk kk kk RR RR RR RK KK KK RR kk kk kok service Assign NAD optional for LIN 2 x HK KK KK RR RR RR RK RRR ee define LIN INCLUDE ASSIGN NAD The Assign NAD service is optional It is enabled since it is called in the Initialization table of the demo present in the LDF file of the LIN package and is required to configure slave nodes BORK KK KK KK kk ke kk ke RR RR KK KK KK KR kk kok service Read By Id mandatory for LIN 2 x Doc ID 17460 Rev 1 49 83 Driver configuration UM0941 4 4 4 50 83 HK KK KK KK RK KR kikki k k RR ee define LIN INCLUDE READ BY ID BORK KK KK KK kk KK kk kk RR RR RK RK KK RR kk service Conditional Change NAD optional for LIN 2 x HK KKK KK KK A KR RR RR RK KK KR a k k undef LIN INCLUDE COND CHANGE NAD BORK KK KK KK KKK ke kk kk RR RR RR RR KK KR KR kk kk kk service Data Dump optional for LIN 2 x Note The standard strongly discourages use of this service in operational LIN clusters HK KK KK KR a A RR RR ROK RRR Re k ek undef LIN INCLUDE DATA DUMP BORK KKK KK KK kk kk RR RRR KKK RK KR kk kk choose Serial Number optional for Slave node Slave node may have a serial number to identify a specific instance of a slave node product The serial number is 4 bytes long KK KK KK KK KR RR ROR RRR I k k k k define SERIAL NUMBER OxFFFF The Save Configuration and Assign Frame Id
10. 1 bytes wr 1 signal handle signalId l u8 start l u8 count dynamic const 1 8 const data Availability Master and slave nodes Include lin h This function sets the current value of the selected bytes in the specified signal to the values Description given in data see LIN 2 1 section 7 2 2 5 The sum of start and count must never be greater than the length of the byte array signalId the signal to be written e g for the configured signal user data then LIN SIGNAL user data Parameters start the first byte to be written count the number of bytes to be written data the area where the bytes will be read from Return value None Prototype static 14 83 void l bytes wr sss 1 u8 start 1 u8 count const 1l u8 const data where sss denotes the name of the signal to be written e g for the configured signal user data then the prototype void l bytes wr user data l u8 start l u8 count const 1l u8 const data 3 Doc ID 17460 Rev 1 UM0941 API 3 3 3 Notification Table 8 Test flag flg tst Prototype l bool 1 flg tst 1 flag handle f1ag dynamic E dibus Availability Master and slave nodes Include lin h Description This function returns the state of the flag specified i e zero if cleared non zero otherwise see P LIN 2 1 section 7 2 3 1 flag the flag which state is to be returned e g for the configured flag Txerror then Parameters LIN FLAG Txerror Re
11. 3 4 msecs AK KK KK A RR RRR KR KK RR ee k k ifndef LIN 13 define LIN BUSSLEEP TIMEOUT VAL IFC 1 ul6 4000 define LIN WAKEUP TIMEOUT VAL SHORT IFC 1 u16 150 define LIN WAKEUP TIMEOUT VAL LONG IFC 1 u16 1500 endif The maximum number of attempts can also be configured BOR KR KKK KK KKK ke kk ke RR RR RR RR RK RR RR kk kk The number of wakeup retries to send If after a wakeup signal from the slave the master does not start to send frame headers the slave may retry to send the wakeup signal The define gives the maximum number of retries HK KK KK a RR RRR KR RRR ke ex define LIN WAKEUP RETRIES MAX 3 Setting this value to zero means that the driver does not stop sending wakeup signals when there is no response from the master Diagnostic functions configuration The diagnostic module functions can be individually selected as described below The driver default settings reflect the standard requirements The following definitions are used for this purpose BOR KK KK KK KR kk kk kk ke k e k kc kckckckckckckckckckckckckckckckckck RRR kk kk kk Configuration features Select by define ing Default values match the mandatory services defined by the standard HK KK KK KK RR RK RR KR RR ee BORK KK KK KK KK ke kk RR RR RR ROKK RRR kk kk service Assign Frame Id mandatory for LIN 2 0 obsolete for LIN 2 1 FI IOI IO IO IO I ke ko IOI IO IO IO IO IO IOI IO IO IO eee Y
12. Master and slave nodes Include lin h This function gueues a raw diagnostic frame for transmission see LIN 2 1 section 7 4 3 1 Description The data area is copied in the call and the pointer is not memorized Note The application should check 1d raw tx status before attempting to queue a frame If no space is available the frame data is discarded ifc interface handle Parameters pData pointer to the data to be queued Return value None Table 31 Get raw frame Id get raw Prototype void ld get raw 1 ifc handle ifc 1 u8 const pData Availability Master and slave nodes Include lin h This function copies the oldest frame on the receive stack to the provided buffer see LIN 2 1 section 7 4 3 2 Description ld raw rx status should be checked first as the Id get raw function does not report whether a frame has been copied or not No data are copied if the receive queue is empty ifc interface handle Parameters pData pointer to the buffer into which the frame will be copied Return value None 4 Doc ID 17460 Rev 1 29 83 API UM0941 Table 32 Query raw transmit gueue status Id raw tx status Prototype l u8 ld raw tx status 1 ifc handle ifc Availability Master and slave nodes Include lin h Description This function returns the status of the raw frame transmission gueue see LIN 2 1 section 7 4 3 3 Parameters ifc interface handle Return value
13. Py Master node supporting either Interleaved diagnostics or Diagnostics only mode Upon request from an external diagnostic test tool the master node can operate each of its connected LIN clusters either in Interleaved Diagnostics Interleaved mode or in Diagnostics only mode see Figure 5 e Diagnostics Interleaved mode This is the master node default mode Before executing diagnostic schedules the master node completed the ongoing normal communication schedules see Figure 4 and Figure 5 After executing of a diagnostic schedule the master node runs a normal communication schedule before executing the new diagnostic schedule see Figure 7 In Diagnostics Interleaved mode the master application ensures via normal communication schedule design that the time between two subsequent diagnostic schedules complies with the OEM specific diagnostic requirements Doc ID 17460 Rev 1 55 83 Driver configuration UM0941 Figure 7 Diagnostic Interleaved mode Active schedule table Normal communication schedule Diagnostic master reguest schedule Normal communication schedule Diagnostic slave response schedule i IIIJ The number of executions of the diagnostic master request schedule table depends on the amount of data that needs to be transmitted It is determined by the master node in compliance with the LIN transport protocol As an example the schedule must be executed twice to transmit 10
14. Range services are valid only for LIN 2 1 ifdef LIN 21 J E OR KR RR RR RK KK KK RR KR RR RR ck ckockck ck KKK KK KK KK ke RK e k service Save Configuration optional for LIN 2 1 HK KK KK KK A KR RR RR RK KK KR ek define LIN INCLUDE SAVE CONFIGURATION J E OR KK KR RRR RK KK KK KR RR RR RR kk kc kckckckck ck ck k ck ck RR RK RK KK KK KKK k KR KK service Assign Frame Id Range mandatory for LIN 2 1 HK KK KK KK KR RR RR RK KK RR ke k k define LIN INCLUDE ASSIGN FRAME ID RANGE The Save Configuration service is also optional It is enabled since it is called in the Initialization table of the demo present in the LDF file of the LIN package Diagnostic class The Diagnostic class is valid and mandatory only for LIN 2 1 slave nodes It can be used to perform the following actions e Doacrosscheck between LDF and the same class to understand if the slave node is able to perform the diagnostic Understand which diagnostic services the slave node is able to respond to Know which configuration and identification services is supported Understand if the slave node is able to support the Transport Protocol Understand if the slave node is able to be reprogrammed only class 3 3 Doc ID 17460 Rev 1 UM0941 Driver configuration BOR KK KK KK RK KK KK RR RR RR RR KK KK KR KR kk kk choose Diagnostic Class mandatory for LIN 2 1 slave node LIN 2 1 slave nodes must have a Diagnostic Class value defined This
15. SlaveOnly table in the LDF file SlaveOnly the Slave Diagnostic Interleaved Mode mandatory the default scheduled table in Diagnostic Only Mode and no active transmission from master node must be sent SlaveResp delay 20 ms e Ifthe lingen tool does not find any table complying with the mandatory requirements it does not include the LIN SLAVE ONLY define statement This will cause a compilation error since a master node must support the Interleaved Diagnostics schedule Mode which is mandatory see also Master node supporting either Interleaved diagnostics or Diagnostics only mode Figure 5 Interleaving of a diagnostic slave response schedule table Active schedule table a oy Normal communication schedule Diagnostic slave response schedule Normal communication schedule Doc ID 17460 Rev 1 ky UM0941 Driver configuration No diagnostic schedule tables executed by the master node when no diagnostic communication is active This is the master node default behavior The master application must not switch to tables such as the LIN TAB SlaveOnly or LIN TAB MasterOnly tables described in the previous examples before it receives a diagnostic request from an external tool see Figure 6 Figure 6 No diagnostic communication Active schedule table Normal communication schedule Normal communication schedule Normal communication schedule Normal communication schedule i i M y y
16. can be influenced by two settings The first option is to start the slave node bus sleep timer going when a slave node connects to the network The slave then enters sleep mode if no activity is detected Additionally a master node can be set up to send a wakeup signal when connecting to the network Note that if a slave is set up to start the bus sleep timer on connection then the master should be configured to send a wakeup If it is not the case and the master does not start transmitting within 4 seconds then the slave node enters sleep mode In this case the slave node will not be ready to receive frames as it expects to receive a wakeup signal first The following two settings can be used for this purpose BORK CK Ck KK RK kk kk kk kk RR RR RR RK RR KK RR kk kk select whether the slave node will start the bus sleep timer on connect Note The slave may lose the first frame if the master node does not start with a Wakeup signal followed by 100ms silence KK KK KR RK RR RK RRR eek define LIN START BUSSLEEP TIMER ON CONNECT BORK KK KK KK RK kk kk kk RR RR RR KK RR RR kk kk kok select whether the master node should start a wakeup sequence on connect AK KK KK KK RR RR RR KR KR ke k k define LIN SEND WAKEUP SIG ON CONNECT For a master node the initial delay is undefined when switching from LL NULL SCHEDULE to a valid schedule table after startup Use the following definition to set the initial value
17. intermediate status between the configuration request and configuration response LD SERVICE IDLE The configuration request response combination has been completed i e the response is valid and can be analyzed This value is also returned if no request has been called LD SERVICE ERROR The configuration request or response failed This means that a bus error occurred and that the slave node did not receive any negative configuration response Return value 3 Doc ID 17460 Rev 1 23 83 API UM0941 Figure 2 successful configuration request and response LD SERVICE IDLE LD SERVICE BUSY LD REQUEST FINISHED LD SERVICE IDLE Ek Master Request Frame Slave Response Frame Configuration service called Table 20 Check configuration response Id check response void ld check response 1 ifc handle ifc l u8 const pRsid 1 u8 const Prototype pErrorCode Availability Master node only Include lin h This function returns the result of the last node configuration call completed in the parameters Description pRsid and pErrorCode A value is always returned in pRsid but not always in pErrorCode Default values for pRsid and pErrorCode are 0 see LIN 2 1 section 7 3 1 2 ifc interface of the node to be checked Parameters pRsid location of the RSID returned pErrorCode location of the error code returned Return value None Table 21 Assign frame
18. k k k k k k k k length of the break signal in bit times nr of bits recommended is 13 Please adjust LIN FRAME TIME MULTIPLIER if necessary K K KKK RR RR RR RK KK RRR RRR kk define LIN BREAK DURATION BITS 13 According to the LIN 2 1 standard a slave node is able to detect a BREAK at any time The current frame processing is interrupted and the new frame is then processed A BREAK is detected by the driver through a framing error This may occur at any time during the transmission of a data byte or between transmissions of data bytes The following switch allows to decide if all framing errors should be treated as a possible BREAK or not Defining the switch will force the driver to examine the information last received over the bus Only a BREAK character that does not occur during the transmission of a data byte will be accepted as a valid BREAK BORK KKK RK KK KK KK RR ke ke kk RR k k RR RRR RR KK KK KK KK k k RRR RR k k k k k The slave driver is able to detect a new BREAK character during an ongoing frame transfer if supported by hardware This is detected through a framing error and may occur at any time If LIN FORCE STANDALONE BREAK is not defined any framing error will be considered as a possible BREAK character even if this occurs during the transmission of a data byte Otherwise a framing error will only be considered as a possible break if it occurs between transmission of data bytes
19. k k k k k k k k k k k k k k define LIN DIAGNOSTIC CLASS 1 OR OR FF F FH FF F HF KF F F OR HF KF F F F HF F F FF OF o ifdef LIN SLAVE NODE ifndef LIN DIAGNOSTIC CLASS error For a LIN 2 1 slave node LIN Diagnostic Class is mandatory and must be defined endif if LIN DIAGNOSTIC CLASS 1 LIN DIAGNOSTIC CLASS 3 error LIN 2 1 Diagnostic Class value can be 1 2 or 3 endif 4 Doc ID 17460 Rev 1 51 83 Driver configuration UM0941 4 4 5 52 83 else if defined LIN MASTER ONLY defined LIN SLAVE ONLY error A master node must support the Interleaved Diagnostics schedule Mode mandatory endif dendif endif LIN 21 BORK CK Ck KK KK kk ke kk ke kk RR RR RK KK KR RR kk LIN TP features Select by define ing TP is disabled by default HK KK KK KK RR RR RR RR RK KK RR ee k k BOR KK KK KK KK kk kk ke ke RR RR RR RR RK RR RR kk kk kok the cooked diagnostic TP KK KK KK KK KK A RR RR RR RK RK RR ek k k undef LIN INCLUDE COOKED TP BOR KK KKK KK kk KK RR RR KR RR RRR RK KKK KR kk kok the raw diagnostic TP ARK KK KK KK A KR RR RR RK RRR undef LIN INCLUDE RAW TP For the Raw TP the size of the Rx and Tx FIFO stack can be configured using the definition BRK Ck Ck KK KK kk kk ke kk RR RR RR RK KK RR kk kok define the stack size of the raw tp fifo stacks in numbers of frames AK KK KKK RR RR RK KKK
20. kk ke A kc kckckckckckckckckckckckckckckckckckck ck k k k k k k A k k k k k k k k k k RK Activate the use of a hardware timer for LIN via define LIN USE HARDWARE TIMER Deactivate the use of a hardware timer for LIN via undef LIN USE HARDWARE TIMER HK KKK KK KK KR RR RR KK KR ee define LIN USE HARDWARE TIMER Doc ID 17460 Rev 1 ky UM0941 Architecture notes Note STMB8 microcontrollers only support an 8 bit system timer TIM4 it is referred to as 1 The timer must be configured as follows ifdef LIN USE HARDWARE TIMER BORK Ck Ck KR KKK KK KK kk ke k kk kk kc kckckckckckckckckckckckckckck ck RK KK k k RRR RR RR kk kk choose the timer used by the LIN driver valid values depend on the architecture used kkxkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkxk define LIN TIMER 1 endif Note that the driver is delivered with the hardware timer configured as default timer in lin def stm8 h define LIN USE HARDWARE TIMER When the hardware timer is used its prescaler and reload values must be configured For the 4 most common configurations these values are already given in the lin stm8 h file see Table 61 Table 61 Hardware timer configuration GPU Time base Prescaler Reload frequency Note Hz ms value value 16 000 000 2 7 250 16 MHz 27 250 gt 2 ms timebase 8 000 000 2 7 125 16 MHz 27 125 gt 2 ms timebase 16 000 0
21. master and or to other slave nodes As a result communications are possible from slave to slave without routing through the master and the master can broadcast to all slaves belonging to the LIN subsystem The order in which frames are sent is determined by a schedule table used by the master Several tables may be configured but only one table can be active at a time Switching between tables can be carried out either by the application or internally by the driver The schedule tables required by an application must be configured by the user in the LIN description file Master slave node communications master node slave node signals frames LIN API LIN API operating system i operating system Doc ID 17460 Rev 1 9 83 Overview UM0941 2 3 2 4 Note 10 83 Signal management Signals are transferred in the frame data bytes Several signals can be packed into a frame as long as they do not overlap each other or extend beyond the data area of the frame Each signal has only one producer This means that it is always written by the same node in a given cluster Each signal that is issued by a node must be configured by the user A signal is described either by a scalar value or by a byte array e Scalar signal ranging between 1 and 16 bits A 1 bit signal is called a boolean signal 2 bit to 16 bit scalar signals are treated as unsigned values e A byte array ranging from 1 to 8 byt
22. memory page 0 is unlikely to work since the space required to store these variables probably exceeds the available space A master node using multiple interfaces can only be compiled using the physical stack option If the driver has been configured to support the conditional change NAD function by defining LIN INCLUDE COND CHANGE NAD in the lin def h file the memory model chosen when building the slave driver must use a physical stack Doc ID 17460 Rev 1 81 83 Revision history UM0941 8 82 83 Revision history Table 63 Document revision history Date 14 Jun 2010 Revision 1 Initial release Changes Doc ID 17460 Rev 1 UM0941 Please Read Carefully Information in this document is provided solely in connection with ST products STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections modifications or improvements to this document and the products and services described herein at any time without notice All ST products are sold pursuant to ST s terms and conditions of sale Purchasers are solely responsible for the choice selection and use of the ST products and services described herein and ST assumes no liability whatsoever relating to the choice selection or use of the ST products and services described herein No license express or implied by estoppel or otherwise to any intellectual property rights is granted under thi
23. new nad to be assigned to the nodes Return value None Table 23 Save configuration Id save configuration Prototype void ld save configuration 1 ifc handle ifc 1 u8 nad Availability Master node only Include lin h Description This function issues a save configuration request to a specific slave node with the given NAD or P to all slave nodes if NAD is set to broadcast see LIN 2 1 section 7 3 1 5 CREE ifc addressed interface nad nad of the nodes to which the driver sends the request Return value None Table 24 Assign frame ID Id assign frame id void ld assign frame id 1 ifc handle ifc 1 u8 nad 1 ul6 Prototype supplier id 1 ul6 message id l_u8 pid Master node only Availability This function is obsolete for LIN 2 1 and disabled by default It can be used only to configure LIN 2 0 slaves in mixed clusters Include lin h This function changes the protected identifier of a frame in the slave node corresponding Description to nad and supplier id The changed frame must be the specified message id and the new protected identifier value given in pid 4 Doc ID 17460 Rev 1 25 83 API UM0941 Table 24 Assign frame ID continued Id assign frame id ifc interface handle nad diagnostic address of the node Parameters supplier id supplier id of the node message id the message id to assign to the frame id pid the new protected id value Retu
24. of the delay in timebase ticks define LIN DELAY INIT 2 Doc ID 17460 Rev 1 47 83 Driver configuration UM0941 Note 48 83 On slave nodes when receiving frames pIDs are validated against stored plDs However there is no validation of plDs assigned by the master or by the slave application Therefore an option to validate plDs on assignment is provided The following definition can be used for this purpose define LIN INCLUDE PID PARITY CHECK Validation is only carried out on assignment and not on reception of each frame by the slave node In LIN 1 2 1 3 nodes the API functions 1 ifc goto sleep andl ifc wake up were not defined Use the following definition if LIN 1 2 1 3 nodes need to include these two API functions BORK KK KK KK KKK KK kk kk RR RR RR RR RR KK KK KR kk kk kk LIN 1 2 1 3 specific setting define this if you want to use LIN 2 x goto sleep wakeup API for LIN 1 2 1 3 RK KK KK KR RR RR RK KK KR RR define LIN INCLUDE 2x SLEEP MODE API The LIN 2 x standard describes the behavior of nodes when receiving a wakeup request from a slave All slave nodes must be ready to receive frames within 100 ms A master must send frames within 150 ms after the wakeup request This means that a slave node may take up to 100 ms before being ready to receive frames and so a master node should not start transfer before this delay has elapsed However if slave nodes are ready to receive frames in a sh
25. switch BORK KKK KK KK kk kk kk kk k k kc kc kckckckckckckckckckckckckck KK KK RRR RRR RR kk Set the driver for development or production For development define LIN DEVELOPMENT several checks of input parameters are performed This will be quite useful for debugging during the development phase For production undef LIN DEVELOPMENT only a few checks on the input parameters of the functions are performed Activate this for smaller and faster code for the production phase after development KKK KR A RR RR KK KK RRR ek x define LIN DEVELOPMENT oko ok 0k ok F F o x Setting the frame maximum duration The maximum duration for a frame transfer can be configured as a percentage of the nominal transfer time the default setting of 140 corresponds to that specified in the LIN 2 1 specification BORK KR KK KK KK kk kk ke RR RR RR KR KK KK KR kk kk kk select the maximum frame transfer time in multiples of the nominal time 100 AK KK KK KK KK A RR RR RR RR RRR define LIN FRAME TIME MULTIPLIER 140 Doc ID 17460 Rev 1 45 83 Driver configuration UM0941 46 83 Setting the number of bits for the BREAK signal The number of bits to be used for a normal BREAK signal can be configured by changing the following setting However it is not normally recommended to change this value from the LIN standard value of 13 bits BORK KK RRR RK KK KK RK kk RR k k RR RRR RR RK KK KK RK RRR RRR
26. value can be 1 2 or 3 other values will involve in an error HK KKK KK A A KR RRR RR k k k k k k k k k ek DIAGNOSTIC CLASS 1 Only the node configuration services are supported The slave does not support any other diagnostic services Single frames SF transport protocol support is sufficient Node Identification is limited to the mandatory read by identifier service DIAGNOSTIC CLASS 2 Node configuration and identification services are supported Full transport layer implementation is reguired to support multi frame transmissions Node Identification is extended to all the Read By Id services Slave nodes will support a set of ISO 14229 1 diagnostic services like Node identification SID 0x22 Reading data parameter SID 0x22 if applicable Writing parameters SID 0x2E if applicable DIAGNOSTIC CLASS 3 Node configuration and identification services are supported Full transport layer implementation is reguired to support multi frame transmissions Node Identification is extended to all the Read By Id services Slave nodes shall support all services as of Class II Additionally other services may be supported depending on the features which are implemented by the slave node for example Session control SID 0x10 I O control by identifier 0x2F Read and clear DTC SID 0x19 0x14 Only class 3 slave nodes can reprogram the application via the LIN bus KK KK KK Re kk A k k A k k A kikki k k k k k
27. 00 1 6 250 16 MHz 29 250 gt 1 ms timebase 8 000 000 1 5 250 16 MHz 2 250 gt 1 ms timebase The driver uses a special callback function 1 timerISR to handle hardware timer interrupts The user application must implement and bind a timer interrupt service routine The user ISR will be called at the expiry of the hardware timer LIN_TIMER and it must call 1 timerISR The timer must not be used for any other purposes The user ISR should not handle the interrupt nor clear any flags it should only call the driver interrupt service routine Doc ID 17460 Rev 1 79 83 Architecture notes UM0941 7 4 7 5 80 83 The description of 1 timerISR is given below Table 62 Hardware timer interrupt service routine timerlSR Prototype void l timerISR void This function handles the hardware timer interrupt clears the interrupt flag Description restarts the timer and handles any software timeouts that may have occurred Include lin h Parameters None Return value None Interrupt function configuration Section 3 3 4 Interface Management provides a general description of the Rx and Tx interrupt functions defined by the LIN 2 x standard For STM8 architecture only the Rx interrupt is used The user defined interrupt handler must therefore call the 1 ifc rx function The 1 ifc tx function should not to be called as it has no effect Using memory page 0 To im
28. 38 Schedule tick sch tick Prototype i i 1 u8 1 sch tick 1 ifc handle ifc dynamic n Availability Master node only Include lin h This function follows a schedule table and initiates the transmission of frames when due When the end of the current schedule is reached it restarts from the beginning of the schedule see LIN 2 1 section 7 2 4 1 This function must be called periodically and individually for each interface within the node and at a rate specified in the cluster configuration file LDF The freguency at which this function is called is D ipti given by the time base value set as part of the master node configuration Since the period at scription which this function is called effectively sets the timebase tick it is essential that the timebase period is uphold with a minimum jitter see Section 6 2 for an example A call to this function will not only start the transition of the next frame due it will also update the signal values for those signals received since the previous call A predefined schedule table L NULL SCHEDULE shall exist and may be used to stop all transfers on the LIN cluster Parameters ifc interface handle Return value Non zero if next call to 1 sch tick will start the transmission of the frame in the schedule table entry The value will be the next schedule table entry number ranging from 1 to n for a table n entries 0 if the next call will not start a transmission
29. 73 78 83 Architecture notes These architecture notes explains how to configure the LIN driver to run on STM8 microcontrollers CPU freguency The CPU frequency must be configured in lin def stm8 h as follows BORK KK KK KK KK KK KKK KR RK kk RRR RK RR kc ko k kk k k define frequency of the cpu HK KK KK KK KK KK k k RR RR RRR RRR kk x define LIN BOARD CPU FREQ HZ 8000000 Interfaces Two serial interfaces are supported by STM8 microcontrollers SCI1 and SCI2 The interface is configured in the lingen control file as described in Section 5 lingen control file specifications In addition to the standard support for LIN the interfaces offer extra functionalities e Foramaster node both interfaces support the sending of BREAK directly This is a fixed 13 bit BREAK signal and it is always used e Fora slave node the SCI1 interface allows to auto synchronize with the current bus baud rate when a SYNCH is detected to within 1596 of the nominal rate This functionality can be selected by defining undefining the following variable in lin def stm8 h undef LIN SLAVE LINSCI AUTOSYNC or define LIN SLAVE LINSCI AUTOSYNC Timers The timer used by the LIN driver can be either a hardware or a software timer It is configured by the user application in lin def stm8 h by defining or undefining the LIN USE HARDWARE TIMER variable The following example shows the selection of a hardware timer BOR KK KK KK KK kk kk kk ke
30. API L zeusdad xxx RUE o a ERN Sra Mie wk xe Ru 12 3 1 Data oaa eked Seen o hod de seek a tob E AAT ak bad ea ree dB obe eee 2 12 3 2 FUNCIONS M Lm 12 3 3 CORE AP usual Shak hires ewe V d dac 5 Fue iP TOP Ed Rd 12 3 3 1 Driver and cluster management 000 eee eee 12 3 3 2 Signal interaction 4 4444 eee 13 3 3 3 NOtINCAtON 2 creed ex xA eee ERN pa eae steele eases 15 3 3 4 Interface Management 0 e eee 15 3 4 DISQNOSIGAP esses 8 ester eee MEAs REG XR X REG Sa ae REPS OE 23 3 4 1 Node Configuration specific API diagnostic 23 3 4 2 Node Identification specific API diagnostic 28 3 4 3 Diagnostic Transport Layer es 28 3 4 4 Diagnostic Transport Layer RAW API 0000 eee 29 3 4 5 Diagnostic Transport Layer COOKED API 31 3 5 Master specific APl is niv bee pceeueesbde ee sp ses eeu eaves 33 3 5 1 Schedule management 000 c cee tees 33 3 6 Slave specific API 2 ees 35 3 6 1 Interface management 0 cece eee 35 3 7 STMicroelectronics extensions lt 36 3 8 Implementation notes cee ee 38 3 8 1 API data types 00 ccc tee 38 3 8 2 Notification flags uis e Rer exu d 4 Boce RE Boyda n KRB on R eh A 38 4 Driver configuration 4 uasa Sk cen ok daco o COR lo c o RR 39 2 83 Doc ID 17460 Rev 1 ky UM0941 Contents 4 1 File and directory structure 0 ee 39 4 2 d
31. E IDLE after this function is called the area specified by data contains the requested data see LIN 2 1 Description section 7 3 3 1 The data returned is always in big endian format Note The user must reserve the memory space to store 5 bytes when id is in the range given for user defined ids ifc interface handle nad diagnostic address of the node supplier id supplier id of the node function id function id of the node id id of the data requested as follows Parameters 0 LIN product identification 1 serial number 2 31 reserved 32 63 user defined 64 255 reserved data pointer to buffer for receiving the requested data Return value None 3 4 3 Diagnostic Transport Layer Table 29 Initialization Id init Prototype void ld init 1 ifc handle ifc Availability Master and slave nodes Include lin h This function re initializes the raw and the cooked layers on the ifc interface All transport layer buffers are initialized see LIN 2 1 section 7 4 2 If a diagnostic frame transporting a cooked or raw message is ongoing on the bus it will not be aborted Description Parameters ifc the interface handle Return value None 3 28 83 Doc ID 17460 Rev 1 UM0941 API 3 4 4 Diagnostic Transport Layer RAW API Table 30 Put raw frame Id put raw Prototype void ld put raw 1 ifc handle ifc const 1 u8 const pData Availability
32. FLAGS COND CHANGE NAD LIN DIAG2 FLAGS READ BY ID LIN DIAG2 FLAGS DATA DUMP LIN IOCTL READ NAD The function returns a 16 bit value the lower 8 bit being the diagnostic node address NAD currently configured pParams is not used and may be set to 0 in the function call LIN IOCTL WRITE NAD Sets the diagnostic node address NAD of the slave node to the u8 value of pParams All values are accepted values from 1 to 126 are specified by the standard as the values to be used for diagnostic node addresses Always returns success i e O LIN IOCTL WRITE INITIAL NAD Sets the initial diagnostic node address NAD of the slave node to the u8 value of pParams All values are accepted values from 1 to 126 are specified by the standard as values to be used for diagnostic node addresses Always returns success i e 0 Note This function shall be called after sys init but before ifc init otherwise the initial NAD set with the call will not be used by the driver to initialise the current NAD Prototype static 4 l ul6 1 ifc ioctl iii 1 ioctl op operation void pParams where iii denotes the interface to which the operation is to be applied e g for the configured interface SCIO then the prototype l ul6 1 ifc ioctl SCIO 1 ioctl op operation void pParams Doc ID 17460 Rev 1 19 83 API UM0941 Table 15 Character reception notification I ifc
33. ID range Id assign frame id range Void ld assign frame id range 1 ifc handle ifc 1 u8 nad 1l u8 Prototype start index const 1 u8 const PIDs Availability Master node only Include lin h This function changes the PIDs of up to four frames in the slave node with the addressed NAD Description The PIDs parameter must be four bytes long each byte must contain a PID don t care OxFF or unassigned value 0x00 see LIN 2 1 section 7 3 1 3 ifc interface handle nad diagnostic address of the node Parameters start index frame index from which to start to assign PIDs PIDs Up to 4 bytes containing the new PIDs PIDs values must be either a value listed in table 2 4 in section 2 8 2 of LIN 2 1 specifications OxFF or 0x00 Return value None 3 24 83 Doc ID 17460 Rev 1 UM0941 API Table 22 Assign diagnostic address Id assign NAD void ld assign NAD 1 ifc handle ifc 1 u8 initial nad 1 ul6 Prototype supplier id 1 ul6 function id l_u8 new nad Availability Master node only Include lin h This function changes the diagnostic address NAD of any slave nodes matching the specified Description initial nad supplier idand function id to the value in new nad See LIN2 1 section 7 3 1 4 ifc addressed interface initial nad nad of the nodes to be re assigned Parameters supplier id supplier id of the nodes function id function id of the nodes new nad the
34. MasterReqB6 48 MasterReqB7 56 SlaveResp 61 SlaveRespBO 0 SlaveRespBl 8 SlaveRespB2 16 SlaveRespB3 24 SlaveRespB4 32 SlaveRespB5 40 SlaveRespB6 48 SlaveRespB7 56 72 83 node definition node attributes Node_attributes slavel LIN protocol 2 0 the startup diagnostic address configured NAD 1 product id is used to uniquely identify a slave node within a cluster product_id 0x1234 0x5678 0x03 definition of the error signal of the slave response error errorSignalSlavel the list of configurable frames all frames to be processed by the slave node must get a message id in this section configurable frames frmM1 0x01 frmM2 0x02 frmM3 0x03 frmS11 0x04 frmS12 0x05 Doc ID 17460 Rev 1 3 UM0941 Examples frmS13 0x06 frms21 0x08 frms22 0x09 frms23 0x10 slave2 LIN protocol 1 2 the startup diagnostic address configured NAD 2 schedule table definitions Schedule tables this schedule table will configure the slavel node to participate in LIN communication schTabConfig AssignFrameId slavel AssignFrameId slavel AssignFrameId slavel AssignFrameId slavel AssignFrameId slavel AssignFrameId slavel AssignFrameId slavel AssignFrameId slavel AssignFrameId slavel the normal sig
35. N INCLUDE RAW TP For the Raw TP the size of the Rx and Tx FIFO stack can be configured using the definition BORK KK KK KK KK KK KK RR RR RR RR KK KR KR kk kk kk define the stack size of the raw tp fifo stacks in numbers of frames HK KKK KK RR RRR RR RRR ee define LIN DIAG3 FIFO SIZE MAX 1 Doc ID 17460 Rev 1 3 UM0941 Driver configuration Figure 10 Default schedule in the Diagnostic Only mode Active schedule table Diagnostic slave response schedule Diagnostic slave response schedule Diagnostic slave response schedule Diagnostic slave response schedule i M y LAS 4 4 6 Callback functions Interrupt callback functions Two callback functions must also be provided by the user They allow the LIN driver to enable or disable system interrupts The function prototypes are described below together with their implementation They can be located in the lin def c file located in the user configuration directory The function prototypes are defined as follows Table 52 Disable Interrupts I sys irq disable Prototype l irqmask 1 sys irq disable void Availability Master and slave nodes This function achieves a state in which no interrupts from the LIN communication Description can occur Parameters None Return value Interrupt mask describing the state of the interrupts when this function is called Table 53 Restore Interrupts sys irq restore
36. Prototype void l sys irq restore l irqmask irqMask Availability Master and slave nodes Description This function restores the interrupt level identified by the irgMask parameter Parameters irqMask mask containing the state of the interrupts to be restored Return value None 4 Doc ID 17460 Rev 1 61 83 Driver configuration UM0941 62 83 An implementation example is given in Section 6 4 Example implementation of IRO callbacks master and slave The LIN driver uses these user defined functions each time an API function is called Interrupts are disabled when entering the API function and re enabled before returning This means that the callback functions provided for the driver must handle nested calls If an API function is called and interrupts have already been disabled interrupts shall only be re enabled at the outermost call to the 1 sys irq restore function The SuspendOSInterrupts and RestoreOSInterrupts OSEK functions described in Section 6 4 meet this requirements Protocol switch callback function The application can change the protocol for a given LIN interface by using the l protocol switch function with its parameter set to disable LIN When LIN is disabled a callback function is used by the ISR as an entry to the alternative protocol This callback function must be provided by the user and comply with the prototype given in Table 54 To enable the use of this featu
37. a master node the frames are sent to the node which address is nad If it is called from a slave node the frames are sent to the master see LIN 2 1 section 7 4 4 1 The call returns immediately The buffer should not be changed by the application as long as ld rx status returns LD IN PROGRESS If a message transfer is ongoing the call returns without performing any action Note SID or RSID must be the first byte in the data area It is included in the length Parameters ifc interface handle length from 1 to 4095 bytes including SID or RSID i e message length plus one nad address of node not used in slave nodes pData pointer to the data to be sent Return value None Table 35 Receive message Id receive message Prototype void ld receive message 1 ifc handle ifc 1l ul16 const length l_u8 yp const nad l u8 const pData Availability Master and slave nodes Include lin h This function prepares the module to receive a message and stores it in the given buffer When the call is issued length specifies the maximum allowed length After the call length specifies the actual length If ld receive message is called from a master node nad is assigned the value of the nad in the message see LIN 2 1 section 7 4 4 2 The call returns immediately The buffer should not be changed by the application as long as ld rx status returns LD IN PROGRESS o s l If the call is issued after the mess
38. age transmission has started i e the SF or FF is already transmitted this message will not be received and the function waits until the next message transfer begins The application must monitor the Id rx status and must not call this function until the status is LD COMPLETED Otherwise this function may return inconsistent data Note SID or RSID must be the first byte in the data area and is included in the length ifc interface handle length ranges from 1 to 4095 It is smaller than the value originally set in the call SID or RSID Parameters is included in the length nad address of node not used in slave nodes pData pointer to buffer into which the data will be written Return value None ky Doc ID 17460 Rev 1 31 83 API UM0941 Table 36 Get transmit queue status Id tx status Prototype u8 ld tx status 1 ifc handle ifc Availability Master and slave nodes Include lin h Description This function returns the status of the last call made to Id send message see LIN 2 1 section 7 4 4 3 Parameters ifc interface handle Return value LD IN PROGRESS transmission not yet completed LD COMPLETED transmission completed successfully A new 1d send message call can be issued This value is also returned after the initialization of transport layer is complete LD FAILED transmission completed with an error Data have been partially sent The transport layer should be re
39. at the root of the source directory This information is used to ensure that only consistent files are included when building the driver Doc ID 17460 Rev 1 11 83 API UM0941 API 3 1 Data The following data types must be defined for the driver bool u8 _u16 _u32 ioctl op irgmask ifc handle Since these types are hardware dependent they are defined in the architecture specific file lin def archname gen h located in the architecture specific directory 3 2 Functions The numbering in the description sections below refers to the LIN API specification section where the corresponding function is described 3 3 CORE API 3 3 1 Driver and cluster management Table 3 System Initialization I sys init void Prototype l bool 1 sys init void Availability Master and slave nodes Include lin h This function performs the initialization of the LIN core LIN API 7 2 1 1 The scope of the Descasiad initialization is the physical node i e the complete node see LIN 2 1 section 9 2 3 3 The call to 1_sys_init is the first call the user application must issue in the LIN core before calling any other API functions Parameters None Return value zero if initialization succeeded non zero if initialization failed 12 83 Doc ID 17460 Rev 1 ky UM0941 API 3 3 2 Signal interaction Table 4 Scalar signal read I bool rd u8 rd u16 rd l bool 1 bool rd 1 signal handle
40. be set None Prototype static 4 void 1 bool wr sss 1 bool val void 1 u8 wr sss 1 u8 val void 1 ul6 wr sss 1 ul6 val where sss denotes the name of the signal which value is to be set to val e g for the configured boolean signal status then the prototype void 1 bool wr status 1 bool val Doc ID 17460 Rev 1 13 83 API UM0941 Table 6 Byte array read bytes rd Prototype void 1 bytes rd 1 signal handle signalId 1 u8 start 1l u8 count dynamic l u8 const data Availability Master and slave nodes Include lin h This function reads and returns the current value of the selected bytes in the specified signal see Description LIN 2 1 section 7 2 2 4 The sum of start and count must never be greater than the length of the byte array signalId the signal to be read e g for the configured signal user data then LIN SIGNAL user data Parameters start the first byte to be read count the number of bytes to be read data the area where the bytes will be written Return value None Prototype static void 1 bytes rd sss 1 u8 start 1 u8 count 1 u8 const data where sss denotes the name of the signal to be read e g for the configured signal user data then the prototype void l1 bytes rd user data l u8 start l u8 count 1 u8 const data Table 7 Byte array write I bool wr Il u8 wr l u16 wr Prototype void
41. c interleaved Mode mandatory MasterReq delay 20 ms e If the lingen tool does not find a table complying with the mandatory requirements it does not include the LIN MASTER ONLY define statement This will cause a compilation error since a master node must support the Interleaved Diagnostics schedule mode which is mandatory see also Master node supporting either Interleaved diagnostics or Diagnostics only mode Figure 4 Interleaving of a diagnostic master request schedule table Active schedule table N Normal communication schedule N Diagnostic master reguest v X schedule X Normal communication schedule ky Doc ID 17460 Rev 1 53 83 Driver configuration UM0941 54 83 Master node supporting a diagnostic slave response schedule table containing a single slave response frame The diagnostic slave response schedule table is run between the executions of the normal communication schedules whenever a slave response frame is transmitted see Figure 5 The lingen tool checks if a table containing only a single slave response frame exists in the LDF file e If atable is found if there are more than one table it checks only the first table found in the LDF file it includes the following define statement in the lin cfg types h located under demo stm8 lin_basic_demo master obj define LIN SLAVE ONLY LIN TAB SlaveOnly In the example below the lingen tool has found the
42. c wake up iii void Prototype where iii denotes the interface to be woken up e g for the configured interface SCIO then the static prototype void l ifc wake up SCIO void 3 16 83 Doc ID 17460 Rev 1 UM0941 API Table 14 Interface control I ifc ioctl Availability Master and slave nodes Include lin h This function controls a functionality that is not covered by the other API calls It is used to control protocol specific parameters or hardware specific functionalities such as switching on off the wakeup signal detection Description The operations supported depend on the interface type The parameter block pParams is optional It is set to null if not needed Otherwise it is interpreted as specified below see LIN 2 1 section 7 2 5 4 This function is currently implemented to support the operations listed below ifc interface to which the operation is to be applied Parameters operation the operation to be applied pParams optional parameter block Return value master node LIN IOCTL DRIVER STATE This function returns a 16 bit values where the lower 8 bits represent the state of the driver and the upper 8 bits either the protected identifier of the frame currently being transferred or OxFF The protected identifier is only returned if the state is neither LIN STATE IDLE nor LIN STATE BUSSLEEP Note The definition of driver states is currently located in the file 1in_type
43. cture see Section 7 Architecture notes for the possible values The timer timebase is configured in 1in def h This timebase specifies the frequency at which the driver timer routine is called For a software timer this timebase gives the frequency at which the API function 1 timer tick is called by the user application or operating system If a hardware timer interrupt has been configured the driver sets the timer so that the timer ISR is called at this frequency Doc ID 17460 Rev 1 ky UM0941 Driver configuration 4 4 2 4 The recommended value for the timebase is either 1 or 2 ms It is set as follows BOR RR RK RK RK KK KK RR k k k k RR k k RR RR RR RR KK KK KKK RRR RR RR k k Set the time base of the lin timer in ms This is the time base of the timer ticks of the application driven timer or the time base of the hardware timer HK KK RR RR RR RR RK KK KK RK RRR RR define LIN TIME BASE IN MS 1 Further details concerning the use of a hardware timer are given in Section 7 Architecture notes General settings The user must define additional settings as described below Checking function parameters The driver can be built either for development or for production purposes The development version includes a more extensive check on the parameters passed to the functions This may not be necessary for a production version In this case checking operations can be reduced by changing the following
44. e board masterDIPStatel DIPs 1 and 2 masterDIPState2 DIPs 3 to 6 masterDIPState3 DIP 7 masterDIPSTate4 DIP 8 masterDIPStatel 2 0 master slavel slave2 masterDIPState2 4 0 master slavel slave2 masterDIPState3 1 0 master slavel slave2 masterDIPState4 1 0 master slavel slave2 slavel node signals the DIP state of the slavel node board slavelDIPStatel DIPs 1 and 2 slavelDIPState2 DIPs 3 to 6 slavelDIPState3 DIP 7 SlavelDIPSTate4 DIP 8 slavelDIPStatel 2 0 slavel master slave2 slavelDIPState2 4 0 slavel master slave2 slavelDIPState3 1 0 slavel master slave2 slavelDIPState4 1 0 slavel master slave2 slavelToggle 1 0 slavel master slave2 node signals the DIP state of the slavel node board slave2DIPStatel DIPs 1 and 2 slave2DIPState2 DIPs 3 to 6 slave2DIPState3 DIP 7 slave2DIPSTate4 DIP 8 slave2DIPStatel 2 0 slave2 master slavel slave2DIPState2 4 0 slave2 master slavel slave2DIPState3 1 0 slave2 master slavel slave2DIPState4 1 0 slave2 master slavel slave2Toggle 1 0 slave2 master ky Doc ID 17460 Rev 1 69 83 Examples UM0941 error signal errorSignalSlavel 1 0 slavel master errorSignalSlave2 1 0 slave2 master 70 83 signal definition diagnostic signals optional but recommended Diagnostic signals MasterRegBO0 MasterRegBl MasterReqB2 MasterRe
45. eration of the LIN library can then be included as follows make LIN OBJ PATH lin lib or by including LIN OBJ PATH lin lib in the target build instruction 3 Doc ID 17460 Rev 1 UM0941 Driver configuration 4 3 4 3 1 A sample makefile is delivered in the driver This can be used as a basis for development purposes Cluster configuration Cluster description The description of the node and cluster must be provided in a LIN description file LDF in accordance with the LIN 2 1 specification An LDF example is provided in Section 6 2 The lingen tool delivered with the driver suite can be used to convert the information given in the LDF into the appropriate format used internally by the driver In addition to the cluster description the user must specify which hardware interface s are used This information is specified in the lingen control file that is input to the lingen tool If the lingen tool is called from within the make process then the name of the control file must be set by the user in the top level makefile as described in Section 4 2 1 Top level makefile Master node A master node can support more than one interface In this case a separate LDF file is needed for each interface The lingen control file specifies which interfaces are used and the corresponding LDF file The format of the lingen control file is specified in Section 5 1 Lingen control file and is shown in the example below
46. erface 2 2 0 RI RR I t 15 Connect interface 0 2 20 ccc hr ere 16 Disconnect interface ee e EIRENE 16 E C mE 16 Interface control 2 0 2 ell hh 17 Character reception notification lt 4 44 lt 44 lt lt lt lt lt lt lt lt lt 4 4 20 Character transmission notification lille 20 Read interface status 0 0 0 0 ene 21 Description of ifc read status returned value 00 eee eee eee 23 Diagnostic module ready 0 cee rn 23 Check configuration response lt 444444444 24 Assign frame ID range 0 ec eR uh 24 Assign diagnostic address lt 44444 nen 25 Save configuration s isa siaua iiae sa aore a aaia aanika ae 25 Assign trame lD prer zamds sig om band ate date Eee eee Reade Pe eee eee Vus Ea 25 Conditional change diagnostic address 0 ccc eee esee 26 Read configuration 0 0 0c eh rr 26 Set configuration 2 104 20084 rale eo ae bd Va eae AUR RUE Vie EE RC Ea eig 27 Read Dy pp 28 NitAliZALION CDD 28 Put raw frame ice Rue A eee eee Se kee GS HES Sa ee 29 Get raw frame 2a wie kee edd ues ea eer odd ee Roe ee Sa ee vr 29 Query raw transmit queue status liliis 30 Query raw receive queue status llis 30 Send message llle rrr 31 Receive message lel hr hr 31 Get transmit gueue status 4 444444444 ae 32 Get receive queue status
47. ersion 4 2 8 Date 03 Dec 2008 COSMIC Software STM8 C Cross Compiler V4 2 8 03 Dec 2008 Win32 F COSMIC Software STM8 C Parser V4 8 12 25 Nov 2008 Win32 F COSMIC Software STM8 Code Generator V4 2 8 03 Dec 2008 Win32 F COSMIC Software STM8 Optimizer V4 2 8 03 Dec 2008 Win32 COSMIC Software STM8 Macro Assembler V4 5 6 13 Oct 2008 Win32 F COSMIC Software Linker V4 7 4 1 27 Oct 2008 Win32 F COSMIC Software Hexa Translator V4 3 13 27 Jun 2008 Win32 COSMIC Software Absolute Listing V4 3 13 27 Jun 2008 Win32 COSMIC Software Librarian V4 3 13 27 Jun 2008 Win32 COSMIC Software Absolute C Listing V4 3 13 27 Jun 2008 Win32 COSMIC Software Object Inspector V4 3 13 27 Jun 2008 Win32 COSMIC Software Print Debug Info V4 3 13 27 Jun 2008 Win32 COSMIC Software ELF DWARF Converter V4 5 27 18 Nov 2008 Win32 COSMIC Software IEEE695 Converter V7 0 7 23 Mar 2006 Win32 To optimize the driver code size the compiler compact switch can be used However in this case as in earlier Cosmic compiler versions the driver may not be reliable This risk must be considered by the user when choosing this option The driver can be built using stack or non stack memory model Since most driver functions need to be re entrant the estack qualifier has been added to each one As a result the memory model has little impact on the driver Using a memory model switch to build the driver with all global variables placed in
48. es Signal self consistency is ensured by the driver a partially updated 16 bit signal must never be passed to an application while the consistency between signals is managed by the application The signal LSB is transmitted first Scalar signals may cross a byte boundary at most once The driver maps each byte in the byte array to a byte in the frame Using the driver The driver must be configured and built before use Details on the configuration steps are given in Section 4 Driver configuration and architecture specific details are provided in Section 7 Architecture notes The STMicroelectronics LIN driver includes the diagnostic layer as described in LIN 2 1 specification The diagnostic API is divided between a RAW API and a COOKED API The RAW API allows a diagnostic application to control the contents of every frame sent while the COOKED API provides a full transport layer The user can choose to include or not the diagnostic functions when building the driver see Section 4 4 3 Diagnostic functions configuration Before using the driver functionalities the driver itself must be initialized by calling the 1 sys init API function Before using any interface related function the microcontroller interfaces must be initialized using the 1 ifc init API function and then connected using 1 ifc connect l ifc connect and1l ifc disconnect functions are obsolete for LIN 2 1 protocol and will not be compiled These functi
49. es 5 6626 ce ester uk NR RREWGCe wx B d 78 7 1 CPUMEQUENCY CT tan BAR tea n oo Bed ko Bok s Rk N vs S 78 72 riz 1 46 04 tikes io she tad BOB eh entice e enews od NEO ee 78 7 3 TIMO cH PD TUTUP 78 7 4 Interrupt function configuration lt lt 80 7 5 Using memory page O 0 ee eese 80 7 6 Toolchain support lt 1x66 anh RR FER RR UR pres qnn be edd eee 81 ky Doc ID 17460 Rev 1 3 83 Contents UM0941 8 REVISION history 4 a7 cao 0 i6 a r DC ol pov e e o o 82 4 83 Doc ID 17460 Rev 1 ky UM0941 List of tables List of tables Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Table 9 Table 10 Table 11 Table 12 Table 13 Table 14 Table 15 Table 16 Table 17 Table 18 Table 19 Table 20 Table 21 Table 22 Table 23 Table 24 Table 25 Table 26 Table 27 Table 28 Table 29 Table 30 Table 31 Table 32 Table 33 Table 34 Table 35 Table 36 Table 37 Table 38 Table 39 Table 40 Table 41 Table 42 Table 43 Table 44 Table 45 Table 46 Table 47 Table 48 ky Description of abbreviated forms 2 4444 8 LIN naming conventionS 0 e RR I e 10 System Initialization lt lt 12 Scalar signal read 1 tetas 13 Scalar signal write 2 2 hh 13 Byte array read ee rmn 14 Byte array Wile ceresti eenid siirre ca ee Ta x Ra E ed v PEE ee doeet 14 Iro 15 Cleantlag PDT 15 Initialize int
50. es not transport any message on the bus see LIN 2 1 section 7 3 1 7 This function must be called to restore a saved configuration or set an initial configuration for example coded by I O pins It must be called after calling 1 ifc init The caller must set the size of the data area before calling it The data contains the NAD and the PIDs and occupies one byte each The structure of the data is NAD and then all PIDs for the frames The PIDs are ordered in the same way as in the frame list in the LDF and NCF see LIN 2 1 section 9 2 2 2 and section 8 2 5 respectively Parameters ifc the interface to address data structure containing the NAD and n PIDs for the frames of the specified NAD length length of data 1 n NAD PIDs Return value LD_SET_OK If the service was successful LD_LENGTH_NOT_CORRECT if the required size of the configuration is not equal to the given length LD_DATA_ERROR Configuration setting could not be performed ky Doc ID 17460 Rev 1 27 83 API UM0941 3 4 2 Node Identification specific API diagnostic Table 28 Read by ID Id read by id void ld read by id 1 ifc handle ifc 1 u8 nad l1 ul6 supplier id Prototype l ul6 function id l_u8 id l_u8 const data Availability Master node only Include lin h This function reads the data specified by id from the node identified by naa and supplier id When the next call to ld is ready returns LD SERVIC
51. fined area 32 to 63 from the read by identifier configuration request Parameters see LIN 2 1 Table 4 19 Return value 4 data pointer to a data area of 5 bytes This area is used by the application to set up the positive response see LIN 2 1 user defined area in Table 4 20 The driver acts according to the following return values from the application LD_NEGATIVE_RESPONSE the slave node responds with a negative response see LIN 2 1 Table 4 21 In this case the data area is taken into account LD_POSTIVE_RESPONSE the slave node sets up a positive response using the data provided by the application LD_NO_RESPONSE The slave node does not answer Doc ID 17460 Rev 1 35 83 API UM0941 3 7 STMicroelectronics extensions Table 43 Software Timer function timer tick Prototype void l timer tick void Availability Master and slave nodes Include lin h This function handles a software timer interrupt Internal LIN timers are incremented and ee expired timers are evaluated Description i f TES This function should be called by the user application every LIN TIME BASE IN MS ms when no hardware timer has been configured see also Section 4 4 Parameters None Return value None Table 44 Protocol Switch I protocol switch Prototype void l protocol switch 1 ifc handle ifc 1 bool linEnable Availability Master and slave nodes Include lin h This function swi
52. gB3 MasterReqB4 MasterRegB5 MasterRegB6 MasterRegB7 SlaveRespBO SlaveRespBl SlaveRespB2 SlaveRespB3 SlaveRespBA4 SlaveRespB5 SlaveRespB6 SlaveRespB7 s n 0 000000000000 o o m O OOo O O O Oo Oo o o o o o o oO frame definition unconditional frames Frames frames published by the master frmM1 0 master 2 masterDIPStatel 0 frmM2 1 master 1 masterDIPState2 0 frmM3 2 master 1 masterDIPState3 0 masterDIPState4 1 Doc ID 17460 Rev 1 3 UM0941 Examples 4 frames published by slavel frmS11 20 slavel 2 frmS12 21 slavel 2 slavelDIPStatel 0 SlavelDIPState2 8 slavelToggle 12 frmS13 22 slavel 1 slavelDIPState3 0 slavelDIPState4 1 errorSignalSlavel 2 frames published by slave2 frmS21 40 slave2 2 frmS22 41 slave2 2 slave2DIPStatel 0 slave2DIPState2 8 slave2Toggle 12 frmS23 42 slave2 1 slave2DIPState3 0 slave2DIPState4 1 errorSignalSlave2 2 frame definition diagnostic frames optional but recommended Diagnostic frames MasterReq 60 Doc ID 17460 Rev 1 71 83 Examples UM0941 MasterReqBO 0 MasterReqBl 8 MasterReqB2 16 MasterReqB3 24 MasterReqB4 32 MasterReqB5 40
53. handle schedule 1 u8 entry where iii denotes the interface which schedule table is to be set e g for the configured interface SCIO then the prototype void 1 sch set SCIO 1 schedule handle schedule 1 u8 entry Table 40 Goto sleep ifc goto sleep Prototype void 1 ifc goto sleep 1 ifc handle ifc dynamic illos zm zi us Availability Master node only Include lin h This function sets all slave nodes in the cluster connected to the interface given to sleep mode see LIN 2 1 section 7 2 5 2 The go to sleep command is scheduled later when the next schedule entry is due This function does not affect the power mode It is up to the application to do this If the go to sleep command was successfully transmitted on the cluster the go to sleep bit is set Description in the status register see LIN 2 1 section 7 2 5 8 Note It is important that this function is not called if a frame transfer is ongoing The current transmission could be interrupted or the master node driver may not send the go to sleep command as expected The user should first check the current driver state by calling 1 ifc ioctl andcalll ifc goto sleep only if the driver is in LIN STATE IDLE state Parameters ifc interface handle Return value None Prototype static void 1 ifc goto sleep iii void where iii denotes the interface to be sent to sleep e g for the configured interface SCIO then
54. hat after the call has returned the status word is set to 0 For the master node the status word is updated in the ifc sch tick function For slave nodes the status word is updated later when the next frame is started The status word returned by 1 ifc read status is defined as follows bit 15 is MSB bit O is LSB see Table 18 Bit 0 Response error This bit is set when a frame error such as checksum error or framing error is detected in the frame response An error in the header results in the header not being recognized and the frame being ignored It is not set if there was no response on a received frame or if there is an error in the response collision of an event triggered frame Bit 1 Successful transfer This bit is set when a frame has been successfully transmitted received Bit 2 Overrun This bit is set when two or more frames have been processed since the last call to this function If set bit O and bit 1 represent the OR ed values for all the frames processed Bit 3 Go to sleep This bit is set when a go to sleep command has been received by a slave node or when the go to sleep command has been successfully transmitted on the bus by a master node Receiving a go to sleep command does not affect the node power mode It is up to the application to do this Bit 4 Bus activity This bit is set when the node has detected activity on the bus A slave node is put in bus sleep mode after a period of bus inactivity This ca
55. herein and shall not create or extend in any manner whatsoever any liability of ST ST and the ST logo are trademarks or registered trademarks of ST in various countries Information in this document supersedes and replaces all information previously supplied The ST logo is a registered trademark of STMicroelectronics All other names are the property of their respective owners 2010 STMicroelectronics All rights reserved STMicroelectronics group of companies Australia Belgium Brazil Canada China Czech Republic Finland France Germany Hong Kong India Israel Italy Japan Malaysia Malta Morocco Philippines Singapore Spain Sweden Switzerland United Kingdom United States of America www st com ky Doc ID 17460 Rev 1 83 83
56. icating without having been first configured by the master node This behavior is then no longer compliant with the standard The format of the lingen control file is specified in Section 5 1 Lingen control file and is shown in the examples below lingen control file defining one interface Interfaces specify that slave nodes will start with default frame IDs LIN use default frame ids SCIO home LIN src lin config lin sciO ldf IFCO The interface entries consist of three parts the interface name the LDF file to be associated with this interface and an optional tag field The location of the LDF file should be completely specified by giving the absolute path The tag entry is concatenated with all frame names and signal names when the lingen tool processes the LDF files As an example a signal name s1 sig1 in the LDF file in_sci0 ldf listed above will appear in the code as LIN SIGNAL IFCO sl sig For slave nodes the interface name given in the control file depends on the hardware Following the interface definition the user can specify the use of default frame IDs as described earlier Doc ID 17460 Rev 1 ky UM0941 Driver configuration 4 3 2 Figure 3 Lingen tool A set of configuration files can be generated using the lingen tool provided by ST It is based on the information given in the lingen control file and on the associated LDF file Inputs and outputs for l
57. iles LIN LIB Lib generation tool LIN TMP FILE Name for temporary file LIN SRC PATH Top level directory of the LIN driver Directory containing the configuration information for the cluster and the driver The lingen control file and the files lin def h lin def c and lin def archname h must be located in this directory The file HIN GG PATH lin def archname h is the architecture specific user configuration file where archname refers to the specific architecture name LIN GEN PATH Directory in which generated files are written This is used for the o option for lingen in the file Make LIN LIN LINGEN BIN Command used to invoke lingen Name of the node as defined in the LDF If multiple interfaces are defined for a LIN NODE master node then the name given in the associated LDF files should be the same throughout the application LIN LINGEN CONTROL Name of the control file used by lingen LIN LINGEN OPTS Options to be used by the lingen tool Details of options are given in Section 4 3 40 83 Optional variables In addition the optional makefile variable LIN LDF FILES can be set by the user They can be used to list the LDF filename s to be included in the dependency checks during the make process The definition of the variables of the Make LIN file should be included as follows include lt path to MakeLIN gt Make LIN where lt path to MakeLIN gt specifies the location of Make LIN The gen
58. in the file lin h The function sets the frame ID pParams gt frameld and the message ID pParams gt messageld for the frame indexed by pParams gt framelndex Returns 0 if successful or 1 if the index is invalid LIN IOCTL SET FRAME ID The parameter referenced by pParams must match the type frameMessageld t defined in the file lin h The function sets the frame ID for the frame matching pParams messageld to that given by pParams gt frameld Returns 0 if success otherwise 1 LIN IOCTL FORCE BUSSLEEP Forces the driver into sleep mode LIN IOCTL SET VARIANT ID Sets the Variant ID part of the Product ID in a slave node The default Variant ID used for a slave node on startup is that which is given in the LDF The parameter referenced by pParams must be of type u8 LIN IOCTL READ VARIANT ID The function returns the current value of the Variant ID The parameter given by pParams is not used and may be set to 0 in the function call 18 83 3 Doc ID 17460 Rev 1 UM0941 API Table 14 Interface control continued Return value slave node l ifc ioctl LIN IOCTL READ CONFIG FLAGS The function returns a 16 bit value indicating which configuration flags are set These flags are set on successful completion of the corresponding diagnostic service The flags are only cleared when read using this operation Flags set are LIN DIAG2 FLAGS ASSIGN FRAME ID LIN DIAG2 FLAGS ASSIGN NAD LIN DIAG2
59. ingen are described in Figure 3 Lingen workflow LDF File lingen exe a j listed in input e output Thelin cfg types hfile contains the type definitions needed for the driver lin cfg h contains static macros used for accessing configured signals and 1in cfg c contains initialized data structures in accordance with the information given in the LDF The lingen tool is started automatically from the makefile but can be manually executed using the following command format lingen nodeIdentifier options lingen control file where nodeIdentifier is the name of the node given in the LDF files for which the driver is to be built For a master node it must be the same in all Idfs while there is only one Idf supported in the case of a slave node lingen control file is the name of the control unit input to lingen The options listed in Table 51 are currently supported Doc ID 17460 Rev 1 43 83 Driver configuration UM0941 Note 4 4 4 4 1 44 83 Table 51 Options Name Description Specifies which of the possible configurations given in the LDF will be used seconliguration to build the driver o outputDirectory Specifies the destination for the configuration files that are to be generated Selects the checksum model to be used for receiving frames Possible values are r receiveChecksum 1 default the lingen tool determi
60. initialized before processing further messages Check the status management function 1 read status to find out why the transmission failed see LIN 2 1 section 7 2 5 8 LD N AS TIMEOUT transmission failed because of a N As timeout see LIN 2 1 section 3 2 5 Table 37 Get receive queue status Id rx status Prototype u8ld rx status I ifc handle ifc Availability Master and slave nodes Include lin h Description This function returns the status of the last call made to ld receive message see LIN 2 1 section 7 4 4 4 Parameters ifc interface handle Return value LD IN PROGRESS reception not yet complete LD COMPLETED reception completed successfully All information are available length NAD data This value is also returned when the transport layer initialization is complete and a new ld receive message call can be issued LD FAILED reception completed with an error Data ware partially received and should not be trusted The transport layer should be reinitialized before processing further messages Check the status management function 1 read status to find out why the reception failed see LIN 2 1 section 7 2 5 8 LD N CR TIMEOUT reception failed because of a N Cr timeout See LIN 2 1 section 3 2 5 LD WRONG SN reception failed because of an unexpected seguence number 32 83 3 Doc ID 17460 Rev 1 UM0941 API 3 5 Master specific API 3 5 1 Schedule management Table
61. is function must be called before using any other interface related to API functions see LIN 2 1 section 7 2 5 1 Description Parameters ifc the interface to be initialized Return value Zero if initialization was successful non zero otherwise 1 bool 1 ifc init iii void Prototype where iii denotes the interface to be initialized e g for the configured interface SCIO then the static prototype 1 bool 1 ifc init SCIO void Table 11 Connect interface I ifc connect Prototype ifc connect function is obsolete for LIN 2 1 protocol and should not be used dynamic mb Table 12 Disconnect interface I ifc disconnect Prototype j ifc disconnect function is obsolete for LIN 2 1 protocol and should not be used dynamic diia Table 13 Wakeup ifc wake up Prototype void 1 ifc wake up 1 ifc handle ifc dynamic Availability Master and slave nodes Include lin h This function issues a wakeup signal to the specified interface see LIN 2 1 section 7 2 5 3 The wake up signal OxFO byte i e a dominant pulse lasting 250 us to 5 ms depending on the Description configured bit rate is transmitted directly when this function is called It is the responsibility of the application to retransmit the wakeup signal according to the wakeup sequence see LIN 2 1 section 2 6 2 Parameters ifc interface handle Return value None Void 1 if
62. iven lies in the range allocated for user defined ids i e 32 63 If a non zero value is returned the driver sends the buffer back to the master The user application receives the complete frame buffer and can write up to 5 bytes response into the buffer starting at location pBuffer 3 The application is responsible for setting the PCI byte pBuffer 1 correctly It must be set to the number of valid data bytes written plus one Since the buffer is pre set to OxFF the unused bytes will have this value Description id the id sent by the master Parameters u pBu fer the buffer into which the user application must write a response Return value non zero if buffer to be sent back to master Table 56 Id data dump callback Id dataDumpCallback Prototype 1 bool ld dataDumpCallback l u8 sendBuf l u8 recBuf Provides a response to a data dump request from the master This callback is called by the slave driver and must write 5 bytes in response starting at recBuf 0 and Description then return non zero to the driver If no response is to be sent then return zero to the driver Note When a response is to be returned 5 bytes will always be transferred sendBuf the buffer sent by the master Parameters m ice recBuf the buffer into which the application can write its response Return value non zero if the driver is to send a response back to the master Baud rate detection cal
63. k k k k k k k k k k k k k k x define LIN DIAG3 FIFO SIZE MAX 1 Transport Protocol handling in LIN 2 1 Master Transport Protocol handling reguires that The master node supports a diagnostic master reguest schedule table that contains a single master reguest frame The master node supports a diagnostic slave response schedule table that contains a single slave response frame When no diagnostic communication is active the master node does not execute diagnostic schedules tables default A master node supports the following different scheduling modes Interleaved diagnostics mode mandatory Diagnostics only mode optional 3 Doc ID 17460 Rev 1 UM0941 Driver configuration Master node supporting a diagnostic master reguest schedule table containing a single master reguest frame The diagnostic master reguest schedule table is executed each time a master reguest frame is transmitted see Figure 4 The lingen tool checks if a table containing only a single master request frame exists in the LDF file e lfatable is found if there are more than one table it checks only the first table found in the LDF file it includes the following define statement in the 1in cfg types h located under demo stm8 lin_basic_demo master obj define LIN MASTER ONLY LIN TAB MasterOnly In the example below the lingen tool has found the MasterOnly table in the LDF file MasterOnly This is the Master Diagnosti
64. l1 delay 10 ms Poll the RSM node CEM Frml delay 15 ms LSM Frm2 delay 15 ms RSM Frm2 delay 15 ms LSM Frml delay 10 ms Poll the LSM node Signal encoding types Dig2Bit logical value 0 off logical value 1 on logical value 2 error logical value 3 void ErrorEncoding logical value 0 OK logical value 1 error 76 83 Doc ID 17460 Rev 1 y UM0941 Examples FaultStateEncoding logical value 0 No test result logical value 1 failed logical value 2 passed logical value 3 not used LightEncoding logical value 0 Off physical value 1 254 1 100 lux logical value 255 error Signal representation Dig2Bit InternalLightsRequest ErrorEncoding RSMerror LSMerror FaultStateEncoding IntError LightEncoding RightIntLightsSwitch LefttIntLightsSwitch 6 4 Example implementation of IRQ callbacks master and slave The following example describes OSEK implementation l irqmask 1 sys irq disable void SuspendOSInterrupts return 0 void l sys irq restore l irqmask irqmask ResumeOSInterrupts return The user can locate these implementations in an application specific file that includes the corresponding operating system header file For an OSEK implementation include os h 4 Doc ID 17460 Rev 1 77 83 Architecture notes UM0941 7 7 1 7 2
65. language and the interface for software programming LIN communications Communications between the application software embedded on LIN nodes are performed by exchanging signals The LIN driver software is responsible for managing the exchange of signals at low level The information are transferred between the nodes by using frames Doc ID 17460 Rev 1 ky UM0941 Overview Figure 1 The driver is conseguently responsible for processing application signals packing them into the frame data section and initiating the transfers The frames are then transferred via the microcontroller serial interface Using this communication technigue signal reading and writing operations are performed asynchronously of the frame transfers An overview of communications between LIN nodes is described in Figure 1 All transfers are initiated by the master node Slave nodes only transmit data when requested to do so The message frame consists of a header and a frame body The master node sends the frame message header The frame body can be sent either by the master or by a slave node Since the publisher for any given frame is configured before building the application only one node will send the frame body The frame message identifier denotes the message content and not the destination This communication concept means that data are exchanged between nodes as follows e From the master node to one or more slave nodes e From a slave node to the
66. lback function slave only Baud rate detection for slave nodes can be configured When this feature is enabled a callback function is invoked by the LIN driver when an incorrect baud rate is detected From this callback the application can then call the 1 change baudrate function to reduce the current baud rate The application starts with the highest possible baud rate and then repeatedly reduces the baud rate until communication is established This feature must be enabled in 1in def h by define LIN BAUDRATE DETECT Doc ID 17460 Rev 1 63 83 Driver configuration UM0941 Table 57 Baud rate detection callback baudrate callback iii Prototype void 1 baudrate callback iii 1 ul6 baudrate This function sets the baud rate for the given interface by calling the 1 change baudrate API function This callback is called if an incorrect too high baud rate is detected by the slave driver The callback is interface specific and so for each interface the user must provide a corresponding callback Description ifc interface handle Parameters baudrate the baud rate currently detected i e the incorrect baud rate on the interface Return value None 4 5 Interrupt configuration The STMicroelectronics LIN driver provides functions to handle the interrupts occurring when a character is received or transmitted on a specific interface These functions must be called from the user defined interrup
67. lementation notes API data types STLIN driver does not support some of the types defined in the standard API This means that the application cannot directly define variables of these types The types that are not defined are 1 signal handle 1 frame handleandl flag handle When calling the dynamic interface the application can only use the signals frames and schedules by their name as defined in the LDF It should use the interface name defined in the lingen control file Flag names are based on the signals and frames defined in the LDF Refer to Section 2 4 Using the driver for details on the naming conventions used by the driver Notification flags The notification flags are used to indicate signal or frame updates resulting from the transfer of signal or frames Since the application and driver executions are asynchronous unexpected behavior may occur as described in the following example Description 1 The driver master or slave detects that a frame must be sent and builds its frame buffer It copies the current signal values into the frame buffer and starts the transmission 2 The user application writes a signal that is contained in the frame being transferred It can also reset the Tx flag to be notified when the signal transmission is complete However the transfer of the frame is still in progress 3 The driver completes successfully the transfer of the frame It then marks the frame and all the signals it contai
68. licts and will be concatenated with C identifiers internally Therefore it should include a legal sequence of characters following C identifier rules see Section 4 3 1 Cluster description for an example Default frame Identifiers The LIN use default frame ids optional keyword is intended to be used with slave nodes only If included the default frame identifiers IDs given in the LDF apply to all slave frames Slave nodes can start communication without having been configured by the master Syntax specification The following syntax has been used for the specification of the lingen control file It must be consistent with the syntax used for specifying LIN description files as described in the LIN2 1 and LIN 2 0 standards for master and slave nodes respectively Doc ID 17460 Rev 1 ky UM0941 lingen control file specifications K Table 60 Syntax description Symbol Description Is defined to be lt gt Delimits an object specified later Delimits an object that shall appear one or more times Delimits an object that is optional bold text Keyword or symbol use directly as given identifier Identifies an object c style identifier rules apply string Any c style string tag_identifier Use to extend identifiers c style identifier rules apply Doc ID 17460 Rev 1 67 83 Examples UM0941 6 6 1 6 2 68 83 Examples Sample control file for lingen The linge
69. n 150 ms ST min 50 ms configurable frames CEM Frml 0x0001 LSM Frml 0x0002 LSM Frm2 0x0003 74 83 Doc ID 17460 Rev 1 ky UM0941 Examples 4 Signals IntLightsReq 2 0 CEM LSM RSM RightIntLightsSwitch 8 0 RSM CEM LeftIntlLightsSwitch 8 0 LSM CEM LSMerror 1 0 LSM CEM RSMerror 1 0 LSM CEM IntTest 2 0 LSM CEM Frames CEM Frml 0x01 CEM 1 LSM Frml 0x02 LSM 2 LSM Frm2 0x03 LSM 1 InternalLightsRequest 0 LeftIntLightsSwitch 0 LSMerror 0 IntError 1 RSM Frml 0x04 RSM 2 RSM Frm2 0x05 RSM 1 RightIntLightsSwitch 0 RSMerror 0 Event_triggered_frames Node Status Event Collision resolver 0x06 RSM Frml LSM Frm1l Schedule tables Configuration Schedule Doc ID 17460 Rev 1 75 83 Examples UM0941 AssignNAD LSM delay 15 ms AssignFrameIdRange LSM 0 delay 15 ms AssignFrameId RSM CEM Frm1 delay 15 ms AssignFrameId RSM RSM Frm1 delay 15 ms AssignFrameId RSM RSM Frm2 delay 15 ms Normal_Schedule CEM Frml delay 15 ms LSM Frm2 delay 15 ms RSM Frm2 delay 15 ms Node Status Event delay 10 ms MRF_schedule MasterReq delay 10 ms SRF_schedule SlaveResp delay 10 ms Collision_resolver Keep timing of other frames if collision CEM Frml delay 15 ms LSM Frm2 delay 15 ms RSM Frm2 delay 15 ms RSM Frm
70. n be implemented by the application by monitoring the bus activity Note The bus is inactive when there is no transition between recessive and dominant bit values Bus activity is the opposite Bit 5 Event triggered frame collision This bit remains set as long as the collision resolving schedule is executed It can be used in conjunction with the value returned by 1 sch tick For slave nodes this bit is always O If the master node application switches schedule table while the collision is resolved the event triggered frame collision flag is set to 0 Bit 6 Save configuration This bit is set when the save configuration request has been successfully received It is set only for slave nodes and always remains 0 for the master node Bit 7 always set to 0 Bit 8 15 Last frame protected identifier This 8 bit value represents the protected identifier last detected on the bus and processed in the node If the overrun bit bit 2 is set only the last value is maintained Prototype static 1 u16 1 ifc read status iii void where iii denotes the interface which status is to be read e g for the configured interface SCIO then the prototype void l ifc read status SCIO void 22 83 3 Doc ID 17460 Rev 1 UM0941 API Table 18 Description of ifc read status returned value 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Event Last frame PID 0 Save triggered Bus Go to Ov iirun Successful Respon
71. n tool uses a specific control file to determine which interfaces have to be configured and which LDF file is associated with the selected interfaces This example applies to a master configuration with two interfaces Master node lingen control file defining two interfaces Interfaces SCIO home LIN src lin config lin sciO ldf IFCO SCI1 home LIN src lin config lin scil ldf IFC1 Slave node lingen control file defining one interface Interfaces SCIO home LIN src lin config lin sciO ldf IFCO H specify that slave nodes will start with default frame IDs LH LIN use default frame ids LIN 2 0 LDF example master and slave The format and full details for a LIN description file are given in the LIN configuration language specification section of LIN 2 0 standard This example shows a configuration with one master and two slave nodes The first slave node is set up according to LIN 2 0 and the second according to LIN 1 2 global definitions LIN description file LIN protocol version 2 0 LIN language version 2 0 LIN speed 19 2 kbps node definition participating nodes Doc ID 17460 Rev 1 ky UM0941 Examples Nodes Master master 10 ms 0 1 ms Slaves slavel slave2 signal definition standard signals Signals Master node signals the DIP state of the Master nod
72. nals are transferred using table schTabl frmM1 delay 20 ms frmS11 delay 20 ms frmS21 delay 20 ms frmM2 delay 20 ms frmM3 delay 20 ms frmS13 delay 20 ms frmM1 frmM2 frmM3 frmS11 frmS12 frmS13 frms21 frms22 frms23 Doc ID 17460 Rev 1 delay delay delay delay delay delay delay delay delay 20 20 20 20 20 20 20 20 20 ms ms ms ms ms ms ms ms ms this schedule 73 83 Examples UM0941 frmS23 delay 20 ms 6 3 LIN 2 1 LDF example master and slave node The format and full details of a LIN description file are given in the LIN configuration language specification section of LIN 2 1 standard This example shows a configuration with one master and two slave nodes Both slave nodes are set up according to LIN 2 1 LIN description file LIN protocol version 2 1 LIN language version 2 1 LIN speed 19 2 kbps Channel name DB Nodes Master CEM 5 ms 0 1 ms Slaves LSM RSM Node_attributes LSM LIN protocol 2 1 configured NAD 0x20 initial NAD 0x01 product id Ox4A4F 0x4841 response error LSMerror fault state signals IntTest P2 min 150 ms ST min 50 ms configurable frames CEM Frmi LSM Frml LSM Frm2 RSM LIN protocol 2 0 configured NAD 0x20 product_id Ox4E4E 0x4553 1 response error RSMerror P2 mi
73. nes the checksum model from the information given in the LDF both the driver accepts either model for all frames Selects the checksum model to be used for sending frames Possible values are s sendChecksum laf default the lingen tool determines the checksum model from the information given in the LDF classic the driver sends all frames using the classic checksum v verbose mode Details from lingen will be output to the shell The o option is set in the file Make_LIN and should not be set in the top level makefile It must be set to LIN_GEN_PATH It is recommended not to change this setting unless the file Make_LIN Is replaced User configuration There are two header files that contain user configurable settings lin def h and lin_def_archname h where _archname refers to a specific architecture lin def archname h contains the architecture dependent settings see Section 7 Architecture notes lin def h contains other configurable settings see Section 4 4 1 Section 4 4 2 Section 4 4 3 Section 4 4 4 Section 4 4 5 and Section 4 4 6 Timers The LIN driver can use either a hardware timer or a software timer to monitor bus activity when sending frames or checking bus sleep conditions This timer must be configured by the user in the architecture specific configuration file lin def archname h If a hardware timer is selected the timer number must also be configured according to the archite
74. nostic master request schedule Diagnostic slave response schedule Diagnostic master request schedule Diagnostic slave response schedule awe da dia d asc d ITUR UFU FAIA OF The Diagnostics only mode is enabled and disabled by issuing a diagnostic service request from an external test tool For example the Communication Control service in UDS disables normal communication on the LIN cluster and activates the Diagnostics only mode When operating in Diagnostics only mode and no transmission is active the master node executes diagnostic slave response schedule tables see Figure 10 The lingen tool checks if a table containing only two frames a master request frame and a slave response frame exists in the LDF file If at least one table is found if there are more than one table it checks only the first table found in the LDF file it includes the following define statement in the lin cfg types h located under demo stm8 lin_basic_demo master obj define LIN DIAGNOSTIC ONLY LIN TAB Diagnostic In the example below the lingen tool has found the Diagnostic table in the LDF file Diagnostic This is the Diagnostic Only Mode optional MasterReq delay 20 ms SlaveResp delay 20 ms If the lingen tool does not find any table complying with the optional requirements it does not include the LIN DIAGNOSTIC ONLY define statement This does not generate any compilation since the Diagnostics only mode is optional
75. nostic slave response schedule Normal communication schedule Diagnostic slave response schedule pe S T Slave response frame with response SF ae BC ame ame E KA Diagnostic response e Diagnostics only mode optional In Diagnostics only mode only the diagnostic schedules No normal communication schedules are executed The basic principles when using master request frame schedule tables and slave response frame schedule tables are similar as for the Diagnostics interleaved mode except that no normal communication schedules are interleaved between the diagnostic schedule tables This allows to optimize diagnostic data transmission when reading slave node Identifications or during Flash memory reprogramming see Figure 9 for the different cases 3 Doc ID 17460 Rev 1 57 83 Driver configuration UM0941 Figure 9 Diagnostic only mode a Long transmission to diagnostic class III slave Active schedule table Diagnostic master reguest schedule Diagnostic master reguest schedule Diagnostic master reguest schedule Diagnostic master reguest schedule b Long transmission from diagnostic class III slave Active schedule table Diagnostic slave response schedule Diagnostic slave response schedule Diagnostic slave response schedule Diagnostic slave response schedule a Subseguent reguests with responses from diagnostic class I slave nodes Active schedule table Diag
76. ns as transferred 4 The user application polls the Tx flag and receives 1 It consequently assumes that the value just written has been transferred Instead the value that was originally valid has been transferred Workaround Usethe1 ifc ioct1 function to query the driver state before writing new signal values If a frame is being transferred the query returns the pID and the driver state The application can then check if the signal to be written is part of the current frame See Section 3 3 4 Interface Management for further details of the 1 ifc ioct1 function Doc ID 17460 Rev 1 ky UM0941 Driver configuration 4 Driver configuration This section describes the configuration and the hardware specific settings reguired and explains how to build the driver 4 1 File and directory structure The LIN driver consists of four different groups of source files e Generic files for all architectures e Hardware specific files e User configurable files e Configuration files generated by the lingen tool supplied with the driver The user configurable files the lingen tool the control file and the LDF files required to generate a LIN library must be located in a directory selected by the user This must then be specified in the top level makefile as described in Section 4 2 The driver specific Make_LIN makefile supplied with the driver is based on a particular directory structure The top level directory i
77. nsible for storing the data in the appropriate memory area Before calling this function the caller must reserve an area allowing to store the number of bytes specified by length The 1d read configuration function sets the length parameter to the actual size of the configuration If the data area is too small the function returns without performing any action If the NAD has not been set by a previous call to 1d set configuration or the Master node has used the configuration services the returned NAD will be the initial NAD The data consists of two bytes the NAD followed by the PIDs for all frames ordered in the same way as in the frame list in the LDF and NCF see LIN 2 1 section 9 2 2 2 and section 8 2 5 respectively Parameters ifc addressed interface data structure that contains the NAD and n PIDs for the frames of the specified NAD length length of data 1 n NAD PIDs Return value LD READ OK if the service was successful LD LENGTH TOO SHORT if the configuration size is greater than the size specified by length lt means that the data area does not contain a valid configuration Table 27 Set configuration Prototype Id set configuration l u8 ld set configuration 1 ifc handle ifc const l1 u8 const data l u16 length Availability Slave node only Include lin h Description This function configures the NAD and the PIDs according to the configuration specified by data lt do
78. ntrol file specifications UM0941 5 5 1 5 2 66 83 lingen control file specifications Lingen control file The lingen tool uses a specific control file to determine which interfaces have to be configured and which LDF file is associated with the selected interfaces The following sections specify the content of this control file C C style comments can be used in the lingen control file They are not described in the sections below An explanation of the syntax is given in Section 5 2 Syntax specification File definition lt lingen_control file gt Interfaces lt interface spec gt LIN use default frame ids Interface specification The interface is defined as follows interface spec interface id gt lt ldf file name tag id interface id identifier The driver currently supports the interface identifiers from SCIO to SCI9 However the identifiers should match the specific interface as defined in Section 7 Architecture notes lt ldf file name gt string The string should specify the filename of the LIN description file It must include the full path specification for the file It can be either the relative path to the file or the filename if the file is located in the current directory It is recommended to specify the full path especially if the lingen tool is executed from a makefile tag id tag identifier The tag identifier is intended for avoiding naming conf
79. ol on Availability Master node only Include lin h Description This function sets the break length to the cooling value if the parameter on is set to TRUE P otherwise the break length is set to the standard break length ifc interface handle Parameters on set to true if cooling break should be used false if normal break should be used Return value None Table 47 Set baud rate I change baudrate Prototype void 1 change baudrate 1 ifc handle ifc l ul6 baudrate Availability Slave node only Include lin h This function sets the baud rate for the specified interface This function should only be called Description from the callback function that is invoked by the driver when an incorrect too high baud rate is detected The callback function must be configured as described in Section 4 4 6 ifc interface handle Parameters baudrate the baud rate to set for the interface Return value None Table 48 Raw Tx delete Id raw tx delete Return value Prototype void ld raw tx delete l ifc handle ifc Availability Master and slave nodes Include lin h j This function removes the oldest Raw Tx frame that has been put on the Tx stack using Description ld put raw Parameters ifc interface handle 1 if a frame has been removed 0 if no Raw Tx frame was on the stack 3 Doc ID 17460 Rev 1 37 83 API UM0941 3 8 3 8 1 3 8 2 38 83 Imp
80. ons will be compiled only for LIN 2 0 or LIN 1 3 protocols The following naming convention that has been adopted in STMicroelectronics driver Table 2 LIN naming conventions item type item name LIN name signal sigName LIN SIGNAL sigName frame frameName LIN FRAME frameName flag flagName LIN FLAG flagName schedule table tabName LIN TAB tabName node nodeName LIN NODE nodeName Doc ID 17460 Rev 1 SA UM0941 Overview 2 5 The application must use the LIN name format except when calling the API static functions For example if a signal named sigMstatus has been configured in the LDF file the application must use the form LIN SIGNAL sigMstatus for dynamic function calls my sig l u8 rd LIN SIGNAL sigMstatus or the form sigMstatus as used in the generation of static function names my sig 1 u8 rd sigMstatus If a master node is configured to use multiple interfaces an optional tag can be specified by the user to avoid naming conflicts This tag will prefix the item name given above See Section 4 3 Cluster configuration for details and examples Driver version The driver comprises several source and header files that are revisioned with a version number which is only updated on change A given driver release consequently contains files with varied version numbers The list of the file versions used to build a given driver release is contained in the file lin version control h located
81. orter time frame then the master may start sending earlier This time delay must be configured using the following definition BORK KK KK KK KK KKK KR RR RR RR RK KKK KKK kk kk kk Master specific setting Here the delay after wakeup before sending frames is specified for LIN 2 x The value is configurable here in milliseconds The default value is 100 milli secs Here you can specify other values for example shorter times if you know your slaves are responding faster In particular the CANoe lin conformance test needs a shorter time recommended in this case is 75 HK KK KK KR RR KKK RR ke k k define LIN MASTER WAKEUP TIMER VALUE 100 RR 0X FF On slave nodes the default value for bus sleep timeout is specified in the LIN2 x standard as 4 s When a wakeup request is issued by a slave node the period between consecutive retries is 150 ms After three failed attempts the node must wait 1 5 s before issuing another wakeup request These values can be configured by the user as follows BORK RK RK KK ke kk ke kk RR k k RR KR RR RK KK KK KK k k k RR RR k k LIN 2 x specific setting The value for the bus sleep timeout is configurable here in milliseconds The recommended default value given in the standard is 4secs The other two definitions give the period between the signals in milliseconds the standard demands 150 and 1500 Doc ID 17460 Rev 1 ky UM0941 Driver configuration Note 4 4
82. prove the speed and the driver code size some variables can be located in page 0 of the memory area The user application must specify how many bytes to allocate for this purpose in the lin def stm8 h file This is done as follows BORK KK KK KK kk kk ke ke ke kk e k kc kckckckckckckckckckckckckckckckckck RRR ck ko ko kk Optimisation for STM8 Give size available in fastest most efficient memory area you can spare for the LIN driver in bytes HK KK KK KK KK kk kk kk kc kc kckckckckckckckckckckckckckckckckck RRR ke k k define LIN ZERO PAGE SIZE 5 The default value is of 5 bytes The driver automatically selects which variables can be located in the available space and tags them accordingly for the linker Additionally the user can also choose to locate some additional data in page 0 This can be configured by changing the following settings in lin def stm8 h undef LIN TX FLAGS IN ZERO PAGE undef LIN RX FLAGS IN ZERO PAGE undef LIN CHANGED FLAGS IN ZERO PAGE undef LIN FRAME BUFFER IN ZERO PAGE undef LIN FRAME IDS IN ZERO PAGE The space required to locate these data in page 0 is not automatically calculated by the driver and must be defined by the user Doc ID 17460 Rev 1 ky UM0941 Architecture notes 7 6 Note Toolchain support The LIN driver for the STM8 has been developed with GNU make v3 74 and Cosmic compiler version 4 2 8 with the following components STM8 COSMIC C Compiler V
83. pt is used Description For UART based implementations this function can be called from a user defined interrupt handler triggered by a UART on transmission of one character of data In this case the function performs the required operations on the UART control registers For more complex LIN hardware it can be used to indicate the transmission of a complete frame see also Section 4 5 Parameters ifc the interface that sent the data Return value None Prototype static void 1 ifc tx iii void where iii denotes the interface that transmitted data e g for the configured interface SCIO then the prototype void 1 ifc tx SCIO void 20 83 3 Doc ID 17460 Rev 1 UM0941 API Table 17 Read interface status ifc read status Prototype dynamic 1 ul6 1 ifc read status 1 ifc handle ifc Availability Master and slave nodes The behavior is different for master and slave nodes Include lin h Description Returns a 16 bit status frame for the specified interface Parameters ifc the interface which status is to be returned see LIN 2 1 section 7 2 5 8 Ky Doc ID 17460 Rev 1 21 83 API UM0941 Table 17 Read interface status continued Return value ifc read status Status of the previous communication 16 bit word which value depends on the frame transmitted or received by the node except bus activity The call is a read reset call This means t
84. re include the following define statement in lin def h define LIN PROTOCOL SWITCH Table 54 Protocol switch function callback I protocol callback iii void 1 protocol callback iii void Protot diuina where iii denotes configured interfaces SCIO SCIn Availability Master and slave nodes This function provides the entry point to an alternative protocol handler called by the ISR when an interrupt occurs after the application has called the l protocol switch API function to disable LIN The callback is interface specific and so for each interface the user must provide a corresponding callback Description Parameters None Return value None Doc ID 17460 Rev 1 ky UM0941 Driver configuration 4 Diagnostic callback functions slave only Two callback functions can be configured for slave nodes to be able to use the ld read by id diagnostic service when used for user defined ids and the ld data dump service These have the following prototype forms For these two callbacks empty implementations are included in the file lin def c These must be replaced by the user to provide the functionality required Table 55 Id read by id callback Id readByldCallback Prototype l bool ld readByIdCallback 1 u8 id 1 u8 pBuffer This function provides a response in accordance with the id reguest sent from the master This callback will be called by the slave driver when the id g
85. re implemented by the slave node for example Session control SID 0x10 I O control by identifier 0x2F Read and clear DTC SID 0x19 0x14 Only class 3 slave nodes can reprogram the application via the LIN bus KK KK KK Re kk A k k A k k A kikki k k k k k k k k k k k k k k k k k k k define LIN DIAGNOSTIC CLASS 1 OR OR FF F FH FF F HF KF F F OR HF KF F F F HF F F FF OF o ifdef LIN SLAVE NODE ifndef LIN DIAGNOSTIC CLASS error For a LIN 2 1 slave node LIN Diagnostic Class is mandatory and must be defined endif if LIN DIAGNOSTIC CLASS 1 LIN DIAGNOSTIC CLASS 3 error LIN 2 1 Diagnostic Class value can be 1 2 or 3 endif 4 Doc ID 17460 Rev 1 59 83 Driver configuration UM0941 60 83 else if defined LIN MASTER ONLY defined LIN SLAVE ONLY error A LIN 2 1 master node must support the Interleaved Diagnostics schedule Mode mandatory endif endif endif LIN 21 BOR KK KK KK kk kk kk ke I kc kc kc kckckckckckckckckckckckckck ck ck ck RR kk kk LIN TP features Select by define ing TP is disabled by default HK KK KK KK RR RR RR RR RK KK RR ee k k BOR KK KK KK KK kk kk ke ke RR RR RR RR RK RR RR kk kk kok the cooked diagnostic TP KK KK KK KK KK A RR RR RR RK RK RR ek k k undef LIN INCLUDE COOKED TP BOR KK KKK KK KK KK KK RR KR RR RR RR KK RK KR kk kok the raw diagnostic TP AK KK KK RK RR RR RR RRR kk x undef LI
86. rers to produce low cost automotive networks that complement existing networks such as CAN It is based on single wire serial communications using SCI UART interfaces that are commonly available on microcontrollers LIN is intended to be used together with CAN to build a hierarchical vehicle network LIN is usually used for local subsystems where a low bit rate up to 20 kbit s is acceptable and no safety critical functions are required These applications are typically used for car body electronics such as door and seat control air conditioning etc These subunits are connected to a CAN network through a LIN CAN gateway ALIN cluster comprises one master node and one or several slave nodes LIN has a special feature that performs the synchronization of slave nodes via the bus thus allowing to implement low cost nodes without the need of quartz clocking In addition since accesses to the bus are controlled by the master node no collision management is required between the slave nodes This also means that a worst case transmission time for signals can be guaranteed The slave nodes do not need any information about the LIN cluster As a result additional slave nodes can be added to the LIN without modifying existing slave nodes The master node requests information from all slaves and must be re built if new nodes are added The LIN standard includes the specification of the transmission protocol the transmission medium the system definition
87. rn value None Table 25 Conditional change diagnostic address Id conditional change NAD void ld conditional change NAD 1 ifc handle ifc 1 u8 nad 1 u8 Prototype id 1l u8 byte l_u8 mask l_u8 invert l_u8 new nad Availability Master node only Include lin h This function changes the nad if the corresponding node properties fulfills the test specified Description by id byte mask and invert see LIN 2 1 section 7 3 2 Refer to LIN Diagnostic Specification for further details ifc interface handle nad diagnostic address of the node id 0 31 Parameters byte 1 5 specifying the id byte mask 0 255 invert 0 255 new_nad new node address Return value None Table 26 Read configuration Id read configuration l u8 ld read configuration 1 ifc handle ifc l u8 const data 1 u8 Prototype const length Availability Slave node only Include lin h 3 26 83 Doc ID 17460 Rev 1 UM0941 API Table 26 Read configuration continued Id read configuration Description This function serializes the current configuration and copies it to the area data pointer provided by the application It does not transport any message on the bus see LIN 2 1 section 7 3 1 6 Tis function must be called when the save configuration reguest flag is set in the status register see LIN 2 1 section 7 2 5 8 When the call has completed the application is respo
88. rx Prototype void 1 ifc rx 1 ifc handle ifc dynamic Availability Master and slave nodes Include lin h This function must be called when the specified interface receives one character of data see LIN 2 1 section 2 5 5 The application program is responsible for binding the interrupt and setting the correct interface handle if the interrupt is used Description For UART based implementations this function can be called from a user defined interrupt handler triggered by a UART on reception of one character of data In this case the function performs the required operations on the UART control registers For more complex LIN hardware this function can be used to indicate the reception of a complete frame see also Section 4 5 Parameters ifc the interface that received the data Return value None Prototype static void l ifc rx iii void where iii denotes the interface that received data e g for the configured interface SCIO then the prototype void 1 ifc rx SCIO void Table 16 Character transmission notification I ifc tx Prototype f void 1 ifc tx 1 ifc handle ifc dynamic Availability Master and slave nodes Include lin h This function must be called when the specified interface transmits one character of data see LIN 2 1 section 7 2 5 6 The application program is responsible for binding the interrupt and for setting the correct interface handle if the interru
89. s document If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein UNLESS OTHERWISE SET FORTH IN STS TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND THEIR EOUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT UNLESS EXPRESSLY APPROVED IN WRITING BY AN AUTHORIZED ST REPRESENTATIVE ST PRODUCTS ARE NOT RECOMMENDED AUTHORIZED OR WARRANTED FOR USE IN MILITARY AIR CRAFT SPACE LIFE SAVING OR LIFE SUSTAINING APPLICATIONS NOR IN PRODUCTS OR SYSTEMS WHERE FAILURE OR MALFUNCTION MAY RESULT IN PERSONAL INJURY DEATH OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE ST PRODUCTS WHICH ARE NOT SPECIFIED AS AUTOMOTIVE GRADE MAY ONLY BE USED IN AUTOMOTIVE APPLICATIONS AT USER S OWN RISK Resale of ST products with provisions different from the statements and or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described
90. s h Doc ID 17460 Rev 1 17 83 API UM0941 Table 14 Interface control continued Return value slave node l ifc ioctl The return value depends on the operation requested LIN IOCTL DRIVER STATE The function returns a 16 bit values where the lower 8 bits represent the state of the driver and the upper 8 bits either the protected identifier of the frame currently being transferred or OxFF The protected identifier is returned if the state is either LIN STATE SEND DATA or LIN STATE RECEIVE DATA Note The definition of driver states is currently located in the file lin types h LIN IOCTL READ FRAME ID The parameter referenced by pParams must match the type frameMessageld t defined in the file lin h The function sets the frame identifier pParams gt frameld and the frame index pParams gt framelndex that matches the message ID pParams gt messageld The function returns O if it is successful and 1 if the message was not found LIN IOCTL READ MESSAGE ID The parameter referenced by pParams must match the type frameMessage t defined in the file lin h The function sets the message ID pParams gt messageld and the frame index pParams gt framelndex that matches the message ID pParams gt messageld Returns 0 if successful or 1 if the message ID was not found LIN IOCTL READ FRAME ID BY INDEX The parameter referenced by pParams must match the type frameMessageld t defined
91. s referred to by the variable LIN SRC PATH and must be configured in the top level makefile see Section 4 2 Its subdirectories should be compliant with Table 49 Table 49 Directory structure Top directory Subdirectory Comment node type is master if Master node otherwise node type P v slave general as given LIN SRC PATH diag as given timer as given aret ach name arch name specifies the specific architecture for which the driver will be built 4 2 Makefiles The LIN driver is delivered together with two makefiles that can be used to build a library containing the required functionalities e A top level makefile example which includes the settings for environment variables see Section 4 2 1 Top level makefile e Make LIN this file controls the building process and is designed to be included in the top level makefile Doc ID 17460 Rev 1 39 83 Driver configuration UM0941 4 2 1 Table 50 Top level makefile Predefined variables This file must include the definitions for the following variables Top level makefile predefined variable definition LIN NODE IDENTITY Name Description This variable must be set to MASTER NODE for a master node driver or SLAVE NODE for a slave node driver LIN CC Compiler command LIN CC OPT Compiler options LIN CC INC Include directories for the compilation process LIN MAKE PATH Path to Make LIN file LIN OBJ PATH Path in which to generate object f
92. se configuration frame activity sleep transfer error collision 3 4 Diagnostic API 3 4 1 Node Configuration specific API diagnostic Table 19 Diagnostic module ready Id is ready Prototype l u8 ld is ready 1 ifc handle ifc Availability Master node only Include lin h This function returns the status of the last reguested configuration service The returned value values are interpreted as follows LD SERVICE BUSY Service is ongoing LD_REQUEST_FINISHED The configuration request has been completed This is an intermediate status between configuration request and configuration response LD SERVICE IDLE The configuration request response combination has been completed i e the response is valid and can be analyzed This value is also returned if no request has been called LD SERVICE ERROR The configuration request or response failed This means that a bus error occurred and that the slave node did not receive any negative configuration response see LIN 2 1 section 7 3 1 1 Figure 2 shows the case of a successful configuration request and configuration response The change of state after the master request frame and slave response frame are complete may be delayed by up to one timebase period Description Parameters ifc the interface of the module to be queried LD SERVICE BUSY Service is ongoing LD REQUEST FINISHED The configuration request has been completed This is an
93. signalId Prototype d namic l u8 1 u8 rd 1 signal handle signalId y l ul6 1 ul6 rd 1 signal handle signalId Availability Master and slave nodes Include lin h EN These functions read and return the current value of the specified signal see LIN 2 1 section Description 7 2 2 2 signalId name of the signal to be read e g for the configured signal status then Parameters LIN SIGNAL status Return value bool boolean signal value or 0 if signalTd is invalid u8 8 bit signal value or 0 if signalTd is invalid u16 16 bit value or 0 if signalTd is invalid l bool 1 bool rd sss void l u8 1 u8 rd sss void Return value Prototype l ul6 1 ul6 rd sss void static where sss denotes the name of the signal that is to be read e g for the configured boolean signal status then the prototype 1 bool 1 bool rd status void Table 5 Scalar signal write I bool wr u8 wr l u16 wr void 1 bool wr 1 signal handle signalId 1 bool val Prototype i d namic void 1 u8 wr 1 signal handle signalId 1 u8 val y void l_ul6_wr 1 signal handle signalId l_u16 val Availability Master and slave nodes Include lin h Description These functions set the current value of the specified signal to val see LIN 2 1 section 7 2 2 3 signalId the signal to be set e g for the configured signal status then Parameters LIN SIGNAL status val the value to which the signal is to
94. t handlers which are called when an interrupt is triggered Since the driver functions completely handle the interrupts any further handling should not be implemented by the user These driver functions are architecture dependent As an example the application user should not call the Tx handler when only the Rx handler is used Refer to Section 7 Architecture notes for exact details The functions have the following interfaces Table 58 Handler for character rx I ifc rx Prototype void 1 ifc rx 1 ifc handle ifc Availability Master and slave nodes Description This function handles the interrupt when a character is received Parameters ifc the interface on which the interrupt occurred Return value None Interface specific void l ifc rx iii void prototype Description handles the interrupt for the interface given by iii Include lin h 3 64 83 Doc ID 17460 Rev 1 UM0941 Driver configuration K Table 59 Handler for character tx ifc tx Prototype void 1 ifc tx 1 ifc handle ifc Availability Master and slave nodes Description This function handles the interrupt Parameters ifc the interface on which the interrupt occurred Return value None Interface specific void l ifc tx iii void prototype Description handles the interrupt for the interface given by iii Include lin h Doc ID 17460 Rev 1 65 83 lingen co
95. tches the LIN protocol on or off for a specified interface It provides the Description possibility to use an alternative protocol on a given interface The ISR checks if LIN is P enabled If it is not it calls a callback function that is provided as an entry point to the alternative protocol handler This callback must be configured as described in Section 4 4 6 ifc interface handle Parameters linEnable if 1 then switch LIN on if O then off Return value None Table 45 Data Dump I data dump Bratatine void ld data dump 1 ifc handle ifc 1 u8 nad const 1 u8 const yp sendBuf l u8 const receiveBuf Availability Master node only Include lin h This function requests a data dump from a slave node The slave may return up to 5 bytes via D ipti the buffer receiveBuf The application must call 1d is ready after the call to escripton 1d_data_dump When TRUE is returned the application can access the data in the buffer According to the LIN specification this feature should not be used in live networks ifc interface handle nad address of node Parameters sendBuf holds the message to be sent to the slave receiveBuf holds the response when 1d_is_ready next returns TRUE Return value 36 83 None 3 Doc ID 17460 Rev 1 UM0941 API Table 46 Set Cooling Break I ifc set cooling break Prototype void 1 ifc set cooling break 1 ifc handle ifc 1 bo
96. the prototype void 1 ifc goto sleep SCIO void 34 83 3 Doc ID 17460 Rev 1 UM0941 API 3 6 Slave specific API 3 6 1 Interface management Table 41 Slave synchronize I ifc aux Prototype void 1 ifc aux 1 ifc handle ifc dynamic Availability Slave node only Include lin h This function performs the synchronization with the BREAK and SYNC characters sent by the Basic master node on the specified interface see LIN 2 1 section 7 2 5 7 P Note This function is redundant for the drivers currently delivered by ST It is therefore implemented as a null function Parameters ifc interface handle Return value None void 1 ifc aux iii void Prototype UE EM static where iii denotes the interface e g for the configured interface SCIO then the prototype void l ifc aux SCIO void Table 42 Read by ID callout Id read by id callout Prototype u8 ld read by id callout 1 ifc handle ifc 1 u8 id 1 u8 data Availability Slave node only optional if it is used the slave node application must implement this callout Include lin h This function can be used when the master node transmits a read by identifier request with an m identifier in the user defined area Description i k When such a request is received the slave node application is called from the driver see LIN 2 1 section 7 3 3 2 ifc interface handle id identifier in the user de
97. turn value Zero if flag is clear non zero otherwise l bool 1 flg tst fff void Prototype where denotes the name of the flag to be tested e g for the configured flag Txerror then static the prototype l bool 1 flg tst Txerror void Table 9 Clear flag I fig cir Prototype void 1 flg clr 1 flag handle f1ag dynamic Availability Master and slave nodes Include lin h Description This function sets the value of the specified flag to zero see LIN 2 1 section 7 2 3 2 Parameters flag the flag to be cleared e g for the configured flag Txerror then LIN FLAG Txerror Return value None l bool 1 flg clr fff void Prototype where denotes the name of the flag to be cleared e g for the configured flag Txerror then static the prototype bool flg clr Txerror void 3 3 4 Interface Management Table 10 Initialize interface ifc init Prototype T d l bool 1 ifc init 1 ifc handle ifc dynamic gt gt Availability Master and slave nodes Include lin h ky Doc ID 17460 Rev 1 15 83 API UM0941 Table 10 Initialize interface continued I ifc init This function initializes the specified interface for example the baud rate The default schedule set willbe L NULL SCHEDULE where no frames will be sent or received The interface names are listed in lin def h See Section 4 3 and Section 4 4 for details Th
98. ucis Got wat bis 200 UT TT UE 39 4 2 1 Top level makefile lt eee 40 4 3 Cluster configuration 4 45 fe kt arx ere Rr tered dees SEG Bold x as 41 4 3 1 Cluster description 4444444444444 41 4 3 2 Lirigen tool sos eee k been eee ERR aha p d rx Rx 43 4 4 User configuration 1 z jes Ai v Re koe Rr HAG kul ko K ee Pewee eee badd 44 4 4 1 Tames vx Rr Rae e AREE ENS Rae ENG EM Seek 44 4 4 2 General settings sei ado epe e TRU aaa SE d 45 4 4 8 Diagnostic functions configuration lt lt lt lt 49 4 4 4 Diagnostic class lt eren 50 4 4 5 Transport Protocol handling in LIN 2 1 Master 52 4 4 6 Callback functions 2 eens 61 4 5 Interrupt configuration esie p RRERERRERRRESERRAERREREXREEE 64 5 lingen control file specifications esses 66 5 1 Lingen control file 2m dedo uh ra CRGO P ER Abaton 66 5 1 1 File definition eee 66 5 1 2 Interface specification 4 4 44 ee 66 5 1 3 Default frame Identifiers lt 66 5 2 Syntax specification isses RR dve ERR EER REN KE RACE pea RUE 66 6 EXAMDlGS iouis Eee CR K Am eO De RR CEN C OR n 68 6 1 Sample control file for lingen lt 68 6 2 LIN 2 0 LDF example master and slave eee eee 68 6 3 LIN 2 1 LDF example master and slave node 74 6 4 Example implementation of IRQ callbacks master and slave 77 7 Architecture not
99. user data bytes using the LIN transport protocol Subsequent executions of the interleaved diagnostic slave response schedule table depend on the amount of data to be transferred They are performed by the master node until the transmissions have successfully completed or a transport protocol timeout occurs If a diagnostic transmission from slave node to master has started the master node executes the diagnostic slave response schedule even when one or several slave response frame headers have not been answered until see Figure 8 A P2max P2 max timeout occurs See section 5 6 of LIN 2 1 specification Atransport protocol timeout occurs See section 3 2 5 of LIN 2 1 specification The Diagnostic interleaved mode is configured by the Lingen tool by enabling the following define statement define LIN MASTER ONLY LIN TAB TableNamei define LIN SLAVE ONLY LIN TAB TableName2 56 83 Doc ID 17460 Rev 1 ky UM0941 Driver configuration Figure 8 Continued execution of diagnostic slave response schedule table until response received External test tool Master Active schedule table Diagnostic request to slave node ID 0x3C ll Master request frame Diagnostic master request schedule Normal communication schedule Diagnostic slave response schedule Slave response frame without response Normal communication schedule Sartre Mare CD Slave response frame without response Diag

Download Pdf Manuals

Related Search

Related Contents

i run s - Clickbox  2 - Rancilio Coffee Machines  第1回 今後の道路整備の方向性に関する検討委員会  Disney Time Clock agent-p snooze-inator alarm clock User's Manual  Moteurs de recherche et sitographie  Harbor Freight Tools 3/8 in. Professional Impact Air Ratchet Wrench Product manual  Samsung Fascinate  manual - herrajardin  Bitdefender Total Security 2010    

Copyright © All rights reserved. Failed to retrieve file