Vehicle-2-X GeoNetworking (V2xGn)

Initializes the V2x Gn module.

Returns the version information of this module.

Is called by V2x_ Btp to send a message.

Indicates the reception of an Ethernet frame

This function is called by the V2x M when a Pseudonym Change occurs to prepare the change in every module using it.

Confirms the transmission of an Ethernet frame

Main function of the V2x Gn module for periodical execution of protocol operations.

This function is called by the V2x M when all modules are OK with the pseudonym change and the change is to be committed. Availab le via V2x Gn_ V2x M.h

This function is called by the V2x M when an encapsulation has been finished.

This function is called by the V2x M when a decapsulation has been finished.

This function is called by the V2x M when not all modules are OK with the pseudonym change and the change is to be rolled back.

Indication of a received PDU from a lower layer communication interface module. Tags: atp.Status=draft

The lower layer communication interface module confirms the transmission of a PDU, or the failure to transmit a PDU. Tags: atp.Status=draft

Structure containing parameters for the V2x Gn_ Transmit() API.

[SWS_V2xGn_00034] ⌈The V2xGn module shall provide the API V2xGn_Transmit () to enable transmit requests from the V2xBtp Module.⌋

The V2xGn module shall transmits packets using the EthIf_Transmit() A PI provided by the EthIf Module . This has to be done during the V2xGn_Transmit context .

[SWS_V2xGn_00038] ⌈The V2xGn module shall create a unique DecapReqId for each received packet. This DecapReqId is used to track the result of each decap- sulation request during which the signature of the received packet is verified.⌋

[SWS_V2xGn_00039] ⌈The V2xGn module shall indicate received packets via the V2xBtp_RxIndication() callback to the BTP module.⌋

Type of error Related error code Error value API service called with invalid parameter V2XGN_ E_ PARAM 0x01 API service called with invalid pointer V2XGN_ E_ PARAM_ POINTER 0x02 API service used without module initialization V2XGN_ E_ UNINIT 0x03 API service called with invalid configuration pointer V2XGN_ E_ INIT_ FAILED 0x04

Module Header File Imported Type Com Stack_ Types Com Stack_ Types.h Buf Req _ Return Type Eth Eth_ General Types.h Eth _ Buf Idx Type Eth_ General Types.h Eth _ Frame Type Std Std_ Types.h Std _ Return Type Std_ Types.h Std _ Version Info Type V2x_ General Types Rte_ V2x M_ Type.h V2x M _ Position And Time Type Rte_ V2x M_ Type.h V2x M _ Sec Report Type V2x_ General Types.h V2x _ Chan Type V2x_ General Types.h V2x _ Gn Address Type V2x_ General Types.h V2x _ Gn Area Shape Type V2x_ General Types.h V2x _ Gn Destination Are a Type V2x_ General Types.h V2x _ Gn Destination Type V2x_ General Types.h V2x _ Gn Long Position Vector Type V2x_ General Types.h V2x _ Gn Packet Transport Type V2x_ General Types.h V2x _ Gn Tx Result Type V2x_ General Types.h V2x _ Gn Upper Protocol Type V2x_ General Types.h V2x _ Pseudonym Type V2x_ General Types.h V2x _ Sec Profile Type V2x_ General Types.h V2x _ Sec Return Type V2x_ General Types.h V2x _ Traffic Class Id Type V2x Btp V2x Btp.h V2x Btp _ Rx Params Type WEth WEth_ General Types.h W Eth _ Buf W Rx Param Id Type WEth_ General Types.h W Eth _ Buf W Tx Param Id Type

