1 /***************************************************************************//** 2 * \file cy_lin.h 3 * \version 1.1 4 * 5 * \brief 6 * Provides an API declaration of the LIN driver 7 * 8 ******************************************************************************** 9 * \copyright 10 * Copyright 2020-2021, Cypress Semiconductor Corporation. All rights reserved. 11 * You may use this file only in accordance with the license, terms, conditions, 12 * disclaimers, and limitations in the end user license agreement accompanying 13 * the software package with which this file was provided. 14 *******************************************************************************/ 15 16 /** 17 * \addtogroup group_lin 18 * \{ 19 * The LIN driver provides a function API to manage Local Interconnect Network. 20 * 21 * The functions and other declarations used in this driver are in cy_lin.h. 22 * You can include cy_pdl.h to get access to all functions 23 * and declarations in the PDL. 24 * 25 * The Local Interconnect Network (LIN) bus was developed to create a standard for low-cost, low-end multiplexed communication. The use of a standard * bus protocol promotes the interoperability of network nodes. 26 * The LIN bus is a sub-bus system based on a serial communications protocol. The bus is a single master / multiple slave bus that uses a single wire * to transmit data. 27 * A LIN cluster exchanges messages with a pre-defined message frame format. The master node initiates a message exchange. Both the master node and * the slave nodes can transmit (TX) and receive (RX). 28 * The LIN protocol is half-duplex: a LIN node is either transmitting or receiving, but it cannot transmit and receive at the same time. Messages are * exchanged when the LIN cluster is in operational mode. 29 * A LIN cluster also exchanges wake-up signals. Both the master node and the slave nodes can initiate a wake-up. Wake-up signals are exchanged when * the LIN cluster is in sleep mode. 30 * The LIN bus can have a length of 10's of meters and has a bit-rate in the range of 1 kbps to 20 kbps. Most bus timing is expressed in bit periods * (e.g. a 20 kbps LIN bus has a 50 us bit period). 31 * The LIN bus uses single wire communication using a "lin" line with an operating Voltage of 12 V. Most master and slave nodes use discrete * transceiver devices. 32 * 33 * Features: 34 * * Single LIN hardware unit supporting multiple LIN channels. 35 * * Unified interrupt model. 36 * * Per LIN channel: 37 * * * Master and slave functionality. 38 * * * Master node autonomous header transmission. Master node autonomous response transmission and reception. 39 * * * Slave node autonomous header reception. Slave node autonomous response transmission and reception. 40 * * * Message buffer for PID, data and checksum fields. 41 * * * Break detection during message reception. 42 * * * Classic and enhanced checksum. 43 * * * Wakeup signaling. 44 * * * Timeout detection. 45 * * * Error detection. 46 * 47 * The LIN bus is an industry standard. 48 * 49 * \image html lin_network.png "LIN Network" width=400px 50 * \image latex lin_network.png 51 * 52 * Message Format: 53 * 54 * A LIN message have a pre-defined message frame format. 55 56 * A frame consists of a header, followed by a response. 57 * A frame header consists of a break field, followed by a synchronization field, followed by a protected identifier (PID) field. 58 * A frame response consists of 1, 2, ..., or 8 data fields, followed by a checksum field. 59 * The PID field, data fields and checksum fields are supported through a message buffer registers (MMIO PID_CHECKSUM, DATA0 and DATA1 registers). 60 * 61 * When transmitting, the message buffer registers provides the "to be transmitted" field values (with the exception of the checksum 62 * field, which is dynamically calculated). 63 * When receiving, the message buffer registers capture the received field values. 64 * 65 * \image html LIN_Message_Format.png "LIN Message Format" width=600px 66 * \image latex LIN_Message_Format.png 67 * 68 * The break field length and the break delimiter length. 69 * 70 * All other fields are 8-bit (1Byte) values that are transferred in a "UART format" with 1 START bit period and 1 STOP bit period. 71 * 72 * When receiving, the START and STOP bits are verified. In case of verification failure, a RX_HEADER_FRAME_ERROR or 73 * RX_RESPONSE_FRAME_ERROR is activated. 74 * Byte values are transmitted with least significant bit first format. 75 * 76 * Initialization: 77 * 78 * The LIN initialization is according to the Options setup in the passed Config Struct. \ref cy_stc_lin_config_t Several validations are done before that and an error is returned if invalid Modes are requested. 79 * 80 * Lin Configuration: 81 * 82 * Break_Wakup_Length field is used for transmission/reception of BOTH break and wakeup signals. 83 * \note These functions are mutually exclusive: 84 * Break_Delimiter_length field specifies the break delimiter length: used in header transmission, not used in header reception. 85 * STOP bit periods: 86 * LIN mode. 87 * 88 * \snippet lin/snippet/main.c snippet_Cy_LIN_Init 89 * 90 * Command: 91 * 92 * There are 5 commands that user can set in combinations. to send the data. 93 * - TX_HEADER 94 * - RX_HEADER 95 * - TX_RESPONSE 96 * - RX_RESPONSE 97 * - TX_WAKEUP 98 * 99 * The following restrictions apply when programming the commands: 100 * - TX_HEADER and RX_HEADER are mutually exclusive; i.e. both cannot be set to '1'. 101 * - TX_WAKEUP is mutually exclusive with all other commands. 102 * - TX_RESPONSE and RX_RESPONSE are NOT mutually exclusive, but are evaluated in the following order (of decreasing priority): TX_RESPONSE, RX_RESPONSE. 103 * 104 * The break or wakeup detection is always enabled, regardless of CMD register setting. 105 * 106 * Following are the combination of commands that user can use. These commands can be provided as predefined commands in cy_lin.h. 107 * - LIN_CMD_TX_HEADER 108 * - LIN_CMD_TX_RESPONSE 109 * - LIN_CMD_RX_RESPONSE 110 * - LIN_CMD_TX_HEADER_TX_RESPONSE 111 * - LIN_CMD_TX_HEADER_RX_RESPONSE 112 * - LIN_CMD_RX_HEADER_RX_RESPONSE 113 * - LIN_CMD_TX_WAKEUP 114 * 115 * \snippet lin/snippet/main.c snippet_Cy_LIN_Sequence 116 * 117 * Interrupt Handling : 118 * 119 * Lin channels have dedicated interrupts 120 * 121 * Driver does not handle interrupts and it is user's responsibility to clear interrupts. 122 * User registers for the list of interrupts given below and handle the interrupts in the interrupt handler. 123 * A code snippet is given below for registering to the interrupts and handling the interrupts in interrupt handler. 124 * 125 * There are 16 type of interrupts that the software can register for 126 * 127 * - TX_HEADER_DONE : When a frame header (break field, synchronization field and PID field) is transmitted. 128 * - TX_RESPONSE_DONE : When a frame response (data fields and checksum field) is transmitted. 129 * - TX_WAKEUP_DONE : When a wakeup signal is transmitted. This cause is activated on a transition from dominant/'0' state to recessive/'1' state; i.e. at the end of the wakeup signal. 130 * - RX_HEADER_DONE : When a frame header (break field, synchronization field and PID field) is received. 131 * - RX_RESPONSE_DONE : When a frame response (data fields and checksum field) is received 132 * - RX_BREAK_WAKEUP_DONE : When a break or wakeup signal is received (per CTL.BREAK_WAKEUP_LENGTH). This cause is activated on a transition from dominant/'0' state to recessive/'1' state; i.e. at the end of the wakeup signal. 133 * - RX_HEADER_SYNC_DONE : When a synchronization field is received (including trailing STOP bits). 134 * - RX_NOISE_DETECT : When isolated '0' or '1' "in_rx_in" values are observed or when during sampling the last three "lin_rx_in" values do NOT all have the same value. This mismatch is an indication of noise on the LIN line. 135 * - TIMEOUT : When a frame, frame header or frame response timeout is detected. 136 * - TX_HEADER_BIT_ERROR : When a transmitted "lin_tx_out" value does NOT match a received "lin_rx_in" value (during header transmission). This specific test allows for delay through the external transceiver. This mismatch is an indication of bus collisions on the LIN line. 137 * - TX_RESPONSE_BIT_ERROR : When a transmitted "lin_tx_out" value does NOT match a received "lin_rx_in" value (during response transmission). 138 * - RX_HEADER_FRAME_ERROR : When the received START or STOP bits have an unexpected value (during header reception). 139 * - RX_HEADER_SYNC_ERROR : When the received synchronization field is not received within the synchronization counter range [106, 152] 140 * - RX_HEADER_PARITY_ERROR : When the received PID field has a parity error. 141 * - RX_RESPONSE_FRAME_ERROR : When the received START or STOP bits have an unexpected value (during response reception) 142 * - RX_RESPONSE_CHECKSUM_ERROR : When the calculated checksum over the received PID and data fields is not the same as the received checksum. 143 * 144 * \snippet lin/snippet/main.c snippet_Cy_LIN_ISR 145 * 146 * \section group_lin_changelog Changelog 147 * <table class="doxtable"> 148 * <tr><th>Version</th><th>Changes</th><th>Reason for Change</th></tr> 149 * <tr> 150 * <td>1.1</td> 151 * <td>Fixed MISRA 2012 violations.</td> 152 * <td>MISRA 2012 compliance.</td> 153 * </tr> 154 * <tr> 155 * <td>1.0</td> 156 * <td>Initial version</td> 157 * <td></td> 158 * </tr> 159 * </table> 160 * 161 * \defgroup group_lin_macro Macros 162 * \{ 163 * \defgroup group_lin_cmd_macro LIN Command Type Definition 164 * \defgroup group_lin_intr_mask_macro LIN ALL Interrupt Mask Definition 165 * \defgroup group_lin_common_macro LIN Common Macros 166 * \} 167 * \defgroup group_lin_functions Functions 168 * \defgroup group_lin_data_structures Data Structures 169 * \defgroup group_lin_enums Enumerated Types 170 */ 171 172 173 #if !defined(CY_LIN_H) 174 #define CY_LIN_H 175 #include "cy_device.h" 176 #if defined (CY_IP_MXLIN) 177 /*****************************************************************************/ 178 /* Include files */ 179 /*****************************************************************************/ 180 #include <stdint.h> 181 #include <stddef.h> 182 #include <stdbool.h> 183 #include "cy_syslib.h" 184 185 #if defined(__cplusplus) 186 extern "C" { 187 #endif 188 189 /** 190 * \addtogroup group_lin_macro 191 * \{ 192 */ 193 194 195 /*****************************************************************************/ 196 /* Global pre-processor symbols/macros ('#define') */ 197 /*****************************************************************************/ 198 /** Driver major version */ 199 #define CY_LIN_DRV_VERSION_MAJOR 1 200 201 /** Driver minor version */ 202 #define CY_LIN_DRV_VERSION_MINOR 1 203 204 /** LIN driver ID */ 205 #define CY_LIN_ID CY_PDL_DRV_ID(0x37u) 206 207 /** \} group_lin_macro */ 208 209 /** 210 * \addtogroup group_lin_common_macro LIN Common Macros 211 * \{ 212 * LIN Specific common Macros 213 */ 214 /** Maximum ID */ 215 #define LIN_ID_MAX (0x3Fu) 216 /** Maximum data length */ 217 #define LIN_DATA_LENGTH_MAX (8u) 218 /** Minimum data length */ 219 #define LIN_DATA_LENGTH_MIN (1u) 220 /** Maximum time out length */ 221 #define LIN_TIMEOUT_LENGTH_MAX (255u) 222 /** Minimum wakeup period value = 250usec*/ 223 #define LIN_WAKEUP_PERIOD_MIN (250u) 224 /** Maximum break_wakeup period bit length */ 225 #define LIN_BREAK_WAKEUP_LENGTH_BITS_MAX (31u) 226 /** LIN Master minimum break filed detection length */ 227 #define LIN_MASTER_BREAK_FILED_LENGTH_MIN (13u) 228 229 /** \} group_lin_common_macro */ 230 231 /** 232 * \addtogroup group_lin_enums 233 * \{ 234 */ 235 /** LIN API status definition */ 236 typedef enum 237 { 238 CY_LIN_SUCCESS = 0x00u, /**< Returned successful */ 239 CY_LIN_BAD_PARAM = CY_LIN_ID | CY_PDL_STATUS_ERROR | 0x01u, /**< Bad parameter was passed */ 240 CY_LIN_BUSY = CY_LIN_ID | CY_PDL_STATUS_ERROR | 0x02u, /**< Change settings while tx/rx on-going */ 241 CY_LIN_FRAME_NOT_RECEIVED = CY_LIN_ID | CY_PDL_STATUS_ERROR | 0x03u, /**< No frame received */ 242 } cy_en_lin_status_t; 243 /** \} group_lin_enums */ 244 245 /** 246 * \addtogroup group_lin_cmd_macro LIN Command Type Definition 247 * \{ 248 * Specifies the parameter values passed to LIN command API 249 */ 250 /** LIN Command TX Header */ 251 #define LIN_CMD_TX_HEADER (LIN_CH_CMD_TX_HEADER_Msk) 252 /** LIN Command TX Response */ 253 #define LIN_CMD_TX_RESPONSE (LIN_CH_CMD_TX_RESPONSE_Msk) 254 /** LIN Command RX Response */ 255 #define LIN_CMD_RX_RESPONSE (LIN_CH_CMD_RX_RESPONSE_Msk) 256 /** LIN Command TX Header and TX Response */ 257 #define LIN_CMD_TX_HEADER_TX_RESPONSE (LIN_CH_CMD_TX_HEADER_Msk | LIN_CH_CMD_TX_RESPONSE_Msk) 258 /** LIN Command TX Header and RX Response */ 259 #define LIN_CMD_TX_HEADER_RX_RESPONSE (LIN_CH_CMD_TX_HEADER_Msk | LIN_CH_CMD_RX_RESPONSE_Msk) 260 /** LIN Command RX Header and RX Response */ 261 #define LIN_CMD_RX_HEADER_RX_RESPONSE (LIN_CH_CMD_RX_HEADER_Msk | LIN_CH_CMD_RX_RESPONSE_Msk) 262 /** LIN Command TX Wake up */ 263 #define LIN_CMD_TX_WAKEUP (LIN_CH_CMD_TX_WAKEUP_Msk) 264 /** \} group_lin_cmd_macro */ 265 266 /** 267 * \addtogroup group_lin_intr_mask_macro LIN ALL Interrupt Mask Definition 268 * \{ 269 * Specifies the mask value for interrupt status/mask 270 */ 271 /** Mask for TX Header DONE */ 272 #define LIN_INTR_TX_HEADER_DONE (LIN_CH_INTR_TX_HEADER_DONE_Msk) 273 /** Mask for TX Response DONE */ 274 #define LIN_INTR_TX_RESPONSE_DONE (LIN_CH_INTR_TX_RESPONSE_DONE_Msk) 275 /** Mask for TX Wake up DONE */ 276 #define LIN_INTR_TX_WAKEUP_DONE (LIN_CH_INTR_TX_WAKEUP_DONE_Msk) 277 /** Mask for RX Header DONE */ 278 #define LIN_INTR_RX_HEADER_DONE (LIN_CH_INTR_RX_HEADER_DONE_Msk) 279 /** Mask for RX Response DONE */ 280 #define LIN_INTR_RX_RESPONSE_DONE (LIN_CH_INTR_RX_RESPONSE_DONE_Msk) 281 /** Mask for RX Wake up DONE */ 282 #define LIN_INTR_RX_BREAK_WAKEUP_DONE (LIN_CH_INTR_MASK_RX_BREAK_WAKEUP_DONE_Msk) 283 /** Mask for RX Header Sync DONE */ 284 #define LIN_INTR_RX_HEADER_SYNC_DONE (LIN_CH_INTR_RX_HEADER_SYNC_DONE_Msk) 285 /** Mask for RX Noise Detect */ 286 #define LIN_INTR_RX_NOISE_DETECT (LIN_CH_INTR_RX_NOISE_DETECT_Msk) 287 /** Mask for timeout */ 288 #define LIN_INTR_TIMEOUT (LIN_CH_INTR_TIMEOUT_Msk) 289 /** Mask for TX Header Bit error */ 290 #define LIN_INTR_TX_HEADER_BIT_ERROR (LIN_CH_INTR_TX_HEADER_BIT_ERROR_Msk) 291 /** Mask for TX Response Bit error */ 292 #define LIN_INTR_TX_RESPONSE_BIT_ERROR (LIN_CH_INTR_TX_RESPONSE_BIT_ERROR_Msk) 293 /** Mask for RX Header frame error */ 294 #define LIN_INTR_RX_HEADER_FRAME_ERROR (LIN_CH_INTR_RX_HEADER_FRAME_ERROR_Msk) 295 /** Mask for Rx header sync error */ 296 #define LIN_INTR_RX_HEADER_SYNC_ERROR (LIN_CH_INTR_RX_HEADER_SYNC_ERROR_Msk) 297 /** Mask for Rx header parity error */ 298 #define LIN_INTR_RX_HEADER_PARITY_ERROR (LIN_CH_INTR_RX_HEADER_PARITY_ERROR_Msk) 299 /** Mask for Rx Response frame error */ 300 #define LIN_INTR_RX_RESPONSE_FRAME_ERROR (LIN_CH_INTR_RX_RESPONSE_FRAME_ERROR_Msk) 301 /** Mask for Rx response checksum error */ 302 #define LIN_INTR_RX_RESPONSE_CHECKSUM_ERROR (LIN_CH_INTR_RX_RESPONSE_CHECKSUM_ERROR_Msk) 303 /** Mask for all slave errors */ 304 #define LIN_INTR_ALL_ERROR_MASK_SLAVE (LIN_CH_INTR_RX_NOISE_DETECT_Msk |\ 305 LIN_CH_INTR_TIMEOUT_Msk |\ 306 LIN_CH_INTR_TX_RESPONSE_BIT_ERROR_Msk |\ 307 LIN_CH_INTR_RX_HEADER_FRAME_ERROR_Msk |\ 308 LIN_CH_INTR_RX_HEADER_SYNC_ERROR_Msk |\ 309 LIN_CH_INTR_RX_HEADER_PARITY_ERROR_Msk |\ 310 LIN_CH_INTR_RX_RESPONSE_FRAME_ERROR_Msk |\ 311 LIN_CH_INTR_RX_RESPONSE_CHECKSUM_ERROR_Msk) 312 /** Mask for all master errors */ 313 #define LIN_INTR_ALL_ERROR_MASK_MASTER (LIN_INTR_ALL_ERROR_MASK_SLAVE | LIN_CH_INTR_TX_HEADER_BIT_ERROR_Msk) 314 315 316 /** \} group_lin_intr_mask_macro */ 317 318 /** 319 * \addtogroup group_lin_enums 320 * \{ 321 */ 322 /*****************************************************************************/ 323 /* Global type definitions ('typedef') */ 324 /*****************************************************************************/ 325 /** 326 ***************************************************************************** 327 ** \brief LIN break delimiter length 328 ** 329 ** This configuration is effective only when corresponding channel = master mode. 330 *****************************************************************************/ 331 typedef enum cy_en_lin_break_delimiter_length{ 332 LIN_BREAK_DILIMITER_LENGTH_1BITS = 0, /*!< 1-bit length */ 333 LIN_BREAK_DILIMITER_LENGTH_2BITS = 1, /*!< 2-bit length */ 334 LIN_BREAK_DILIMITER_LENGTH_3BITS = 2, /*!< 3-bit length */ 335 LIN_BREAK_DILIMITER_LENGTH_4BITS = 3 /*!< 4-bit length */ 336 }cy_en_lin_break_delimiter_length_t; 337 338 /** 339 ***************************************************************************** 340 ** \brief Stop bit selection. 341 ** 342 *****************************************************************************/ 343 typedef enum cy_en_lin_stopbit 344 { 345 LIN_ONE_STOP_BIT = 1, /*!< 1 stop bit */ 346 LIN_TWO_STOP_BIT = 3 /*!< 2 stop bits */ 347 } cy_en_lin_stopbit_t; 348 349 /** 350 ***************************************************************************** 351 ** \brief Checksum type selection. 352 ** 353 *****************************************************************************/ 354 typedef enum cy_en_lin_checksum_type 355 { 356 LIN_CHECKSUM_TYPE_NORMAL = 0, /*!< Normal (classic) checksum */ 357 LIN_CHECKSUM_TYPE_EXTENDED = 1 /*!< Extended (enhanced) checksum */ 358 }cy_en_lin_checksum_type_t; 359 360 /** 361 ***************************************************************************** 362 ** \brief Timeout type selection. 363 ** 364 *****************************************************************************/ 365 typedef enum cy_en_lin_timeout_sel_type 366 { 367 LIN_TIMEOUT_NONE = 0, /*!< No timeout */ 368 LIN_TIMEOUT_FROM_BREAK_TO_CHECKSUM = 1, /*!< Frame mode: from the start of break field to checksum field STOP bits */ 369 LIN_TIMEOUT_FROM_BREAK_TO_PID = 2, /*!< Frame header mode: detects timeout from the start of break field to PID field STOP bits */ 370 LIN_TIMEOUT_FROM_RESPONSE_TO_CHECKSUM = 3 /*!< Frame response mode: detects timeout from the first data field START bit to checksum field STOP bits. */ 371 }cy_en_lin_timeout_sel_type_t; 372 /** \} group_lin_enums */ 373 374 /** 375 * \addtogroup group_lin_data_structures 376 * \{ 377 */ 378 379 /** 380 ***************************************************************************** 381 ** \brief LIN configuration 382 ** These settings are per LIN instance. 383 *****************************************************************************/ 384 typedef struct cy_stc_lin_config 385 { 386 387 bool masterMode; /**< If TRUE, corresponding channel = master mode, If FALSE, slave mode. */ 388 389 bool linTransceiverAutoEnable; /**< If TRUE, corresponding LIN channel transceiver is enabled automatically, 390 If FALSE, firmware has to handle the transceiver enable signal manually */ 391 392 uint8_t breakFieldLength; /**< Break field length. */ 393 394 cy_en_lin_break_delimiter_length_t breakDelimiterLength; /**< Break delimiter length. See #cy_en_lin_break_delimiter_length_t */ 395 396 cy_en_lin_stopbit_t stopBit; /**< Stop bit length. See #cy_en_lin_stopbit_t. */ 397 398 bool filterEnable; /**< If TRUE, lin_rx_in filter operates. 399 Median 3 operates on the last three "lin_rx_in" values. 400 The sequences '000', '001', '010' and '100' result in a filtered value '0'. 401 The sequences '111', '110', '101' and '011' result in a filtered value '1'. 402 */ 403 }cy_stc_lin_config_t; 404 405 /** 406 ***************************************************************************** 407 ** \brief LIN Test configuration 408 ** This testing functionality simplifies SW development, 409 ** but may also be used in the field to verify correct channel functionality. 410 *****************************************************************************/ 411 typedef struct cy_stc_lin_test_config 412 { 413 uint8_t chidx; /**< Specifies the channel index of the channel to which the test applies. 414 The test mode allows BOTH of the two connected channels to be tested. */ 415 bool mode; /**< When set FALSE, it is partial disconnect from IOSS. Used to observe messages outside of device. 416 When Set TRUE, it is full disconnect from IOSS. Used for device test without effecting 417 operational LIN cluster. */ 418 }cy_stc_lin_test_config_t; 419 420 /** 421 ***************************************************************************** 422 ** \brief LIN Error CTL configuration 423 ** Used only for software testing. 424 ** It enables HW injected channel transmitter errors. 425 ** The receiver should detect these errors and report these errors through activation of corresponding interrupt causes. 426 *****************************************************************************/ 427 typedef struct cy_stc_lin_test_error_config 428 { 429 uint8_t chidx; /**< Specifies the channel index of the channel to which the test applies. 430 The test mode allows BOTH of the two connected channels to be tested. */ 431 bool txsync_error; /**< At the receiver, this should result in INTR.RX_HEADER_SYNC_ERROR activation. */ 432 bool txsyncStop_error; /**< At the receiver, this should result in INTR.RX_HEADER_SYNC_ERROR or INTR.RX_HEADER_FRAME_ERROR activation. */ 433 bool txParity_error; /**< At the receiver, this should result in INTR.RX_HEADER_PARITY_ERROR activation. */ 434 bool txPIDStop_error; /**< At the receiver, this should result in INTR.RX_HEADER_FRAME_ERROR activation. */ 435 bool txDataStop_error; /**< At the receiver, this should result in INTR.RX_RESPONSE_FRAME_ERROR activation. */ 436 bool txChecksum_error; /**< At the receiver, this should result in INTR.RX_RESPONSE_CHECKSUM_ERROR activation. */ 437 bool txChecksumStop_error; /**< At the receiver, this should result in INTR.RX_RESPONSE_FRAME_ERROR activation. */ 438 }cy_stc_lin_test_error_config_t; 439 440 /** \} group_lin_data_structures */ 441 442 /*****************************************************************************/ 443 /* Global variable declarations ('extern', definition in C source) */ 444 /*****************************************************************************/ 445 /** \cond Internal */ 446 /* 447 * Default values for the CTL Register. 448 */ 449 450 /** Mask for Stop Bits */ 451 #define LIN_CH_CTL0_STOP_BITS_DEFAULT LIN_ONE_STOP_BIT 452 /** Mask for Auto Enable */ 453 #define LIN_CH_CTL0_AUTO_EN_DEFAULT 0U 454 /** Mask for break delimiter length */ 455 #define LIN_CH_CTL0_BREAK_DELIMITER_LENGTH_DEFAULT 1U 456 /** Mask for break wake up length */ 457 #define LIN_CH_CTL0_BREAK_WAKEUP_LENGTH_DEFAULT 12U 458 /** Mask for mode */ 459 #define LIN_CH_CTL0_MODE_DEFAULT 0U 460 /** Mask for error ignore */ 461 #define LIN_CH_CTL0_BIT_ERROR_IGNORE_DEFAULT 0U 462 /** Mask for parity */ 463 #define LIN_CH_CTL0_PARITY_DEFAULT 0U 464 /** Mask for parity enable */ 465 #define LIN_CH_CTL0_PARITY_EN_DEFAULT 0U 466 /** Mask for filter enable */ 467 #define LIN_CH_CTL0_FILTER_EN_DEFAULT 1U 468 /** Mask for enabled */ 469 #define LIN_CH_CTL0_ENABLED_DEFAULT 0U 470 /** Mask for default */ 471 #define LIN_CH_CTL0_DEFAULT (_VAL2FLD(LIN_CH_CTL0_STOP_BITS, LIN_CH_CTL0_STOP_BITS_DEFAULT) | \ 472 _VAL2FLD(LIN_CH_CTL0_AUTO_EN, LIN_CH_CTL0_AUTO_EN_DEFAULT) | \ 473 _VAL2FLD(LIN_CH_CTL0_BREAK_DELIMITER_LENGTH, LIN_CH_CTL0_BREAK_DELIMITER_LENGTH_DEFAULT) | \ 474 _VAL2FLD(LIN_CH_CTL0_BREAK_WAKEUP_LENGTH, LIN_CH_CTL0_BREAK_WAKEUP_LENGTH_DEFAULT) | \ 475 _VAL2FLD(LIN_CH_CTL0_MODE, LIN_CH_CTL0_MODE_DEFAULT) | \ 476 _VAL2FLD(LIN_CH_CTL0_BIT_ERROR_IGNORE, LIN_CH_CTL0_BIT_ERROR_IGNORE_DEFAULT) | \ 477 _VAL2FLD(LIN_CH_CTL0_PARITY, LIN_CH_CTL0_PARITY_DEFAULT) | \ 478 _VAL2FLD(LIN_CH_CTL0_PARITY_EN, LIN_CH_CTL0_PARITY_EN_DEFAULT) | \ 479 _VAL2FLD(LIN_CH_CTL0_FILTER_EN, LIN_CH_CTL0_FILTER_EN_DEFAULT) | \ 480 _VAL2FLD(LIN_CH_CTL0_ENABLED, LIN_CH_CTL0_ENABLED_DEFAULT)) 481 482 /* Macros for the conditions used by CY_ASSERT calls */ 483 #define CY_LIN_TEST_CTL_CH_IDX_MIN 0U /** LIN Test Ctl Channel index Minimum value */ 484 #define CY_LIN_TEST_CTL_CH_IDX_MAX 31U /** LIN Test Ctl Channel index Maximum value */ 485 486 #define CY_LIN_IS_TEST_CTL_CH_IDX_VALID(chidx) ((chidx) <= CY_LIN_TEST_CTL_CH_IDX_MAX) 487 488 489 /** \endcond */ 490 491 /** 492 * \addtogroup group_lin_functions 493 * \{ 494 */ 495 496 /*****************************************************************************/ 497 /* Global function prototypes ('extern', definition in C source) */ 498 /*****************************************************************************/ 499 /** 500 ***************************************************************************** 501 ** \brief Deinitialization of a LIN module. 502 ** This function deinitializes the selected LIN channel. 503 ** 504 ** \param [in] base Pointer to LIN instance channel register 505 ** 506 ** \retval Refer \ref cy_en_lin_status_t 507 ** 508 ** \funcusage 509 ** \snippet lin/snippet/main.c snippet_Cy_LIN_DeInit 510 ** 511 *****************************************************************************/ 512 cy_en_lin_status_t Cy_LIN_DeInit( LIN_CH_Type* base ); 513 514 /** 515 ***************************************************************************** 516 ** \brief Initializes the LIN module. 517 ** This function initializes LIN according to the options setup in the 518 ** passed Config Struct. Several checkings are done before that and an error 519 ** is returned if invalid Modes are requested. 520 ** 521 ** \pre The Application must configure corresponding LIN pins (SIN, SOT) 522 ** according to requirements and settings of LIN instance. 523 ** And must set baud rate using SysClk. LIN I/F has internal fixed 524 ** oversampling value (16). Therefore, LIN clock / 16 is actual 525 ** baud rate. 526 ** 527 ** \param [in] base Pointer to LIN instance register area 528 ** \param [in] pstcConfig LIN module configuration. See #cy_stc_lin_config_t. 529 ** 530 ** \retval Refer \ref cy_en_lin_status_t 531 ** 532 ** \funcusage 533 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Init 534 ** 535 *****************************************************************************/ 536 cy_en_lin_status_t Cy_LIN_Init( LIN_CH_Type* base, const cy_stc_lin_config_t *pstcConfig); 537 538 /** 539 ***************************************************************************** 540 ** \brief Reads response data. 541 ** Data is read in Bytes. Maximum data length is 8-bytes. 542 ** 543 ** \pre Must be run after RX_RESPONSE_DONE. 544 ** 545 ** \note This function returns last received data set. 546 ** 547 ** \param base [in] Pointer to LIN instance register area. 548 ** \param data [out] Pointer to received data. 549 ** Must have enough space for current Rx data. 550 ** 551 ** \retval Refer \ref cy_en_lin_status_t 552 ** 553 ** \funcusage 554 ** \snippet lin/snippet/main.c snippet_Cy_LIN_ISR 555 ** 556 *****************************************************************************/ 557 cy_en_lin_status_t Cy_LIN_ReadData( LIN_CH_Type* base, uint8_t *data); 558 559 /** 560 ***************************************************************************** 561 ** \brief Writes response data. 562 ** Data is written in Bytes. Maximum data length is 8-bytes. 563 ** \param base [in] Pointer to LIN instance register area. 564 ** \param data [in] Pointer to response data. 565 ** \param dataLength [in] Data length in bytes. 566 ** \retval Refer \ref cy_en_lin_status_t 567 ** 568 ** \funcusage 569 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Sequence 570 ** 571 *****************************************************************************/ 572 cy_en_lin_status_t Cy_LIN_WriteData( LIN_CH_Type* base, const uint8_t *data, uint8_t dataLength ); 573 574 /** 575 ***************************************************************************** 576 ** \brief Enables LIN channel. 577 ** 578 ** \param base [in] Pointer to LIN instance register area. 579 ** 580 ** \retval Refer \ref cy_en_lin_status_t 581 ** 582 ** \funcusage 583 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Enable 584 ** 585 *****************************************************************************/ 586 cy_en_lin_status_t Cy_LIN_Enable(LIN_CH_Type* base); 587 588 /** 589 ***************************************************************************** 590 ** \brief Disables LIN channel. 591 ** Disabling LIN channel causes clearing of non retained registers. 592 ** e.g) CMD register, INTR register, STATUS register. 593 ** This behavior can be used for re-initialization, after error or 594 ** abort RX operation. 595 ** 596 ** \param base [in] Pointer to LIN instance register area. 597 ** 598 ** \retval Refer \ref cy_en_lin_status_t 599 ** 600 ** \funcusage 601 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Disable 602 ** 603 *****************************************************************************/ 604 cy_en_lin_status_t Cy_LIN_Disable(LIN_CH_Type* base); 605 606 /** 607 ***************************************************************************** 608 ** \brief Sets LIN break/wakeup field length. 609 ** Normally this I/F is used for detection of the wakeup pulse. 610 ** 611 ** \param base [in] Pointer to LIN instance register area. 612 ** \param length [in] Bit length of the break/wakeup field. 613 ** 614 ** \retval Refer \ref cy_en_lin_status_t 615 ** 616 *****************************************************************************/ 617 cy_en_lin_status_t Cy_LIN_SetBreakWakeupFieldLength(LIN_CH_Type* base, uint8_t length); 618 619 /** 620 ***************************************************************************** 621 ** \brief Sets LIN response field data length. 622 ** Data is in Bytes and maximum data length is 8-bytes. 623 ** 624 ** \param base [in] Pointer to LIN instance register area. 625 ** \param length [in] Data length in byte 626 ** 627 ** \retval Refer \ref cy_en_lin_status_t 628 ** 629 ** \funcusage 630 ** \snippet lin/snippet/main.c snippet_Cy_LIN_SetDataLength 631 ** 632 *****************************************************************************/ 633 cy_en_lin_status_t Cy_LIN_SetDataLength(LIN_CH_Type* base, uint8_t length); 634 635 /** 636 ***************************************************************************** 637 ** \brief Sets LIN checksum type setting. 638 ** 639 ** \param base [in] Pointer to LIN instance register area. 640 ** \param type [in] Checksum type. Refer \ref cy_en_lin_checksum_type_t 641 ** 642 ** \retval Refer \ref cy_en_lin_status_t 643 ** 644 ** \funcusage 645 ** \snippet lin/snippet/main.c snippet_Cy_LIN_SetChecksumType 646 ** 647 *****************************************************************************/ 648 cy_en_lin_status_t Cy_LIN_SetChecksumType(LIN_CH_Type* base, cy_en_lin_checksum_type_t type); 649 650 /** 651 ***************************************************************************** 652 ** \brief Sets LIN operation command. 653 ** 654 ** \note As a normal usage, following combinations are used. 655 ** - Master 656 ** Header TX only : LIN_CMD_TX_HEADER 657 ** Header TX & TX response : LIN_CMD_TX_HEADER_TX_RESPONSE 658 ** Header TX & RX response : LIN_CMD_TX_HEADER_RX_RESPONSE 659 ** - Slave 660 ** Header RX : LIN_CMD_RX_HEADER_RX_RESPONSE 661 ** TX response : LIN_CMD_TX_RESPONSE 662 ** RX response : Already set when header RX 663 ** As a typical usage, RX response is always set at header RX phase. 664 ** - Wakeup frame : LIN_CMD_TX_WAKEUP 665 ** Instead of above macro, you can use raw definition LIN_CH_CMD_*_Msk defined in IO header file. 666 ** 667 ** \param base [in] Pointer to LIN instance register area. 668 ** \param command [in] Required operation command. Refer \ref group_lin_cmd_macro 669 ** 670 ** \retval Refer \ref cy_en_lin_status_t 671 ** 672 ** \funcusage 673 ** \snippet lin/snippet/main.c snippet_Cy_LIN_SetCmd 674 ** 675 *****************************************************************************/ 676 cy_en_lin_status_t Cy_LIN_SetCmd(LIN_CH_Type* base, uint32_t command); 677 678 /** 679 ***************************************************************************** 680 ** \brief Sets LIN header for master tx header operation. 681 ** 682 ** \param base [in] Pointer to LIN instance register area. 683 ** \param id [in] ID value 684 ** 685 ** \retval Refer \ref cy_en_lin_status_t 686 ** 687 ** \funcusage 688 ** \snippet lin/snippet/main.c snippet_Cy_LIN_SetHeader 689 ** 690 *****************************************************************************/ 691 cy_en_lin_status_t Cy_LIN_SetHeader(LIN_CH_Type* base, uint8_t id); 692 693 /** 694 ***************************************************************************** 695 ** \brief Returns received LIN header. 696 ** 697 ** \param base [in] Pointer to LIN instance register area. 698 ** \param id [out] Received ID value. 699 ** \param parity [out] Received parity value. 700 ** Note that parity check is always done by HW automatically. 701 ** 702 ** \retval Refer \ref cy_en_lin_status_t 703 ** 704 *****************************************************************************/ 705 cy_en_lin_status_t Cy_LIN_GetHeader(LIN_CH_Type* base, uint8_t *id, uint8_t *parity); 706 707 /** 708 ***************************************************************************** 709 ** \brief Sets interrupt source to be accepted. 710 ** 711 ** \param base [in] Pointer to LIN instance register area. 712 ** \param mask [in] The mask with the OR of the interrupt source to be accepted. 713 ** See \ref group_lin_intr_mask_macro for the set of constants. 714 ** 715 ** \retval Refer \ref cy_en_lin_status_t 716 ** 717 ** \funcusage 718 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Sequence 719 ** 720 *****************************************************************************/ 721 cy_en_lin_status_t Cy_LIN_SetInterruptMask(LIN_CH_Type* base, uint32_t mask); 722 723 /** 724 ***************************************************************************** 725 ** \brief Returns interrupt mask setting. 726 ** 727 ** \param base [in] Pointer to LIN instance register area. 728 ** \param mask [out] The mask with the OR of the interrupt source which is masked. 729 ** See \ref group_lin_intr_mask_macro for the set of constants. 730 ** 731 ** \retval Refer \ref cy_en_lin_status_t 732 ** 733 ** \funcusage 734 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Sequence 735 ** 736 *****************************************************************************/ 737 cy_en_lin_status_t Cy_LIN_GetInterruptMask(LIN_CH_Type* base, uint32_t *mask); 738 739 /** 740 ***************************************************************************** 741 ** \brief Returns interrupt masked status. 742 ** 743 ** \param base [in] Pointer to LIN instance register area. 744 ** \param status [out] The mask with the OR of the interrupt source which occurs. 745 ** See \ref group_lin_intr_mask_macro for the set of constants. 746 ** 747 ** \retval Refer \ref cy_en_lin_status_t 748 ** 749 ** \funcusage 750 ** \snippet lin/snippet/main.c snippet_Cy_LIN_ISR 751 ** 752 *****************************************************************************/ 753 cy_en_lin_status_t Cy_LIN_GetInterruptMaskedStatus(LIN_CH_Type* base, uint32_t *status); 754 755 /** 756 ***************************************************************************** 757 ** \brief Returns interrupt raw status. 758 ** 759 ** \param base [in] Pointer to LIN instance register area. 760 ** \param status [out] The mask with the OR of the interrupt source which occurs. 761 ** See \ref group_lin_intr_mask_macro for the set of constants. 762 ** 763 ** \retval Refer \ref cy_en_lin_status_t 764 ** 765 ** \funcusage 766 ** \snippet lin/snippet/main.c snippet_Cy_LIN_ISR 767 ** 768 *****************************************************************************/ 769 cy_en_lin_status_t Cy_LIN_GetInterruptStatus(LIN_CH_Type* base, uint32_t *status); 770 771 /** 772 ***************************************************************************** 773 ** \brief Clears interrupt status. 774 ** 775 ** \param base [in] Pointer to LIN instance register area. 776 ** \param mask [in] The mask with the OR of the interrupt source to be cleared. 777 ** See \ref group_lin_intr_mask_macro for the set of constants. 778 ** 779 ** \retval Refer \ref cy_en_lin_status_t 780 ** 781 ** \funcusage 782 ** \snippet lin/snippet/main.c snippet_Cy_LIN_ISR 783 ** 784 *****************************************************************************/ 785 cy_en_lin_status_t Cy_LIN_ClearInterrupt(LIN_CH_Type* base, uint32_t mask); 786 787 /** 788 ***************************************************************************** 789 ** \brief Returns LIN module status. 790 ** 791 ** \param base [in] Pointer to LIN instance register area. 792 ** \param status [out] LIN module status. 793 ** 794 ** \retval Refer \ref cy_en_lin_status_t 795 ** 796 ** \funcusage 797 ** \snippet lin/snippet/main.c snippet_Cy_LIN_ISR 798 ** 799 *****************************************************************************/ 800 cy_en_lin_status_t Cy_LIN_GetStatus(LIN_CH_Type* base, uint32_t *status); 801 802 /** 803 ***************************************************************************** 804 ** \brief Enables LIN channel 'en' out. 805 ** 806 ** If linTransceiverAutoEnable in cy_stc_lin_config_t config structure is set to true 807 ** then transceiver is set automatically and user need not call this function, 808 ** else user has to call Cy_Status_EnOut_Enable() before sending a message and call 809 ** Cy_Status_EnOut_Disable() after sending the message. 810 ** 811 ** \param base [in] Pointer to LIN instance register area. 812 ** 813 ** \retval Refer \ref cy_en_lin_status_t 814 ** 815 ** \funcusage 816 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Init_Example 817 ** 818 *****************************************************************************/ 819 cy_en_lin_status_t Cy_LIN_EnOut_Enable(LIN_CH_Type* base); 820 821 /** 822 ***************************************************************************** 823 ** \brief Disables LIN channel 'en' out. 824 ** 825 ** If linTransceiverAutoEnable in cy_stc_lin_config_t config structure is set to true 826 ** then transceiver is set automatically and user need not call this function, 827 ** else user has to call Cy_Status_EnOut_Enable() before sending a message and call 828 ** Cy_Status_EnOut_Disable() after sending the message. 829 ** 830 ** \param base [in] Pointer to LIN instance register area. 831 ** 832 ** \retval Refer \ref cy_en_lin_status_t 833 ** 834 *****************************************************************************/ 835 cy_en_lin_status_t Cy_LIN_EnOut_Disable(LIN_CH_Type* base); 836 837 /** 838 ***************************************************************************** 839 ** \brief Enables LIN Testing mode. 840 ** 841 ** This testing functionality simplifies SW development, 842 ** but may also be used in the field to verify correct channel functionality. 843 ** 844 ** \param base [in] Pointer to LIN instance register area. 845 ** \param lin_test_config [in] pointer to Test configuration structure. 846 ** 847 ** \retval Refer \ref cy_en_lin_status_t 848 ** 849 ** \funcusage 850 ** \snippet lin/snippet/main.c snippet_Cy_LIN_Init_Example 851 ** 852 *****************************************************************************/ 853 cy_en_lin_status_t Cy_LIN_TestMode_Enable(LIN_Type* base, const cy_stc_lin_test_config_t* lin_test_config); 854 855 /** 856 ***************************************************************************** 857 ** \brief Disables LIN Testing mode. 858 ** 859 ** This testing functionality simplifies SW development, 860 ** but may also be used in the field to verify correct channel functionality. 861 ** 862 ** \param base [in] Pointer to LIN instance register area. 863 ** 864 ** \retval Refer \ref cy_en_lin_status_t 865 ** 866 *****************************************************************************/ 867 cy_en_lin_status_t Cy_LIN_TestMode_Disable(LIN_Type* base); 868 869 /** 870 ***************************************************************************** 871 ** \brief Enables LIN ERROR CTL. 872 ** 873 ** Enables HW injected channel transmitter errors. 874 ** The receiver should detect these errors and report these errors through activation of corresponding interrupt causes. 875 ** 876 ** \param base [in] Pointer to LIN instance register area. 877 ** \param test_error_config [in] pointer to Test Error configuration structure. 878 ** 879 ** \retval Refer \ref cy_en_lin_status_t 880 ** 881 *****************************************************************************/ 882 cy_en_lin_status_t Cy_LIN_ErrCtl_Enable(LIN_Type* base, cy_stc_lin_test_error_config_t* test_error_config); 883 884 /** 885 ***************************************************************************** 886 ** \brief Disables LIN ERROR CTL. 887 ** 888 ** Disables HW injected channel transmitter errors. 889 ** 890 ** \param base [in] Pointer to LIN instance register area. 891 ** 892 ** \retval Refer \ref cy_en_lin_status_t 893 ** 894 *****************************************************************************/ 895 cy_en_lin_status_t Cy_LIN_ErrCtl_Disable(LIN_Type* base); 896 897 898 /** \} group_lin_functions */ 899 /** @} */ 900 901 #ifdef __cplusplus 902 } 903 #endif 904 #endif /*(CY_IP_MXLIN) */ 905 #endif /* __CY_LIN_H__ */ 906 907 /** \} group_lin */ 908 909 /*****************************************************************************/ 910 /* EOF (not truncated) */ 911 /*****************************************************************************/ 912
