1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright (c) 2017, Joyent, Inc. 13.\" Copyright 2022 Oxide Computer Company 14.\" 15.Dd July 2, 2022 16.Dt MAC_GROUP_INFO 9S 17.Os 18.Sh NAME 19.Nm mac_group_info , 20.Nm mac_group_info_t 21.Nd MAC group information structure 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Sh INTERFACE LEVEL 25.Sy Uncommitted - 26This interface is still evolving. 27API and ABI stability is not guaranteed. 28.Sh DESCRIPTION 29The 30.Vt mac_group_info_t 31structure is used by the MAC framework as part of the 32.Dv MAC_CAPAB_RINGS 33capability. 34For background on the MAC framework, please see 35.Xr mac 9E 36and for an introduction to the 37.Dv MAC_CAPAB_RINGS 38capability, 39.Xr mac_capab_rings 9E . 40.Pp 41When a device driver declares that it supports the 42.Dv MAC_CAPAB_RINGS 43capability and fills out the capability structure as described in 44.Xr mac_capab_rings 9E , 45it indicates that it supports a number of transmit and receive groups. 46For each group that it indicates, its 47.Xr mr_gget 9E 48entry point will be called, during which it will have to fill out the 49.Vt mac_group_info_t 50structure described here. 51.Sh TYPES 52The following types define the function pointers in use in the 53.Vt mac_group_info_t 54structure. 55.Bd -literal -offset indent 56typedef int (*mac_group_start_t)(mac_group_driver_t); 57typedef void (*mac_group_stop_t)(mac_group_driver_t); 58typedef int (*mac_add_mac_addr_t)(mac_group_driver_t, const uint8_t *mac, 59 uint_t flags) 60typedef int (*mac_rem_mac_addr_t)(mac_group_driver_t, const uint8_t *mac, 61 uint_t flags) 62typedef int (*mac_add_vlan_t)(mac_group_driver_t, uint16_t vlan, uint_t flags) 63typedef int (*mac_rem_vlan_t)(mac_group_driver_t, uint16_t vlan, uint_t flags) 64.Ed 65.Sh STRUCTURE MEMBERS 66.Bd -literal -offset indent 67mac_group_driver_t mgi_driver; 68mac_group_start_t mgi_start; 69mac_group_start_t mgi_stop; 70uint_t mgi_count; 71mac_add_mac_addr_t mgi_addmac; 72mac_rem_mac_addr_t mgi_remmac; 73mac_add_vlan_t mgi_addvlan; 74mac_rem_vlan_t mgi_remvlan; 75.Ed 76.Pp 77The 78.Fa mgi_driver 79member should be set by the driver to a driver-specific value that 80represents the data structure that corresponds to this group. 81The driver will receive this value in all of the callback functions that 82are defined in this structure and listed below. 83.Pp 84The 85.Fa mgi_start 86member is an optional entry point. 87If the driver needs to take a specific action before it the group is 88used, then it should set this to a function. 89For more information, see 90.Xr mgi_start 9E . 91.Pp 92The 93.Fa mgi_stop 94member is an optional entry point. 95If the driver needs to take a specific action when the group is being 96stopped, then it should set this to a function. 97For more information, see 98.Xr mgi_stop 9E . 99.Pp 100The 101.Fa mgi_count 102member should be set to a count of the number of rings that are present 103in this group. 104When the group type is 105.Dv MAC_GROUP_TYPE_STATIC , 106then the value in 107.Fa mgi_count 108represents the fixed number of rings available to the group. 109.Pp 110The 111.Fa mgi_addmac 112member is an optional entry point and should be set to a function that 113can add a MAC address filter to the group in hardware. 114For more information, see 115.Xr mgi_addmac 9E . 116This member only has meaning for a receive group, transmit groups should 117set this to 118.Dv NULL . 119.Pp 120The 121.Fa mgi_remmac 122member is an optional entry point and should be set to a function that 123can remove a MAC address filter from a group in hardware. 124If the 125.Fa mgi_addmac 126member is a valid pointer, then this entry point must be as well. 127For more information, see 128.Xr mgi_remmac 9E . 129This member only has meaning for a receive group, transmit groups should 130set this to 131.Dv NULL . 132.Pp 133The 134.Fa mgi_addvlan 135member is an optional entry point and should be set to a function that 136can add a VLAN filter to the group in hardware. 137For more information, see 138.Xr mgi_addvlan 9E . 139This member only has meaning for a receive group, transmit groups should 140set this to 141.Dv NULL . 142.Pp 143The 144.Fa mgi_remvlan 145member is an optional entry point and should be set to a function that 146can remove a VLAN filter from a group in hardware. 147If the 148.Fa mgi_addvlan 149member is a valid pointer, then this entry point must be as well. 150For more information, see 151.Xr mgi_remvlan 9E . 152This member only has meaning for a receive group, transmit groups should 153set this to 154.Dv NULL . 155.Ss Required Members 156All of the non-function pointers described in this manual are required 157members for both transmit and receive groups. 158The 159.Fa mgi_start 160and 161.Fa mgi_stop 162members are optional for both transmit and receive groups. 163.Pp 164For transmit groups, all of the filter entry points must be set to 165.Dv NULL . 166.Pp 167Receive groups must have some way to set a MAC address filter. 168This means that one of the MAC address related functions must be set. 169Currently, the driver must implement either 170.Fa mgi_addmac 171and 172.Fa mgi_remmac . 173.Sh SEE ALSO 174.Xr mac 9E , 175.Xr mac_capab_rings 9E , 176.Xr mgi_addmac 9E , 177.Xr mgi_addvlan 9E , 178.Xr mgi_remmac 9E , 179.Xr mgi_remvlan 9E , 180.Xr mgi_start 9E , 181.Xr mgi_stop 9E , 182.Xr mr_gget 9E 183