KallistiOS ##version## FAQ
Copyright (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.


0 --- Licensing ---------------------------------------------------------

0.0

This section is NOT legal advice. It's just a help to people who are
having trouble with the myriad free software / "open source" licenses.


0.1

Q) What is the new BSD/KOS license? What exactly do its terms mean?

Q) Can I make a proprietary / "closed source" program using KOS?

Q) Can I distribute "forked" versions of KOS?

A) The BSD license is pretty well understood among the free software
community, but I'll go ahead and give a layman's description of it here.
Basically what it says is that you can use the code in any of your
programs (proprietary, free/"open source", etc) as long as you don't try
to remove or change the copyright notices, and you don't try to
advertise your program as if it's endorsed by us. You may also
distribute changed versions as long as they are clearly marked as such
(often called a "fork"). This is a layman's description, it is not a
replacement for reading and understanding the license itself. If you
don't understand it, please find a lawyer friend to help you with it.

Sorry for being so terse about this, I'm just sick of "intellectual
property" battles. That and people somehow equate the BSD or X11 license
with "I can rip and use this code with no credit". This is absolutely
false. You may also not include the KOS code (or any other copyrighted
code) in your program verbatim without credit and a copyright notice.
Very small pieces are probably alright, but anything substantial must
have something to the effect of "derived from blagh.c in KOS 1.1.x".
It's really a very small price to pay for this nice code library you
can pull from freely :)


0.2

Q) What is the GPL license? What exactly do its terms mean?

Q) Can I make a proprietary / "closed source" program using XingMP3?

Q) Can I distributed "forked" versions of XingMP3?

A) The GPL says (again, in layman's terms) that if you make a derivative
work (e.g., use its code in your program), then your program must be
distributed under the terms of the GPL. Note that this does not mean you
must change your license, as some people would say (excellent example:
the Linux kernel contains BSD-licensed code, and BSD's kernel contains
_optional_ GPL'd kernel modules). It does, however, mean that you must
follow the GPL's terms for distribution. Additionally, if you make
significant changes to the XingMP3 library (a direct derivative) then
you must make the result licensed under the GPL.

I use XingMP3 as the example here because it is going to be the one
people have the most encounters with in their own programs. Genromfs is
distributed along with KOS (aggregated) but is not part of it. XingMP3,
however, is also "aggregated" but becomes a part of your program if you
link the MP3 playback library. So if you want to do this, pay attention.

This example is most analogous to the BSD kernel situation. They have a
GPL'd math library that may be linked with the BSD kernel, but the
resulting binary must always be accompanied by all of its source code
(i.e., distributed under the terms of the GPL). The same is true with
your own programs. You may not use the MP3 library without following
similar restrictions: you may license it under any GPL-compatible
license, but you may not distribute any part of it as a proprietary
application.

You may distributed "forked" versions of XingMP3, following the same
restrictions. They must be licensed under the GPL license. You may add
entirely new files to the library, licensed under a different license,
but they must be distributable under the GPL's terms.

Now then, if you don't like those restrictions, you are free to replace
the XingMP3 engine with something else. In fact I would be overjoyed if
someone provided me with a BSD-licensed MP3 engine. But for now, those
are the breaks. Sorry.

Also, to keep you safe from accidentally linking GPL'd code into your
program, 100% of this code is located inside the "xingmp3" tree in the
"addons" tree. All headers in the global "headers" tree are either ours
or otherwise BSD-style licensed.


1 --- OS Basics --------------------------------------------------------

1.1

Q) Why do you call this an "operating system" if it's just a library?

A) This seems to be a point of common confusion. Most of the
misunderstanding stems from the fact that both the kernel and you can
link the kernel itself into your program. Many people who are writing
software have not really had much exposure to a true embedded
environment before and so this confusion is understandable.

