Ethernet C API

The Ethernet API consists of two main parts:

  1. The Ethernet controller

  2. The Ethernet frame

Ethernet Controller

An Ethernet controller is created with the following function:

SilKit_ReturnCode SilKit_EthernetController_Create(SilKit_EthernetController **outController, SilKit_Participant *participant, const char *name, const char *network)

Create an Ethernet controller at this SIL Kit simulation participant.

Note

The object returned must not be deallocated using free()!

Parameters

  • outController – A pointer to a pointer in which the Ethernet controller will be stored (out parameter).

  • participant – The simulation participant for which the Ethernet controller should be created.

  • name – The name of the new Ethernet controller (UTF-8).

  • network – The network of the Ethernet controller to operate in (UTF-8).

Returns

A return code identifying the success/failure of the call. !

It’s status can be controlled with the functions:

SilKit_ReturnCode SilKit_EthernetController_Activate(SilKit_EthernetController *controller)

Activates the Ethernet controller.

Upon activation of the controller, the controller attempts to establish a link. Messages can only be sent once the link has been successfully established,

Parameters

controller – The Ethernet controller to be activated.

Returns

A return code identifying the success/failure of the call.

SilKit_ReturnCode SilKit_EthernetController_Deactivate(SilKit_EthernetController *controller)

Deactivate the Ethernet controller.

Deactivate the controller and shut down the link. The controller will no longer receive messages, and it cannot send messages anymore.

Parameters

controller – The Ethernet controller to be deactivated.

Returns

A return code identifying the success/failure of the call.

The Ethernet controller can send Ethernet frames with:

SilKit_ReturnCode SilKit_EthernetController_SendFrame(SilKit_EthernetController *controller, SilKit_EthernetFrame *frame, void *userContext)

Send an Ethernet frame.

Requires previous activation of the controller and a successfully established link. Also, the entire EthernetFrame must be valid, e.g., destination and source MAC addresses must be valid, ether type and vlan tags must be correct.

These requirements are not enforced in simple simulation. In this case, the message is simply passed on to all connected controllers without performing any check. The user must ensure that a valid frame is provided.

If the frame size is smaller than the minimum of 60 bytes, the frame will be padded with zeros.

Parameters

  • controller – The Ethernet controller that should send the frame.

  • frame – The Ethernet frame to be sent.

  • userContext – The user provided context pointer, that is reobtained in the frame ack handler

Returns

A return code identifying the success/failure of the call.

The following set of functions can be used to add and remove event handlers on the controller:

SilKit_ReturnCode SilKit_EthernetController_AddFrameHandler(SilKit_EthernetController *controller, void *context, SilKit_EthernetFrameHandler_t handler, SilKit_Direction directionMask, SilKit_HandlerId *outHandlerId)

Register a callback for Ethernet message reception.

The handler is called when the controller receives a new Ethernet message.

Parameters

  • controller – The Ethernet controller for which the message callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on reception.

  • directionMask – A bit mask defining the transmit direction of the messages (rx/tx)

  • outHandlerId – The handler identifier that can be used to remove the callback.

Returns

A return code identifying the success/failure of the call.

SilKit_ReturnCode SilKit_EthernetController_AddFrameTransmitHandler(SilKit_EthernetController *controller, void *context, SilKit_EthernetFrameTransmitHandler_t handler, SilKit_EthernetTransmitStatus transmitStatusMask, SilKit_HandlerId *outHandlerId)

Register a callback for Ethernet transmit acknowledgments.

The handler is called when a previously sent message was successfully transmitted or when the transmission has failed. The original message is identified by the userContext.

NB: Full support in a detailed simulation. In a simple simulation, all messages are immediately positively acknowledged by a receiving controller.

Parameters

  • controller – The Ethernet controller for which the message acknowledge callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on reception.

  • transmitStatusMask – A bit mask defining the transmit status of the message

  • outHandlerId – The handler identifier that can be used to remove the callback.

Returns

A return code identifying the success/failure of the call.

SilKit_ReturnCode SilKit_EthernetController_AddStateChangeHandler(SilKit_EthernetController *controller, void *context, SilKit_EthernetStateChangeHandler_t handler, SilKit_HandlerId *outHandlerId)

Register a callback for changes of the controller state.

The handler is called when the state of the controller changes. E.g., a call to SilKit_EthernetController_Activate() causes the controller to change from state SilKit_EthernetState_Inactive to SilKit_EthernetState_LinkDown. Later, when the link has been established, the state changes again from SilKit_EthernetState_LinkDown to SilKit_EthernetState_LinkUp. Similarly, the status changes back to SilKit_EthernetState_Inactive upon a call to SilKit_EthernetController_Deactivate().

Parameters

  • controller – The Ethernet controller for which the message acknowledge callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on reception.

  • outHandlerId – The handler identifier that can be used to remove the callback.

Returns

A return code identifying the success/failure of the call.

SilKit_ReturnCode SilKit_EthernetController_AddBitrateChangeHandler(SilKit_EthernetController *controller, void *context, SilKit_EthernetBitrateChangeHandler_t handler, SilKit_HandlerId *outHandlerId)

Register a callback for changes of the link bit rate.

