The VNIC protocol defined in this appendix defines the protocol to be used with VNIC virtual IOA, as defined in . VNIC provides a mechanism which minimizes the number of times data is copied within the memory of the physical system. The virtual I/O model described herein allows for either zero copy using the redirected DMA or single copy when the data is first moved to the memory space of firmware before being DMAed to the client partition. This protocol is designed to fulfill the following requirements: Fast, efficient transfer and reception of Ethernet frames Exploitation of adapter multiple transmit and receive queue support. Partition mobility capable Promiscuous mode support Stateless TCP and IP checksum offload TCP large send offload Multiple interrupt source support Notification of physical Ethernet link state Physical Ethernet link state control if configured Statistics, trace, and dump support Extensible protocol for future functional additions

The intent of this protocol is to support the implementation, within the client logical partition, of a VNIC adapter device driver (VNIC client) which is functionally similar to a physical Ethernet adapter device driver. The VNIC can send and receive Ethernet packets, add receive buffers to the virtualized hardware, handle physical and logical link status, acquire hardware statistics, and utilize advanced hardware features like checksum offload. The VNIC interface also provides tracing, logging, and dumping facilities. It is the firm intent of this protocol that no changes be required in any layer 3 or higher communication protocol (e.g. TCP, IP, etc.). A partition may have multiple VNIC Adapters.

Unlike the Interpartition Logical LAN option (See ), the VNIC protocol allows for the physical Ethernet adapter associated with the VNIC device to securely target memory pages associated with a VNIC adapter for virtual I/O operations. LoPAR defines two modes of LRDMA (See ). The use of Redirected RDMA is completely invisible to the VNIC adapter, and has no impact on the VNIC protocol defined here. It is left entirely to the discretion of the server firmware whether it first moves data from a physical adapter into its own memory before moving (DMAing) the data to the VNIC adapter, or whether the physical adapter sets up the I/O request in such a way that the physical device DMAs directly to the memory of the client adapter. The virtualizing firmware uses the RDMA mode that best suits its needs for a given virtual I/O operation.

The CRQ and Sub-CRQ facilities as defined in are used to send and receive VNIC commands to system firmware. The different VNIC command types are defined in . Throughout this document, boolean values assume 0 to be false, 1 to be true. Unless otherwise specified, all lengths are expected to be given in terms of bytes. Any setting or capability changed or enabled after a successful H_REGISTER_CRQ will be cleared when H_FREE_CRQ is performed. The format of a VNIC command is shown in . The Command Type field of the VNIC command is defined in . The Return Code for a a VNIC command is always at offset 12 in the response, as shown in . All VNIC commands have VNIC command values from 0x0 to 0x7F. Each response to a VNIC command has a VNIC command value that is equal to the command with the 0x80 bit in the command turned on. In the event firmware receives a command it doesn’t understand, a response will be returned with an UnknownCommand return code set at offset 12, and the VNIC command type set to the passed in command type with the 0x80 bit turned on. Byte Offset 0 1 2 3 4 5 6 7 0x00 0x80 Command Type Command dependent 0x08 Command dependent Return Code or Command Dependent   Field Name Byte Offset Length Definition Architected Return Value 0 1 This field contains a value from that contains the high level return code for the operation. Detailed Error Data 1 3 This field contains an unarchitected detailed error code that can be used by firmware to further classify the error returned in the architected return value.   Command Type Command value Sent by Description Location VERSION_EXCHANGE 0x01 VNIC Client Used to inform firmware of level of protocol VNIC supports VERSION_EXCHANGE_RSP 0x81 Firmware Used to inform VNIC of level of protocol firmware supports QUERY_CAPABILITY 0x02 VNIC Client Query firmware for a specific VNIC capability QUERY_CAPABILITY_RSP 0x82 Firmware Response for a QUERY_CAPABILITY REQUEST_CAPABILITY 0x03 VNIC Client Request firmware to start using a specific capability value REQUEST_CAPABILITY_RSP 0x83 Firmware Response from firmware to a REQUEST_CAPABILITY command LOGIN 0x04 VNIC Client Used to exchange Sub-CRQ information with system firmware in preparation for functional use of the virtualized adapter LOGIN_RSP 0x84 Firmware Response from firmware with firmware’s Sub-CRQ information in preparation for functional use. QUERY_PHYS_PARMS 0x05 VNIC Client Used by VNIC client to enquire about physical port parameters such as line speed, duplex setting, etc. QUERY_PHYS_PARMS_RSP 0x85 Firmware A response to the QUERY_PHYS_PARMS request containing the requested information QUERY_PHYS_CAPABILITIES 0x06 VNIC Client Used by VNIC client to enquire about physical port capabilities such as line speed. QUERY_PHYS_CAPABILITIES_RSP 0x86 Firmware A response to the QUERY_PHYS_CAPABILITIES request containing the requested information. SET_PHYS_PARMS 0x07 VNIC Client Used by the VNIC to set physical port parameters such as line speed if allowed. SET_PHYS_PARMS_RSP 0x87 Firmware Response indicating status of SET_PHYS_PARMS request ERROR_INDICATION 0x08 Firmware Used to indicate to either side of an error condition. REQUEST_ERROR_INFO 0x09 VNIC Client Used to request detailed error data about a previous asynchronous error condition REQUEST_ERROR_RSP 0x89 Firmware Used to return detailed error data in response to a request REQUEST_DUMP_SIZE 0x0A VNIC Client Used to request an estimate of how much size a VNIC collected debug dump will require. REQUEST_DUMP_SIZE_RSP 0x8A Firmware Used to inform VNIC of the dump size estimate. REQUEST_DUMP 0x0B VNIC Client Used to request firmware to perform an adapter & firmware dump to assist in problem determination REQUEST_DUMP_RSP 0x8B Firmware Used to inform VNIC Client when the requested dump has been completed LOGICAL_LINK_STATE 0x0C VNIC Client Used by VNIC Client to tell firmware to start and stop packet reception LOGICAL_LINK_STATE_RSP 0x8C Firmware Used to inform VNIC Client of the status of the LINK_STATE request REQUEST_STATISTICS 0x0D VNIC Client Used to retrieve standard network adapter statistics (bytes/packet sent/rcvd, etc.) REQUEST_STATISTICS_RSP 0x8D Firmware Used to inform VNIC Client when statistics were successfully collected REQUEST_RAS_COMP_NUM 0x0E VNIC Client Used by VNIC Client to retrieve the number of independent firmware components that can have their RAS capabilities controlled in firmware associated with the VNIC REQUEST_RAS_COMP_NUM_RSP 0x8E Firmware Response to the REQUEST_RAS_COMP_NUM command. REQUEST_RAS_COMPS 0x0F VNIC Client Used by VNIC Client to retrieve the list of component ids that can have their RAS capabilities controlled in firmware for this VNIC. REQUEST_RAS_COMPS_RSP 0x8F Firmware Response to the REQUEST_RAS_COMPS_RSP. CONTROL_RAS 0x10 VNIC Client Request firmware to modify RAS characteristics to allow for easier problem determination. CONTROL_RAS_RSP 0x90 Firmware Response to the CONTROL_RAS command. COLLECT_FW_TRACE 0x11 VNIC Client This allows the VNIC Client to collect a trace for a firmware component. COLLECT_FW_TRACE_RSP 0x91 Firmware Inform VNIC Client the trace collection is complete LINK_STATE_INDICATION 0x12 Firmware Inform VNIC Client of link state changes. CHANGE_MAC_ADDR 0x13 VNIC Client Request system firmware to change the current VNIC MAC address CHANGE_MAC_ADDR_RSP 0x93 Firmware Inform VNIC Client of MAC address change request status MULTICAST_CTRL 0x14 VNIC Client Request system firmware to change current multicast MAC address settings MULTICAST_CTRL_RSP 0x94 Firmware Inform VNIC Client of multicast response GET_VPD_SIZE 0x15 VNIC Client Query firmware for the size of VPD GET_VPD_SIZE_RSP 0x95 Firmware Return the size of VPD to VNIC client GET_VPD 0x16 VNIC Client Request system firmware to return VPD associated with adapter. GET_VPD_RSP 0x96 Firmware Response to GET_VPD. TUNE 0x17 VNIC Client Pass debugging information to system firmware TUNE_RSP 0x97 Firmware Response to TUNE command. QUERY_IP_OFFLOAD 0x18 VNIC Client Request details about TCP, UDP, and IP offload capabilities QUERY_IP_OFFLOAD_RSP 0x98 Firmware Response to QUERY_IP_OFFLOAD command. CONTROL_IP_OFFLOAD 0x19 VNIC Client Enable and disable TCP, UDP, and IP offload capabilities CONTROL_IP_OFFLOAD_RSP 0x99 Firmware Response to CONTROL_IP_OFFLOAD command. ACL_CHANGE_INDICATION 0x1A Firmware Inform VNIC client of dynamic changes to access controls ACL_QUERY 0x1B VNIC Client Request information about access control limitations in place for this VNIC. ACL_QUERY_RSP 0x9B Firmware Response to ACL_QUERY command. REQUEST_DEBUG_STATS 0x1C VNIC Client Request unarchitected statistics block used for debugging firmware problems. REQUEST_DEBUG_STATS_RSP 0x9C Firmware Response to REQUEST_DEBUG_STATS command.   Return Code Value Definition Success 0 The requested operation completed successfully. PartialSuccess 1 The requested operation completed partially successful. The parameters were valid, but not all resources could be obtained to completely satisfy the command. Check the specific function definition for details. Permission 2 The request called for permissions not available. NoMemory 3 The request failed due to insufficient memory. Parameter 4 One or more parameters were in error in the request. UnknownCommand 5 The specific VNIC command is unknown. Aborted 6 The command was aborted by some other action. InvalidState 7 The requested command is invalid at this time. InvalidIOBA 8 An I/O bus address passed as a parameter was invalid. InvalidLength 9 A length passed as a parameter was invalid. UnsupportedOption 10 A reserved value or option was used on an existing command that system firmware does not support. Reserved 11-255 These return codes are reserved.

