share/man/man9e/mac_capab_led.9e

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