Communication Stack Types (ComStack_Types)

Via ComStack_Types.h, the comstack module provides the common types with which all layers of the Classic communication stack address and exchange PDUs: PduIdType as handle, PduLengthType as length, and PduInfoType with payload pointer, metadata pointer, and length ([SWS_COMTYPE_00011]). Transport protocols copy large PDUs segment by segment via StartOfReception, CopyRxData, and CopyTxData. They report the buffer state with BufReq_ReturnType, while RetryInfoType controls confirmation and retransmission ([SWS_COMTYPE_00012]). Most important constraint: The width of PduIdType and PduLengthType depends on the EcuC configuration and is generated.

more ›

Module comstack defines the common type inventory of the Classic communication stack. This includes PduIdType, PduLengthType, PduInfoType, BufReq_ReturnType, RetryInfoType, as well as identifiers for channels and sub-networks, all available via ComStack_Types.h ([SWS_COMTYPE_00011], [SWS_COMTYPE_00038]). Bus interfaces, transport protocols, PduR, diagnostic modules, and RTE use the same types; RTE imports them explicitly (SWS RTE p. 833).

Context diagram: One type inventory for all layers, dimensioned via the EcuC configuration. Sources: [SWS_COMTYPE_00005], SWS RTE p. 833

Handles and lengths depend on the configuration. PduIdType is uint8 or uint16; PduLengthType is uint8, uint16, or uint32; both are generated from the EcuC configuration ([SWS_COMTYPE_00005], [SWS_COMTYPE_00008]). Each providing module selects its handle IDs itself. They only need to be unique per API; PduR translates them along the routing path (ECU Configuration p. 156).

PduInfoType bundles payload pointer, metadata pointer, and length. The structure thus carries transmit requests, receive indications, and Trigger Transmit. Large PDUs are copied in chunks: the transport protocol repeatedly calls CopyTxData of the upper layer via PduR (SWS PduR p. 109). Reception begins with StartOfReception and continues with CopyRxData.

Sequence diagram: The transport protocol pulls the transmit data in a loop from DCM; confirmation follows at the end. Sources: SWS PduR p. 109

BufReq_ReturnType reports errors and bottlenecks ([SWS_COMTYPE_00012]):

• BUFREQ_E_BUSY: temporarily no buffer or insufficient data; the call may be retried.
• BUFREQ_E_OVFL: no buffer of the required length.
• BUFREQ_E_NOT_OK: abort.

RetryInfoType controls confirmation and retransmission during TP transmission with TP_DATACONF, TP_CONFPENDING, and TP_DATARETRY including offset TxTpDataCnt ([SWS_COMTYPE_00027], [SWS_COMTYPE_00037]).

Additional identifier types complement the inventory. NetworkHandleType (uint8) designates a communication channel. TPParameterType selects STmin, Block Size, or bandwidth control for modification ([SWS_COMTYPE_00031]). In R20-11, PNCHandleType is derived from uint8 ([SWS_COMTYPE_00036]); the R23-11 version specifies uint16 deviating from this (SWS ComStackTypes p. 17).

more ›

Role: common type inventory of the communication stack

Module comstack does not provide any services of its own. It defines the data types through which the modules of the Classic communication stack communicate with each other. These include PduIdType, PduLengthType, PduInfoType, BufReq_ReturnType, TpDataStateType, RetryInfoType, TPParameterType, NetworkHandleType, and PNCHandleType. They are available via ComStack_Types.h ([SWS_COMTYPE_00011], [SWS_COMTYPE_00037], [SWS_COMTYPE_00038]). Interpretation: The module itself therefore has no runtime behavior. Question Q-766338989232e06a (open) Sequences, states, and error reactions only arise in the modules that use these types in their interfaces.

The system boundary therefore runs across the entire stack. The same types are used by:

• bus interfaces like CanIf and transport protocols like CanTp (SWS CanIf p. 87),
• PDU Router and diagnostic modules like DCM (SWS PduR p. 109),
• SecOC (SWS SecOC p. 110),
• RTE, which explicitly imports BufReq_ReturnType, PduIdType, PduInfoType, PduLengthType, and RetryInfoType from ComStack_Types.h (SWS RTE p. 833).

Context diagram: All layers from the bus interface to the RTE rely on the same set of types from ComStack_Types.h; its sizes are generated from the EcuC configuration. Sources: [SWS_COMTYPE_00005], SWS RTE p. 833, SWS PduR p. 33, SWS ComM p. 171

PDU handles and lengths: Identity and size of a PDU

PduIdType is a zero-based integer in the range 0…<PduIdmax>. Its width (uint8 or uint16) depends on the maximum number of PDUs managed by an individual software module. The generator tool generates it from the value in ComStack_Cfg.h configured in the virtual EcuC layer ([SWS_COMTYPE_00005]). The associated parameter PduIdTypeEnum defines the rule: UINT8 is sufficient as long as no module handles more than 256 PDUs, otherwise UINT16 is required (ECU Configuration p. 153).