This section gives an overview of the typical VNIC startup sequence. The operating system discovers a VNIC device in the device tree. The operating system instantiates the VNIC client device driver, allocates a buffer for the VNIC CRQ, which is then TCE-mapped using the VNIC’s TCE table. Since the VNIC protocol is a command/response protocol, the VNIC client should allocate a CRQ buffer big enough to handle a response for every command it wishes to have outstanding concurrently with firmware with an allowance for unsolicited asynchronous error and link state change CRQ events. VNIC client calls H_REG_CRQ specifying the unit address and IOBA of the CRQ page(s), and waits for either H_Success or an INITIALIZATION message as defined in . VNIC client sends either an INITIALIZATION_COMPLETE or an INITIALIZATION message to firmware using H_SEND_CRQ, as defined in . Once the INITIALIZATION and INITIALIZATION_COMPLETE messages have been exchanged, the VNIC client sends a VERSION_EXCHANGE using H_SEND_CRQ, specifying the latest version of the VNIC protocol supported by the VNIC client. Firmware responds with a VERSION_EXCHANGE_RSP specifying the version it supports. Both VNIC client and firmware must support the lower of the two versions. Until and unless the VNIC client receives a VERSION_EXCHANGE_RSP, no further VNIC commands may be sent. VNIC client may now use QUERY_CAPABILITY commands to interrogate what the firmware supports currently. Multiple QUERY_CAPABILITY commands may be send in parallel, up to one for each capability being interrogated. Firmware will respond with QUERY_CAPABILITY_RSP messages for each query sent. Once the queries are returned, the VNIC client uses the REQUEST_CAPABILITY commands to inform the firmware of the capabilities it plans on using. Until the capability has been requested and a successful response has been received, it will not function, and commands which use the capabilities will fail. Only the Capability-related commands are usable prior to sending a Login command. The VNIC client determines how many Sub-CRQs to set up based on the capabilities negotiated with the server and partition configuration, and attempts to set those up by allocating memory, mapping them with TCEs, and calling H_REG_SUB_CRQ iteratively for each Sub-CRQ. Once the VNIC client has successfully gotten each Sub-CRQ it needs registered (with some possibly failing due to unavailable resources), it parcels them out to specific queues (Transmit Completion and Receive Completion), and does a REQUEST_CAPABILITY for the appropriate number of each from firmware. Once the VNIC client has all SubCrqs registered, he sends a LOGIN CRQ to the server, specifying each Sub-CRQ handle and purpose as defined in the LOGIN command structure, and waits for a LOGIN_RSP which includes the server’s Sub-CRQ handles and purposes. Once the LOGIN_RSP has been returned successfully, the VNIC client is free to utilize the Transmit Submission Sub-CRQs and Receive Buffer Add Sub-CRQs, as well as any other VNIC command. Once the VNIC client is ready to receive frames (for the Logical Link State to transition to Link Up), it sends a LOGICAL_LINK_STATE command to firmware. If the VNIC client is also in control of the physical port, sending the LOGICAL_LINK_STATE command has the side effect of initiating physical port link negotiation, as appropriate. The firmware will send a LOGICAL_LINK_STATE_RSP once the link state is up.

In the event that system firmware encounters an error, needs to update the firmware on the adapter, or needs to remove the virtualized adapter from the partition, the following flows will happen. Firmware will close its CRQ and Sub-CRQs. VNIC client receives a TRANSPORT_EVENT specifying Partner Partition Closed or receives an H_Closed return code on a H_SEND_CRQ or H_SEND_SUB_CRQ hypervisor call. VNIC client closes all Sub-CRQs and CRQ using H_FREE_SUB_CRQ and H_FREE_CRQ. (Optionally, only H_FREE_CRQ could be used to close the CRQ and all Sub-CRQs.) VNIC client cleans up all outstanding unacknowledged transmit frames. VNIC client cleans up all receive buffers that had been given to the firmware. VNIC client opens the CRQ, and attempts the boot sequence.

In the event that an active partition is migrated to a new platform, the following sequence takes place. VNIC client receives a TRANSPORT_EVENT event specifying Partner Partition Suspended (Defined in ). VNIC client pauses submission of new transmit frames and receive add buffers. VNIC client closes all Sub-CRQs. VNIC client completes all outstanding unacknowledged transmit frames. This may involve queueing them for retransmission once the VNIC is recovered, or completing them as dropped, letting higher layers of the TCP/IP stack perform retransmission. VNIC client calls H_ENABLE_CRQ until H_Success is returned. VNIC client attempts the boot sequence.

Typical dump collection flow: VNIC client decides on the need for a VNIC dump. VNIC client sends a REQUEST_DUMP_SIZE command (see ) to system firmware. Firmware responds with a REQUEST_DUMP_SIZE_RSP with an estimate on the amount of storage required to store the dump into VNIC client memory. VNIC client allocates a buffer big enough to hold the dump, and maps it with TCEs. VNIC client sends a REQUEST_DUMP command (see ) to system firmware containing the IOBAs referring to the dump buffer. System firmware uses the supplied dump buffer to collect the memory that’s previously been registered by firmware as important for dumps. System firmware optionally collects physical adapter debug data into the dump buffer as well. System firmware sends a REQUEST_DUMP_RSP (see ) to the VNIC client, indicating the dump is complete.

Transmission of Ethernet frames using the VNIC protocol is accomplished using two or more Subordinate CRQs. The VNIC client allocates one or more Transmit Completion Sub-CRQs and system firmware allocates one or more Transmit Submission CRQs. The handles for each are exchanged during the LOGIN processing. The following numbered sequence details the simplified transmission of an Ethernet frame. As with any CRQ or Subordinate CRQ based protocol, the listed virtual interrupts may not occur for every CRQ or Sub-CRQ that is sent using H_SEND_CRQ, H_SEND_SUB_CRQ, or H_SEND_SUB_CRQ_INDIRECT. It is the firm intent of this protocol to allow the VNIC client and system firmware to batch frame transmission submission and transmit complete indications to minimize the number of virtual interrupts and to make the transmission of Ethernet frames as efficient as possible. Multiple Sub-CRQs may be presented to either the VNIC or system firmware with a single virtual interrupt. Operating system chooses a VNIC adapter to use for frame transmission. VNIC client device driver either copies the frame into a private buffer that’s already been mapped via a TCE or maps the frame with a TCE. VNIC client device driver constructs a Transmit Descriptor (or multiples) describing the TCE mapped buffer (see ). VNIC client device driver uses H_SEND_SUB_CRQ to pass the Transmit Descriptor to system firmware’s Transmit Submission Sub-CRQ. System firmware receives the Sub-CRQ event, and transforms it into the appropriate format for the specific Ethernet adapter being virtualized, and uses its embedded device driver to send the frame out the wire. The system firmware uses RDMA to DMA the frame directly from the VNIC client. The physical Ethernet device driver interrupts system firmware (or system firmware polls for completion at appropriate times) indicating the frame has been successfully transmitted. System firmware constructs a Transmit Completion Sub-CRQ event (see ), and places that Sub-CRQ onto the Transmit Completion Sub-CRQ. VNIC client removes the TCE mapping for the frame, and makes it available to its network stack.

