development.dbk

bochs : one pc simulator.

Making it evaluate to nothing would be a lot cleaner, but then the scoping rules
would change slightly between the two Bochs configurations, which would be a load
of bugs just waiting to happen. Some classes use BX_SMF, others have their own
version of the macro, like BX_PIC_SMF above.
</para>
</section>
<section id="cpu-mem-objects"><title>CPU und memory objects in UP/SMP configurations</title>
<para>
The CPU class is a special case of the above: if Bochs is simulating a uni-
processor machine then there is obviously only one bx_cpu_c object and the
static methods trick can be used. If, on the other hand, Bochs is simulating an
smp machine then we can't use the trick. The same seems to be true for memory:
for some reason, we have a memory object for each CPU object. This might become
relevant for NUMA machines, but they are not all that common -- and even the
existing IA-32 NUMA machines bend over backwards to hide that fact: it should
only be visible in slightly worse timing for non-local memory and non-local
peripherals. Other than that, the memory map and device map presented to each
CPU will be identical.
</para>
<para>
In a UP configuration, the CPU object is declared as bx_cpu. In an SMP
configuration it will be an array of pointers to CPU objects (bx_cpu_array[]).
For memory that would be bx_mem and bx_mem_array[], respectively.
Each CPU object contains a pointer to its associated memory object.
Access of a CPU object often goes through the BX_CPU(x) macro, which either
ignores the parameter and evaluates to &amp;bx_cpu, or evaluates to bx_cpu_array
[n], so the result will always be a pointer. The same goes for BX_MEM(x).
If static methods are used then BX_CPU_THIS_PTR evaluates to BX_CPU(0)->. Ugly,
isn't it?
</para>
</section>
<section id="config-parameter-tree"><title>The configuration parameter tree</title>
<para>
Starting with version 1.3, the Bochs configuration parameters are stored in parameter
objects. These objects have get/set methods with min/max checks and it is possible
to define parameter handlers to perform side effects and to override settings.
Each parameter type has it's own object type with specific features (numeric,
boolean, enum, string and file name). A special object type containing a list of
parameters is designed for building and managing configuration menus or dialogs
automatically. In the original implementation the parameters could be accessed
only with their unique id from a static list or a special structure containing
pointers to all parameters.
</para>
<para>
Starting with version 2.3, the Bochs parameter object handling has been rewritten
to a parameter tree. There is now a root list containing child lists, and these
lists can contain lists or parameters and so on. The parameters are now accessed
by a name build from all the list names in the path and finally the parameter
name separated by periods.
<screen>
Bit32u megs = SIM->get_param_num("memory.standard.ram.size")->get();
</screen>
</para>
<para>
The example above shows how to get the memory size in megabytes from the simulator
interface. In the root list (".") there is child list named "memory" containing
a child list "standard". It's child list "ram" contains the numeric parameter type
"size". The SIM->get_param_num() methods returns the object pointer and the get()
method returns the parameter value.
</para>
<para>
The table below shows all parameter types used by the Bochs configuration interface.
<table>   
<title>Parameter types</title>
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>bx_object_c</entry>
<entry>Base class for all the other parameter types. It contains the unique parameter id and the object type value.</entry>
</row>
<row>
<entry>bx_param_c</entry>
<entry>Generic parameter class. It contains the name, label, description and the input/output formats.</entry>
</row>
<row>
<entry>bx_param_num_c</entry>
<entry>Numerical (decimal/hex) config settings are stored in this parameter type.</entry>
</row>
<row>
<entry>bx_param_bool_c</entry>
<entry>This parameter type is based on bx_param_num_c, but it is designed for boolean values. A dependency
list can be defined to enable/disable other parameters depending on the value change.</entry>
</row>
<row>
<entry>bx_param_enum_c</entry>
<entry>Based on bx_param_num_c this parameter type contains a list of valid values.</entry>
</row>
<row>
<entry>bx_param_string_c</entry>
<entry>Configuration strings are stored in this type of parameter.</entry>
</row>
<row>
<entry>bx_param_filename_c</entry>
<entry>Based on bx_param_string_c this parameter type is used for file names.</entry>
</row>
<row>
<entry>bx_list_c</entry>
<entry>Contains a list of pointers to parameters (bx_param_*_c and bx_list_c).
In the config interface it is used for menus/dialogs.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="save-restore"><title>The save/restore feature</title>
<para>
The save/restore feature is based on an extension to the parameter tree concept.
A subtree (list) called "save_restore" appears in the root of the parameter tree
and some new "shadow" parameter types store pointers to values instead of the values
itself. All the hardware objects have register_state() methods to register pointers
to the device registers and switches that need to be saved. The simulator interface
saves the registered data in text format to the specified folder (usually one file
per item in the save/restore list). Large binary arrays are registered with a
special parameter type, so they are saved as separate files.
</para>
<para>
The table below shows the additional parameter types for save/restore.
<table>   
<title>Save/restore parameter types</title>
<tgroup cols="2">
<thead>
<row>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>bx_shadow_num_c</entry>
<entry>Based on bx_param_num_c this type stores a pointer to a numerical variable.</entry>
</row>
<row>
<entry>bx_shadow_bool_c</entry>
<entry>This parameter type stores a pointer to a boolean variable.</entry>
</row>
<row>
<entry>bx_shadow_data_c</entry>
<entry>This special parameter type stores pointer size of a binary array.</entry>
</row>
</tbody>
</tgroup>
</table>
It is also possible to use the bx_param_num_c object with parameter save/restore
handlers. With this special way several device settings can be save to and restored
from one single parameter.
</para>
<para>
All devices can uses these two save/restore specific methods:
<itemizedlist>
<listitem><para>register_state() is called after the device init() to register the device members for save/restore</para></listitem>
<listitem><para>after_restore_state() is an optional method to do things directly after restore</para></listitem>
</itemizedlist>
</para>
</section>
</section>

     <section id="configure-scripting"><title>Configure Scripting</title>
      <para>
      &FIXME;
      configure script, makefiles, header files
      </para>
     </section>

      <section id="logfunctions"><title>Log Functions</title>
      <para>
      &FIXME;
      log functions: what is a panic, what is an error, etc.
      </para>
      </section>

      <section id="timers"><title>timers</title>
      <para>
      &FIXME;
      </para>
      </section>

