development.dbk

用于操作系统实现方面的调试工具

</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>

     <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>

<para>
BX_USE_SB16_SMF should be 1 unless you intend to have several sound cards
running at the same time.
</para>

<para>
BX_USE_SOUND_VIRTUAL can be 0 or 1, and determines whether the output class
uses virtual functions or not. The former is more versatile and allows to
select the class at runtime (not supported at the moment), while the latter
is slightly faster.
</para>

<para>
BX_SOUND_OUTPUT_C is the name of the class used for output.  The default is
to have no output functions, so you need to change this if you want any sound.
The following are supported at the moment:
</para>

<programlisting>
        bx_sound_linux_c    for output to /dev/dsp and /dev/midi00 on Linux
                            (and maybe other OSes that use the OSS driver)
        bx_sound_windows_c  for output to the midi and wave mapper of
                            Windows 3.1 and higher.
        bx_sound_output_c   for no output at all.
</programlisting>

<para>
Setup the SB16 emulation in your .bochsrc, according to instructions
in that file.
</para>
</section>

<section><title>Runtime configuration</title>

<para>
The source for the SB16CTRL program that is used to modify
the runtime behaviour of the SB16 emulator is included in
misc/sb16. You can compile it or download the
<ulink url="http://publish.uwo.ca/~jdrexler/bochs/">executable</ulink>.
</para>

<para>
See the section "Sound Blaster 16 Emulation" in the user documentation for
information about the commands of SB16CTRL.
</para>
</section>

<section><title>Features planned for the future</title>
<itemizedlist>
<listitem><para>Ports to more OS's, but I can't do this myself</para></listitem>
<listitem><para>Finishing the OPL3 FM emulation by translating the music to midi data</para></listitem>
</itemizedlist>
</section>

<section>
<title>Description of the sound output classes</title>

<para>
This file is intended for programmers who would like to port the sound
output routines to their platform. It gives a short outline what services
have to be provided.
</para>
<para>
You should also have a look at the exisiting files, <emphasis>SOUNDLNX.CC</emphasis>
for Linux and <emphasis>SOUNDWIN.CC</emphasis> for Windows and their respective
header files to get an idea about how these things really work.
</para>
</section>

<section><title>Files</title>

<para>
The main include file is <emphasis>bochs.h</emphasis>. It has all definitions 
for the system-independent functions that the SB16 emulation uses, which
are defined in <emphasis>sb16.h</emphasis>.
</para>

<para>
Additionally, every output driver will have an include file, which
should be included at the end of sb16.h to allow the emulator
to use that driver.
</para>

<para>
To actually make the emulator use any specific driver, 
<emphasis>BX_SOUND_OUTPUT_C</emphasis> has to be set to the name of the respective
output class.
</para>

<para>
Note that if your class contains any system-specific statements,
include-files and so on, you should enclose both the include-file and
the CC-file in an <emphasis>#if defined</emphasis> (OS-define) construct.
Also don't forget to add your file to the object list in
iodev/Makefile and iodev/Makefile.in.
</para>
</section>

<section><title>Classes</title>

<para>
The following classes are involved with the SB16 emulation:
</para>
<itemizedlist>
<listitem><para>
<emphasis>bx_sb16_c</emphasis> is the class containing the emulator itself, that
is the part acting on port accesses by the application, handling the
DMA transfers and so on. It also prepares the data for the output
classes.
</para></listitem>

<listitem><para>
<emphasis>bx_sound_output_c</emphasis> is the base output class. It has all
the methods used by the emulator, but only as stubs and does not
actually produce any output. These methods are then called by
the emulator whenever output is necessary.
</para></listitem>

<listitem><para>
<emphasis>bx_sound_OS_c</emphasis> is derived from 
<emphasis>bx_sound_output_c</emphasis>. It contains the code to generate 
output for the <emphasis>OS</emphasis> operating system. 
It is necessary to override all
the methods defined in the base class, unless virtual functions
are used. Note that this should remain an option, so try to
override all methods, even if only as stubs. They should be
declared <emphasis>virtual</emphasis> if and only if <emphasis>BX_USE_SOUND_VIRTUAL</emphasis>
is defined, just as in the examples. 
The constructor should call the inherited constructor
as usual, even though the current constructor does not do
anything yet.
</para></listitem>
</itemizedlist>
</section>


<section><title>Methods</title>
<para>
The following are the methods that the output class has to override.
All but constructor and destructor have to return either