Subject: Re: CVS commit: src/share/man/man9
To: YAMAMOTO Takashi <yamt@mwd.biglobe.ne.jp>
From: Bill Studenmund <wrstuden@netbsd.org>
List: source-changes
Date: 10/24/2005 10:12:25
--+HP7ph2BbKc20aGI
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Mon, Oct 24, 2005 at 02:36:26PM +0900, YAMAMOTO Takashi wrote:
> > Module Name:	src
> > Committed By:	wrstuden
> > Date:		Thu Sep  8 22:51:36 UTC 2005
> >=20
> > Modified Files:
> > 	src/share/man/man9: buffercache.9
> >=20
> > Log Message:
> > Note the fact that buffer cache takes block numbers in
> > units of DEV_BSIZE, even if the device's device size is
> > larger. Update date.
>=20
> it's plainly wrong.

How is it plainly wrong?

sdstrategy() does DEV_BSIZE -> lp->d_secsize conversion, as does=20
cdstrategy(). wdstrategy() does the same. Thus the block number had to=20
have been in units of DEV_BSIZE to begin with.

I am very confused. As all the code I looked at actually works the way I=20
describe in the change, I fail to see how it is "plainly wrong."=20
Confusing, yes! Non-intuitive, yes! But that's what the code is doing now.

> besides, i doubt if it's appropriate to document
> specfs-specific things in this manpage.

What units are bread()'s blkno in?

Turns out they are NOT in the units of blocks on the device.

Thus documentation with bread() and bwrite().

This documentation also is the direct result of one of my SoC projects=20
stalling for about a week as the student assumed bno was in device blocks,=
=20
and then nothing worked. When he switched it to DEV_BSIZE blocks, things=20
started working.

I strongly believe that we need enough documentation so that someone=20
looking at this man page can figure out what units to use for blkno for=20
bread() and bwrite().

The belief above would be satisfied with a cross-reference to another man=
=20
page that went into this (assuming it was clear that you REALLY NEEDED to=
=20
look at the other page).

However the units used for block numbers in the buffer cache really seems=
=20
to me to be appropriate for "man 9 buffercache". This behavior doesn't=20
seem to me to be at all specfs-specific, so it seems fine to document it=20
here; what specfs-level code does is also what buffer cache code has to=20
work with.

Take care,

Bill

--+HP7ph2BbKc20aGI
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (NetBSD)

iD8DBQFDXRX5Wz+3JHUci9cRAjgGAJ9Qs6DhoxesdlhZHvlPP9JnX4it5gCfW62T
vBlQknyKGaob+QrF0AZ95xk=
=mv25
-----END PGP SIGNATURE-----

--+HP7ph2BbKc20aGI--