Reception of Ethernet frames is accomplished using two or more Sub-CRQs, similar to frame transmission. System firmware creates one or more Receive Buffer Add Sub-CRQs and the VNIC client creates one or more Receive Completion Sub-CRQs. The following numbered sequence details the simplified reception of an Ethernet frame. As with any CRQ or Subordinate CRQ based protocol, the listed virtual interrupts may not occur for every CRQ or Sub-CRQ that is sent using H_SEND_CRQ, H_SEND_SUB_CRQ, or H_SEND_SUB_CRQ_INDIRECT. It is the firm intent of this protocol to allow the VNIC client and system firmware to batch frame reception and buffer adding to minimize the number of virtual interrupts and to make the reception of Ethernet frames as efficient as possible. Multiple Sub-CRQs may be presented to either the VNIC or system firmware with a single virtual interrupt. When the VNIC client is started, the VNIC allocates several memory buffers to be used to the reception of Ethernet frames. The VNIC client maps those buffers with TCEs using its TCE mapping services. For each receive buffer, the VNIC client creates Add Receive Buffer Descriptor events (see ), and gives them to system firmware via the Receive Buffer Add Sub-CRQ using H_SEND_SUB_CRQ or H_SEND_SUB_CRQ_INDIRECT. Once this is done, the VNIC client should not use or otherwise modify the receive buffer until it’s been given back to the VNIC client using the Receive Sub-CRQ or the Sub-CRQs and CRQ have been freed using H_FREE_SUB_CRQ and H_FREE_CRQ. As system firmware receives the Receive Buffer Add Sub-CRQ events, it uses its physical adapter device driver to add the receive buffer to the physical adapter’s receive queues. A frame arrives for the physical adapter off of the physical wire, and the adapter dmas the frame directly to the VNIC client’s memory for one of the receive buffers. System firmware receives an interrupt from the physical adapter saying a frame has arrived, and uses the information it saves to generate a Receive Completion event Sub-CRQ (see ), and places it on the appropriate Receive Completion Sub-CRQ. The VNIC client receives a virtual interrupt for its Receive Completion Sub-CRQ, and passes the frame up its network stack.

All VNIC commands are sent using H_SEND_CRQ.

The VERSION_EXCHANGE command as defined in allow the VNIC protocol to be easily updated in the future. Each side is required to support the highest common version of the VNIC protocol specification, as exchanged right after the low level CRQ registration flows. Field Name ByteOffset Length Definition CRQ Type 0 1 This field should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field should be either VERSION_EXCHANGE or VERSION_EXCHANGE_RSP. Version 2 2 Maximum version that VNIC client supports on a VERSION_EXCHANGE and the maximum version that system firmware supports on a VERSION_EXCHANGE_RSP. Each side must support the highest common version between the two versions. A value from will be contained in this field. Reserved 4 8 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .   Value Definition 1 Initial VNIC protocol version 2-65535 Reserved

The VNIC capabilities command as defined in is used to create an abstracted architecture for discovering and utilizing different NIC advanced functions on adapters, in an adapter-independent manner. As new capabilities are introduced in adapters, more capability values will be added. To discover which capabilities a VNIC currently supports, multiple QUERY_CAPABILITY commands should be sent from the VNIC client for each capability of interest. System firmware will return the current capability setting, or a bad return code if the capability isn’t supported. System firmware will return UnsupportedOption for any capability it doesn’t understand. If the VNIC client wishes to use one of the supported capabilities, it must be enabled via the correct REQUEST_CAPABILITY command. If a capability has a variable number of settings (settable via the Number field), and system firmware doesn’t support the value, a PartialSuccess return code will be returned with the capped value in the response. If the VNIC client wishes to use REQUEST_CAPABILITY to determine if any specific capabilities are valid without performing QUERY_CAPABILITY commands, that’s acceptable, but there may be side effects as a result. Field Name Byte Offset Length Definition CRQ Type 0 1 This field should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field should be QUERY_CAPABILITIES, REQUEST_CAPABILITIES, or their associated responses. Capability 2 2 This value should be one of the values from . Number 4 8 This field is used for both REQUESTs and QUERYs. For a REQUEST, it’s the value that the VNIC client wishes to use. On any RSP, it’s the new (or unchanged) current value of the capability. Return Code 12 4 This is a return code for the operation as defined in .   Value Field Name Behavior 1 Minimum Number of firmware-supported Transmit Completion/Submission Queues - Query-only- Integer value returned in Number 2 Minimum Number of firmware-supported Receive Completion Queues - Query-only- Integer value returned in Number 3 Minimum Number of firmware-supported Receive Buffer Add Queues per Receive Completion Queue - Query-only- Integer value returned in Number 4 Maximum Number of firmware-supported Transmit Completion/Submission Queues - Query-only- Integer value returned in Number 5 Maximum Number of firmware-supported Receive Completion Queues - Query-only- Integer value returned in Number 6 Maximum Number of firmware-supported Receive Buffer Add Queues per Receive Completion Queue - Query-only- Integer value returned in Number 7 Requested Number of Transmit Completion/Submission Queues - Settable- Positive integer value set and returned in Number 8 Requested Number of Receive Completion Queues - Settable- Positive integer value set and returned in Number 9 Requested Number of Receive Buffer Add Queues per Receive Completion Queue - Settable- Positive integer value set and returned in Number 10 Minimum Number of Transmit Entries Per Sub-CRQ - Query only- Positive integer value set and returned in Number 11 Minimum Number of Receive Buffer Add Entries per Sub-CRQ - Query only- Positive integer value set and returned in Number 12 Maximum Number of Transmit Entries Per Sub-CRQ - Query only- Positive integer value set and returned in Number 13 Maximum Number of Receive Buffer Add Entries per Sub-CRQ - Query only- Positive integer value set and returned in Number 14 Requested Number of Transmit Entries Per Sub-CRQ - Settable- Positive integer value set and returned in Number 15 Requested Number of Receive Buffer Add Entries per Sub-CRQ - Settable- Positive integer value set and returned in Number 16 TCP/IP offload supported - Query only- Boolean value returned in Number. If TRUE, TCP/IP offload commands defined in are supported. 17 Promiscuous mode requested - Settable- Boolean value returned in Number 18 Promiscuous mode supported - Query only- Boolean value returned in Number 19 Minimum MTU size - Query only- Positive integer value set and returned in Number 20 Maximum MTU size - Query only- Positive integer value set and returned in Number 21 Requested MTU size - Settable - Positive integer value set and returned in Number - This setting can impact the minimum number of queues or receive buffer sizes supported, and should either be set early or other capabilities will need to be reevaluated. 22 Maximum Number of Unique Multicast MAC address filters - Query only- Positive integer value set and returned in Number 23 VLAN Header insertion supported - Query only - Boolean value returned in Number - This is controlled on a packet by packet basis in the transmit descriptor. 24 Reserved   25 Maximum Transmit Scatter Gather entries - Query only - Positive integer value reflecting the maximum number of IOBAs that can be used to describe a single frame using Transmit Descriptors. 26 Receive Scatter/Gather Mode supported - Query only - Boolean value set and returned in Number. - If supported, this can enable chaining of receive buffers together to minimize the amount of memory that needs to be added in the form of Receive Buffers (Particularly if Large Receive Offload is enabled). 27 Receive Scatter/Gather Mode Requested - Settable - Boolean value set and returned in Number. - This setting can impact the number of queues or receive buffer sizes supported, and should be set before configuring those values. 28-65535 Reserved  

