/** @mainpage LIN Stack Documentation * * @authors FPT Software
Copyright by Freescale Semiconductor, 2008-2016 *
Copyright by NXP Semiconductors, 2016-2017 * *
*

Introduction

* *

*

*

    *
  1. Node Configuration Tool:

    2. * * The Node Configuration Tool is a built-in script of the LIN Stack package which allows user to easily generate the node * configuration .h and .c files based on LIN Configuration Description File (LCF) and Node Private Description File (LPF). * Those files are then in compiler integrated with LIN Stack source code and user application and after compilation downloaded * to the target derivative. Figure 3. shows the diagram of configuration data flow. * * @image html ConfigurationData.JPG *
    Figure 3. Configuration data
    * * The LDF file describes a complete LIN cluster including Master/slave mode definition and contains information to handle the cluster.
    * The NPF file contains information about LIN nodes such as node name, number of interface, MCU clock frequency, used communication channel * (e.g. SCI channel) and port (e.g. GPIO port), etc., required for full description of the node. * *
  2. LIN Stack:

    3. * * The Figure 4. shows the details of modules in the LIN Stack package. It also demonstrates the relationship among modules and the direction of function call among them. * * @image html LIN_Stack_Architecture1.jpg *
    Figure 4. LIN Stack Layer Diagram
    * * * LIN Stack software package provides support for LIN2.1, LIN 2.0 and J2602 communication protocols. The stack package is divided into the layers as follows: * *
      *
    1. The lowest layer, Board Support Package (BSP) layer is comprised of codes, which implements the tasks dedicated to specific MCU platform: * interrupt service routines, i/o port setup, memory handling and so on. There are three interfaces implemented within the stack package: SCI, SLIC, GPIO and XGATE.
      2. * *
    2. Low level layer consists of core functions for the LIN protocol such as the frames handling, signals transmission and reception, * data preparation, etc. Besides, this layer contains common implementation functions for the lowest layer to provide the interface abstraction. * Function for LIN cluster setup can be found here as well. This layer interacts with the core API layer through low level API functions.
      3. * *
    3. Core API layer consists of API functions as defined by the LIN2.1/J2602 specification enabling the user to utilize the LIN2.1/J2602 * communication within the user application. Both the static and dynamic modes for calling the API functions are supported. The core API layer * interacts with the low level layer and can be called by such upper layers as LIN2.1 TL API, LIN TL J2602 or application for diagnostic implementation
      4. * *
    4. Transport layer stands between the application layer and the core API layer including LIN2.1 TL API and LIN TL J2602. * This layer provides APIs for the transport protocol, node configuration and diagnostic. For LIN2.1, all components will be * extended from LIN 2.0 specification. The node configuration for J2602 implements only some functions of LIN 2.0 specification. * The layer contains some main components below: *
        *
      • Transport protocol: *
          *
        • LIN2.1: Error handing and communication functions are added to LIN 2.0 specification.
          • *
        *
        • * *
      • Node configuration: *
          *
        • LIN2.1 extends slave configuration and assign frame with ID range to LIN 2.0. The assign frame with ID is removed.
          • * *
        • J2602 simplifies LIN 2.0 Node configuration.
          • *
        *
        • * *
      • Diagnostic: * *
          *
        • LIN 2.0 Diagnostic implements functions as diagnostic service. In the other hand, LIN2.1 Diagnostic implements functions.
          • *
        *
        • *
      *
      5. * *
    5. Application layer is the highest layer which stands for applications of user.
      6. *
    *
* *

* */ /** * @defgroup LIN_Stack LIN stack */ /** @defgroup diagnostic_group Diagnostic services * @ingroup LIN_Stack * @brief Diagnostic services defines methods to implement diagnostic data transfer between a master node, respectively a diagnostic tester, and the slave nodes * @details Three different classes of diagnostic nodes are defined. Class I is using normal signalling and class II and class III uses the transport layer.

* The master node and the diagnostic tester are connected via a back-bone bus (e.g. CAN). The master * node shall receive all diagnostic requests addressed to the slave nodes from the * back-bone bus, and gateway them to the correct LIN cluster(s). Responses from the * slave nodes shall be gatewayed back to the back-bone bus through the master node.

* All diagnostic requests and responses (services) addressed to the slave nodes can be * routed in the network layer (i.e. no application layer routing), if the Diagnostic and * Transport Layer Protocol of tester back-bone-bus master node fulfills the respective * needs. In this case, the master node must implement the LIN transport protocol, see * Transport Layer Specification, as well as the transport protocols used on the back- * bone busses (e.g. ISO15765-2 on CAN) */ /** @defgroup transport_group Transport layer API * @ingroup LIN_Stack * @brief Transport layer stands between the application layer and the core API layer * @details * This layer consists the implementation of data transportation which contains one or more LIN frames. * It is situated between the application layer and the core API layer including LIN2.1 TL API and LIN TL J2602. * This layer provides APIs for the transport protocol, node configuration and diagnostic. * For LIN 2.1, all components will be extended from LIN 2.0 specification. * The node configuration for J2602 implements only some functions of LIN 2.0 specification */ /** @defgroup coreapi_group LIN Core API * @ingroup LIN_Stack * @brief Refer to chappter 7, LIN 2.1 specification * @details * - Core API layer consists of API functions as defined by the LIN2.1/J2602 specification * - Enabling the user to utilize the LIN2.1/J2602 communication within the user application. * - Both the static and dynamic modes for calling the API functions are supported. * - The core API layer interacts with the low level layer and can be called by such upper layers as LIN2.1 TL API, * LIN TL J2602 or application for diagnostic implementation */ /** @defgroup lowlevel_group Low level API * @ingroup LIN_Stack * @brief Low level layer consists of core functions for the LIN protocol * @details This layer contains the implementation of LIN protocol such as the frames handling, * signals transmission and reception, data preparation, etc. Besides, this layer contains common implementation functions * for the lowest layer to provide the interface abstraction. Function for LIN cluster setup can be found here as well. * This layer interacts with the core API layer through low level API functions. */ /** @defgroup bsp_group Board Support Package * @ingroup LIN_Stack * @brief BSP (Board Support Package) is the lowest layer of the LIN Stack. * @details BSP is comprised of codes, * which implements the tasks dedicated to specific MCU platform: interrupt service routines, i/o port setup, memory handling and so on. * There are four interfaces implemented within the stack package: SCI, SLIC, GPIO and SCI + XGATE, UART. */ /** @defgroup common_core_api_group Common Core API * This group contains general core APIs that used for both protocol LIN 2.1 and J2602. * * @ingroup coreapi_group */ /** @defgroup LIN21_core_api_group LIN 2.1 Specific API * LIN 2.1 is extended from in LIN 2.0 specification through diagnostic services and few functions were removed as obsolete. *
    *
  1. LIN 2.1 is compatible with LIN 2.0: * * *
    2. * *
  2. Changes between LIN 2.0 and LIN 2.1 * * LIN2.1 enhance the capacity of LIN2.0 on event-triggered frame collision handling and diagnostic services supported. * Besides, several features are add to fulfill powerful capacity of LIN network such as configuration service, assign frame ID range configuration, etc. *
* @ingroup coreapi_group */ /** @defgroup J2602_core_api_group J2602 Specific API * J2602 protocol is LIN 2.0 based. It contains LIN 2.0's modules to support Signal management, network management, scheduler and J2602 status management. * The goal of J2602 is to improve the interoperability and interchangeability of LIN devices within a network by resolving those LIN2.0 requirements that are ambiguous, conflicting, or optional. * Moreover, J2602 provides additional requirements that are not present in LIN2.0. For example: fault tolerant, operation, network topology, etc. * Different to LIN2.1 protocol, J2602 does not support sporadic and event trigger frames in communication. * @ingroup coreapi_group */ /** @defgroup GPIO_group GPIO interface * GPIO interface uses GPIO pins to communicates with LIN network. This group provides functions that help higher layers communicate with it. Only 9S12QD4 is supported. * * @ingroup bsp_group */ /** @defgroup SLIC_group SLIC interface * SLIC (Slave LIN Interface Controller) is one integrated module of MCU, it support MCU communicating with LIN network as slave node. Only 9S08EL32 is supported. * * @ingroup bsp_group */ /** @defgroup SCI_group SCI interface * This group contains functions that help physical module can communicate with LIN network through SCI module. * List of supported MCUs with version of SCI and number of SCI channels is in table below: * @image html SCI_allversions.png * * @ingroup bsp_group */ /** @defgroup UART_group UART interface * UART interface uses UART to communicate with LIN network. * @ingroup bsp_group */ /** @defgroup XGATE_group XGATE interface * This interface use SCI to communicate with LIN network and XGATE to process MCU's interrupts. * * @ingroup bsp_group */ /** @defgroup resync_group Resynchronize module * Local interconnect network (LIN) is widely used standard for low cost automotive networks. * In order to ensure reliable communication via LIN bus, a bus clock of MCU needs to be accurate enough to avoid errors. * MCU can use crystal or ceramic resonator to provide very accurate bus clocks. However, LIN protocol was designed to allow more cost-effective solution. * An automatic resynchronization feature allows more cost-effective solution: MCUs can use on-chip oscillators to implement LIN slaves, even though the on-chip oscillators have less accuracy than a crystal. * The automatic resynchronization module use the LIN SYNC field which is composed of five falling edges to synchronize with the master baud rate. * The module measures the sync byte field and adjusts the slave bus frequency after each LIN sync field reception from the master node. * * @ingroup bsp_group */ /** @defgroup autobaud_group Autobaud Feature * AUTOBAUD is an extensive feature in LIN Driver which allows a peripheral MCU to detect baud rate of LIN bus and adapt its original baud rate to bus value. * Auto Baud is applied when the baud rate of the incoming data is unknown or the baud rate is fixed with some specific values. * Each LIN network might have different configuration on such baudrates. * One MCU can work with different configurations without flashing. * @ingroup bsp_group */ /** @defgroup 9s08qd4_group 9S08QD4 MCU * @ingroup GPIO_group */ /** @defgroup 9s08el32_group 9S08EL32 MCU * @ingroup SLIC_group */ /** @defgroup driver_cluster_group Driver and cluster management * * @brief initialization for LIN node. * * @details * * @ingroup common_core_api_group */ /** @defgroup signal_interract_group Signal interaction * * @brief This group contains APIs that help you communicate with signals of LIN node. * * @details * * @ingroup common_core_api_group */ /** @defgroup notification_group Notification * * @brief This group contains APIs that let you know when a signal's value changed. * * @details * * @ingroup common_core_api_group */ /** @defgroup schedule_management_group Schedule management * * @brief This group contains APIs that help you manage schedules table in master node only. * * @details * * @ingroup common_core_api_group */ /** @defgroup interface_management_group Interface management * * @brief This group contains APIs that help you manage interface(s) in LIN node. * * @details * * @ingroup common_core_api_group */ /** @defgroup call_out_group User provided call-outs * * @brief This group contains APIs which may be called from within the LIN module in order to enable/disable LIN communication interrupts. * * @details * * @ingroup common_core_api_group */ /** @defgroup commontl_api_group Common API * @brief contains APIs that used for both protocols LIN2.1 and J2602 * * @ingroup transport_group */ /** @defgroup lin21tl_api_group LIN 2.1 specific API * @brief contains APIs that only used for LIN 2.1 protocol * * @ingroup transport_group */ /** @defgroup j2602tl_api_group J2602 specific API * @brief contains APIs that only used for J2602 protocol * * @ingroup transport_group */ /** @defgroup node_configuration_group Node configuration * * @brief This group contains APIs that used for node configuration purpose. * * @details * * @ingroup lin21tl_api_group */ /** @defgroup node_identification_group Node identification * * @brief This group contains API that used for node identification purpose. * * @details * * @ingroup lin21tl_api_group */ /** @defgroup initialization_group Initialization * * @brief Initialize transport layer (queues, status, ...). * * @details * * @ingroup commontl_api_group */ /** @defgroup raw_api_group Raw API * * @brief The raw API is operating on PDU level and it is typically used to gateway PDUs * between CAN and LIN. * * @details Usually, a FIFO is used to buffer PDUs in order to handle the * different bus speeds. * * @ingroup commontl_api_group */ /** @defgroup cooked_api_group Cooked API * * @brief Cooked processing of diagnostic messages manages one complete message at a time. * * @ingroup commontl_api_group */