KallistiOS

From DCEmulation
Jump to: navigation, search

KallistiOS is the most used development library for Dreamcast homebrew and was written by Dan Potter. At the moment it is maintained by several other developers.

What is KallistiOS?

KallistiOS is a pseudo-real-time operating system for gaming consoles, licensed under the terms of the *new* BSD license (the one without the advertising clause). It has currently been ported to the Dreamcast*, Gameboy Advance*, PlayStation 2*, and Intel* ia32 platforms, though the DC port is still the most advanced and functional of the lot.

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

KallistiOS is a modular monolithic kernel, like Linux or FreeBSD. This means that there is a kernel library which you link with your own code. This library (libkallisti.a) contains the whole core OS functionality. You may also enable dynamically loaded modules which will link into your program at runtime and add extra functionality like new VFS modules, new peripheral device support, image loader plugins, etc. The possiblities are limited only by your patience with adding enough exports to support the modules. ;)

Note that this is different from previous versions of KOS which had an actual "OS mode". The new dynamic loader system is architected somewhat like the AmigaOS's library system but it makes no pretenses whatsoever to being an actual process management system.

What KallistiOS is primarily:
- Processor manager (threads, MMU, store queues, DMA, exceptions, etc)
- Pseudo-POSIX/ANSI layer (printf, files, threads, etc)
- HAL (hardware abstraction layer)

What KallistiOS provides optionally:
- Dynamic module loading
- Ported addon modules, through kos-ports

What KallistiOS is NOT:
- UNIX (or even compatible)
- Linux/BSD (those are their own ports! =)
- Memory protection; programs can overwrite each other at will
- Pretty much anything else you can think of that's not in the above list

(There is an MMU module for the DC port, but nothing really uses it at this point.)

If you're looking for all these features in a solid proven kernel, then look no further than Linux or NetBSD. On the other hand, if you want a simple kernel that you can grok in a few hours and use simply, use KallistiOS!

As an aside, if you are interested in a skeleton version of KOS that uses the MMU and memory protection, a real process model, etc, check out KOS-MMU. It's not being worked on any more but it has some interesting code in it and is a clean example of a simple OS. Most of the interesting code from KOS-MMU was merged into KOS 1.1.x, 1.2.x, and 1.3.x.

LICENSING

Please read the file "LICENSE" for more information about this subject. This program is now distributed under a similar set of terms as earlier ones (libdream), and has changed since KallistiOS 0.7 (GPL). Even so, some of the software distributed with KOS (newlib math routines, Xing MP3 engine, modplug, etc) are under different licenses. Please read "LICENSE" if in doubt!

This software is based in part on the work of the Independent JPEG Group (see addons/libjpeg/README).

I have also added a somewhat informative "licensing" section to the FAQ.

If in doubt, please contact us. If you want to use KOS in a project, we'd love to hear from you anyway!

PREREQUISITES

Building KallistiOS from source entirely requires two things: - GNU Binutils / GCC, cross-compile to the platform of your choice; for DC this is a compiler targeted for "sh-elf", for GBA this is a compiler targeted for "arm-elf", and for PS2 you'll need the PS2DEV "ee" compiler. On ia32, you can just use any PC version of GCC that writes ELF files (e.g., Linux compiler). See below about version notes. - GNU Binutils / GCC / GNU Make for your host platform

If you don't have any of the above, please see this site for some more instructions and a build script that may help you:

DC: http://www.boob.co.uk/
GBA: http://www.gbadev.org/
PS2: http://ps2dev.sf.net/

On the DC, you'll want GCC 3.0.4. It's far better than the 2.9x series at this point and even compiles nicely with -O2, unlike previous versions. The default optimization setting in the enclosed environ files is -O2. If you want to build SPU programs then you will also need an ARM tool chain. Precompiled binaries are included for the ARM code that is used by the addons, however.

DO NOT use a version of GCC beyond 3.0.4 for DC development. Let me repeat that just to make sure... DO NOT use a version of GCC beyond 3.0.4. It has a very small and well known set of bugs which are worked around with compiler flags. There is unfortunately at least one major bug in every known version of GCC past 3.0.4 for the SH-4 platform.

On the GBA, any fairly new GCC 3.0.x and above works fine. It includes the new ARM-supplied backend for that CPU target. It also provides a compiler that works with both ARM and Thumb mode code, including interworking (though good luck getting that to work!).

For PS2, you're stuck with a 2.95.2 derivative for the EE, because that's what Sony provided and no one has managed to fully update to the latest versions AFAIK. YMMV, there may be a new one by now. Note that the PS2 port currently only builds for the RTE sub-arch, which is the loader DVD used with the PS2 Linux Kit. So using KOS for PS2 currently requires that you have a Linux Kit. You can buy one here:

http://us.playstation.com/hardware/more/SCPH-97047.asp

BUILDING

Building KOS itself is actually quite simple, especially if you don't want to add new sections for yourself. Make a copy of doc/environ.sh.sample and call it environ.sh in your main KOS dir. Edit this file to match your compiler setup and any other preferences you may have. Also make sure you set the architecture that you want to build for here.

Note that unlike previous versions, there is only one environ.sh file no matter what platform you use. The common pieces and most of the platform specific pieces have been pulled out so that you don't have to deal with them anymore.

After you have a working environ script, run it with 'source environ.sh' and run your make program. For BSD people this will be 'gmake', otherwise it will probably be just 'make'. 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. I recommend putting the 'source' line above into your shell's .rc/.login.

This process should work (and has been tested) under Linux, BSD, and Cygwin. It is very doubtful that it will work in any non-Unix environment, though some success has been reported using MinGW.

VERSION CODES

All KOS versions are composed of three sections: major, minor, micro. Major revisions are generally something that changes the OS fundamentally, or when we run out of single-digit major version numbers =). For example, in the 1.0.x -> 1.1.x transition we moved from an OS style target to a library style target. The minor version number is used to denote a development series. Even numbered minor versions are considered stable, while odd-number versions are considered unstable, incomplete, etc. When we feel like significant progress has been made since the last stable release, we'll make a new stable release. Finally, the micro version denotes a sequence in the development series. 1.1.0 would be the first snapshot of the 1.1 development series.

And as always, if you want to be on the bleeding edge, use the Subversion tree hosted via SourceForge and the svnpush/svnpull scripts.

HACKING

If you are planning on doing your own hacking and potentially submitting patches for me to include, then I'd very much appreciate it if you would do this against the SVN tree rather than a release tree. You can generate patches for me like so:

svn diff -ruN

I don't guarantee that any patch will get included (especially if your patch contains a lot of reformatting, sloppy coding, things at cross-purposes with the primary thrust of KOS, etc), but I will make an effort to at least examine and comment on any submitted patches.

Please also read coding_style.txt if you want to submit things to the KOS core. Except in some exceptional circumstances, I will want the code to match up style-wise in at least the core lib. Things in add-ons aren't quite as important.

OS MODE IS GONE FOR GOOD

All the interesting and maintainable pieces of the KOS 1.0.x "os mode" have been fully integrated back into the mainline KOS 1.3.x tree. It is now used for dynamic module loading and does not include process support, etc. This is unlikely to be revived again in the future.

If you want this kind of functionality but still want an MMU-less environment for speed, I recommend porting uCLinux to your platform.

PLATFORM NOTES

Dreamcast

- MPGLIB (LGPL MP3 library, which is also faster) is included, but does not work. If you want to screw with it yourself, check the libmp3 Makefile and look at sndmp3_mpglib.c in that dir.
- libs3m is present but doesn't really work. It needs serious porting work.

Gameboy Advance

- This port is now being maintained by Gil Megidish.
- There is not a lot of hardware support yet. IRQs aren't even supported, so don't even think about trying to use threads yet =). This port is somewhat immature however, so I expect the support to improve over time.
- KOS is currently configured to run as Thumb code from the ROM. This can be changed by editing the config script to set the compiler flags and editing kernel/arch/gba/kernel/startup.s to remove the "bx" call and make it a regular jump.
- In future versions I hope to have a more elegant system to combine Thumb and ARM mode code (including automated copying of your ARM code into RAM with the data segment). You can see the beginnings of this in the linker script.

PlayStation 2

- This port currently only supports booting on the Linux Kit RTE. If anyone who has a raw PS2DEV setup would like to port things around to work on the raw PS2 as well, I'd be happy to accept any help.
- It is designed to be used with ps2-load-ip as a loader.
- There is basically no hardware support yet, just a CPU/kernel-core port.

Intel IA32

- This platform was essentially a test just to see if it could be done, but I suspect it would be pretty useful for people writing things like embedded MP3 players.
- It was written using the very old KOS 1.3.x snapshot, so it probably doesn't compile right now. But it could probably be fixed pretty easily.

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.

Also, please take note of our new web URL (below). We have moved hosting to SourceForge for all console-related things.

Cryptic Allusion
http://gamedev.allusion.net/

"Sega" and "Dreamcast" are registered trademarks of Sega Enterprises, Ltd. "Nintendo" and "Gameboy Advance" are registered trademarks of Nintendo of America Kalisto Software is a registered trademark of Kalisto Software, Inc. "PlayStation" is a registered trademark of Sony Computer Entertainment America "Intel" is a registered trademark of Intel, Inc. Any other trademarks are trademarks of their respective owners.