%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 SVN with write access. The SVN contains the most recent copy of the source code, and with write access you can upload any changes you make to the SVN server for others to use. The SVN checkout command is identical to the one for normal users, but you might want to get the whole tree to work with branches and tags. svn co https://svn.code.sf.net/p/bochs/code bochs-svn Depending on your network connection this may take a long time, since it downloads all files from all branches and tags that exist in the repository at the current revision.

Once you have a Bochs directory, you can compile the files, edit them, test them, etc. See the documentation section, Tracking the source code with SVN for more info on SVN, in the User Manual. But what's new and different is that you can now do SVN 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 SVN update to make sure nobody else has changed it since you downloaded it last. At the first commit you'll always have to specify your SF username and type your password. $ svn update file.cc $ svn commit --username sfusername file.cc [editor opens. type log message, save, and exit.] Login area: <https://svn.code.sf.net:443> SourceForge Subversion area Username: sfusername Password for 'sfusername': <--type your password Sending file.cc Transmitting file data . Committed revision 10. When SVN 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 SVN revision number 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: $ svn commit misc.txt [edit log msg] Sending misc.txt Transmitting file data . Committed revision 6. And here is an aborted one: $ svn commit misc.txt [quit editor without saving] Log message unchanged or not specified a)bort, c)ontinue, e)dit: a

Backups of the SVN repository can be made with the rsync utility. In case of data corruption or other problems on the server, the repository with all revisions, branches and tags can be restored easily. It is recommended to update this backup frequently. The following example creates a folder called bochs-svn-rsync that contains the repository. rsync -av svn.code.sf.net::p/bochs/code bochs-svn-rsync

The Bochs SVN repository is set up to send a notification email to the "bochs-cvs" mailing list after each successful commit. This email contains the log message, a list of the modified files and a diff against the previous revision. The diff of large commits will be truncated at 96 kByte. After each commit the SVN server runs the script post-commit located in the hooks folder. On SourceForge, this script forces a refresh of the Allura code browser and it can call a script post-commit-user for addition operations if it exists. For Bochs we have set up this script and call svnnotify from it to create the notification email. #!/bin/sh svnnotify --repos-path $1 --revision $2 -O -C -d -e 98304 -t bochs-cvs@lists.sourceforge.net

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

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 an ethernet card, a PCI controller, a soundcard, 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; In addition to the simulator itself, some other components are required for the communication with the user. The most important parts are these: the window that simulates the monitor and receives keyboard / mouse events the configuration interface that allows to adjust simulation settings the simulator interface for the communication between the other componnents the parameter tree (for configuration settings and save/restore) the logfunctions class (handle and configure panic/error/info/debug) These componnents of Bochs are optional: the plugin interface the builtin debugger the disassembler the instrumentation feature The simulation window is handled by the GUI object (other terms used in the sources are "display library", "VGAW"). 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), Amiga, etc. The cross-platform libraries SDL and wxWidgets are also supported. For the configuration interface there are also some different implementations: textconfig (text menus only), wxdialog (wxWidgets port), win32dialog/win32paramdlg (Windows port).

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 sourcescpu/fputhe fpu 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)guidisplay libraries (guis), the simulator interface and text mode config interfacegui/bitmapsbitmaps for the headerbargui/fontthe default VGA font used by most of the display librariesgui/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 core devicesiodev/displaydisplay adapters (vga, cirrus, voodoo)iodev/hdimagesupport for different disk image types and lowlevel cdrom accessiodev/networkingnetworking devices and lowlevel modulesiodev/soundsound devices and lowlevel modulesiodev/usbUSB HCs and pluggable devicesmemorymemory management and ROM loadermiscuseful utilities (e.g. bximage, bxcommit, niclist)misc/sb16tool to control the SB16 emulation from the guest sidepatchespending patches

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?

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. 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. Bit32u megs = SIM->get_param_num("memory.standard.ram.size")->get(); 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. The table below shows all parameter types used by the Bochs configuration interface. Type Description bx_object_c Base class for all the other parameter types. It contains the unique parameter id and the object type value. bx_param_c Generic parameter class. It contains the name, label, description and the input/output formats. bx_param_num_c Numerical (decimal/hex) config settings are stored in this parameter type. bx_param_bool_c 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. bx_param_enum_c Based on bx_param_num_c this parameter type contains a list of valid values. bx_param_string_c Configuration strings are stored in this type of parameter. bx_param_filename_c Based on bx_param_string_c this parameter type is used for file names. bx_list_c Contains a list of pointers to parameters (bx_param_*_c and bx_list_c). In the config interface it is used for menus/dialogs.

