Print this page
12309 errors in section 9e of the manual
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man9e/ddi_ufm.9e.man.txt
+++ new/usr/src/man/man9e/ddi_ufm.9e.man.txt
1 1 DDI_UFM(9E) Driver Entry Points DDI_UFM(9E)
2 2
3 3 NAME
4 4 ddi_ufm, ddi_ufm_op_nimages, ddi_ufm_op_fill_image, ddi_ufm_op_fill_slot,
5 5 ddi_ufm_op_getcaps - DDI upgradable firmware module entry points
6 6
7 7 SYNOPSIS
8 8 typedef struct ddi_ufm_handle ddi_ufm_handle_t
9 9 typedef struct ddi_ufm_ops ddi_ufm_ops_t
10 10
11 11 #include <sys/ddi_ufm.h>
12 12
13 13 int
14 14 ddi_ufm_op_getcaps(ddi_ufm_handle_t *uhp, void *drv_arg,
15 15 ddi_ufm_cap_t *caps);
16 16
17 17 int
18 18 ddi_ufm_op_nimages(ddi_ufm_handle_t *uhp, void *drv_arg, uint_t *nimgp);
19 19
20 20 int
21 21 ddi_ufm_op_fill_image(ddi_ufm_handle_t *uhp, void *drv_arg, uint_t imgid,
22 22 ddi_ufm_image_t *uip);
23 23
24 24 int
25 25 ddi_ufm_op_fill_slot(ddi_ufm_handle_t *uhp, void *drv_arg, uint_t imgid,
26 26 uint_t slotid, ddi_ufm_slot_t *usp);
27 27
28 28 INTERFACE LEVEL
29 29 Evolving - This interface is evolving still in illumos. API and ABI
30 30 stability is not guaranteed.
31 31
32 32 PARAMETERS
33 33 uhp A handle corresponding to the device's UFM handle. This is
34 34 the same value as returned in ddi_ufm_init(9F).
35 35
36 36 drv_arg This is a private value that the driver passed in when
37 37 calling ddi_ufm_init(9F).
38 38
39 39 nimgp A pointer that the driver should set with a number of
40 40 images.
41 41
42 42 nslotp A pointer that the driver should set with a number of
43 43 slots.
44 44
45 45 imgid An integer indicating which image information is being
46 46 requested for.
47 47
48 48 uip An opaque pointer that represents a UFM image.
49 49
50 50 slotid An integer indicating which slot information is being
51 51 requested for.
52 52
53 53 usp An opaque pointer that represents a UFM slot.
54 54
55 55 DESCRIPTION
56 56 Upgradable firmware modules (UFM) are a potential component of many
57 57 devices. These interfaces aim to provide a simple series of callbacks
58 58 for a device driver to implement such that it is easy to report
59 59 information and in the future, manipulate firmware modules.
60 60
61 61 UFM Background
62 62 UFMs may come in different flavors and styles ranging from a firmware
63 63 blob, to an EEPROM image, to microcode, and more. Take for example a
64 64 hard drive. While it is a field replaceable unit (FRU), it also contains
65 65 some amount of firmware that manages the drive which can be updated
66 66 independently of replacing the drive.
67 67
68 68 The motherboard often has a UFM in the form of the BIOS or UEFI. The
69 69 Lights out management controller on a system has a UFM, which is usually
70 70 the entire system image. CPUs also have a UFM in the form of microcode.
71 71
72 72 An important property of a UFM is that it is a property of the device
73 73 itself. For example, many WiFi device drivers are required to send a
74 74 binary blob of firmware to the device after every reset. Because these
75 75 images are not properties of the device and must be upgraded by either
76 76 changing the device driver or related system files, we do not consider
77 77 these UFMs.
78 78
79 79 There are also devices that have firmware which is a property of the
80 80 device, but may not be upgradable from the running OS. This may be
81 81 because the vendor doesn't have tooling to upgrade the image or because
82 82 the firmware image itself cannot be upgraded in the field at all. For
83 83 example, a YubiKey has a firmware image that's burned into it in the
84 84 factory, but there is no way to change the firmware on it short of
85 85 replacing the device in its entirety. However, because these images are
86 86 a permanent part of the device, we also consider them a UFM.
87 87
88 88 Images and Slots
89 89 A device that supports UFMs is made up of one or more distinct firmware
90 90 images. Each image has its own unique purpose. For example, a
91 91 motherboard may have both a BIOS and a CPLD image, each of which has
92 92 independent firmware revisions.
93 93
94 94 A given image may have a number of slots. A slot represents a particular
95 95 version of the image. Only one slot can be active at a given time.
96 96 Devices support slots such that a firmware image can be downloaded to the
97 97 device without impacting the current device if it fails half-way through.
98 98 The slot that's currently in use is referred to as the active slot.
99 99
100 100 The various entry points are designed such that all a driver has to do is
101 101 provide information about the image and its slots to the kernel, it does
102 102 not have to wrangle with how that is marshalled to users and the
103 103 appearance of those structures.
104 104
105 105 Registering with the UFM Subsystem
106 106 During a device driver's attach(9E) entry point, a device driver should
107 107 register with the UFM subsystem by filling out a UFM operations vector
108 108 and then calling ddi_ufm_init(9F). The driver may pass in a value,
109 109 usually a pointer to its soft state pointer, which it will then receive
110 110 when its subsequent entry points are called.
111 111
112 112 Once the driver has finished initializing, it must call
113 113 ddi_ufm_update(9F) to indicate that the driver is in a state where it's
114 114 ready to receive calls to the entry points.
115 115
116 116 The various UFM entry points may be called from an arbitrary kernel
117 117 context. However, they will only ever be called from a single thread at
118 118 a given time.
119 119
120 120 UFM operations vector
121 121 The UFM operations vector is a structure that has the following members:
122 122
123 123 typedef struct ddi_ufm_ops {
124 124 int (*ddi_ufm_op_nimages)(ddi_ufm_handle_t *uhp, void *arg,
125 125 uint_t *nimgp);
126 126 int (*ddi_ufm_op_fill_image)(ddi_ufm_handle_t *uhp, void *arg,
127 127 uint_t imgid, ddi_ufm_image_t *img);
128 128 int (*ddi_ufm_op_fill_slot)(ddi_ufm_handle_t *uhp, void *arg,
129 129 int imgid, ddi_ufm_image_t *img, uint_t slotid,
130 130 ddi_ufm_slot_t *slotp);
131 131 int (*ddi_ufm_op_getcaps)(ddi_ufm_handle_t *uhp, void *arg,
132 132 ddi_ufm_cap_t *caps);
133 133 } ddi_ufm_ops_t;
134 134
135 135 The ddi_ufm_op_nimages() entry point is optional. If a device only has a
136 136 single image, then there is no reason to implement the
137 137 ddi_ufm_op_nimages(entry, point.) The system will assume that there is
138 138 only a single image.
139 139
140 140 Slots and images are numbered starting at zero. If a driver indicates
141 141 support for multiple images or slots then the images or slots will be
142 142 numbered sequentially going from 0 to the number of images or slots minus
143 143 one. These values will be passed to the various entry points to indicate
144 144 which image and slot the system is interested in. It is up to the driver
145 145 to maintain a consistent view of the images and slots for a given UFM.
146 146
147 147 The members of this structure should be filled in the following ways:
148 148
149 149 ddi_ufm_op_nimages()
150 150 The ddi_ufm_op_nimages() entry point is an optional
151 151 entry point that answers the question of how many
152 152 different, distinct firmware images are present on the
153 153 device. Once the driver determines how many are
154 154 present, it should set the value in nimgp to the
155 155 determined value.
156 156
157 157 It is legal for a device to pass in zero for this
158 158 value, which indicates that there are none present.
159 159
160 160 Upon successful completion, the driver should return 0.
161 161 Otherwise, the driver should return the appropriate
162 162 error number. For a full list of error numbers, see
163 163 Intro(2). Common values are:
164 164
165 165 EIO An error occurred while
166 166 communicating with the device
167 167 to determine the number of
168 168 firmware images.
169 169
170 170 ddi_ufm_op_fill_image()
171 171 The ddi_ufm_op_fill_image() entry point is used to fill
172 172 in information about a given image. The value in imgid
173 173 is used to indicate which image the system is asking to
174 174 fill information about. If the driver does not
175 175 recognize the image ID in imgid then it should return
176 176 an error.
177 177
178 178 The ddi_ufm_image_t structure passed in uip is opaque.
179 179 To fill in information about the image, the driver
180 180 should call the functions described in
181 181 ddi_ufm_image(9F).
182 182
183 183 The driver should call the ddi_ufm_image_set_desc(9F)
184 184 function to set a description of the image which
185 185 indicates its purpose. This should be a human-readable
186 186 string. The driver may also set any ancillary data
187 187 that it deems may be useful with the
188 188 ddi_ufm_image_set_misc(9F) function. This function
189 189 takes an nvlist, allowing the driver to set arbitrary
190 190 keys and values.
191 191
192 192 Once the driver has finished setting all of the
193 193 information about the image then the driver should
194 194 return 0. Otherwise, the driver should return the
195 195 appropriate error number. For a full list of error
196 196 numbers, see Intro(2). Common values are:
197 197
198 198 EINVAL The image indicated by imgid is
199 199 unknown.
200 200
201 201 EIO An error occurred talking to
202 202 the device while trying to fill
203 203 out firmware image information.
204 204
205 205 ENOMEM The driver was unable to
206 206 allocate memory while filling
207 207 out image information.
208 208
209 209 ddi_ufm_op_fill_slot()
210 210 The ddi_ufm_op_fill_slot() function is used to fill in
211 211 information about a specific slot for a specific image.
212 212 The value in imgid indicates the image the system wants
213 213 slot information for and the value in slotid indicates
214 214 which slot of that image the system is interested in.
215 215 If the device driver does not recognize the value in
216 216 either or imgid or slotid, then it should return an
217 217 error.
218 218
219 219 The ddi_ufm_slot_t structure passed in usp is opaque.
220 220 To fill in information about the image the driver
221 221 should call the functions described in
222 222 ddi_ufm_slot(9F).
223 223
224 224 The driver should call the ddi_ufm_slot_set_version(9F)
225 225 function to indicate the version of the UFM. The
226 226 version is a device-specific character string. It
227 227 should contain the current version of the UFM as a
228 228 human can understand it and it should try to match the
229 229 format used by device vendor.
230 230
231 231 The ddi_ufm_slot_set_attrs(9F) function should be used
232 232 to set the attributes of the UFM slot. These
233 233 attributes include the following enumeration values:
234 234
235 235 DDI_UFM_ATTR_READABLE
236 236 This attribute indicates that the
237 237 firmware image in the specified slot may
238 238 be read, even if the device driver does
239 239 not currently support such functionality.
240 240
241 241 DDI_UFM_ATTR_WRITEABLE
242 242 This attributes indicates that the
243 243 firmware image in the specified slot may
244 244 be updated, even if the driver does not
245 245 currently support such functionality.
246 246
247 247 DDI_UFM_ATTR_ACTIVE
248 248 This attributes indicates that the
249 249 firmware image in the specified slot is
250 250 the active (i.e. currently running)
251 251 firmware. Only one slot should be marked
252 252 active.
253 253
254 254 DDI_UFM_ATTR_EMPTY
255 255 This attributes indicates that the
256 256 specified slot does not currently contain
257 257 any firmware image.
258 258
259 259 Finally, if there are any device-specific key-value
260 260 pairs that form useful, ancillary data, then the driver
261 261 should assemble an nvlist and pass it to the
262 262 ddi_ufm_set_misc(9F) function.
263 263
264 264 Once the driver has finished setting all of the
265 265 information about the slot then the driver should
266 266 return 0. Otherwise, the driver should return the
267 267 appropriate error number. For a full list of error
268 268 numbers, see Intro(2). Common values are:
269 269
270 270 EINVAL The image or slot indicated by
271 271 imgid and slotid is unknown.
272 272
273 273 EIO An error occurred talking to
274 274 the device while trying to fill
275 275 out firmware slot information.
276 276
277 277 ENOMEM The driver was unable to
278 278 allocate memory while filling
279 279 out slot information.
280 280
281 281 ddi_ufm_op_getcaps()
282 282 The ddi_ufm_op_getcaps() function is used to indicate
283 283 which DDI UFM capabilities are supported by this driver
284 284 instance. Currently there is only a single capability
285 285 (DDI_UFM_CAP_REPORT) which indicates that the driver is
286 286 capable of reporting UFM information for this instance.
287 287 Future UFM versions may add additional capabilities
288 288 such as the ability to obtain a raw dump of the
289 289 firmware image or to upgrade the firmware.
290 290
|
↓ open down ↓ |
290 lines elided |
↑ open up ↑ |
291 291 The driver should indicate the supported capabilities
292 292 by setting the value in the caps parameter. Once the
293 293 driver has populated caps with an appropriate value,
294 294 then the driver should return 0. Otherwise, the driver
295 295 should return the appropriate error number. For a full
296 296 list of error numbers, see Intro(2). Common values
297 297 are:
298 298
299 299 EIO An error occurred talking to
300 300 the device while trying to
301 - discover firmware capabilties.
301 + discover firmware capabilities.
302 302
303 303 ENOMEM The driver was unable to
304 304 allocate memory.
305 305
306 306 Caching and Updates
307 307 The system will fetch firmware and slot information on an as-needed
308 308 basis. Once it obtains some information, it may end up caching this
309 309 information on behalf of the driver. Whenever the driver believes that
310 310 something could have changed -- it need know that it has -- then the
311 311 driver must call ddi_ufm_update(9F).
312 312
313 313 Locking
314 314 All UFM operations on a single UFM handle will always be run serially.
315 315 However, the device driver may still need to apply adequate locking to
316 316 its structure members as other may be accessing the same data structure
317 317 or trying to communicate with the device.
318 318
319 319 Unregistering from the UFM subsystem
320 320 When a device driver is detached, it should unregister from the UFM
321 321 subsystem. To do so, the driver should call ddi_ufm_fini(9F). By the
322 322 time this function returns, the driver is guaranteed that no UFM entry
323 323 points will be called. However, if there are outstanding UFM related
324 324 activity, the function will block until it is terminated.
325 325
326 326 ioctl Interface
327 327 Userland consumers can access UFM information via a set of ioctls that
328 328 are implemented by the ufm(7D) driver.
329 329
330 330 CONTEXT
|
↓ open down ↓ |
19 lines elided |
↑ open up ↑ |
331 331 The various UFM entry points that a device driver must implement will
332 332 always be called from kernel context.
333 333
334 334 SEE ALSO
335 335 Intro(2), ufd(7D), attach(9E), ddi_ufm_fini(9F), ddi_ufm_image(9F),
336 336 ddi_ufm_image_set_desc(9F), ddi_ufm_image_set_misc(9F),
337 337 ddi_ufm_image_set_nslots(9F), ddi_ufm_init(9F), ddi_ufm_slot(9F),
338 338 ddi_ufm_slot_set_attrs(9F), ddi_ufm_slot_set_misc(9F),
339 339 ddi_ufm_slot_set_version(9F), ddi_ufm_update(9F)
340 340
341 -illumos April 30, 2019 illumos
341 +illumos February 15, 2020 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX