From nobody Tue Jan 24 22:12:30 2023 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 4P1h6Q5vsGz3bfqJ; Tue, 24 Jan 2023 22:12:30 +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 4P1h6Q4ntHz3DFL; Tue, 24 Jan 2023 22:12:30 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1674598350; 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=ZG3j1SPZ0BRPzPon05S9in9Adstaiaiq5zWXZIPdu8o=; b=KT16F0Vgu90TOW64hcatBNMVQsSVP+AAapUnv7SKnuW0RU9VB7mpIPnrpT3p8cbst+UW+r rXirnQPXeNgiNVjl0DgdR7gwOFazvzm78uX3JpDpa6co+4U699ueX7pYtHIVOo0BLoRG8p AE60yzerOjbD8Ypi1T/H4unifCTejuwSaDk2AIcuNe4wTxD+qIBFx2s7YGLwdxz+XxB4tX F22cK4tFeAKPxaAmUbkc+YnI+YiP9PslUarSnV3ZF7+YSZUNwmWVfCgk2+bI4vyV2vxEW/ qTUBvZ0Pwrt73gTuD1krEtvr31EE22hH4IZZhaHnddYXfc9zXC5/eelq6RjPOg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1674598350; 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=ZG3j1SPZ0BRPzPon05S9in9Adstaiaiq5zWXZIPdu8o=; b=VVYN/0ARyRZqxlDMowkcOwG6fT1LDxAeLznaFGTcFwJr72iCR4K7vn3LLgt/jeuEd3Vcn9 4mIfnCCD6bHRvqaHImUIPitROSfWHBWg8AP2RkQUAYg1aRa2tXAyRL/ZWgn/xN/2GH2j3d 0TGoaJ7hIjwih2fzNYdU8RlH/RZKv9lCSPYT+rTjmr4z/xPXZSdjZtMeRfHg9x0PqIoD9m kvbxWTf5MMJI6W5pDL2e4lMXaIZN+8sqrFg8ECFibD1q95Vtn9wAGqa+VKLFG09kzdU8HX MYGO20mp7BX1Gd1f8umvGC5B/S0M7c6WZ/F0ngpsj1I0Vf6HUstGbelcxp48gw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1674598350; a=rsa-sha256; cv=none; b=a3p/bPuZPWyUY1quF0qdPTevCt9eDqDEpBFZ3SAyXlOUWKEkgJOId6pu3cao/nMVHo/xYa x/5Sc9bU/ORFktr2HgBg9+W+rvELKO/fxWjlkdm4evsx+M7nQgK7zL0F7NQ7262dM9JqS6 NpxBU0t4M7dA5asrGfa0eNSS/QxvI9abuNOiAj6nc2Q4IeqKvomXGavjrr5QS+3VAp3Ae2 eL9qq9dq/b4+ah0qheHQXCmgfWqcYTusVTZv2u5RotCcztTnIP9fjy7oVjyQVmdtAMIZ4w DffK5V1jA59yOzYdKKEOHSEcxAQrsp09U9FgYH7C1Hx1lWtgbfffA9Lid2ypWw== 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 4P1h6Q3ry1zQfH; Tue, 24 Jan 2023 22:12:30 +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 30OMCUuJ087114; Tue, 24 Jan 2023 22:12:30 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 30OMCUIJ087113; Tue, 24 Jan 2023 22:12:30 GMT (envelope-from git) Date: Tue, 24 Jan 2023 22:12:30 GMT Message-Id: <202301242212.30OMCUIJ087113@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Warner Losh Subject: git: b9ec3ec2275c - stable/13 - 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/stable/13 X-Git-Reftype: branch X-Git-Commit: b9ec3ec2275c6788fb91ebb8b641d5cd637fbed5 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch stable/13 has been updated by imp: URL: https://cgit.FreeBSD.org/src/commit/?id=b9ec3ec2275c6788fb91ebb8b641d5cd637fbed5 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: https://reviews.freebsd.org/D35912 (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 .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