The most common definition for an OS I've heard is a program or API
layer which translates something undesirable to work with (for example,
raw hardware) to something desirable to work with (for example, fopen(),
fread(), fclose(), etc). You could group a lot of things under this
definition, like a JVM -- you are taking an unruly and unportable
OS-level API and translating it to something that is the same for all
platforms, even down to the binary code. To be more precise about the
common meaning though , the "undesirable" state is actually raw hardware
and the "desirable" state includes some way to run multiple tasks at
once, a virtual file system, hardware drivers, perhaps a TCP/IP stack
and other such services.

In a standard OS like you might run on your development workstation, the
OS "kernel" is what performs these tasks, and it provides an interface
for normal programs ("userland") to talk to the OS and other programs in
a very controlled manner. It is easy to see how this userland layer is
just another abstraction which isn't really even necessary if you don't
want its features -- and on a console where you must take advantage of
being as close to the hardware as possible, it will just get in the way.

Thus what ends up happening is that you link your "userland program"
directly into the kernel itself, and this is loaded on the target system
all at once instead of in two pieces. Your program also gets full,
unfettered access to everything the kernel can do; so if you don't like
the way it does something, you can change it.


1.2

Q) What's a virtual file system, and why do I want one? Why don't I just
talk directly to the device I want to use?

A) A virtual file system is basically an object oriented multiplexer for
a generic file interface. What that means in human-readable terms is that
it translates a full path name to a device handle plus a device name. For
example, if you access "/cd/foobar.txt", and "/cd" is mapped to the
CD-Rom driver, then you will actually access "foobar.txt" on the root of
the CD-Rom device.

To fully appreciate this design decision, you must port a load of
software to KOS. :) But the quick answer is, it provides a (mostly)
uniform interface to any sort of storage medium. This way, for example,
the PNG library doesn't need to know that it is loading files from a
VMU, from inside an internal ROM image, from over the network, etc...
all it knows is that it has a file descriptor it can use to access that
data. With the concept of a working directory, this allows you to very
easily switch targets during development. For example, you can use all
relative paths to identify your files (no leading slashes) and then put a
fs_chdir at the top of your program to switch to the file source, whether
that's over the ethernet using a loader or from a CD.


1.3

Q) What are threads? Why do I want to use them?

Q) Why are we wasting resources with such a silly thing on a console? Why
don't you ninnies code like real men and do your own task multiplexing?!

A) Threads are basically very light-weight processes or tasks. It is a
simple way to get the system to do more than one thing at once without
explicitly taking control over that switching, such as making a load of
"per frame" calls to do things like sound mixing. A very simple example
of something that is very difficult or impossible to do without threads
is a 3D "loading" display during a large batch load of data from a CD or
other VFS device.

Yes, the second question has actually come up a number of times. :)
Especially from people disenfranchised with the removal of non-threaded
mode from KOS earlier. This was a design decision that was made to
prevent the continuing spread of code that looked like this:

if (thd_enabled) {
	do one thing;
} else {
	do something else;
}

The better, and somewhat counterintuitive answer, is that threading can
actually _improve_ your program's performance. Most people who dislike
threading point to context switch overhead (saving and restoring the CPU
state when switching threads), and this is a valid concern (and is
certainly a problem on a purely computational set of tasks). However,
with a properly written set of drivers, OS core, and user program, the
OS can get a much better picture of what is going on and optimize task
scheduling. Remember, most hardware usage involves a lot of busy
waiting which you could spend doing something useful with the CPU. For
example, let's say you are doing a 3D display and playing back an MP3
while loading from the CD. The system state might look like this:

- One thread handling 3D display at higher priority, so that it will
  always get scheduled when the 3D card is ready for more data; when it's
  waiting for the next frame, there's no need to even schedule it.
- One thread that is reading MP3 data from some source (perhaps a ramdisk
  on the VFS) and decoding it for output buffer. Again, it will spend most
  of its time waiting for sound to finish playing back.
- One thread handling data loading from the CD, which spends most of its
  time waiting for data to come back (thus it has no need to even be
  scheduled until something is ready). This thread could be lower than
  normal priority so it would not cause skipping or frame drops with the
  other two.

