Re: API/ABI rank of headers in /usr/include/isofs/cd9660

[David Holland <dholland-tech%netbsd.org@localhost>]

On Wed, May 28, 2014 at 06:22:16PM +1000, matthew green wrote:
 > > On Wed, May 14, 2014 at 08:00:56AM +1000, matthew green wrote:
 > >  > thanks for looking at this.  we've gotten better since early
 > >  > days with these sorts of issues, but there are still a lot of
 > >  > headers that are installed for no good reason but no one has
 > >  > had the chance/motivation to clean them up yet.
 > > 
 > > It's not that so much as cleaning it all up properly requires cvs
 > > rename, which unfortunately fails to exist. Otherwise I'd have done it
 > > years ago.
 > 
 > i don't see why that matters in the vast majority of cases that
 > are just like this one -- headers that were never useful for
 > userland were installed because of history (the original scripts
 > were find ... -name \*.h, with some filters, IIRC), not because
 > we need to shuffle their contents around to make it so.  all we
 > have to do is, like this case, simply not install them.

Well... at least in the case of ufs (dunno about cd9660) the
definitions are all mixed together. And, worse, ffs doesn't even
distinguish the in-memory and on-disk superblock structures.

If there are some that can just be punted from userland, then we
should do that, but between kmem grovelers and other mess I'm not sure
there are really that many.

For fixing things like ufs the best way to do it is to pick up the
minimum set of decls that actually public and move them to a new file;
for best long-term results that file should be in a reserved place for
such files (so among other things it doesn't end up part of the
supported API) ...and setting up such a place and populating it really
wants rename.

That doesn't mean we couldn't start with things like the ufs headers
and do more incrementally or even leave things halfway until we solve
the SCM problem. But I haven't been entirely inclined to push ahead,
especially since creating src/sys/include isn't universally popular. :-)


Since maybe there are passersby who haven't seen the plan before:

   userland-only includes in src/include, src/include/sys;
   kernel-only includes in src/sys/include, src/sys/include/sys;
   shared includes in src/sys/include/kern;
   src/sys/include/kern/*.h gets installed in /usr/include/kern;
   no filename in src/sys/include/kern is part of any supported API
      (all code just includes <sys/foo.h> or whatever, and that header
      includes <kern/*.h> headers as needed);
   shared MD header files go in src/sys/arch/foo/include/kern with the
      same rules;
   standard C headers that can be provided in the kernel environment
      can be placed in src/sys/include, e.g. <stdarg.h>.

I think I get to claim this is proper after laying out a number of
research kernels and getting it wrong the first two or three times,
but everyone's of course welcome to disagree with me.

The choice of "kern" for the kernel headers directory is necessitated
by the fact that "sys" is already taken. (In fact, sys/ was originally
just the place for for kernel headers; but years of abuse, bad design,
standardization, and cruft accumulation has resulted in about 1/3 to
1/2 of sys/ belonging to userland; with the organization we currently
have all this stuff sits in the kernel include directory and gets in
the way.) Something other than "kern" could be used but "kern" seems
like a reasonable choice.

Note that while in this scheme some or all non-exported kernel things
could be migrated to be top-level headers (e.g. <sys/proc.h> ->
<proc.h>) there's probably little benefit to this in the short to
medium term.

Anyhow, creating this setup requires wholesale moves. I don't think
it's really a very good idea to create the file that should be
e.g. <kern/ufs.h> as some other name with the expectation of changing
it later. And like I was saying above, I think it isn't a great idea
to create src/sys/include/kern and put only a handful of things in it.
Partially completed migrations are horrible mudpits for large projects.

-- 
David A. Holland
dholland%netbsd.org@localhost