General Transformer Specification (Xfrm)

This function is the interface of the first transformer in a transformer chain of Sender/Receiver communication. The length of the transformed data shall be calculated by the transformer during runtime and returned in the OUT parameter bufferLength. It may be smaller than the maximum buffer size used by the RTE for buffer allocation.

This function is the interface of the first transformer in a transformer chain of Client/Server communication. It takes the operation arguments and optionally the return value as input and outputs a uint8 array containing the transformed data. The length of the transformed data shall be calculated by the transformer during runtime and returned in the OUT parameter bufferLength. It may be smaller than the maximum buffer size used by the RTE for buffer allocation.

This function is the interface of the first transformer in a transformer chain of Sender/Receiver communication. The length of the transformed data shall be calculated by the transformer during runtime and returned in the OUT parameter bufferLength. It may be smaller than the maximum buffer size used by the RTE for buffer allocation. 5 General 4

This function is the interface of a first transformer in a transformer chain of Sender/Receiver communication (this is the last executed transformer on the receiving side!).

This function is the interface of the first transformer in a transformer chain of Client/Server communication (this is the last executed transformer on the receiving side!). It takes the constant buffer (IN parameter buffer) of length (IN parameter bufferLength which may be smaller than the maximum buffer size used by the RTE for buffer allocation) as input and outputs the operation arguments and optionally the return value (OUT parameters data_1, ..., data_n, and returnValue).

This function is the interface of a transformer which is not the first transformer in a transformer chain. It takes the output of an earlier transformer in the chain and transforms the data. The length of the transformed data shall be calculated by the transformer during runtime and returned in the OUT parameter bufferLength. It may be smaller than the maximum buffer size used by the RTE for buffer allocation.

This service returns the version information of the called transformer module.

This service initializes the transformer for the further processing.

This service deinitializes the transformer.

This function is the interface of the first transformer in a transformer chain of external trigger events. The length of the transformed data shall be calculated by the transformer during runtime and returned in the OUT parameter bufferLength. It may be smaller than the maximum buffer size used by the RTE for buffer allocation.

This function is the interface of a first transformer in a transformer chain of external trigger event communication (this is the last executed transformer on the trigger sink side!).

Function to extract the relevant protocol header fields of the message and the type of the message result of a transformer. - At the time being, this is limited to the types used for C/S communication (i.e., REQUEST and RESPONSE and OK and ERROR).

This is the type of the data structure containing the initialization data for the transformer.

Transformers shall be stateful only, if the dedicated transformer functionality requires maintaining a transformer state.

A transformer shall consider that the target ECU might have a different architecture than the sender ECU (e.g. 8/16/32bit, little/big endian, etc.) so the on-wire format shall be fixed.

A transformer shall clearly define endianness of multi-byte words.

A transformer shall clearly define the ordering of the contained data elements in the complex data if it is a serializer.

A transformer shall clearly define the data semantics.

A transformer shall clearly define the source (=target) data type of the data represented by the byte array if it is a serializer.

A transformer shall clearly define the padding of data.

The way to deal with unexpected data shall be specified by the transformer specific SWS. In general the transformer shall discard the unexpected data but shall tolerate the expected fraction.

A transformer shall be implemented re-entrant because there exist valid configurations which can lead to a concurrent execution of a transformer.

A transformer which uses in-place buffering shall use the in- put buffer also as output buffer. (See [SWS_Xfrm_00040] and [SWS_Xfrm_00045])

A transformer which uses out-of-place buffering shall work with two buffers: One for the input to the transformer and one for its output.

A transformer which uses out-of-place buffering shall not alter the data of the input buffer.

The first transformer in the chain on the sending side shall use out-of-place buffering.

The last transformer in the chain on the receiving side shall use out-of-place buffering.

A serializer shall take data elements (complex or atomic) and serialize them into a linear representation (byte array).

The serialization algorithm shall be defined for all possible com- plex data input.