Similarly, PduLengthType is defined depending on the configuration as uint8, uint16, or uint32. The decisive factor is the maximum length of the PDUs that an ECU transmits ([SWS_COMTYPE_00008]). Transport protocols also derive lengths from the EcuC: CanTp determines the maximum transmission length of the N-PDU from the EcuC parameter PduLength (SWS CanTp p. 60).

The APIs of the stack combine two things: a pointer to the PDU data buffer and a handle ID that defines which PDU this pointer belongs to. The providing module freely chooses the value of the handle ID. Thus, the same PDU can go from Com with ID 5 to the PduR, and from the PduR with ID 19 to CanIf. The ID only needs to be unique within the scope of the respective API (ECU Configuration p. 156). To enable two modules to reference the same PDU, the module-independent EcucPduCollection exists in the virtual module configuration EcuC (ECU Configuration p. 154). The PduR identifies a routing path via source ID and destination IDs, translates the IDs, and passes the PduInfoType value on unchanged (SWS PduR p. 33).

Collaboration diagram: Each interface has its own handle IDs; the PduR translates them while the common PDU is referenced via the EcucPduCollection. Sources: ECU Configuration p. 156, ECU Configuration p. 154, SWS PduR p. 33

PduInfoType: Payload, metadata, and length in a single structure

PduInfoType bundles three elements ([SWS_COMTYPE_00011]):

• SduDataPtr points to the payload.
• MetaDataPtr points to metadata such as CAN ID, socket ID, or diagnostic addresses. Their length and type are statically configured per PDU; elements with more than 8 bits are in platform byte order.
• SduLength of type PduLengthType specifies the SDU length in bytes.

The same structure supports multiple interaction forms:

• Transmit request: <Mod>_Transmit(TxPduId, const PduInfoType*) passes length, data pointer, and metadata pointer and returns E_OK or E_NOT_OK (SWS CanIf p. 87).
• Reception indication: <Mod>_RxIndication(RxPduId, const PduInfoType*). For CanNm, the data pointer is valid only until the indication returns (SWS CanNm p. 73).
• Trigger Transmit: PduInfoPtr is input and output. Upon invocation, SduLength contains the available buffer size, and upon return, the length of the copied data (SWS CanIf p. 107). In the preceding transmit request, the upper layer passes only the length; SduDataPtr then points to NULL (SWS CanIf p. 158).
• TP copy interfaces: StartOfReception, CopyRxData, and CopyTxData with return value BufReq_ReturnType (SWS PduR p. 93).

Transport protocol buffers: Segment-by-segment copying instead of passing

Large PDUs are not passed as a whole. The transmitter retrieves the data piece by piece: DCM initiates CanTp_Transmit via the PduR. CanTp then repeatedly calls PduR_CanTpCopyTxData, which is forwarded to Dcm_CopyTxData. At the end are PduR_CanTpTxConfirmation and Dcm_TpTxConfirmation (SWS PduR p. 109). The following applies to the parameters of CopyTxData:

• info provides the destination buffer and the number of bytes to be copied.
• An SduLength of 0 only reports a state change in the retry parameter or queries the available amount of data; SduDataPtr may then be NULL_PTR (SWS PduR p. 93).
• availableDataPtr reports the remaining transmit data. TP modules with dynamic payload length, such as FrIsoTp, use this to dimension the subsequent Consecutive Frames (SWS LdCom p. 34).

Sequence diagram: During TP transmission, the transport protocol pulls the data in a loop from the upper layer via the PduR; the confirmation only follows after the last segment. Sources: SWS PduR p. 109, SWS PduR p. 93, [SWS_COMTYPE_00012]

Reception proceeds in three steps:

1. StartOfReception opens the connection. info carries the data of the First or Single Frame including metadata, or it is NULL_PTR if neither is present. TpSduLength specifies the total length. Via bufferSizePtr, the receiver reports its free buffer; the transport protocol calculates the Block Size from this (SWS PduR p. 92).
2. Each CopyRxData call provides the next piece of the I-PDU and writes back the remaining buffer (SWS PduR p. 91).
3. An RxIndication completes reception.

If a TP PDU is additionally gatewayed, the PduR buffers it itself because the DCM has no knowledge of the gatewaying (SWS PduR p. 112).

Sequence diagram: TP reception starts with a buffer negotiation, continues segment by segment, and ends with the indication. Sources: SWS PduR p. 112, SWS PduR p. 92, SWS PduR p. 91

Confirmation and retry: RetryInfoType and TpDataStateType

RetryInfoType contains two fields ([SWS_COMTYPE_00037]):

• TpDataState describes the state of the TP buffer.
• TxTpDataCnt indicates the offset from the current position that determines the number of bytes to be retransmitted.

TpDataStateType has three values ([SWS_COMTYPE_00027]):

• TP_DATACONF: All previously copied data is confirmed and may be removed from the TP buffer. Data copied in this call is excluded from this.
• TP_DATARETRY: Already copied data is copied again to recover from an error. TxTpDataCnt specifies the start offset.
• TP_CONFPENDING: The previously copied data must remain in the TP buffer for error recovery.

If retry itself is NULL_PTR, the data may be released immediately after copying (SWS PduR p. 93).

