2.6 Injecting and Modifying Network Traffic

2.6.1 From a Network Dump

Simics comes with a eth-injector class that takes a pcap format file and injects the packets described in the file into the simulated network.

Each packet in a pcap file has a time stamp that usually is the absolute time when the packet was recorded. The eth-injector starts injecting the first packet of the pcap file directly after the start command has been run. The consecutive packets are injected after an amount of virtual time that is equal to the difference in time stamp between that packet and the first packet of the pcap file. If the packet cannot be injected because of bandwidth limitations, it is ignored. Incoming packets are ignored as well.

It is common that the CRC of Ethernet frames are not recorded in pcap files. In Simics, the whole Ethernet frame has to be present for a correct simulation result. The -no-crc option of the <eth-injector>.start command can be used to tell the injector that the pcap file contains no CRC. The injector then adds a CRC to each frame that Simics will handle as if it was correct. By not using the -no-crc option the frames in the pcap file are injected as they were recorded, without any modification.

The eth-injector can be connected to an Ethernet link like any other Ethernet device. It can also be connected directly to another Ethernet device without the need to have a link between the device and the eth-injector.

The following example creates a new eth-injector, connects it to an already existing ethernet_switch of name ethernet_switch0 and starts packet playback from a file named test.pcap:

simics> load-module eth-injector-comp
simics> new-eth-injector-comp name = inj0
Created instantiated 'eth_injector_comp' component 'inj0'
simics> connect ethernet_switch0.link inj0.link
simics> inj0.injector.start file = test.pcap

2.6.2 From an Ethernet Probe

The section Observing Network Traffic explained how to use an Ethernet probe to listen to the incoming and outgoing traffic of a device connected on an Ethernet link. A probe can also be used to modify this traffic by dropping and changing existing packets, or injecting new ones.

typedef enum {
        Eth_Probe_Port_A = 0,
        Eth_Probe_Port_B = 1
} eth_probe_side_t;

typedef void (*ethernet_probe_snoop_t)(lang_void *user_data,
                                       conf_object_t *probe,
                                       eth_probe_side_t to_side,
                                       const frags_t *frame,
                                       eth_frame_crc_status_t crc_status);
// END ethernet_probe_snoop_t

SIM_INTERFACE(ethernet_probe) {
        void (*attach_snooper)(conf_object_t *NOTNULL probe,
                               ethernet_probe_snoop_t snoop_fun,
                               lang_void *user_data);
        void (*attach_probe)(conf_object_t *NOTNULL probe,
                             ethernet_probe_snoop_t snoop_fun,
                             lang_void *user_data);
        void (*detach)(conf_object_t *NOTNULL probe);
        void (*send_frame)(conf_object_t *NOTNULL probe,
                           eth_probe_side_t to_side,
                           const frags_t *frame,
                           eth_frame_crc_status_t crc_status);
};

#define ETHERNET_PROBE_INTERFACE "ethernet_probe"

A complete description of this interface is provided in the API Reference Manual, chapter Model-to-Model Interfaces, section ethernet_probe. What we are interested in now is to register a probe callback that will be allowed to modify the traffic:

simics> python-mode

# a callback that drops all outgoing packets
def callback(user_data, probe, to_side, packet, crc_status):
    if to_side == Eth_Probe_Port_A:
        print('dropping incoming packet')
    else:
        print('forwarding outgoing packet')
        probe.iface.ethernet_probe.send_frame(to_side, packet, crc_status)

conf.probe0.iface.ethernet_probe.attach_probe(callback, None)

.......
simics>>> (Ctrl-D)
simics> continue
forwarding outgoing packet
forwarding outgoing packet
[...]

When a callback is registered as a probe, it takes responsibility for forwarding packets it receives. It is also allowed to drop them, modify them, modify their CRC status or inject new packets. For example, it could duplicate outgoing packets, inject errors, etc. Note that if your callback modifies the simulation in this manner, you may need to create an object representing the changes' state engine to make sure the simulation can be checkpointed and stays deterministic.