Add initial operation for LIN bus

docs/4_4_2_lin.adoc

@@ -1,3 +1,334 @@
 ==== LIN
+This chapter describes the <<low-cut-layered-standard-bus-protocol, Layered Standard Bus Protocol>> for LIN.
+
+===== Operations
+This section defines the allowed operations for LIN.
+The following tables provides an overview of all operations and specifies the position and length of the corresponding arguments, as well as the respective flow direction.
+
+====== Transmit [[low-cut-lin-transmit-operation]]
+There are three types of transmit operations, each representing the transmission of a LIN header, a response and a combination of a header and response.
+
+.Detailed description of the LIN Header operation.
+[#table-lin-header-operation]
+[cols="5,4,3,20"]
+|====
+h|Name 3+| Header
+h|Description 3+| Represents an operation for the transmission of a LIN header from a LIN Master to LIN slaves.
+h|OP Code [hex] 3+| 0x10
+.5+h|Content h|Argument h|Length h|Description
+| OP Code | 1 byte | Contains the OP Code of the specified operation.
+For this operation the OP Code always has the value 0x10.
+| Total Length | 4 byte | Defines the cumulative length of all arguments in bytes.
+For this operation always applies: `Total Length = 7`.
+| PID | 1 byte | The specified protected ID (PID) of the LIN message.
+The maximum length of a PID is 8-bit.
+| Response Data Length | 1 byte | The size of the response in byte.
+h|Behavior
+3+|The Header operation shall be provided by Network FMUs to initiate the transmission of a LIN header.
+In case of direct connected Network FMUs (see <<common-concepts-direct-communication>>), the FMU importer forwards the operation directly to the receiving Network FMUs.
+If a Bus Simulation is involved (see <<common-concepts-composition-with-dedicated-bus-simulation-fmu>> and <<common-concepts-importer-with-integrated-bus-simulation>>), the FMU importer forwards the operation initially to the Bus Simulation, where the operation is distributed with respect to the simulated bus behavior.
+Depending on the simulation details, the Bus Simulation might response with a <<low-cut-lin-bus-error-operation, Bus Error>> or <<low-cut-lin-format-error-operation, Format Error>> operation.
+
+|====
+
+.Detailed description of the LIN Response operation.
+[#table-lin-response-operation]
+[cols="5,4,3,20"]
+|====
+h|Name 3+| Response
+h|Description 3+| Represents an operation for the transmission of a LIN response from a LIN slave to the LIN Master.
+h|OP Code [hex] 3+| 0x11
+.7+h|Content h|Argument h|Length h|Description
+| OP Code | 1 byte | Contains the OP Code of the specified operation.
+For this operation the OP Code always has the value 0x11.
+| Total Length | 4 byte | Defines the cumulative length of all arguments in bytes.
+For this operation always applies: `Total Length = 8 + Data Length`.
+| PID | 1 byte | The specified protected ID (PID) of the LIN message.
+The maximum length of a PID is 8-bit.
+| Response Error | 1 byte | Represents the Response Error field of a LIN frame.
+For specification the boolean values `TRUE` and `FALSE` (see <<table-boolean-value-kinds>>) shall be used.
+| Data Length | 1 byte | Specifies the length of the Data argument in bytes.
+| Data | n byte | Stores the given frame data to transfer, whereby the valid length of the data depends on the LIN Format.
+h|Behavior
+3+|The Response operation shall be provided by Network FMUs to initiate a response to a given LIN header.
+In case of direct connected Network FMUs (see <<common-concepts-direct-communication>>), the FMU importer forwards the operation directly to the receiving Network FMUs.
+If a Bus Simulation is involved (see <<common-concepts-composition-with-dedicated-bus-simulation-fmu>> and <<common-concepts-importer-with-integrated-bus-simulation>>), the FMU importer forwards the operation initially to the Bus Simulation, where the operation is distributed with respect to the simulated bus behavior.
+Depending on the simulation details, the Bus Simulation might response with a <<low-cut-lin-bus-error-operation, Bus Error>> or <<low-cut-lin-format-error-operation, Format Error>> operation.
+
+|====
+
+.Detailed description of the LIN Header Response operation.
+[#table-lin-header-response-operation]
+[cols="5,4,3,20"]
+|====
+h|Name 3+| Header Response
+h|Description 3+| Represents an operation for the transmission of a LIN header and response from a LIN Master to LIN slaves.
+h|OP Code [hex] 3+| 0x12
+.6+h|Content h|Argument h|Length h|Description
+| OP Code | 1 byte | Contains the OP Code of the specified operation.
+For this operation the OP Code always has the value 0x12.
+| Total Length | 4 byte | Defines the cumulative length of all arguments in bytes.
+For this operation always applies: `Total Length = 7 + Data Length`.
+| PID | 1 byte | The specified protected ID (PID) of the LIN message.
+The maximum length of a PID is 8-bit.
+| Data Length | 1 byte | Specifies the length of the Data argument in bytes.
+| Data | n byte | Stores the given frame data to transfer, whereby the valid length of the data depends on the LIN Format.
+h|Behavior
+3+|The Header Response operation shall be provided by Network FMUs to initiate the transmission of a LIN frame that contains the specified header and response.
+In case of direct connected Network FMUs (see <<common-concepts-direct-communication>>), the FMU importer forwards the operation directly to the receiving Network FMUs.
+If a Bus Simulation is involved (see <<common-concepts-composition-with-dedicated-bus-simulation-fmu>> and <<common-concepts-importer-with-integrated-bus-simulation>>), the FMU importer forwards the operation initially to the Bus Simulation, where the operation is distributed with respect to the simulated bus behavior.
+Depending on the simulation details, the Bus Simulation might response with a <<low-cut-lin-bus-error-operation, Bus Error>> or <<low-cut-lin-format-error-operation, Format Error>> operation.
+
+|====
+
+====== Format Error [[low-cut-lin-format-error-operation]]
+Represents a format error that indicates a syntax or content error of receiving operations.
+See <<low-cut-format-error-operation, Format Error>> for definition.
+
+====== Bus Error [[low-cut-lin-bus-error-operation]]
+The Bus Error operation represents special bus communication errors, which are delivered to the LIN Master node in the network.
+
+.Detailed description of the Bus Error operation.
+[#table-lin-bus-error-operation]
+[cols="5,4,3,20"]
+|====
+h|Name
+3+|Bus Error
+h|Description
+3+|Represents an operation for bus communication error handling.
+h|OP Code [hex]
+3+|0x20
+.5+h|Content h|Argument h|Length h|Description
+|OP Code
+|1 byte
+|Contains the OP Code of the specified operation.
+For this operation the OP Code always has the value 0x20.
+
+|Total Length
+|4 byte
+|Defines the cumulative length of all arguments in bytes.
+For this operation always applies: `Total Length = 10`.
+
+|ID
+|4 byte
+|The specified ID of the LIN message which triggers the error.
+
+|Error Code
+|1 byte
+|The specified error code, basing on the table below.
+
+h|Behavior
+3+|The specified operation shall be produced by the Bus Simulation and consumed by Network FMUs.
+An Error operation is always a reaction from the Bus Simulation to a <<low-cut-lin-transmit-operation, Transmit operation>> that was produced by a Network FMU.
+Out of this Error operations are available in the <<common-concepts-composition-with-dedicated-bus-simulation-fmu, Composition with dedicated Bus Simulation FMU>> and <<common-concepts-importer-with-integrated-bus-simulation, Importer with Integrated Bus Simulation>> communication use case only.
+
+|====
+
+The following codes are allowed to use as Error Code: 
+
+.Overview of the available error states and codes.
+[#table-lin-bus-error-codes]
+[cols="1,3,20"]
+|====
+
+h|State h|Error Code h|Description
+
+|BIT_ERROR
+|0x01
+|Represents a bit error.
+The given error is always related to a specific <<low-cut-lin-transmit-operation, Transmit operation>>.
+
+|CHECKSUM_ERROR
+|0x02
+|Represents a CRC error.
+The error can occurs during a collision of multiple response frames when Event-Triggered-Frames are used.
+The given error is always related to a specific <<low-cut-lin-transmit-operation, Transmit operation>>.
+
+|IDENTIFIER_PARITY_ERROR
+|0x03
+|Represents an Identifier Parity Error.
+The error can occurs during a collision of multiple LIN headers.
+The given error is always related to a specific <<low-cut-lin-transmit-operation, Transmit operation>>.
+
+|SLAVE_NOT_RESPONDING_ERROR
+|0x04
+|Represents a Slave Not Responding Error.
+The error can occurs if LIN Slaves does not response to a specified LIN header.
+The given error is always related to a specific <<low-cut-lin-transmit-operation, Transmit operation>>.
+
+|SYNCH_FIELD_ERROR
+|0x05
+|Represents a Inconsistent-Synch Field Error.
+The given error is always related to a specific <<low-cut-lin-transmit-operation, Transmit operation>>.
+
+|PHYSICAL_BUS_ERROR
+|0x06
+|Represents a Physical Bus Error.
+The given error is always related to a specific <<low-cut-lin-transmit-operation, Transmit operation>>.
+
+|====
+
+====== Configuration [[low-cut-lin-configuration-operation]]
+The `Configuration operation` allows Network FMUs the configuration of the Bus Simulation with parameters like baud rate information and further options.
+The following information are included within this operation: 
+
+
+.Detailed description of the Configuration operation.
+[#table-lin-configuration-operation]
+[cols="5,1,10,4,3,20"]
+|====
+h|Name
+5+|Configuration
+h|Description
+5+|Represents an operation for the configuration of a Bus Simulation.
+In detail the configuration of a LIN baud rate is possible.
+Also the configuration of further options, like LIN Master or LIN Slave representation, is supported by this operation.
+h|OP Code [hex]
+5+|0x30
+.7+h|Content 3+h|Argument h|Length h|Description
+3+|OP Code
+|1 byte
+|Contains the OP Code (0x30) of the operation.
+
+3+|Total Length
+|4 byte
+|Defines the cumulative length of all arguments in bytes.
+The following applies for this operation: `Total Length = 6 + Length of parameter arguments in bytes`.
+
+3+|Parameter Type
+|1 byte
+|Defines the current configuration parameter.
+Note that only one parameter can be set per `Configuration operation`.
+
+.3+h|
+4+h|Parameters
+
+|LIN_BAUDRATE
+|Baudrate
+|4 byte
+|The specified baudrate value to configure, whereby the specified ranges are defined by the LIN standard.
+The required unit for the baudrate value is bit/s.
+
+|LIN_NODE_DEFINITION
+|Node Definition
+|1 byte
+|Configures the required node type (Master or Slave) within a Bus Simulation.
+Possible values are: `LIN_MASTER` and `LIN_SLAVE` (see <<table-lin-configuration-node-definition-kinds>>).
+
+h|Behavior
+5+|The specified operation shall be produced by a Network FMU and consumed by the Bus Simulation.
+The operation shall not be routed to other Network FMUs by the Bus Simulation.
+A Network FMU shall ignored this operation on consumer side.
+The configuration shall be completed by a specified Network FMU before it produces any <<low-cut-lin-transmit-operation, Transmission operation>>.
+Any configuration can be repeated multiple times during the runtime of a Network FMU.
+If required configuration parameters are not adjusted by a Network FMU the Bus Simulation shall choose a default behavior by itself.
+For a smooth simulation, it must be ensured that exactly one master node is configured.
+|====
+
+The following Kind values are allowed to be used: 
+
+.Overview of the available configuration kinds and values.
+[#table-lin-configuration-kinds]
+[cols="1,1,5"]
+|====
+
+h|Kind h|Value h|Description
+|LIN_BAUDRATE|0x01|This code indicates that a LIN baud rate should be configured for the Bus Simulation.
+|LIN_NODE_DEFINITION|0x02|This code configures the specified node type (Master or Slave) within a Bus Simulation.
+
+|====
+
+The following values for the Arbitration Lost Behavior option are defined:
+
+.Overview of the available node definition values for LIN.
+[#table-lin-configuration-node-definition-kinds]
+[cols="2,1,5"]
+|====
+
+h|Node Definition h|Value h|Description
+|LIN_MASTER|0x01|Configuration of a LIN Master node within a specified Bus Simulation.
+|LIN_SLAVE|0x02|Configuration of a LIN Slave node within a specified Bus Simulation.
+
+|====
+
+====== Status [[low-cut-lin-status-operation]]
+By using the `Status operation` a Network FMU can communicate the current LIN node state of the simulated LIN Controller within the Network FMU to the Bus Simulation.
+The following information are included within this operation: 
+
+.Detailed description of the status operation.
+[#table-lin-status-operation]
+[cols="5,4,3,20"]
+|====
+h|Name
+3+|Status
+h|Description
+3+|Represents an operation for status handling.
+h|OP Code [hex]
+3+|0x31
+.4+h|Content h|Argument h|Length h|Description
+|OP Code
+|1 byte
+|Contains the OP Code of the specified operation.
+For this operation the OP Code always has the value 0x31.
+
+|Total Length
+|4 byte
+|Defines the cumulative length of all arguments in bytes.
+For this operation always applies: `Total Length = 6`.
+
+|Status
+|1 byte
+|The specified status code, basing on the table below.
+
+h|Behavior
+3+|The specified operation shall be produced by Network FMUs and consumed by the Bus Simulation.
+The operation shall not be routed to other Network FMUs by the Bus Simulation.
+A Network FMU shall ignore this operation on the consumer side.
+A Network FMU shall report its status to the Bus Simulation after it changes.
+
+|====
+
+The following status values are allowed to use: 
+
+.Overview of the available status values.
+[#table-lin-status-values]
+[cols="1,1,5"]
+|====
+
+h|Kind h|Value h|Description
+|POWER_OFF|0x01|Indicates that a simulated LIN controller within the Network FMU has currently the LIN node state: Power Off.
+|INITIALIZATION|0x02|Indicates that a simulated LIN controller within the Network FMU has currently the LIN node state: Initialization.
+|OPERATION|0x03|Indicates that a simulated LIN controller within the Network FMU has currently the LIN node state: Operation.
+|SLEEP|0x04|Indicates that a simulated LIN controller within the Network FMU has currently the LIN node state: Sleep.
+|====
+
+====== Wake-up [[low-cut-lin-wakeup-operation]]
+By using the `Wakeup operation` the underlying Bus Simulation can trigger a bus-specific wake up.
+
+.Detailed description of the Wakeup operation.
+[#table-lin-wakeup-operation]
+[cols="5,4,3,20"]
+|====
+h|Name
+3+|Wakeup
+h|Description
+3+|Represents an operation for triggering a bus-specific wake up.
+h|OP Code [hex]
+3+|0x32
+.3+h|Content h|Argument h|Length h|Description
+|OP Code
+|1 byte
+|Contains the OP Code of the specified operation.
+For this operation the OP Code always has the value 0x32.
+
+|Total Length
+|4 byte
+|Defines the cumulative length of all arguments in bytes.
+For this operation always applies: `Total Length = 5`.
+
+h|Behavior
+3+|The specified operation shall be produced by a Network FMU and distributed to all participants, except the wake-up initiator, of the bus by using the Bus Simulation.
+If a Network FMU does not support wake-up this operation can be ignored on consumer side.
+
+|====
 
-#TODO dSPACE#