KallistiOS 0.80 FAQ
(c)2001 Dan Potter

Here you may find some answers to some common questions we hear
regarding the usage of KOS. We will be adding more to this file over
time, but perhaps these can help you get started.


1 --- Kernel and Userland -----------------------------------------------

1.1

Q) What is the difference between linking libkallisti into my program,
and linking libk for a userland program?

Q) I am trying to link libkallisti into my userland program but some
things don't work right.

Q) What is the difference between kernel and userland anyway? What are
the advantages of each?

A) We hear a lot of these types of questions, and I figure it's probably
time to go ahead and clear these up. Most of the misunderstandings stem
from the fact that both the kernel and the userland library and examples
are distributed in the same package, and also that you can link the
kernel itself into your program. Many people who are writing DC software
have not really had much exposure to a true embedded environment before
and so this confusion is understandable. Software like QNX Neutrino has
worked this way for quite a while, and that's the model we're using.

Basically what you need to do to understand the distinction here is to
think back to whatever OS you are using right now for development, be
this Windows, DOS, a *nix flavor, etc. I'm going to use Linux as an 
example, but the same basic idea is true of any user OS. For Windows,
you could replace "Linux kernel" with "Win32 kernel" and "init" with,
say, "Explorer" (not entirely accurate, but close enough).

There are two very distinct parts to this OS at the top level. Further
down there are more parts, but at the top level there are only two: the
kernel and the userland. The kernel is what is responsible for the
hardware, multitasking, global memory allocation, and allowing programs
to communicate effectively. Generally the kernel itself does not perform
any more tasks than that. The actual functionality is delegated to the
userland, which is generally isolated from the hardware and
multitasking. In Linux, the kernel is what is really called "Linux" --
it is a downloadable piece of code that you can recompile for many
platforms, and it has no function besides managing the hardware and
other global tasks that individual applications should not have to
handle (file systems, networking, etc). This Linux kernel layer is what
lets me do things like run a file manager on both a VFAT partition and
an Ext2FS partition with no changes to the app itself. When Linux boots,
it initializes its hardware and other subsystems, and loads a program
called "init", which is a userland program. This program is isolated
from the kernel, the hardware, and any other userland programs that may
be loaded after it. It also handles the loading of other userland
programs, but that is by OS design.

Now what you can do with Linux is actually pull out its main init
routine, and instead of loading the "init" userland program, you could
make it do something like play MP3s. In this case you are coding
directly at the kernel level, have full access to the machine and all
pieces of the operating system, and are running at the fastest potential
machine speed. You are also at risk of overwriting some important kernel
structure (bringing down the machine unexpectedly) and your kernel has
no other purpose than to play MP3s.

This is a very uncommon practice with OS's like Linux that were designed
as more of a desktop environment. It's a lot more practical with
embedded systems that are designed to be used in things like ATM
machines. In that case the added overhead of actually making a
kernel/userland distinction (both processor time and memory usage) are
not worth the advantages, which are almost nothing.

This is the dilemma you get to choose from when you develop a program
using KallistiOS. You can choose to link the kernel directly, and you
will have full control over what happens inside that kernel. You can
enable or disable threads at any time, you can tweak a lot of internal
things in the TA module, etc. However, once we actually publish a
standalone bootable version of KallistiOS, your program is off limits to
all the users of the standalone KallistiOS who might use that version.
They will have to exit and boot into your version, and that's all that
can happen. Permanently, in a fashion, because you'd have to actually
port your program from a kernel-space program to a userland program
before it could cooperate with other tasks on the system. This is one
big advantage to using a userland program from the beginning: it's
fairly easy to write a userland app and then port to a kernel-space one
by pulling services like you'd normally do in a userland app, but it's
fairly difficult to go the other way once you have started tapping into
the internals of the kernel.

There are other advantages to writing a userland app as well. For one,
different people may be running different kernels. I could be running on
a hacked up custom bus that includes a hard disk and an ethernet card
like a 3c503, and Joe Schmoe could be running on just the official
broadband adapter. If you are running as a userland program, you will be
using the KOS exported API for network access, and thus it will run on
both machines identically. If you do not, then one or the both of those
people can not use their network access. This is the same problem that
the official Sega software has, since they have basically decided to
link a kernel into their apps. Older apps will never be able to use the
ethernet because they simply don't contain the neccessary driver code.
In an ideal world, there would be one networking API that would take a
few settings (perhaps) and establish a TCP/IP connection without telling
the game what it did. This is much more like the PSX model. Instead,
there is a full stack inside each game, each stack with its own quirks
and abilities.

