CAPLfunctionsIPOverview

Valid for: CANoe DE • CANoe4SW DE

Ethernet

• Only available with Option Ethernet.
• With Option Ethernet several APIs are provided for receiving and transmitting Ethernet packets.
• These CAPL functions are supported by Windows and Linux. The functionality under Linux has not been fully tested yet.

---

ON THIS PAGE:

• Event Procedures
• General Functions
• Methods
• Objects
• Stress Generator

Event Procedures

• on ethernetErrorPacket: Is called if an erroneous Ethernet packet is received.
• on ethernetMacsecStatus: Is called when the Ethernet MACsec connection state of a physical port has changed.
• on ethernetPacket: Is called up after an Ethernet packet has been received.
• on ethernetPacketForwarded: Is called up after a the network interface has forwarded a received Ethernet packet.
• on ethernetPhyState: Is called when the state of an ethernet PHY has changed or any relevant activity has been triggered.
• on ethernetStatus: Is called if the status of an Ethernet link is changed.
• on serviceSignal: Is called if value of received Service Signal has changed.
• on serviceSignal_update: Is called if Service Signal is received.

General Functions

• GetServiceSignal: Reads the value of a Service Signal.
• GetServiceSignalData: Reads the data of a Service Signal.
• GetServiceSignalString: Reads the string value of a Service Signal.
• SetServiceSignal: Sets the value of a Service Signal.
• SetServiceSignalData: Sets the data of a Service Signal.
• SetServiceSignalString: Sets the string value of a Service Signal.
• ethClearMacAddressTable: Clears MAC address table of network interface.
• ethGetLinkStatus: Returns the link status of the channel.
• ethSetLinkStatus: Configures the channel of the Vector hardware to establish or destablish a link.
• ethGetPhyConnector: Gets the PHY connector.
• ethGetMacAddressAsNumber: Converts a MAC address from string to a number.
• ethGetMacAddressAsString: Converts a MAC address to a string.
• ethGetMacsecSecureEntity: Returns the MACsec Secure Entity associated with the given measurement port.
• ethGetPortAccessEntity: Returns the MACsec Port Access Entity associated with the given measurement port.
• ethGetPhyMedium: Gets the PHY medium.
• ethGetPhyMode: Gets the PHY mode.
• ethGetPhyState: Gets the PHY state.
• ethSetPhyState: Sets the PHY state.
• ethResetStatistics: Rest the statistics values of Eth<channel> object
• output: Outputs an Ethernet packet.
• ethGetEthernetPort: Gets the Ethernet port for the current simulation node.
• ethGetEthernetPortInfos: Retrieves port related information of all connected network-based Ethernet devices.
• ethInjectPacket: Transmits an Ethernet packet by a specific Ethernet port.
• lookupEthernetPort: Gets the Ethernet port for a port qualification string.
• ethDisableStatisticsOfAllNetworks: Disables or enables the processing of the RT statistic values for all ports on all Ethernet networks.
• ethDisableStatisticsOfNetwork: Disables or enables the processing of the RT statistic values for all ports of the Ethernet network on which the passed port exists.
• ethDisableStatisticsOfPort: Disables or enables the processing of the RT statistic values for one port.
• ethGetLinkSpeed: Returns the link speed of the specified port.
• ethGetRxBitRate: Returns the RX bitrate of the specified port.
• ethGetRxBytesTotalCount: Returns the number of received bytes of the specified port.
• ethGetRxErrorPacketsTotalCount: Returns the number of received error packets of the specified port.
• ethGetRxPacketRate: Returns the RX packet rate of the specified port.
• ethGetRxPacketsTotalCount: Returns the number of received packets of the specified port.
• ethGetSQI: Returns the SQI (Signal Quality Indicator) of the specified port.
• ethGetTxBitRate: Returns the TX bitrate of the specified port.
• ethGetTxBytesTotalCount: Returns the number of transmitted bytes of the specified port.
• ethGetTxErrorPacketsTotalCount: Returns the number of transmitted error packets of the specified port.
• ethGetTxPacketRate: Returns the TX packet rate of the specified port.
• ethGetTxPacketsTotalCount: Returns the number of transmitted packets of the specified port.
• ethResetStatisticsOfAllNetworks: Resets the RT statistic values of all ports of all Ethernet networks.
• ethResetStatisticsOfNetwork: Resets the RT statistic values of all ports of the Ethernet network on which the passed port exists.
• ethResetStatisticsOfPort: Resets the RT statistic values of the port.