The save/restore feature is based on an extension to the parameter tree concept. A subtree (list) called "bochs" 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. The filename is then created from the full parameter path without the prefix "bochs.". The table below shows the additional parameter types for save/restore. Type Description bx_shadow_num_c Based on bx_param_num_c this type stores a pointer to a numerical variable. bx_shadow_bool_c This parameter type stores a pointer to a boolean variable (bit #0 only) or a numerical one (only one selected bit). bx_shadow_data_c This special parameter type stores pointer size of a binary array. The data is saved in a separate file and the text file uses the file name as the value. bx_shadow_filedata_c This special parameter type stores the descriptor of an open file (added in Bochs 2.5). 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 saved to and restored from one single parameter. The disk image state is also handled this way (see below). All devices can uses these two save/restore specific methods: register_state() is called after the device init() to register the device members for save/restore after_restore_state() is an optional method to do things directly after restore (e.g. vga: force a display update) To implement save/restore for hard drive images, the new method register_state() has been added to the base class of the disk image objects. It creates a bx_param_bool_c object called "image" and installs static save and restore handlers. The save operation finally sets the parameter's value (1 = success) and the save/restore handlers are doing the main job. The static handlers call the class-specific code. Depending on the image "mode" they copy either the whole image file or the file containing changes (journal). The files are saved similar to binary arrays with the same naming convention. The restore methods are doing some format or coherency checks, close the open image, copy the file(s) and finally re-open the image.

Like many other open source projects, Bochs uses a configure script created with autoconf. The configure script generates all makefiles and a set of header and support files from templates. This example shows how to add an option to the template file configure.in. The resulting configure script sets up symbols like BX_SUPPORT_BUSMOUSE in the output file config.h and replaces @BUSM_OBJS@ entries in the makefile output. BUSM_OBJS='' AC_MSG_CHECKING(for Busmouse support) AC_ARG_ENABLE(busmouse, AS_HELP_STRING([--enable-busmouse], [enable Busmouse support (InPort)]), [if test "$enableval" = yes; then AC_MSG_RESULT(yes) AC_DEFINE(BX_SUPPORT_BUSMOUSE, 1) BUSM_OBJS='busmouse.o' else AC_MSG_RESULT(no) AC_DEFINE(BX_SUPPORT_BUSMOUSE, 0) fi], [ AC_DEFINE(BX_SUPPORT_BUSMOUSE, 0) AC_MSG_RESULT(no)] ) AC_SUBST(BUSM_OBJS) These output files are generated by the configure script in addition to the makefiles. config.h - the main header file ltdlconf.h - header file required for compiling with libtool bxversion.h - header file containing version strings bxversion.rc - resource file for Windows with version information build/linux/bochs-dlx - DLX Linux shortcut script (Linux only) build/macosx/Info.plist - property list file for MacOSX build/win32/nsis/bochs.nsi - NSIS script for creating Windows installer package

The logfunctions class is one of the base classes of Bochs. It supports 4 log levels (debug, info, error, panic) and 4 possible "actions" that can be done when a log event occurs. Most of the higher level C++ classes of Bochs inherit this class to make the logging configuration per object (here called "module") possible. In the Bochs sources the log events appear as macros (BX_DEBUG, BX_INFO, BX_ERROR, BX_PANIC) and they call the related logfunction methods, unless the symbol BX_NO_LOGGING is set to 1. This is the definition in bochs.h: typedef class BOCHSAPI logfunctions { char *name; char *prefix; int onoff[N_LOGLEV]; class iofunctions *logio; // default log actions for all devices, declared and initialized // in logio.cc. BOCHSAPI_CYGONLY static int default_onoff[N_LOGLEV]; public: logfunctions(void); logfunctions(class iofunctions *); ~logfunctions(void); void info(const char *fmt, ...) BX_CPP_AttrPrintf(2, 3); void error(const char *fmt, ...) BX_CPP_AttrPrintf(2, 3); void panic(const char *fmt, ...) BX_CPP_AttrPrintf(2, 3); void ldebug(const char *fmt, ...) BX_CPP_AttrPrintf(2, 3); void fatal (const char *prefix, const char *fmt, va_list ap, int exit_status); void ask (int level, const char *prefix, const char *fmt, va_list ap); void put(const char *p); void put(const char *n, const char *p); void setio(class iofunctions *); void setonoff(int loglev, int value) { assert (loglev >= 0 && loglev < N_LOGLEV); onoff[loglev] = value; } const char *get_name() const { return name; } const char *getprefix() const { return prefix; } int getonoff(int level) const { assert (level>=0 && level<N_LOGLEV); return onoff[level]; } static void set_default_action(int loglev, int action) { assert (loglev >= 0 && loglev < N_LOGLEV); assert (action >= 0 && action < N_ACT); default_onoff[loglev] = action; } static int get_default_action(int loglev) { assert (loglev >= 0 && loglev < N_LOGLEV); return default_onoff[loglev]; } } logfunc_t;

Here is a short description of some logfunctions methods. The constructor registers a new log module with default values. The module's log prefix is empty and the log levels are set up with default actions. The destructor removes the log module from the table. The info(), error(), panic() and ldebug() methods are called via macros to create a log event of the related level. The fatal() method is called if a log event occurs and it's action is set to "fatal". It is used to shut down the Bochs simulation. The ask() method is called if a log event occurs and it's action is set to "ask". It sends an event to the simulator interface and depending on the return value the simulation continues or it is terminated by calling fatal(). The simulator interface either prompts the user on the console or calls some platform / gui specific code to handle the ask request. The put() methods are used to set up the log module prefix in that appears in the log file and the log module name that appears in the config interface. If the name is not specified, the prefix is used instead. The setio() method sets up the iofunctions class for the log file output. This method is only used by the logfunctions constructors. The getonoff() and setonoff() methods are used by the config interface to display and change the log actions for a Bochs facility. The get_default_action() and set_default_action() methods are also used by the config interface to set up the default action for a log level. The get_name() and getprefix() methods return the strings set up with the put() method. The config interface is also using them to build the menu / dialog to set up the log functions.

The Bochs internal timers are required to provide timer features in the device emulation and for the interaction between simulator and gui. They are implemented in the bx_pc_system_c class and driven by the cpu. When programming a timer the interval is specified in useconds and the timer code translates the value to cpu ticks using the IPS value. In the original implementation the cpu object calls a timer method to increment the system time by one tick after completing one instruction. If a timer has expired, the related timer handler function is called. Now it is also possible to execute a number of cpu instructions, finally update the timer subsystem with this number and possibly call several timer handlers. Here are some examples for timers in the devices and gui code: the PIT (i82C54) system timer at 18.2 Hz the CMOS RTC one-second-timer the display update timer (set up with "vga: update_freq=X") the devices timer (polls keyboard/mouse events from the gui every 1 msecond) the LED auto-off timer (indicating data transfer for min 0.5 seconds) the synchronization timers are also based on the standard timers These are the capabilities of the Bochs internal timers: register / unregister at runtime activate / deactivate at runtime timer period changeable one-shot or continuous mode

Here are the timer-related definitions and members in pc_system.h: #define BX_MAX_TIMERS 64 #define BX_NULL_TIMER_HANDLE 10000 typedef void (*bx_timer_handler_t)(void *); struct { bx_bool inUse; // Timer slot is in-use (currently registered). Bit64u period; // Timer periodocity in cpu ticks. Bit64u timeToFire; // Time to fire next (in absolute ticks). bx_bool active; // 0=inactive, 1=active. bx_bool continuous; // 0=one-shot timer, 1=continuous periodicity. bx_timer_handler_t funct; // A callback function for when the // timer fires. void *this_ptr; // The this-> pointer for C++ callbacks // has to be stored as well. #define BxMaxTimerIDLen 32 char id[BxMaxTimerIDLen]; // String ID of timer. Bit32u param; // Device-specific value assigned to timer (optional) } timer[BX_MAX_TIMERS]; unsigned numTimers; // Number of currently allocated timers. unsigned triggeredTimer; // ID of the actually triggered timer. Bit32u currCountdown; // Current countdown ticks value (decrements to 0). Bit32u currCountdownPeriod; // Length of current countdown period. Bit64u ticksTotal; // Num ticks total since start of emulator execution. Bit64u lastTimeUsec; // Last sequentially read time in usec. Bit64u usecSinceLast; // Number of useconds claimed since then. // A special null timer is always inserted in the timer[0] slot. This // make sure that at least one timer is always active, and that the // duration is always less than a maximum 32-bit integer, so a 32-bit // counter can be used for the current countdown. static const Bit64u NullTimerInterval; static void nullTimer(void* this_ptr); These are the public timer-related methods for timer control, driving the timers with the cpu and retrieving the internal time implemented in the bx_pc_system_c class: void initialize(Bit32u ips); int register_timer(void *this_ptr, bx_timer_handler_t, Bit32u useconds, bx_bool continuous, bx_bool active, const char *id); bx_bool unregisterTimer(unsigned timerID); void setTimerParam(unsigned timerID, Bit32u param); void start_timers(void); void activate_timer(unsigned timer_index, Bit32u useconds, bx_bool continuous); void deactivate_timer(unsigned timer_index); unsigned triggeredTimerID(void) { return triggeredTimer; } Bit32u triggeredTimerParam(void) { return timer[triggeredTimer].param; } static BX_CPP_INLINE void tick1(void) { if (--bx_pc_system.currCountdown == 0) { bx_pc_system.countdownEvent(); } } static BX_CPP_INLINE void tickn(Bit32u n) { while (n >= bx_pc_system.currCountdown) { n -= bx_pc_system.currCountdown; bx_pc_system.currCountdown = 0; bx_pc_system.countdownEvent(); // bx_pc_system.currCountdown is adjusted to new value by countdownevent(). } // 'n' is not (or no longer) >= the countdown size. We can just decrement // the remaining requested ticks and continue. bx_pc_system.currCountdown -= n; } int register_timer_ticks(void* this_ptr, bx_timer_handler_t, Bit64u ticks, bx_bool continuous, bx_bool active, const char *id); void activate_timer_ticks(unsigned index, Bit64u instructions, bx_bool continuous); Bit64u time_usec(); Bit64u time_usec_sequential(); static BX_CPP_INLINE Bit64u time_ticks() { return bx_pc_system.ticksTotal + Bit64u(bx_pc_system.currCountdownPeriod - bx_pc_system.currCountdown); } static BX_CPP_INLINE Bit32u getNumCpuTicksLeftNextEvent(void) { return bx_pc_system.currCountdown; } This private method is called when the function handling the clock ticks finds that an event has occurred: void countdownEvent(void);

The Bochs timer implementation requires at least one timer to be active. That's why there is a so-called nullTimer to make it work. It is initialized in the constructor on the first timer slot with the highest possible timer interval and it's handler is an empty function. The most important variables of the timer subsystem are initialized on startup with the nullTimer values and updated after each timer modification (register / unregister / activate / deactivate / processing handler). ticksTotal: number of ticks total from emulator startup to the last update of timer subsystem currCountdownPeriod: length of the period from ticksTotal to the next timer event currCountdown: number of ticks remaining until the next timer event occurs The number if ticks since emulator startup are calculated with the formula ticksTotal + currCountdownPeriod - currCountdown and returned with the time_ticks() method. &FIXME; To be continued

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) Q - set by the emulator (Qemu) 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:hd, 1:fd) 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 0x5b S extra memory above 4GB 0x5c S extra memory above 4GB 0x5d S extra memory above 4GB 0x5f Q number of processors

This section is a detailed description for configuring Sound Blaster 16 from source. If you have a binary and all you want to know is what to put in your bochsrc file, see the sb16 bochsrc option in the user guide. The original version of the Sound Blaster 16 (SB16) emulation for Bochs was written and donated by Josef Drexler. The entire set of his SB16 patches have been integrated into Bochs, however, so you can find everything you need here.

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 to the host sound system is supported on Windows, Linux, FreeBSD, MacOS 9, MacOSX and platforms supported by SDL. 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. If ALSA is present on Linux and the sound driver is set to alsa, Bochs uses it's default PCM output device and MIDI sequencer. On Windows, midi and (wave) output go to the midi mapper and the wave mapper, respectively. A future version might have selectable output devices. See the next section for more information about the sound lowlevel interface.

You need to configure Bochs using the --enable-sb16 option. There are a few values in config.h that are relevant to the sound functions. Editing config.h after running configure is usually not necessary, since it detects the available drivers and enables them for the compilation. BX_USE_SB16_SMF should be 1 unless you intend to have several sound cards running at the same time. BX_SOUND_LOWLEVEL_C is the name of the class used as the "default" sound driver for output. The default value of this setting is the dummy driver with no output. The configure script usually changes this value. The following are supported at the moment: bx_sound_linux_c for output to /dev/dsp and /dev/midi00 on Linux, FreeBSD 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_alsa_c for output to the default ALSA PCM device and the default ALSA sequencer. bx_sound_osx_c for output on Mac OS 9 and Mac OSX. bx_sound_sdl_c for wave output on platforms supported by SDL. bx_sound_output_c for no output at all. Setup the SB16 emulation in your bochsrc, according to instructions in that file (see sb16 option in the user guide).