The use of the LOGIN and LOGIN_RSP commands is defined in . The format of the LOGIN command is defined in , and the LOGIN_RSP command is defined in . There must be exactly one Transmit Submission Sub-CRQ for each Transmit Completion Sub-CRQ, and vice versa. Each is implicitly tied to the other by virtue of the order each appears in the array of handles in the LOGIN Buffer and LOGIN Response buffer. (i.e. The first entry in each are associated, the second entry in each are associated, etc.) Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This should be set to LOGIN. Reserved 2 6 This field is reserved, and should be set to 0. IOBA 8 4 This field is an I/O bus address referring to a TCE-mapped buffer containing the LOGIN Buffer as defined in . Length 12 4 This field is the length of the TCE-mapped LOGIN buffer. This value should match that as seen in the LOGIN Buffer.   Field Name Byte Offset Length Definition Total Length 0 4 This field is the total length of the LOGIN Buffer. Version 4 4 This field contains the version of LOGIN Buffer layout. The initial version should be set to 1. Number of Transmit Completion Sub-CRQs 8 4 This field contains the number of Transmit Completion Sub-CRQs as allocated by the VNIC client. Offset to Transmit Completion Sub-CRQ handles 12 4 Offset from the beginning of the LOGIN buffer to the start of an array of 8 byte elements containing the array of Transmit Completion Sub-CRQ handles. Number of Receive Completion Sub-CRQs 16 4 This field contains the number of Receive Completion Sub-CRQs as allocated by the VNIC client. Offset to Receive Completion Sub-CRQ handles 20 4 Offset from the beginning of the LOGIN Buffer to the start of an array of 8 byte elements containing the array of Receive Completion Sub-CRQ handles. Login Response buffer IOBA 24 4 This field contains an I/O buffer address referencing a TCE-mapped buffer to be used for the system firmware to place its LOGIN Response buffer containing its variable length array of Sub-CRQ handles. This can point to the same storage as the LOGIN Buffer, as necessary. Login Response buffer length 28 4 This field contains the length of the Login Response buffer described in the Login Response buffer IOBA. The VNIC client needs to ensure that system firmware will have enough space to place each Sub-CRQ handle as requested prior to LOGIN using REQUEST_CAPABILITY commands. Transmit Completion Sub-CRQ handle array variable variable This is a variable sized array containing the Sub-CRQ handles obtained from H_REGISTER_SUB_CRQ for the Transmit Completion Sub-CRQ handles. Receive Completion Sub-CRQ handle array variable variable This is a variable sized array containing the Sub-CRQ handles obtained from H_REGISTER_SUB_CRQ for the Receive Completion Sub-CRQ handles.   Field Name Byte Offset Length Definition Total Length 0 4 This field is the total length of the Login Response Buffer. Version 4 4 This field contains the version of LOGIN Response Buffer layout. The initial version should be set to 1. Number of Transmit Submission Sub-CRQs 8 4 This field contains the number of Transmit Submission Sub-CRQs as requested by the VNIC client and allocated by firmware. Offset to Transmit Submission Sub-CRQ handles 12 4 Offset from the beginning of the LOGIN Response Buffer to the start of an array of 8 byte elements containing the array of Transmit Submission Sub-CRQ handles. Number of Receive Buffer Add Sub-CRQs 16 4 This field contains the total number of Receive Buffer Add Sub-CRQs as requested by the VNIC client and allocated by the firmware. The first n correspond to the first Receive Completion Sub-CRQ, the next n to the second, etc., where n is the Requested number of Receive Buffer Add Sub-CRQs per Receive Completion Queue requested by the VNIC client. Offset to Receive Buffer Add Sub-CRQ handles 20 4 Offset from the beginning of the LOGIN Response Buffer to the start of an array of 8 byte elements containing the array of Receive Buffer Add Sub-CRQ handles. Offset to Receive Buffer Add Buffer Size 24 4 Offset from the beginning of the LOGIN Response Buffer to the start of an array of 8 byte sizes. There is one size for each Receive Buffer Add Sub-CRQ, and each size represents the receive buffer size possible for that specific Receive Buffer Add Sub-CRQ. Number of Supported Transmit Descriptors 28 4 This field contains the number of supported Transmit Descriptors, as detailed in . Offset to Supported Transmit Descriptors array 32 4 Offset from the beginning of the LOGIN Response Buffer to the start of an array of 1 byte values. There is one value for each supported Transmit Descriptor format, sorted so the formats with best performance will be first in the array. Transmit Submission Sub-CRQ handle array variable variable This is a variable sized array containing the Sub-CRQ handles obtained from H_REGISTER_SUB_CRQ for the Transmit Submission Sub-CRQ handles. Receive Buffer Add Sub-CRQ handle array variable variable This is a variable sized array containing the Sub-CRQ handles obtained from H_REGISTER_SUB_CRQ for the Receive Buffer Add Sub-CRQ handles. Receive Buffer Add Buffer Size array variable variable This is a variable sized array containing the Receive Buffer Sizes must use for the respective Receive Buffer Add Sub-CRQs. Supported Transmit Descriptors array variable variable This is a variable sized array containing the performance-order sorted array of one byte supported Transmit Descriptor formats.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This should be set to LOGIN_RSP. Reserved 2 10 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .

A VNIC client may always use the QUERY_PHYS_PARM command to retrieve information about the current physical port state such as current link speed and state. A VNIC client may always use the QUERY_PHYS_CAPABILITIES command to retrieve information about the current capabilities of the physical adapter associated with the VNIC, including allowed speed, duplex, and ability to modify those values. If the VNIC client wishes to determine all bits that are supported by firmware, it may choose to send a QUERY_PHYS_CAPABILITIES command with no bits turned on. Firmware will respond with all possible bits it supports. If the VNIC client wishes to determine if a specific bit combination is supported by firmware, it may turn on those specific bit combinations. In that case, firmware will validate the combination, and validate the specific combination. If the system administrator has configured the VNIC to have physical port configuration authority, the VNIC client may also use the SET_PHYS_PARMS command to change those values. The SET_PHYS_PARMS, QUERY_PHYS_PARMS, and QUERY_PHYS_CAPABILITIES commands all use a common command format defined in . Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be either SET_PHYS_PARMS, QUERY_PHYS_PARMS, QUERY_PHYS_CAPABILITIES, or the respective response values. Flags 2 1 The following bits are used to either request the specific capability on a SET_PHYS_PARMS, indicate the capability to use that capability on a QUERY_PHYS_CAPABILITIES, or return the current value of the capability on a QUERY_PHYS_PARMS command. Bit 0: External loopback mode Bit 1: Internal loopback mode Bit 2: Promiscuous mode Bit 3: Physical Link Active (VNIC can communicate onto the physical media) Bit 4: Autonegotiate Duplex Bit 5: Full duplex mode Bit 6: Half duplex mode Bit 7: If set, the VNIC has the ability to change physical port parameters. Flags 3 1 Bit 0: Adapter Logical Link Active (multiple VNICs on the same adapter can communicate) Bit 1-7: Reserved Speed 4 4 The following bits are used to either request the specific speed on a SET_PHYS_PARMS, indicate the capability to use that speed on a QUERY_PHYS_CAPABILITIES, or return the current speed on a QUERY_PHYS_PARMS command. Bit 0: Autonegotiate speed Bit 1: 10 megabit speed Bit 2: 100 megabit speed Bit 3: 1 gigabit speed Bit 4: 10 gigabit speed Bit 5-31: These bits are reserved, and should be set to 0. MTU 8 4 This field is used to request a MTU for this VNIC client, and to return the current MTU setting. If this value exceeds the allowed value in the case where there are multiple VNICs associated with the same physical adapter, this MTU will be capped to an allowable value, and a PartialSuccess return code will be returned on the SET_PHYS_PARMS command. Return Code 12 4 On a response, this is a return code for the operation as defined in .

When the VNIC does not have authority to change the physical port parameters, the LOGICAL_LINK_STATE command and response provide a method for the VNIC to inform system firmware when it’s ready to receive packets. The format of the LOGICAL_LINK_STATE and LOGICAL_LINK_STATE_RSP commands is defined in . The current VNIC logical link state will always be returned in the Link State field on a LOGICAL_LINK_STATE_RSP. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be either LOGICAL_LINK_STATE or LOGICAL_LINK_STATE_RSP. Link State 2 1 This field is used to request a logical link state change by the VNIC client without a corresponding change to the physical link state. The intended use for this is when a VNIC client is associated with a NIC VF that doesn’t have control over the physical port to control when the VNIC client receives incoming frames. If this field is a 0, the link should be down, if the field is a 1, the link should be up. if this field is 0xFF, no logical link state change will be done, and the current logical link state will be returned in the response. Reserved 3 9 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .

The QUERY_IP_OFFLOAD command as defined in allows the VNIC client to determine what facilities exist in the VNIC system firmware, and its limitations, if any. Based on the capabilities and limitations, the CONTROL_IP_OFFLOAD command as defined in allows the VNIC client to enable appropriate offload capabilities. QUERY_IP_OFFLOAD and CONTROL_IP_OFFLOAD must be done prior to successful LOGIN exchange. All offload parameters are off by default. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be either QUERY_IP_OFFLOAD or QUERY_IP_OFFLOAD_RSP. Reserved 2 2 This field is reserved, and should be set to 0. Length 4 4 This field contains the length of the QUERY_IP_OFFLOAD buffer IOBA 8 4 This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to return IP offload information. On reception of a successful QUERY_IP_OFFLOAD_RSP, the buffer will be filled in with the structure as defined in . Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be CONTROL_IP_OFFLOAD or CONTROL_IP_OFFLOAD_RSP. Reserved 2 2 This field is reserved, and should be set to 0. IOBA 4 4 This field is an I/O bus address referring to a TCE-mapped buffer containing the parameters to enable or disable TCP, UDP, and IP offload. The format of this buffer is defined in . Length 8 4 This field contains the length of the CONTROL_IP_OFFLOAD buffer. Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Definition Total Length 0 4 This field is the total length of the QUERY_IP_OFFLOAD Buffer. Version 4 4 This field contains the version of QUERY_IP_OFFLOAD Buffer layout. The initial version should be 1. IPv4 Checksum offload supported 8 1 This field is 1 if supported IPv6 Checksum offload supported 9 1 This field is 1 if supported. TCP over IPv4 checksum offload supported 10 1 This field is 1 if supported. TCP over IPv6 checksum offload supported 11 1 This field is 1 if supported. UDP over IPv4 checksum offload supported 12 1 This field is 1 if supported. UDP over IPv6 checksum offload supported 13 1 This field is 1 if supported. Large send offload over IPv4 supported 14 1 This field is 1 if supported. Large send offload over IPv6 supported 15 1 This field is 1 if supported. Large receive offload over IPv4 supported 16 1 This field is 1 if supported. Large receive offload over IPv4 supported 17 1 This field is 1 if supported. Reserved 18 14 This field is reserved, and is set to 0. Maximum IPv4 header size 32 2 This field contains the maximum size of the IPv4 header for offload operations, or 0xFFFF if no limit. Maximum IPv6 header size 34 2 This field contains the maximum size of the IPv6 header for offload operations, or 0xFFFF if no limit. Maximum TCP header size 36 2 This field contains the maximum size of the TCP header for offload operations, or 0xFFFF if no limit. Maximum UDP header size 38 2 This field contains the maximum size of the UDP header for offload operations, or 0xFFFF if no limit. Maximum Large send offload size 40 4 This field contains the maximum size of a pseudo-frame for large send offload operations, or 0xFFFFFFFF if no limit. Maximum Large receive offload size 44 4 This field contains the maximum size of a pseudo-frame for large receive offload operations, or 0xFFFFFFFF if no limit. Reserved 48 16 This field is reserved, and is set to 0. IPv6 Extension Header supported 64 1 This field contains a 0 if no extension headers are supported. This field contains a 1 if extension headers are supported with limits This field contains a 0xFF if all IPv6 extension headers are supported TCP Pseudosum required 65 1 This field is 0 if no pseudosum is required in the frame. This field is 1 if a standard pseudosum is required to be put in the frame. All other values are reserved. Reserved 66 30 This field is reserved, and is set to 0. Number of IPv6 extension headers supported 96 2 This field must be non zero if the IPv6 Extension Header supported field is 1. Offset to List of supported IPv6 extension headers 98 4 This field contains an offset from the start of the QUERY_IP_OFFLOAD buffer to the array of supported extension header values. Reserved 102 154 This field is reserved, and should be set to 0. Array of IPv6 extension header types variable variable This is an array of one byte values that are the extension header types supported by IPv6 offload.   Field Name Byte Offset Length Definition Total Length 0 4 This field is the total length of the CONTROL_IP_OFFLOAD Buffer. Version 4 4 This field contains the version of CONTROL_IP_OFFLOAD Buffer layout. The initial version should be set to 1. Enable IPv4 Checksum offload 8 1 This field is 1 if desired Enable IPv6 Checksum offload 9 1 This field is 1 if desired. Enable TCP over IPv4 checksum offload 10 1 This field is 1 if desired. Enable TCP over IPv6 checksum offload 11 1 This field is 1 if desired. Enable UDP over IPv4 checksum offload 12 1 This field is 1 if desired. Enable UDP over IPv6 checksum offload 13 1 This field is 1 if desired. Enable Large send offload over IPv4 14 1 This field is 1 if desired. Enable Large send offload over IPv6 15 1 This field is 1 if desired. Enable bad packet reception 16 1 This field is 1 if desired Reserved 17 111 This field is reserved, and should be set to 0.

The dumps collected via the VNIC interface is a smart dump that depends upon a working device driver. If the portion of system firmware servicing the physical adapter has run into catastrophic problems, an entire memory image of the associated firmware will be collected automatically, and collected in a similar fashion to platform dumps. If the VNIC client detects that the VNIC interface is not providing the services in the manner it expects, it may utilize the dump support to collect focused debugging data collected and stored in VNIC client storage that’s been TCE-mapped. The format of the REQUEST_DUMP command is defined in , and the format of the REQUEST_DUMP_RSP command is defined in . Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be either REQUEST_DUMP_SIZE or REQUEST_DUMP_SIZE_RSP. Reserved 2 6 This field is reserved, and should be set to 0. Length 8 4 This field is set to the estimated length of the VNIC dump in the REQUEST_DUMP_RSP if the return code was Success. Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_DUMP. Reserved 2 2 This field is reserved, and should be set to 0. IOBA 4 4 This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to place the VNIC dump. Length 8 4 This field contains the length of the VNIC dump buffer. Reserved 12 4 This field is reserved and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_DUMP_RSP. Reserved 2 6 This field is reserved, and should be set to 0. Dumped Length 8 4 This field contains the amount of data placed into the dump buffer. Return Code 12 4 This is a return code for the operation as defined in .

The VNIC RAS support allows the tracing of information within system firmware, and control of consistency checking done by firmware. Individual components of firmware will be exposed to the VNIC Client, and each component can independently have their tracing and error checking levels increased and decreased. Each individual component’s trace information can be collected independently from others. Trace entries will be returned to the VNIC client in timebase order. The upper 16 bits of the trace ID for the Firmware Trace Data Format are an AIX RAS tracehook ID, and the lower 16 bits are an AIX RAS subhookid. Prior to a successful LOGIN request, all components related to the VNIC may not be available in the list of components. To get a complete list of all possible components, the RAS commands should be delayed until after a successful LOGIN unless a pre-LOGIN problem is being diagnosed. The CONTROL_RAS command can be used to resize the individual components’ trace buffers, but due to the limited memory available in the system firmware, increasing the sizes of one trace buffer may require decreasing the size of a different component’s trace buffer. The REQUEST_RAS_COMP_NUM and REQUEST_RAS_COMP_NUM_RSP commands are defined in , and the REQUEST_RAS_COMPS and REQUEST_RAS_COMPS_RSP command format is defined in . The COLLECT_FW_TRACE and COLLECT_FW_TRACE_RSP commands are defined in . Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_RAS_COMP_NUM or REQUEST_RAS_COMP_NUM_RSP. Reserved 2 2 This field is reserved, and should be set to 0. Number of Components 4 4 This field contains the number of individual firmware components whose RAS characteristics can be independently modified. Reserved 8 4 This field is reserved, and should be set to 0. Return Code 12 4 On a response, this field will contain a return code for the request as defined in . This field is reserved for a request. . Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_RAS_COMPS or REQUEST_RAS_COMPS_RSP. Reserved 2 2 This field is reserved, and should be set to 0. IOBA 4 4 This field contains an I/O bus address of a TCE-mapped buffer containing an array of Firmware Component structures as defined in . The VNIC client should ensure the buffer is large enough to contain the number of components as returned in a REQUEST_RAS_COMP_NUM_RSP command. Length 8 4 This field is the length of the buffer referred to by the IOBA field. It should be some multiple of the size of the Firmware Component format. Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be CONTROL_RAS or CONTROL_RAS_RSP. Correlator 2 1 This field contains a Correlator for a Firmware Component as defined in that this command should act on. Level 3 1 This value should be a value between 0 and 9, where a larger number indicates a higher detail of tracing or error checking. Operation 4 1 This field controls what action the CONTROL_RAS command performs. If this value is a 1, use the Level field to modify the current trace level of the specified component. If this value is a 2, use the Level field to modify the current error checking level of the specified component. If this value is a 3, suspend the tracing for the specified component that was previously on. If this value is a 4, resume the tracing for the specified component that was previously suspended. If this value is a 5, turn tracing for the specified component on. If this value is a 6, turn tracing for the specified component off. If this value is a 7, change the size of the specified trace buffer for the specified component. All other values are reserved. Trace Buffer Size 5 3 If Operation is a 7, this field contains the requested size of the specified trace buffer. On a response, will be filled in with the current size of the trace buffer. For all other Operation values, this field is reserved. Reserved 8 4 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be COLLECT_FW_TRACE or COLLECT_FW_TRACE_RSP. Correlator 2 1 This field contains a Correlator for a Firmware Component as defined in that this command should act on. Reserved 3 1 This field is reserved, and should be set to 0. IOBA 4 4 This field contains the I/O bus address of a TCE-mapped buffer of the indicated size that will be used by firmware to return the trace. Buffer Length 8 4 This field contains the length of the buffer in bytes used to collect the trace information. On a COLLECT_FW_RSP, this value will indicate how much trace data is actually placed in the buffer. The trace data is an array of entries with the format as defined in . Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Trace ID 0 4 Number Valid Trace Data 4 1 Reserved 5 3 PMC Registers 8 8 Timebase 16 8 Trace Data 1 24 8 Trace Data 2 32 8 Trace Data 3 40 8 Trace Data 4 48 8 Trace Data 5 56 8   Field Name Byte Offset Length Definition Component Name 0 48 This field contains an ASCII string containing a readable name of the component. Trace Buffer Size 48 4 This field contains the size of the trace buffer. Correlator 52 1 This field contains a value to be used on a COLLECT_FW_TRACE or CONTROL_RAS command to identify which component to operate on. Trace Level 53 1 This field shows the current trace level, as defined in . A value of 0xFF indicates this component does not support tracing. Parent Correlator 54 1 This field contains the correlator of the parent component. If this value is 0xFF, there is no parent. Error Checking 55 1 This field contains the error checking level for this component. It contains a value from 0-9, where 0 means no extra error checking, and 9 means the highest level of consistency checking. A value of 0xFF indicates this component does not support changing its level of error checking. Trace State 56 1 If this field is a 0, the component’s tracing is turned off. If this field is a 1, the component’s tracing is turned on. Reserved 57 7 This field is reserved, and should be set to 0. Description 64 192 This field contains an ASCII string containing a readable description of the component.

