%bochsdefs; ]> KevinLawton BryceDenney ChristopheBothamy MichaelCalabrese The development guide describes resources that are intended for developers in particular. Many Bochs resources are also covered in the User Guide, including compile instructions, bochsrc options, how to find the mailing lists, etc.

If you are an official SourceForge developer, then you can use CVS with write access. The CVS contains the most recent copy of the source code, and with write access you can upload any changes you make to the CVS server for others to use. A few extra steps are required the first time you use CVS write access.

First you need to install both cvs (Concurrent Version System) and ssh (Secure Shell). These are already installed on many UNIX systems and also Cygwin (win32 platform). If not, you can install binaries or compile cvs and ssh yourself. The links below should help you get going. CVS software and instructions are available at www.cvshome.org. A free version of secure shell called OpenSSH is at www.openssh.org. OpenSSH requires a library called OpenSSL from www.openssl.org. Be sure to install OpenSSL before trying to compile OpenSSH.

Next, you need to use secure shell to connect to cvs.sf.net. This step is a little strange, because you can't actually log in and get a shell prompt. All that will happen, when you get the username and password right, is that it will create a home directory on that machine for you. That's it! If you try it again, it will say "This is a restricted Shell Account. You cannot execute anything here." At this point, you've succeeded and you never have to do this step again, ever. ssh sfusername@cvs.sf.net Replace sfusername with your Source Forge username, of course. The first time, you will probably get a message like The authenticity of host 'cvs.sf.net' can't be established. Are you sure you want to continue? Just type yes. When it asks for a password, be sure to type your source forge password. If you have trouble logging in, be sure to use your SOURCE FORGE username and password in the ssh line, which isn't necessarily the same as your local username and password. Add the "-v" option to ssh to see more information about what is failing. If you have ssh version 2, it is possible that you might need to add "-1" to the ssh command to force it to use the version 1 protocol.

Every time you connect to the Source Forge CVS server (including cvs update, stat, commit, etc.), you must set the CVS_RSH environment variable to ssh. So just take the time now to add one of these lines to your .bashrc/.cshrc, so that the CVS_RSH setting will be there every time you log in. export CVS_RSH=ssh (bash syntax) setenv CVS_RSH ssh (csh syntax)

Finally, you should be able to do the checkout! If you already have a Bochs subdirectory directory, move it out of the way because the checkout will overwrite it. export CVSROOT=":ext:sfusername@cvs.sourceforge.net:/cvsroot/bochs" cvs -z3 checkout bochs sfusername@cvs.sourceforge.net's password: <--type your password In the CVSROOT variable, replace sfusername with your SF username. There's no need to add CVSROOT to your rc files because CVS will remember it after the checkout. The -z3 (optional) just adds some compression to make the checkout go faster. Once all the files have been downloaded, you will have a Bochs directory which is checked out with write access!

Once you have a Bochs directory with cvs write access, you can compile the files, edit them, test them, etc. See the documentation section, "Tracking the source code with CVS" for more info on CVS, in the User Manual. (FIXME: add cross reference) But what's new and different is that you can now do cvs commits. When a file is all fixed and ready to share with the rest of the world, you run a commit command to upload your version to the server. First, it's good to do a cvs update to make sure nobody else has changed it since you downloaded it last. $ cvs update file.cc sfusername@cvs.sf.net's password: <--type your password $ cvs commit file.cc sfusername@cvs.sf.net's password: <--type your password [editor opens. type log message, save, and exit.] When CVS starts an editor, The default is usually vi. If you want a different editor, set the EDITOR environment variable to the name of your preferred editor. When you're done, just save the file and quit the editor. Unless there's some problem, you will see a message that says what the new revision number for the file is, and then "done". If while you're editing the log message, you decide that you don't want to commit after all, don't save the file. Quit the editor, and when it asks where the log message went, tell it to abort. Here is an example of a successful checkin: $ cvs commit misc.txt sfusername@cvs.sf.net's password: <--type your password [edit log msg] Checking in misc.txt; /cvsroot/bochs/bochs/doc/docbook/misc.txt,v <-- misc.txt new revision: 1.6; previous revision: 1.5 done And here is an aborted one: $ cvs commit misc.txt sfusername@cvs.sf.net's password: <--type your password [quit editor without saving] Log message unchanged or not specified a)bort, c)ontinue, e)dit, !)reuse this message unchanged for remaining dirs Action: a cvs [commit aborted]: aborted by user

&FIXME;

