12759 Want ability to read ufm images

12758 ufm_detach doesn't properly clean up
12760 igb ufm support
12765 fwflash plugin cleanup handling is buggy
Reviewed by: Patrick Mooney <patrick.mooney@joyent.com>
Reviewed by: Jerry Jelinek <jerry.jelinek@joyent.com>
Approved by: Joshua Clulow <josh@sysmgr.org>

1 files changed, 141 insertions, 35 deletions

diff --git a/usr/src/man/man7d/ufm.7d b/usr/src/man/man7d/ufm.7d
index 5cd2b3581e..60fdfa9983 100644
--- a/usr/src/man/man7d/ufm.7d
+++ b/usr/src/man/man7d/ufm.7d
@@ -10,8 +10,9 @@
 .\"
 .\"
 .\" Copyright 2019 Joyent, Inc.
+.\" Copyright 2020 Oxide Computer Company
 .\"
-.Dd Jun 5, 2019
+.Dd June 9, 2020
 .Dt UFM 7D
 .Os
 .Sh NAME
@@ -24,10 +25,15 @@
 .Sh DESCRIPTION
 The
 .Nm
-device is a character special file that provides acccess to
+device is a character special file that provides access to
 Upgradeable Firmware Image information, as described in
 .Xr ddi_ufm 9E
 via a private ioctl interface.
+.Pp
+The UFM interfaces described below are used in the implementation of the
+system through tools such as
+.Xr fwflash 1M
+or as part of the fault management architecture.
 .Sh FILES
 .Bl -tag -width Pa
 .It Pa /kernel/drv/amd64/ufm
@@ -47,56 +53,91 @@ The
 .Dv UFM_IOC_GETCAPS
 ioctl is used to retrieve the set of DDI UFM capabilities supported by this
 device instance.
-Currently there is only a single capability
-.Dv DDI_UFM_CAP_REPORT ,
-which indicates
-that the driver is capable of reporting UFM information.
 .Pp
 The ddi_ufm_cap_t type defines a bitfield enumerating the full set of DDI UFM
 capabilities.
 .Bd -literal
 typedef enum {
 	DDI_UFM_CAP_REPORT	= 1 << 0,
+	DDI_UFM_CAP_READIMG	= 1 << 1
 } ddi_ufm_cap_t;
 .Ed
 .Pp
-The ufm_ioc_getcaps_t type defines the input/output data for the
+The capabilities mean:
+.Bl -tag -width Dv
+.It Dv DDI_UFM_CAP_REPORT
+Indicates that the device is capable of reporting UFM information and
+supports the
+.Dv UFM_IOC_REPORT
+and
+.Dv UFM_IOC_REPORTSZ
+ioctls.
+.It Dv DDI_UFM_CAP_READIMG
+Indicates that the device is capable of retrieving a firmware image from
+a slot and transferring it back to the caller.
+The
+.Dv UFM_IOC_READIMG
+ioctl is supported.
+.El
+.Pp
+The
+.Vt ufm_ioc_getcaps_t
+structure defines the input/output data for the
 .Dv UFM_IOC_GETCAPS
 ioctl.
-Callers should specify the ufmg_version and ufmg_devpath fields.
-On success the ufmg_caps field will be filled in with a value indicating the
-supported UFM capabilities of the device specified in ufmg_devpath.
+Callers should specify the
+.Fa ufmg_version
+and
+.Fa ufmg_devpath
+fields.
+On success the
+.Fa ufmg_caps
+field will be filled in with a value indicating the
+supported UFM capabilities of the device specified in
+.Fa ufmg_devpath .
 .Bd -literal
 typedef struct ufm_ioc_getcaps {
-	uint_t		ufmg_version;	/* DDI_UFM_VERSION */
+	uint_t		ufmg_version;	/* DDI_UFM_VERSION_ONE */
 	uint_t		ufmg_caps;	/* UFM Caps */
 	char		ufmg_devpath[MAXPATHLEN];
 } ufm_ioc_getcaps_t;
 .Ed
-.It UFM_IOC_REPORTSZ
+.It Dv UFM_IOC_REPORTSZ
 The
-.Dv UFM_IOC_REPORTSZ ioctl is used to retrieve the amount of space
+.Dv UFM_IOC_REPORTSZ
+ioctl is used to retrieve the amount of space
 (in bytes) required to hold the UFM data for this device instance.
 This should be used to allocate a sufficiently sized buffer for the
 .Dv UFM_IOC_REPORT
 ioctl.
 .Pp
-The ufm_ioc_bufsz_t struct defines the input/output data for the
-.Dv UFM_IOC_REPORTSZ ioctl.
-Callers should specify the ufbz_version and ufbz_devpath fields.
-On success the ufmg_size field will be filled in with the required buffer size.
+The
+.Vt ufm_ioc_bufsz_t
+structure defines the input/output data for the
+.Dv UFM_IOC_REPORTSZ
+ioctl.
+Callers should specify the
+.Fa ufbz_version
+and
+.Fa ufbz_devpath
+fields.
+On success the
+.Fa ufbz_size
+field will be filled in with the required buffer size.
 .Bd -literal
 typedef struct ufm_ioc_bufsz {
-	uint_t		ufbz_version;	/* DDI_UFM_VERSION */
+	uint_t		ufbz_version;	/* DDI_UFM_VERSION_ONE */
 	size_t		ufbz_size;	/* sz of buf to be returned by ioctl */
 	char		ufbz_devpath[MAXPATHLEN];
 } ufm_ioc_bufsz_t;
 .Ed
-.It UFM_IOC_REPORT
+.It Dv UFM_IOC_REPORT
 The