The REQUEST_STATISTICS command as defined in is used by the VNIC client to obtain statistic counters kept by system firmware and the physical adapter supporting the VNIC. The REQUEST_STATISTICS_RSP command is defined in . In the event a given VNIC does not support the retrieval of certain of the statistics, the statistic will have a -1 value returned in it. The REQUEST_DEBUG_STATS command defined in is used by the VNIC client to retrieve an unarchitected block of statistics that is implementation dependent which may be used to debug firmware problems. This is an optional command, and the actual data returned may vary from implementation to implementation. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_STATISTICS. Flags 2 1 Bit 0: If set, retrieve the physical port statistics. If the VNIC doesn’t have authority to retrieve the physical port statistics, the command may fail. If this bit is 0, retrieve the logical port statistics. Bit 1: If this field is set to 1, clear the statistics. If this field is set to 0, do not clear any statistics. Bit 2-7: This fields are reserved, and should be set to 0. Reserved 3 1 This field is reserved, and should be set to 0. IOBA 4 4 This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to place the VNIC statistics block as defined in . Length 8 4 This field contains the length of the VNIC statistics buffer. Reserved 12 4 This field is reserved and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_STATISTICS_RSP. Reserved 2 2 This field is reserved, and should be set to 0. Reserved 4 8 This field is reserved and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Version 0 4 Promiscuous 4 4 Received Packets 8 8 Bytes Received 16 8 Packets Sent 24 8 Bytes Sent 32 8 Unicast Packets Sent 40 8 Unicast Packets Received 48 8 Multicast Packets Sent 56 8 Multicast Packets Received 64 8 Broadcast Packets Sent 72 8 Broadcast Packets Received 80 8 Alignment Errors 88 8 FCS Errors 96 8 Single Collision Frames 104 8 Multiple Collision Frames 112 8 SQE Test Errors 120 8 Deferred Transmissions 128 8 Late Collisions 136 8 Excess Collisions 144 8 Internal MAC Transmit Errors 152 8 Carrier Sense 160 8 Too Long Frames 168 8 Internal MAC Receive Errors 176 8 DMA Receive Overrun 184 8 DMA Transmit Underrun 192 8 Receive No Resource 200 8 Too Short Frames 208 8 Reserved 216 40   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_DEBUG_STATS or REQUEST_DEBUG_STATS_RSP. Reserved 2 2 This field is reserved, and should be set to 0. IOBA 4 4 This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to place the VNIC debug statistics block. Length 8 4 This field contains the length of the VNIC statistics buffer. On a REQUEST_DEBUG_STATS_RSP, contains the amount of data filled in. Return Code 12 4 This is a return code for the operation as defined in .

If system firmware encounters an error processing requests related to the physical adapter being virtualized by the VNIC interface, it will generate ERROR_INDICATION commands to the VNIC client, as defined in . The VNIC client may then, at its discretion, obtain detailed error information using the REQUEST_ERROR_INFO command as defined in . It is the intent that the VNIC client should log the detailed error information using its normal error logging infrastructure and methods. The REQUEST_ERROR_INFO_RSP command as defined in is used by firmware to indicate the successful retrieval of error information. The retrieval of detailed error information allows firmware to reuse the resources for tracking that error. Detailed error information can only be requested for a specific error once. If system firmware encounters an error while the VNIC client is not connected, firmware will log the detailed error information using firmware error logging methods. Firmware will have a finite amount of space reserved for storing detailed error information. In some situations, some detailed error information may be unavailable in response to a REQUEST_ERROR_INFO command if too many errors are being logged in firmware. If the detailed error information is overwritten prior to the VNIC client performing the relative REQUEST_ERROR_INFO command, an error return code will be returned. If the fatal error bit is set, the VNIC firmware has encountered a fatal error preventing it from automatically recovering from the error. The VNIC client should use the RAS facilities to collect any error information, collect any RAS tracing, statistics, and possibly a dump. Once all available error data has been collected, it is the VNIC client’s responsibility to cause the VNIC to restart. This can be accomplished in one of two ways: by freeing its CRQ using H_FREE_CRQ, or by initiating a VNIC reset using the H_VIOCTL FW_RESET subfunction. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be ERROR_INDICATION. Flags 2 1 Bit 0: If this bit is 1, this is a fatal error. Bit 1-7: These fields are reserved, and should be set to 0. Reserved 3 1 This field is reserved, and should be set to 0. Error Identification 4 4 This field is set to the error identification number that can be used to retrieve detailed information about the error using the REQUEST_ERROR_INFO command. If this value is set to 0, there is no more detailed error information to retrieve, and the ERROR_INDICATION contains all relevant information. Detailed Error Size 8 4 This field contains the size of the detailed error information associated with the error. Error Cause 12 2 This field contains a value as detailed in showing the cause of the error. Reserved 14 2 This field is reserved, and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_ERROR_INFO. Reserved 2 2 This field is reserved, and should be set to 0. Buffer IOBA 4 4 This field contains the I/O bus address of a TCE-mapped buffer to be used by system firmware to write the detailed error information into. Buffer Length 8 4 This field contains the length of the TCE-mapped buffer. Error Identification 12 4 This field contains the error identification from an ERROR_INDICATION command that specifies which detailed error information to obtain.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be REQUEST_ERROR_INFO_RSP. Reserved 2 2 This field is reserved, and should be set to 0. Error Identification 4 4 This field contains the error identification from an ERROR_INDICATION command. This field can be used to correlate this response to s REQUEST_ERROR_INFO command, allowing multiple requests for errors to be outstanding at the same time. Length 8 4 This field contains the length of data successfully returned in the TCE-mapped buffer. Return Code 12 4 This is a return code for the operation as defined in .   Value Definition Adapter Problem 0 Bus Problem 1 Firmware Problem 2 Device Driver Problem 3 EEH Recovery 4 Firmware Updated 5 Low Memory 6 Reserved 7-65535

This LINK_STATE_INDICATION command as defined in is an unacknowledged command sent by system firmware to inform the VNIC client when the state of the link changes. The VNIC client can also use QUERY_PHYS_PARMS at any time to poll for link state changes. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be LINK_STATE_INDICATION. Reserved 2 2 This field is reserved, and should be set to 0. Physical Link State 4 1 If this field is a 0, the physical link is down, if the field is a 1, the physical link is up. Logical Link State 5 1 If this field is a 0, the logical link is down and the VNIC cannot communicate with other VNICs on the same adapter, if the field is a 1, the logical link is up, and the VNIC can communicate with other VNICs on the same adapter. Reserved 6 10 This field is reserved, and should be set to 0.

The CHANGE_MAC_ADDR command defined in allows the VNIC client to change the current MAC address. The request to change may fail due to Access Control List entries set up by the administrator. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be CHANGE_MAC_ADDR or CHANGE_MAC_ADDR_RSP. MAC Address 2 6 This field contains the new requested MAC address on a CHANGE_MAC_ADDR command, and the current MAC address on a CHANGE_MAC_ADDR_RSP. Reserved 8 4 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .

The MULTICAST_CTRL command defined in allows the VNIC client to manage the reception of Multicast Ethernet traffic. Individual multicast MAC addresses may be enabled and disabled, as well as all multicast traffic. The VNIC client can choose to enable more than the maximum unique multicast Ethernet addresses as returned in the Capabilities exchange. In the event the VNIC client does so, system firmware will either enable the MAC address via a non-exact hashing multicast reception mechanism if the hardware supports it, or will enable all multicast addresses. When this is done, system firmware will report exact matches through the unique multicast Ethernet filter via the Exact Match bit defined in the Receive Completion Descriptor as defined in . If the Exact Match bit is off, and a multicast packet was returned in the Receive Completion Descriptor, the multicast packet either matches a non-exact hashing mechanism if one exists or system firmware has enabled all multicast MAC address reception. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be MULTICAST_CTRL or MULTICAST_CTRL_RSP. MAC Address 2 6 This field contains the new requested multicast MAC address, as appropriate for the specific options requested. Flags 8 1 Bit 0: Enable specified multicast MAC address Bit 1: Disable specified multicast MAC address Bit 2: Enable the reception of all multicast MAC addresses. This does not affect the multicast addresses enabled through Bit 0. Bit 3: Disable the reception of all multicast MAC addresses. This does not affect the multicast addresses enabled through Bit 0. Bit 4-7: These bits are reserved, and should be set to 0. Reserved 9 3 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .

The VPD commands may be used by the VNIC client to collect, store, and display VPD related to the physical adapter backing the VNIC. As the exact adapter may change during partition mobility operations, it is suggested this data not be relied upon operationally, and be used with the understanding that it may change from request to request. The VPD commands are defined in , , , and . Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be GET_VPD_SIZE. Reserved 2 14 This field is reserved, and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be GET_VPD_SIZE_RSP. Reserved 2 2 This field is reserved, and should be set to 0. Length 4 8 This field contains the length of the VPD present. Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be GET_VPD. Reserved 2 2 This field is reserved, and should be set to 0. IOBA 4 4 This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to place the VNIC VPD. Length 8 4 This field contains the length of the VPD buffer. Reserved 12 4 This field is reserved and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be GET_VPD_RSP. Reserved 2 10 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .

The VNIC may have certain Access Control Lists (ACLs) in effect, and some of these may change dynamically. The ACL_CHANGE_INDICATION command defined in is sent by system firmware to the VNIC client in the event any of the ACLs have changed dynamically. The ACL_QUERY command defined in and its associated response defined in may be used by the VNIC client to obtain information about the ACLs in effect to enable earlier error checking or ease of use functions. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be ACL_CHANGE_INDICATION. Change Type 2 2 If this field is a 0, the MAC address ACLs have changed. If this field is a 1, the VLAN id ACLs have changed. All other values are reserved. Reserved 4 12 This field is reserved, and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be ACL_QUERY. Reserved 2 2 This field is reserved, and should be set to 0. IOBA 4 4 This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to place the ACL information. Upon reception of a ACL_QUERY_RSP with a Success return code, this buffer will be filled in with the structure as defined in Size 8 4 This field contains the size of the buffer mapped by the IOBA. Reserved 12 4 This field is reserved, and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be ACL_QUERY_RSP. Reserved 2 10 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .   Field Name Byte Offset Length Definition Total Length 0 4 This field is the total length of the ACL Buffer. Version 4 4 This field contains the version of ACL Buffer layout. The initial version should be set to 1. MAC ACLs in effect 8 1 This field contains a 1 if there are MAC restrictions in effect, zero otherwise. VLAN id ACLs in effect 9 1 This field contains a 1 if there are VLAN id ACLs in effect, zero otherwise. Reserved 10 22 This field is reserved, and should be set to 0. Number of Allowed MAC addresses 32 4 This field contains the number of allowable MAC addresses. Offset to array of allowed MAC addresses 36 4 This field contains an offset from the start of the ACL Buffer to an array of six byte MAC addresses. Number of allowed VLAN ids 40 4 This field contains the number of allowable VLAN ids. Offset to array of allowed VLAN ids 44 4 This field contains an offset from the start of the ACL buffer to an array of 2 byte VLAN ids. Reserved 48 80 This field is reserved, and should be set to 0. Array of allowed MAC addresses variable variable This is the array of six byte MAC addresses, with a size as defined in the Number of Allowed MAC address field. Array of allowed VLAN ids variable variable This is the array of two byte VLAN ids, with a size as defined in the Number of Allowed VLAN ids field.

The TUNE command defined in may be used by the VNIC client to opaquely pass tuning data from the VNIC client to system firmware. As the exact firmware backing a VNIC client may change during partition mobility operations, it is suggested this data not be relied upon operationally, and be used with the understanding that it may change from adapter to adapter. A TUNE_RSP command defined in will be generated by system firmware upon completion of the TUNE command. This command is an optional VNIC command, and may not be supported for all VNIC implementations or versions of system firmware. Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be TUNE. Reserved 2 2 This field is reserved, and should be set to 0. IOBA 4 4 This field is an I/O bus address referring to a TCE-mapped buffer used by system firmware to obtain the tuning parameters. Length 8 4 This field contains the length of the VPD buffer. Reserved 12 4 This field is reserved and should be set to 0.   Field Name Byte Offset Length Definition CRQ Type 0 1 This should be set to 0x80 to indicate a valid CRQ event. VNIC Command 1 1 This field will be TUNE_RSP. Reserved 2 10 This field is reserved, and should be set to 0. Return Code 12 4 This is a return code for the operation as defined in .

Frame transmission and reception is handled through the Subordinate CRQ infrastructure, using the H_SEND_SUB_CRQ and H_SEND_SUB_CRQ_INDIRECT hypervisor calls.

