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 2019 Joyent, Inc. 13.\" Copyright 2021 Oxide Computer Company 14.\" 15.Dd May 19, 2020 16.Dt DDI_UFM 9E 17.Os 18.Sh NAME 19.Nm ddi_ufm , 20.Nm ddi_ufm_op_nimages , 21.Nm ddi_ufm_op_fill_image , 22.Nm ddi_ufm_op_fill_slot , 23.Nm ddi_ufm_op_getcaps 24.Nd DDI upgradable firmware module entry points 25.Sh SYNOPSIS 26.Vt typedef struct ddi_ufm_handle ddi_ufm_handle_t 27.Vt typedef struct ddi_ufm_ops ddi_ufm_ops_t 28.In sys/ddi_ufm.h 29.Ft int 30.Fo ddi_ufm_op_getcaps 31.Fa "ddi_ufm_handle_t *uhp" 32.Fa "void *drv_arg" 33.Fa "ddi_ufm_cap_t *caps" 34.Fc 35.Ft int 36.Fo ddi_ufm_op_nimages 37.Fa "ddi_ufm_handle_t *uhp" 38.Fa "void *drv_arg" 39.Fa "uint_t *nimgp" 40.Fc 41.Ft int 42.Fo ddi_ufm_op_fill_image 43.Fa "ddi_ufm_handle_t *uhp" 44.Fa "void *drv_arg" 45.Fa "uint_t imgno" 46.Fa "ddi_ufm_image_t *imgp" 47.Fc 48.Ft int 49.Fo ddi_ufm_op_fill_slot 50.Fa "ddi_ufm_handle_t *uhp" 51.Fa "void *drv_arg" 52.Fa "uint_t imgno" 53.Fa "uint_t slotno" 54.Fa "ddi_ufm_slot_t *slotp" 55.Fc 56.Ft int 57.Fo ddi_ufm_op_readimg 58.Fa "ddi_ufm_handle_t *uhp" 59.Fa "void *drv_arg" 60.Fa "uint_t imgno" 61.Fa "uint_t slotno" 62.Fa "uint64_t len" 63.Fa "uint64_t offset" 64.Fa "void *buf" 65.Fa "uint64_t *nreadp" 66.Fc 67.Sh INTERFACE LEVEL 68.Sy Evolving - This interface is evolving still in illumos. API and ABI stability is not guaranteed. 69.Sh PARAMETERS 70.Bl -tag -width Fa 71.It Fa uhp 72A handle corresponding to the device's UFM handle. 73This is the same value as returned in 74.Xr ddi_ufm_init 9F . 75.It Fa drv_arg 76This is a private value that the driver passed in when calling 77.Xr ddi_ufm_init 9F . 78.It Fa nimgp 79A pointer that the driver should set with a number of images. 80.It Fa imgno 81An integer indicating which image information is being requested for. 82.It Fa imgp 83An opaque pointer that represents a UFM image. 84.It Fa slotno 85An integer indicating which slot information is being requested for. 86.It Fa slotp 87An opaque pointer that represents a UFM slot. 88.It Fa len 89Indicates the number of bytes from a firmware payload that are desired. 90.It Fa offset 91Indicates an offset in a firmware payload to start reading from. 92.It Fa buf 93A buffer to place raw firmware data from the device into. 94.It Fa nreadp 95A pointer whose value should be updated with the number of bytes 96actually read from the image. 97.El 98.Sh DESCRIPTION 99Upgradable firmware modules (UFM) are a potential component of many 100devices. 101These interfaces aim to provide a simple series of callbacks 102for a device driver to implement such that it is easy to report 103information and in the future, manipulate firmware modules. 104.Ss UFM Background 105UFMs come in different flavors and styles that vary from device to 106device. 107.Qq Firmware 108generally refers to some form of software that runs on a device and is often 109packaged up as a binary payload. 110However, many things that aren't always called 111.Qq firmware , 112such as EEPROM images, CPU microcode, flash based configuration, and more, are 113all just as important here. 114Take for example a hard drive. 115While it is a field replaceable unit (FRU), it also contains some amount 116of firmware that manages the drive which can be updated independently of 117replacing the drive. 118.Pp 119The motherboard often has a UFM in the form of the BIOS or UEFI. 120The Lights Out Management controller on a system has a UFM, which is usually 121the entire system image. 122CPUs also have a UFM in the form of microcode. 123.Pp 124An important property of a UFM is that it is a persistent part of the device 125itself. 126For example, many WiFi device drivers are required to send a binary blob of 127firmware to the device after every reset. 128Because these images are not persistent parts of the device and must be upgraded 129by either changing the device driver or related system files, we do not consider 130these UFMs. 131.Pp 132There are also devices that have firmware which is a part of the 133device, but may not be upgradable from the running OS. 134This may be because the vendor doesn't have tooling to upgrade the image or 135because the firmware image itself cannot be upgraded in the field at all. 136For example, a YubiKey has a firmware image that's burned into it in the 137factory, but there is no way to change the firmware on it short of 138replacing the device in its entirety. 139However, because these images are a permanent and persistent part of the device, 140we also consider them a UFM. 141.Ss Images and Slots 142A device that supports UFMs is made up of one or more distinct firmware 143images. 144Each image has its own unique purpose. 145For example, a motherboard may have both a BIOS and a CPLD image, each of which 146has independent firmware revisions. 147.Pp 148A given image may have a number of slots. 149A slot represents a particular version of the image. 150Only one slot is considered the 151.Em active 152slot. 153It represents the currently running version of the image. 154Devices support multiple slots so that an image can be downloaded to an inactive 155slot without risking damage to the active slot. 156This ensures that a power-loss or failure halfway through writing to a slot 157doesn't leave the device with corrupted firmware. 158.Pp 159The various entry points are designed such that all a driver has to do 160is provide information about the image and its slots to the kernel, it 161does not have to wrangle with how that is marshalled to users and the 162appearance of those structures. 163.Ss Registering with the UFM Subsystem 164During a device driver's 165.Xr attach 9E 166entry point, a device driver should register with the UFM subsystem by 167filling out a UFM operations vector and then calling 168.Xr ddi_ufm_init 9F . 169The driver may pass in a value, usually a pointer to its soft state 170pointer, which it will then receive when its subsequent entry points are 171called. 172.Pp 173Once the driver has finished initializing, it must call 174.Xr ddi_ufm_update 9F 175to indicate that the driver is in a state where it's ready to receive 176calls to the entry points. 177.Pp 178The various UFM entry points may be called from an arbitrary kernel 179context. 180However, they will only ever be called from a single thread at 181a given time. 182.Ss UFM operations vector 183The UFM operations vector is a structure that has the following members: 184.Bd -literal -offset indent 185typedef struct ddi_ufm_ops { 186 int (*ddi_ufm_op_nimages)(ddi_ufm_handle_t *uhp, void *drv_arg, 187 uint_t *nimgp); 188 int (*ddi_ufm_op_fill_image)(ddi_ufm_handle_t *uhp, void *drv_arg, 189 uint_t imgno, ddi_ufm_image_t *imgp); 190 int (*ddi_ufm_op_fill_slot)(ddi_ufm_handle_t *uhp, void *drv_arg, 191 int imgno, ddi_ufm_image_t *img, uint_t slotno, 192 ddi_ufm_slot_t *slotp); 193 int (*ddi_ufm_op_getcaps)(ddi_ufm_handle_t *uhp, void *drv_arg, 194 ddi_ufm_cap_t *caps); 195 int (*ddi_ufm_op_readimg)(ddi_ufm_handle_t *uhp, void *drv_arg, 196 uint_t imgno, uint_t slotno, uint64_t len, uint64_t offset, 197 void *buf, uint64_t *nreadp); 198} ddi_ufm_ops_t; 199.Ed 200.Pp 201The 202.Fn ddi_ufm_op_nimages 203and 204.Fn ddi_ufm_op_readimg 205entry points are optional. 206If a device only has a single image, then there is no requirement to implement 207the 208.Fn ddi_ufm_op_nimages 209entry point and it may be set to 210.Dv NULL . 211The system will assume that there is only a single image. 212.Pp 213Slots and images are numbered starting at zero. 214If a driver indicates support for multiple images, through the 215.Fn ddi_ufm_op_nimages 216entry point, or slots, by using the 217.Xr ddi_ufm_image_set_nslots 9F 218function in the 219.Fn ddi_fum_op_fill_image 220callback then the images 221or slots will be numbered sequentially going from 0 to the number of images or 222slots minus one. 223These values will be passed to the various entry points to indicate which image 224and slot the system is interested in. 225It is up to the driver to maintain a consistent view of the images and slots 226for a given UFM. 227.Ss Fn ddi_ufm_op_nimages 228The 229.Fn ddi_ufm_op_nimages 230entry point is an optional entry point that answers the question of how 231many different, distinct firmware images are present on the device. 232Once the driver determines how many are present, it should set the value in 233.Fa nimgp 234to the determined value. 235.Pp 236It is legal for a device to pass in zero for this value, which indicates 237that there are none present. 238.Pp 239Upon successful completion, the driver should return 240.Sy 0 . 241Otherwise, the driver should return the appropriate error number. 242For a full list of error numbers, see 243.Xr Intro 2 . 244Common values are: 245.Bl -tag -width Er -offset width 246.It Er EIO 247An error occurred while communicating with the device to determine the 248number of firmware images. 249.El 250.Ss Fn ddi_ufm_op_fill_image 251The 252.Fn ddi_ufm_op_fill_image 253entry point is used to fill in information about a given image. 254The value in 255.Fa imgno 256is used to indicate which image the system is asking to fill 257information about. 258If the driver does not recognize the image ID in 259.Fa imgno 260then it should return an error. 261.Pp 262The 263.Ft ddi_ufm_image_t 264structure passed in 265.Fa imgp 266is opaque. 267To fill in information about the image, the driver should call the functions 268described in 269.Xr ddi_ufm_image 9F . 270.Pp 271The driver must call the 272.Xr ddi_ufm_image_set_desc 9F 273function to set a description of the image which indicates its purpose. 274This should be a human-readable string. 275In addition, the driver must call the 276.Xr ddi_ufm_image_set_nslots 9F 277function to indicate the number of slots that the device supports for 278that particular firmware image. 279The driver may also set any ancillary data that it deems may be useful with the 280.Xr ddi_ufm_image_set_misc 9F function. 281This function takes an nvlist, allowing the driver to set arbitrary keys and values. 282.Pp 283Once the driver has finished setting all of the information about the 284image then the driver should return 285.Sy 0 . 286Otherwise, the driver should return the appropriate error number. 287For a full list of error numbers, see 288.Xr Intro 2 . 289Common values are: 290.Bl -tag -width Er -offset width 291.It Er EINVAL 292The image indicated by 293.Fa imgno 294is unknown. 295.It Er EIO 296An error occurred talking to the device while trying to fill out 297firmware image information. 298.It Er ENOMEM 299The driver was unable to allocate memory while filling out image 300information. 301.El 302.Ss Fn ddi_ufm_op_fill_slot 303The 304.Fn ddi_ufm_op_fill_slot 305function is used to fill in information about a specific slot for a 306specific image. 307The value in 308.Fa imgno 309indicates the image the system wants slot information for and the value 310in 311.Fa slotno 312indicates which slot of that image the system is interested in. 313If the device driver does not recognize the value in either or 314.Fa imgno 315or 316.Fa slotno , 317then it should return an error. 318.Pp 319The 320.Ft ddi_ufm_slot_t 321structure passed in 322.Fa slotp 323is opaque. 324To fill in information about the image the driver should call the functions 325described in 326.Xr ddi_ufm_slot 9F . 327.Pp 328The driver should call the 329.Xr ddi_ufm_slot_set_version 9F 330function to indicate the version of the UFM. 331The version is a device-specific character string. 332It should contain the current version of the UFM as a human can understand it 333and it should try to match the format used by device vendor. 334.Pp 335The 336.Xr ddi_ufm_slot_set_attrs 9F 337function should be used to set the attributes of the UFM slot. 338These attributes include the following enumeration values: 339.Bl -tag -width Dv 340.It Dv DDI_UFM_ATTR_READABLE 341The 342.Dv DDI_UFM_ATTR_READABLE 343attribute indicates that the firmware image in the specified slot 344may be read, even if the device driver does not currently support such 345functionality. 346.It Dv DDI_UFM_ATTR_WRITEABLE 347The 348.Dv DDI_UFM_ATTR_WRITEABLE 349attribute indicates that the firmware image in the specified slot 350may be updated, even if the driver does not currently support such 351functionality. 352.It Dv DDI_UFM_ATTR_ACTIVE 353The 354.Dv DDI_UFM_ATTR_ACTIVE 355attribute indicates that the firmware image in the specified slot 356is the active 357.Pq i.e. currently running 358firmware. 359Only one slot should be marked active. 360.It Dv DDI_UFM_ATTR_EMPTY 361The 362.Dv DDI_UFM_ATTR_EMPTY 363attribute indicates that the specified slot does not currently contain 364any firmware image. 365.El 366.Pp 367If the driver supports the 368.Fn ddi_ufm_op_readimg 369entry point, then the driver should attempt to determine the size in 370bytes of the image in the slot and indicate that by calling the 371.Xr ddi_ufm_slot_set_imgsize 9F 372function. 373.Pp 374Finally, if there are any device-specific key-value pairs that form 375useful, ancillary data, then the driver should assemble an nvlist and 376pass it to the 377.Xr ddi_ufm_slot_set_misc 9F 378function. 379.Pp 380Once the driver has finished setting all of the information about the 381slot then the driver should return 382.Sy 0 . 383Otherwise, the driver should return the appropriate error number. 384For a full list of error numbers, see 385.Xr Intro 2 . 386Common values are: 387.Bl -tag -width Er -offset width 388.It Er EINVAL 389The image or slot indicated by 390.Fa imgno 391and 392.Fa slotno 393is unknown. 394.It Er EIO 395An error occurred talking to the device while trying to fill out 396firmware slot information. 397.It Er ENOMEM 398The driver was unable to allocate memory while filling out slot 399information. 400.El 401.Ss Fn ddi_ufm_op_getcaps 402The 403.Fn ddi_ufm_op_getcaps 404function is used to indicate which DDI UFM capabilities are supported by this 405driver instance. 406Currently, all UFM-capable drivers are required to implement the 407.Dv DDI_UFM_CAP_REPORT 408capability. 409The following capabilities are supported and the drivers should return a 410bitwise-inclusive-OR of the following values: 411.Bl -tag -width Dv -offset width 412.It Dv DDI_UFM_CAP_REPORT 413Indicates that the driver is capable of reporting UFM information and 414implements the 415.Fn ddi_ufm_op_fill_slot 416and 417.Fn ddi_ufm_op_fill_image 418entry points. 419It also indicates, that it optionally implements 420.Fn ddi_ufm_op_nimages 421entry point. 422.It Dv DDI_UFM_CAP_READIMG 423Indicates that the driver is capable of reading a binary firmware 424payload off of a device. 425.El 426.Pp 427The driver should indicate the supported capabilities by setting the value in 428the 429.Ft caps 430parameter. 431Once the driver has populated 432.Ft caps 433with an appropriate value, then the driver should return 434.Sy 0 . 435Otherwise, the driver should return the appropriate error number. 436For a full list of error numbers, see 437.Xr Intro 2 . 438Common values are: 439.Bl -tag -width Er -offset width 440.It Er EIO 441An error occurred talking to the device while trying to discover firmware 442capabilities. 443.It Er ENOMEM 444The driver was unable to allocate memory. 445.El 446.Ss Fn ddi_ufm_op_readimg 447The 448.Fn ddi_ufm_op_readimg 449is an optional entry point that allows the system to read a binary 450firmware payload from the device. 451The driver should read the firmware payload indicated by both 452.Fa imgno 453and 454.Fa slotno . 455The driver should check to make sure that the region requested, starting 456at 457.Fa offset 458bytes into the image 459and 460.Fa len 461bytes long is valid for the image and if not, return the error 462.Er EINVAL . 463Data from the device should be copied into 464.Fa buf 465and the number of bytes successfully read should be placed into 466.Fa nreadp . 467.Pp 468Upon successfully reading this data, the driver should return 469.Sy 0 . 470Otherwise the driver should return the appropriate error number. 471For a full list of error numbers, see 472.Xr Intro 2 . 473Common values are: 474.Bl -tag -width Er -offset width 475.It Er EINVAL 476The image or slot indicate by 477.Fa imgno 478and 479.Fa slotno 480is unknown. 481The combination of 482.Fa offset 483and 484.Fa len 485would overflow or read from a region of the image which is not valid. 486The device currently has an alignment restriction and the requested 487offset and length do not honor that. 488.It Er EIO 489An error occurred while communicating with the device to read the 490firmware image. 491.It Er ENOTSUP 492The driver does not support reading a firmware payload on this device or 493from a particular image and slot. 494.El 495.Ss Caching and Updates 496The system will fetch firmware and slot information on an as-needed 497basis. 498Once it obtains some information, it may end up caching this information on 499behalf of the driver. 500Whenever the driver believes that something could have changed then the driver 501must call 502.Xr ddi_ufm_update 9F . 503The driver does not need to know for certain that something has changed. 504For example, after a device reset or firmware upgrade, the driver doesn't need 505to check if the firmware revision changed at all, it can simply call 506.Xr ddi_ufm_update 9F . 507.Ss Locking 508All UFM operations on a single UFM handle will always be run serially. 509However, the device driver may still need to apply adequate locking to 510its structure members as other entry points may be called on the device in 511parallel, which could access the same data structures and try to communicate 512with the device. 513.Ss Unregistering from the UFM subsystem 514When a device driver is detached, it should unregister from the UFM 515subsystem. 516To do so, the driver should call 517.Xr ddi_ufm_fini 9F . 518By the time this function returns, the driver is guaranteed that no UFM 519entry points will be called. 520However, if there are outstanding UFM related activity, the function will 521block until it is terminated. 522.Ss ioctl Interface 523Userland consumers can access UFM information via a set of ioctls that are 524implemented by the 525.Xr ufm 4D 526driver. 527.Sh CONTEXT 528The various UFM entry points that a device driver must implement will 529always be called from 530.Sy kernel 531context. 532.Sh SEE ALSO 533.Xr Intro 2 , 534.Xr ufd 4D , 535.Xr attach 9E , 536.Xr ddi_ufm_fini 9F , 537.Xr ddi_ufm_image 9F , 538.Xr ddi_ufm_image_set_desc 9F , 539.Xr ddi_ufm_image_set_misc 9F , 540.Xr ddi_ufm_image_set_nslots 9F , 541.Xr ddi_ufm_init 9F , 542.Xr ddi_ufm_slot 9F , 543.Xr ddi_ufm_slot_set_attrs 9F , 544.Xr ddi_ufm_slot_set_misc 9F , 545.Xr ddi_ufm_slot_set_version 9F , 546.Xr ddi_ufm_update 9F 547