Managing the Hyper-V Extensible Switch Forwarding Context
Note This page assumes that you are familiar with the information and diagrams in Overview of the Hyper-V Extensible Switch and Hybrid Forwarding.
The NET_BUFFER_LIST structure for each packet that traverses the Hyper-V extensible switch data path contains out-of-band (OOB) data. This data specifies the source port from where the packet originated, as well as one or more destination ports for packet delivery. This OOB data is known as the extensible switch forwarding context.
Note The extensible switch forwarding context is different from the NET_BUFFER_LIST_CONTEXT structure. This allows extensions to allocate their own context structures without affecting the forwarding context.
The extensible switch forwarding context is allocated and freed in the following way:
When a packet arrives at the extensible switch from a network adapter, the extensible switch interface allocates the forwarding context and associates it with the packet's NET_BUFFER_LIST structure.
When the packet is delivered to its destination ports, the interface frees the forwarding context from the packet's NET_BUFFER_LIST structure.
If an extensible switch extension injects a new or cloned packet into the extensible switch data path, it must allocate the forwarding context before it calls NdisFSendNetBufferLists.
After the extension allocates a NET_BUFFER_LIST structure for a new or cloned packet, it must call the AllocateNetBufferListForwardingContext function to allocate the forwarding context for the packet. When the send packet request is completed, the extension must call FreeNetBufferListForwardingContext before it frees or reuses the NET_BUFFER_LIST structure.
Note When the extension calls AllocateNetBufferListForwardingContext, the source port for the packet is set to NDIS_SWITCH_DEFAULT_PORT_ID. This specifies that the packet originated from an extension instead of arriving at an extensible switch port. Under certain conditions, the extension may want to change the source port for the packet. For more information, see Modifying a Packet's Extensible Switch Source Port Data.
For more information, see Hyper-V Extensible Switch Send and Receive Operations.
All extensible switch extensions can call the following extensible switch handler functions to access the data within the packet's forwarding context:
AllocateNetBufferListForwardingContext
Allocates the extensible switch forwarding context and prepares a NET_BUFFER_LIST structure for send or receive operations within the extensible switch.
CopyNetBufferListInfo
Copies the forwarding context from a source packet's NET_BUFFER_LIST structure to a destination packet's NET_BUFFER_LIST structure. This data includes the extensible switch source port and network adapter information. The extensible switch destination port information can also be copied to the destination packet.
FreeNetBufferListForwardingContext
Frees the resources in the extensible switch forwarding context of a NET_BUFFER_LIST structure. This data was used for send or receive operations in a Hyper-V extensible switch, and was previously allocated by calling the AllocateNetBufferListForwardingContext function.
GetNetBufferListDestinations
Returns the destination ports from the forwarding context of a packet's NET_BUFFER_LIST structure.
A forwarding extension is responsible for adding destination ports for a packet, unless the packet is an NVGRE packet. (For more information, see Hybrid Forwarding.) The extension calls the following extensible switch handler functions to add or update the destination ports within the packet's forwarding context:
AddNetBufferListDestination
Adds a single destination to the extensible switch forwarding context area for a packet that is specified by a NET_BUFFER_LIST structure.
Note This call commits the change to the forwarding context area. In this case, the forwarding extension does not need to call UpdateNetBufferListDestinations.
GrowNetBufferListDestinations
Increases the size of the destination port array in the forwarding context area of a packet's NET_BUFFER_LIST structure.
UpdateNetBufferListDestinations
Commits modifications that the extension made to one or more extensible switch destination ports of a packet. This function updates the forwarding context of a packet's NET_BUFFER_LIST structure with these changes.
Note After the forwarding extension commits the changes for destination ports to the forwarding context, destination ports cannot be removed and only the IsExcluded member of a destination port's NDIS_SWITCH_PORT_DESTINATION structure can be changed. For more information, see Excluding Packet Delivery to Extensible Switch Destination Ports.