README for the almost-release (version 0.95) libdream
Please read through this before attempting to use libdream.



TRADEMARKS
----------
Right up front: "Sega" and "Dreamcast" are registered trademarks of 
Sega Enterprises, Ltd. This package has no association with Sega or
any of its affiliates, besides working on their hardware. All other
trademarks are owned by their respective trademark holders.


WHAT IS LIBDREAM 
---------------- 
Libdream is a function library for the Sega Dreamcast game system, for
hobbyist programming. It is published under a very permissive license
(see below) so that it can be used in the maximum number of hobbyist
projects. The intention is not for MegaCorp X(tm) to be able to bypass
the Sega licensing scheme. We're providing "the gun" here, but we're not
responsible for what you do with it.


LICENSE
-------
This is a work in progress. The library itself is distributed under the
MIT licensing terms. Basically they say that you can do whatever you
want to with this, as long as you don't change it and then distribute it
saying that it's the same library (i.e., you claim it's the original
"libdream") or that you change it and say that you wrote it.
Additionally, there is NO WARRANTY on the program or its functionality.
The header of libdream.c contains some credits info:

/*
 * Dreamcast function library (libdream)
 * Portions (c)2000 Dan Potter, Jordan DeLong
 *
 * Many thanks to and helpful info from these guys:
 *  Marcus Comstedt (some cd, sound, video, and maple info)
 *  Mike Brent (early libdream help and serial cable help)
 *  Bitmaster (video info)
 *  HeroZero (waitvbl info)
 *  HitMen-DC (help on gcc)
 *  Chuck Mason (320x240 example code)
 *  Maiwe (TA help)
 *  The DCDev list on eGroups 
 *
 * This library is licensed under the MIT/X style license. For more
 * information, please see COPYING.
 */


COMPILING IT
------------
If you want to compile the library from scratch, you'll need to have
a copy of the SH-4 GCC and Binutils, and GNU make. Then again, you'll
need the first part even if you're not going to recompile it, so this
shouldn't be an issue =). Edit Makefile.config at the top of the tree
to change paths to match yours, and off you go. Make sure if you are
running in BSD to use 'gmake' and not 'make' because BSD make isn't
compatable with these Makefiles. The Makefile in the root will also
build the examples, assuming the libdream build was successful.

Note that if you want to use libdream with Cygnus' newlib, you'll need
to change dc_main to main in the examples, or alternatively, add a #define
in dream.h to take care of it:

#define dc_main main


USING IT
--------
All of the basic functionality is declared in "dream.h", which you can
include in your programs. This program expects a certain amount of libc
code to be present, which can come from newlib or some other source.  I've
been using my miniature libc on my web site, which works pretty well. 
Note that all of your code must match in compilation options -- and
libdream currently suggests "-ml -m4-single-only" (to get proper floating
point support for 3D). The most common symptom of not having these
match up is that your printf acts very oddly.

This version includes routines for almost all of the currently discovered
Dreamcast hardware. This includes the GD-ROM (Mode1/2 only! no GD
access!), the sound CPU, basic and 3D video routines, a sleep function,
peripheral access, etc.


SPU FIRMWARE
------------
As you might or might not know, the sound chip in the Dreamcast is a
Yamaha(tm) AICA sound system. This is a combination ARM7 RISC core
and Yamaha 64-channel wavetable synthesizer. This chip can in theory
be programmed directly from the SH4 but it's very error prone for
realistic usage. So I've removed that functionality from libdream, and
you'll now need AICA firmware to use the thing.

If you'd like to compile AICA firmware for use with the SPU, you'll need
the GNU toolchain built for ARM7. Specifically you'll need GCC and AS.
These can be built in exactly the same way you built the SH4 toolchain --
just follow the directions on the Hitmen page except use these configure
lines: 

../binutils-2.10/configure --target=arm-elf --prefix=$prefix
../gcc-2.95.2/configure --target=arm-elf --prefix=$prefix --without-headers
	--without-libs

That ought to do it for you. See the S3M player on my site for an example
of code that uses the SPU natively. Once you have an ELF file, you'll need
to convert it to a BIN with VMA 0 and convert that to an H file you can
include in your program.


EXAMPLES
--------
Examples galore! I guess too many people were having troubles compiling
the little test programs on my site and they weren't really demonstrating
the usefulness or power of libdream, so I have incorporated an entire
directory full of examples. They will match up with the current libdream
version and compile right out of the box. In fact if you execute a "make"
in the root of libdream to build libdream itself, you'll automatically get
executables for the examples in bin and srec format.


DOCUMENTATION
-------------
Likewise, I've included some rudimentary documentation in the "docs"
directory. I'd be interested in hearing if this helps out with usage of
the library or not. 

libdream.lyx is a LyX 1.0.0 document, written on a stock LyX 1.0.0
distribution in Debian/Woody. libdream.ps was generated inside LyX
using the TeX tools, and the html tree was generated by exporting
LaTeX and using latex2html. Finally, libdream.txt was created using
the ASCII export of LyX.


GCC IS NOT YOUR FRIEND
----------------------
DO NOT compile this with -O2, it _will_ break several things in the 3D
support, and gods only know where else. This is demonstrated by this 
simple function:

void *test(uint32 value) { return (void*)(0xa4000000 + value); }

This gets compiled to code that equates to:

