iLLD_TC27xC  1.0
IfxAsclin_Lin.h
Go to the documentation of this file.
1 /**
2  * \file IfxAsclin_Lin.h
3  * \brief ASCLIN LIN details
4  * \ingroup IfxLld_Asclin
5  *
6  * \version iLLD_0_1_0_10
7  * \copyright Copyright (c) 2013 Infineon Technologies AG. All rights reserved.
8  *
9  *
10  * IMPORTANT NOTICE
11  *
12  *
13  * Infineon Technologies AG (Infineon) is supplying this file for use
14  * exclusively with Infineon's microcontroller products. This file can be freely
15  * distributed within development tools that are supporting such microcontroller
16  * products.
17  *
18  * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED
19  * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
20  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
21  * INFINEON SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL,
22  * OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
23  *
24  * \defgroup IfxLld_Asclin_Lin_Usage How to use the ASCLIN LIN Interface driver?
25  * \ingroup IfxLld_Asclin
26  *
27  * The LIN interface driver provides a default ASCLIN configuration for asynchronous serial communication in 8bit mode, and a set of data transfer routines.
28  * It supports all four elementary LIN transactions
29  * TxH - Transmission of Header
30  * TxR - Transmission of Response
31  * RxH - Reception of Header
32  * RxR - Reception of Response
33  *
34  * In the following sections it will be described, how to integrate the driver into the application framework.
35  *
36  * \section IfxLld_Asclin_Lin_Preparation Preparation
37  * \subsection IfxLld_Asclin_Lin_Include Include Files
38  *
39  * Include following header file into your C code:
40  * \code
41  * #include <Asclin/Lin/IfxAsclin_Lin.h>
42  * \endcode
43  *
44  * \subsection IfxLld_Asclin_Lin_Variables Variables
45  *
46  * Declare the LIN handle as global variable in your C code:
47  *
48  * \code
49  * // used globally
50  * static IfxAsclin_Lin lin;
51  * \endcode
52  *
53  * \subsection IfxLld_Asclin_Asc_Init Module Initialisation
54  *
55  * The module initialisation can be done in the same function. Here an example:
56  * \code
57  * // create module config
58  * IfxAsclin_Lin_Config linConfig;
59  * IfxAsclin_Lin_initModuleConfig(&linConfig, &MODULE_ASCLIN1);
60  *
61  * // set the lin mode of operation
62  * linConfig.linMode = IfxAsclin_LinMode_master;
63  *
64  * // set the desired baudrate
65  * linConfig.btc.prescaler = 4;
66  * linConfig.brg.baudrate = 19200; // FDR values will be calculated in initModule
67  *
68  * // pin configuration
69  * const IfxAsclin_Lin_Pins pins = {
70  * &IfxAsclin1_RXB_P15_5_IN, IfxPort_InputMode_pullUp, // Rx pin
71  * &IfxAsclin1_TX_P15_4_OUT, IfxPort_OutputMode_pushPull, // Tx pin
72  * IfxPort_PadDriver_cmosAutomotiveSpeed1
73  * };
74  * linConfig.pins = &pins;
75  *
76  * // initialize module
77  * //IfxAsclin_Lin lin; // defined globally
78  * IfxAsclin_Lin_initModule(&lin, &linConfig);
79  * \endcode
80  *
81  * The LIN is ready for use now!
82  *
83  * \section IfxLld_Asclin_Lin_DataTransfers Data Transfers
84  *
85  * \subsection IfxLld_Asclin_Lin_DataMaster Master Transfers
86  *
87  * The LIN driver provides all three master elemnatry tranfers.
88  *
89  * This means: you can send a header and based on the id byte, after transmission of header
90  * you can send or receive response and also can ignore the header based on the id:
91  * \code
92  * // set the id bytes
93  * uint8 txId = 0x80 // for sending respose after header
94  * uint8 rxId = 0xC1 // for receiving respose after header
95  *
96  * // prepare transmit bytes incase of sending response
97  * uint8 txData[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };
98  *
99  * // prepare receive buffer incase of receiving response
100  * uint8 rxData[8] = { 0, 0, 0, 0, 0, 0, 0, 0 };
101  *
102  * uint32 size = 8;
103  *
104  * //send response case
105  * IfxAsclin_Lin_sendHeader(&lin, &txId);
106  *
107  * if (lin.acknowledgmentFlags.txHeaderEnd == 1) // if the header is been transmitted succesfully
108  * {
109  * IfxAsclin_Lin_sendResponse(&lin, txData, size);
110  * }
111  *
112  * //receive response case
113  * IfxAsclin_Lin_sendHeader(&lin, &rxId);
114  *
115  * if (lin.acknowledgmentFlags.txHeaderEnd == 1) // if the header is been transmitted succesfully
116  * {
117  * IfxAsclin_Lin_receiveResponse(&lin, rxData, size);
118  * }
119  * \endcode
120  *
121  * \subsection IfxLld_Asclin_Lin_DataSlave Slave Transfers
122  *
123  * Same as master the LIN driver provides all three slave elemnatry tranfers.
124  *
125  * This means: you can receive a header and based on the id byte received,
126  * you can send or receive response and can also ignore the header based on the id:
127  * \code
128  * uint8 id; // for storing received id byte
129  *
130  * // prepare transmit bytes incase of sending response
131  * uint8 txData[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };
132  *
133  * // prepare receive buffer incase of receiving response
134  * uint8 rxData[8] = { 0, 0, 0, 0, 0, 0, 0, 0 };
135  *
136  * uint32 size = 8;
137  *
138  * // receive header
139  * IfxAsclin_Lin_receiveHeader(&lin, &id);
140  *
141  * // if data is requsted by master
142  * if(id == txId)
143  * {
144  * IfxAsclin_Lin_sendResponse(&lin, txData, size); // send response
145  * }
146  *
147  * // if header is follwed by response
148  * else if(id == rxId)
149  * {
150  * IfxAsclin_Lin_receiveResponse(&lin, rxData, size); // receive response
151  * }
152  *
153  * // if header is not for this slave
154  * else
155  * {
156  * IfxAsclin_Lin_ignoreHeader(&lin);
157  * }
158  * \endcode
159  *
160  * \defgroup IfxLld_Asclin_Lin LIN
161  * \ingroup IfxLld_Asclin
162  * \defgroup IfxLld_Asclin_Lin_DataStructures Data Structures
163  * \ingroup IfxLld_Asclin_Lin
164  * \defgroup IfxLld_Asclin_Lin_ElementaryTransactions Elementary Transactions
165  * \ingroup IfxLld_Asclin_Lin
166  * \defgroup IfxLld_Asclin_Lin_ModuleFunctions Module Functions
167  * \ingroup IfxLld_Asclin_Lin
168  * \defgroup IfxLld_Asclin_Lin_errorHandlingFunctions Error Handling Functions
169  * \ingroup IfxLld_Asclin_Lin
170  */
171 
172 #ifndef IFXASCLIN_LIN_H
173 #define IFXASCLIN_LIN_H 1
174 
175 /******************************************************************************/
176 /*----------------------------------Includes----------------------------------*/
177 /******************************************************************************/
178 
179 #include "Asclin/Std/IfxAsclin.h"
181 
182 /******************************************************************************/
183 /*-----------------------------------Macros-----------------------------------*/
184 /******************************************************************************/
185 
186 #define IFXASCLIN_LIN_SEND_RESPONSE (0x80)
187 
188 #define IFXASCLIN_LIN_RECEIVE_RESPONSE (0xC1)
189 
190 /******************************************************************************/
191 /*-----------------------------Data Structures--------------------------------*/
192 /******************************************************************************/
193 
194 /** \addtogroup IfxLld_Asclin_Lin_DataStructures
195  * \{ */
196 /** \brief Structure for Acknowledgement Flags
197  */
198 typedef struct
199 {
200  uint8 txHeaderEnd : 1; /**< \brief transmit header end */
201  uint8 txResponseEnd : 1; /**< \brief transmit response end */
202  uint8 rxHeaderEnd : 1; /**< \brief receive header end */
203  uint8 rxResponseEnd : 1; /**< \brief receive response end */
205 
206 /** \brief Structure for Baudrate Detection
207  */
208 typedef struct
209 {
210  boolean abd; /**< \brief LINCON.ABD, autobaud detection enable */
211  uint8 lowerLimit; /**< \brief BRD.LOWERLIMIT, auto baudrate detection lowerlimit */
212  uint8 upperLimit; /**< \brief BRD.UPPERLIMIT, auto baudrate detection upperlimit */
213  uint8 measured; /**< \brief BRD.MEASURED, measured time interval between the
214  * first and the fifth falling edge of the sync byte */
216 
217 /** \brief Structure for Baudrate Generation
218  */
219 typedef struct
220 {
221  float32 baudrate; /**< \brief value of the required baudrate */
222  uint16 numerator; /**< \brief BRG.NUMERATOR, defines the numerator of fractional divider */
223  uint16 denominator; /**< \brief BRG.DENOMINATOR, defines the denominator of fractional divider */
225 
226 /** \brief Structure for Bit Sampling
227  */
228 typedef struct
229 {
230  uint8 filterDepth; /**< \brief IOCR.DEPTH, digital glitch filter depth */
231  IfxAsclin_SamplesPerBit medianFilter; /**< \brief BITCON.SM, no. of samples per bit 1 or 3 */
232  IfxAsclin_SamplePointPosition samplePointPosition; /**< \brief BITCON.SAMPLEPOINT, sample point position */
234 
235 /** \brief Structure for Bit Timing
236  */
237 typedef struct
238 {
239  uint16 prescaler; /**< \brief BITCON.PRESCALER, predivider to generate the baud rate */
240  IfxAsclin_OversamplingFactor oversampling; /**< \brief BITCON.OVERSAMPLING, postdivider, used for oversampling */
242 
243 /** \brief Structure for Data Control
244  */
245 typedef struct
246 {
247  IfxAsclin_DataLength dataLength; /**< \brief DATCON.DATALENGTH, data length, number of bits per transfer */
248  IfxAsclin_HeaderResponseSelect headerOnly; /**< \brief DATCON.HO, Lin frame with header and response or header only */
249  IfxAsclin_LinResponseTimeoutMode responseTimeoutMode; /**< \brief DATCON.RM, response mode (response or frame timeout threshold) */
250  IfxAsclin_Checksum checksum; /**< \brief DATCON.CSM, checksum mode (classic or enhanced) */
251  uint16 responseTimeout; /**< \brief DATCON.RESPONSE, timeout limit */
253 
254 /** \brief Structure for Error Flags
255  */
256 typedef struct
257 {
258  uint8 frameError : 1; /**< \brief frame error */
259  uint8 headerTimeout : 1; /**< \brief header timeout */
260  uint8 responseTimeout : 1; /**< \brief response timeout */
261  uint8 breakDetected : 1; /**< \brief break detected */
262  uint8 linParityError : 1; /**< \brief lin parity error */
263  uint8 linAutobaudDetectionError : 1; /**< \brief lin autobaud detection error */
264  uint8 linChecksumError : 1; /**< \brief lin checksum error */
265  uint8 collisionDetectionError : 1; /**< \brief collision detection error */
266  uint8 rxFifoOverflow : 1; /**< \brief receive FIFO overflow error */
267  uint8 txFifoOverflow : 1; /**< \brief transmit FIFO overflow error */
269 
270 /** \brief Structure for FIFO Control
271  */
272 typedef struct
273 {
274  IfxAsclin_ReceiveBufferMode buffMode; /**< \brief RXFIFOCON.BUF, receive buffer mode (RXFIFO or RXBuffer) */
275  IfxAsclin_TxFifoInletWidth inWidth; /**< \brief TXFIFOCON.INW, transmit FIFO inlet width */
276  IfxAsclin_RxFifoOutletWidth outWidth; /**< \brief RXFIFOCON.OTW, receive FIFO oulet width */
278 
279 /** \brief Structure for Frame Control
280  */
281 typedef struct
282 {
283  IfxAsclin_IdleDelay idleDelay; /**< \brief FRAMECON.IDLE, idle delay */
284  IfxAsclin_LeadDelay leadDelay; /**< \brief FRAMECON.LEAD, lead delay */
285  IfxAsclin_StopBit stopBit; /**< \brief FRAMECON.STOP, number of stop bits */
286  IfxAsclin_ParityType parityType; /**< \brief FRAMECON.ODD, parity type (even or odd) */
287  IfxAsclin_ShiftDirection shiftDir; /**< \brief FRAMECON.MSB, shift direction */
288  boolean parityEnable; /**< \brief FRAMECON.PEN, parity enable */
289  boolean collisionDetectionEnable; /**< \brief FRAMECON.CEN, collision detection enable */
291 
292 /** \brief Structure for lin Control
293  */
294 typedef struct
295 {
296  boolean csEnable; /**< \brief LINCON.CSEN, hardware checksum generation and checking */
297  IfxAsclin_ChecksumInjection csi; /**< \brief LINCON.CSI, checksum injection (not written or written) into RxFIFO */
298  uint16 breakLength; /**< \brief LINBTIMER.BREAK, break pulse generation and detection length */
299  uint16 headerTimeout; /**< \brief LINHTIMER.HEADER, header timeout threshold value */
301 
302 /** \brief Structure for LIN pin configuration
303  */
304 typedef struct
305 {
306  const IfxAsclin_Rx_In *rx; /**< \brief LIN Rx pin */
307  IfxPort_InputMode rxMode; /**< \brief rx pin as input */
308  const IfxAsclin_Tx_Out *tx; /**< \brief LIN Tx pin */
309  IfxPort_OutputMode txMode; /**< \brief tx as output */
310  IfxPort_PadDriver pinDriver; /**< \brief pad driver */
312 
313 /** \} */
314 
315 /** \addtogroup IfxLld_Asclin_Lin_DataStructures
316  * \{ */
317 typedef struct
318 {
319  Ifx_ASCLIN *asclin; /**< \brief pointer to ASCLIN registers */
320  IfxAsclin_LinMode linMode; /**< \brief LINCON.MS, lin mode of operation (master or slave) */
321  IfxAsclin_Lin_AcknowledgementFlags acknowledgmentFlags; /**< \brief structure for acknowledgement flags */
322  IfxAsclin_Lin_ErrorFlags errorFlagsStatus; /**< \brief structure for error flags status */
323  boolean receiveIdEnable; /**< \brief setting to receive Id in Rx Fifo after sending it */
324 } IfxAsclin_Lin;
325 
326 /** \brief Configuration structure of the module
327  */
328 typedef struct
329 {
330  Ifx_ASCLIN *asclin; /**< \brief pointer to ASCLIN registers */
331  IfxAsclin_FrameMode frameMode; /**< \brief FRAMECON.MODE, mode of operation of the module (ASC, SPI, LIN) */
332  IfxAsclin_LinMode linMode; /**< \brief LINCON.MS, lin mode of operation (master or slave) */
333  IfxAsclin_Lin_BaudrateGeneration brg; /**< \brief structure for baudrate generation */
334  IfxAsclin_Lin_BaudrateDetection brd; /**< \brief structure for baudrate detection */
335  IfxAsclin_Lin_BitTimingControl btc; /**< \brief structure for bit timings */
336  IfxAsclin_Lin_BitSamplingControl bsc; /**< \brief structure for bit sampling */
337  IfxAsclin_Lin_FrameControl frame; /**< \brief structure for frame control */
338  IfxAsclin_Lin_FifoControl fifo; /**< \brief structure for FIFO control */
339  IfxAsclin_Lin_DataControl data; /**< \brief structure for data control */
340  IfxAsclin_Lin_LinControl lin; /**< \brief structure for lin control */
341  const IfxAsclin_Lin_Pins *pins; /**< \brief structure for LIN pins */
342  IfxAsclin_ClockSource clockSource; /**< \brief CSR.CLKSEL, clock source selection */
343  IfxAsclin_RxInputSelect alti; /**< \brief IOCR.ALTI, Rx input (alternate input) pin selection */
344  boolean receiveIdEnable; /**< \brief setting to receive Id in Rx Fifo after sending it */
346 
347 /** \} */
348 
349 /** \addtogroup IfxLld_Asclin_Lin_ElementaryTransactions
350  * \{ */
351 
352 /******************************************************************************/
353 /*-------------------------Global Function Prototypes-------------------------*/
354 /******************************************************************************/
355 
356 /** \brief Ignores the latest header
357  * \param asclin module handle
358  * \return None
359  *
360  * Usage Example:
361  * \code
362  * //IfxAsclin_Lin lin; // defined globally
363  * IfxAsclin_Lin_ignoreHeader(&lin);
364  * \endcode
365  *
366  */
368 
369 /** \brief Receives the header
370  * \param asclin module handle
371  * \param id the id byte which should be received
372  * \return None
373  *
374  * Usage Example:
375  * \code
376  * uint8 receivedId;
377  *
378  * // receive the header
379  * //IfxAsclin_Lin lin; // defined globally
380  * IfxAsclin_Lin_receiveHeader(&lin, &receivedId);
381  * \endcode
382  *
383  */
385 
386 /** \brief Receives the response
387  * \param asclin module handle
388  * \param data Pointer to the start of data which should be received
389  * \param length count of data (in bytes).
390  * \return None
391  *
392  * Usage Example:
393  * \code
394  * // prepare receive buffer
395  * uint8 rxData[8] = {0, 0, 0, 0, 0, 0, 0, 0};
396  * uint32 length = 8;
397  *
398  * // start the transmission
399  * //IfxAsclin_Lin lin; // defined globally
400  * IfxAsclin_Lin_receiveResponse(&lin, rxData, length);
401  * \endcode
402  *
403  */
405 
406 /** \brief Sends the header
407  * \param asclin module handle
408  * \param id the id byte which should be sent
409  * \return None
410  *
411  * Usage Example:
412  * \code
413  * // set the id byte
414  * uint8 id = 0x80 // for sending respose after header
415  *
416  * // send the header
417  * //IfxAsclin_Lin lin; // defined globally
418  * IfxAsclin_Lin_sendHeader(&lin, &id);
419  * \endcode
420  *
421  */
423 
424 /** \brief sends the response
425  * \param asclin module handle
426  * \param data Pointer to the start of data which should be sent
427  * \param length count of data (in bytes).
428  * \return None
429  *
430  * Usage Example:
431  * \code
432  * //prepare transmit bytes
433  * uint8 txData[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };
434  * uint32 length = 8;
435  *
436  * // send the response
437  * //IfxAsclin_Lin lin; // defined globally
438  * IfxAsclin_Lin_sendResponse(&lin, txData, length);
439  * \endcode
440  *
441  */
442 IFX_EXTERN void IfxAsclin_Lin_sendResponse(IfxAsclin_Lin *asclin, uint8 *data, uint32 length);
443 
444 /** \} */
445 
446 /** \addtogroup IfxLld_Asclin_Lin_ModuleFunctions
447  * \{ */
448 
449 /******************************************************************************/
450 /*-------------------------Global Function Prototypes-------------------------*/
451 /******************************************************************************/
452 
453 /** \brief Disables the module
454  * \param asclin module handle
455  * \return None
456  */
458 
459 /** \brief Initialises the module
460  * \param asclin module handle
461  * \param config predefined configuration structure of the module
462  * \return Status
463  *
464  * Usage Example:
465  * \code
466  * // create module config
467  * IfxAsclin_Lin_Config linConfig;
468  * IfxAsclin_Lin_initModuleConfig(&linConfig, &MODULE_ASCLIN1);
469  *
470  * // set the lin mode of operation
471  * linConfig.linMode = IfxAsclin_LinMode_master;
472  *
473  * // set the desired baudrate
474  * linConfig.baudrate.prescaler = 4;
475  * linConfig.baudrate.baudrate = 19200; // FDR values will be calculated in initModule
476  *
477  * // pin configuration
478  * const IfxAsclin_Lin_Pins pins = {
479  * &IfxAsclin0_RXB_P15_5_IN, IfxPort_InputMode_pullUp, // Rx pin
480  * &IfxAsclin0_TX_P15_4_OUT, IfxPort_OutputMode_pushPull, // Tx pin
481  * IfxPort_PadDriver_cmosAutomotiveSpeed1
482  * };
483  * linConfig.pins = &pins;
484  *
485  * // initialize module
486  * //IfxAsclin_Lin lin; // defined globally
487  * IfxAsclin_Lin_initModule(&lin, &linConfig);
488  * \endcode
489  *
490  */
492 
493 /** \brief Fills the config structure with default values
494  * \param config predefined configuration structure of the module
495  * \param asclin pointer to ASCLIN registers
496  * \return None
497  *
498  * Usage example: see \ref IfxAsclin_Lin_initModule
499  *
500  */
501 IFX_EXTERN void IfxAsclin_Lin_initModuleConfig(IfxAsclin_Lin_Config *config, Ifx_ASCLIN *asclin);
502 
503 /** \} */
504 
505 /** \addtogroup IfxLld_Asclin_Lin_errorHandlingFunctions
506  * \{ */
507 
508 /******************************************************************************/
509 /*-------------------------Global Function Prototypes-------------------------*/
510 /******************************************************************************/
511 
512 /** \brief checks for acknowledgement and error flags for received header
513  * \param asclin module handle
514  * \return None
515  */
517 
518 /** \brief checks for acknowledgement and error flags for received response
519  * \param asclin module handle
520  * \return None
521  */
523 
524 /** \brief checks for acknowledgement and error flags for transmitted header
525  * \param asclin module handle
526  * \return None
527  */
529 
530 /** \brief checks for acknowledgement and error flags for transmitted response
531  * \param asclin module handle
532  * \return None
533  */
535 
536 /** \brief clears the flags status structures
537  * \param asclin module handle
538  * \return None
539  */
541 
542 /** \brief waits until receive header end acknowledgemnet has been detected
543  * \param asclin module handle
544  * \return None
545  */
547 
548 /** \brief waits until receive response end acknowledgemnet has been detected
549  * \param asclin module handle
550  * \return None
551  */
553 
554 /** \brief waits until transmit header end acknowledgemnet has been detected
555  * \param asclin module handle
556  * \return None
557  */
559 
560 /** \brief waits until transmit response end acknowledgemnet has been detected
561  * \param asclin module handle
562  * \return None
563  */
565 
566 /** \} */
567 
568 #endif /* IFXASCLIN_LIN_H */