<section id="cmos-map"><title>Bochs's CMOS map</title>
<para>
In addition to the default CMOS RAM layout, the Bochs BIOS uses some additional 
registers for harddisk parameters and the boot sequence. The following table 
shows all CMOS registers and their meaning.
</para>
<para>
<screen>
Legend:
S	- set by the emulator (Bochs)
B	- set by the bios
U	- unused by the bios

LOC	NOTES	MEANING
0x00	S	rtc seconds
0x01	B	second alarm
0x02	S	rtc minutes
0x03	B	minute alarm
0x04	S	rtc hours
0x05	B	hour alarm

0x06	S,U	day of week
0x07	S,B	date of month
0x08	S,B	month
0x09	S,B	year

0x0a	S,B	status register A
0x0b	S,B	status register B
0x0c	S	status register C
0x0d	S	status register D

0x0f	S	shutdown status
    values:
	0x00: normal startup
	0x09: normal
	0x0d+: normal
	0x05: eoi ?
	else: unimpl

0x10	S	fd drive type (2 nibbles: high=fd0, low=fd1)
    values:
	1: 360K 5.25"
	2: 1.2MB 5.25"
	3: 720K 3.5"
	4: 1.44MB 3.5"
	5: 2.88MB 3.5"

!0x11	configuration bits!!

0x12	S	how many disks first (hd type)

!0x13	advanced configuration bits!!

0x14	S,U	equipment byte (?)
	bits	where		what
	7-6	floppy.cc
	5-4	vga.cc		0 = vga
	2	keyboard.cc	1 = enabled
	0	floppy.cc

0x15	S,U	base memory - low
0x16	S,U	base memory - high

0x17	S,U	extended memory in k - low
0x18	S,U	extended memory in k - high

0x19	S	hd0: extended type
0x1a	S	hd1: extended type

0x1b	S,U	hd0:cylinders - low
0x1c	S,U	hd0:cylinders - high
0x1d	S,U	hd0:heads
0x1e	S,U	hd0:write pre-comp - low
0x1f	S,U	hd0:write pre-comp - high
0x20	S,U	hd0:retries/bad_map/heads>8
0x21	S,U	hd0:landing zone - low
0x22	S,U	hd0:landing zone - high
0x23	S,U	hd0:sectors per track