-.Dv UFM_IOC_REPORT ioctl returns UFM image and slot data in the form of a
-packed nvlist.
-The ufm_ioc_report_t struct defines the input/output data for the
+.Dv UFM_IOC_REPORT
+ioctl returns UFM image and slot data in the form of a packed nvlist.
+The
+.Vt ufm_ioc_report_t
+structure defines the input/output data for the
 .Dv UFM_IOC_REPORT
 ioctl.
 Callers should specify the ufmr_version, ufmr_bufsz and ufmr_devpath fields.
@@ -106,31 +147,93 @@ This data can be unpacked and decoded into an nvlist using
 .Xr nvlist_unpack 3NVPAIR .
 .Bd -literal
 typedef struct ufm_ioc_report {
-	uint_t		ufmr_version;	/* DDI_UFM_VERSION */
+	uint_t		ufmr_version;	/* DDI_UFM_VERSIONONE */
 	size_t		ufmr_bufsz;	/* size of caller-supplied buffer */
 	caddr_t		ufmr_buf;	/* buf to hold packed output nvl */
 	char		ufmr_devpath[MAXPATHLEN];
 } ufm_ioc_report_t;
+.Ed
 .Pp
 Due to the asynchronous nature of the system, it's possible for a device to
 undergo a configuration change in between a
-.Dv UFM_IOC_REPORTSZ ioctl and a subsequent
-.Dv UFM_IOC_REPORT ioctl that would alter the size of the buffer
+.Dv UFM_IOC_REPORTSZ
+ioctl and a subsequent
+.Dv UFM_IOC_REPORT
+ioctl that would alter the size of the buffer
 required to hold the UFM data.
 .Pp
 If the size of buffer supplied in the
-.Dv UFM_IOC_REPORT ioctl is greater than is required to hold the UFM data, then
+.Dv UFM_IOC_REPORT
+ioctl is greater than is required to hold the UFM data, then
 the ioctl will succeed and the ufmr_bufsz field will be updated to reflect the
 actual size of the returned UFM data.
 If the size of buffer supplied in the
-.Dv UFM_IOC_REPORT ioctl is less than what is required to hold the UFM data,
+.Dv UFM_IOC_REPORT
+ioctl is less than what is required to hold the UFM data,
 the ioctl will fail with errno set to
 .Er EOVERFLOW .
+.It Dv UFM_IOC_READIMG
+The
+.Dv UFM_IOC_READIMG
+ioctl retrieves a firmware image and slot from a device.
+The
+.Vt ufm_ioc_readimg_t
+structure defines the input and output data for the ioctl.
+Devices may have their own alignment and size constraints which may be
+enforced upon issuing this ioctl.
+The structure has the following form:
+.Bd -literal
+typedef struct ufm_ioc_readimg {
+	uint_t		ufri_version;
+	uint_t		ufri_imageno;
+	uint_t		ufri_slotno;
+	uint64_t	ufri_offset;
+	uint64_t	ufri_len;
+	uint64_t	ufri_nread;
+	void		*ufri_buf;
+	char		ufri_devpath[MAXPATHLEN];
+} ufm_ioc_readimg_t;
 .Ed
+.Pp
+The
+.Ft ufri_imageno
+and
+.Ft ufri_slotno
+values are used to indicate the image and slot to read.
+These indexes correspond to the same indices that are returned in the
+nvlist from the
+.Dv UFM_IOC_REPORT
+ioctl.
+The
+.Ft ufri_offset
+and
+.Ft ufri_len
+members are used to indicate how many bytes to read from the image and
+where in the image to begin.
+The
+.Fa ufri_buf
+member must be set to a valid pointer.
+Data read from the device will be placed in that pointer.
+The pointer must be at least
+.Fa ufri_len
+bytes long.
+Upon successful completion, the
+.Fa ufri_nread
+member will be filled in with the number of bytes that have been placed
+in
+.Fa ufri_buf .
+Finally, the
+.Fa ufri_version
+and
+.Fa ufri_devpath
+fields must be filled in with the version number,
+.Dv DDI_UFM_VERSION_ONE ,
+and the corresponding /devices path.
 .El
 .Sh EXAMPLES
-This example demonstrates how to use the UFM_IOC_GETCAPS ioctl to determine
-the UFM capabilities of a given device instance.
+This example demonstrates how to use the
+.Dv UFM_IOC_GETCAPS
+ioctl to determine the UFM capabilities of a given device instance.
 .Bd -literal
 #include <stdio.h>
 #include <stdlib.h>
@@ -183,19 +286,22 @@ A subset of the more common errors are detailed below.
 For a full list of error numbers, see
 .Xr Intro 2
 .Bl -tag -width Er
-.It Er ENOTSUP
-Either the requested ioctl is not supported by the target device, the device
-does not exist or the device does not support the UFM interfaces.
-.It Er EFAULT
-The ufm driver encountered a failure while copying data either from or to the
-address space of the calling process.
 .It Er EAGAIN
 The device driver is not currently ready to accept calls to it's DDI UFM entry
 points.
 This may be because the driver is not fully initialized or because the driver
 is in the process of detaching.
+.It Er EFAULT
+The ufm driver encountered a failure while copying data either from or to the
+address space of the calling process.
+.It Er EINVAL
+The offset or length of an image would have resulted in a read outside
+of the image's valid range or with improper alignment.
 .It Er EIO
 A failure occurred while executing a DDI UFM entry point.
+.It Er ENOTSUP
+Either the requested ioctl is not supported by the target device, the device
+does not exist or the device does not support the UFM interfaces.
 .El
 .Sh INTERFACE STABILITY
 .Sy Evolving