All isn't rosy: it's a bit of overhead to manage opening the userland
ABI libraries and so on. They will run a bit slower because of the extra
pointer redirection (though on the SH-4, due to the way the C compiler
writes code anyway, this is somewhat negligible). Additionally, all
these advantages I've been talking about with process protection simply
don't exist in the simple world view of KOS right now (there is no MMU
support to prevent apps from trampling on eachother). We still recommend
that you make userland apps, however, because once the kernel is more
complete and stabilized, you will be glad you did it.

The other thing that has perhaps been confusing people is that you can
include userland binaries and other arbitrary data into the kernel image
itself during compile time. All this does for you is make your files
show up under /bi or /rd. Compiling a userland binary into the kernel in
this way _does not_ imply that it is running as part of the kernel.


1.2
Q) How can I run a userland app that someone else has posted on the web
somewhere?

Q) How can I get my own userland apps to run?

A) When the standalone version of KOS is posted, this will be a LOT
easier. However, until that time what you have to do is one of two
things:

  - Burn it on a CD with a custom KOS kernel image that loads your
    program from the CD and runs it instead of /bi/init.elf
  - Load your program into the kernel image in place of the default
    /rd/init.elf

For #1, you just need to change the name of the loaded program from
/bi/init.elf to /cd/yourprogram.elf in kernel/main.c and recompile. For
#2, you'll need to replace kernel/romdisk_boot/init.elf, delete
romdisk_boot.o, and let it recreate the image. If you didn't understand
that, then please hold off until we have a standalone version.


1.3
Q) How can I use kernel functionality that isn't exported (yet)?

A) Right now the only thing you can do is write the program as a linked
kernel or write a new ABI for yourself. If you want to do #2, let me
know so that we can discuss it and we might include that ABI in the
future release versions.


2 --- Memory Allocation ------------------------------------------------

2.1

Q) How can I determine how much RAM I have allocated / how much RAM my
program is using? 

A) This won't always be accurate, but in the kernel space you can call
malloc_stats(). The output is sent to the kernel console. Eventually we
might export this into a debug ABI.


2.2

Q) My malloc()'s are failing. Why?

Q) I tried malloc_stats() and it claims I allocated like four billion
bytes of RAM!

A) You probably have a pointer overrun somewhere. Unfortunately these
are rather difficult to debug for now in KOS since it has no MMU
support. I recommend old school debugging (calling malloc_stats() every
so often to see when it bombs and narrowing it down, or perhaps
commenting out blocks until it works again). Eventually we'd like to
have a Linux version of KOS. Yes, if that sounds weird, see below.

3 --- VFS ----------------------------------------------------------

3.1

Q) What exactly is this VFS thing? Why should I use it?

A) VFS stands for "virtual file system". All it does is bring together
several disparate name spaces into one convienent API. VFS is the
hallmark of a *nix system: "everything's a file". In KOS that's not
quite that true, but it is handy. For example, you can put a file on a
CD and it shows up in /cd, or you can build it into the kernel and have
it show up in /bi or /rd. In the case of /bi, you could even have dynamic
"files" that change at runtime. Or perhaps it's coming over the network
from your PC in /net. Either way, all your programs will use the same
exact API calls to access the files.


3.2

Q) What VFS modules are available?

A) Presently there are five:

- Builtin -- mounts on /bi, and reads files from an internal array built
into the kernel (thus the name). This lets you embed bootstrap userland
code into the kernel, data files, etc. It's also non-permanent (like a
CDR) so if you are uploading test images you can put test files here. A
little known trick of /bi is that you can put an arbitrary pointer into
the table and tweak both the pointer and the file size at runtime, thus
providing proc-like functionality.

- ISO9660 -- mounts on /cd, and is a decent implementation of the
ISO9660 file system standard used on CDs. Note that because of the
simple nature of KOS's block devices right now, ISO9660 is bound
directly to the CD-Rom device. In the future this may change.

- SerConsole -- mounts on /pc, connects to a PC-hosted program, called
'konsole'. Note that recent versions of dc-load have a similar fs you
can add to KOS that does about the same thing. All the files in the
current directory of konsole will show up here. Note that this doesn't
seem to work right now if you enable threading.

- VMU -- mounts on /vmu, what it sounds like. This dynamic file system
shows all detected VMU or memory cards on the maple bus and lets you
browse and read/write them. Note that it's fairly primitive right now
and has been known to corrupt cards on writing.

- Romdisk -- mounts on /rd. This is an implementation of the Linux ROMFS
file system. Right now it only supports one directory (you can have a
tree in the ROMFS image, but the fs won't see it) and no listings. In
other words, about the same functionality as the old builtin system. As
time goes on I will be working on this to make it more fully functional.


3.3

Q) How can I make images for the romdisk file system?