The handler is called when the bit rate of the connected link changes. This is typically the case when a link was successfully established, or the controller was deactivated.

Parameters

  • controller – The Ethernet controller for which the bitrate change callback should be registered.

  • context – The user provided context pointer, that is reobtained in the callback.

  • handler – The handler to be called on change.

  • outHandlerId – The handler identifier that can be used to remove the callback.

Returns

A return code identifying the success/failure of the call.

SilKit_ReturnCode SilKit_EthernetController_RemoveFrameHandler(SilKit_EthernetController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_EthernetFrameHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The Ethernet controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

SilKit_ReturnCode SilKit_EthernetController_RemoveFrameTransmitHandler(SilKit_EthernetController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_EthernetFrameTransmitHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The Ethernet controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

SilKit_ReturnCode SilKit_EthernetController_RemoveStateChangeHandler(SilKit_EthernetController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_EthernetStateChangeHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The Ethernet controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

SilKit_ReturnCode SilKit_EthernetController_RemoveBitrateChangeHandler(SilKit_EthernetController *controller, SilKit_HandlerId handlerId)

Remove a SilKit_EthernetBitrateChangeHandler_t by SilKit_HandlerId on this controller.

Parameters

  • controller – The Ethernet controller for which the callback should be removed.

  • handlerId – Identifier of the callback to be removed. Obtained upon adding to respective handler.

Ethernet Frame

The SilKit_EthernetFrame is a raw Ethernet frame consisting of the destination MAC, the source MAC, the EtherType and a payload.

Note

For an example of manual frame construction one can refer to the C Ethernet demo.

Data Structures

struct SilKit_EthernetStateChangeEvent

Public Members

SilKit_StructHeader structHeader

The interface id that specifies which version of this struct was obtained.

SilKit_NanosecondsTime timestamp

Timestamp of the state change event.

SilKit_EthernetState state

New state of the Ethernet controller.

struct SilKit_EthernetBitrateChangeEvent

Public Members

SilKit_StructHeader structHeader

The interface id that specifies which version of this struct was obtained.

SilKit_NanosecondsTime timestamp

Timestamp of the bitrate change event.

SilKit_EthernetBitrate bitrate

New bitrate in kBit/sec.

struct SilKit_EthernetFrameEvent

Public Members

SilKit_StructHeader structHeader

The interface id that specifies which version of this struct was obtained.

SilKit_NanosecondsTime timestamp

Send time.

SilKit_EthernetFrame *ethernetFrame

The raw Ethernet frame.

SilKit_Direction direction

Receive/Transmit direction.

void *userContext

Optional pointer provided by user when sending the frame.

struct SilKit_EthernetFrameTransmitEvent

Public Members

SilKit_StructHeader structHeader

The interface id that specifies which version of this struct was obtained.

void *userContext

Value that was provided by user in corresponding parameter on send of Ethernet frame.

SilKit_NanosecondsTime timestamp

Reception time.

SilKit_EthernetTransmitStatus status

Status of the EthernetTransmitRequest.

Enumerations and Typedefs

typedef uint32_t SilKit_EthernetTransmitStatus
typedef uint32_t SilKit_EthernetState
typedef uint32_t SilKit_EthernetBitrate

Bitrate in kBit/sec.

struct SilKit_EthernetFrame

A raw Ethernet frame.

Public Members

SilKit_StructHeader structHeader

The interface id that specifies which version of this struct was obtained.

SilKit_ByteVector raw
typedef struct SilKit_EthernetController SilKit_EthernetController
typedef void (*SilKit_EthernetFrameHandler_t)(void *context, SilKit_EthernetController *controller, SilKit_EthernetFrameEvent *frameEvent)

Callback type to indicate that a EthernetMessage has been received.

Param context

The context provided by the user upon registration.

Param controller

The Ethernet controller that received the message.

Param frameEvent

Contains the raw frame and the timestamp of the event.

typedef void (*SilKit_EthernetFrameTransmitHandler_t)(void *context, SilKit_EthernetController *controller, SilKit_EthernetFrameTransmitEvent *frameTransmitEvent)

Callback type to indicate that a EthernetFrame has been sent.

Param context

The by the user provided context on registration.

Param controller

The Ethernet controller that received the acknowledge.

Param frameTransmitEvent

Contains the transmit status and the timestamp of the event.

typedef void (*SilKit_EthernetStateChangeHandler_t)(void *context, SilKit_EthernetController *controller, SilKit_EthernetStateChangeEvent *stateChangeEvent)

Callback type to indicate that the Ethernet controller state has changed.

Param context

The by the user provided context on registration.

Param controller

The Ethernet controller whose state did change.

Param stateChangeEvent

Contains the new state and the timestamp of the event.

typedef void (*SilKit_EthernetBitrateChangeHandler_t)(void *context, SilKit_EthernetController *controller, SilKit_EthernetBitrateChangeEvent *bitrateChangeEvent)

Callback type to indicate that the link bit rate has changed.

Param context

Context pointer provided by the user on registration.

Param controller

The Ethernet controller that is affected.

Param bitrateChangeEvent

Contains the new bitrate and the timestamp of the event.