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 Compuer Company 14.\" Copyright 2023 Peter Tribble 15.\" 16.Dd July 17, 2023 17.Dt MR_RGET 9E 18.Os 19.Sh NAME 20.Nm mr_rget 21.Nd fill in ring information 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Ft void 25.Fo prefix_fill_ring_info 26.Fa "void *driver" 27.Fa "mac_ring_type_t rtype" 28.Fa "const int group_index" 29.Fa "const int ring_index" 30.Fa "mac_ring_info_t *infop" 31.Fa "mac_ring_handle_t rh" 32.Fc 33.Sh INTERFACE LEVEL 34.Sy Uncommitted - 35This interface is still evolving. 36API and ABI stability is not guaranteed. 37.Sh PARAMETERS 38.Bl -tag -width Fa 39.It Fa driver 40A pointer to the driver's private data that was passed in via the 41.Fa m_pdata 42member of the 43.Xr mac_register 9S 44structure to the 45.Xr mac_register 9F 46function. 47.It Fa group_index 48An integer value indicating the group that this ring belongs to. 49Groups are numbered starting from zero. 50.It Fa rtype 51A value indicating the type of ring. 52Valid values include: 53.Bl -tag -width Dv 54.It Dv MAC_RING_TYPE_RX 55The ring is a receive ring. 56.It Dv MAC_RING_TYPE_TX 57The ring is a transmit ring. 58.El 59.It Fa ring_index 60An integer indicating the index of the ring inside of the group. 61Ring indexes are numbered starting from zero. 62Each group has its own set of ring indexes. 63.It Fa infop 64A pointer to an instance of a 65.Xr mac_ring_info 9S 66structure. 67.It Fa rh 68An opaque pointer to a ring handle that can be used to identify this 69ring. 70.El 71.Sh DESCRIPTION 72The 73.Fn mr_rget 74entry point provides a means for the device driver to fill in 75information about a ring. 76The driver must fill in information into the 77.Fa infop 78argument. 79For the list of fields and an explanation of how to fill them in, please 80see 81.Xr mac_ring_info 9S . 82.Pp 83The 84.Fa rtype 85argument describes whether this is a receive ring or transmit ring 86identified by a value of 87.Dv MAC_RING_TYPE_RX 88or 89.Dv MAC_RING_TYPE_TX 90respectively. 91The ring information that is filled in varies between transmit and 92receive rings. 93If separate entry points were not specified in the 94.Xr mac_capab_rings 9E 95structure, then the driver 96must ensure that it checks this value. 97.Pp 98The 99.Fa group_index 100and 101.Fa ring_index 102arguments are used to uniquely identify a ring. 103The number of groups that a driver supports is based on the values 104present in the 105.Fa mr_gnum 106member of the 107.Vt mac_capab_rings_t 108structure which is described in 109.Xr mac_capab_rings 9E . 110The group index ranges from zero to the specified number of groups minus 111one. 112The number of rings in the group is determined based on the values 113specified in 114.Xr mac_group_info 9S 115structure that is filled in during the 116.Xr mr_gget 9E 117entry point. 118The ring numbering for each group is independent and always starts at 119zero. 120Based on the combination of group and ring index, the driver should be 121able to map that to a unique ring. 122.Pp 123After filling out the ring structure in 124.Fa infop , 125the driver should make sure to store the ring handle in 126.Fa rh 127for future use. 128This is required for callbacks such as 129.Xr mac_rx_ring 9F 130or 131.Xr mac_tx_ring_update 9F . 132.Sh CONTEXT 133The 134.Fn mr_rget 135entry point will be called in response to a driver calling the 136.Xr mac_register 9F 137function and the driver has acknowledged that it supports the 138.Dv MAC_CAPAB_RINGS 139capability. 140This will be called after a call to the driver's 141.Xr mr_gget 9E 142entry point. 143.Sh SEE ALSO 144.Xr mac 9E , 145.Xr mac_capab_rings 9E , 146.Xr mr_gget 9E , 147.Xr mac_register 9F , 148.Xr mac_rx_ring 9F , 149.Xr mac_tx_ring_update 9F , 150.Xr mac_group_info 9S , 151.Xr mac_register 9S , 152.Xr mac_ring_info 9S 153