FreeLists / openbeosstorage / [openbeosstorage] Kernel Interface Design

["Tyler Dauwalder" <tyler@xxxxxxxxxxxxx>]

Hey folks, 

Sorry for being a bit quiet over the past couple of days; I
went to visit my mom over the weekend and got absolutely 
nothing done whatsoever.

I think it's time we started planning out what I'm going to 
from here out refer to as our "kernel interface". By that I
mean our bottom-level C functions that we'll initially implement
with POSIX and later implement with syscalls.

(one short note here: I'm calling them C functions, but I
don't see any reason we would be restricted to using pure C)

I made up a quick header and cpp pair with rough POSIX 
implementations of open() and close() to try and get a sense 
of some of the issues we're going to need to address in our 
design. There in CVS at:

/storage_kit/source/lib/kernel_interface.h
/storage_kit/source/lib/kernel_interface.POSIX.cpp

Please note that I haven't tried compiling these, I just
needed a place to start.


----------------------------------------------------------------------
1. Interface portability
----------------------------------------------------------------------

First and formost, we want to design our interface to be
as portable as possible, meaning we don't want it to work
fine with POSIX but then have to be changed when we
rewrite it to use syscalls. To that degree, I've started a
brief function dependency document in CVS at:

/storage_kit/docs/kernel_interface/FunctionDependencyReference.html

All I've done is list the NewOS and POSIX calls that each function
will depend on. This helps to give a sense of how each function will
need to be designed in order for it to work as an interface to both
the kernel and POSIX.

For calls that are not yet implemented in the kernel, we're
just going to have to make educated guesses based on
the calls that *are* implemented.

One thing I'd like everybody to do is just pick a few functions,
look up the user_* equivalent in the NewOS kernel (vfs.h) or
extrapolate a reasonable guess as to what it might look like if
it doesn't exist, figure out which POSIX functions and headers
are involved, and add said info to the list.

As I've mentioned before, the set of functions in our interface will
need to be basically identical to the set of functions in the vfs add-on
layer we documented. So use that list of functions as a base for
which functions we need to have in our interface that aren't currently 
supported in the kernel.

I guess just pick a few functions at a time, email the list saying
you're going to work on those, and do your thing. There are templates
in comments in the HTML file for the various sections you'll need
to update.


----------------------------------------------------------------------
2. Error handling
----------------------------------------------------------------------

We're going to want/need a uniform method of error handling.
We can either use exceptions or something depending on 
return values and/or output parameters. My vote's for exceptions
unless someone thinks that's a really bad idea.


----------------------------------------------------------------------
3. Data types
----------------------------------------------------------------------

There's not a lot of consistency between POSIX and the kernel API
as far as data types go. For example, open modes in POSIX are 
character strings, but in the kernel they're ints. I propose we create 
our own set of data types as needed specifically for this interface. 
These will end up being the data types we use throughout the entire 
Storage Kit, and I think having a well thought out set of types to work 
with will make our job easier and make our code cleaner. 

In some cases, we're not going to be able or want to change
data structures around too much. There's proabably no good
reason for a file descriptor to be anything but an int. Directory
functions are probably going to work with dirents. In other cases,
like open modes, defining our own enum of values will probably
be useful.

I'm also thinking it might eventually be a good idea to go through 
the Storage Kit and make up a dependency reference similar to 
the one for the kernel interface. Something a little more in depth
that lists off the kind of functionality each class provides and what 
sorts of data types it will need to sling around in order to accomplish 
what it's supposed to accomplish. We don't need to jump on that
just yet though. 



I think those are the main issues I wanted to address (it's really late,
so I may have overlooked some...). Look through the kernel_interface.* 
code and see what you think of the examples in there, and write up
a couple of dependencies as you're able. :-)

-Tyler