Q) Where can I get this genromfs program to make ROMFS image for use
with the romdisk file system?

A) This is a Linux utility (it's a Linux-specific file system.. well
it was until a few days ago anyway }-D) called genromfs that does
this for you. Here is a URL:

ftp://sunsite.unc.edu/pub/Linux/system/recovery/genromfs-0.3.tar.gz

Additionally, I have provided a copy of this program for your convienence.
You will need to edit kernel/Makefile to change the paths if you want
it to work "out of the box". If you are using Cygwin you will also
need to make sure there's a /tmp path mount for bin2o's usage.


4 --- Networking ---------------------------------------------------

4.1

Q) Does KOS have any kind of TCP/IP stack? Network support at all?

A) No. It will probably have something pretty soon now that I've gotten
my hands on a BB adapter finally. 


4.2

Q) Ok, what _will_ it support?

A) Can't really tell right now, but I can say safely that it will
probably only support very basic IP/ICMP level access at first, and move
on from there. Once we have a better stack in place, we'll have
relatively full TCP/IP capabilities.


5 --- Building -----------------------------------------------------

5.1 

Q) I'm having an issue building KOS; it gives me errors about not
finding Makefiles or not finding include files.

A) Make sure you check the paths in _both_ Makefile.globals and
Makefile.prefab. I'd like to find a better way to handle this in the
future (perhaps some kind of config script?) but at least those are the
only two places you ought to have to change.


5.2

Q) I grok the userland thing above, now once the kernel is built, what
do I do with it?

A) You have two choices for running your program: either take the file
kernel/kallistios.bin and upload it over your serial cable or ethernet
card, or scramble it and burn it on a CD; or you can use the Makefile to
do the steps for you if you're using dc-load/dc-tool. The way this works
is to use the 'run' target in the top-level or kernel Makefiles. You
can also modify your Makefile to use something like netcat to send
to Marcus Comstedt's IPLOAD program. This version of KOS seems to work
fine with it (and if you use IPLOAD 1.002, it exits back gracefully
as long as your program didn't do anything weird).


6 --- Debugging ---------------------------------------------------------

6.1

Q) Is there ever going to be an easier way to develop KOS apps besides
this tedious libdream-like method?

A) Yes, there are two distinct possibilites coming up.

First is developing using a network connection. The way this works is
that we'll have a program like konsole and a VFS like fs_serconsole, but
it uses TCP/IP. This is obviously a little ways off, but it will allow
you to boot KOS itself (perhaps KOSH) and then run programs off your
development machine at will. It will also completely eliminate the need
for a serial cable because all console i/o can happen over ethernet
packets, and the host program will provide NFS-like file sharing.

Second is that we're planning to implement KOS under Linux-SH at some
point. This sounds weird but it's one of the advantages of having a
microkernel architecture that works like ours does (Amiga-style). Amiga
themselves are actually doing this in their next generation AmigaOS.
What this gives you is binary API compatability with KOS, but your
program runs under the Linux kernel and gets all of its memory
protection advantages, a debugger, etc. Note that this will probably
only be an option if you are making a userland program.


6.2

Q) I don't have a serial cable so how can I see the debug output?

Q) I want to use the serial line but the pesky kernel debug output is
getting in my way.

Q) I am writing a userland app / set of apps that will want a stdout but
I don't want it to go to the serial port.

A) There are two stdout redirection mechanisms in KOS, depending on
whether you're working at the kernel or userland level.

For the kernel level, you will want to use ps_set_printk() (defined in
process/process.c). This function will return the old printk in case you
just wanted to filter. For userland level, you can actually do something
evil and tricky (which may eventually be banned ;-), and replace the
printf pointer in the fundamental ABI. Make sure if you do this that you
put it back normal when your program exits.

We're working on a generic method for cleaning up resources such as
these, but it's going to have to wait until there is real process
support instead of just threads with loadable modules.


6.3

Q) Can I trace through KOS using GDB or similar?

A) Yes, in theory. It will run just like any other DC program (like a
libdream app) but you will have to be aware that there are interrupts
enabled and they are extremely relevant. They are used in things like
PVR page flipping and rendering, threading, and will be used other
places later on. Additionally, you can have things like the DC's boot
ROM itself being multitasked in a thread during CD access! So be
careful!


--- End ------------------------------------------------------------

KOS Version Id: $Id: FAQ,v 1.3 2001/02/05 00:29:46 bard Exp $