Assuming properly written drivers for all of the above, the OS could see
what was going on at any given moment and schedule accordingly. And I
think we can all appreciate the considerably reduced complexity from
decoupling all three tasks.

On the other hand, the drivers in KOS aren't very efficient at thread
usage still. This is mostly a left-over vestige from the days when
threads were optional (and when we had less info about hardware IRQ
support), and is slowly being worked out.


1.4

Q) What VFS modules are available?

A) Presently there are six:

- 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. This is
DC-only.

- DC-Load Console -- mounts on /pc, connects to a PC-hosted program,
called 'dc-load'. DC-Load is Andrew Kieschnick's BBA/Serial port loader
program. If you use the DC-Load console, then you can read files
directly from your in the /pc directory. The other major advantage (if
you are using a BBA) is that DC-Load will redirect console messages over
the ethernet for you. There is also the ps2-load-ip console for PS2 RTE
development which performs a similar function.

- 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. This is DC-only.

- Romdisk -- mounts on /rd. This is an implementation of the Linux ROMFS
file system. Right now it supports nested directories but no listings. As
time goes on I will be working on this to make it more fully functional.

- Ramdisk -- mounts on /ram. Works exactly as you expect -- putting files
here eats up core RAM, deleting them recovers it. Otherwise it works
exactly like a normal file system.


1.5

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 used to be a Linux-specific file system
but it is well used among embedded developers these days) 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 your environ.sh/tcsh 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.


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.


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).

You can also edit kernel/mm/malloc.c and enable the memory debugging
defines at the top. These will track all memory usage and look for buffer
overruns/underruns, reporting any issues as they happen. It will also
show leaked buffers remaining at the end of the program. There is a
similar facility for the PVR on the DC port.


3 --- Networking ---------------------------------------------------

3.1

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

A) Yes. There is a very primitive and rudimentary driver for the Sega
broadband adapter (an RTL8193C based 10/100 card) and the Lan Adapter on
the DC; and for TCP/IP there is a port of Adam Dunkel's lwIP embedded
stack. 


3.2

Q) What about a BSD stack?

A) That seems to be everyone's generic answer to wanting a TCP/IP stack.
Have you actually _looked_ at the BSD stack? Not just glanced through it
at the files and said "oh yep, it's all there!" but really studied what
it would take to do a port? If you're still interested then I welcome
you to attempt a port, but it's not a small task. The biggest problem
would seem to be ripping it out of its BSD home and putting it in a
foreign environment, but with the additions of semaphores and other
thread primitives now in KOS this might not be as hard.


4 --- Building -----------------------------------------------------

4.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 environ.sh and/or environ.tcsh, and
make sure you are running one of those with the 'source' command (see the
README). If in doubt, use 'set' or 'setenv' to find the environment
variables. You should have a KOS_BASE variable.


4.2

Q) Where is the source to bin2o? All your other stuff has source...

A) Examine the file more closely. It _is_ the source code =). bin2o is
a bash shell script that runs from a real bash on a *nix, or under the
Cygwin bash. There were some issues with it running under Cygwin 
previously but those should now be fixed.


5 --- Debugging ---------------------------------------------------------

5.1

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

Q) I work on a PS2; how can I see debug output?

A) For #1, use dc-load-ip and it has a very nice console mode also. For
#2, I give you basically the same answer: put ps2-load-ip on your Linux
memory card and add it to your RTE menu. Use that to load any KOS
programs and you will have a choice of both GS-based and ethernet-based
consoles.


5.2

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

A) You'll want to either disable all debug output (using dbglog_set_level)
or redirect it elsewhere using dbgio_set_printk(). You can also add
INIT_QUIET to your init flags.


5.3

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

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

There is an effort to make a GDB stub that will work with KOS, but
nothing has fully materialized yet. There's a very simplistic one
for the DC port which lets you place manual breakpoints, but it
doesn't support any sort of tracing.


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

KOS Version Id: $Id: FAQ,v 1.5 2002/11/06 08:30:57 bardtx Exp $


