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