From nobody Fri Sep 9 23:27:32 2022 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4MPXGD2RDpz4bdwy; Fri, 9 Sep 2022 23:27:32 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4MPXGD1vWkz3g88; Fri, 9 Sep 2022 23:27:32 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1662766052; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=nsTLQ4TKx+mUfAojkXVb58B562Y/Wh5W6Z5yGM9MDxY=; b=WNwvjyaqgfrmg21H6dKavl0oMqnc541UdNOw3HoBnj6AAvgfDgHVo9RBvhzVkdZ6TMDPuo U2MvzoqgvjJryE5QSOWM/m1tgmW8jyC8TJhUjcUNWNhC0mKjn8CnFDvzoBgBYtjEd0BWnI CtSGFdgC4QjgowOIvrvBJpGn4vD5B8Zy9VwF2L/vIfdnE0ZGtkV78Q80upFwaUdS92fQpg oAexgLvI5lkqNvrJQ164755rBHCRlIr+Tw5QsPxGSjLYJWNSnfR8Ek4T6VDNyLBDAkinsk CjD/Yq3xmz2dIcJZbql8+vdnLtZk9mpzdEmGzbvBmwUr9rMkUf/BHAAh8J7QCQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4MPXGD0xBCz1Lrm; Fri, 9 Sep 2022 23:27:32 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 289NRW5T006724; Fri, 9 Sep 2022 23:27:32 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 289NRWZC006723; Fri, 9 Sep 2022 23:27:32 GMT (envelope-from git) Date: Fri, 9 Sep 2022 23:27:32 GMT Message-Id: <202209092327.289NRWZC006723@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Warner Losh Subject: git: 45ad955714f8 - main - stand: Add driver interface docs List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: imp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 45ad955714f8442a4485510de819755370a76af3 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1662766052; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=nsTLQ4TKx+mUfAojkXVb58B562Y/Wh5W6Z5yGM9MDxY=; b=uG78AzjplZIu1norBvjKxeKT9NwnklXDd9lDp2MKA1F8FZOvMWuff3ydZ/vSQwaBfAWZph RGyGQ+9XPNiH2OIL6/Q1P2CdzFUXgTdQ3jFUrPOAnwPNoU/B6qZCUSTlgO5A9vxvhROy0+ zQ7tiNgRQwszYlr3yL4fYo+7PcAC9I4cxGhGmgXHQgFKsbeVSZ1BDVLdpgO/guvLZiS+8q HWsAAo7Q6T8XC2nB6L2szVHmMpfqntXSR1Fts+SYs6DrU5a95U9H5YaxoNVEABZU86yKaT SPLHBVLLWgoDWE0/D3zyJ88ba4TOUMqQkYhVdJ6EQzMWEpiyCoNUr1ZlxXCtJg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1662766052; a=rsa-sha256; cv=none; b=S+vUWSKD4W7IScElKFYPVMVuMx2yOliuC9nOuCh8NYRPIpA9qdj1i7LFal2Vo4LO9xSJih fFbEEJ/viwWUtCjuzFbW9Gomi6b2iR1j8My8TNHFbmZjO31cIgqFYoD2Xq1gifoQHVv0oa SgSg2UuordfZxnjB4KiwBPxb1U42RrakA+7c7b3EXCNx9it1YKZDXg8mmAT91dS5CYKBdU hcQ/oVtRi0/qGn4M/kAbdBSA47rar1eZL3KoXm//sOyB9mk1RQCJW+LXEQ7VklmqU7ncHj Iruta8r11nc+U7G0glMty3w8lodx01MiviEryhbPcRCODs4FfJnnQwYpIEHzeQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=45ad955714f8442a4485510de819755370a76af3 commit 45ad955714f8442a4485510de819755370a76af3 Author: Warner Losh AuthorDate: 2022-09-09 23:22:09 +0000 Commit: Warner Losh CommitDate: 2022-09-09 23:25:59 +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: https://reviews.freebsd.org/D35912 --- 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 .Os .Sh NAME @@ -502,6 +502,12 @@ Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading. .Sh MISC .Bl -hang -width 10n .It Xo +.Ft char * +.Fn devformat "struct devdesc *" +.Xc +.Pp +Format the specified device as a string. +.It Xo .Ft void .Fn twiddle void .Xc @@ -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 .Xc .Pp Calls @@ -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. +.Sh DRIVER INTERFACE +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 *); +}; +.Ed +.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" +.It DEVT_NONE +.It DEVT_DISK +.It DEVT_NET +.It DEVT_CD +.It DEVT_ZFS +.It DEVT_FD +.El +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 +returns. +.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. +.El .Sh HISTORY The .Nm