Eth If _ Get Buf W Rx - Params Eth If.h Read out values related to the receive direction of the transceiver for a received packet. For example, this could be RSSI or Channel belonging to one single packet. Eth If _ Get Buf W Tx - Params Eth If.h Read out valu es related to the transmit direction of the transceiver for a transmitted packet. For example, this could be transaction ID belonging to one single packet. Eth If _ Provide Tx - Buffer Eth If.h Provides access to a transmit buffer of the specified Ethernet controller. Eth If _ Set Buf W Tx - Params Eth If.h Set values related to the transmit direction of the transceiver for a specific buffer (packet to be sent). For example, this can be the desired transmit power or the channel belonging to one single packet. Eth If _ Transmit Eth If.h Triggers transmission of a previously filled transmit buffer V2x Btp _ Copy Tx - Data V2x Btp.h This API is called by the V2x Gn module to request the V2x Btp module to copy the transmission data to a specific location. V2x Btp _ Rx - Indication V2x Btp.h Via this API, the V2x Btp module gets the data (BTP - PDU), the Geo Networking parameters and the Transaction ID of a received Geo Networking packet. V2x M _ Calc - Distance V2x M.h Calculates the distance between two geograp hical points on earth with the assumption that they are on elevation 0. V2x M _ Get - Position And Time V2x M.h Provides the instantaneous position information. V2x M _ Get Ref - Time Ptr V2x M.h Provides a pointer to the time reference of the V2X - Stack. V2 x M _ Trigger - Pseudonym - Change V2x M.h This function is called by the V2x Fac, V2x Gn or another entity to change the Pseudonym used by the V2X - Stack, e.g. due to a Geo Networking address conflict. V2x M _ V2x Gn _ - Get Global Tx - Params V2x M_ V2x Gn.h This function is called by V2x Gn to get the current channel busy percentage for the specified channel V2x M _ V2x Gn _ - Req Decap V2x M_ V2x Gn.h This function is called by the V2x Gn to decrypt and verify a message. An asynchronous V2x Gn_ V2x M_ Decap C onfirmation call will be used to notify V2x Gn of the result. V2x M _ V2x Gn _ - Req Encap V2x M_ V2x Gn.h This function is called by the V2x Gn to sign and/ or encrypt a message. An asynchronous V2x Gn_ V2x M_ Encap Confirmation call will be used to notify V2x Gn of the result. V2x M _ V2x Gn _ - Set Global Rx - Params V2x M_ V2x Gn.h This function is called by V2x Gn to set the current channel busy percentage for the specified channel

Det _ Report Error Det.h Service to report development errors. V2x Btp _ Tx - Confirmation V2x Btp.h By this API primitive, the V2x Btp module gets an indication from the V2x Gn module about the status of the transmission of the data (FAC - PDU) with the associated ID.

[SWS_V2xGn_00083] ⌈The V2xGn module shall provide transmission parameters to the Wireless Ethernet Driver for a V2X Packet to be transmitted via an API call to EthIf_SetBufWTxParams(). This has to be done during the V2xGn_Transmit() con- text.⌋

[SWS_V2xGn_00084] ⌈The V2xGn module shall get the reception status of a re- ceived packet during the V2xGn_RxIndication() from the EthIf module with a call to EthIf_GetBufWRxParams().⌋

[SWS_V2xGn_00090] ⌈If development error detection is enabled: the function shall check the parameter VersionInfoPtr for being valid. If the check fails, the function shall raise the development error V2XGN_E_PARAM_POINTER.⌋

[SWS_V2xGn_00091] Upstream requirements: SRS_V2X_00176 ⌈The function V2xGn_V2xM_PreparePseudonymChange() shall prepare the setting of the pseudonym specific part of the GeoNetworking Address being used for packet transmission.⌋

[SWS_V2xGn_00092] ⌈If development error detection is enabled: the function shall check that the service V2xGn_Init() was previously called. If the check fails, the function shall raise the development error V2XGN_E_UNINIT.⌋

[SWS_V2xGn_00093] ⌈If development error detection is enabled: the function shall check the parameter PseudonymPtr for being valid. If the check fails, the function shall raise the development error V2XGN_E_PARAM_POINTER.⌋ Note: This starts a module internal transaction for the pseudonym change. The actual pseudonym change becomes effective only after an API call to V2xGn_V2xM_Com- mitPseudonymChange().

[SWS_V2xGn_00095] ⌈The function V2xGn_Transmit() shall transmit a V2X Packet.⌋

[SWS_V2xGn_00096] ⌈If development error detection is enabled: the function shall check that the service V2xGn_Init() was previously called. If the check fails, the function shall raise the development error V2XGN_E_UNINIT.⌋