The source and the DOS executable for the SB16CTRL program that is used to modify the runtime behaviour of the SB16 emulator is included in misc/sb16. See the section SB16CTRL in the user documentation for information about the commands of SB16CTRL.

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, SOUNDMOD.CC and e.g. SOUNDLNX.CC for Linux or SOUNDWIN.CC for Windows and their respective header files to get an idea about how these things really work.

The main include file for a lowlevel sound driver is iodev.h. It has all definitions for the system-independent functions that a sound driver uses. The sound driver also needs to include soundmod.h for the definition of the base class bx_sound_output_c. Additionally, every output driver will have an include file, which should be included on top of soundmod.cc to allow the emulator to use that driver. A soundcard does not need to include the specific driver header. To actually make the emulator use any specific driver as the default, BX_SOUND_LOWLEVEL_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 list of lowlevel sound object files (SOUNDLOW_OBJS) in the file configure.in and to regenerate the configure script,

The following classes are involved with the sound lowlevel interface: bx_soundmod_ctl_c is a pseudo device that is used to initialize the sound driver depending on the configuration. In addition to this, it has methods for the PC speaker beep generation and the VOC file output. bx_sound_output_c is the base output class. It has all the methods used by the soundcard emulation, 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 not necessary to override all the methods defined in the base class, since virtual functions are used. The constructor should call the inherited constructor as usual, even though the current constructor does not do anything yet.