Activity diagram: A CopyTxData call first evaluates the retry parameter and then decides on copying or BUFREQ_E_BUSY. Sources: SWS PduR p. 93, [SWS_COMTYPE_00027], [SWS_COMTYPE_00012]

The diagram for the J1939 transport protocol illustrates the interaction concretely:

• For each block, the first packet is requested with TP_DATACONF, the subsequent ones with TP_CONFPENDING.
• If a TP.DT is lost, transmission starts again at the first packet of the block. For this purpose, TP_DATARETRY is set, and TxTpDataCnt contains the offset to the start of the block (SWS J1939Tp p. 55).

Not every user evaluates the parameter: In LdCom, according to the specification, retry is handled neither by LdCom nor by its upper layer (SWS LdCom p. 34).

Sequence diagram: Block-by-block transmission with confirmation states and jump back to the start of the block in case of a lost data packet. Sources: SWS J1939Tp p. 55, [SWS_COMTYPE_00027], [SWS_COMTYPE_00037]

Channels, partial networks, and TP parameters

NetworkHandleType is a uint8 with the zero-based range 0..255. It stores the identifier of a communication channel ([SWS_COMTYPE_00038]). Examples from later releases:

• Bus Mirroring reports a LIN frame with the ComM channel assigned to the LIN channel (SWS Mirror p. 80).
• J1939Dcm passes the channel on which a request was received (SWS J1939Dcm p. 67).

PNCHandleType stores the identifier of a Partial Network Cluster and is derived from uint8 in R20-11 ([SWS_COMTYPE_00036]). In contrast, the documentation citation from R23-11 specifies uint16 (SWS ComStackTypes p. 17). For R20-11, the requirement applies. The context of use for PNC identifiers is shown, for example, by the synchronized PNC shutdown in ComM (SWS ComM p. 171).

TPParameterType specifies the transport protocol parameter whose value is to be changed ([SWS_COMTYPE_00031]):

• TP_STMIN: Separation Time,
• TP_BS: Block Size,
• TP_BC: Bandwidth control of the FlexRay transport protocol.

Block Size and STmin appear, for instance, in the flow control frame of the FlexRay AR transport protocol (SWS FrArTp p. 47).

Behavior in the event of an error

The outcome of a buffer request is described by BufReq_ReturnType ([SWS_COMTYPE_00012]):

• BUFREQ_OK (0): successful.
• BUFREQ_E_NOT_OK (1): The buffer is not accessible.
• BUFREQ_E_BUSY (2): Temporarily, no buffer is available; the requester should retry for a certain period of time.
• BUFREQ_E_OVFL (3): No buffer of the required length can be provided.

The interfaces assign these values as follows:

• CopyTxData: If the transmit data is insufficient, nothing is copied and BUFREQ_E_BUSY is returned; the lower layer may retry the call (SWS PduR p. 93). In the paged buffer procedure of DCM, BUFREQ_E_BUSY occurs alternately with preparing the next page (SWS DCM p. 481).
• StartOfReception: BUFREQ_E_NOT_OK rejects the connection and aborts reception; bufferSizePtr remains unchanged. BUFREQ_E_OVFL aborts because no buffer of the required length is available. In the case of BUFREQ_OK without a buffer of the requested size, a buffer size of 0 is reported (SWS DCM p. 273).
• CopyRxData: BUFREQ_E_NOT_OK indicates that nothing was copied due to an error (SWS PduR p. 91).
• Transmission error in TP: Recovery is performed via TP_DATARETRY with the offset TxTpDataCnt ([SWS_COMTYPE_00027]).
• TriggerTransmit: E_NOT_OK means that nothing was copied. PduInfoPtr must then not be used because it may be NULL or invalid (SWS CanIf p. 107).

Further checks are defined by the using modules themselves. Examples:

• DoIP_SoAdTpCopyRxData checks, with development error detection enabled, whether DoIP_Init was called previously (SWS DoIP p. 77).
• In state FRIF_STATE_OFFLINE, FrIf_Transmit returns the value E_NOT_OK (SWS FrIf p. 68).
• Many of these functions are reentrant only for different PDU IDs, not for the same one (SWS DoIP p. 75).

Further detailed evidence

The following overview classifies the most important references ([SWS_COMTYPE_00005] to [SWS_COMTYPE_00038]):

Reference	Classification
[SWS_COMTYPE_00005], [SWS_COMTYPE_00008]	Configuration-dependent width of PduIdType and PduLengthType, generated from EcuC
[SWS_COMTYPE_00011]	Structure of PduInfoType including metadata
[SWS_COMTYPE_00012]	Result codes of all TP buffer requests
[SWS_COMTYPE_00027], [SWS_COMTYPE_00037]	Confirmation and retry logic during TP transmission
[SWS_COMTYPE_00031], [SWS_COMTYPE_00036], [SWS_COMTYPE_00038]	TP parameter selection, PNC, and channel identifiers
ECU Configuration S. 156	Handle ID concept: Values freely selectable per module, unique per API
SWS PduR S. 93, SWS PduR S. 92	Reference semantics of the TP copy interfaces
SWS J1939Tp S. 55	Diagram on retry handling (also designated for R20-11)