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.\" 14.Dd Feb 21, 2017 15.Dt MAC_CAPAB_LED 9E 16.Os 17.Sh NAME 18.Nm mac_capab_led , 19.Nm mcl_set 20.Nd MAC LED capability 21.Sh SYNOPSIS 22.In sys/mac_provider.h 23.Vt typedef struct mac_capab_led mac_capab_led_t; 24.Vt typedef enum mac_led_mode mac_led_mode_t; 25.Ft int 26.Fo mcl_set 27.Fa "void *driver" 28.Fa "mac_led_mode_t mode" 29.Fa "uint_t flags" 30.Fc 31.Sh INTERFACE LEVEL 32.Sy Evolving - 33This interface is still evolving. 34API and ABI stability is not guaranteed. 35.Sh PARAMETERS 36.Bl -tag -width Fa 37.It Fa driver 38A pointer to the driver's private data that was passed in via the 39.Sy m_pdata 40member of the 41.Xr mac_register 9S 42structure to the 43.Xr mac_register 9F 44function. 45.It Fa mode 46A value that indicates how the driver should drive the LEDs. 47See the 48.Sx LED MODES 49section for a list of supported modes. 50.It Fa flags 51Reserved for future use. 52.El 53.Sh DESCRIPTION 54The 55.Sy MAC_CAPAB_LED 56capability allows GLDv3 device drivers to expose an interface for 57controlling the LEDs on the device. 58This allows the system to control the LEDs to assist system 59administrators in finding and identifying specific physical devices in 60the system. 61.Pp 62Implementing this capability is optional. 63For more information on how to handle capabilities and how to indicate 64that a capability is not supported, see 65.Xr mc_getcapab 9E . 66.Pp 67This capability should be implemented if the device in question provides 68a way to manipulate its LEDs. 69Generally the LEDs on a device default to indicating link status and 70activity. 71However, they can often be turned off or set to a specific pattern for 72identification purposes. 73.Ss LED MODES 74The system has a notion of different LED modes. 75Each LED mode suggests a different way that a device driver should drive 76the indicator LEDs on the device. 77While we generally want all such LED modes to be as uniform 78as possible, there is a limit to such similarities due to the 79capabilities of NICs. 80Each mode is a member of the 81.Vt mac_led_mode_t 82enumeration. 83The currently defined modes are: 84.Bl -tag -width Dv -offset indent 85.It Dv MAC_LED_DEFAULT 86This mode indicates that the device's default behavior should be used. 87This is usually some form of link status and activity. 88It is device specific and usually is the default behavior after a device 89is powered on. 90.It Dv MAC_LED_OFF 91This mode indicates that the device's LEDs should be turned off and not 92emit any light. 93.It Dv MAC_LED_ON 94This mode indicates that the device's LEDs should be turned on and 95remain solid. 96.It Dv MAC_LED_IDENT 97This mode indicates that the driver should emit some form of 98identification pattern. 99We suggest that devices indicate some form of solid blinking light that 100is on and off at alternating units of time, for example, every 200 101milliseconds. 102If it is possible to use an alternate color from the normal link up and 103activity lighting, that is recommended. 104.El 105.Ss MAC Capability Structure 106When the device driver's 107.Xr mc_getcapab 9E 108function entry point is called with the capability set to 109.Dv MAC_CAPAB_LED , 110then the value of the capability structure is the following structure: 111.Bd -literal -offset indent 112typedef struct mac_capab_led { 113 uint_t mcl_flags; 114 mac_led_mode_t mcl_modes; 115 int (*mcl_set)(void *driver, mac_led_mode_t mode, 116 uint_t flags); 117} mac_capab_led_t; 118.Ed 119.Pp 120If the driver supports the 121.Dv MAC_CAPAB_LED 122capability, it should fill in this structure, based on the following 123rules: 124.Bl -tag -width Vt 125.It Fa mcl_flags 126The 127.Fa mcl_flags 128member is used to negotiate extensions with the driver. 129MAC will set the value of 130.Fa mcl_flags 131to include all of the currently known extensions. 132The driver should intersect this list with the set that they actually 133support. 134At this time, no such features are defined and the driver should set the 135member to 136.Sy 0 . 137.It Fa mcl_modes 138The 139.Fa mcl_modes 140member represents the support modes of the device driver. 141The device driver should set 142.Vt mcl_modes 143to the bitwise-inclusive-OR of the LED modes listed in 144.Sx LED MODES . 145.Pp 146If the driver does not support anything other than the default behavior 147of 148.Dv MAC_LED_DEFAULT , 149then the device driver should not indicate that it supports this 150capability. 151.It Fa mcl_set 152The 153.Fa mcl_set 154entry point will be called by the MAC framework when it needs the device 155driver to change how it is driving its LEDs. 156Each call will ask the driver to change the display mode to the 157specified mode. 158The driver does not have to multiplex requests for multiple modes or 159keep track of what has been requested, that is taken care of by the 160system itself. 161.Pp 162The driver should first validate that 163.Fa mode 164is a mode that it supports. 165While the device reports the set of supported modes as a 166bitwise-inclusive-OR, the driver should only receive a single value in 167.Fa mode . 168The value of the 169.Fa flags 170argument is reserved for future use. 171Drivers must check that the value of flags is zero and if not, return 172.Er EINVAL . 173.Pp 174When this entry point is first called on a driver, it should snapshot 175its device registers such that it knows how to restore the default 176behavior. 177Because each method of programming the LEDs is different, it 178is up to the driver itself to take care of this, the broader framework 179cannot take care of it. 180.Pp 181If for some reason the driver is asked to program the same mode that it 182is already driving, then it need not do anything and should simply 183return success. 184.Pp 185Once the driver successfully changes the LED driving mode, it should 186return 187.Sy 0 . 188Otherwise, it should return the appropriate error number. 189For a full list of error numbers, see 190.Xr Intro 2 . 191Common values are: 192.Bl -tag -width Er -offset width 193.It Er EINVAL 194.Fa flag 195contains an unknown value. 196.It Er ENOTSUP 197.Fa mode 198is unsupported. 199.Fa flags 200contains an unsupported or unknown value. 201.It Er EIO 202An I/O error occurred while trying to program the device's registers. 203This could be because a command timed out or an FM-aware driver 204encountered an error. 205.El 206.Pp 207The broader framework will guarantee that only a single call to the 208.Fa mcl_set 209function is ongoing at any time. 210If other parts of the driver refer to the data used by the 211.Fa mcl_set 212function, then the driver must ensure that it is performing sufficient 213locking of its data. 214.El 215.Sh CONTEXT 216The 217.Ft mcl_set 218entry point will only be called from 219.Sy user 220or 221.Sy kernel 222context. 223It will never be called from interrupt context. 224.Sh SEE ALSO 225.Xr Intro 2 , 226.Xr mac 9E , 227.Xr mc_getcapab 9E , 228.Xr mac_register 9F 229