                             =====================
                             AdvanceCD Build Notes
                             =====================


1 DESCRIPTION
=============

This document describes the internal details and the
build process of AdvanceCD. The build process is
possible only in Linux.


2 DISK TYPES
============

AdvanceCD can boot from three different disk types: CD/DVD,
USB disk and fixed disk. Any disk type uses a different
boot filesystem with different booting tools.

2.1 CD/DVD
----------

For CD and DVD is used an iso9660 filesystem using the
El Torito boot support in `no emulation' mode.
The image is created with the mkisofs program.
For booting is used the isolinux boot loader.

2.2 USB disk
------------

For USB disks is used a FAT 12/16 filesystem, with a special
partition table which is also a FAT boot sector. This allows
booting using both the USB-FDD and USB-HDD BIOS.
The disk is created with the included makebootfat program.
For booting is used the syslinux boot loader.

2.3 Fixed disk
--------------

For Fixed disks is used a FAT 12/16/32 filesystem in
a standard partition.
The disk is created with the included makebootfat program.
For booting is used the FreeDOS operating system and the
loadlin linux loader.


3 FILES
=======

In the bootable disk images are present various files
required in the booting process.

3.1 isolinux.bin/isolinux.cfg
-----------------------------

isolinux.bin is the CD/DVD boot loader that loads the Linux Kernel
and the root filesystem. The configuration of isolinux
is in the isolinux.cfg file.
In the configuration file is set the kernel parameter
"advancecd=1" to allow the recognition of the boot from
CD/DVD condition.

3.2 ldlinux.sys/syslinux.cfg
----------------------------

ldlinux.sys is the FAT boot loader used for USB disks that
loads the Linux Kernel and the root filesystem.
The configuration of ldlinux.sys is in the syslinux.cfg file.
In the configuration file is set the kernel parameter
"advanceusb=1" to allow the recognition of the boot from
USB disk condition.

3.3 loadlin.exe
---------------

loadlin.exe is the FAT boot loader used for fixed disks
that loads the Linux Kernel and the root filesystem.
It's a DOS program, so it needs a DOS environment like
FreeDOS to run.
The configuration of loadlin.exe is in the autoexec.bat file.
In the configuration file is set the kernel parameter
"advancehd=1" to allow the recognition of the boot from
fixed disk condition.

3.4 kernel32.sys/command.com/config.sys/autoexec.bat
----------------------------------------------------

kernel32.sys and command.com are minimal component
of FreeDOS required to run the loadlin.exe linux loader.
config.sys and autoexec.bat are the configuration files
of FreeDOS.

3.5 linux
---------

linux is the compressed image of the Linux Kernel.

3.6 initrd.img
--------------

initrd.img is a gzipped ext2 filesystem image containing
the Linux root filesystem. This filesystem is loaded in ram
by the linux loader. It contains the minimal software required
for the Linux startup.

Please note that the ext2 filesystem is supported only
in Linux. You cannot read this filesystem in Windows without
using special tools.

The file /etc/rc.d/rc.S in the image is the start script
which does all the initialization work. The /etc/rc.d/rc.0
file is the shutdown script.

3.7 app.img
-----------

app.img is a compressed iso9660 filesystem image using the
zisofs extension. This filesystem is mounted by the
/etc/rc.d/rc.S startup script present in the initrd
filesystem. It contains all the emulator software and
all the Linux Kernel modules.

Please note that the zisofs extension is supported only in Linux.
You cannot read this filesystem in Windows without using special
tools.


4 PREPARATION
=============

To build AdvanceCD you must have both the source and binary
package.

Login as root and decompress both the packages in the same
directory and run the command:

    make extract

to extract the initrd/ and app/ compressed filesystems.


5 MAKEFILE
==========

The Makefile has the targets:

    all - Update app, initrd and iso.
    app - Update the app.img file from the app/ directory.
    initrd - Update the initrd.img file from the initrd/ directory.
    iso - Create the iso image.
    dist - Create the source distribution file.
    distbin - Create the binary distribution file.


6 APP
=====

To update the app image follow the steps:

* Copy the new files in the app/ directory
* Update the image with the command "make app"

You need at least the kernel 2.4.14 to support the zisofs extension.
Check the manpage of mkisofs for the -z option or the mkzftree manpage.

6.1 AdvanceMAME/AdvanceMENU/AdvanceMESS
---------------------------------------

To compile a new version of AdvanceMAME/MESS/MENU you can use
the `wholecd' AdvanceMAME make target.

Then you must manually copy the new binaries in
the app/root directory. Remember to update also the .xml
game list in the same directory.

6.2 Kernel
----------

To update the Linux kernel follow the steps:

* Uncompress the kernel source
* Copy the .config script from the contrib/ dir in the kernel dir.
* Change the .config script enabling the required SCSI, Joystick and
  FrameBuffer drivers.
