GLDv3 implements a capability mechanism that allows the framework to query and enable capabilities that are supported by the GLDv3 driver. Use the mc_getcapab(9E)entry point to report capabilities. If a capability is supported by the driver, pass information about that capability, such as capability-specific entry points or flags through mc_getcapab(). Pass a pointer to the mc_getcapab() entry point in the mac_callback structure. See GLDv3 MAC Registration Data Structures for more information about the mac_callbacks structure.
boolean_t mc_getcapab(void *driver_handle, mac_capab_t cap, void *cap_data);
The cap argument specifies the type of capability being queried. The value of cap can be MAC_CAPAB_HCKSUM (hardware checksum offload) , MAC_CAPAB_LSO (large segment offload) or MAC_CAPAB_RINGS. Use the cap_data argument to return the capability data to the framework.
If the driver supports the cap capability, the mc_getcapab() entry point must return B_TRUE. If the driver does not support the cap capability, mc_getcapab() must return B_FALSE.
Example 19-5 The mc_getcapab() Entry Pointstatic boolean_t
xx_m_getcapab(void *arg, mac_capab_t cap, void *cap_data)
{
switch (cap) {
case MAC_CAPAB_HCKSUM: {
uint32_t *txflags = cap_data;
*txflags = HCKSUM_INET_FULL_V4 | HCKSUM_IPHDRCKSUM;
break;
}
case MAC_CAPAB_LSO: {
/* ... */
break;
}
case MAC_CAPAB_RINGS: {
/* ... */
break;
}
default:
return (B_FALSE);
}
return (B_TRUE);
}
The following sections describe the supported capabilities and the corresponding capability data to return.
Both transmit and receive hardware rings are DMA channels and can be exposed by device drivers. Rings are associated with ring groups. Receive ring groups are associated with one or more MAC addresses, and all network traffic matching any of the MAC addresses associated with a receive group must be delivered by the NIC through one of the rings of that group. The steering of traffic to the receive ring groups is enabled in hardware through layer-2 classification.
The mapping of receive rings to ring groups can be either dynamic or static. With dynamic ring groups, rings can be moved between the groups, as requested by the framework, thereby dynamically shrinking or growing the size of the groups. However with static ring groups, the rings are statically assigned to the groups and this assignment cannot change.
If a receive group contains more than one ring, the NIC must spread traffic through these rings using a hashing mechanism such as RSS (Receive Side Scaling) allowing multiple connections to be assigned different ring.
Exactly one of the receive groups must be designated as the default group (usually the first group at index 0). The following properties are associated with this receive group :
Should have at least one ring.
Is assigned to the primary MAC client of the NIC. The primary MAC client is assigned the primary MAC address of the NIC, and is typically IP.
Must be used to receive all multicast and broadcast traffic received from the network.
If the NIC is placed in promiscuous mode, it must be used to receive all traffic which does not match the MAC addresses assigned to non-default receive groups.
The following points are noteworthy with regards to the hardware implementation of receive rings and receive ring groups:
If multiple receive rings are implemented but layer-2 classification is not supported, the hardware should expose a single receive ring group with all the ring belonging to that group to the framework.
If layer-2 hardware classification is implemented but RSS is not supported, the hardware should register multiple receive groups, with one ring per group.
If both layer-2 hardware classification and RSS are implemented, the hardware should register multiple receive groups with one or more rings per group.
If neither layer-2 hardware classification nor RSS is implemented, the hardware should either not advertise a ring capability, or advertise a ring capability with a single pseudo ring and ring group, which can be used to dynamically poll the adapter for traffic.
Registering rings with the framework involves a process consisting of various calls from the framework to the driver. The following steps describe the registration process :
The framework queries the MAC_CAPAB_RINGS capability of the driver by calling the driver. One call is made for the transmit rings and one call for the receive rings. See MAC_CAPAB_RINGS Capability for more information.
The framework uses the mr_rget(9E) and mr_gget(9E) entry points which are obtained from the previous step, to retrieve information about a specific ring or ring group. See the mr_rget(9E) and mr_gget(9E) man pages for more information.
When the framework wants to use a ring, it starts the ring group with the mgi_start(9E) entry point, and then starts the ring using the mri_start(9E) entry point as advertised in the previous step.
Traffic can now flow through the rings until they are stopped through the mgi_stop(9E) and mri_stop(9E) entry points.
To obtain information about support for hardware transmit and receive rings, the framework sends MAC_CAPAB_RINGS in the cap argument and expects the information back in the cap_data field, which points to the mac_capab_rings structure.
The framework allocates the mac_capab_rings(9S) structure and sets the mr_type member to MAC_RING_TYPE_RX for receive rings, or MAC_RING_TYPE_TX for transmit rings. The remaining members of the structure mac_capab_rings is then filled by the drivers.
The following fields are defined in the mac_capab_rings structure:
Must be set to MAC_RINGS_VERSION_1.
Number of rings.
Number of groups.
The following values are defined:
MAC_GROUP_TYPE_DYNAMIC – The group is dynamic.
MAC_GROUP_TYPE_STATIC – The group is static.
See Rings and Ring Groups Layer–2 Classification for more information.
Driver entry point to get more information about ring groups. See mr_gget() Entry Point for more information.
Driver entry point to get more information about ring. See mr_rget() Entry Point for more information.
Driver entry point to add a ring to a group. See mr_gaddring(9E).
Driver entry point to remove a ring from a group. See mr_gremring(9E).
The mr_gget(9E) entry point is invoked by the framework for each valid group indices corresponding to the number of groups which is indicated by mr_gnum parameter. See mr_gget(9E) for more information. After the call to mr_gget(), the group information is returned in the mac_group_info structure by the driver. The structure itself is pre-allocated by the framework and is filled in by the driver.
The following fields are defined in the mac_group_infostructure:
An opaque driver group handle which is used by the framework in future calls to group entry points.
Number of rings in the group.
Group flags MAC_GROUP_DEFAULT identifies the group to be a default group. See Rings and Ring Groups Layer–2 Classification for more information.
Group start entry point.
Group stop entry point.
Add unicast MAC address entry point.
Remove unicast MAC address entry point.
Entry point to add hardware VLAN filtering, tagging, and stripping of VLAN tags.
Entry point to remove hardware VLAN filtering, tagging, and stripping of VLAN tags.
Set RX group MTU entry point
Entry point to retrieve SR-IOV information for the group. See Ring Groups and SR-IOV for more information.
See mac_group_info(9S) and mac_group_info(9E) for detailed information.
It defines VLAN IDs that must be allowed, for transmission and reception, by the NIC. That is, any tagged packet that is not in the configured list will be dropped.
If the MAC_GROUP_VLAN_TRANSPARENT_ENABLE flag is set then it also enables the hardware VLAN tagging and stripping for that particular VLAN ID.
The mr_rget(9E) entry point is invoked by the framework for each valid group and ring indices corresponding to the number of groups which is indicated by mr_gnum and the number of rings which is indicated by mr_rnum as advertised by the call to MAC_CAPAB_RINGS. See mr_rget(9E) for detailed information.
After the call to mr_rget() is completed, the ring information is returned in the mac_ring_info structure by the driver. The structure is pre-allocated by the framework and is filled in by the driver.
The following fields are defined in the mac_ring_info structure:
An opaque driver group handle which is used by the framework in future calls to ring entry points.
Ring start entry point.
Ring stop entry point
Ring statistics entry point. See GLDv3 Network Statistics for more information.
Ring transmit entry point. See Transmit Data Path for more information.
Ring poll entry point. Receive Data Path for more information.
The DDI interrupt handle associate with the interrupt for this ring.
Enable interrupts on RX rings. See Receive Data Path for more information.
Disable interrupts on RX rings. Receive Data Path for more information.
See mac_group_info(9S) and mac_ring_info(9S) man pages for detailed information.
The device drivers that are SR-IOV capable use the MAC_CAPAB_RINGS capability to inform the framework that they are SR-IOV capable by implementing the mgi_getsriov_info(9E) group entry point. The PF driver is responsible for implementing this entry point.
After the call to mgi_getsriov_info(9E), the SR-IOV information is returned in the mac_sriov_info structure by the driver. The structure is pre-allocated by the framework and is filled-in by the driver.
The PF (Physical Function) driver instance registers as many transmit and receive ring groups as the number of VFs (Virtual Functions). These ring groups advertised by the PF driver are special and are used to manage the VFs. The ring groups do not have any data flowing through them. They are used to configure unicast MAC address, set MTU, add VLAN filters, remove VLAN filters, remove VLAN hardware, and perform VLAN tagging and stripping for VFs.
The msi_vf_index structure member, set by the PF driver, captures the VF index that corresponds to a ring group. This is the same index used by the device driver when the driver calls the pci_plist_getvf(9F) function.
See Chapter 21, SR-IOV Drivers for detailed information about SR-IOV drivers.
To get data about support for hardware checksum offload, the framework sends MAC_CAPAB_HCKSUM in the cap argument. See Hardware Checksum Offload Capability Information.
To query checksum offload metadata and retrieve the per-packet hardware checksumming metadata when hardware checksumming is enabled, use mac_hcksum_get(9F). See The mac_hcksum_get() Function Flags.
To set checksum offload metadata, use mac_hcksum_set(9F). See The mac_hcksum_set() Function Flags.
See Hardware Checksumming: Hardware and Hardware Checksumming: MAC Layer for more information.
To pass information about the MAC_CAPAB_HCKSUM capability to the framework, the driver must set a combination of the following flags in cap_data, which points to a uint32_t. These flags indicate the level of hardware checksum offload that the driver is capable of performing for outbound packets.
Partial 1's complement checksum ability
Full 1's complement checksum ability for IPv4 packets
Full 1's complement checksum ability for IPv6 packets
IPv4 Header checksum offload capability
The flags argument of mac_hcksum_get() is a combination of the following values:
Compute the full checksum for this packet.
The full checksum was verified in hardware and is correct.
Compute the partial 1's complement checksum based on other parameters passed to mac_hcksum_get(). HCK_PARTIALCKSUM is mutually exclusive with HCK_FULLCKSUM.
Compute the IP header checksum.
The IP header checksum was verified in hardware and is correct.
The flags argument of mac_hcksum_set() is a combination of the following values:
The full checksum was computed and passed through the value argument.
The full checksum was verified in hardware and is correct.
The partial checksum was computed and passed through the value argument. HCK_PARTIALCKSUM is mutually exclusive with HCK_FULLCKSUM.
The IP header checksum was computed and passed through the value argument.
The IP header checksum was verified in hardware and is correct.
To query support for large segment (or send) offload, the framework sends MAC_CAPAB_LSO in the cap argument and expects the information back in cap_data, which points to a mac_capab_lso(9S) structure. The framework allocates the mac_capab_lso structure and passes a pointer to this structure in cap_data. The mac_capab_lso structure consists of an lso_basic_tcp_ipv4(9S) structure and an lso_flags member. If the driver instance supports LSO for TCP on IPv4, set the LSO_TX_BASIC_TCP_IPV4 flag in lso_flags and set the lso_max member of the lso_basic_tcp_ipv4 structure to the maximum payload size supported by the driver instance.
Use mac_lso_get(9F) to obtain per-packet LSO metadata. If LSO is enabled for this packet, the HW_LSO flag is set in the mac_lso_get() flags argument. The maximum segment size (MSS) to be used during segmentation of the large segment is returned through the location pointed to by the mss argument. See Large Segment Offload for more information.