class bx_sound_lowlevel_c : public logfunctions { public: bx_sound_lowlevel_c(); virtual ~bx_sound_lowlevel_c(); virtual int get_type() {return BX_SOUNDLOW_DUMMY;} virtual int waveready(); virtual int midiready(); virtual int openmidioutput(const char *mididev); virtual int sendmidicommand(int delta, int command, int length, Bit8u data[]); virtual int closemidioutput(); virtual int openwaveoutput(const char *wavedev); virtual int startwaveplayback(int frequency, int bits, bx_bool stereo, int format); virtual int sendwavepacket(int length, Bit8u data[]); virtual int stopwaveplayback(); virtual int closewaveoutput(); virtual int openwaveinput(const char *wavedev, sound_record_handler_t rh); virtual int startwaverecord(int frequency, int bits, bx_bool stereo, int format); virtual int getwavepacket(int length, Bit8u data[]); virtual int stopwaverecord(); virtual int closewaveinput(); static void record_timer_handler(void *); void record_timer(void); protected: int record_timer_index; int record_packet_size; sound_record_handler_t record_handler; }; The base class for sound lowlevel support is derived from the logfunctions class to make the Bochs logging capabilities available in the sound driver code. It contains the framework for wave input (recording) support. The base class is in use if the "dummy" sound driver is selected or in case no platform or library specific implementation is available.

The following are the methods that the sound driver class has to override. All but constructor and destructor have to return either BX_SOUNDLOW_OK (0) if the function was successful, or BX_SOUNDLOW_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. The constructor should not allocate the output devices. This shouldn't be done until the actual output occurs; in either openmidioutput() or openwaveoutput(). 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.

Returns.the ID of the sound driver module. The default value is BX_SOUNDLOW_DUMMY. New values should be added to the list in soundmod.h.

openmidioutput() is called when the first midi output starts. It is only called if the midi output to the driver is active (midimode 1). It should prepare the given MIDI hardware for receiving midi commands. Description of the parameters: 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_SOUNDLOW_OK if the midi output device is ready. BX_SOUNDLOW_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 sound subsystem initializes. 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 startwaveplayback(). openwaveoutput() will only be called once, whereas startwaveplayback() is called for every new wave output command to the soundcard emulation. If feasible, it could be useful to open and/or lock the output device in startwaveplayback() 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 waveout=device configuration parameter of the sound bochsrc 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 emulator receives a new wave output command. 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 soundcards, 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_SOUNDLOW_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_SOUNDLOW_WAVEPACKETSIZE bytes. If BX_SOUNDLOW_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_SOUNDLOW_WAVEPACKETSIZE is ready at the soundcard emulation. 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_SOUNDLOW_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 wave data 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 the Bochs simulation quits. 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 data 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.

The wave input feature is relatively new in Bochs. If a lowlevel driver does not implement recording, the methods of the base class ("dummy" driver) are used. They return silence to let the input mechanism of the soundcard emulation work. The soundcard emulator object needs to implement a callback function to notifies the emulation about available data. This function usually calls the driver method to get the wave data packet. The driver objects has a periodic timer with an interval of 0.1 emulated seconds that is active during recording. The timer handler processes the wave data recorded with platform or library specific function and finally notifies the emulator.

openwaveinput() is called when the sound emulation first receives a sound recording command. It should do the following: Open the given device, and prepare it for wave input or Store the device name so that the device can be opened in startwaverecord(). In addition to this the record handler value should be stored and the record timer should be registered. This is the definition of record handler callback function: typedef Bit32u (*sound_record_handler_t)(void *arg, Bit32u len); openwaveinput() will only be called once, whereas startwaverecord() is called for every new wave input command to the soundcard emulation. If feasible, it could be useful to open and/or lock the input device in startwaverecord() as opposed to openwaveinput() to ensure that it can be used by other applications while Bochs doesn't need it. 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 wavein=device configuration parameter of the sound bochsrc option. rh is a pointer to the record handler method of the sound emulation. When sound recording is active, this handler is called periodicly to notify the sound emulation about newly available data. Note that only one wave input 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 method is very similar to the startwaveplayback() method for sound output and it takes the same argument list. It should set up the input device for recording, calculate the size of the recording packet for 0.1 second and start the record timer.

This method is called from the record handler method of the sound emulation device to retrieve the recorded wave data packet.

This function is called to stop the wave recording. It deactivates the timer that calls the method to perform the recording.

This function is called just before the Bochs simulation quits. It is very similar to the closewaveoutput() method.

This section describes how the three new disk images "undoable", "growing", and "volatile" are implemented in Bochs 2.1. It also applies to the write support the "vvfat" disk image mode in Bochs 2.4.6. undoable -> base r/o file, plus growing, commitable, rollbackable redolog file growing -> growing files, all previously unwritten sectors go to the end of file volatile -> base r/o file, plus hidden growing redolog vvfat -> virtual VFAT disk created from directory, plus hidden growing redolog

