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_RING_INFO 9S 17.Os 18.Sh NAME 19.Nm mac_ring_info , 20.Nm mac_ring_info_t 21.Nd MAC ring information structure 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Sh INTERFACE STABILITY 25.Sy Uncommitted - 26This interface is still evolving. 27API and ABI stability is not guaranteed. 28.Sh DESCRIPTION 29The 30.Vt mac_ring_info_t 31structure is used by the MAC framework as part of the 32.Dv MAC_CAPAB_RINGS 33capability. 34For more 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 structure as described in 44.Xr mac_capab_rings 9E , 45it indicates that it supports a number of rings for transmitting and 46receiving. 47For each ring that it supports, the driver's 48.Xr mr_rget 9E 49entry point will be called, during which it will have to fill out the 50.Vt mac_ring_info_t 51structure defined here. 52.Sh TYPES 53The following types define the function pointers in use in the 54.Vt mac_ring_info_t 55structure. 56.Bd -literal -offset indent 57typedef int (*mac_ring_start_t)(mac_ring_driver_t, uint64_t); 58typedef void (*mac_ring_stop_t)(mac_ring_driver_t); 59 60typedef mblk_t *(*mac_ring_send_t)(mac_ring_driver_t, mblk_t *); 61typedef mblk_t *(*mac_ring_poll_t)(mac_ring_driver_t, int); 62 63typedef int (*mac_ring_stat_t)(mac_ring_driver_t, uint_t, uint64_t *); 64.Ed 65.Sh STRUCTURE MEMBERS 66.Bd -literal -offset indent 67mac_ring_driver_t mri_driver; 68mac_ring_start_t mri_start; 69mac_ring_stop_t mri_stop; 70mac_intr_t mri_intr; 71mac_ring_send_t mri_tx; 72mac_ring_poll_t mri_poll; 73mac_ring_stat_t mri_stat; 74.Ed 75.Pp 76The 77.Fa mri_driver 78member should be set to a driver-specific value that represents the data 79structure that corresponds to the ring. 80The driver will receive this value in all of the callback functions that 81are defined in this structure and discussed below. 82.Pp 83The 84.Fa mri_start 85member is a required entry point that is used to start the ring. 86While the device driver may not need to do any work with hardware to 87start the use of the ring, it must record the ring's generation number. 88For more information, see 89.Xr mri_start 9E . 90.Pp 91The 92.Fa mri_stop 93member is an optional entry point that will be called when the ring is 94being stopped. 95For more information, see 96.Xr mri_stop 9E . 97.Pp 98The 99.Fa mri_intr 100member contains information about the interrupt associated with the 101ring. 102For more information on filling it out, see 103.Xr mac_intr 9S . 104.Pp 105The 106.Fa mri_tx 107member should only be set on transmit rings. 108It must not be set on receive rings. 109The 110.Fa mri_tx 111member should be set to a function that will transmit a given frame on 112the specified ring. 113For more information, see 114.Xr mri_tx 9E . 115.Pp 116The 117.Fa mri_poll 118member should only be set on receive rings. 119It must not be set on transmit rings. 120The 121.Fa mri_poll 122member should be set to a function which will poll the specified ring. 123For more information, see 124.Xr mri_poll 9E . 125.Pp 126The 127.Fa mri_stat 128member should be set to a function which will retrieve statistics about 129the specified ring. 130For more information, see 131.Xr mri_stat 9E . 132.Ss Required Members 133All non-function members are required. 134The 135.Fa mri_intr 136member must be a properly filled out as per 137.Xr mac_intr 9S . 138.Pp 139For transmit rings, the 140.Fa mri_tx 141member is required. 142.Pp 143For receive rings, the 144.Fa mri_poll 145member is required. 146.Sh SEE ALSO 147.Xr mac 9E , 148.Xr mac_capab_rings 9E , 149.Xr mri_poll 9E , 150.Xr mri_start 9E , 151.Xr mri_stat 9E , 152.Xr mri_stop 9E , 153.Xr mri_tx 9E , 154.Xr mac_intr 9S 155