[SWS_V2xGn_00098] Status: OBSOLETE ⌈The function shall return V2X_GNTX_E_MAXSDUSIZEOVFL if the call to EthIf_ProvideTxBuffer returns BUFREQ_E_OVFL.⌋

[SWS_V2xGn_00099] ⌈The function shall return V2X_GNTX_E_MAXPACKETLIFE- TIME if the parameter TxParams.maxPacketLifetime is invalid.⌋

[SWS_V2xGn_00100] ⌈The function shall return V2X_GNTX_E_TCID if the parameter TxParams.trafficClassId is invalid.⌋

[SWS_V2xGn_00101] ⌈The function shall return V2X_GNTX_E_MAXGEOAREASIZE if the parameter TxParams.destinationType is V2X_GNDESTINATION_AREA and the parameter TxParams.destinationArea is invalid.⌋

[SWS_V2xGn_00103] ⌈The function V2xGn_RxIndication() shall get reception param- eters of the Wireless Ethernet Driver for a V2X Packet received via an API call to EthIf_GetBufWRxParams.⌋() This is done to get access to the wireless specific reception parameters of the packet that is not available through the V2xGn_RxIndication() API.

[SWS_V2xGn_00104] ⌈If development error detection is enabled: the function shall check that the service V2xGn_Init() was previously called. If the check fails, the function shall raise the development error V2XGN_E_UNINIT.⌋()

[SWS_V2xGn_00105] Status: OBSOLETE ⌈If development error detection is enabled: the function shall check the parameter DataPtr for being valid. If the check fails, the function shall raise the development error V2XGN_E_PARAM_POINTER.⌋

[SWS_V2xGn_00112] Upstream requirements: SRS_V2X_00176 ⌈The function V2xGn_V2xM_CommitPseudonymChange() shall update the pseudonym specific part of the module’s GeoNetworking Address.⌋

[SWS_V2xGn_00113] ⌈If development error detection is enabled: the function shall check that the service V2xGn_Init() was previously called. If the check fails, the function shall raise the development error V2XGN_E_UNINIT.⌋ Note: The function requires previous preparation of the pseudonym via an API call to V2xGn_V2xM_PreparePseudonymChange().

[SWS_V2xGn_00115] Upstream requirements: SRS_V2X_00176 ⌈The function V2xGn_V2xM_AbortPseudonymChange() shall set the state of the module to the state before the pseudonym change has been prepared.⌋

[SWS_V2xGn_00116] ⌈If development error detection is enabled: the function shall check that the service V2xGn_Init() was previously called. If the check fails, the function shall raise the development error V2XGN_E_UNINIT.⌋ Note: The function requires previous preparation of the pseudonym via an API call to V2xGn_V2xM_PreparePseudonymChange().

[SWS_V2xGn_00127] ⌈The V2xGn module shall call V2xM_SetGlobalRxParams() with CBR information extracted from the GeoNetworking header.⌋

[SWS_V2xGn_00128] ⌈The V2xGn module shall call V2xM_GetGlobalTxParams() that delivers own channel CBR information set in the GeoNetworking header to be transmitted.⌋ The transmission request towards the LSduR is performed with direct data provision. With direct data provision, the data for transmission is forwarded in one single call via the LSduR to the lower layer. The lower layer is responsible to transfer the data to a transmit buffer.

[SWS_V2xGn_00131] ⌈The V2xGn module shall use V2xM_CalcDistance() when cal- culations of geographical distances are necessary for the V2xGn protocol operations.⌋

If development error detection is enabled: The function shall check the parameter CfgPtr for containing a valid configuration. If the check fails, the function shall raise the development error V2XGN_E_INIT_FAILED.

[SWS_V2xGn_00135] ⌈The V2xGn module shall create a unique EncapReqId for each packet to be transmitted. This EncapReqId is used to track the result of each encapsu- lation request during which the packet to be transmitted is signed to authenticate the transmitting ITS station.⌋

[SWS_V2xGn_00136] Usage of LSduR_V2xGnTransmit() in context of V2xGn_- Transmit() Status: DRAFT Replaces: SWS_V2xGn_00082, SWS_V2xGn_00035 Upstream requirements: SRS_V2X_26011 ⌈The V2xGn module shall transmit packets using the LSduR_V2xGnTransmit() API provided by the LSduR Module. This has to be done during the V2xGn_Transmit() context.⌋

