svn commit: r349791 - head/sys/vm

[Bruce Evans]

On Mon, 8 Jul 2019, Scott Long wrote:

> This isn’t the first time I’ve witnessed your passion on this topic.  It would
> help immensely if there was some documentation, maybe in /sys/sys/param.h,
> or maybe even in a manual page, on what a “click” is, what a “db” is, why
> they’re important, and how they should be used.  Do you have any
> documentation tucked away that could be edited and committed?

I don't have any extra documentation.

I learned about clicks because Minix had them and actually used them in a
nontrivial way (1 click = 16 bytes = real mode segment granularity, and
16-bit ints could could represent the final click address in the real-mode
address space of 1MB but not the size of the whole address space).

Mike Karels gave more details about this.  PDP-11's had 64-bit clicks.  I
think this was also to extend the 16-bit address space in a less bad way
that x86 real mode segments.

Google says that NetBSD has dbtob(9).  This is a link to ctod(9).  This
man page does little more than say "The ctod family of macros can be
used to convert between bytes, pages (''clicks'') and disk blocks" and
expand the abbreviations.  'c' is expanded to 'pages', and there are
no documented macros where 'pages' is abbreviated to 'p'.  The full
list is:
- ctod (spelled ctodb() in FreeBSD),
- dtoc (similarly),
- ctob,
- btoc,
- dbtob (same spelling as in FreeBSD).
- btodb.
One detail is interesting: that the macros make no assumption about
the type of the input parameter (this is clearly wrong since signed
types with negative values don't work when the implementation uses
shifts, floating-point types are further from working, and
non-arithmetic types can't work), and that the caller must ensure that
integer overflow and integer underflow do not occur (here "integer
underflow" is nonsense" -- it means integer overflow to a negative
value).

4.4BSD-Lite2 has these macros with the NetBSD spellings, and also on
i386, tahoe and vax:
- ctos, stoc: core clicks to segments.  All do the identity conversion.
   None are used on any arch.

FreeBSD-1.0 has similar or the same macros as 4.4BSD-Lite2, including
implementation and comments.

FreeBSD-3 doesn't have ctos or stoc, and abbreviates 'disk block' to
'db' consistently, and improves some of the implementations and
comments.

FreeBSD-current is similar to FreeBSD-3, except most of the macros are now
MI and it has lost better comments which were only in the alpha version.

FreeBSD's <sys/param.h> actually documents most of these macros
reasonably well in comments.  It just uses different styles and random
grouping.  Only btodb and dbtob end up without a comment giving a hint
about what b and db are.  The comments for dbtoc and ctodb tell you
that a db is a devblk and a c is a page.  Other comments tell you that
a c is a click.

Bruce