Methods

Information on the protocol and field designators can be found on the protocol’s help page.

• ethernetPacket::Clear: Clears data and reset length.
• ethernetPacket::CompletePacket: Calculates the checksum and length field for all protocols contained in the packet.
• ethernetPacket::FaultInjectDisableLengthPadding: Sends Ethernet packet, which is smaller than minimal allowed length.
• ethernetPacket::FaultInjectFCS: Sends Ethernet packet with invalid frame checksum.
• ethernetPacket::GetData: Copies the data of an ethernetPacket to a byte array, char array, CAPL struct or system variable struct.
• ethernetPacket::GetBitLength: Returns the number of bits of the specified field as dword.
• ethernetPacket::GetInt: Returns the value of the specified field as int.
• ethernetPacket::GetInt64: Returns the value of the specified field as int64.
• ethernetPacket::IsAvailable: Checks whether the protocol and the protocol field are present in the Ethernet packet.
• ethernetPacket::GetDestinationIPAddress: Returns the destination IP address as IP_Address.
• ethernetPacket::GetDestinationIPEndpoint: Returns the destination IP address and UDP/TCP port as IP_Endoint.
• ethernetPacket::GetPDU: Retrieves the PDU with index n in this packet.
• ethernetPacket::GetProtocolErrorText: Copies an error text to the buffer for invalid Ethernet packets.
• ethernetPacket::GetSourceIPAddress: Returns the source IP address as IP_Address.
• ethernetPacket::GetSourceEndpoint: Returns the source IP address and UDP/TCP port as IP_Endoint.
• ethernetPacket::GetVlan: Returns the VLAN tag, if the Ethernet packet contains a VLAN tag.
• ethernetPacket::GetVlanId: Returns the VLAN ID, if the Ethernet packet contains a VLAN tag.
• ethernetPacket::GetVlanPriority: Returns the VLAN priority, if the Ethernet packet contains a VLAN tag.
• ethernetPacket::HasProtocolError: Checks protocol errors.
• ethernetPacket::HasVlan: Returns number of VLAN tags.
• ethernetPacket::PDUCount: Returns the number of all PDUs in this message.
• ethernetPacket::PDUOffset: Returns the byte offset of the start of the PDU.
• ethernetPacket::protocol::field::GetData: Gets data of a protocol field within an Ethernet packet.
• ethernetPacket::protocol::field::IsAvailable: Returns if a protocol field is available in the Ethernet packet.
• ethernetPacket::protocol::field::ParseAddress: Sets the protocol field, which has type IPv4 or IPv6 address.
• ethernetPacket::protocol::field::SetData: Sets payload data of a protocol within an Ethernet packet.
• ethernetPacket::protocol::GetData: Gets payload data of a protocol within an Ethernet packet.
• ethernetPacket::protocol::Init: Initializes the protocol within a ethernetPacket.
• ethernetPacket::protocol::IsAvailable: Returns 1, if the ethernetPacket contains the protocol.
• ethernetPacket::protocol::optional-structure::Clear: Removes a protocol option from the Ethernet packet.
• ethernetPacket::protocol::optional-structure::Init: Adds a protocol option for a specific protocol to the Ethernet packet.
• ethernetPacket::protocol::ResizeData: Resizes the payload of a protocol within a ethernetPacket.
• ethernetPacket::protocol::SetData: Sets payload data of a protocol within an Ethernet packet.
• ethernetPacket::RemoveVlan: Remove a VLAN tag from an ethernetPacket.
• ethernetPacket::SetData: Copies bytes from a char array, byte array, CAPL struct or system variable struct to the data of an ethernetPacket.
• ethernetPacket::SetDestinationIPAddress: Sets the destination IP address.
• ethernetPacket::SetDestinationIPEndpoint: Sets the destination IP address an the UDP/TCP port.
• ethernetPacket::SetSourceIPAddress: Sets the source IP address.
• ethernetPacket::SetSourceIPEndpoint: Sets the source IP address an the UDP/TCP port.
• ethernetPacket::SetTxEventGeneration: Enables/Disables send acknowledgment
• ethernetPacket::SetVlan: Sets the VLAN tag of an ethernetPacket.
• ethernetPacket::SetVlanId: Sets the VLAN ID of an ethernetPacket.
• ethernetPacket::SetVlanPriority: Sets the VLAN priority of an ethernetPacket.
• ethernetPacket::source::ParseAddress: Sets the source or destination MAC address.
• IP_Address::IsIPv4Address: Checks if the current address is an IPv4 address.
• IP_Address::IsIPv6Address: Checks if the current address is an IPv6 address
• IP_Address::IsBroadcast: Checks if the current address is a broadcast address.
• IP_Address::IsMulticast: Checks if the current address is a multicast address.
• IP_Address::GetAddressAsArray: Copies the current IP address to the byte.
• IP_Address::MatchesAddress: Compares two addresses.
• IP_Address::ParseAddressFromString: Converts the character string to an IPv4 or IPv6 address and sets this address to the IP address value.
• IP_Address::PrintAddressToString: Converts the IP address to a character string.
• IP_Address::SetAddressAsArray: Copies the byte array to the IP address value.
• IP_Endpoint::IsTCP: Checks if the current transport protocol of this endpoint is TCP.
• IP_Endpoint::IsUDP: Checks if the current transport protocol of this endpoint is UDP.
• IP_Endpoint::IsUnknown: Checks if the current transport protocol of this endpoint is unknown.
• IP_Endpoint::MatchesEndpoint: Compares two endpoints.
• IP_Endpoint::ParseEndpointFromString: Converts the character string to an endpoint.
• IP_Endpoint::PrintEndpointToString: Converts the endpoint to a character string.
• IP_Endpoint::SetToTCP: Sets the transport protocol to TCP.
• IP_Endpoint::SetToUDP: Sets the transport protocol to UDP.
• IP_Endpoint::SetTransportProtocolToUnknown: Invalidates the transport protocol.

