Page MenuHomeFreeBSD

stand: Add driver interface docs
ClosedPublic

Authored by imp on Jul 25 2022, 8:32 PM.
Tags
None
Referenced Files
Unknown Object (File)
Fri, Apr 5, 8:18 PM
Unknown Object (File)
Fri, Apr 5, 8:10 PM
Unknown Object (File)
Fri, Apr 5, 8:09 PM
Unknown Object (File)
Fri, Apr 5, 7:20 PM
Unknown Object (File)
Fri, Apr 5, 7:20 PM
Unknown Object (File)
Fri, Apr 5, 7:09 PM
Unknown Object (File)
Feb 4 2024, 5:38 AM
Unknown Object (File)
Jan 30 2024, 5:53 PM

Details

Summary

Add some rather bare-bones driver interface docs.

Sponsored by: Netflix

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

imp requested review of this revision.Jul 25 2022, 8:32 PM
rpokala added inline comments.
stand/libsa/libsa.3
717

"The name of the device."

719

Is this really an int, or is it actually an enum? Perhaps an enum value stored in an int?

In any case, if there are limited valid values like an enum, then they should be listed somewhere.

723

"Drivers are"

pauamma_gundo.com added inline comments.
stand/libsa/libsa.3
719

Clarify "Gross". Rough? General?

761

While here, why isn't this just .Nm?

This revision now requires changes to proceed.Jul 26 2022, 10:20 PM
stand/libsa/libsa.3
719

Is this really an int, or is it actually an enum? Perhaps an enum value stored in an int?

int with #define values. This code is a bit old-school having been around 25 years :)

Roll all the review feedback into this update (hopefully)
Bump date based on the target commit date.

stand/libsa/libsa.3
719

Is this really an int, or is it actually an enum? Perhaps an enum value stored in an int?

int with #define values. This code is a bit old-school having been around 25 years :)

Missed this response earlier. That's close enough to "enum" for our purposes here. :-)

The list of valid values should be referenced in some way, either by being listed in this document, or with a pointer to the file which contains the #defines.

722

This is C, so clarify what you mean by "subclass".

(In this case, from grepping through the code, it seems like you mean that there are multiple 'struct foo_devdesc', each of which have 'struct devdesc' as the first field'.)

Based on my previous comments, I suggest something like this for dv_type:

.It 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.

(The markup might need a little tweaking, particularly the references to the structures, but that should be in the right ballpark.)

Minor enough to fix when committing.

stand/libsa/libsa.3
509

Or "device passed in"

718

Parallel with "file name", "path name", "street name", etc.

743

(or "devdesc passed in")

This revision is now accepted and ready to land.Jul 29 2022, 11:41 PM

I'm going to commit what I have...
I think I got all the suggestions, but please reply if I have missed some or more occur to you...

This revision was automatically updated to reflect the committed changes.
In D35912#829187, @imp wrote:

I'm going to commit what I have...
I think I got all the suggestions, but please reply if I have missed some or more occur to you...

https://reviews.freebsd.org/D35912#inline-221612 missing. If not deliberate, race you to fixing it.