KallistiOS 0.6
(c)2000 Dan Potter and Jordan DeLong of Cryptic Allusion


OVERVIEW
--------
KallistiOS is a real-time pseudo-microkernel operating system for the
Sega* Dreamcast*, licensed under the terms of the GNU Public License (GPL).

Depending on whether you wish to see the fnords, you can pronounce it
"kallisti-o's" (like a cereal) or "kallisti o s" (like an operating
system). We like the former since it's silly to be so serious most of the
time =). "Kallisti" means "to the fairest" in Greek. This was the word (so
the story goes) that was inscribed on the golden apple that Eris threw
into the banquet of the gods to start the Trojan war. This somehow landed
her the title of matriarch of a silly religion called Discordianism, which
is what the name pays homage to. If you want a short abbreviation, you can
also refer to it as "KOS", which can be pronounced "k-os" (chaos).

Note that this name is _not_ to be confused or associated with either the
professional development company Kalisto Software* or the cracking group
"Kalisto".

Now that that is cleared up... =)

Like most embedded kernels, KallistiOS has two major modes of operation. 
In the first mode, it can be linked directly into a program. In this case
you have very fine control over what gets included in the binary and how
and when it is initialized. It is also by far the simplest way to make use
of it (hearken back to the days of libdream...). The second mode is the
more versatile and fun. You can run the standalone KallistiOS binary and
have it load programs and multitask like a regular OS. The virtualized
file system is used in this loading process, so the first (and subsequent) 
loaded binaries can be sitting on a CDR, embedded in the kernel, or even
come across from a PC debugger host. 

What KallistiOS IS:
- Processor manager (threads, MMU, store queues, DMA, exceptions, etc)
- Pseudo-POSIX layer (printf, files, threads, etc)
- DC HAL (hardware abstraction layer)
- Optional complex OS services (simple windowing system, etc)

What KallistiOS is NOT:
- UNIX (or even compatible)
- Linux (that's its own port! =)
- Memory protected; programs can overwrite eachother at will
- Pretty much anything else you can think of that's not in the above list

If you're looking for all these features in a solid proven kernel, then
look no further than Linux-SH. On the other hand, if you want a simple
kernel that you can grok in a few hours and use simply, use KallistiOS! 
We also feel like it's kinda cool because it's the one and only Dreamcast
OS. ^_^ WinCE doesn't count since you can never see it overtly like on a
PDA. 


LICENSING
---------
Please read the file "LICENSE" for more information about this subject. This
program is distributed under a fairly different set of terms from earlier
ones (libdream).

If in doubt, please contact us.


BUILDING
--------
Building KallistiOS from source entirely requires three things:
- GNU Binutils / GCC, cross-compile to the "sh" target (to build kernel)
- GNU Binutils / GCC, cross-compile to the "arm" target (to build ARM code)
- GNU Binutils / GCC / Make for your host platform (to build utils)

If you don't have any of the above, please see "gnutools.txt" in the
documents directory for more info on obtaining and/or building them.
(FIXME: add a gnutools.txt)

Note that KOS will _not_ successfully build with GCC 2.95.2 (which is the
version most people have) unless you turn off all optimizations. This is
unfortunate but there's not much we can do about it.

Building is actually quite simple, especially if you don't want to add new
sections for yourself. First, edit Makefile.globals, and set all that
stuff. You'll need to set KALLISTIBASE to the directory containing
Makefile.globals, and the other parts are fairly self explanatory. The
"TARGET" should be sh-elf or sh-linux-elf, depending on how you built your
tools. "BASE" points to the base directory of said tools. The structure
given is the one I have on my machine since I have two sets of cross tools
-- one for SH-4 and one for ARM7. You'll need both sets of tools to build
the full OS from scratch, though this is not required. A precompiled
binary is included for the ARM7 code used by default. You'll additionally
need to edit Makefile.prefab and set KALLISTIBASE. 

After that, just run GNU make in the KallistiOS root and take a break.  It
should be done after a few minutes. If something goes wrong, please check
the FAQ; if that fails, email one of us and we'll see what we can do. 

This process should also work under Cygwin. It is very doubtful that it
will work in any non-Unix environment such as Mingwin.


INCOMPLETENESS NOTICE
---------------------
KallistiOS, as it stands, is more of a developer tool and a toy for the
very determined. We don't expect it to be usable by the "general public" 
for another release or two. If you can manage to make use of it even
with the difficulties of missing documentation and areas of incomplete
code, then more power to you! But I recommend waiting a while for most
people.

A short list of errata:
- Serial console support is completely broken if you turn on threading.
  Communication from the DC to the PC will work ok (so you'll get printf
  messages and file writes might work) but going the other way it really
  doesn't work. Thus, you can't use it in kosh yet. Well, you _can_, but
  as above, it isn't particularly fully working =)
- There are various thread contention issues popping up here and there.
  We'll work to fix these where we can find them.
- There is a lot of documentation missing.. sorry
- We claim to have sound routines, but there isn't much more than there
  was in libdream right now.
- There is a lot of new, fairly untested code in this package, like
  a basically brand new TA module, and a completely brand new iso9660
  module. They work for us for the most part but they need to be tested
  more. Specifically, the TA allocation routines don't work yet with
  everything. You can enable the experimental ones by changing the
  "#if 1" to "#if 0" in ta_alloc_buffers near the top. Some stuff in
  here can even rightly be considered experimental outside of KOS itself
  (our new 800x608 mode for VGA boxes is a good example).
- GCC 2.95.2 IS NO LONGER SUPPORTED. Compiling with no optimizations
  (maybe) seems to work, but if you are having troubles, try a CVS GCC.
  We are using binutils-001111 and gcc-20001106 from sourceware.cygnus.com
  and it seems to work alright. Let me repeat again: if you have any
  gcc release version (like the one that has been recommended on dcdev)
  it _will_ _not_ _work_ with any optimizations turned on at all, and it
  may not work even then.

In general, there are a lot of things that may or may not work in this
beast. It's fairly new. 


END
---
That's where we leave off here. Now that you have a build and ready copy,
you're ready to get to the more fun things. Please read the other documents
in the "doc" directory for more information. Also check the FAQ if there
is something you were wondering. (FIXME: add a faq)


					Dan Potter
					Jordan DeLong
					Cryptic Allusion
					http://www.allusion.net/dcdev/


* "Sega" and "Dreamcast" are registered trademarks of Sega Enterprises, Ltd. 
  Kalisto Software is a registered trademark of Kalisto Software, Inc. 

KOS Version Id: $Id: README,v 1.5 2000/11/12 01:11:15 bard Exp $