The idea behind volatile and undoable disk images is to have a read-only base file, associated with one redolog file. In case of vvfat, a directory is associated with the redolog file. Reading a sector is done from the redolog file if it contains the sector, or from the base file / vvfat directory otherwise. Sectors written go to the redolog, so base image 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 base image file, you get a "growing" disk image. So "undoable", "volatile", "growing" and "vvfat" 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 is also checked when the automatic type and size detection is selected. 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, 0x00020000 68 4 Bit32u header size 512 The current version of the header is 0x00020000 (2.0) - see below for details. 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 4 Bit32u timestamp in FAT format ("undoable" mode only - otherwise reserved) 88 8 Bit64u disk size in bytes The reserved field between "extent" and "disk" has been added in redolog version 2.0 to fix an alignment bug on some platforms. It is now used for consistency check of the "undoable" mode. When creating the redolog file, the timestamp of the read-only file is stored there (in FAT format). After that, the "undoable" mode init code compares the timestamp of the r/o file with the one stored in the redolog.

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.

Each extent starts with a bitmap block of n*512 bytes size. Each byte of the bitmap stores the write status of 8 coresponding disk sectors in the extent (1 = data written).

This is a collection of successive 512-bytes sectors of the disk image. The bitmap preceeding this data block contains the write status of each sector.

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. It also contains methods for the subtype and consistency check and for the save/restore support. 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 (0x00020000) #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. int open(const char* filename, const char* type, Bit64u size, int flags); opens a redolog file with flags applied. This allows to open a redolog in read-only mode. All other parameters and the return value are similar to the default open() method above. 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 and SEEK_CUR are 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. Bit64u get_size(); returns the size stored in the "disk" field in the header. This is used for size autodetection feature ("growing" mode) and the consistency check ("undoable" mode). Bit32u get_timestamp(); returns the value of the "timestamp" field in the header (only used by the "undoable" mode). bx_bool set_timestamp(Bit32u timestamp); writes the timestamp to the header. This is done by the "undoable" mode init code if get_timestamp() returns 0 or the redolog is newly created. static int check_format(int fd, const char *subtype); checks the format of the file with descriptor fd. Returns HDIMAGE_FORMAT_OK if the subtype matches the requested one. This is used for for the image mode autodetection feature. bx_bool save_state(const char *backup_fname); copies the redolog file to a new file backup_fname. This is used by the hdimage save/restore feature.

"volatile" and "undoable" disk images are easily implemented by instanciating a device_image_t object (base image) and a redolog_t object (redolog). "growing" disk images only instanciates a redolog_t object. Class 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 disk image pathname in read-only mode, as an undoable disk image. The image mode of this base image is auto-detected. All supported disk image modes can be used here. 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 base 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 and SEEK_CUR are 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 base 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. bx_bool save_state(const char *backup_fname); calls the related redolog_t method to save the image state. void restore_state(const char *backup_fname); called by the hdimage restore code. Copies the backup file to the original location and overwrites the existing redolog file.

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 disk image pathname in read-only mode, as a volatile disk image. The image mode is auto-detected. 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 base 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 and SEEK_CUR are 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 base 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. bx_bool save_state(const char *backup_fname); calls the related redolog_t method to save the image state. void restore_state(const char *backup_fname); called by the hdimage restore code. Copies the backup file to the original location and overwrites the existing redolog file.

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 and SEEK_CUR are 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. static int check_format(int fd, Bit64u imgsize); checks the format of the file with descriptor fd. Returns HDIMAGE_FORMAT_OK if the file format matches the "growing" one. This is used for the image mode autodetection feature. bx_bool save_state(const char *backup_fname); calls the related redolog_t method to save the image state. void restore_state(const char *backup_fname); called by the hdimage restore code. Copies the backup file to the original location and overwrites the existing redolog file.

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.

This device was added by Dave Poirier (eks@void-core.2y.net). Compiling Bochs with iodebug support ./configure --enable-iodebug make Other optional fields may be added to the ./configure line, see Bochs documentation for all the information. To enable the iodebug plugin at runtime, it must be loaded with the 'plugin_ctrl' bochsrc option. Using the I/O Interface to the debugger port range: 0x8A00 - 0x8A01 Port 0x8A00 servers as command register. You can use it to enable the i/o interface, change which data register is active, etc. Port 0x8A01 is used as data register for the memory monitoring.

