1508a0e8cSRob Johnston.\" 2508a0e8cSRob Johnston.\" This file and its contents are supplied under the terms of the 3508a0e8cSRob Johnston.\" Common Development and Distribution License ("CDDL"), version 1.0. 4508a0e8cSRob Johnston.\" You may only use this file in accordance with the terms of version 5508a0e8cSRob Johnston.\" 1.0 of the CDDL. 6508a0e8cSRob Johnston.\" 7508a0e8cSRob Johnston.\" A full copy of the text of the CDDL should have accompanied this 8508a0e8cSRob Johnston.\" source. A copy of the CDDL is also available via the Internet at 9508a0e8cSRob Johnston.\" http://www.illumos.org/license/CDDL. 10508a0e8cSRob Johnston.\" 11508a0e8cSRob Johnston.\" 12508a0e8cSRob Johnston.\" Copyright 2019 Joyent, Inc. 138d55b806SRobert Mustacchi.\" Copyright 2020 Oxide Computer Company 14508a0e8cSRob Johnston.\" 159dd2e6b5SPeter Tribble.Dd May 23, 2021 16*bbf21555SRichard Lowe.Dt UFM 4D 17508a0e8cSRob Johnston.Os 18508a0e8cSRob Johnston.Sh NAME 19508a0e8cSRob Johnston.Nm ufm 20508a0e8cSRob Johnston.Nd Upgradeable Firmware Module driver 21508a0e8cSRob Johnston.Sh SYNOPSIS 22508a0e8cSRob Johnston.Pa /dev/ufm 23508a0e8cSRob Johnston.Lp 24508a0e8cSRob Johnston.In sys/ddi_ufm.h 25508a0e8cSRob Johnston.Sh DESCRIPTION 26508a0e8cSRob JohnstonThe 27508a0e8cSRob Johnston.Nm 288d55b806SRobert Mustacchidevice is a character special file that provides access to 29508a0e8cSRob JohnstonUpgradeable Firmware Image information, as described in 30508a0e8cSRob Johnston.Xr ddi_ufm 9E 31508a0e8cSRob Johnstonvia a private ioctl interface. 328d55b806SRobert Mustacchi.Pp 338d55b806SRobert MustacchiThe UFM interfaces described below are used in the implementation of the 348d55b806SRobert Mustacchisystem through tools such as 35*bbf21555SRichard Lowe.Xr fwflash 8 368d55b806SRobert Mustacchior as part of the fault management architecture. 37508a0e8cSRob Johnston.Sh FILES 38508a0e8cSRob Johnston.Bl -tag -width Pa 39508a0e8cSRob Johnston.It Pa /kernel/drv/amd64/ufm 40508a0e8cSRob Johnston64-bit AMD64 ELF kernel driver 41508a0e8cSRob Johnston.It Pa /kernel/drv/sparcv9/ufm 42508a0e8cSRob Johnston64-bit SPARC ELF kernel driver 43508a0e8cSRob Johnston.El 44508a0e8cSRob Johnston.Sh IOCTLS 45508a0e8cSRob JohnstonThe 46508a0e8cSRob Johnston.Nm 47508a0e8cSRob Johnstondriver implements a versioned ioctl interface for accessing UFM facilities. 48508a0e8cSRob JohnstonThe ioctl interfaces are defined in sys/ddi_ufm.h. 49508a0e8cSRob JohnstonThe following ioctl cmds are supported by DDI_UFM_VERSION_ONE: 50508a0e8cSRob Johnston.Bl -tag -width Dv 51508a0e8cSRob Johnston.It Dv UFM_IOC_GETCAPS 52508a0e8cSRob JohnstonThe 53508a0e8cSRob Johnston.Dv UFM_IOC_GETCAPS 54508a0e8cSRob Johnstonioctl is used to retrieve the set of DDI UFM capabilities supported by this 55508a0e8cSRob Johnstondevice instance. 56508a0e8cSRob Johnston.Pp 57508a0e8cSRob JohnstonThe ddi_ufm_cap_t type defines a bitfield enumerating the full set of DDI UFM 58508a0e8cSRob Johnstoncapabilities. 59508a0e8cSRob Johnston.Bd -literal 60508a0e8cSRob Johnstontypedef enum { 61508a0e8cSRob Johnston DDI_UFM_CAP_REPORT = 1 << 0, 628d55b806SRobert Mustacchi DDI_UFM_CAP_READIMG = 1 << 1 63508a0e8cSRob Johnston} ddi_ufm_cap_t; 64508a0e8cSRob Johnston.Ed 65508a0e8cSRob Johnston.Pp 668d55b806SRobert MustacchiThe capabilities mean: 678d55b806SRobert Mustacchi.Bl -tag -width Dv 688d55b806SRobert Mustacchi.It Dv DDI_UFM_CAP_REPORT 698d55b806SRobert MustacchiIndicates that the device is capable of reporting UFM information and 708d55b806SRobert Mustacchisupports the 718d55b806SRobert Mustacchi.Dv UFM_IOC_REPORT 728d55b806SRobert Mustacchiand 738d55b806SRobert Mustacchi.Dv UFM_IOC_REPORTSZ 748d55b806SRobert Mustacchiioctls. 758d55b806SRobert Mustacchi.It Dv DDI_UFM_CAP_READIMG 768d55b806SRobert MustacchiIndicates that the device is capable of retrieving a firmware image from 778d55b806SRobert Mustacchia slot and transferring it back to the caller. 788d55b806SRobert MustacchiThe 798d55b806SRobert Mustacchi.Dv UFM_IOC_READIMG 808d55b806SRobert Mustacchiioctl is supported. 818d55b806SRobert Mustacchi.El 828d55b806SRobert Mustacchi.Pp 838d55b806SRobert MustacchiThe 848d55b806SRobert Mustacchi.Vt ufm_ioc_getcaps_t 858d55b806SRobert Mustacchistructure defines the input/output data for the 86508a0e8cSRob Johnston.Dv UFM_IOC_GETCAPS 87508a0e8cSRob Johnstonioctl. 888d55b806SRobert MustacchiCallers should specify the 898d55b806SRobert Mustacchi.Fa ufmg_version 908d55b806SRobert Mustacchiand 918d55b806SRobert Mustacchi.Fa ufmg_devpath 928d55b806SRobert Mustacchifields. 938d55b806SRobert MustacchiOn success the 948d55b806SRobert Mustacchi.Fa ufmg_caps 958d55b806SRobert Mustacchifield will be filled in with a value indicating the 968d55b806SRobert Mustacchisupported UFM capabilities of the device specified in 978d55b806SRobert Mustacchi.Fa ufmg_devpath . 98508a0e8cSRob Johnston.Bd -literal 99508a0e8cSRob Johnstontypedef struct ufm_ioc_getcaps { 1008d55b806SRobert Mustacchi uint_t ufmg_version; /* DDI_UFM_VERSION_ONE */ 101508a0e8cSRob Johnston uint_t ufmg_caps; /* UFM Caps */ 102508a0e8cSRob Johnston char ufmg_devpath[MAXPATHLEN]; 103508a0e8cSRob Johnston} ufm_ioc_getcaps_t; 104508a0e8cSRob Johnston.Ed 1058d55b806SRobert Mustacchi.It Dv UFM_IOC_REPORTSZ 106508a0e8cSRob JohnstonThe 1078d55b806SRobert Mustacchi.Dv UFM_IOC_REPORTSZ 1088d55b806SRobert Mustacchiioctl is used to retrieve the amount of space 109508a0e8cSRob Johnston(in bytes) required to hold the UFM data for this device instance. 110508a0e8cSRob JohnstonThis should be used to allocate a sufficiently sized buffer for the 111508a0e8cSRob Johnston.Dv UFM_IOC_REPORT 112508a0e8cSRob Johnstonioctl. 113508a0e8cSRob Johnston.Pp 1148d55b806SRobert MustacchiThe 1158d55b806SRobert Mustacchi.Vt ufm_ioc_bufsz_t 1168d55b806SRobert Mustacchistructure defines the input/output data for the 1178d55b806SRobert Mustacchi.Dv UFM_IOC_REPORTSZ 1188d55b806SRobert Mustacchiioctl. 1198d55b806SRobert MustacchiCallers should specify the 1208d55b806SRobert Mustacchi.Fa ufbz_version 1218d55b806SRobert Mustacchiand 1228d55b806SRobert Mustacchi.Fa ufbz_devpath 1238d55b806SRobert Mustacchifields. 1248d55b806SRobert MustacchiOn success the 1258d55b806SRobert Mustacchi.Fa ufbz_size 1268d55b806SRobert Mustacchifield will be filled in with the required buffer size. 127508a0e8cSRob Johnston.Bd -literal 128508a0e8cSRob Johnstontypedef struct ufm_ioc_bufsz { 1298d55b806SRobert Mustacchi uint_t ufbz_version; /* DDI_UFM_VERSION_ONE */ 130508a0e8cSRob Johnston size_t ufbz_size; /* sz of buf to be returned by ioctl */ 131508a0e8cSRob Johnston char ufbz_devpath[MAXPATHLEN]; 132508a0e8cSRob Johnston} ufm_ioc_bufsz_t; 133508a0e8cSRob Johnston.Ed 1348d55b806SRobert Mustacchi.It Dv UFM_IOC_REPORT 135508a0e8cSRob JohnstonThe 1368d55b806SRobert Mustacchi.Dv UFM_IOC_REPORT 1378d55b806SRobert Mustacchiioctl returns UFM image and slot data in the form of a packed nvlist. 1388d55b806SRobert MustacchiThe 1398d55b806SRobert Mustacchi.Vt ufm_ioc_report_t 1408d55b806SRobert Mustacchistructure defines the input/output data for the 141508a0e8cSRob Johnston.Dv UFM_IOC_REPORT 142508a0e8cSRob Johnstonioctl. 143508a0e8cSRob JohnstonCallers should specify the ufmr_version, ufmr_bufsz and ufmr_devpath fields. 144508a0e8cSRob JohnstonOn success, the ufmr_buf field will point to a packed nvlist containing the UFM 145508a0e8cSRob Johnstondata for the specified device instance. 146508a0e8cSRob JohnstonThis data can be unpacked and decoded into an nvlist using 147508a0e8cSRob Johnston.Xr nvlist_unpack 3NVPAIR . 148508a0e8cSRob Johnston.Bd -literal 149508a0e8cSRob Johnstontypedef struct ufm_ioc_report { 1508d55b806SRobert Mustacchi uint_t ufmr_version; /* DDI_UFM_VERSIONONE */ 151508a0e8cSRob Johnston size_t ufmr_bufsz; /* size of caller-supplied buffer */ 152508a0e8cSRob Johnston caddr_t ufmr_buf; /* buf to hold packed output nvl */ 153508a0e8cSRob Johnston char ufmr_devpath[MAXPATHLEN]; 154508a0e8cSRob Johnston} ufm_ioc_report_t; 1558d55b806SRobert Mustacchi.Ed 156508a0e8cSRob Johnston.Pp 157508a0e8cSRob JohnstonDue to the asynchronous nature of the system, it's possible for a device to 158508a0e8cSRob Johnstonundergo a configuration change in between a 1598d55b806SRobert Mustacchi.Dv UFM_IOC_REPORTSZ 1608d55b806SRobert Mustacchiioctl and a subsequent 1618d55b806SRobert Mustacchi.Dv UFM_IOC_REPORT 1628d55b806SRobert Mustacchiioctl that would alter the size of the buffer 163508a0e8cSRob Johnstonrequired to hold the UFM data. 164508a0e8cSRob Johnston.Pp 165508a0e8cSRob JohnstonIf the size of buffer supplied in the 1668d55b806SRobert Mustacchi.Dv UFM_IOC_REPORT 1678d55b806SRobert Mustacchiioctl is greater than is required to hold the UFM data, then 168508a0e8cSRob Johnstonthe ioctl will succeed and the ufmr_bufsz field will be updated to reflect the 169508a0e8cSRob Johnstonactual size of the returned UFM data. 170508a0e8cSRob JohnstonIf the size of buffer supplied in the 1718d55b806SRobert Mustacchi.Dv UFM_IOC_REPORT 1728d55b806SRobert Mustacchiioctl is less than what is required to hold the UFM data, 173508a0e8cSRob Johnstonthe ioctl will fail with errno set to 174508a0e8cSRob Johnston.Er EOVERFLOW . 1758d55b806SRobert Mustacchi.It Dv UFM_IOC_READIMG 1768d55b806SRobert MustacchiThe 1778d55b806SRobert Mustacchi.Dv UFM_IOC_READIMG 1788d55b806SRobert Mustacchiioctl retrieves a firmware image and slot from a device. 1798d55b806SRobert MustacchiThe 1808d55b806SRobert Mustacchi.Vt ufm_ioc_readimg_t 1818d55b806SRobert Mustacchistructure defines the input and output data for the ioctl. 1828d55b806SRobert MustacchiDevices may have their own alignment and size constraints which may be 1838d55b806SRobert Mustacchienforced upon issuing this ioctl. 1848d55b806SRobert MustacchiThe structure has the following form: 1858d55b806SRobert Mustacchi.Bd -literal 1868d55b806SRobert Mustacchitypedef struct ufm_ioc_readimg { 1878d55b806SRobert Mustacchi uint_t ufri_version; 1888d55b806SRobert Mustacchi uint_t ufri_imageno; 1898d55b806SRobert Mustacchi uint_t ufri_slotno; 1908d55b806SRobert Mustacchi uint64_t ufri_offset; 1918d55b806SRobert Mustacchi uint64_t ufri_len; 1928d55b806SRobert Mustacchi uint64_t ufri_nread; 1938d55b806SRobert Mustacchi void *ufri_buf; 1948d55b806SRobert Mustacchi char ufri_devpath[MAXPATHLEN]; 1958d55b806SRobert Mustacchi} ufm_ioc_readimg_t; 196508a0e8cSRob Johnston.Ed 1978d55b806SRobert Mustacchi.Pp 1988d55b806SRobert MustacchiThe 1998d55b806SRobert Mustacchi.Ft ufri_imageno 2008d55b806SRobert Mustacchiand 2018d55b806SRobert Mustacchi.Ft ufri_slotno 2028d55b806SRobert Mustacchivalues are used to indicate the image and slot to read. 2038d55b806SRobert MustacchiThese indexes correspond to the same indices that are returned in the 2048d55b806SRobert Mustacchinvlist from the 2058d55b806SRobert Mustacchi.Dv UFM_IOC_REPORT 2068d55b806SRobert Mustacchiioctl. 2078d55b806SRobert MustacchiThe 2088d55b806SRobert Mustacchi.Ft ufri_offset 2098d55b806SRobert Mustacchiand 2108d55b806SRobert Mustacchi.Ft ufri_len 2118d55b806SRobert Mustacchimembers are used to indicate how many bytes to read from the image and 2128d55b806SRobert Mustacchiwhere in the image to begin. 2138d55b806SRobert MustacchiThe 2148d55b806SRobert Mustacchi.Fa ufri_buf 2158d55b806SRobert Mustacchimember must be set to a valid pointer. 2168d55b806SRobert MustacchiData read from the device will be placed in that pointer. 2178d55b806SRobert MustacchiThe pointer must be at least 2188d55b806SRobert Mustacchi.Fa ufri_len 2198d55b806SRobert Mustacchibytes long. 2208d55b806SRobert MustacchiUpon successful completion, the 2218d55b806SRobert Mustacchi.Fa ufri_nread 2228d55b806SRobert Mustacchimember will be filled in with the number of bytes that have been placed 2238d55b806SRobert Mustacchiin 2248d55b806SRobert Mustacchi.Fa ufri_buf . 2258d55b806SRobert MustacchiFinally, the 2268d55b806SRobert Mustacchi.Fa ufri_version 2278d55b806SRobert Mustacchiand 2288d55b806SRobert Mustacchi.Fa ufri_devpath 2298d55b806SRobert Mustacchifields must be filled in with the version number, 2308d55b806SRobert Mustacchi.Dv DDI_UFM_VERSION_ONE , 2318d55b806SRobert Mustacchiand the corresponding /devices path. 232508a0e8cSRob Johnston.El 233508a0e8cSRob Johnston.Sh EXAMPLES 2348d55b806SRobert MustacchiThis example demonstrates how to use the 2358d55b806SRobert Mustacchi.Dv UFM_IOC_GETCAPS 2368d55b806SRobert Mustacchiioctl to determine the UFM capabilities of a given device instance. 237508a0e8cSRob Johnston.Bd -literal 238508a0e8cSRob Johnston#include <stdio.h> 239508a0e8cSRob Johnston#include <stdlib.h> 240508a0e8cSRob Johnston#include <errno.h> 241508a0e8cSRob Johnston#include <fcntl.h> 242508a0e8cSRob Johnston#include <string.h> 243508a0e8cSRob Johnston#include <unistd.h> 244508a0e8cSRob Johnston#include <sys/ddi_ufm.h> 245508a0e8cSRob Johnston#include <sys/types.h> 246508a0e8cSRob Johnston 247508a0e8cSRob Johnstonstatic const char devname[] = "/pci@ce,0/pci8086,2030@0/pci15d9,808@0"; 248508a0e8cSRob Johnston 249508a0e8cSRob Johnstonint 250508a0e8cSRob Johnstonmain(int argc, char **argv) 251508a0e8cSRob Johnston{ 252508a0e8cSRob Johnston int fd; 253508a0e8cSRob Johnston ufm_ioc_getcaps_t ioc = { 0 }; 254508a0e8cSRob Johnston 255508a0e8cSRob Johnston if ((fd = open(DDI_UFM_DEV, O_RDWR)) < 0) { 256508a0e8cSRob Johnston (void) fprintf(stderr, "failed to open %s (%s)\n", DDI_UFM_DEV, 257508a0e8cSRob Johnston strerror(errno)); 258508a0e8cSRob Johnston return (1); 259508a0e8cSRob Johnston } 260508a0e8cSRob Johnston 261508a0e8cSRob Johnston ioc.ufmg_version = DDI_UFM_CURRENT_VERSION; 262508a0e8cSRob Johnston (void) strcpy(ioc.ufmg_devpath, devname); 263508a0e8cSRob Johnston 264508a0e8cSRob Johnston if (ioctl(fd, UFM_IOC_GETCAPS, &ioc) < 0) { 265508a0e8cSRob Johnston (void) fprintf(stderr, "getcaps ioctl failed (%s)\n", 266508a0e8cSRob Johnston strerror(errno)); 267508a0e8cSRob Johnston (void) close(fd); 268508a0e8cSRob Johnston return (1); 269508a0e8cSRob Johnston } 270508a0e8cSRob Johnston if ((ioc.ufmg_caps & DDI_UFM_CAP_REPORT) == 0) { 271508a0e8cSRob Johnston (void) printf("Driver does not support DDI_UFM_CAP_REPORT\n"); 272508a0e8cSRob Johnston } else { 273508a0e8cSRob Johnston (void) printf("Driver supports DDI_UFM_CAP_REPORT\n"); 274508a0e8cSRob Johnston } 275508a0e8cSRob Johnston (void) close(fd); 276508a0e8cSRob Johnston return (0); 277508a0e8cSRob Johnston} 278508a0e8cSRob Johnston.Ed 279508a0e8cSRob Johnston.Sh ERRORS 280508a0e8cSRob JohnstonOn failure to open or perform ioctls to the 281508a0e8cSRob Johnston.Nm 282508a0e8cSRob Johnstondriver, 283508a0e8cSRob Johnston.Va errno 284508a0e8cSRob Johnstonwill be set to indicate the type of error. 285508a0e8cSRob JohnstonA subset of the more common errors are detailed below. 286508a0e8cSRob JohnstonFor a full list of error numbers, see 287508a0e8cSRob Johnston.Xr Intro 2 288508a0e8cSRob Johnston.Bl -tag -width Er 289508a0e8cSRob Johnston.It Er EAGAIN 290508a0e8cSRob JohnstonThe device driver is not currently ready to accept calls to it's DDI UFM entry 291508a0e8cSRob Johnstonpoints. 292508a0e8cSRob JohnstonThis may be because the driver is not fully initialized or because the driver 293508a0e8cSRob Johnstonis in the process of detaching. 2948d55b806SRobert Mustacchi.It Er EFAULT 2958d55b806SRobert MustacchiThe ufm driver encountered a failure while copying data either from or to the 2968d55b806SRobert Mustacchiaddress space of the calling process. 2978d55b806SRobert Mustacchi.It Er EINVAL 2988d55b806SRobert MustacchiThe offset or length of an image would have resulted in a read outside 2998d55b806SRobert Mustacchiof the image's valid range or with improper alignment. 300508a0e8cSRob Johnston.It Er EIO 301508a0e8cSRob JohnstonA failure occurred while executing a DDI UFM entry point. 3028d55b806SRobert Mustacchi.It Er ENOTSUP 3038d55b806SRobert MustacchiEither the requested ioctl is not supported by the target device, the device 3048d55b806SRobert Mustacchidoes not exist or the device does not support the UFM interfaces. 305508a0e8cSRob Johnston.El 306508a0e8cSRob Johnston.Sh INTERFACE STABILITY 307508a0e8cSRob Johnston.Sy Evolving 308508a0e8cSRob Johnston.Sh SEE ALSO 309508a0e8cSRob Johnston.Xr ddi_ufm 9E , 3109dd2e6b5SPeter Tribble.Xr ddi_ufm 9F , 3119dd2e6b5SPeter Tribble.Xr ddi_ufm_image 9F , 3129dd2e6b5SPeter Tribble.Xr ddi_ufm_slot 9F 313