[SWS_V2xGn_00137] Transmission request with direct data provision Status: DRAFT Upstream requirements: SRS_V2X_26011 ⌈If a transmission request need to be performed, then the V2xGn module shall call LSduR_V2XGnTransmit() with the following arguments: • TxPduId equal to the PDU id that is referenced by the used V2xGnTxPdu • PduInfoPtr.SduDataPtr equal to the data pointer • PduInfoPtr.SduLength equal to the data length • PduInfoPtr.MetaDataPtr equal to the pointer of the created MetaDataItem configured at the V2xGnTxPdu that corresponds to the given TxPduId. ⌋

[SWS_V2xGn_00138] Meta data handling while containing headers Status: DRAFT Upstream requirements: SRS_V2X_26011 ⌈If the V2xGn module provides headers necessary for the transmission through PduInfoPtr.MetaDataPtr then MetaDataItem shall be set in the following order: • ETHERNET_MAC_64 equal to the destination MAC address • LISTELEM_PTR equal to the pointer of the created instance of type ListElem- StructType in the following order: – create an instance of type ListElemStructType and set NextLis- tElemPtr to NULL_PTR – set DataPtr to address of the created header and DataLength to the length of the created header • PRIORITY_8 equal to the priority value used for this packet ⌋

[SWS_V2xGn_00139] Meta data handling while not containing headers Status: DRAFT Upstream requirements: SRS_V2X_26011 ⌈If the V2xGn module provides headers necessary for the transmission through PduInfoPtr.SduDataPtr then MetaDataItem shall be set in the following order: • ETHERNET_MAC_64 equal to the Physical destination address (MAC address in network byte order) • LISTELEM_PTR equal to NULL_PTR • PRIORITY_8 equal to the priority value used for this packet ⌋

[SWS_V2xGn_00140] Reception parameters derived from PDU Status: DRAFT Upstream requirements: SRS_V2X_26011 ⌈If a packet is received, the V2xGn module shall derive the frame type (EthIfFram- eType) and the EthIfCtrl (EthIfController) configured in EthIf via the PDU that is referenced by the V2xGnRxPdu which is identified by the given RxPduId.⌋

[SWS_V2xGn_00141] Reception parameters derived from meta data items Status: DRAFT Upstream requirements: SRS_V2X_26011 ⌈If a packet is received, the V2xGn module shall consume meta data items PduIn- foPtr.MetaDataPtr configured at the V2xGnRxPdu that corresponds to the given RxPduId in the following order: • ETHERNET_MAC_64 indicating the Physical source address (MAC address in net- work byte order) • BROADCAST_8 indicating a broadcast frame ⌋

[SWS_V2xGn_00147] Error report for aborting the transmission request Status: DRAFT Upstream requirements: SRS_V2X_26011 ⌈The V2xGn shall report the runtime error by calling Det_ReportRuntimeError( V2XGN_E_TX_INTERNAL_PROCESSING_FAILED) if one of the following conditions applies: • A transmission processing is requested from LSduR_V2xGnTransmit() and then aborted. ⌋

[SWS_V2xGn_00148] Return value if LSduR_V2xGnTransmit() reports E_NOT_OK Status: DRAFT Replaces: SWS_V2xGn_00098 Upstream requirements: SRS_V2X_26011 ⌈The function shall return V2X_GNTX_E_UNSPECIFIED if the call to LSduR_- V2xGnTransmit() returns E_NOT_OK.⌋

[SWS_V2xGn_00149] Development error handling for invalid PduInfoPtr Status: DRAFT Replaces: SWS_V2xGn_00105 Upstream requirements: SRS_V2X_26011 ⌈If development error detection is enabled: the function shall check the parameter PduInfoPtr for being valid. If the check fails, the function shall raise the development error V2XGN_E_PARAM_POINTER.⌋

