The OpenNSL packet transmit and receive APIs provide the ability to receive packets captured from the data plane and to send packets to the data plane from the Host CPU. Typical uses for these functions are to implement various networking control protocols or "slow path" session handling.
"Transmit" and "receive" are named from the point of view of the Host CPU, so a "tx" routine sends a packet from the Host CPU to egress some switch port, while "rx" routines handle packets extracted from the data plane. Selection of the frames that get captured to the Host CPU is handled by other modules such as the field processor.
The OpenNSL API presents packets in a standard format. The API defines a structure, opennsl_pkt_t, which includes both the actual packet data as well as additional metadata available to the switch device that is not part of the actual frame, such as the ingress port or destination. Packet data is pointed to by a member of the opennsl_pkt_t structure, and metadata is presented in other fields of that structure.
The Host CPU can transmit a single frame to one or more ports with a single call. The packet structure thus specifies the destination port(s) with a port bitmap.
The packet structure is divided into two parts:
- The actual packet data and a description of the frame format
- Additional information about the packet not part of the actual packet (such as the port on which the packet was received).
This second category is referred to as "metadata". The metadata oocupies many more members in the structure. Some of those members are specific to transmit or receive. The packet data proper is represented by a variable length array of (pointer, length) pairs called "blocks".
The opennsl_pkt_t contains a pointer to an array of these blocks, and a length of this array, "blk_count". Usually, one packet will require only one block, though this depends on the application's buffer management policy.
All other members of the opennsl_pkt_t structure are metadata. In the receive direction, metadata in the packet structure is parsed from the device-specific format supplied by the hardware. Some devices support a rich set of metadata, and this parsing can be a significant portion of the cost of handling a packet. So, applications which do not require the full metadata may opt to disable the driver parser and instead supply their own custom parser to extract only fields of interest. In the transmit direction, application code fills in any necessary fields in the opennsl_pkt_t structure. The underlying driver routines will use these fields to correctly format the entire frame as required by the specific switch device.
