Page MenuHomeFreeBSD

intro(9): rewrite from scratch
ClosedPublic

Authored by mhorne on Jul 19 2023, 8:55 PM.
Tags
None
Referenced Files
Unknown Object (File)
Tue, Nov 12, 11:37 PM
Unknown Object (File)
Tue, Nov 12, 2:54 AM
Unknown Object (File)
Tue, Nov 12, 2:54 AM
Unknown Object (File)
Tue, Nov 12, 1:46 AM
Unknown Object (File)
Fri, Nov 8, 4:50 AM
Unknown Object (File)
Thu, Nov 7, 9:50 PM
Unknown Object (File)
Thu, Nov 7, 12:34 AM
Unknown Object (File)
Wed, Nov 6, 2:32 PM

Details

Summary

This page has existed as a placeholder since its creation in 1995. It
does not provide a useful introduction to the content in this section.

Reimagine it as a top-level overview page containing brief descriptions
and links to existing pages in section 9. It is roughly organized into
sub-sections, grouped by topic or subsystem.

There is a balance to be found here between providing as many links as
possible and keeping the page concise and searchable. In general the aim
is to reference pages which provide the best entry point to a particular
topic. For example, a link is given to locking(9), but not to the
specific lock pages such as mutex(9) or rwlock(9).

NetBSD has done something similar with their intro(9), so some
inspiration has been taken from there, although the content doesn't
align with what we have that closely. I have done a thorough review of
our existing pages and formed these subsections around them, but they
are meant to be flexible, not set in stone.

*Reviewer Notes:*
Descriptions are still a WIP, and are not all complete or consistent
yet. For the first draft I am looking for feedback on the content (e.g.
accuracy of statements, what is included or ommitted) and organization,
but not necessarily formatting or word-smithing.

As much as possible, I would appreciate fully-formed text suggestions.
There is a lot of content here.

Test Plan

For the rendered output see P595. I intend to keep it updated.

NetBSD intro(9): here

Diff Detail

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

Event Timeline

mhorne created this revision.
share/man/man9/intro.9
20

we should maybe just call them "programming interfaces" rather than APIs, or "Kernel Programming Interfaces (KPIs)"

27
221

pfil is the interface used by firewalls (ipfw, pf) while bpf is the interface used to pass (some subset of) packets seen on an interface to userland

share/man/man9/intro.9
19
22
26
The documentation in this section is written for developers, by developers.
46
54–160

Handle comments + a few small additions.

mhorne added inline comments.
share/man/man9/intro.9
26

Thanks, but I prefer the original phrasing. Perhaps it seems a bit clumsy, but stating the two separate points explicitly results in a stronger statement.

221

Thanks, please see what I have now.

This looks good to me. I'll try to give it one more read over from top to bottom, but IMO it's at the point where we can commit it and iterate further in tree if needed.

mhorne marked an inline comment as done.

A few more expanded descriptions/consistency improvements.

mhorne retitled this revision from [DRAFT] intro(9): rewrite from scratch to intro(9): rewrite from scratch.Jul 31 2023, 7:11 PM

This looks good to me. I'll try to give it one more read over from top to bottom, but IMO it's at the point where we can commit it and iterate further in tree if needed.

Thanks, I feel the same, so I will aim to commit it this week!

It's OK but needs a lot of work on organization. It's kinda all over the place. It's OK enough to commit though.

share/man/man9/intro.9
1–2

I'd be tempted to remove this boilerplate

34

I'd revise this after committing... it seems kinda out of place and too apologetic... but not so much as to hold it up.

253

It would likely be better to have a separate man page for newbus and driver writing... this is an ok stand in for that...

519

Design and implementation of FreeBSD reference here?

This revision is now accepted and ready to land.Aug 1 2023, 1:07 AM
In D41104#939612, @imp wrote:

It's OK but needs a lot of work on organization. It's kinda all over the place. It's OK enough to commit though.

Yes. It is a reflection of the content that we have, meaning it is wide-reaching and scattered. Constructing a cohesive map of this collection is incredibly difficult, and so a lot of time and thought went into producing the version you see here.

In lieu of specific feedback on the structure, which I appreciate is time consuming to give, maybe you can elaborate on your expectations/hopes&dreams of what this document should be. That would be of use to me.

Remove copyright boilerplate.

Remove trivial 'Start-up and Shutdown' subsection.

This revision now requires review to proceed.Aug 2 2023, 3:33 PM
mhorne added inline comments.
share/man/man9/intro.9
519

I considered it and am ambivalent. It seems right to add it, but feels wrong, so *shrug*.

share/man/man9/intro.9
301

maybe "not permitted" rather than "not guaranteed", and it should then probably be "Direct read/write access" or something like that.

Direct read/write access to userspace memory from the kernel is not permitted, and

519

It seems reasonable to me to add it

This revision is now accepted and ready to land.Aug 3 2023, 12:47 PM
This revision was automatically updated to reflect the committed changes.