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 MI_ENABLE 9E 17.Os 18.Sh NAME 19.Nm mi_enable , 20.Nm mi_disable 21.Nd MAC interrupt enable and disable entry points 22.Sh SYNOPSIS 23.In sys/mac_provider.h 24.Ft int 25.Fo prefix_intr_enable 26.Fa "mac_intr_handle_t driver" 27.Fc 28.Ft int 29.Fo prefix_intr_disable 30.Fa "mac_intr_handle_t driver" 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 mac interrupt's private data that was passed in via the 40.Vt mi_handle 41member of the 42.Xr mac_intr 9S 43structure. 44.El 45.Sh DESCRIPTION 46The 47.Fn mi_enable 48and 49.Fn mi_disable 50entry points are used by the MAC framework when it wishes to disable the 51generation of interrupts for the ring and poll on the it through the 52.Xr mri_poll 9E 53entry point. 54.Pp 55These entry points should enable and disable the generation of the 56interrupt for the ring that is represented by 57.Fa driver . 58The 59.Fa driver 60argument corresponds to what the driver set in the 61.Fa mri_intr 62member while filling out the 63.Xr mac_ring_info 9S 64structure and generally is used to point to a specific ring. 65.Pp 66Importantly, this entry point is not asking to enable and disable the 67underlying device-level interrupt such as a PCIe MSI or MSI-X, which may 68be being used by multiple rings. 69Drivers must not implement this in terms of the DDI interrupt functions 70such as 71.Xr ddi_intr_enable 9F 72and 73.Xr ddi_intr_disable 9F . 74.Pp 75Instead this should be implemented through device specific means such as 76writing to registers or sending control messages to enable or disable 77the generation of interrupts for the specified ring. 78.Pp 79When manipulating the device's control of interrupts, the driver should 80be careful to serialize these changes with the ongoing processing of 81interrupts through the interrupt handler and the 82.Xr mri_poll 9E 83entry point. 84These should all be protected by the same mutex which is scoped to the 85ring itself when the ability to turn on and off interrupt generation may 86be manipulated on a per-ring basis. 87Failure to properly synchronize this may lead to the driver mistakenly 88delivering the same packet twice through both its interrupt handler and 89its 90.Xr mri_poll 9E 91entry point. 92.Sh RETURN VALUES 93Upon successful completion, the 94.Fn mi_enable 95and 96.Fn mi_disable 97entry points should return 98.Sy 0 . 99Otherwise the appropriate error number should be returned. 100.Sh SEE ALSO 101.Xr mac 9E , 102.Xr mac_capab_rings 9E , 103.Xr mri_poll 9E , 104.Xr ddi_intr_disable 9F , 105.Xr ddi_intr_enable 9F , 106.Xr mac_intr 9S , 107.Xr mac_ring_info 9S 108