0x8A00 Used to enable the device. Any I/O to the debug module before this command is sent is sent will simply be ignored. 0x8A01 Selects register 0: Memory monitoring range start address (inclusive) 0x8A02 Selects register 1: Memory monitoring range end address (exclusive) 0x8A80 Enable address range memory monitoring as indicated by register 0 and 1 and clears both registers 0x8AE0 - Return to Debugger Prompt If the debugger is enabled (via --enable-debugger), sending 0x8AE0 to port 0x8A00 after the device has been enabled will return the Bochs to the debugger prompt. Basically the same as doing CTRL+C. 0x8AE2 - Instruction Trace Disable If the debugger is enabled (via --enable-debugger), sending 0x8AE2 to port 0x8A00 after the device has been enabled will disable instruction tracing 0x8AE3 - Instruction Trace Enable If the debugger is enabled (via --enable-debugger), sending 0x8AE3 to port 0x8A00 after the device has been enabled will enable instruction tracing 0x8AE4 - Register Trace Disable If the debugger is enabled (via --enable-debugger), sending 0x8AE4 to port 0x8A00 after the device has been enabled will disable register tracing. 0x8AE5 - Register Trace Enable If the debugger is enabled (via --enable-debugger), sending 0x8AE5 to port 0x8A00 after the device has been enabled will enable register tracing. This currently output the value of all the registers for each instruction traced. Note: instruction tracing must be enabled to view the register tracing 0x8AFF Disable the I/O interface to the debugger and the memory monitoring functions. all accesses must be done using word reading this register will return 0x8A00 if currently activated, otherwise 0

All accesses to this port must be done using words. Writing to this port will shift to the left by 16 the current value of the register and add the provided value to it. Sample: reg0 = 0x01234567 out port: 0x8A01 data: 0xABCD reg0 = 0x4567ABCD

Enable memory monitoring on first page of text screen (0xb8000-0xb8fa0): add in bochrc file: optromimage1: file="asmio.rom", address=0xd0000 /* * Make asmio ROM file: * gcc -c asmio.S * objcopy -O binary asmio.o asmio.rom */ .text .global start .code16 /* ROM Header */ .byte 0x55 .byte 0xAA .byte 1 /* 512 bytes long */ start: /* Monitor memory access on first page of text screen */ mov $0x8A00,%dx /* Enable iodebug (0x8A00->0x8A00) */ mov %dx,%ax out %ax,%dx mov $0x8A01,%ax /* Select register 0 start addr (0x8A01->0x8A00) */ out %ax,%dx mov $0x8A01,%dx /* Write start addr 0xB8000 (high word first) */ mov $0xB,%ax out %ax,%dx mov $0x8000,%ax /* Write start addr (low word) */ out %ax,%dx mov $0x8A02,%ax /* Select register 1 end addr (0x8A02->0x8A00) */ mov $0x8A00,%dx out %ax,%dx mov $0x8A01,%dx /* Write end addr 0xB8FA0 (high word first) */ mov $0xB,%ax out %ax,%dx mov $0x8FA0,%ax /* Write end addr (low word) */ out %ax,%dx mov $0x8A00,%dx /* Enable addr range memory monitoring (0x8A80->0x8A00) */ mov $0x8A80,%ax out %ax,%dx mov $0x8A00,%dx /* Return to Bochs Debugger Prompt (0x8AE0->0x8A00) */ mov $0x8AE0,%ax out %ax,%dx lret .byte 0x6b /* Checksum (code dependent!, update it as needed) */ .align 512 /* NOP follow */

&FIXME; Not written yet.

&FIXME; Not written yet (take stuff from bxdebugger.html).

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 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. Make sure that contributed code / patches are LGPL compatible.

Update version number and strings in configure.in. VERSION="2.5" VER_STRING="2.5" REL_STRING="Build from SVN snapshot on November 27, 2011" 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: Sun Nov 27 16:55:00 CET 2011 Version: 2.5 In the file bochs.manifest you have to update the version number for the Windows build. version="2.5.0.0" Check date, update/sumup info in CHANGES. Run autoconf to regenerate configure and check them in. Create an SVN tag that contains all files of the revision that was used in the release. For prereleases I create a normal SVN tag like this: svn mkdir tags/REL_2_5_pre1_FINAL svn copy trunk/bochs tags/REL_2_5_pre1_FINAL/bochs svn commit But for a real release, I make an SVN branch tag AND a normal tag. svn mkdir tags/REL_2_5_FINAL svn copy trunk/bochs tags/REL_2_5_FINAL/bochs svn mkdir branches/REL_2_5 svn copy trunk/bochs branches/REL_2_5/bochs svn commit The 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. svn diff tags/REL_2_5_FINAL/bochs trunk/bochs svn diff tags/REL_2_5_FINAL/bochs branches/REL_2_5 etc. All bugfix-only releases after the final release should be created from the REL_2_5 branch. Now you can start building packages with the sources from the created release tag.

An anonymous SVN checkout from the release tag is the base for all official release packages. Do this checkout from the release tag and specify a not yet existing directory name with the version number as the destination. Then create the source package from this new directory. These steps can be done both on Linux and Windows (Cygwin). svn co http://svn.code.sf.net/p/bochs/code/tags/REL_2_5_FINAL/bochs bochs-2.5 tar czvf bochs-2.5.tar.gz --exclude=.svn bochs-2.5 The source TAR file bochs-2.5.tar.gz is ready for 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. The DLX Linux demo package will be downloaded from the Bochs website to the Bochs root directory if it is not already present there. ./build/redhat/make-rpm | tee ../build.txt This produces two rpm files in the current directory. Test and upload.