0x24	S,U	hd1:cylinders - low
0x25	S,U	hd1:cylinders - high
0x26	S,U	hd1:heads
0x27	S,U	hd1:write pre-comp - low
0x28	S,U	hd1:write pre-comp - high
0x29	S,U	hd1:retries/bad_map/heads>8
0x2a	S,U	hd1:landing zone - low
0x2b	S,U	hd1:landing zone - high
0x2c	S,U	hd1:sectors per track

0x2d	S	boot from (bit5: 0:fd, 1:hd)

0x2e	S,U	standard cmos checksum (0x10->0x2d) - high
0x2f	S,U	standard cmos checksum (0x10->0x2d) - low

0x30	S	extended memory in k - low
0x31	S	extended memory in k - high

0x32	S	rtc century

0x34	S	extended memory in 64k - low
0x35	S	extended memory in 64k - high

0x37	S	ps/2 rtc century (copy of 0x32, needed for winxp)

0x38	S	eltorito boot sequence + boot signature check
	bits
	0	floppy boot signature check (1: disabled, 0: enabled)
	7-4	boot drive #3 (0: unused, 1: fd, 2: hd, 3:cd, else: fd)

0x39	S	ata translation policy - ata0 + ata1
	bits
	1-0	ata0-master (0: none, 1: LBA, 2: LARGE, 3: R-ECHS)
	3-2	ata0-slave
	5-4	ata1-master
	7-6	ata1-slave

0x3a	S	ata translation policy - ata2 + ata3 (see above)

0x3d	S	eltorito boot sequence (see above)
	bits
	3-0	boot drive #1
	7-4	boot drive #2
</screen>
</para>
</section>

<section id="sb16-emulation-basics"> <!-- start of SB16 section-->

<title>Sound Blaster 16 Emulation</title>
<note><para>
  A little more up-to-date version of the user related part of this section is
  available in the <ulink url="../user/sb16-emulation.html">user guide</ulink>.
</para></note>
<para>
Sound Blaster 16 (SB16) emulation for Bochs was written and donated by
Josef Drexler, who has a
<ulink url="http://publish.uwo.ca/~jdrexler/bochs/">web page</ulink> on the topic.
  The entire set of his SB16 patches have been integrated into
Bochs, however, so you can find everything you need here.
</para>

<para>
SB16 Emulation has been tested with several soundcards and versions of Linux.  Please give
Josef <ulink url="mailto:[e-mail]">feedback</ulink> on 
whether is does or doesn't work on your combination of software and hardware.
</para>

<section><title>How well does it work?</title>
<para>
Right now, MPU401 emulation is next to perfect. It supports UART
and SBMIDI mode, because the SB16's MPU401 ports can't do anything else as well.
</para>

<para>
The digital audio basically works, but the emulation is too slow for fluent
output unless the application doesn't do much in the background (or the
foreground, really). The sound tends to looping or crackle on slower
computer, but the emulation appears to be correct. Even a MOD
player works, although only for lower sampling speeds.
</para>
<para>
Also, the MIDI data running through the MPU401 ports can be written
into a SMF, that is the standard midi file. The wave output
can be written into a VOC file, which has a format defined by
Creative Labs. This file format can be converted to WAV by
sox for example.
</para>
</section>

<section><title>Output to a sound card</title>

<para>
Output is supported on Linux and Windows 95 at the moment.
On Linux, the output goes to any file or device. If you have a
wavetable synthesizer, midi can go to /dev/midi00, otherwise you may need
a midi interpreter. For example, the midid program from the
DosEmu project would work. Wave output should go to /dev/dsp.
These devices are assumed to be OSS devices, if they're not
some of the ioctl's might fail.
On Windows, midi and output goes to the midi mapper and the wave mapper,
respectively. A future version might have selectable output devices.
</para>
</section>

<section><title>Installation on Linux</title>

<para>
<emphasis>Prerequisites:</emphasis>
</para>

<para>
A wavetable synthesizer on /dev/midi00 and a working /dev/dsp if you want real time music and sound, otherwise output to midi and wave files is also possible. 
Optionally, you can use a software midi interpreter, such as the midid program from the DosEmu project instead of /dev/midi00. 
</para>
</section>

<section><title>Configuring Bochs</title>

<para>
There are a few values in config.h that are relevant to the sound functions.
Edit config.h after running configure, but before compiling.
</para>