<!--================================================================doc/docbook/development/development.dbk$Id: development.dbk,v 1.16 2005/03/31 17:11:01 vruppert Exp $This is the top level file for the Bochs Developers Manual.================================================================--><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [<!-- include definitions that are common to all bochs documentation --><!ENTITY % bochsdefs SYSTEM "../include/defs.sgm">%bochsdefs;]><book><bookinfo>   <title>Bochs Developers Guide</title>   <authorgroup>   <author><firstname>Kevin</firstname><surname>Lawton</surname></author>   <author><firstname>Bryce</firstname><surname>Denney</surname></author>   <author><firstname>Christophe</firstname><surname>Bothamy</surname></author>   <editor><firstname>Michael</firstname><surname>Calabrese</surname></editor>   </authorgroup></bookinfo><!-- *************************************************************** --><chapter id="resources"><title>Resources for developers</title><para>The development guide describes resources that are intended for developersin particular.  Many Bochs resources are also covered in the User Guide,including compile instructions, bochsrc options, how to find the mailinglists, etc.</para><section><title>Setting up CVS write access</title><para>If you are an official SourceForge developer, then you can use CVS with writeaccess.  The CVS contains the most recent copy of the source code, and withwrite access you can upload any changes you make to the CVS server for othersto use.  A few extra steps are required the first time you use CVS writeaccess.</para><section><title>Install ssh and cvs</title><para>First you need to install both cvs (Concurrent Version System) and ssh (SecureShell).  These are already installed on many UNIX systems and also Cygwin(win32 platform).  If not, you can install binaries or compile cvs and sshyourself.  The links below should help you get going.</para><itemizedlist><listitem> <para> CVS software and instructions are available at <ulink url="http://www.cvshome.org">www.cvshome.org</ulink>. </para> </listitem><listitem> <para> A free version of secure shell called OpenSSH is at <ulink url="http://www.openssh.org">www.openssh.org</ulink>. </para> </listitem><listitem> <para> OpenSSH requires a library called OpenSSL from <ulink url="http://www.openssl.org">www.openssl.org</ulink>.  Be sure to install OpenSSL before trying to compile OpenSSH. </para> </listitem></itemizedlist></section> <section><title>ssh to cvs.sf.net</title><para>Next, you need to use secure shell to connect to cvs.sf.net.  This step is alittle strange, because you can't actually log in and get a shell prompt.  Allthat will happen, when you get the username and password right, is that itwill create a home directory on that machine for you.  That's it!  If you tryit again, it will say "This is a restricted Shell Account.  You cannot executeanything here."   At this point, you've succeeded and you never have to dothis step again, ever.<screen>  ssh <replaceable>sfusername</replaceable>@cvs.sf.net</screen></para><para>Replace <replaceable>sfusername</replaceable> with your Source Forge username,of course.  The first time, you will probably get a message like <screen>The authenticity of host 'cvs.sf.net' can't be established.Are you sure you want to continue?</screen>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 SOURCEFORGE username and password in the ssh line, which isn't necessarily the sameas your local username and password.  Add the "-v" option to ssh to see moreinformation about what is failing.  If you have ssh version 2, it is possiblethat you might need to add "-1" to the ssh command to force it to use theversion 1 protocol.  </para> </section> <section><title>Set CVS_RSH environment variable to ssh</title><para>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.  Sojust take the time now to add one of these lines to your .bashrc/.cshrc, sothat the CVS_RSH setting will be there every time you log in.</para><screen>  export CVS_RSH=ssh           (bash syntax)  setenv CVS_RSH ssh           (csh syntax)</screen></section> <!--end of "Set environment variable"--><section><title>cvs checkout</title><para>Finally, you should be able to do the checkout!  If you already have a bochssubdirectory directory, move it out of the way because the checkout willoverwrite it.</para><screen>  export CVSROOT=":ext:<replaceable>sfusername</replaceable>@cvs.sourceforge.net:/cvsroot/bochs"  cvs -z3 checkout bochs  <replaceable>sfusername</replaceable>@cvs.sourceforge.net's password:        <replaceable><--type your password</replaceable></screen><para>In the CVSROOT variable, replace <replaceable>sfusername</replaceable> with your SF username.  There'sno need to add CVSROOT to your rc files because CVS will remember itafter the checkout.  The -z3 (optional) just adds some compression to make the checkout go faster.  Once all the files have been downloaded, you willhave a bochs directory which is checked out with write access!</para></section> <!-- end cvs checkout --></section> <!-- end setting up cvs write access --><section id="using-cvs-write-access"><title>Using CVS write access</title><section><title>Checking in files</title><para>Once you have a bochs directory with cvs write access, you can compile thefiles, edit them, test them, etc.  See the documentation section, "Trackingthe 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 nowdo cvs commits.  When a file is all fixed and ready to share with the rest ofthe 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 itsince you downloaded it last.</para><screen>  $ cvs update file.cc  <replaceable>sfusername</replaceable>@cvs.sf.net's password:        <replaceable><--type your password</replaceable>  $ cvs commit file.cc  <replaceable>sfusername</replaceable>@cvs.sf.net's password:        <replaceable><--type your password</replaceable>  [editor opens. type log message, save, and exit.]</screen><para>When CVS starts an editor, The default is usually vi.  If you want a differenteditor, set the EDITOR environment variable to the name of your preferrededitor.  When you're done, just save the file and quit the editor.  Unlessthere's some problem, you will see a message that says what the new revisionnumber for the file is, and then "done".  If while you're editing the logmessage, you decide that you don't want to commit after all, don't save thefile.  Quit the editor, and when it asks where the log message went, tell itto abort.</para><para>Here is an example of a successful checkin:<screen>  $ cvs commit misc.txt  <replaceable>sfusername</replaceable>@cvs.sf.net's password:        <replaceable><--type your password</replaceable>  [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</screen>And here is an aborted one:<screen>  $ cvs commit misc.txt  <replaceable>sfusername</replaceable>@cvs.sf.net's password:        <replaceable><--type your password</replaceable>  [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</screen></para></section> <!--end of "Checking in Files" --></section> <!--end of "Using CVS write access" -->      <section id="trackers"><title>SourceForge bug, feature, and patch trackers</title>         <para>	 &FIXME;         </para>      </section><section id="other"><title>Ideas for other sections</title><para><screen>Ideas:- how to browse code with cvsweb- how to find an identifier, variable, or specific text in the code- write access CVS (must be an official developer on SF)- how to make patches with CVS</screen></para></section></chapter> <chapter id="about-the-code"><title>About the code</title><section><title>How to add keymapping in a GUI client</title><para>Christophe Bothamy, wrote the keymapping code for Bochs, provided theseinstructions to help developers to add keymapping to a GUI.</para><screen>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 keyYou have to provide a translation function from string to your Bit32u keyconstant. Casting will be necessary if your key constants are not Bit32u typed.The function must be "static Bit32u (*)(const char *)" typed, and must returnBX_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 itas an example.</screen></section>    <section id="directory-structure"><title>Directory Structure</title>      <para>      &FIXME;      cpu directory does this, iodev does that, gui does that      </para>    </section>     <section id="configure-scripting"><title>Configure Scripting</title>      <para>      &FIXME;      configure script, makefiles, header files      </para>     </section>      <section id="logfunctions"><title>Log Functions</title>      <para>      &FIXME;      log functions: what is a panic, what is an error, etc.      </para>      </section>      <section id="emulator-objects"><title>Emulator Objects</title>       <para>      &FIXME;      objects that do all the work (cpu, mem)      </para>      </section>      <section id="timers"><title>timers</title>      <para>      &FIXME;      </para>      </section><section id="sb16-emulation-basics"> <!-- start of SB16 section--><title>Sound Blaster 16 Emulation</title><note><para>  A little more up-to-date version of the user related part of this section is  available in the <ulink url="../user/sb16-emulation.html">user guide</ulink>.</para></note><para>Sound Blaster 16 (SB16) emulation for Bochs was written and donated byJosef Drexler, who has a<ulink url="http://publish.uwo.ca/~jdrexler/bochs/">web page</ulink> on the topic.  The entire set of his SB16 patches have been integrated intoBochs, however, so you can find everything you need here.</para><para>SB16 Emulation has been tested with several soundcards and versions of Linux.  Please giveJosef <ulink url="mailto:jdrexler@julian.uwo.ca">feedback</ulink> on whether is does or doesn't work on your combination of software and hardware.</para><section><title>How well does it work?</title><para>Right now, MPU401 emulation is next to perfect. It supports UARTand SBMIDI mode, because the SB16's MPU401 ports can't do anything else as well.</para><para>The digital audio basically works, but the emulation is too slow for fluentoutput unless the application doesn't do much in the background (or theforeground, really). The sound tends to looping or crackle on slowercomputer, but the emulation appears to be correct. Even a MODplayer works, although only for lower sampling speeds.</para><para>Also, the MIDI data running through the MPU401 ports can be writteninto a SMF, that is the standard midi file. The wave outputcan be written into a VOC file, which has a format defined byCreative Labs. This file format can be converted to WAV bysox for example.</para></section><section><title>Output to a sound card</title><para>Output is supported on Linux and Windows 95 at the moment.On Linux, the output goes to any file or device. If you have awavetable synthesizer, midi can go to /dev/midi00, otherwise you may needa midi interpreter. For example, the midid program from theDosEmu project would work. Wave output should go to /dev/dsp.These devices are assumed to be OSS devices, if they're notsome of the ioctl's might fail.On Windows, midi and output goes to the midi mapper and the wave mapper,respectively. A future version might have selectable output devices.</para></section><section><title>Installation on Linux</title><para><emphasis>Prerequisites:</emphasis></para><para>A wavetable synthesizer on /dev/midi00 and a working /dev/dsp if you want real time music and sound, otherwise output to midi and wave files is also possible. Optionally, you can use a software midi interpreter, such as the midid program from the DosEmu project instead of /dev/midi00. </para></section><section><title>Configuring bochs</title><para>There are a few values in config.h that are relevant to the sound functions.Edit config.h after running configure, but before compiling.</para><para>BX_USE_SB16_SMF should be 1 unless you intend to have several sound cardsrunning at the same time.</para><para>BX_USE_SOUND_VIRTUAL can be 0 or 1, and determines whether the output classuses virtual functions or not. The former is more versatile and allows toselect the class at runtime (not supported at the moment), while the latteris slightly faster.</para><para>BX_SOUND_OUTPUT_C is the name of the class used for output.  The default isto have no output functions, so you need to change this if you want any sound.The following are supported at the moment:</para><programlisting>        bx_sound_linux_c    for output to /dev/dsp and /dev/midi00 on Linux                            (and maybe other OSes that use the OSS driver)        bx_sound_windows_c  for output to the midi and wave mapper of                            Windows 3.1 and higher.        bx_sound_output_c   for no output at all.</programlisting><para>Setup the SB16 emulation in your .bochsrc, according to instructionsin that file.</para></section><section><title>Runtime configuration</title><para>The source for the SB16CTRL program that is used to modifythe runtime behaviour of the SB16 emulator is included inmisc/sb16. You can compile it or download the<ulink url="http://publish.uwo.ca/~jdrexler/bochs/">executable</ulink>.</para><para>See the section "Sound Blaster 16 Emulation" in the user documentation forinformation about the commands of SB16CTRL.</para></section><section><title>Features planned for the future</title><itemizedlist><listitem><para>Ports to more OS's, but I can't do this myself</para></listitem><listitem><para>Finishing the OPL3 FM emulation by translating the music to midi data</para></listitem></itemizedlist></section><section><title>Description of the sound output classes</title><para>This file is intended for programmers who would like to port the soundoutput routines to their platform. It gives a short outline what serviceshave to be provided.</para><para>You should also have a look at the exisiting files, <emphasis>SOUNDLNX.CC</emphasis>for Linux and <emphasis>SOUNDWIN.CC</emphasis> for Windows and their respectiveheader files to get an idea about how these things really work.</para></section><section><title>Files</title><para>The main include file is <emphasis>bochs.h</emphasis>. It has all definitions for the system-independent functions that the SB16 emulation uses, whichare defined in <emphasis>sb16.h</emphasis>.</para><para>Additionally, every output driver will have an include file, whichshould be included at the end of sb16.h to allow the emulatorto use that driver.</para><para>To actually make the emulator use any specific driver, <emphasis>BX_SOUND_OUTPUT_C</emphasis> has to be set to the name of the respectiveoutput class.</para><para>Note that if your class contains any system-specific statements,include-files and so on, you should enclose both the include-file andthe CC-file in an <emphasis>#if defined</emphasis> (OS-define) construct.Also don't forget to add your file to the object list iniodev/Makefile and iodev/Makefile.in.</para></section><section><title>Classes</title><para>The following classes are involved with the SB16 emulation:</para><itemizedlist>