A safety transformer shall protect the inter-ECU communication of safety related SWCs.

A safety transformer shall ensure the correct order of data trans- missions.

A safety transformer shall ensure the correct content of data transmissions.

A security transformer shall protect the inter-ECU communica- tion of security related SWCs.

A security transformer shall ensure the authenticity of data trans- missions.

A security transformer shall ensure the integrity of data trans- missions.

A security transformer shall ensure the freshness of data trans- missions.

Transformers shall return errors to the RTE as return codes.

If a transformer cannot generate a valid output, it shall return a hard error.

If a transformer produces an output but wants to signal warning to the SWC, it shall return a soft error.

Each transformer class shall have its own set of abstract errors.

Each transformer shall return only errors which are a subset of the errors defined for the transformer's transformer class.

A serializer transformer shall return one of the errors shown in Table 7.1.

A safety transformer shall return one of the errors shown in Ta- ble 7.2.

A security transformer shall return one of the errors shown in Table 7.3.

A transformer shall use the ImplementationDataType s de- fined by RTE in the transformer's Module Interlink Types Header file.

The function <Mip>_<transformerId> specified in [SWS_Xfrm_00036] shall exist for the first reference in the list of ordered references transformer from a DataTransformation to a TransformationTechnology if the DataTransformation is referenced by an ISignal in the role dataTrans- formation where the ISignal references a SystemSignal which is referenced by SenderReceiverToSignalMapping , a SenderRecRecordElementMapping or a SenderRecArrayElementMapping .

The function <Mip>_<transformerId> specified in [SWS_Xfrm_00038] shall exist for the first reference in the list of ordered references transformer from a DataTransformation to a TransformationTechnology if the DataTransformation is referenced by an ISignal in the role dataTrans- formation where the ISignal references a SystemSignal which is referenced by ClientServerToSignalMapping in the callSignal or returnSignal .

The function <Mip>_<transformerId> specified in [SWS_Xfrm_00040] shall exist for the non-first reference in the list of ordered references transformer from a DataTransformation to a Transformation- Technology if the DataTransformation is referenced by an ISignal in the role dataTransformation .

The function <Mip>_Inv_<transformerId> specified in [SWS_Xfrm_00042] shall exist for the first reference in the list of ordered references transformer from a DataTransformation to a TransformationTechnology if the DataTransformation is referenced by an ISignal in the role dataTrans- formation where the ISignal references a SystemSignal which is referenced by SenderReceiverToSignalMapping , a SenderRecRecordElementMapping or a SenderRecArrayElementMapping .

The function <Mip>_Inv_<transformerId> specified in [SWS_Xfrm_00044] shall exist for the first reference in the list of ordered references transformer from a DataTransformation to a TransformationTechnology if the DataTransformation is referenced by an ISignal in the role dataTrans- formation where the ISignal references a SystemSignal which is referenced by ClientServerToSignalMapping in the callSignal or returnSignal .

The function <Mip>_Inv_<transformerId> specified in [SWS_Xfrm_00046] shall exist for the non-first reference in the list of ordered refer- ences transformer from a DataTransformation to a TransformationTech- nology if the DataTransformation is referenced by an ISignal in the role data- Transformation .

A deserializer transformer (serializer transformer on receiver side) shall be able to return all or a subset of the deserialized data to the RTE.

An implementation of a transformer shall be able to cope with NULL_PTR as input data. The detailed behavior shall be specified in the specific trans- former SWS.

A custom transformer shall return one of the custom errors spec- ified for the custom transformer. See Table 7.4.

If a transformer returns a hard error, it shall leave the output buffer unchanged

Each function that satisfies the name pattern <Mip>_<trans- formerId> (independent from the position in the transformer chain) shall implement its BswModuleEntry which has the same shortName and is referenced by Xfrm- TransformerBswModuleEntryRef .

