git: b9ec3ec2275c - stable/13 - stand: Add driver interface docs

From: Warner Losh <>
Date: Tue, 24 Jan 2023 22:12:30 UTC
The branch stable/13 has been updated by imp:


commit b9ec3ec2275c6788fb91ebb8b641d5cd637fbed5
Author:     Warner Losh <>
AuthorDate: 2022-09-09 23:22:09 +0000
Commit:     Warner Losh <>
CommitDate: 2023-01-24 21:49:33 +0000

    stand: Add driver interface docs
    Add some rather bare-bones driver interface docs.
    Sponsored by:           Netflix
    Suggestions by:         rpokala
    Reviewed by:            pauamma
    Differential Revision:
    (cherry picked from commit 45ad955714f8442a4485510de819755370a76af3)
 stand/libsa/libsa.3 | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/stand/libsa/libsa.3 b/stand/libsa/libsa.3
index f1bfcd7b5be7..7bd7a848cd3d 100644
--- a/stand/libsa/libsa.3
+++ b/stand/libsa/libsa.3
@@ -24,7 +24,7 @@
 .\" $FreeBSD$
-.Dd February 22, 2018
+.Dd September 9, 2022
 .Dt LIBSA 3
@@ -502,6 +502,12 @@ Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading.
 .Bl -hang -width 10n
 .It Xo
+.Ft char *
+.Fn devformat "struct devdesc *"
+Format the specified device as a string.
+.It Xo
 .Ft void
 .Fn twiddle void
@@ -615,7 +621,7 @@ The device driver itself will already have been called for the close; this call
 should clean up any allocation made by devopen only.
 .It Xo
 .Ft void
-.Fn abort
+.Fn __abort
@@ -687,6 +693,65 @@ pointers should be terminated with a NULL.
 Devices are exported by the supporting code via the array
 .Vt struct devsw *devsw[]
 which is a NULL terminated array of pointers to device switch structures.
+The driver needs to provide a common set of entry points that are
+used by
+.Nm libsa
+to interface with the device.
+.Bd -literal
+struct devsw {
+    const char	dv_name[DEV_NAMLEN];
+    int		dv_type;
+    int		(*dv_init)(void);
+    int		(*dv_strategy)(void *devdata, int rw, daddr_t blk,
+			size_t size, char *buf, size_t *rsize);
+    int		(*dv_open)(struct open_file *f, ...);
+    int		(*dv_close)(struct open_file *f);
+    int		(*dv_ioctl)(struct open_file *f, u_long cmd, void *data);
+    int		(*dv_print)(int verbose);
+    void	(*dv_cleanup)(void);
+    void	(*dv_fmtdev)(struct devdesc *);
+.Bl -tag -width ".Fn dv_strategy"
+.It Fn dv_name
+The device's name.
+.It Fn dv_type
+Type of device.
+The supported types are:
+.Bl -tag -width "DEVT_NONE"
+Each type may have its own associated (struct type_devdesc),
+which has the generic (struct devdesc) as its first member.
+.It Fn dv_init
+Driver initialization routine.
+This routine should probe for available units.
+Drivers are responsible for maintaining lists of units for later enumeration.
+No other driver routines may be called before
+.Fn dv_init
+.It Fn dv_open
+The driver open routine.
+.It Fn dv_close
+The driver close routine.
+.It Fn dv_ioctl
+The driver ioctl routine.
+.It Fn dv_print
+Prints information about the available devices.
+Information should be presented with
+.Fn pager_output .
+.It Fn dv_cleanup
+Cleans up any memory used by the device before the next stage is run.
+.It Fn dv_fmtdev
+Converts the specified devdesc to the canonical string representation
+for that device.