* Go to the kernel dir.
* Use the ../contrib/dokernel script to compile and install the kernel.

This is the list of the not included drivers/features:
    SCSI - "Probe all LUNs on each SCSI device" - Safer to have it disabled.
    Joystick - "I-Force USB joysticks and wheels" - Kernel Panic
        also without the device.
    USB - "UHCI Alternate Driver (JE)" - This drivers is reported to have
        some problems with HID devices. Use the "UHCI (Intel PIIX4, VIA, ...)"
        version. Reported in the xmame list.
    FrameBuffer - "VESA VGA" - This driver isn't able to set an
        arbitrary video mode.

The kernel has all the modules compiled in. The only external
modules are for Joystick, GamePort and ALSA.

To boot logo is contained in the linux_logo.h file created with the
fblogo utility.

The kernel used is the version 2.4.26 with the following
patches applied:

noprintk - Remove all the kernel messages.
bootkey - Change the boot key sequence.
keyboard - Allow the boot key sequence also in RAW mode and to
    immediately shutdown the system.
i810fb-lite-0.0.23 - Intel i810 framebuffer driver.
i810fb-lite-0.0.23-0.0.35 - Updated Intel i810 framebuffer driver.
i810fb-noclock - Fix for the framebuffer driver.
i810fb-nomodule - Fix for the framebuffer driver.
savagefb-0.3.2 - S3 Savage framebuffer driver (from DirectFB).
savagefb-noexit - Fix for the framebuffer driver.
savagefb-nomodule - Fix for the framebuffer driver.
rivafb-0.9.4c - Updated nVidia GeForce framebuffer driver.
rivafb-id - New cards for nVidia GeForce framebuffer driver.
radeonfb-id - New cards for ATI Radeon framebuffer driver.
i740fb-20021207 - Intel i740 framebuffer driver.

The kernel is compiled with the contrib/.config configuration
file.

6.3 Modules
-----------

To update the Linux kernel modules follow the steps:

* Go to the kernel dir.
* Use the ../contrib/dokernelmodules script to compile and
  install the kernel modules. Note that this command
  deletes all the previously installed modules.
* Install the ALSA modules.
* Delete from /app/lib/modules/modules.isapnpmap:

    snd-es968 - It's a too short line and it generates a runtime warning.

* Delete from /app/lib/modules/modules.pcimap:

    snd-bt87x - It's a TV Tuner and must not be seen as an audio device.
    snd-atiixp-modem - Only modems.
    snd-via82xx-modem - Only modems.
    snd-intel8x0m - Only modems.

6.4 ALSA
--------

To update the ALSA modules and binaries follow the steps:

* Uncompress the ALSA-driver source.
* Go to the ALSA-driver dir.
* Use the ../contrib/doalsa script to compile and install
  the ALSA modules.
* Go to the kernel dir and use the ../contrib/dokerneldepmod
  script to update the modules dependencies.

The ALSA library (lib 0.9.1) doesn't work if compiled with a prefix
different than the final running location. It means that you need
to compile and install it with the standard prefix=/usr and
manually copy the files.

Ensure also that the /etc/modules.conf options are still valid
for the new ALSA modules. Otherwise the modules will not be
loaded.

6.5 Other
---------

To update the other binaries and libraries you must copy
them manually.

All the binaries already present are from a Slackware 10.0
installation.


7 INITRD
========

To update the initrd image follow the steps:

* Copy the new files in the initrd/ directory.
* Update the images with the command "make initrd".

7.1 Busybox
-----------

The BusyBox program is compiled with the .config-busybox
configuration file.

To compile Busybox, first copy the .config file, then
type "make menuconfig", "make" and "make install".

To install, copy the install bin/ and sbin/ directory in initrd/.

Note that you must have all the commands in /bin and not
in /usr/bin.


8 IMAGE
=======

To update the disk image follow the steps:

* Copy the new files in the image/ directory

8.1 Isolinux
------------

The isolinux.bin image is compiled with the following patches:

memfix - Allow the use of the mem=512M kernel parameter also if
    the system has less than 512MB. The mem=512M option is
    required to allow the Linux Frame Buffer driver to map the
    video card memory in the kernel address space also if the
    system has 1GB or more memory.
nomsg - Remove some boot messages.

If you don't want to use the `memfix' patch, remember to remove
the `mem=512M' option from isolinux.cfg.

8.2 Syslinux
------------

If you update the syslinux files, be sure to update both the
ldlinux.bss and the ldlinux.sys files. They must always be part
of the same compilation process.

ldlinux.sys uses the same patches of isolinux.bin.

If you don't want to use the `memfix' patch, remember to remove
the `mem=512M' option from syslinux.cfg.

8.3 FreeDOS
-----------

Be sure to use the 32 kernel.sys version. The 16 version
doesn't have the FAT32 support.


9 COPYRIGHT
===========

This file is Copyright (C) 2003, 2004 Andrea Mazzoleni.
