Home

STSW-STM8A-LIN software package

1. The maximum number of attempts can also be configured JAFFA RR RARA RR RR RARA RR RRA ck ck ckckckckck kckck ck ckckckckckckckck ck ck ck ckckck ko KKK 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 Ckckckck ck ckckckckckckckckck ck ck ckckckckckckck ck ckckckckckckckck AN 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 f ECKCKCk kc kckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ckckckckckckckckck ck ckckckckckckckck ck ck ck ck ck ck k k k k Configuration features Select by define ing Default values match the mandatory services defined by the standard kckckck ck ckckckckckckckckckckckckckckckckckck ck ckckckckckckck ck ckckckckckckckck ck kckckckckckckck ck ck ck ckckck k kk f ECKCKCk kc kckckckckckckckck ck ckckck ckckckckckckckckckckckckckckck ck ckckckckckckckck ck ckck ck ckck kckck ck ck ck ckckck ko kc kk service
2. DIAGNOSTIC CLASS 2 services are supported Full transport layer implementation is required to support multi frame transmissions Node Identification is extended to all the Read By kckckck ck ckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckck ck ckckckckckckckckck ck ck ckckckckckck ck ck ck ckckck k kk Only the node configuration services Node Identification is limited to the mandatory read by identifier service Node configuration and identification parameters S3 DIAGNOSTIC CLASS 3 Services are supported Full transport layer implementation is required multi frame transmissions Node Identification is extended to all the Read By d 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 D Ox2E if applicable Node configuration and identification to support Class identifier 0 ACA F ACA 0X CAC F F 0X F F Xo Ro F Xo 0o F EC ACA OX Xo Xo Xo F Xo X Additionally d services Slave nodes shall support all services as of 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 0x2F Read and clear DTC SID 0x19 0x14 the LIN bus kckckck ck ckckckck
3. define LIN START BUSSLEEP TIMER ON CONNECT f ECKCKCk kc kckckckckckckckck ck ckckckckckckckckckckckckckckckckck AAA select whether the master node should start a wakeup sequence on connect Okckckck ck ckckckckckckckckck ck ck ckckckckckckck ck ckckckckckckckck ck ck ckckckckckckckck kckckckckckckck ck kockckckck k kk fdefine LIN SEND WAKEUP SIG ON CONNECT For a master node the initial delay is undefined when switching from L NULL SCHEDULE to a valid schedule table after startup Use the following definition to set the initial value of the delay in timebase ticks define LIN DELAY INIT 2 DoclD024013 Rev 2 Ly UM1593 Note 2 Driver configuration 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 f ECKCKCk kc kckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ckckckckckc
4. 1 2 6 a ee e a kn 9 24 Using the driver ora ss a Re ROR RR CRUCE RE Ree RTL 9 2 5 Driver version aiia aii acer e i aos pr Sorte kei e a EE P e ET RR eens 10 3 Pi A E CO 11 3 1 Data si a ia ii 11 3 2 FUNCIONS sn yom a ne o ia ike werd ke Geese eee 11 3 3 CORE API iuris Se ee ho Fabr od Whee eS 11 3 3 1 Driver and cluster management 00 00 eee eee eee 11 3 3 2 Signal interaction 0 0 0 0 eee eee 12 3 3 3 NOUTICALION yc usa b uus bbw aaah a ILE AUD ARS bay dares 14 3 3 4 Interface Management oocccccccc ers 14 3 4 Diagnostic API asse home Ti 22 3 4 1 Node Configuration specific API diagnostic 22 3 4 2 Node Identification specific API diagnostic 27 3 4 3 Diagnostic Transport Layer i 27 3 4 4 Diagnostic Transport Layer RAW API i 28 3 4 5 Diagnostic Transport Layer COOKED API 30 3 5 Master specific API i 32 3 5 1 Schedule management 000 cee ee eee 32 3 6 Slave specific API es 34 3 6 1 Interface management 2000 e eee eee eee 34 3 7 STMicroelectronics extensions i 35 3 8 Implementation notes ccc eee 37 3 8 1 API data tyD6S ii ate e e ctn ate bite oe eee 37 3 8 2 Notification flags sss 37 4 Driver configuration sos 4 di pe Wake ertuE RSERE RERENENEERES 38 2 82 DoclD024013 Rev 2 Ly UM1593 2 Contents 4 1 File and directory structure oo 38 4 2 Pc e UT ee arre ab a aa cee eee ee ee 38 4 2 1 Top level makefil
5. 34 82 DoclD024013 Rev 2 UM1593 API 3 7 STMicroelectronics extensions Table 43 Software Timer function timer tick Prototype void 1 timer tick void Availability Master and slave nodes Include lin h This function handles a software timer interrupt Internal LIN timers are incremented and expired timers are evaluated Description P 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 protocol switch Prototype void 1 protocol switch 1 ifc handle ifc 1 bool linEnable Availability Master and slave nodes Include lin h This function switches 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 f linEnable if 1 then switch LIN on if O then off Return value None Table 45 Data Dump data dump void ld data dump 1 ifc handle ifc 1 u8 nad const 1 u8 const Prototype sendBuf 1 u8 const receiveBuf Availability Master node only Include lin h This function requests a data
6. void ld get raw 1 u8 const pData Availability Master and slave nodes Include lin h Description Parameters Return value 28 82 This function copies the oldest frame on the receive stack to the provided buffer see LIN 2 1 section 7 4 3 2 ld raw rx status should be checked first as the 1d 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 pData pointer to the buffer into which the frame will be copied None 2 DoclD024013 Rev 2 UM1593 API Table 32 Query raw transmit queue status ld raw tx status Prototype 1l u8 ld raw tx status 1 ifc handle ifc Availability Master and slave nodes Include lin h This function returns the status of the raw frame transmission queue see LIN 2 1 section 7 4 3 3 Description Parameters ifc interface handle 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 Bet value 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 1l u8 ld raw rx status 1 ifc han
7. 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 can 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 conjunct
8. Examples 69 82 Examples 70 82 frames published by slavel frmS11 20 slavel 2 slavelDIPStatel 0 frmS12 21 slavel 2 slavelDIPState2 8 slavelToggle 12 frmS13 22 slavel 1 slavelDIPState3 0 SlavelDIPState4 1 errorSignalSlavel 2 frames published by slave2 ES frms21 40 slave2 2 slave2DIPStatel 0 frmS22 41 slave2 2 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 DoclD024013 Rev 2 UM1593 2 UM1593 2 Examples MasterReqBO 0 MasterReqB1 8 MasterReqB2 16 MasterReqB3 24 MasterReqB4 32 MasterReqB5 40 MasterReqB6 48 MasterReqB7 56 SlaveResp 61 SlaveRespB0 0 SlaveRespB1 8 SlaveRespB2 16 SlaveRespB3 24 SlaveRespB4 32 SlaveRespB5 40 SlaveRespB6 48 SlaveRespB7 56 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
9. Parameters ifc addressed interface nad nad of the nodes to which the driver sends the request Return value None Table 24 Assign frame ID ld assign frame id void ld assign frame id 1 ifc handle ifc 1_u8 nad 1_ul6 supplier id 1 u16 message id l u8 pid Prototype 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 2 24 82 DoclD024013 Rev 2 UM1593 API Table 24 Assign frame ID continued ld 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 Return 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 yp id 1 u8 byte 1 u8 mask 1 u8 invert 1 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
10. 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 16 82 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 lin types h 2 DoclD024013 Rev 2 UM1593 API Table 14 Interface control continued Return value slave node _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
11. recommended in this case is 75 Okckckck ck ckckckckckck kckck ck ck ckckckckckckck ck ckckckckck kckckckckckckckckckckck ck kck ck ckckc kckck ck ck ck ckckck k kk define LIN MASTER WAKEUP TIMER VALUE 100 AA XX F Xx X 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 f ECKCKCk Ck kckckckckckckckck ck ckckckckckckckck ck ckckckckckckckckckckckckckckckckckck ck ckckckckckckckckck ck kkk kkk kk 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 XA A 0X DoclD024013 Rev 2 47 82 Driver configuration UM1593 Note 4 4 3 48 82 msecs Ckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckck ck ckckckckckckckckck ck ck ck ckckck ko KK KK ifndef LIN 13 define LIN BUSSLEEP TIMEOUT VAL IFC 1 u16 4000 define LIN WAKEUP TIMEOUT VAL SHORT IFC 1 u16 150 define LIN WAKEUP TIMEOUT VAL LONG IFC 1 u16 1500 endif
12. 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 82 Directory struct te 2 2 0 4 da gu eee ea Pee ek dade dU RR ea Hee 38 Top level makefile predefined variable definition o o o oooooooooo 39 ODLONS x soa teeta A a DEG SNP tae EN CU Ras 43 Disable Interrupts i 60 Restore Interrupts els 60 Protocol switch function callback sasaaa saanane 61 ld read by idcallback i 62 ld data dump callback 0 000 eee 62 Baud rate detection callback i 63 Handler for character rx 0 63 Handler for character tx et 64 Syntax description eae se oi EEE rn 66 Hardware timer configuration ot 78 Hardware timer interrupt service routine i 79 Document revision history arda nutan rds EERE hr 81 2 DoclD024013 Rev 2 UM1593 Abbreviations 2 1 2 2 2 Abbreviations Table 1 Description of abbreviated forms Abbreviation Description Application Programming Interface 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 manufacturers 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
13. 9 for the different cases 2 56 82 DoclD024013 Rev 2 UM1593 Driver configuration Figure 9 Diagnostic only mode a Long transmission to b Long transmission from a Subsequent requests with diagnostic class Ill slave diagnostic class Ill slave responses from diagnostic Active schedule table Active schedule table Active schedule table Diagnostic master request schedule Diagnostic master request schedule Diagnostic master request schedule Diagnostic master Diagnostic slave request schedule class slave nodes Diagnostic slave response schedule Diagnostic master request schedule Diagnostic slave response schedule Diagnostic slave response schedule Diagnostic master response schedule request schedule Diagnostic slave response schedule Diagnostic slave response schedule yw Wut uu 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
14. Assign Frame Id mandatory for LIN 2 0 obsolete for LIN 2 1 kckckck ck ckckckckckckckckck ck ck ckckckckckckck ck ckckckckckckckckckckckckckckckckck ck kck ck ckckckckck ck k ck ckckck k kk tundef LIN INCLUDE ASSIGN FRAME ID f ECKCKCk kc RR RARA RR RR RARA kk RR RARE RR RARA ck ckckckckckck ck ck ck ck ckck kc k k k service Assign NAD optional for LIN 2 x kckckck ck ckckckckckckckck ck ckckckckckckckckck ck ckckckckckckckckckckckckckckckckck ck kckckckckckckck ck k ck ckckck k kk 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 f ECKCKCk kc kckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckckck ck ckckckckck kckck ck ck ck ckckck kc KKK service Read By Id mandatory for LIN 2 x DoclD024013 Rev 2 Ly UM1593 Driver configuration Ckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckck ck ckckckckckckckck ck ckck ck ckckck ko kc ko kk ddefine LIN INCLUDE READ BY ID f RCKCKCkCkckckckc kc RR RARA RR RR RARE RR RR RRA RR RR RRA RR RR RRA kkk kkk service Conditional Change NAD optional for LIN 2 x EEE AN tundef LIN_INCLUDE_COND_CHANGE_NAD f RCKCKCkCk kk kc kc k
15. Diagnostic module ready o cooccccoo eae 22 Check configuration response i 23 Assign frame ID range 0 rh ee ee 23 Assign diagnostic address i 24 Save configuration oe To i A ger A e RU ve RATE IER A ern a 24 ASSION kome lD c 24 Conditional change diagnostic address i 25 Read configuration 20 0 ri eee ae 25 Set configuration oia aa be NE ee ene en p mx a a a 26 EEN A a A E E EE E E E EO 27 ET 27 Put raw frame 28 Get raw frame oae p aa eee a kd REA WR EATUR AN Gee ee D IE CAVE n 28 Query raw transmit queue status 2 eh 29 Query raw receive queue status lille res 29 Send Message cest tem rpm O t ded a Gea eR dur arce d RE RC a Re teu dn 30 Receive message seda Rete DER E eR E ALI boe eri Res 2h de TERR bets 30 Get transmit queue status l l 31 Get receive queue status lr 31 Sched le tick xr ed rt e RC CT EQ RUE RC IR RU RUN ee Sw hk RR CR a 32 Set schedule table 0 32 NN 1 ex gk ek eae a Genes bok Gane pea betas Ge ede BA aa ee te Ge eee 33 Slave synchronize 2 esee AA eo Dias vere Rice 34 Read by ID GO 34 Software Timer function 0 0000 cece ete eee 35 Protocol SWIM sce oo Pe ae EROR ek n D Ha RA Rn date eek Geta RA de 35 Data Dump 2 54 A VERE ADU ee IPIE SC RUE RU S bak e 4 SRI cd 35 Set Cooling Break 06 rn 36 Setbaud rate ue DR ad Miles t S EA REA eee eee EU e ae 36 Raw Tx delete 0 36 DoclD024013 Rev 2 5 82 List of tables UM1593 Table 49 Table 50 Table
16. IN description file IN protocol version 2 0 IN language version 2 0 IN Speed 19 2 kbps node definition participating nodes DoclD024013 Rev 2 67 82 Examples 68 82 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 node 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 and 2 slave2DIPState2 DIPs 3 to 6 slave2DIPState3 DIP 7 slave2DIPSTate4 DIP 8
17. INCLUDE COOKED TP f RCKCKCkCk kk RR RRA RRE RRE RR RR RRE RR RR kckckckckckckckck kkk the raw diagnostic TP CKCkckck ck ckckckckckckckckckckockckckckckckckckckckckckckckckckck ck ckckckckckckckck ck ck ckckckckck kckck ko kckckckck kk undef LIN INCLUDE RAW TP For the Raw TP the size of the Rx and Tx FIFO stack can be configured using the definition f RCKCKCkCk kk kc kc ck ckck ck kc kckckckckckckckckckckckckckckckckckckckckckckckck ck ck ckckckckckckckckck ck ckckckckck ko kk define the stack size of the raw tp fifo stacks in numbers of frames EE ck ckckckckckckckckck ck ckckckckck ko kc ko kk define LIN DIAG3 FIFO SIZE MAX Transport Protocol handling in LIN 2 1 Master Transport Protocol handling requires that e The master node supports a diagnostic master request schedule table that contains a single master request frame e The master node supports a diagnostic slave response schedule table that contains a single slave response frame e When no diagnostic communication is active the master node does not execute diagnostic schedules tables default e Amaster node supports the following different scheduling modes Interleaved diagnostics mode mandatory Diagnostics only mode optional DoclD024013 Rev 2 Driver configuration UM1593 52 82 Master node supporting a diagnostic master request schedule table containing a single
18. 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 1l u8 1d read configuration 1l ifc handle ifc 1 u8 const data 1_u8 const length Prototype Slave node only lin h Availability Include Ly DoclD024013 Rev 2 25 82 API UM1593 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 request flag is set in the status register see LIN 2 1 section 7 2 5 8 When the call has completed the application is responsible 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 1ength 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 confi
19. 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 zs All transport layer buffers are initialized see LIN 2 1 section 7 4 2 Description i i na If a diagnostic frame transporting a cooked or raw message is ongoing on the bus it will not be aborted ifc the interface handle Ly DoclD024013 Rev 2 27182 API UM1593 3 4 4 Diagnostic Transport Layer RAW API Table 30 Put raw frame ld put raw Prototype void ld put raw 1 ifc handle ifc const 1 u8 const pData Availability Master and slave nodes Include lin h This function queues 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 Prototype ld get raw 1 ifc handle ifc
20. 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 andcalli ifc goto sleep only if the driver is in LIN STATE IDLE state Parameters ifc interface handle Return value void l1 ifc goto sleep iii void Prototype where iii denotes the interface to be sent to sleep e g for the configured interface SCIO then static the prototype void l1 ifc goto sleep SCIO void DoclD024013 Rev 2 33 82 API UM1593 3 6 Slave specific API 3 6 1 Interface management Table 41 Slave synchronize ifc aux Prototype void 1 ifc aux 1 ifc handle ifc dynamic Availability Slave node only Include lin h Description This function performs the synchronization with the BREAK and SYNC characters sent by the master node on the specified interface see LIN 2 1 section 7 2 5 7 Note This function is redundant for the drivers currently delivered by ST It is therefore implemented as a null function Parameters ifc interface handle Ret
21. 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 0 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 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
22. eR eke bend debe RR ES 79 7 6 Toolchain Support m ke aed meo ee a eee es RUE S 80 DoclD024013 Rev 2 3 82 Contents UM1593 8 Revision history casitas rro de 81 2 4 82 DoclD024013 Rev 2 UM1593 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 Ly List of tables Description of abbreviated forms ee 7 LIN naming conventions liiis R3 9 System Initialization conse niea a a RR eh 11 Scalar signal tead 2 032246 a Rb CR aee Rehd a OON a RR RR a 12 Scalar signal Wlle leslie sul ge oh orm c m B Roh oko E E ee Rc d 12 Bye aray ead Ex 13 Byte array WOE a a E E A a it A eae 13 A E A 14 1 14 Initialize interface 000 0c hh 14 Connect interface 15 Disconnect interface 9 15 Wake p chica dente behest ROC bike VERA i ded teenies 15 Interface COMMON cui Re Em ERR OE Ux e RR ges ed ae 16 Character reception notification es 19 Character transmission notification os 19 Read interface status 4 20 Description of ifc read status returned value i 22
23. 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 void l ifc tx iii void Prototype where iii denotes the interface that transmitted data e g for the configured interface SCIO then static the prototype void 1 ifc tx SCIO void 2 DoclD024013 Rev 2 19 82 API UM1593 Table 17 Read interface status ifc read status Prototype dynamic l u16 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 20 82 DoclD024013 Rev 2 Ly UM1593 API Table 17 Read interface status continued 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 that after the call has returned the status word is set to O 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 16
24. 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 1 ifc connect and 1 ifc disconnect functions are obsolete for LIN 2 1 protocol and will not be compiled These functions 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 c
25. master request frame The diagnostic master request schedule table is executed each time a master request 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 Ifa 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 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 Diagnostic interleaved Mode mandatory MasterReq delay 20 ms e Ifthe 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 BN Normal communication schedule A EN Diagnostic master request BEEN d schedule BN Normal communication schedule A 2 DoclD024013 Rev 2 UM1593 2 Driver configuration Master node supporting a diagnostic slave response schedule tabl
26. 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 A LIN 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 language and the interface for software programming LIN communications Communications between the application software embedded on LIN nodes are performed by exc
27. 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 conflicts 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 DoclD024013 Rev 2 65 82 Lingen control file specifications UM1593 Table 60 Syntax description Symbol Description n Is defined to be lt gt Delimits an object specified later Delimits an object that shall appear one or more times Delimits an obje
28. 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 Okckckck ck ckckckckckckckckckckckckckckckckck ck ckckckckckckckckckckckckckckckckckck ck ckckckckckckckck ck ck ck ck ckck kk k 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 switch RRRRRRKKRRKKKKK ckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckckck ck ckckckckckckckck ck ck ck ckckck ck KKK 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 kckckckck ckckckckckckckckck ck ckckckckckckckck ck ckckckckckck
29. 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 2 DoclD024013 Rev 2 17 82 API UM1593 Table 14 Interface control continued Return value slave node Prototype static 18 82 _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 FRAMI LIN DIAG2 FLAGS ASSIGN NAD LIN DIAG2 FLAGS COND CHANGE NAD LIN DIAG2 FLAGS READ BY ID LIN DIAG2 FLAGS DATA DUMP iral H o LIN_IOCTL_READ_NAD The function returns a 16 bit value the lower 8 bit being the diagnostic node addres
30. tx Prototype void l1 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 1 ifc tx iii void prototype Description handles the interrupt for the interface given by iii Include lin h DoclD024013 Rev 2 2 UM1593 5 5 1 5 2 2 Lingen control file specifications 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 ldf file name tag id interface id iuc 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 string The string should specify
31. 2 UM1593 Examples 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 IN description file IN protocol version IN language version IN speed 19 2 kbps Channel name DB Nodes Master CEM 5 ms 0 1 ms Slaves LSM RSM N N Node_attributes LSM LIN protocol 2 1 configured NAD 0x20 initial NAD 0x01 product id 0x4A4F 0x4841 response error LSMerror fault state signals IntTest P2 min 150 ms ST min 50 ms configurable frames CEM Frm1 LSM_Frm1 LSM Frm2 M RSM LIN protocol 2 0 configured_NAD 0x20 product id 0x4E4E 0x4553 1 response_error RSMerror P2 min 150 ms ST_min 50 ms configurable_frames CEM Frml 0x0001 LSM Frm1 0x0002 LSM Frm2 0x0003 2 DoclD024013 Rev 2 73 82 Examples UM1593 Signals IntLightsReq 2 0 CEM LSM RSM RightIntLightsSwitch 8 0 RSM CEM eftIntllightsSwitch 8 0 LSM CEM LSMerror 0 LSM CEM RSMerror 0 LSM CEM IntTest 2 0 LSM CEM Frames CEM Frmi1 0x01 CEM 1 InternalLightsRequest 0
32. IC IC Q O n 2 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 stack 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 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 1in_def h file the memory model chosen when building the slave driver must use a physical stack 2 DoclD024013 Rev 2 UM1593 8 2 Revision history Revision history Table 63 Document revision history Date 05 Dec 2012 16 May 2014 Revision Changes Initial release replacing UM0941 Rev 1 14 Jun 2010 Changed document title Updated Introduction on page 1 Added Applicable products on page 1 Updated the document title and the Introduction on the cover page to include STMicroelectronics
33. KCk kc kckckckckckckck ck ck ckckckckckckck ck ckckckckckckckckck ck ckckckckckckckck ck kkk kk kkk ck kck ck ckckckckckck ck ck ckckck c 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 UIN USE HARDWARE TIMER xx 0X Okckckck ck ckckckckckckckckck ck ckckckckckckck ck ckckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckck ck kck ck ckck kc kck KKK KKK define LIN USE HARDWARE TIMER 2 DoclD024013 Rev 2 77 82 Architecture notes UM1593 Note 78 82 STM8 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 FERRERA RR RARE RR RR RR RRA RR RRA RR RR RR RRA RR RR RR ck ckckckckckckckckck ck ck kk k k KKK choose the timer used by the LIN driver valid values depend on the architecture used J 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 p
34. KK KK the raw diagnostic TP undef LIN_INCLUDE_RAW_TP For the Raw TP the size of the Rx and Tx FIFO stack can be configured using the definition FERRERA kk RARA RR RR RR REA RR RR RRA RR RR RRA RR RR kckckckckckckckck kk ck define the stack size of the raw tp fifo stacks in numbers of frames define LIN DIAG3 FIFO SIZE MAX 1 DoclD024013 Rev 2 59 82 Driver configuration 4 4 6 60 82 UM1593 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 E y Ly LAD 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 1in def c file located in the user configuration di
35. KRRKEKRKKKKKRKEKKERKKKK ckckckckckckckckckckckckckckckckckck ck kkk kk kkk ck kckckckckckckckck ck ck ckckck k define frequency of the cpu Okckckck ck ckckckckckckckck ck ckckckckckckckckck ckckckckckck kckck ck ckckckckckckckck ck ck ckckckckckckck ck kck ck ckckc kc k ck ck KKK kk define LIN BOARD CPU FREQ HZ 8000000 7 2 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 For a master 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 15 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 rA INSCI AUTOSYNC 7 3 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 f RCKC
36. LIN FRAME BUFFER IN ZERO PAGE tundef 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 DoclD024013 Rev 2 79 82 Architecture notes UM1593 7 6 Note 80 82 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 Version 4 2 8 Date 03 Dec 2008 Software Object Inspector V4 3 13 27 Jun 2008 Win32 Software Print Debug Info V4 3 13 27 Jun 2008 Win32 Software ELF DWARF Converter V4 5 27 18 Nov 2008 Win32 Software IEEE695 Converter V7 0 7 23 Mar 2006 Win32 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 IC
37. LIN software package reference STSW STMB8A LIN Removed the table Applicable products on the cover page No other changes in the content DoclD024013 Rev 2 81 82 UM1593 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 this 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 ST S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT
38. LSM Frm1 0x02 LSM 2 eeftIntLightsSwitch 0 LSM_Frm2 0x03 LSM 1 LSMerror 0 IntError 1 RSM_Frm1 0x04 RSM 2 RightIntLightsSwitch 0 RSM_Frm2 0x05 RSM 1 RSMerror 0 Event_triggered_frames Node Status Event Collision resolver 0x06 RSM_Frml LSM_Frml Schedule_tables Configuration_Schedule 2 74 82 DoclD024013 Rev 2 UM1593 2 AssignNAD LSM delay 15 ms AssignFramel dRange LSM 0 delay 15 ms AssignFrameld RSM CEM Frm1 delay 15 ms AssignFramel AssignFramel Normal_Schedule CEM Frml delay 15 LSM Frm2 delay 15 RSM Frm2 delay 15 Node Status Event MRF schedule d RSM RSM Frm1 delay 15 ms d RSM RSM Frm2 delay 15 ms ms ms ms delay 10 ms MasterReq delay 10 ms SRF schedule SlaveResp del Collision reso Iver Keep timing of CEM Frm de ay LSM Frm2 RSM Frm2 RSM Frm del del del ay ay ay CEM Frm del ay LSM Frm2 RSM Frm2 LSM Frm del del del ay ay ay 00 Ul 0 Ul Ul oO 55555555 Signal_encoding_types Dig2Bit logical_value 0 logical_value 1 logical_value 2 logical_value 3 ErrorEncoding logical_value 0 logical_value 1 lay 10 ms other frames if collision S S S S Poll th
39. May 2014 wr UM1593 I life augmented User manual STSW STM8A LIN software package Introduction Purpose This user manual provides application programmers with detailed information on how to use STMicroelectronics LIN driver STSW STM8A LIN 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 driver to operate with STM8 microcontrollers Scope STMicroelectronics implementation is compliant with the LIN API specification The LIN 2 1 software package supports all LIN standard versions 1 3 2 0 and 2 1 User profile The users should be familiar with the concept of networks and in particular LIN networks As STMicroelectronics LIN driver STSW STM8A LIN 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 STMicroelectronics STSW STMB8A LIN software driver is available on the company website at www st com DoclD024013 Rev 2 1 82 www st com Contents UM1593 Contents 1 Abbreviations AA a See 7 2 OVGIVIEW oececo thsbaesdgwesdX ar s AAA 7 2 1 LIN CONCEPE T aah a ee a 7 2 2 EIN communications cce EC e Ra eed et nice Reb dace Roe ael 7 2 3 Signal management
40. TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND THEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT ST PRODUCTS ARE NOT DESIGNED OR AUTHORIZED FOR USE IN A SAFETY CRITICAL APPLICATIONS SUCH AS LIFE SUPPORTING ACTIVE IMPLANTED DEVICES OR SYSTEMS WITH PRODUCT FUNCTIONAL SAFETY REQUIREMENTS B AERONAUTIC APPLICATIONS C AUTOMOTIVE APPLICATIONS OR ENVIRONMENTS AND OR D AEROSPACE APPLICATIONS OR ENVIRONMENTS WHERE ST PRODUCTS ARE NOT DESIGNED FOR SUCH USE THE PURCHASER SHALL USE PRODUCTS AT PURCHASER S SOLE RISK EVEN IF ST HAS BEEN INFORMED IN WRITING OF SUCH USAGE UNLESS A PRODUCT IS EXPRESSLY DESIGNATED BY ST AS BEING INTENDED FOR AUTOMOTIVE AUTOMOTIVE SAFETY OR MEDICAL INDUSTRY DOMAINS ACCORDING TO ST PRODUCT DESIGN SPECIFICATIONS PRODUCTS FORMALLY ESCC QML OR JAN QUALIFIED ARE DEEMED SUITABLE FOR USE IN AEROSPACE BY THE CORRESPONDING GOVERNMENTAL AGENCY 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 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 docume
41. ble 9 Clear flag fig cir Prototype void l1 flg clr 1 flag handle flag dynamic Availability Master and slave nodes 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 fff denotes the name of the flag to be cleared e g for the configured flag Txerror then static the prototype bool flg cir Txerror void 3 3 4 Interface Management Table 10 Initialize interface ifc init Prototype l bool 1 ifc init dynamic 1 ifc handle ifc Availability Master and slave nodes Include lin h Ly 14 82 DoclD024013 Rev 2 UM1593 API Table 10 Initialize interface continued ifc init This function initializes the specified interface for example the baud rate The default schedule set will be LL 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 This 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 l bool 1 ifc init iii voi
42. ck ck kckckckckckckckckckckckokckckckckckckckckckckckck ckckckckck ck ckckckckckckckckck kckckckckck kk ck service Data Dump optional for LIN 2 x Note The standard strongly discourages use of this service E in operational LIN clusters EAN tundef LIN INCLUDE DATA DUMP f RCKCKCkCk kk kk RRA RR RR RR REA RR RRA RRE RR RARA RR RR RRA RR RRA 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 OkCckckck ck kckckckckckckckckckockckckckckckckckckckckckckckckckckckokckckckckckckck ck ckckckckckckckckck ko kckckckck SS define SERIAL NUMBER OxFFFF The Save Configuration and Assign Frame Id Range services are valid only for LIN 2 1 tifdef LIN 21 f RCKCKCk kc kckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ckckckckckckckckckckckckckckckckckck ck ck ck ck ckck ko k k k service Save Configuration optional for LIN 2 1 kckckck ck ckckckckckckckck ck ckckckckckckckckck ck ckckckckckckckckckckckckckckckckck ck kckckckckckckck ck KKK KKK kk define LIN INCLUDE SAVE CONFIGURATION f ECKCKCk kc kckckckckckckckck ck ckckckckckckckckckckckckckckckckck ck ckckckckckckckckck ck ckckckckckckckck ck ck ck ckckck k k k k service Assign Frame Id Range mandatory for LIN 2 1 Ckckckck ck ckckckckc
43. ckck ck ckckckckckckckck ck ck ck ckckckckckck ck kockckckck k KK define LIN DEVELOPMENT A A XA F F F X F 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 RRRKRRRRKRRERKRKKKKRKRKERKERKK RK ckckckckckckckck ck ck ck ckckckck kckck ck ckckckckckckckck ck ck KKK KKK KK select the maximum frame transfer time in multiples of the nominal time 100 kckckck ck ckckckckckck kck ck ckckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck kck ck ckckckckck ck ck ck ckckck k kk define LIN FRAME TIME MULTIPLIER 140 DoclD024013 Rev 2 Ly UM1593 2 Driver configuration 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 E AAA length of the break signal in bit times nr of bits recommended is 13 Please adjust LIN_FRAME_TIME_MULTIPLIER if necessary Okckckck ck ckckckckckckckckckckckckckckckckckck ck ckckckckckckckckckckckckckckckckck ck ckckckckckckckck ck k ck ck ckck kk k define LIN BREAK DURATION BITS 13 Accordin
44. ckckckck ck ckckckckckckckck ck ck ckckckckckckckckckckckckckckckckck ck kckckckckckckck ck k ck ckckck ko kk define LIN DIAGNOST C CLASS 1 ifdef LIN SLAVE NODE ifndef LIN Dl terror For a LI AGNOSTIC CLASS IN 2 1 slave node LIN Diagnostic Class is mandatory and must be defined IN 2 1 AGNOSTIC CLASS 1 AGNOSTIC CLASS 3 Diagnostic Class value can be 1 2 tendif dif LIN D LIN D terror Li tendif DoclD024013 Rev 2 Only class 3 slave nodes can reprogram the application via or 3 Ly UM1593 4 4 5 2 Driver configuration telse if defined LIN_MASTER_ONLY defined LIN_SLAVE_ONLY error A master node must support the Interleaved Diagnostics schedule Mode mandatory tendif tendif tendif LIN_21 f RCOKCKCkCk kk kk ck ck RRA kc kckckckckckokckckckckckckckckckckckckckckckckck ck ckckckckckckckck kkk kkk kkk ok LIN TP features Select by define ing TP is disabled by default Ckckckckckckckckckckckckckckckckckckckckckokckckckckckckckckckckckckckck kck ck kckckckckckckckck ck ck ck ckckck kc kc ko kk f RCKCKCkCk kk RR RRA RR RR RRE RR RR RRA RR RR RARA RR RR RRA kkk kkk the cooked diagnostic TP CKCk ck ck ck ckckckckckckckckckckokckckckckckckckckckckckckckckckckckokckckckckckckckckckckckckckckc kckck ko kckckckck k kJ undef LIN
45. ct 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 66 82 DoclD024013 Rev 2 STA UM1593 Examples 6 6 1 6 2 2 Examples Sample control file for lingen 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 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 specify that slave nodes will start with default frame IDs 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
46. d Prototype where iii denotes the interface to be initialized e g for the configured interface SCIO then the static prototype l bool 1 ifc init SCIO void Table 11 Connect interface ifc connect Prototype ifc connect function is obsolete for LIN 2 1 protocol and should not be used dynamic Table 12 Disconnect interface ifc disconnect Prototype yP ifc disconnect function is obsolete for LIN 2 1 protocol and should not be used dynamic Table 13 Wakeup ifc wake up Prototype i void 1l ifc wake up 1 ifc handle ifc dynamic Availability Master and slave nodes 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 ifc 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 l1 ifc wake up SCIO void Ly DoclD024013 Rev 2 15 82 API UM1593 Table 14 Interface control _ifc_ioctl Availability Master and slave nodes
47. dle ifc Availability Master and slave nodes Description This function returns the status of the raw frame receive queue see LIN 2 1 section 7 4 3 4 Parameters ifc interface handle LD DATA AVAILABLE receive queue contains data that can be read LD NO DATA receive queue is empty LD RECEIVE ERROR LIN protocol errors occurred during transfer Reinitialize and redo the transmission Return value Ly DoclD024013 Rev 2 29 82 API UM1593 3 4 5 Diagnostic Transport Layer COOKED API Table 34 Send message ld send message Protot p void ld send message 1 ifc handle ifc l_u16 length l_u8 nad const yp l u8 const pData Availability Master and slave nodes Include lin h 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 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 Description ifc interface handle length from 1 to 4095 bytes including SID or RSID i e message length plus on
48. dump from a slave node The slave may return up to 5 bytes via the buffer receiveBuf The application must call 1d is ready after the call to Description ld 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 None Ly DoclD024013 Rev 2 35 82 API UM1593 Table 46 Set Cooling Break ifc set cooling break Prototype void l1 ifc set cooling break 1 ifc handle ifc 1 bool on Availability Master node only Include lin h Descriotion 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 Prototype None Table 47 Set baud rate change baudrate void l1 change baudrate 1 ifc handle ifc l u16 baudrate Availability This function sets the baud rate for the specified interface This function should only be called Slave node only Description from the callback function that is invoked by the driver when an incorrect too high baud rate is detec
49. e 00000 cece ooo 39 4 3 Cluster configuration cone cs Seed ive Dew tata Shee see ww wee ee 40 4 3 1 Cluster description 0 40 4 3 2 Lingen tool tit aa eb ere ees eere n RENS 42 4 4 User configuration xax Rice RR CREE RUPEE ROCA AR RO RR ew yas 43 4 4 1 Te 43 4 4 2 General settings i 44 4 4 3 Diagnostic functions configuration i 48 4 4 4 Diagnostic class llle eh 49 4 4 5 Transport Protocol handling in LIN 2 1 Master 51 4 4 6 Callback functions llssseleese raar 60 4 5 Interrupt configuration sexag kx eee EX EG RR Boke e Ree Katee ha LER 63 Lingen control file specifications eee 65 5 1 Lingen control TG sy sis ds ae owt a ae bP aoe ale Lee ees 65 5 1 1 File definition iue mata Ge ee Be le E mee Ro Ua 65 5 1 2 Interface specification i 65 5 1 3 Default frame Identifiers et 65 5 2 Syntax specification es 65 Examples iua AREAS QE RE AGO A NU Gee nese M RR 67 6 1 Sample control file for lingen llle 67 6 2 LIN 2 0 LDF example master and slave oooooooooooo 67 6 3 LIN 2 1 LDF example master and slave node 73 6 4 Example implementation of IRQ callbacks master and slave 76 Architecture notes 0 a 77 7 1 CPU freqUueney aD 77 7 2 Interfaces cds picas a beans ieadh adad de eva era o he wae 77 7 3 lic se card T pesmi II er ees 77 7 4 Interrupt function configuration i 79 7 5 Using memory page cca eck need Oe
50. e 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 sequence number DoclD024013 Rev 2 31 82 API UM1593 3 5 Master specific API 3 5 1 Schedule management Table 38 Schedule tick sch tick Prototype 1 u8 1 sch tick 1 ifc handle ifc dynamic 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 frequency at which this function is called is given by the time base value set as part of the ma
51. e nad address of node not used in slave nodes pData pointer to the data to be sent Parameters Return value None Table 35 Receive message ld receive message void ld receive message 1 ifc handle ifc 1 u16 const length 1 u8 Prototype n const nad 1 u8 const pData Availability Master and slave nodes 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 1d 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 If the call is issued after the message 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 1d 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 Description 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
52. e 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 Ifa 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 1in_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 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 Normal communication schedule Diagnostic slave response schedule Normal co
53. e RSM node S S S s Poll the LSM node off ton error old OK error DoclD024013 Rev 2 Examples 75 82 Examples UM1593 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 l1 sys irq disable void SuspendOSInterrupts return 0 void l sys irq restore 1 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 2 76 82 DoclD024013 Rev 2 UM1593 Architecture notes 7 Architecture notes These architecture notes explains how to configure the LIN driver to run on STM8 microcontrollers 7 1 CPU frequency The CPU frequency must be configured in lin def stm8 h as follows RRRKRKR
54. ed boolean signal status then the prototype 1 bool val void l1 u8 wr sss void 1l u16 wr sss void 1 bool wr status 2 UM1593 API Table 6 Byte array read Prototype dynamic Availability Include bytes rd void 1 bytes rd 1 signal handle signalId l u8 const data 1l u8 start 1 u8 count Master and slave nodes 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 void 1 bytes rd sss 1 u8 start 1 u8 count 1 u8 const data Prototype where sss denotes the name of the signal to be read e g for the configured signal user data static then the prototype void 1l bytes rd user data l u8 start 1 u8 count 1 u8 const data Table 7 Byte array write bool wr u8 wr l u16 wr Prototype void 1 bytes wr 1 signal handle signallId 1_u8 start 1_u8 count dynamic const l1 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 t
55. 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 DoclD024013 Rev 2 71 82 Examples 72 82 frms13 frms21 frms22 frms23 slave2 LIN_protocol the startup configured_NAD 0x06 0x08 0x09 0x10 1 diagnostic address 23 Za schedule table definitions Schedule_tables this schedule table will participate in Ll the normal signals are transferred using schTabConfig AssignFrameld slave AssignFrameld slave AssignFrameld slave AssignFrameld slave AssignFrameld slave AssignFrameld slave AssignFrameld slave AssignFrameld slave AssignFrameld slave j table fy schTabl frmM1 delay 20 ms frms delay 20 ms frms2 delay 20 ms frmM2 delay 20 ms frmM3 delay 20 ms frms13 delay 20 ms frmM1 frmM2 frmM3 frms frms12 frms13 frms21 frms22 frms23 c2 c2 c2 c2 c2 c2 c2 42 DoclD024013 Rev 2 del del del del del del del del del lay lay lay lay lay lay lay lay lay 20 20 20 20 20 20 20 20 20 configure the slavel node to N communication S S S S S S 555558555858 this schedule UM1593
56. f LIN Dl terror For a LI AGNOSTIC CLASS IN 2 1 slave node LIN Diagnostic Class is mandatory and must be defined IN 2 1 AGNOSTIC CLASS 1 AGNOSTIC CLASS 3 Diagnostic Class value can be 1 2 tendif dif LIN D LIN D terror Li tendif DoclD024013 Rev 2 Only class 3 slave nodes can reprogram the application via or 3 Ly UM1593 2 Driver configuration telse if defined LIN_MASTER_ONLY defined LIN_SLAVE_ONLY error A LIN 2 1 master node must support the Interleaved Diagnostics schedule Mode mandatory tendif tendif tendif LIN_21 f RCKCKCkCk kk RR ckck kc kc kc kc kckckckckckckckck ck ckckckckckckckckckckckckckck ck ckckckckckckckck ck kckckckckck kk ck LIN TP features Select by define ing TP is disabled by default Ckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckckck ck ckckckckckckckckck ck ck ck ckckck kc kc ko kk f RCKCKCkCk kk RR RARA RR RR RRE RR RR RRA RR RR ck ck ckckckckckck kckckckckckckckck kk ok the cooked diagnostic TP undef LIN INCLUDE COOKED TP f RCKCKCkCk kk kk ck ck RARA RR RR RRE RR RR RRE RR RR RRE RR RR RRE ck K
57. faces 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 DoclD024013 Rev 2 Ly UM1593 2 Driver configuration 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 communicating 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 SCIO home LIN src lin config lin sciO ldf IFCO Lf specify that slave nodes will start with default frame IDs LIN_use_default_frame_ids 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 signa
58. g 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 FERRERA RR kckck ck ckckckckckckckck ck ckckckckckckckckckckckckckckckckckck kk kkk kkk kkk kkk kkk kk 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 Tf 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 kckckck ck ckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ckckckckckckckckck ck ckckckckck kck ck ck ck ckckck k kk tundef LIN FORCE STANDALONE BREAK Addi
59. guration 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 Prototype Table 27 Set configuration Id set configuration l u8 1d set configuration 1 ifc handle ifc const 1 u8 const data l u16 length Availability Description Parameters Slave node only This function configures the NAD and the PIDs according to the configuration specified by data lt does 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 f
60. hanging 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 DoclD024013 Rev 2 7 82 Overview UM1593 The driver is consequently 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 technique 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 From the master node to one or more slave nodes e From a slave node to the 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 belong
61. he 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 Return value Prototype static count the number of bytes to be written data the area where the bytes will be read from None void 1 bytes wr sss 1 u8 start 1 u8 count const 1 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 1l bytes wr user data 1 u8 start data l u8 count const l u8 const 2 DoclD024013 Rev 2 13 82 API UM1593 3 3 3 Notification Table 8 Test flag flg tst Prototype l bool 1 flg tst 1 flag handle flag dynamic Availability Master and slave nodes This function returns the state of the flag specified i e zero if cleared non zero otherwise see LIN 2 1 section 7 2 3 1 Description flag the flag which state is to be returned e g for the configured flag Txerror then LIN FLAG Txerror Return 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 Parameters Ta
62. hen 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 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 f ECKCKCk kc kckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ckckckckckck kckck ck ckckckckckc kckck ck ck KKK KKK 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 kckckck ck ckckckckckckckck ck kckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck kckckckckckckck ck ck ck ckckck k kk
63. hroughout the application LIN LINGEN CONTROL Name of the control file used by lingen Options to be used by the lingen tool Details of options are given in Section 4 3 LIN LINGEN OPTS 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 path to MakeLIN Make LIN where lt path to MakeLIN gt specifies the location of Make LIN The generation of the LIN library can then be included as follows make S LIN OBJ PATH lin lib or by including LIN OBJ PATH lin lib in the target build instruction 2 DoclD024013 Rev 2 39 82 Driver configuration UM1593 4 3 4 3 1 40 82 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 a
64. ile 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 2 42 82 DoclD024013 Rev 2 UM1593 Note 4 4 4 4 1 2 Driver configuration Table 51 Options Name Description Specifies which of the possible configurations given in the LDF will be used c configuration 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 1af default the lingen tool determines the checksum model from the information given in the LDF both the driver accepts either model for all frames r receiveChecksum Selects the checksum model to be used for sending frames Possible values are 1df 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 s sendChecksum 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 a
65. ine statement define LIN MASTER ONLY LIN TAB TableNamel define LIN SLAVE ONLY LIN TAB TableName2 2 DoclD024013 Rev 2 55 82 Driver configuration UM1593 Figure 8 Continued execution of diagnostic slave response schedule table until response received External test tool Diagnostic request to slave node Pote 0 Active schedule table Diagnostic master request schedule Master request frame Normal communication schedule Diagnostic slave response Slave response frame po schedule without response Normal communication schedule iD 0x3D A gt Slave response frame without response Diagnostic slave response schedule Normal communication schedule ID 0x3D ae RO i gt Slave response frame CH with response SF Diagnostic slave response schedule ame IE ame Came me RES Diagnostic response 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
66. ing 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 Figure 1 Master slave node communications master node slave node signals frames LIN API LIN API operating system gt operating system 8 82 2 DoclD024013 Rev 2 UM1593 2 3 2 4 Note 2 Overview 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 bytes 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
67. ion 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 O 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 Return value l u16 1 ifc read status iii void Prototype where iii denotes the interface which status is to be read e g for the configured static interface SCIO then the prototype void 1 ifc read status SCIO void 2 DoclD024013 Rev 2 21 82 API UM1593 Table 18 Description of _ifc_read_status returned value Last frame PID 0 Event Save triggered Bus Go to Successful Response i Mh Overrrun configuration frame activity sleep transfer error collision 3 4 Diagnostic API 3 4 1 Node Configuration specific API diagnostic Table 19 Diagnostic module ready Prototype 1 u8 ld is ready 1 ifc handle ifc Availability Master node only Id is ready lin h Description This function returns the status of the last reques
68. is file controls the building process and is designed to be included in the top level makefile 2 DoclD024013 Rev 2 UM1593 Driver configuration 4 2 1 Top level makefile Predefined variables This file must include the definitions for the following variables Table 50 Top level makefile predefined variable definition Name Description This variable must be set to MASTER_NODE for a master node driver or FINSNODE DENNY 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 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 1lin_def h lin def c and lin def archname h must be located in this directory The file LIN CEG PATM lin def archname his 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 t
69. kck kck ck ck ck ckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck kck ck ckckckckck ck kockckckck k kk 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 4 4 4 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 Do a crosscheck between LDF and the same class to understand if the slave node is able to perform the diagnostic e Understand which diagnostic services the slave node is able to respond to e Know which configuration and identification services is supported e Understand if the slave node is able to support the Transport Protocol e Understand if the slave node is able to be reprogrammed only class 3 2 DoclD024013 Rev 2 49 82 Driver configuration 50 82 UM1593 EEE ck ckckckckckckckck ck ckckckckckck kckck ck ckck ck ckck kckck ck ck KKK KKK 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 DIAGNOSTIC CLASS 1 sufficient Single frames are supported The slave does not support any other diagnostic services SF transport protocol support is
70. kckck ck ckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckck ck ckckckckckckckckck ck ck ckckckckckck ck ck ck ckckck k kk Only the node configuration services Node Identification is limited to the mandatory read by identifier service Node configuration and identification parameters S3 DIAGNOSTIC CLASS 3 Services are supported Full transport layer implementation is required multi frame transmissions Node Identification is extended to all the Read By d 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 D Ox2E if applicable Node configuration and identification to support Class identifier 0 ACA F ACA 0X CAC F F 0X F F Xo Ro F Xo 0o F EC ACA OX Xo Xo Xo F Xo X Additionally d services Slave nodes shall support all services as of 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 0x2F Read and clear DTC SID 0x19 0x14 the LIN bus kckckck ck ckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckckckckckckckckckckckck ck kckckckckckckck ck k ck ckckck ko kk define LIN DIAGNOST C CLASS 1 ifdef LIN SLAVE NODE ifnde
71. kckckck ck ckckckckckckckck ck ck ck ckckck kc k k k 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 Okckckckck ckckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck ck ck ckckckckckck ck kockckckck k kk 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 shorter time frame then the master may start sending earlier This time delay must be configured using the following definition f ECKCKCk kc kckckckckckckckck ck ckckckckckckckck ck ck ck ckckckckckck ck ckckckckckckckckck ck ckckckckck kckck ck ck ck ckckck ko kc 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
72. l 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 sig1 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 DoclD024013 Rev 2 41 82 Driver configuration UM1593 4 3 2 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 lingen are described in Figure 3 Figure 3 Lingen workflow LDF File lingen exe mmm e j listed in input output The lin_cfg_types h file 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 wh
73. le 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 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 schedule iii new schedule handle for the interface ifc entry entry point in the new schedule Return value Prototype static None void 1_sch_set_iii 1 schedule 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 1l u8 entry Table 40 Goto sleep 2 ifc goto sleep Prototype void 1 ifc goto sleep 1 ifc handle ifc dynamic 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
74. llowing data types must be defined for the driver bool u8 u16 u32 ioctl op irqmask 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 Functions The numbering in the description sections below refers to the LIN API specification section where the corresponding function is described CORE API Driver and cluster management Table 3 System Initialization I sys init void Prototype l bool 1 sys init void Availability Master and slave nodes This function performs the initialization of the LIN core LIN API 7 2 1 1 The scope of the initialization is the physical node i e the complete node see LIN 2 1 section 9 2 3 3 Description The callto 1 sys initis the first call the user application must issue in the LIN core before calling any other API functions Parameters None zero if initialization succeeded Return value non zero if initialization failed 2 DoclD024013 Rev 2 11 82 3 3 2 API UM1593 Signal interaction Table 4 Scalar signal read Prototype dynamic _bool_rd _u8_rd _u16_rd l bool 1 bool rd 1 signal handle signalId l u8 1 u8 rd 1 signal handle signalld l u16 1 u16 rd 1 signal handle signalId Availability Include Description Master and slave nodes lin h These functions read and
75. m 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 void l ifc rx iii void Prototype where iii denotes the interface that received data e g for the configured interface SCIO then static the prototype void l ifc rx SCIO void Table 16 Character transmission notification ifc tx Prototype I void 1 ifc tx 1 ifc handle ifc dynamic Availability Master and slave nodes 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 interrupt 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
76. ment 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 improve 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 inthe lin def stm8 h file This is done as follows f RCKCKCk kc kckckckckckckckck ck ck ckckckckckckck ck ckckckckckckck ck ck ckckckckckckckckckckckckckckckckck ck ckckckckckckckckck kck ckckck k Optimisation for STM8 Give size available in fastest most efficient memory area you can spare for the LIN driver in bytes Okckckck ck ckckckckckckckck ck ck ckckckckckckck ck ckckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckck ck kck ck ckck kc k ck ck KKK KK 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 tundef LIN TX FLAGS IN ZERO PAGE tundef LIN RX FLAGS IN ZERO PAGE tundef LIN CHANGED FLAGS IN ZERO PAGE tundef
77. mes 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 contains 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 Use the 1 ifc _ioctl 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 DoclD024013 Rev 2 37 82 Driver configuration UM1593 4 4 1 4 2 38 82 Driver configuration This section describes the configuration and the hardware specific settings required a
78. mmunication schedule DoclD024013 Rev 2 53 82 Driver configuration UM1593 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 M M Y LA 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 subseque
79. nad address of node not used in slave nodes pData pointer to buffer into which the data will be written Return value None 2 30 82 DoclD024013 Rev 2 UM1593 API Table 36 Get transmit queue status Id_tx_status Prototype u8 1d 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 1d send message see LIN 2 1 section 7 4 4 3 Parameters Return value Prototype ifc interface handle 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 reinitialized 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 u8 ld rx status I ifc handle ifc Availability Master and slave nodes 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 valu
80. nd explains how to build the driver 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 is 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 slave general as given LIN_SRC_PATH diag as given timer as given arch_name specifies the specific architecture for archi arch name which the driver will be built 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 th
81. nd lin def archname h where archname refers to a specific architecture e lin def archname h contains the architecture dependent settings see Section 7 Architecture notes e 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 architecture see Section 7 Architecture notes for the possible values The timer timebase is configured in lin def nh 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 DoclD024013 Rev 2 43 82 Driver configuration UM1593 4 4 2 44 82 The recommended value for the timebase is either 1 or 2 ms It is set as follows RRRRRRRRREREKRKEKKR ck ckckckckckckckck ck ckckckckckckckckckckckckckckckckckckckckckckckckckckck ck ck kkk kkk k k Set the time base of
82. nd then return non zero to the driver If no response is to be sent then return zero to the driver Description Note When a response is to be returned 5 bytes will always be transferred sendBuf the buffer sent by the master Parameters F T 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 callback 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 2 62 82 DoclD024013 Rev 2 UM1593 4 5 2 Driver configuration Table 57 Baud rate detection callback baudrate callback iii Prototype void 1 baudrate callback iii 1 u16 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 corre
83. nt diagnostic schedules complies with the OEM specific diagnostic requirements 2 54 82 DoclD024013 Rev 2 UM1593 Driver configuration Figure 7 Diagnostic Interleaved mode Active schedule table Normal communication schedule Diagnostic master request schedule Normal communication schedule Diagnostic slave response schedule i LIA EA Py 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 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 AP2max 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 def
84. nt 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 2014 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 82 82 DoclD024013 Rev 2 Ly
85. 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 j 2 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 DoclD024013 Rev 2 57 82 Driver configuration 58 82 UM1593 EEE ck ckckckckckckckck ck ckckckckckck kckck ck ckck ck ckck kckck ck ck KKK KKK 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 DIAGNOSTIC CLASS 1 sufficient Single frames are supported The slave does not support any other diagnostic services SF transport protocol support is DIAGNOSTIC CLASS 2 services are supported Full transport layer implementation is required to support multi frame transmissions Node Identification is extended to all the Read By kc
86. onventions LIN SIGNAL sigName signal sigName frame frameName LIN FRAME frameName schedule table LIN TAB tabName node nodeName LIN NODE nodeName DoclD024013 Rev 2 9 82 UM1593 Overview 2 5 10 82 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 1 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 atthe root of the source directory This information is used to ensure that only consistent files are included when building the driver 2 DoclD024013 Rev 2 UM1593 3 3 1 3 2 API API Data The fo
87. or occurred and that the slave node did not receive any negative configuration response 2 DoclD024013 Rev 2 UM1593 API Figure 2 successful configuration request and response LD_SERVICE_IDLE LD_SERVICE_BUSY LD_REQUEST_FINISHED LD SERVICE IDLE E LEE Slave Response Frame Master Request Frame Configuration service called Table 20 Check configuration response Id check response Prototype void 1d_check_response l_ifc_handle ifc 1_u8 const pRsid 1_u8 const yp 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 ID range ld assign frame id range Void ld assign frame id range 1l 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
88. rames 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 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 26 82 DoclD024013 Rev 2 Ly UM1593 API 3 4 2 Node Identification specific API diagnostic Table 28 Read by ID Id read by id Prototype void ld read by id 1 ifc handle ifc l_u8 nad l_u16 supplier_id l_u16 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 nad and supplier id When the next call to 1d is ready returns LD_SERVICE_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 idis 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
89. re 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 f 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 j 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 sciO ldf listed above will appear in the code as LIN SIGNAL IFCO sl sig1 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 inter
90. rectory The function prototypes are defined as follows Table 52 Disable Interrupts sys irq disable Prototype l irqmask 1l sys irq disable void Availability Master and slave nodes A 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 Prototype Availability Description Parameters Table 53 Restore Interrupts sys irq restore void l sys irq restore l1 irqmask irqMask Master and slave nodes This function restores the interrupt level identified by the irgMask parameter irgMask mask containing the state of the interrupts to be restored Return value None 2 DoclD024013 Rev 2 UM1593 2 Driver configuration An implementation example is given in Section 6 4 Example implementation of IRQ 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 desc
91. rescaler and reload values must be configured For the 4 most common configurations these values are already given in the 1in stm8 h file see Table 61 Table 61 Hardware timer configuration idt Time base Prescaler Reload Note 9 y ms value value Hz 16 000 000 2 7 16 MHz 27 250 gt 2 ms timebase 8 000 000 2 7 16 MHz 27 125 gt 2 ms timebase 16 000 000 1 6 16 MHz 26 250 gt 1 ms timebase 8 000 000 1 5 16 MHz 25 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 2 DoclD024013 Rev 2 UM1593 7 4 7 5 2 Architecture notes The description of 1 timerISR is given below Table 62 Hardware timer interrupt service routine timerlSR Prototype void 1 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 Manage
92. return the current value of the specified signal see LIN 2 1 section 7 2 2 2 Parameters signalId name of the signal to be read e g for the configured signal status then LIN SIGNAL status Return value bool boolean signal value or 0 if signal Ta is invalid u8 8 bit signal value or O if signalTd is invalid u16 16 bit value or 0 if signalTd is invalid Prototype static l bool 1 bool rd sss 1 u8 1 u8 rd sss void l u16 1 u16 rd sss void where sss denotes the name of the signal that is to be read e g for the configured boolean signal status then the prototype l bool 1 bool rd status void void Table 5 Scalar signal write bool wr u8 wr l u16 wr Prototybe void 1_bool_wr 1 signal handle signalId l_bool val d Sn void 1 u8 wr 1 signal handle signalId 1 u8 val i y void 1 u16 wr 1 signal handle signalId 1 u16 val Availability Master and slave nodes Include lin h Description These functions set the current value of the specified signal to va1 see LIN 2 1 section 7 2 2 3 signalla 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 be set Return value None Prototype static 12 82 DoclD024013 Rev 2 void 1 bool wr sss 1l bool val 1 u8 val 1 u16 val where sss denotes the name of the signal which value is to be set to va1 e g for the configur
93. ribed 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 1 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 feature include the following define statement in 1in def h define LIN PROTOCOL SWITCH Table 54 Protocol switch function callback protocol callback iii void 1 protocol callback iii void Protot PS 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 1 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 DoclD024013 Rev 2 61 82 Driver configuration UM1593 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 proto
94. s 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 0 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 l ul6 1 ifc ioctl iii l 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 u16 1 ifc ioctl SCIO 1 ioctl op operation void pParams 2 DoclD024013 Rev 2 UM1593 API Table 15 Character reception notification ifc rx Prototype void 1 ifc rx 1l 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 progra
95. 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 DoclD024013 Rev 2 UM1593 2 UM1593 2 error signal qs 0 Slavel master errorSignalSlave errorSignalSlave2 1 0 slave2 master signal definition diagnostic signals optional but recommended Diagnostic_signals MasterReqBO0 MasterReqB1 MasterReqB2 MasterReqB3 MasterReqB4 MasterRegBb5 MasterReqB6 MasterRegB7 SlaveRespBO SlaveRespBl SlaveRespB2 SlaveRespB3 SlaveRespB4 SlaveRespBb5 SlaveRespB6 SlaveRespB7 gt S ins im im ME A fas S gt OO OO OO 00 00 00 COO COO COO COO OO COO ao OO COO cH So Se 5 5 5 Se se So Se Se Se 5 Se se O GOG OGOGOGOOaOGOGOGOOO OQOGOQOG se frame definition unconditional frames Frames frames published by the master frmM1 0 master masterDIPState 1 frmM2 1 master masterDIPState2 frmM3 2 master masterDIPState masterDIPState 35 4 2 0 1 0 1 0 1 DoclD024013 Rev 2
96. sponding callback Description ifc interface handle Parameters baudrate the baud rate currently detected i e the incorrect baud rate on the interface Return value None 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 interrupt 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 ifc rx Prototype void 1l 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 1_ ifc rx iii void prototype Description handles the interrupt for the interface given by iii Include lin h DoclD024013 Rev 2 63 82 Driver configuration 64 82 Table 59 Handler for character tx UM1593 ifc
97. ster node configuration Since the period at 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 Description Parameters ifc interface handle 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 Return value 1l u8 l sch tick iii void Prototype where iii denotes the interface for which transmission of frames is to be initiated e g for the static configured interface SCIO then the prototype u8 1 sch tick SCIO void Table 39 Set schedule table Prototype dynamic void l1 sch set 1 ifc handle ifc schedule iii l u8 entry l schedule handle Availability Master node only lin h Include 2 32 82 DoclD024013 Rev 2 UM1593 API Table 39 Set schedule table continued Description Parameters sch set This function sets up the next schedu
98. ted 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 Prototype void ld raw tx delete l ifc handle ifc Availability Master and slave nodes Include lin h 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 Return value 1 if a frame has been removed 0 if no Raw Tx frame was on the stack 36 82 2 DoclD024013 Rev 2 UM1593 3 8 3 8 1 3 8 2 2 API Implementation 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 handle and 1 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 fra
99. ted 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 Parameters Return value 22 82 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 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 err
100. tionally 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 f ECKCKCk kc kckckckckckckckck ck ckckckckckckckck ck ckckckckckckckckckckckckckckckckckck ck ckckckckckckckck ck ck kkk kkk k k Activate the Cooling option with define LIN USE COOLING Deactivate it with undef IN USE COOLING Okckckck ck ckckckckckckckckckckckckckckckckckck ck ckckckckckckckckckckckckckckckckck ck ck ckckckckckckck ck RR ck ckck kk k define LIN USE COOLING and the break length set ifdef LIN USE COOLING DoclD024013 Rev 2 45 82 Driver configuration UM1593 46 82 RRRKRKRRRKRKERKKKRKRKKREKRKKKK ckckckckckckckckck ck ckckckckckckckck ck ck ckckckckckckck ck ck ckckck ko k k k length of the break signal in bit times nr of bits Please adjust LIN FRAME TIME MULTIPLIER if necessary kckckck ck ckckckckckckckckck ck ckckckckckckckck ck ckckckckckckckck ck kckckckckckckckck ck kckckckck kckck ck ck kc kc kk define LIN COOLING BREAK DURATION BITS 36 endif Activating the Cooling feature provides the user with an additional interface function 1 ifc set cooling break that can be called from the application w
101. type forms For these two callbacks empty implementations are included in the file 1in_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 1d readByIdCallback l u8 id 1 u8 pBuffer This function provides a response in accordance with the id request sent from the master This callback will be called by the slave driver when the id given 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 a pBuffer 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 1d dataDumpCallback 1l u8 sendBuf l1 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 recBu 0 a
102. 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 2 DoclD024013 Rev 2 23 82 API UM1593 Table 22 Assign diagnostic address Id_assign_NAD Prototype void l assign NAD 1 ifc nana TE ifc l_u8 initial nad 1_ul6 supplier id 1 u16 function id 1 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 idto the value in new nad See LIN2 1 section 7 3 1 4 ifc addressed interface initial nad nad ofthe nodes to be re assigned Parameters supplier id supplier id of the nodes function id function id of the nodes new nad the new nad to be assigned to the nodes Return value None Table 23 Save configuration ld save configuration Prototype void ld save configuration 1l ifc handle ifc 1 u8 nad Availability Master node only Include lin h Describtidn 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
103. urn value None void 1 ifc aux iii void where iii denotes the interface e g for the configured interface SCIO then the prototype void 1 ifc aux SCIO void Prototype static Table 42 Read by ID callout Id read by id callout Prototype u8 1d read by id callout 1 ifc handle ifc 1 u8 id 1 u8 data Availability Slave node only optional if itis 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 identifier in the user defined area When such a request is received the slave node application is called from the driver see LIN 2 1 section 7 3 3 2 Description ifc interface handle id identifier in the user defined area 32 to 63 from the read by identifier configuration Parameters request see LIN 2 1 Table 4 19 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 Return value 2

STSW-STM8A-LIN software package

Contents

Download Pdf Manuals

Related Search

Related Contents