Each function that satisfies the name pattern <Mip>_Inv_- <transformerId> (independent from the position in the transformer chain) shall im- plement its BswModuleEntry which has the same shortName and is referenced by XfrmInvTransformerBswModuleEntryRef .

If a VariableDataPrototype is mapped to multiple ISig- nal s which referr to DataTransformation s and if those DataTransformation s referr to the same TransformationTechnology s at the beginning of their list of ordered references transformer and no XfrmVariableDataPrototypeIn- stanceRef is specified for that TransformationTechnology and no ComBased- Transformer is included in the transformer chains, the execution should be optimzed. As optimization those first transformers should be executed only once and the result should be taken as input for the further transformers for those ISignal s.

If the transformer execution is optimized, the XfrmImplemen- tationMapping shall map all transformers which execution can be optimized to the same BswModuleEntry .

If the transformer execution is optimized and one function trans- forms data (independent from the position in the transformer chain) for multiple ISig- nal s, the <sigName> of the functions name pattern ( <Mip>_<transformerId> ) may be any shortName of any ISignal which is transformed by that BswModuleEn- try .

Type of error Related error code Error value Error code if any other API service, except Get VersionInfo is called before the transformer module was initialized with Init or after a call to De Init <MIP>_E_UNINIT 0x01 Error code if an invalid configuration set was selected <MIP>_E_INIT_FAILED 0x02 API service called with wrong parameter <MIP>_E_PARAM 0x03 API service called with invalid pointer <MIP>_E_PARAM_POINTER 0x04

The name pattern transformerId should be used for the APIs which belong to the BswModuleEntry referenced from a XfrmImplementation- Mapping : • Com_<ComSignalName> if no XfrmVariableDataPrototypeInstanceRef exists in the XfrmImplementationMapping and XfrmISignalRef is used in XfrmSignal and the data are sent/received using Com module. • Com_<ComSignalGroupName> if no XfrmVariableDataPrototypeIn- stanceRef exists in the XfrmImplementationMapping and XfrmISignal- GroupRef is used in XfrmSignal and the data are sent/received using Com module. • LdCom_<LdComIpduName> if no XfrmVariableDataPrototypeIn- stanceRef exists in the XfrmImplementationMapping and the data are sent/received using LdCom module. • <ComponentName>_<p>_<o> if XfrmVariableDataPrototypeIn- stanceRef exists. where • <ComponentName> is the shortName of the SwComponentPrototype which describes the context of XfrmVariableDataPrototypeInstanceRef . • <p> is the shortName of the PortPrototype which describes the context of XfrmVariableDataPrototypeInstanceRef . (This is comparable to p used in the RTE APIs.) • <o> is the shortName of the VariableDataPrototype referenced by Xfrm- VariableDataPrototypeInstanceRef . (This is comparable to o used in the RTE APIs.) • <ComSignalName> is the shortName of ComSignal which references the ISignal (using ComSystemTemplateSystemSignalRef that references ISignalToIPduMapping which references the ISignal ) that references the DataTransformation . • <ComSignalGroupName> is the shortName of ComSignalGroup which ref- erences the ISignalGroup (using ComSystemTemplateSystemSignal- GroupRef that references ISignalToIPduMapping which references the ISignalGroup ) that references the DataTransformation . General • <LdComIpduName> is the shortName of LdComIPdu which references the ISignal (using LdComSystemTemplateSignalRef that references ISignalToIPduMapping which references the ISignal ) that references the DataTransformation .

A transformer shall support the Extended Production Errors shown in Table 7.5.

The Extended Production Error XFRM_E_MALFORMED_MESSAGE shall exist for every transformer which has XFRM_- E_MALFORMED_MESSAGE set.

If the value of the returnValue parameter is inside the range of hard errors (0x80-0xFF), the implementation of [SWS_Xfrm_00038] shall ignore the values of the ClientServerOperation 's arguments data_1 , ... , data_n as they are not filled with meaningful values.

