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