Ideas: - how to browse code with cvsweb - how to find an identifier, variable, or specific text in the code - how to make patches with CVS

The initial versions of some sections in this chapter are based on a document written by Peter "Firefly" Lund. It was added and updated in January 2006. The Bochs virtual PC consists of many pieces of hardware. At a bare minimum there are always a CPU, a PIT (Programmable Interval Timer), a PIC (Programmable Interrupt Controller), a DMA controller, some memory (this includes both RAM and BIOS ROMs), a video card (usually VGA), a keyboard port (also handles the mouse), an RTC with battery backed NVRAM, and some extra motherboard circuitry. There might also be a NE2K ethernet card, a PCI controller, a Sound Blaster 16, an IDE controller (+ harddisks/CDROM), a SCSI controller (+ harddisks), a floppy controller, an APIC .. There may also be more than one CPU. Most of these pieces of hardware have their own C++ class - and if Bochs is configured to have more than one piece of a type of hardware, each will have its own object. The pieces of hardware communicates over a couple of buses with each other - some of the things that the buses carry are reads and writes in memory space, reads and writes in I/O space, interrupt requests, interrupt acknowledges, DMA requests, DMA acknowledges, and NMI request/acknowledge. How that is simulated is explained later.&FIXME; Other important pieces of the puzzle are: the options object (reads/writes configuration files, can be written to and queried while Bochs is running) and the GUI object. There are many different but compatible implementations of the GUI object, depending on whether you compile for X (Unix/Linux), Win32, Macintosh (two versions: one for Mac OS X and one for older OS's), BeOS, Amiga, etc. And then there is the supporting cast: debugger, config menu, panic handler, disassembler, tracer, instrumentation.

Location Meaning biosSystem and VGA BIOS images, system BIOS sources and makefilebuildadditional stuff required for building Bochs on different platformsbx_debugthe builtin Bochs debuggercputhe cpu emulation sourcesdisasmthe disassembler for the Bochs debuggerdoc/docbookthe Bochs documentation in DocBook formatdoc/manBochs manual pagesdocs-htmlold Bochs documentation in HTML (will be replaced by DocBook)dynamicempty directory (reserved for dynamic translation code)fontthe default VGA font used by most of the display librariesfputhe fpu emulation sourcesguidisplay libraries (guis), the simulator interface and text mode config interfacegui/bitmapsbitmaps for the headerbargui/keymapskeymaps for the keyboard mapping featurehosthost specific drivers (currently only used by the pcidev kernel module for Linux)instrumentdirectory tree for the instrumentation featureiodevstandard PC devices, PCI devices, lowlevel networking and sound driversmemorymemory management and ROM loadermiscuseful utilities (e.g. bximage, bxcommit, niclist)misc/sb16tool to control the SB16 emulation from the guest sidepatchespending patchesplex86plex86 directory structure (possibly outdated)

Bochs has many macros with inscrutable names. One might even go as far as to say that Bochs is macro infested. Some of them are gross speed hacks, to cover up the slow speed that C++ causes. Others paper over differences between the simulated PC configurations. Many of the macros exhibit the same problem as C++ does: too much stuff happens behind the programmer's back. More explicitness would be a big win.

C++ methods have an invisible parameter called the this pointer - otherwise the method wouldn't know which object to operate on. In many cases in Bochs, there will only ever be one object - so this flexibility is unnecessary. There is a hack that can be enabled by #defining BX_USE_CPU_SMF to 1 in config.h that makes most methods static, which means they have a "special relationship" with the class they are declared in but apart from that are normal C functions with no hidden parameters. Of course they still need access to the internals of an object, so the single object of their class has a globally visible name that these functions use. It is all hidden with macros. Declaration of a class, from iodev/pic.h: ... #if BX_USE_PIC_SMF # define BX_PIC_SMF static # define BX_PIC_THIS thePic-> #else # define BX_PIC_SMF # define BX_PIC_THIS this-> #endif ... class bx_pic_c : public bx_pic_stub_c { public: bx_pic_c(void); ~bx_pic_c(void); ... BX_PIC_SMF void service_master_pic(void); BX_PIC_SMF void service_slave_pic(void); BX_PIC_SMF void clear_highest_interrupt(bx_pic_t *pic); }; And iodev/pic.cc: ... #define LOG_THIS thePic-> ... bx_pic_c *thePic = NULL; ... void bx_pic_c::service_master_pic(void) { Bit8u unmasked_requests; int irq; Bit8u isr, max_irq; Bit8u highest_priority = BX_PIC_THIS s.master_pic.lowest_priority + 1; if(highest_priority > 7) highest_priority = 0; if (BX_PIC_THIS s.master_pic.INT) { /* last interrupt still not acknowleged */ return; } if (BX_PIC_THIS s.master_pic.special_mask) { /* all priorities may be enabled. check all IRR bits except ones * which have corresponding ISR bits set */ max_irq = highest_priority; } else { /* normal mode */ /* Find the highest priority IRQ that is enabled due to current ISR */ isr = BX_PIC_THIS s.master_pic.isr; ... } ... Ugly, isn't it? If we use static methods, methods prefixed with BX_PIC_SMF are declared static and references to fields inside the object, which are prefixed with BX_PIC_THIS, will use the globally visible object, thePic->. If we don't use static methods, BX_PIC_SMF evaluates to nothing and BX_PIC_THIS becomes this->. 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.

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. 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 &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?

&FIXME; configure script, makefiles, header files

&FIXME; log functions: what is a panic, what is an error, etc.

&FIXME;

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

A little more up-to-date version of the user related part of this section is available in the user guide. Sound Blaster 16 (SB16) emulation for Bochs was written and donated by Josef Drexler, who has a web page on the topic. The entire set of his SB16 patches have been integrated into Bochs, however, so you can find everything you need here. SB16 Emulation has been tested with several soundcards and versions of Linux. Please give Josef feedback on whether is does or doesn't work on your combination of software and hardware.

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

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.

Prerequisites: 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.

There are a few values in config.h that are relevant to the sound functions. Edit config.h after running configure, but before compiling. BX_USE_SB16_SMF should be 1 unless you intend to have several sound cards running at the same time. 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. 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: 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. Setup the SB16 emulation in your .bochsrc, according to instructions in that file.

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 executable. See the section "Sound Blaster 16 Emulation" in the user documentation for information about the commands of SB16CTRL.

Ports to more OS's, but I can't do this myself Finishing the OPL3 FM emulation by translating the music to midi data

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. You should also have a look at the exisiting files, SOUNDLNX.CC for Linux and SOUNDWIN.CC for Windows and their respective header files to get an idea about how these things really work.

The main include file is bochs.h. It has all definitions for the system-independent functions that the SB16 emulation uses, which are defined in sb16.h. 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. To actually make the emulator use any specific driver, BX_SOUND_OUTPUT_C has to be set to the name of the respective output class. 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 #if defined (OS-define) construct. Also don't forget to add your file to the object list in iodev/Makefile and iodev/Makefile.in.

The following classes are involved with the SB16 emulation: bx_sb16_c 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. bx_sound_output_c 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. bx_sound_OS_c is derived from bx_sound_output_c. It contains the code to generate output for the OS 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 virtual if and only if BX_USE_SOUND_VIRTUAL 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.

The following are the methods that the output class has to override. All but constructor and destructor have to return either BX_SOUND_OUTPUT_OK (0) if the function was successful, or BX_SOUND_OUTPUT_ERR (1) if not. If any of the initialization functions fail, output to that device is disabled until the emulator is restarted.

The emulator instantiates the class at the initialization of Bochs. Description of the parameter: sb16 is a pointer to the emulator class. This pointer can then be used to access for example the writelog function to generate sound-related log messages. Apart from that, no access to the emulator should be necessary. The constructor should not allocate the output devices. This shouldn't be done until the actual output occurs; in either initmidioutput() or initwaveoutput(). Otherwise it would be impossible to have two copies of Bochs running concurrently (if anybody ever wants to do this).

The instance is destroyed just before Bochs ends.

openmidioutput() is called when the first midi output starts. It is only called if the midi output mode is 1 (midimode 1). It should prepare the given MIDI hardware for receiving midi commands. openmidioutput() will always be called before openwaveoutput(), and closemidioutput()will always be called before closewaveoutput(), but not in all cases will both functions be called.

device is a system-dependent variable. It contains the value of the MIDI=device configuration option. Note that only one midi output device will be used at any one time. device may not have the same value throughout one session, but it will be closed before it is changed.

midiready() is called whenever the applications asks if the midi queue can accept more data. Return values: BX_SOUND_OUTPUT_OK if the midi output device is ready. BX_SOUND_OUTPUT_ERR if it isn't ready. Note: midiready() will be called a few times before the device is opened. If this is the case, it should always report that it is ready, otherwise the application (not Bochs) will hang.

sendmidicommand()is called whenever a complete midi command has been written to the emulator. It should then send the given midi command to the midi hardware. It will only be called after the midi output has been opened. Note that if at all possible it should not wait for the completion of the command and instead indicate that the device is not ready during the execution of the command. This is to avoid delays in the program while it is generating midi output. Description of the parameters: delta is the number of delta ticks that have passed since the last command has been issued. It is always zero for the first command. There are 24 delta ticks per quarter, and 120 quarters per minute, thus 48 delta ticks per second. command is the midi command byte (sometimes called status byte), in the usual range of 0x80..0xff. For more information please see the midi standard specification. length is the number of data bytes that are contained in the data structure. This does not include the status byte which is not replicated in the data array. It can only be greater than 3 for SysEx messages (commands 0xF0 and 0xF7) data[] is the array of these data bytes, in the order they have in the standard MIDI specification. Note, it might be NULL if length==0.

closemidioutput() is called before shutting down Bochs or when the emulator gets the stop_output command through the emulator port. After this, no more output will be necessary until openmidioutput() is called again, but midiready() might still be called. It should do the following: Wait for all remaining messages to be completed Reset and close the midi output device

openwaveoutput() is called when the first wave output occurs, and only if the selected wavemode is 1. It should do the following: Open the given device, and prepare it for wave output or Store the device name so that the device can be opened in startplayback(). openmidioutput() will always be called before openwaveoutput(), and closemidioutput()will always be called before closewaveoutput(), but not in all cases will both functions be called. openwaveoutput() will typically be called once, whereas startplayback() is called for every new DMA transfer to the SB16 emulation. If feasible, it could be useful to open and/or lock the output device in startplayback() as opposed to openwaveoutput() to ensure that it can be used by other applications while Bochs doesn't need it. However, many older applications don't use the auto-init DMA mode, which means that they start a new DMA transfer for every single block of output, which means usually for every 2048 bytes or so. Unfortunately there is no way of knowing whether the application will restart an expired DMA transfer soon, so that in these cases the startwaveplayback function will be called very often, and it isn't a good idea to have it reopen the device every time. The buffer when writing to the device should not be overly large. Usually about four buffers of 4096 bytes produce best results. Smaller buffers could mean too much overhead, while larger buffers contribute to the fact that the actual output will always be late when the application tries to synchronize it with for example graphics. The parameters are the following: device is the wave device selected by the user. It is strictly system-dependent. The value is that of the WAVE=device configuration option. Note that only one wave output device will be used at any one time. device may not have the same value throughout one session, but it will be closed before it is changed.

This function is called whenever the application starts a new DMA transfer. It should do the following: Open the wave output device, unless openwaveoutput() did that already Prepare the device for data and set the device parameters to those given in the function call The parameters are the following: frequency is the desired frequency of the output. Because of the capabities of the SB16, it can have any value between 5000 and 44,100. bits is either 8 or 16, denoting the resolution of one sample. stereo is either 1 for stereo output, or 0 for mono output. format is a bit-coded value (see below). Bit number Meaning 0 (LSB) 0: unsigned data 1: signed data 1..6 Type of codec (see below) 7 0: no reference byte 1: with reference byte 8..x reserved (0) Value Meaning 0 PCM (raw data) 1 reserved 2 2-bit ADPCM (Creative Labs format) 3 2.4-bit (3-bit) ADPCM (Creative Labs format) 4 4-bit ADPCM (Creative Labs format) Other codecs are not supported by the SB hardware. In fact, most applications will translate their data into raw data, so that in most cases the codec will be zero. The number of bytes per sample can be calculated from this as (bits / 8) * (stereo + 1).

This is called whenever the emulator has another output buffer ready and would like to pass it to the output class. This happens every BX_SOUND_OUTPUT_WAVEPACKETSIZE bytes, or whenever a DMA transfer is done or aborted. It should return whether the output device is ready for another buffer of BX_SOUND_OUTPUT_WAVEPACKETSIZE bytes. If BX_SOUND_OUTPUT_ERR is returned, the emulator waits about 1/(frequency * bytes per sample) seconds and then asks again. The DMA transfer is stalled during that time, but the application keeps running, until the output device becomes ready. As opposed to midiready(), waveready() will not be called unless the device is open.

This function is called whenever a data packet of at most BX_SB16_WAVEPACKETSIZE is ready at the SB16 emulator. It should then do the following: Send this wave packet to the wave hardware This function has to be synchronous, meaning that it has to return immediately, and not wait until the output is done. Also, this function might be called before the previous output is done. If your hardware can't append the new output to the old one, you will have to implement this yourself, or the output will be very chunky, with as much silence between the blocks as the blocks take to play. This is not what you want. Instead, waveready() should return BX_SOUND_OUTPUT_ERR until the device accepts another block of data. Parameters: length is the number of data bytes in the data stream. It will never be larger than BX_SB16_WAVEPACKETSIZE. data is the array of data bytes. The order of bytes in the data stream is the same as that in the Wave file format: Output type Sequence of data bytes 8 bit mono Sample 1; Sample 2; Sample 3; etc. 8 bit stereo Sample 1, Channel 0; Sample 1, Channel 1; Sample 2, Channel 0; Sample 2, Channel 1; etc. 16 bit mono Sample 1, LSB; Sample 1, MSB; Sample 2, LSB; Sample 2, MSB; etc. 16 bit stereo Sample 1, LSB, Channel 0; Sample 1, MSB, Channel 0; Sample 1, LSB, Channel 1; Sample 1, MSB, Channel 1; etc. Typically 8 bit data will be unsigned with values from 0 to 255, and 16 bit data will be signed with values from -32768 to 32767, although the SB16 is not limited to this. For further information on the codecs and the use of reference bytes please refer to the Creative Labs Sound Blaster Programmer's Manual, which can be downloaded from the Creative Labs web site.

This function is called at the end of a DMA transfer. It should do the following: Close the output device if it was opened by startwaveplayback(). and it's not going to be opened soon. Which is almost impossible to tell.

This function is called just before Bochs exits. It should do the following: Close the output device, if this hasn't been done by stopwaveplayback(). Typically, stopwaveplayback() will be called several times, whenever a DMA transfer is done, where closewaveoutput() will only be called once. However, in the future it might be possible that openwaveoutput() is called again, for example if the user chose to switch devices while Bochs was running. This is not supported at the moment, but might be in the future.

This section describes how the three new disk images "undoable", "growing", and "volatile" are implemented in Bochs 2.1 : undoable -> flat file, plus growing, commitable, rollbackable redolog file growing -> growing files, all previously unwritten sectors go to the end of file volatile -> flat file, plus hidden growing redolog

The idea behind volatile and undoable disk images is to have a flat file, associated with one redolog file. Reading a sector is done from the redolog file if it contains the sector, or from the flat file otherwise. Sectors written go to the redolog, so flat files are opened in read only mode in this configuration. The redolog is designed in a way so it starts as a small file and grows with every new sectors written to it. Previously written sectors are done in place. Redolog files can not shrink. The redolog is a growing file that can be created on the fly. Now, it turns out that if you only use a redolog without any flat file, you get a "growing" disk image. So "undoable", "volatile" and "growing" harddisk images classes are implemented on top of a redolog class.

At the start of a redolog file, there is a header, so Bochs can check whether a file is consistent. This header could also be checked when we implement automatic type and size detection. The generic part of the header contains values like type of image, and spec version number. The header also has a specific part. For redologs, the number of entries of the catalog, the extent, bitmap and disk size are stored. In a redolog, the disk image is divided in a number of equal size "extents". Each extent is a collection of successive 512-bytes sectors of the disk image, preceeded by a n*512bytes bitmap. the n*512bytes bitmap defines the presence (data has been written to it) of a specific sector in the extent, one bit for each sector. Therefore with a 512bytes bitmap, each extent can hold up to 4k blocks Typically the catalog can have 256k entries. With a 256k entries catalog and 512bytes bitmaps, the redolog can hold up to 512GiB All data is stored on images as little-endian values

At the start of a redolog file, there is a header. This header is designed to be reusable by other disk image types. The header length is 512 bytes. It contains : Start position in bytes Length in bytes Data type Description Possible values 0 32 string magical value Bochs Virtual HD Image 32 16 string type of file Redolog 48 16 string subtype of file Undoable, Volatile, Growing 64 4 Bit32u version of used specification 0x00010000 68 4 Bit32u header size 512 Start position in bytes Length in bytes Data type Description 72 4 Bit32u number of entries in the catalog 76 4 Bit32u bitmap size in bytes 80 4 Bit32u extent size in bytes 84 8 Bit64u disk size in bytes

Immediately following the header, there is a catalog containing the position number (in extents) where each extent is located in the file. Each position is a Bit32u entity.

&FIXME;

The following tables shows what parameters are used when creating redologs or creating "growing" images : Catalog entries Catalog size(KiB) Bitmap size (B) Extent size (KiB) Disk Max Size 512 2 1 4 2MiB 512 2 2 8 4MiB 1k 4 2 8 8MiB 1k 4 4 16 16MiB 2k 8 4 16 32MiB 2k 8 8 32 64MiB 4k 16 8 32 128MiB 4k 16 16 64 256MiB 8k 32 16 64 512MiB 8k 32 32 128 1GiB 16k 64 32 128 2GiB 16k 64 64 256 4GiB 32k 128 64 256 8GiB 32k 128 128 512 16GiB 64k 256 128 512 32GiB 64k 256 256 1024 64GiB 128k 512 256 1024 128GiB 128k 512 512 2048 256GiB 256k 1024 512 2048 512GiB 256k 1024 1024 4096 1TiB 512k 2048 1024 4096 2TiB 512k 2048 2048 8192 4TiB 1024k 4096 2048 8192 8TiB 1024k 4096 4096 16384 16TiB 2048k 8192 4096 16384 32TiB

The class redolog_t(); implements the necessary methods to create, open, close, read and write data to a redolog. Managment of header catalog and sector bitmaps is done internally by the class.

#define STANDARD_HEADER_MAGIC "Bochs Virtual HD Image" #define STANDARD_HEADER_VERSION (0x00010000) #define STANDARD_HEADER_SIZE (512) These constants are used in the generic part of the header. #define REDOLOG_TYPE "Redolog" #define REDOLOG_SUBTYPE_UNDOABLE "Undoable" #define REDOLOG_SUBTYPE_VOLATILE "Volatile" #define REDOLOG_SUBTYPE_GROWING "Growing" These constants are used in the specific part of the header. #define REDOLOG_PAGE_NOT_ALLOCATED (0xffffffff) This constant is used in the catalog for an unwritten extent.

redolog_t(); instanciates a new redolog. int make_header (const char* type, Bit64u size); creates a header structure in memory, and sets its type and parameters based on the disk image size. Returns 0. int create (const char* filename, const char* type, Bit64u size); creates a new empty redolog file, with header and catalog, named filename of type type for a size bytes image. Returns 0 for OK or -1 if a problem occured. int create (int filedes, const char* type, Bit64u size); creates a new empty redolog file, with header and catalog, in a previously opened file described by filedes, of type type for a size bytes image. Returns 0 for OK or -1 if a problem occured. int open (const char* filename, const char* type, Bit64u size); opens a redolog file named filename, and checks for consistency of header values against a type and size. Returns 0 for OK or -1 if a problem occured. void close (); closes a redolog file. off_t lseek (off_t offset, int whence); seeks at logical data offset offset in a redolog. offset must be a multiple of 512. Only SEEK_SET is supported for whence. Returns -1 if a problem occured, or the current logical offset in the redolog. ssize_t read (void* buf, size_t count); reads count bytes of data of the redolog, from current logical offset, and copies it into buf. count must be 512. Returns the number of bytes read, that can be 0 if the data has not previously be written to the redolog. ssize_t write (const void* buf, size_t count); writes count bytes of data from buf to the redolog, at current logical offset. count must be 512. Returns the number of bytes written.

"volatile" and "undoable" disk images are easily implemented by instanciating a default_image_t object (flat image) and a redolog_t object (redolog). "growing" disk images only instanciates a redolog_t object. Classe names are undoable_image_t, volatile_image_t and growing_image_t. When using these disk images, the underlying data structure and layout is completely hidden to the caller. Then, all offset and size values are "logical" values, as if the disk was a flat file.

#define UNDOABLE_REDOLOG_EXTENSION ".redolog" #define UNDOABLE_REDOLOG_EXTENSION_LENGTH (strlen(UNDOABLE_REDOLOG_EXTENSION)) #define VOLATILE_REDOLOG_EXTENSION ".XXXXXX" #define VOLATILE_REDOLOG_EXTENSION_LENGTH (strlen(VOLATILE_REDOLOG_EXTENSION)) These constants are used when building redolog file names

undoable_image_t(Bit64u size, const char* redolog_name); instanciates a new undoable_image_t object. This disk image logical length is size bytes and the redolog filename is redolog_name. int open (const char* pathname); opens the flat disk image pathname, as an undoable disk image. The associated redolog will be named pathname with a UNDOABLE_REDOLOG_EXTENSION suffix, unless set in the constructor. Returns 0 for OK or -1 if a problem occured. void close (); closes the flat image and its redolog. off_t lseek (off_t offset, int whence); seeks at logical data position offset in the undoable disk image. Only SEEK_SET is supported for whence. Returns -1 if a problem occured, or the current logical offset in the undoable disk image. ssize_t read (void* buf, size_t count); reads count bytes of data from the undoable disk image, from current logical offset, and copies it into buf. count must be 512. Returns the number of bytes read. Data will be read from the redolog if it has been previously written or from the flat image otherwise. ssize_t write (const void* buf, size_t count); writes count bytes of data from buf to the undoable disk image, at current logical offset. count must be 512. Returns the number of bytes written. Data will always be written to the redolog.

volatile_image_t(Bit64u size, const char* redolog_name); instanciates a new volatile_image_t object. This disk image logical length is size bytes and the redolog filename is redolog_name plus a random suffix. int open (const char* pathname); opens the flat disk image pathname, as a volatile disk image. The associated redolog will be named pathname with a random suffix, unless set in the constructor. Returns 0 for OK or -1 if a problem occured. void close (); closes the flat image and its redolog. The redolog is deleted/lost after close is called. off_t lseek (off_t offset, int whence); seeks at logical data position offset in the volatile disk image. Only SEEK_SET is supported for whence. Returns -1 if a problem occured, or the current logical offset in the volatile disk image. ssize_t read (void* buf, size_t count); reads count bytes of data from the volatile disk image, from current logical offset, and copies it into buf. count must be 512. Returns the number of bytes read. Data will be read from the redolog if it has been previously written or from the flat image otherwise. ssize_t write (const void* buf, size_t count); writes count bytes of data from buf to the volatile disk image, at current logical offset. count must be 512. Returns the number of bytes written. Data will always be written to the redolog.

growing_image_t(Bit64u size); instanciates a new growing_image_t object. This disk image logical length is size bytes. int open (const char* pathname); opens the growing disk image pathname, Returns 0 for OK or -1 if a problem occured. void close (); closes the growing disk image. off_t lseek (off_t offset, int whence); seeks at logical data position offset in the growable disk image. Only SEEK_SET is supported for whence. Returns -1 if a problem occured, or the current logical offset in the grwoing image. ssize_t read (void* buf, size_t count); reads count bytes of data from the growing disk image, from current logical offset, and copies it into buf. count must be 512. Returns the number of bytes read. The buffer will be filled with null bytes if data has not been previously written to the growing image. ssize_t write (const void* buf, size_t count); writes count bytes of data from buf to the growing disk image, at current logical offset. count must be 512. Returns the number of bytes written.

Christophe Bothamy, wrote the keymapping code for Bochs, provided these instructions to help developers to add keymapping to a GUI. Bochs creates a bx_keymap_c object named bx_keymap. This object allows you to : - load the configuration specified keymap file - get the translated BX_KEY_* from your GUI key You have to provide a translation function from string to your Bit32u key constant. Casting will be necessary if your key constants are not Bit32u typed. The function must be "static Bit32u (*)(const char *)" typed, and must return BX_KEYMAP_UNKNOWN if it can not translate the parameter string. What you have to do is : - call once "void loadKeymap(Bit32u (*)(const char*))", providing your translation function, to load the keymap - call "Bit32u getBXKey(Bit32u)" that returns the BX_KEY_* constant, for each key you want to map. The file gui/x.cc implements this architecture, so you can refer to it as an example.

&FIXME;

&FIXME;

&FIXME;

&FIXME;

Don't make use of any external C++ classes. They are not offered on all platforms and this would make bochs non-portable. There is use of such classes in the optional debugger. I plan on removing this use. Don't use fancy C++ features. Bochs is incredibly performance sensitive, and will be increasingly so as more speed enhancements are added. There's a time and place for most everything and this is not it. Some advanced features create overhead in the generated code that you don't see. They also convolute the code, and sometimes occlude that is really going on. Don't use templates Don't use virtual functions if not strictly required Don't use C++ exceptions Don't use overloading of any kind Use soft tabs. At least when you submit code, convert all hard tabs to spaces. There is no uniform way to handle tabs properly. Please do compile with all warnings turned on. It's really difficult to spot interesting warnings when a compile is littered with non-interesting ones. Don't use signed ints where unsigned will do.

&FIXME; how to make, where to submit, what happens then?

Update version number and strings in configure.in. VERSION="2.2.pre2" VER_STRING="2.2.pre2" REL_STRING="Build from CVS snapshot on March 25, 2005" In the README file you have to update version number and date. Add some information about new features if necessary. Bochs x86 Pentium+ Emulator Updated: Fri Mar 25 10:33:15 CET 2005 Version: 2.2.pre2 Check date, update/sumup info in CHANGES. Run autoconf to regenerate configure and check them in. Create a CVS tag to mark which revision of each file was used in the release. For prereleases I make a normal CVS tag like this: cvs tag REL_2_2_pre2_FINAL But for a real release, I make a CVS branch tag AND a normal tag. cvs tag REL_2_2_BASE cvs tag -b REL_2_2 The base tag marks where the branch split off of the main trunk. This is very useful in maintaining the branch since you can do diffs against it. cvs diff -r REL_2_2_BASE -r HEAD cvs diff -r REL_2_2_BASE -r REL_2_0 cvs upd -j REL_2_2_BASE -j HEAD file etc. The release and all bugfix releases after it are on the REL_2_2 branch. When the release is actually finalized, you can do this: cvs tag REL_2_2_FINAL Now you can start building packages based on the created release tag.

These instructions require cygwin and MSVC++. In Cygwin: sh .conf.win32-vcpp # runs configure make win32_snap # unzip workspace, make a win32 source ZIP Copy the source ZIP to a windows machine, if necessary. Open up Visual C++ and load the workspace file Bochs.dsw. Check the Build:Set Active Project Configuration is set the way you want it. For releases I use "Win32 Release". To create "bochsdbg.exe" with Bochs debugger support, manually change two lines in config.h to turn on the debugger. #define BX_DEBUGGER 1 #define BX_DISASM 1 VC++ will rebuild Bochs with debugger and overwrite bochs.exe. To avoid trashing the non-debug version, move it out of the way while the debugger version is being built. Then rename the debugger version to bochsdbg.exe. cd obj-release mv bochs.exe bochs-normal.exe (build again with BX_DEBUGGER=1 this time) mv bochs.exe bochsdbg.exe mv bochs-normal.exe bochs.exe To get the docbook installed, you need to do something like this: make dl_docbook copy up to date doc files Then you can do cd doc/docbook; touch */*.html Do make install_win32 into /tmp or someplace: make install_win32 prefix=/tmp/bochs-2.2.pre2 This copies all the files into /tmp/bochs-2.2.pre2 and then creates a binary ZIP at /tmp/bochs-2.2.pre2.zip. Rename that bochs-2.2.pre2.win32-bin.zip. Now make the NSIS installer package (the current script is known to work with NSIS 2.03) cd build/win32/nsis Unzip the binary ZIP file into bochs-$VERSION (must match Makefile) and then run make. unzip ~/bochs-2.2.pre2.zip make That gives an installer called Bochs-2.2.pre2.exe. Test and upload it.

Do a clean checkout using anonymous cvs, so that the source tarball will be all set up for anonymous cvs. First I'll create a clean directory called "clean-anon". cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bochs login cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bochs \ checkout -d clean-anon bochs Start with clean-anon which tracks the CVS head. Change its sticky tag so that it sticks to the release tag. cp -a clean-anon bochs-2.2.pre2 cd bochs-2.2.pre2 cvs upd -P -r REL_2_2_pre2_FINAL cd .. tar czvf bochs-2.2.pre2.tar.gz --exclude CVS --exclude .cvsignore bochs-2.2.pre2 The source TAR file bochs-2.2.pre2.tar.gz is ready to upload. The RPM will be building using the configuration in .conf.linux with a few parameters from build/redhat/make-rpm. Make any last minute changes to .conf.linux. Any changes will go into the source RPM. WARNING : do not build in /tmp/bochs-XXX... ./build/redhat/make-rpm | tee ../build.txt This produces two rpm files in the current directory. Test and upload.

When you are ready with creating release packages you have to upload them to SF using anonymous FTP using this location: upload.sourceforge.net/incoming Note that you cannot modify or delete files after uploading them. If you don't do anything with the uploaded files, they will be deleted by SF after 24 hours. To create or edit a file release you have to log in to the Admin section on the SF project page of Bochs. Then you have to go to the File Releases page and follow the instructions there.

&FIXME;

&FIXME;

&FIXME;

&FIXME;

&FIXME; sources, tmp

&FIXME; sources, tmp