MACsec Access

The methods in this category allow to access a measurement port’s MACsec secure entity, if MACsec is configured for the port.

Note: It is important to note that manipulating a secure entity with currently executing MACsec Key Agreement can interfere badly and lead to unexpected behavior. MKA should always be deactivated in on prestart when planning to configure the SecY using this API.

• EthernetMacsecConfiguration::GetCAK: Copies the current connectivity association key (CAK) of the given MACsec configuration into the byte array given as parameter.
• EthernetMacsecConfiguration::GetCipherSuites: Copies the currently configured cipher suite priority list of the given MACsec configuration into the qword array given as parameter.
• EthernetMacsecConfiguration::GetCKN: Copies the connectivity key name (CKN) of the given MACsec configuration into the byte array given as parameter.
• EthernetMacsecConfiguration::SetCAK: Sets the connectivity association key (CAK) of the MACsec configuration from the given byte array.
• EthernetMacsecConfiguration::SetCipherSuites: Sets the cipher suite priority list of the MACsec configuration from the given qword array.
• EthernetMacsecConfiguration::SetCKN: Sets the current connectivity key name (CKN) of the MACsec configuration from the given byte array..
• EthernetMacsecSecureEntity::CreateRxSA: Creates a secure association for receiving.
• EthernetMacsecSecureEntity::CreateRxSC: Creates a secure channel for receiving.
• EthernetMacsecSecureEntity::CreateTxSA: Creates a secure association for transmitting.
• EthernetMacsecSecureEntity::CreateTxSC: Creates a secure channel for transmitting.
• EthernetMacsecSecureEntity::DeleteRxSA: Deletes a secure association for receiving.
• EthernetMacsecSecureEntity::DeleteRxSC: Deletes a receive secure channel.
• EthernetMacsecSecureEntity::DeleteTxSA: Deletes a secure association for transmitting.
• EthernetMacsecSecureEntity::DeleteTxSC: Deletes a transmit secure channel.
• EthernetMacsecSecureEntity::GetCapability: Returns the MACsec capability of the secure entity.
• EthernetMacsecSecureEntity::GetConfidentialityOffset: Returns the currently agreed confidentiality offset.
• EthernetMacsecSecureEntity::GetCurrentCipherSuite: Returns the ID of the currently agreed MACsec cipher suite.
• EthernetMacsecSecureEntity::GetDefaultRxSC: Returns the default secure channel used for receiving.
• EthernetMacsecSecureEntity::GetIncludeSCI: Returns preset for the SC flag in the tag control information (TCI).
• EthernetMacsecSecureEntity::GetReplayProtection: Returns the replay protection settings.
• EthernetMacsecSecureEntity::GetRxSAK: Returns the current secure association key (SAK) of the receive SA specified by it’s SCI and AN.
• EthernetMacsecSecureEntity::GetRxSalt: Returns the current XPN salt value of the receive SA specified by it’s SCI and AN.
• EthernetMacsecSecureEntity::GetRxSCStats: Returns the secure channel’s receive statistic variables.
• EthernetMacsecSecureEntity::GetSecYStats: Returns the secure entity’s global transmit and receive statistic variables, according to IEEE802.1AE-2018.
• EthernetMacsecSecureEntity::GetTxSAEnabled: Gets the enable state of the specified transmit secure association.
• EthernetMacsecSecureEntity::GetTxSAK: Returns the current secure association key (SAK) of the transmit SA specified by it’s SCI and AN.
• EthernetMacsecSecureEntity::GetTxSalt: Returns the current XPN salt value of the transmit SA specified by it’s SCI and AN.
• EthernetMacsecSecureEntity::GetTxSCStats: Returns the secure channel’s transmit statistic variables.
• EthernetMacsecSecureEntity::GetUseES: Returns preset for the end station (ES) flag in the tag control information (TCI).
• EthernetMacsecSecureEntity::GetValidateFrames: Returns the ValidateFrames setting.
• EthernetMacsecSecureEntity::InitMacsec: Initializes the secure entity.
• EthernetMacsecSecureEntity::InstallKey: Installs a key under the specified key id, and with the specified key data.
• EthernetMacsecSecureEntity::RegisterOnBeforeSendMKPDU: Register a callback function which is called each time before the MKA key server sends a MKPDU (EAPOL-MKA frame).
• EthernetMacsecSecureEntity::RegisterOnBeforeSendMPDU: Register a callback function which is called each time before a readily encoded MACsec frame (MPDU) is going to be transmitted.
• EthernetMacsecSecureEntity::SetRxSAEnabled: Enables or disables use of an existing secure association for receiving.
• EthernetMacsecSecureEntity::SetTxSAEnabled: Enables or disables use of an existing secure association for transmission.
• EthernetMacsecSecureEntity::UpdateMkaICV: Recalculates the integrity check value (ICV) of a MKPDU.
• EthernetMacsecSecureEntity::UpdateSecY: Configures the basic parameters of the secure entity.

Objects

• Eth: Access to Ethernet link status and statistics.
• ethernetErrorPacket: Access information in on ethernetErrorPacket.
• EthernetMacsecSecureEntity: Defines a variable of type EthernetMacsecSecureEntity.
• EthernetMacsecConfiguration: Define a variable of type EthernetMacsecConfiguration.
• EthernetPortAccessEntity: Defines a variable of type EthernetPortAccessEntity.
• ethernetPacket: Creates an Ethernet packet object.
• IP_Address: Variable type for IPv4 and IPv6 address.
• IP_Endpoint: Variable type for IP endpoints.

Stress Generator

Functions for Ethernet Stress Generator are only available with Vector Ethernet network interfaces.

• ethStartPacketGenerator: Starts Ethernet Stress Generator.
• ethStopPacketGenerator: Stops Ethernet Stress Generator.