Since each Transmit Completion Sub-CRQ is tied to a specific Transmit Submission Sub-CRQ, the Transmit Descriptor correlator must only be unique for a given Transmit Completion Sub-CRQ. Several versions of Transmit Descriptors exist. Each version has a Descriptor Version byte at byte offset one in the descriptor, which specifies the layout of the later thirty bytes. A sorted array is returned in the LOGIN response specifying all versions of transmit descriptor supported by the VNIC. The versions of the transmit descriptor offering the best performance appear in the array first. All VNIC versions will support Transmit Descriptor Version Zero defined in , but that version may not offer the best performance. Transmit Descriptor Version Two defined in is designed to be used in combination with a previous use of Transmit Descriptor Version Zero or Transmit Descriptor Version One defined in Field Name Byte Offset Length Definition Sub-CRQ Format 0 1 This value should be set to 0x80 to indicate a valid Sub-CRQ event. Descriptor Version 1 1 This field is 0 for a Version Zero Transmit Descriptor Flags 2 1 Bit 0: If set to 1, this frame should use the large send offload feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 1: If set to 1, this frame should use the IP checksum feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 2: If set to 1, this frame should use the TCP checksum feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 3: If set to 1, this frame should use the physical adapter’s capability of inserting VLAN headers, using the VLAN header field as the source for the values to insert. Bit 4:If set to 1, this frame should use the UDP checksum feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 5: If set to 1, this frame spans multiple transmit descriptors. Bit 6: If set to 1, this frame contains the last fragment of a complete packet for transmission. Bit 7:If set to 1, this frame requires a transmit completion event to be posted to the VNIC client’s Transmit Completion Sub-CRQ. If set to 0, no completion event will be generated unless an error occurred. IP Header offset 3 1 Bit 0:If set to zero, this frame contains an IPv4 frame. If set to 1, this frames contains an IPv6 frame. Bits 1-7: This field should be set to the offset of IP header in the first descriptor of a chain if any checksum offload or large send offload is enabled. If neither checksum offload nor large send offload are enabled, this should be set to 0. TCP/UDP Header offset or IP Data offset 4 2 In the first descriptor of a chain, if any checksum offload or large send offload function should be done for this packet, this field must be set to the offset of the first byte of data after the IP header and extension headers. If no checksum offload or large send offload function should be done for this packet, this field must be set to 0. VLAN Header 6 2 If VLAN header insertion has been enabled, this field contains the VLAN header to be inserted if indicated in the Flags byte. Reserved 8 1 This field is reserved and should be set to 0. MSS Size 9 3 If large send offload is enabled, this field contains the MSS size. Correlator 12 4 This field is set to a unique opaque value generated by the VNIC client that allows the device driver to correlate a transmit submission to an eventual completion. This value must be set even if the Completion Required bit is set to 0 in the event an error happens. IOBA1 16 4 This field contains an I/O bus address valid for the VNIC device that refers to the first chunk of the transmit frame for this descriptor. Length1 20 4 This contains the length of the frame fragment pointed to by IOBA1. IOBA2 24 4 This field contains an I/O bus address valid for the VNIC device that refers to the second fragment of the transmit frame for this descriptor. If the corresponding length field is 0, this field is ignored. Length2 28 4 This contains the length of the frame fragment pointed to by IOBA2. If IOBA2 is invalid, this field should be set to 0.   Field Name Byte offset Length Definition Sub-CRQ Format 0 1 This value should be set to 0x80 to indicate a valid Sub-CRQ event. Number of Completions 1 1 This is the number of return code and correlator pairs of this descriptor that are valid. It must be a value from 1 to 5. Return Codes 2 10 This is an array of 5 two byte integer return codes as defined in . Correlators 12 20 This is an array of five four-byte correlator values as taken from the Transmit Submission Descriptor.   Field Name Byte Offset Length Definition Sub-CRQ Format 0 1 This value should be set to 0x80 to indicate a valid Sub-CRQ event. Descriptor Version 1 1 This field is 1 for a Version One Transmit Descriptor Flags 2 1 Bit 0: If set to 1, this frame should use the large send offload feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 1: If set to 1, this frame should use the IP checksum feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 2: If set to 1, this frame should use the TCP checksum feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 3: If set to 1, this frame should use the physical adapter’s capability of inserting VLAN headers, using the VLAN header field as the source for the values to insert. Bit 4:If set to 1, this frame should use the UDP checksum feature of the physical adapter, assuming it was previously enabled through the use of CONTROL_IP_OFFLOAD command. Bit 5: If set to 1, this frame spans multiple transmit descriptors. Bit 6: If set to 1, this frame contains the last fragment of a complete packet for transmission. Bit 7:If set to 1, this frame requires a transmit completion event to be posted to the VNIC client’s Transmit Completion Sub-CRQ. If set to 0, no completion event will be generated unless an error occurred. IP Header offset 3 1 Bit 0:If set to zero, this frame contains an IPv4 frame. If set to 1, this frames contains an IPv6 frame. Bits 1-7: This field should be set to the offset of IP header in the first descriptor of a chain if any checksum offload or large send offload is enabled. If neither checksum offload nor large send offload are enabled, this should be set to 0. TCP/UDP Header offset or IP Data offset 4 2 In the first descriptor of a chain, if any checksum offload or large send offload function should be done for this packet, this field must be set to the offset of the first byte of data after the IP header and extension headers. If no checksum offload or large send offload function should be done for this packet, this field must be set to 0. VLAN Header 6 2 If this frame is a VLAN-tagged frame, this field contains the VLAN tag even if it is already present in the frame, and even if VLAN offload is disabled. If already present in the frame, this merely provides a hint to enable fast transmission of this frame. If the VLAN header is not present in the frame, this field contains the VLAN header to be inserted if indicated in the Flags byte. Reserved 8 1 This field is reserved and should be set to 0. MSS Size 9 3 If large send offload is enabled, this field contains the MSS size. Correlator 12 4 This field is set to a unique opaque value generated by the VNIC client that allows the device driver to correlate a transmit submission to an eventual completion. This value must be set even if the Completion Required bit is set to 0 in the event an error happens. IOBA1 16 4 This field contains an I/O bus address valid for the VNIC device that refers to the first chunk of the transmit frame for this descriptor. Length1 20 4 This contains the length of the frame fragment pointed to by IOBA1. Destination MAC address 24 6 This field contains the destination MAC address as specified in the frame to be sent. The frame still must contain this information; this merely provides a hint to enable fast transmission of this frame. Ethertype 30 2 This field contains a copy of the ethertype from the specified frame to be sent. The frame still must contain this information; this merely provides a hint to enable fast transmission of this frame.   Field Name Byte Offset Length Definition Sub-CRQ Format 0 1 This value should be set to 0x80 to indicate a valid Sub-CRQ event. Descriptor Version 1 1 This field is 2 for a Version Two Transmit Descriptor. This transmit descriptor should be used following another valid Transmit Descriptor Format such as Version Zero or Version One. It inherits any advanced features from the previous Transmit Descriptor. Flags 2 1 Bit 0-5: These bits are reserved, and should be set to 0. Bit 6: If set to 1, this frame contains the last fragment of a complete packet for transmission. Bit 7:If set to 1, this frame requires a transmit completion event to be posted to the VNIC client’s Transmit Completion Sub-CRQ. If set to 0, no completion event will be generated unless an error occurred. Reserved 3 1 This field is reserved, and should be set to 0. IOBA1 4 4 This field contains an I/O bus address valid for the VNIC device that refers to the first chunk of the transmit frame for this descriptor. Length1 8 4 This field contains the length of the frame fragment pointed to by IOBA1. Correlator 12 4 This field is set to a unique opaque value generated by the VNIC client that allows the device driver to correlate a transmit submission to an eventual completion. This value must be set even if the Completion Required bit is set to 0 in the event an error happens. IOBA2 16 4 This field contains an I/O bus address valid for the VNIC device that refers to the second chunk of the transmit frame for this descriptor. Length2 20 4 This contains the length of the frame fragment pointed to by IOBA2. IOBA3 24 4 This field contains an I/O bus address valid for the VNIC device that refers to the third chunk of the transmit frame for this descriptor. Length3 28 4 This contains the length of the frame fragment pointed to by IOBA3.

Multiple Receive Buffer Add Sub-CRQs can be configured to allow the VNIC client to efficiently allocate receive buffers of different sizes. In the event multiple Sub-CRQs are allocated for this purpose, it is the VNIC client’s responsibility to always allocate the receive buffer size for the Receive Buffer Add Sub-CRQs that are returned by system firmware as defined in . System firmware will configure the correct buffer sizes based on the current VNIC maximum transmission unit, current number of Receive Buffer Add Sub-CRQs, and physical adapter capabilities. In all cases, all receive buffers given to an individual Receive Buffer Add Sub-CRQ must be of the same size. Since a Receive Buffer Correlator may appear on only a single Receive Completion Sub-CRQ, the Receive Buffer Correlators must be unique for a given Receive Completion Sub-CRQ. Since every buffer added to all Receive Buffer Add Sub-CRQs associated with a given Receive Completion Sub-CRQ could be received simultaneously, each Receive Completion Sub-CRQ should be sized to handle every possible buffer given to system firmware on its associated Receive Buffer Add Sub-CRQs. Some implementations of VNIC devices may have alignment requirements. To ensure efficient use of receive buffers, VNIC clients are encouraged to use at least cache-line aligned receive buffers. . Field Name Byte Offset Length Definition Sub-CRQ Format 0 1 This should be set to 0x80 to indicate a valid Sub-CRQ event. Flags 1 1 Bit 0: If this bit is a 1, it indicates system firmware has validated the IP checksum field in the referenced packet was verified to be good. Bit 1: If this bit is a 1, it indicates system firmware has validated the TCP/UDP checksum field in the referenced packet was verified to be good. Bit 2: If this bit is a 1, it indicates this frame contains the end of a packet. Bit 3: If this bit is a 1, this packet is an exact match for one of the requested multicast MAC addresses for this VNIC. Bit 4: If this bit is a 1, the TCP/UDP checksum field contains either the complete TCP/UDP checksum or a partial TCP/UDP checksum in the case of an IP fragment packet. Bit 5-7: These bits are reserved, and will be set to 0. Offset to start of frame data 2 2 This field contains an offset to the start of actual frame data in the returned frame. Length 4 4 This field contains the length of valid data in this descriptor. Correlator 8 8 This field is the correlator taken from the Receive Buffer Add descriptor that allows the VNIC client to associate this completion with a previously added receive buffer. TCP/UDP Checksum 16 2 If the TCP/UDP checksum bit is a 1, this field contains either the complete packet’s TCP/UDP checksum or a partial TCP/UDP checksum in the event the packet is an IP fragment. Reserved 18 14 These fields are reserved, and will be set to 0.   Field Name Byte Offset Length Definition Sub-CRQ Format 0 1 This should be set to 0x80 to indicate a valid Sub-CRQ event. Reserved 1 7 This bytes are reserved, and should be set to 0. Correlator 8 8 This field is an opaque value that is returned to the VNIC client when the buffer described by this descriptor is used to receive a frame from the network. IOBA 16 4 This field contains the I/O bus address for the TCE-mapped memory buffer to be used for frame reception. Length 20 4 This field contains the length of the memory buffer described by this descriptor. Reserved 24 8 These bytes are reserved, and should be set to 0.