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 MR_GGET 9E 17.Os 18.Sh NAME 19.Nm mr_gget 20.Nd fill MAC group information 21.Sh SYNOPSIS 22.In sys/mac_provider.h 23.Ft void 24.Fo prefix_fill_group_info 25.Fa "void *driver" 26.Fa "mac_ring_type_t rtype" 27.Fa "const int group_index" 28.Fa "mac_group_info_t *infop" 29.Fa "mac_group_handle_t gh" 30.Fc 31.Sh INTERFACE LEVEL 32.Sy Uncommitted - 33This interface is still evolving. 34API and ABI stability is not guaranteed. 35.Sh PARAMETERS 36.Bl -tag -width Fa 37.It Fa driver 38A pointer to the driver's private data that was passed in via the 39.Fa m_pdata 40member of the 41.Xr mac_register 9S 42structure to the 43.Xr mac_register 9F 44function. 45.It Fa rtype 46A value indicating the type of ring that makes up the groups. 47Valid values include: 48.Bl -tag -width Dv 49.It Dv MAC_RING_TYPE_RX 50The group is intended for use with receive rings. 51.It Dv MAC_RING_TYPE_TX 52The group is intended for use with transmit rings. 53.El 54.It Fa group_index 55An integer value that uniquely identifying the group. 56Groups are numbered starting from zero. 57.It Fa infop 58A pointer to an instance of a 59.Xr mac_group_info 9S 60structure. 61.It Fa gh 62An opaque pointer to a group handle that can be used to identify this 63group. 64.El 65.Sh DESCRIPTION 66The 67.Fn mr_gget 68entry point provides a means for the device driver to fill in 69information about a group. 70The driver returns information about the group to the MAC framework via 71the 72.Fa infop 73argument. 74For the list of fields and an explanation of how to fill them in, please 75see 76.Xr mac_group_info 9S . 77.Pp 78The 79.Fa rtype 80argument describes whether this is a group of receive rings or a group 81of transmit rings. 82This is identified by the value in 83.Fa rtype 84which will be 85.Dv MAC_RING_TYPE_RX 86for a receive group 87and 88.Dv MAC_RING_TYPE_TX 89for a transmit group. 90It is recommended that a driver doule check that the 91.Fa rtype 92matches what it expects if it uses separate entry points for receive and 93transmit groups. 94The group information that is filled in varies between transmit and 95receive groups. 96If separate entry points were not specified in the 97.Xr mac_capab_rings 9E 98structure, then the driver must ensure that it checks this value and 99acts appropriately. 100.Pp 101The 102.Fa group_index 103argument is used to uniquely identify a group. 104Groups are numbered starting at zero and end at one less then the number 105of groups specified in 106.Fa mr_gnum 107member of the 108.Vt mac_capbab_rings_t 109structure which is described in 110.Xr mac_capab_rings 9E . 111Group IDs can be represented as the mathematical range [0, mr_gnum). 112.Pp 113After filling in the group information in 114.Fa infop , 115the driver should make sure to store the group handle 116.Fa gh 117for future use, mapping it to the index 118.Fa group_index . 119.Sh CONTEXT 120The 121.Fn mr_gget 122entry point will be called in response to a driver calling the 123.Xr mac_register 9F 124function and the driver has acknowledged that it supports the 125.Dv MAC_CAPAB_RINGS 126capability. 127.Sh SEE ALSO 128.Xr mac 9E , 129.Xr mac_capab_rings 9E , 130.Xr mac_register 9F , 131.Xr mac_group_info 9S , 132.Xr mac_register 9S 133