void *test(uint32 value) { return (void*)0xa4000000; }

Hot damn! Massive optimization step there. Libdream, therefore, continues
to be compiled with -O, as I don't have the time nor patience to go
through all of libdream's binary code checking for this crap. This might
be fixed in CVS GCCs, I haven't tried, but that's kind of beside the point
since if you can build a CVS GCC you can probably try -O2 responsibly.
Anyway, programs seem fast enough with -O and if you have problems with
a particular part, write it in assembly! =)


THE ENIGMATIC OS 
----------------
If you've followed DCDev at all, you know this already.. ;-) But we're
currently in the middle of writing an operating system for the Dreamcast
which is called KallistiOS (for name reference see: Discordianism =).
Quite a number of pieces of libdream 0.95 are the direct result of work
on that OS and as you can guess from that code, it's got a much cleaner
layout and design. I expect this to be one of the final libdream
releases. Once I get some feedback on how everything works, I'll release
a 1.0 version, recompile the things on my site with it, and move on to
bigger and better things. I think once the OS is out, most of the
current libdream users will want to do so as well =). I guess the only
major potential problems would be licensing issues but we haven't worked
those out completely yet.

A few things (especially maple) were changed in version 0.7 as a result
of pulling in these new modules, and the CD-Rom system was completely
replaced (and now uses the KOS vfs conventions). I hope it doesn't cause
anyone too much difficulty porting your programs to the new libdream.
But like I said, this is probably one of the last ones anyway.


CDFS IS NOW CDROM AND ISO9660
-----------------------------

If you didn't read the paragraph above, the cdfs module has now been
replaced with a backported cdrom.c and fs_iso9660.c from KallistiOS.
This means that since I didn't feel like rewriting the whole thing, the
calling conventions have changed considerably. Sorry about this. If you
don't care about the licensing or the speed improvements, then feel free
to sub back in the old cdfs.c and gd_syscalls.s from libdream 0.71. 
Otherwise, enjoy the now fully X11'd library!

The calling conventions for cdfs are now as follows:

- Initialization is no longer cdfs_init, but cdrom_init and iso_init.
- All functions are iso_* instead of cd_*
- There is no seperate directory open and close, it is the same now, just
  OR on the O_DIR bit on the open mode.
- struct dirent is deprecated, use dirent_t.
- int's are no longer the file descriptors; now you will want to use a
  uint32, and zero is the failure code instead of a negative value. Yes,
  that sacrifices the errors but it's a lot simpler for some deep
  implementation issues in the OS.

Check examples/cdfs for a simple example.


TODO
----
Before releasing a 1.0 and calling it quits except for bugfixes, I have
a couple of goals for getting stuff into libdream. Currently these
include rudimentary interrupt support and the latest and greatest TA
module from KOS. I also want to include a few good AICA firmware pieces
that can be used with your programs such as the streaming driver I
developed for playing MP3s with KOS.


BUGS
----
There are still a few in here to watch out for. The biggest and most
obvious one is that there is still something weird with the TA support;
if you use an opaque colored polygon (not textured, not translucent),
then the first tile (0,0) will not actually render. The background will
show through there and the translucents will show up, but not the
opaques. I don't know why this is yet, it appeared with translucent
support. Additionally the TA support is kind of flaky in general since I
stopped supporting it when KOS starts. I hope I will have time to
backport the TA module from KOS as well but time will tell. For now I
recommend looking at the examples and dotting all your i's =).

Also, this isn't a bug in libdream per se, but you need to be careful
when accessing the maple bus too fast. If you do a maple execute (even
with blocking) and immidiately do another, it sometimes causes the bus
to lock up temporarily and give you bad results. A 5-10ms delay seems
to be plenty.


CREDITS
-------
I have to acknowledge and make sure everyone understands right up front
the major contributions that Jordan DeLong (also of Cryptic Allusion)
has made to libdream. Most of his work is actually backported from the
OS, but he is responsible for most of the revamped maple subsystem.

Several people sent me submissions for things to fix/change/add in this
and earlier libdream releases. Specifically, I received help from Chuck
Mason of Gleem! fame on getting 320x240 support, and DrkWatr/Hs sent me
some nice keyboard and more complete controller routines. Unfortunately,
I was too lazy to open DrkWatr's libdream changes until pretty recently
and the OS already had both of these things by then! Sorry 'bout that.

Also if anyone does a diff on the sources you'll notice that Mike Brent's
gone from the copyrights. I figured I'd mention this here instead of
someone calling it a conspiracy ;-). It's just that with the newly imported
serial routines from KallistiOS, all of the code that he wrote is now
gone from libdream and I'd like to keep a tidy house. However, I still
acknowledge the usefulness of that code and the help I got from him in
the early DC days, so his name's staying on the credits! ^_^


NO EXCUSES
----------
Now that this is out, I don't want to hear more excuses! =) I want to see
some cool demos and games come out of the hobbyist scene. This ought to
be more than enough to at least get started in that area. If you are
serious about making some hobbyist games or demos, you might also want
to hang on a bit longer to get the stable release of the OS, because it has
things like memory management, exception and interrupt support, 
and threading. It also has a VFS so you can access the VMU, CD, etc, 
through a unified API and path space. Anyhow...


					Dan Potter / Cryptic Allusion
					Dec 27, 2000
					http://www.allusion.net/dcdev/