[SWS_V2xGn_00150] Development Error handling if V2xGn_TxConfirmation() is indicated while V2XGn module is in uninitialized state Status: DRAFT Upstream requirements: SRS_V2X_26011 ⌈If development error detection is enabled: the function shall check that the service V2xGn_Init was previously called. If the check fails, the function shall raise the development error V2XGN_E_UNINIT.⌋

[SWS_V2xGn_20169] Upstream requirements: SRS_V2X_00010 ⌈The V2xGn module shall check the distance from the sender position - in the security envelope, if available - and forward only messages with a distance from the sender of equal or less than 6 km.⌋

[SWS_V2xGn_20181] Upstream requirements: SRS_V2X_00010 ⌈If the V2xGn module detects a collision of the least significant 32 bit of the "Certifi- cate digest" / "hashedId8" with the "Certificate digest" / "hashedId8" of another ITS station, it shall initiate a change of its authorization ticket (pseudonym) only if the cer- tificate corresponding to the other "Certificate digest" / "hashedId8" is valid, and the current authorization ticket was selected according to rules defined in [SWS_V2xM_ 00201] (that is to say no such collision has already triggered the change to the current authorization ticket).⌋

[SWS_V2xGn_20260] Upstream requirements: SRS_V2X_00010 ⌈The V2xGn module shall buffer GBC packets when no neighbours are available (store-carry-forward) if the SCF bit of the TC (Traffic Class) field of GBC packets is set to 1.⌋

[SWS_V2xGn_20262] Upstream requirements: SRS_V2X_00010 ⌈The V2xGn module is not required to offload packets to another channel. Conse- quently, the channel offload bit of the TC (Traffic Class) field in the BTP frames to be sent should be set to 0. Value 1 will be ignored anyway.⌋

[SWS_V2xGn_20263] Upstream requirements: SRS_V2X_00010 ⌈The V2xGn module shall only use the DCC profiles specified in [SWS_WEth_20235]. Consequently, the DCC Profile ID bits of the TC (Traffic Class) field shall only use the DPID values defined in [SWS_WEth_20235].⌋

[SWS_V2xGn_20264] Upstream requirements: SRS_V2X_00010 ⌈The V2xGn shall set the itsGnIsMobile bit of the Flags field to 1.⌋

[SWS_V2xGn_20265] Upstream requirements: SRS_V2X_00010 ⌈The V2xGn shall set the Maximum Hop Limit (MHL) field to 10.⌋

[SWS_V2xGn_20266] Upstream requirements: SRS_V2X_00010, SRS_V2X_00279 ⌈The V2xGn module shall only support Area forwarding algorithms specified in [9] Annex E.3.⌋

[SWS_V2xGn_20267] Upstream requirements: SRS_V2X_00010 ⌈When forwarding packets, the V2xGn module shall use the DCC profile DP3 as de- fined in [19].⌋

[SWS_V2xGn_20268] Upstream requirements: SRS_V2X_00010 ⌈The V2xGn module shall only use duplicate packet detection as specified in [9] Annex A.2 and A.3.⌋

[SWS_V2xGn_20270] Upstream requirements: SRS_V2X_00010 ⌈All GeoNetworking frames sent by the V2xGn module shall use the EtherType value 0x8947 as listed by the IEEE Registration Authority at [20].⌋

[SWS_V2xGn_20401] Upstream requirements: SRS_V2X_00010 ⌈The GN Source Address shall be constructed as follows: • Set the field M (bit 0) to 0. • Set the field ST (bits 1 to 5) to the station type of the ITS-S. The station type in the GN source address shall be identical to the station type in CAMs/DENMs. • Set reserved bits 6 to 15 to 0. • Set the field MID (bits 16 to 63) to the value of the MAC address. ⌋

[SWS_V2xGn_91000] Definition of runtime errors in module V2xGn Status: DRAFT ⌈ Type of error Related error code Error value Internal transmission processing aborted V2XGN_E_TX_INTERNAL_PROCESSING_ FAILED 0x01 ⌋

[SWS_V2xGn_CONSTR_00142] Reception PDU constraint for keeping the local buffer Status: DRAFT ⌈Each V2xGnRxPdu shall refer to global PDU that has KeepLocalPduBuffer set to FALSE.⌋