xref: /titanic_51/usr/src/man/man9e/mac_capab_led.9e (revision 64ea02015ea759144aede2b10c2c063d8fd3ff39)
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