These instructions require cygwin and MSVC++. Use the Bochs sources from the SVN checkout or unpack the TAR file. In Cygwin: sh .conf.win32-vcpp # runs configure make win32_snap # unzip workspace, make a win32 source ZIP The source ZIP is present in the parent directory of the Bochs root and now ready for upload. To build the binary package, copy it to a Windows machine, if necessary. Open up Visual C++ and load the workspace file Bochs.sln. 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 Do make install_win32 into the NSIS folder in the Bochs source tree: make install_win32 INSTDIR=./build/win32/nsis/bochs-2.5 This downloads and unpacks both the DLX Linux demo and the HTML docs from the Bochs website, copies all the files into ./build/win32/nsis/bochs-2.5 and then creates a binary ZIP in the NSIS folder. Rename that bochs-2.5.win32-bin.zip. Now make the NSIS installer package (the current script is known to work with NSIS 2.44) cd build/win32/nsis make That gives an installer called Bochs-2.5.exe. Test and upload it.

When you are ready with creating release packages you have to upload them using the SF file manager feature. Create a subdirectory with the version number in the bochs directory. Point the download destination to the new directory and start uploading packages. The top of the CHANGES file should be used as the release notes. After setting up the file properties the new release is ready for download. After having all files set up in the download area, don't forget to post an announcement containing a brief summary of changes to the bochs-announce mailing list and the "Project News" section on SF.

The Bochs project webspace is stored under the SF directory /home/project-web/bochs. It can be accessed from the SF shell using SSH or with the commands sftp, scp and rsync. Some parts of the directory structure must be updated from the local CVS repository, others from Bochs SVN (directories bochs and sfsite). The online documentation, disk images and screenshots must be uploaded manually. Location Meaning cgi-binCGI scripts for the websitehtdocsroot directory of the websitehtdocs/doc/docbookBochs online documentationhtdocs/docs-htmlold Bochs documentationhtdocs/guestosdisk images directly stored on the Bochs websitehtdocs/screenshotscreenshots of Bochs running several guest operating systemshtdocs/svn-snapshotlink to current snapshothtdocs/techspectechnical specifications of several hardware componentslxrBochs source browsersfsite-cvsrootlocal CVS repositorysitebinshell scripts (e.g. for snapshot generation)sitemanwebsite manual pagessnapshotSVN snapshot storage areatmptemp directory for shell scripts

The main HTML content of the Bochs website (except online documentation) is stored in the sfsite directory of the Bochs SVN repository. Unlike other SF projects you don't need to upload these files to the Bochs project webspace. Running a simple SVN update on the SF shell is enough after the files have been updated in the repository. Please see Setting up SVN write access for general instructions. The only difference is the directory name sfsite instead of bochs. The example below shows how to start the SF shell with SSH and to update the HTML files. ssh -t vruppert,bochs@shell.sourceforge.net create vruppert,bochs@shell.sourceforge.net's password: Requesting a new shell for "vruppert" and waiting for it to start. queued... starting... This is an interactive shell created for user vruppert,bochs. Use the "timeleft" command to see how much time remains before shutdown. Use the "shutdown" command to destroy the shell before the time limit. For path information and login help, type "sf-help". [vruppert@shell-24002 ~]$ cd /home/project-web/bochs/htdocs/ [vruppert@shell-24002 htdocs]$ svn update U index.html Updated to revision 10752 [vruppert@shell-24002 htdocs]$ shutdown Requesting that your shell be shut down. This request will be processed soon. [vruppert@shell-24002 htdocs]$ Broadcast message from root (Mon Oct 31 09:45:04 2011): The system is going down for system halt NOW! Connection to shell-24002 closed by remote host. Connection to shell-24002 closed. Connection to shell.sourceforge.net closed.

The SVN snapshot The SVN snapshot link can be found on the bottom of the page getcurrent.html. can be updated with SF shell access using SSH. There is a script called update-svn-snapshot.sh that can do all the required steps (checking out SVN, packing the source tree into one archive, updating the website link). See previous section how to create a shell. cd /home/project-web/bochs/sitebin/ ./update-svn-snapshot.sh

To update the online documentation, a file called bochsdoc.tar.gz must be generated with the make. This file must be uploaded to the location of the online documentation on SF using scp. cd doc/docbook make bochsdoc.tar.gz scp bochsdoc.tar.gz vruppert,bochs@web.sf.net:htdocs/doc/docbook After a successful upload, the HTML files must be unpacked from the SF shell. See section Updating the Bochs website content how to create a shell. cd /home/project-web/bochs/htdocs/doc/docbook tar xvzf bochsdoc.tar.gz The updated files can be accessed from the sidebar of the Bochs website.

&FIXME; sources, tmp

&FIXME; sources, tmp