If a Trigger is mapped to multiple ISignal s which refer to DataTransformation s and if those DataTransformation s refer to the same TransformationTechnology s at the beginning of the ordered transformer- Chain and no XfrmVariableDataPrototypeInstanceRef is specified for that TransformationTechnology and no ComBasedTransformer is included in the transformer chains, the execution should be optimized.

The function <Mip>_<transformerId> specified in [SWS_Xfrm_00102] shall exist for the first referenced TransformationTech- nology in the ordered transformerChain of a DataTransformation if the DataTransformation is referenced by an ISignal in the role dataTransfor- mation where the ISignal references a SystemSignal which is referenced by a TriggerToSignalMapping .

The function <Mip>_Inv_<transformerId> specified in [SWS_Xfrm_00104] shall exist for the first referenced TransformationTechnology in the ordered transformerChain of a DataTransformation if the DataTrans- formation is referenced by an ISignal in the role dataTransformation where the ISignal references a SystemSignal which is referenced by a TriggerToSig- nalMapping .

The function <Mip>_<transformerId> specified in [SWS_Xfrm_00036] shall exist for the first reference in the list of ordered references transformer from a DataTransformation to a TransformationTechnology if the DataTransformation is referenced by an DataPrototypeMapping in the role firstToSecondDataTransformation .

The function <Mip>_Inv_<transformerId> specified in [SWS_Xfrm_00042] shall exist for the first reference in the list of ordered references transformer from a DataTransformation to a TransformationTechnology if the DataTransformation is referenced by an DataPrototypeMapping in the role firstToSecondDataTransformation .

A transformer which is called with NULL_PTR as input data shall not change the output buffer unless the transformer invocation shall trigger an au- tonomous error reaction (see also [SWS_Rte_07420]).

⌊ DRAFT g The data type Std_TransformerForward shall be defined as follows: 1 struct Std_TransformerForward { 2 Std_TransformerForwardCode errorCode, 3 Std_TransformerClass transformerClass 4 };

⌊ DRAFT g A safety transformer shall handle the forwarded status shown in Table 8.1.

⌊ DRAFT g The underlying data type of the type Std_TransformerForwardCode shall be uint8 .

The function <Mip>_ExtractProtocolHeaderFields spec- ified in [SWS_Xfrm_91002] shall exist in case the respective transformer processes relevant protocol header fields related to the type of a message and the type of the message result. – This function shall extract this information and provide it in a canon- ical representation via its output arguments.

The function <Mip>_ExtractProtocolHeaderFields spec- ified in [SWS_Xfrm_91002] shall return E_NOT_OK in case of an error (e.g., parsing er- ror) during extraction. Neither messageType nor messageResult shall be modified in this case.

The function <Mip>_ExtractProtocolHeaderFields spec- ified in [SWS_Xfrm_91002] shall return E_OK otherwise.

Module Header File Imported Type Rte Rte.h Rte_Cs_TransactionHandleType Std_Types.h Std_ExtractProtocolHeaderFieldsType Std_Types.h Std_MessageResultType Std_Types.h Std_MessageTypeType Std_Types.h Std_ReturnType Std Std_Types.h Std_VersionInfoType

If there exists a XfrmImplementationMapping which references an ISignal or ISignalGroup sig1 and contains the optional parameter XfrmVariableDataPrototypeInstanceRef , all XfrmImplementa- tionMapping s which reference the same ISignal or ISignalGroup sig1 shall contain a XfrmVariableDataPrototypeInstanceRef .

The XfrmVariableDataPrototypeIn- stanceRef shall refer to the instance of a VariableDataPrototype which belongs to a subclass of an AtomicSwComponentType .

If no XfrmSignal exists and hence no ISignal or ISignalGroup is referenced, XfrmVariableDataPrototypeInstanceRef shall be used to reference the instance of the VariableDataPrototype which data shall be transformed.