Page MenuHomeFreeBSD

Document disk ioctl
ClosedPublic

Authored by imp on Oct 28 2020, 11:21 PM.

Details

Reviewers
phk
scottl
imp
Group Reviewers
manpages
Commits
rS367847: Document disk ioctl

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

imp requested review of this revision.Oct 28 2020, 11:21 PM
imp created this revision.

This is mostly a cut and paste job from sys/disk.h.

rpokala added inline comments.
share/man/man4/disk.4
36 ↗(On Diff #78871)
40 ↗(On Diff #78871)

Since we're talking about multiple ioctls, this needs to be plural, i.e.

All the block devices in the system should support the different disk ioctl(2)s defined here.

I'm not sure what the syntax for that is though.

48 ↗(On Diff #78871)

calls apply to disk drives, and are defined

49 ↗(On Diff #78871)

Singular file.

56 ↗(On Diff #78871)
This is usually a power of 2, but might not be (i.e. CDROM audio).
59 ↗(On Diff #78871)

Don't double-space between sentences; linebreak between sentences.

85 ↗(On Diff #78871)

Move the define before it's used.

88 ↗(On Diff #78871)
Most of the time, the ident is a unique and fixed identifier for the provider.

What are the exceptions to "most of the time"?

94 ↗(On Diff #78871)
ident value is preserved between detach/attach of provider,
96 ↗(On Diff #78871)
ident value is preserved even if provider's name changes
99 ↗(On Diff #78871)

Comma after "words".

104 ↗(On Diff #78871)
there can be more than one provider with the same ident, but
only if they point at exactly the same physical storage.
This is the case for multipathing, for example.
106 ↗(On Diff #78871)

"consume"

107 ↗(On Diff #78871)
providers, like
.Xr geli 8
and
.Xr gbde 8 ,
should just attach the class name to the
110 ↗(On Diff #78871)
ident is a printable ASCII string

(Is it fixed-width, or NUL-terminated?)

116 ↗(On Diff #78871)
Given a device path, store the provider name in a buffer.

All this was cut and pasted from sys/disk.h, almost vebatim

In D26994#602203, @imp wrote:

All this was cut and pasted from sys/disk.h, almost vebatim

Then fix it both places, of course! ;-)

share/man/man4/disk.4
36 ↗(On Diff #78871)

The page you reference is misleading. FreeBSD doesn't have buffered block devices anymore. The line between block and char devices is thus blurred; a block device that doesn't interface through GEOM instead interfaces through a cdevsw, which makes only a passing distinction between character and block semantics.

share/man/man4/disk.4
36 ↗(On Diff #78871)

Thanks! I've been confused by this assertion for years, since obviously disk-like devices can only do block-sized IO. Can we clean up that page?

(But that also raises the question of the distinction between "buffered" vs "cached", since we obviously do keep stuffed cached.)

danfe added inline comments.
share/man/man4/disk.4
56 ↗(On Diff #78871)

As CDROM audio is an example here, it should be e.g., not i.e.

share/man/man4/disk.4
66 ↗(On Diff #78871)

Don't use contractions in the manpages. :-)

73 ↗(On Diff #78871)

Ditto.

Well, I wrote a lot of that text myself, so I can hardly disagree with it.

share/man/man4/disk.4
36 ↗(On Diff #78871)

Technically they are "blocked devices" rather than "block devices", but that may be a too fine distinction ?

55 ↗(On Diff #78871)

It might be worth mentioning here, that the device can only be lseek(2)'ed to (N*sectorsize).

This revision is now accepted and ready to land.Oct 29 2020, 7:50 AM
imp marked 10 inline comments as done.

I've made changes to the man page as suggested above for the most part. I'm going to go ahead and commit this since I think there's little value in waiting for more review at this point. If there's issues you see after I commit (or that I overlooked), please let me know and I'll fix them then.

share/man/man4/disk.4
40 ↗(On Diff #78871)

The usual construct applied here would be "disk ioctl(2) commands"

85 ↗(On Diff #78871)

Given the formatting, that turns out to be difficult.

This revision was automatically updated to reflect the committed changes.