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.\" Copyright 2023 Peter Tribble 15.\" 16.Dd July 17, 2023 17.Dt MRI_POLL 9E 18.Os 19.Sh NAME 20.Nm mri_poll 21.Nd Poll a ring for received network data 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Ft mblk_t * 25.Fo prefix_ring_poll 26.Fa "void *driver" 27.Fa "int poll_bytes" 28.Fc 29.Sh INTERFACE LEVEL 30.Sy Uncommitted - 31This interface is still evolving. 32API and ABI stability is not guaranteed. 33.Sh PARAMETERS 34.Bl -tag -width Fa 35.It Fa driver 36A pointer to the ring's private data that was passed in via the 37.Fa mri_driver 38member of the 39.Xr mac_ring_info 9S 40structure as part of the 41.Xr mr_rget 9E 42entry point. 43.It Fa poll_bytes 44The maximum number of bytes that the driver should poll in a given call. 45.El 46.Sh DESCRIPTION 47The 48.Fn mri_poll 49entry point is called by the MAC framework when it wishes to have the 50driver check the ring specified by 51.Fa driver 52for available data. 53.Pp 54The device driver should perform the same logic that it would when it's 55processing an interrupt and as described in the 56.Sx Receiving Data 57section of 58.Xr mac 9E . 59The main difference is that instead of calling 60.Xr mac_rx_ring 9F , 61it should instead return that data as a 62.Vt mblk_t 63chain. 64Also, while an interrupt may map to more than one ring in some drivers, 65the driver should only process the ring indicated by 66.Fa driver . 67The MAC framework can be polling some rings that are receiving a lot of 68traffic while still relying on interrupts for others. 69.Pp 70Drivers should exercise caution with the locking between the polling, 71interrupt disabling routines, and the interrupt handler. 72This mutex is generally scoped to a receive ring and is used to 73synchronize the act of transitioning between polling and handling 74interrupts. 75That means that in addition to the 76.Fn mri_poll 77entry point, the 78.Xr mi_enable 9E 79and 80.Xr mi_disable 9E 81entry points should synchronize on the same mutex when transitioning the 82device. 83This is the same mutex that would be used when processing this ring 84during an interrupt handler, though that mutex should only be used while 85processing a specific ring and not held for the duration of the entire 86interrupt handler. 87.Pp 88The driver should limit the number of frames it collects based on the 89size value present in the 90.Fa poll_bytes 91argument. 92The driver should sum up the total size of each processed frame and 93compare that running total to 94.Fa poll_bytes . 95If there are fewer frames than, 96.Fa poll_bytes , 97the driver should not wait and can instead return right away. 98Similarly, if the driver has iterated around its entire descriptor ring 99and still does not have enough enough, it is OK to return early. 100Importantly, the framework is 101.Em not 102asking the driver to block until it has 103.Fa poll_bytes 104available . 105.Sh RETURN VALUES 106Upon successful completion, the device driver should return a message 107block chain of collected frames. 108If no frames are available or it encountered an error while processing 109data, then it should return 110.Dv NULL . 111.Sh SEE ALSO 112.Xr mac 9E , 113.Xr mac_capab_rings 9E , 114.Xr mi_disable 9E , 115.Xr mi_enable 9E , 116.Xr mr_rget 9E , 117.Xr mac_rx_ring 9F , 118.Xr mac_ring_info 9S 119