Bochs - The cross platform IA-32 (x86) emulator
Updated: Sun Aug  1 10:07:00 CEST 2021
Version: 2.7

WHAT IS BOCHS?

Bochs is a highly portable open source IA-32 (x86) PC emulator
written in C++, that runs on most popular platforms.  It includes
emulation of the Intel x86 CPU, common I/O devices, and a custom
BIOS. Bochs can be compiled to emulate many different x86 CPUs,
from early 386 to the most recent x86-64 Intel and AMD processors
which may even not reached the market yet. Bochs is capable of running
most Operating Systems inside the emulation, for example DOS,
Linux or Windows. Bochs was written by Kevin Lawton and is currently
maintained by the Bochs project at "https://bochs.sourceforge.io".

Bochs can be compiled and used in a variety of modes, some which are
still in development.  The 'typical' use of bochs is to provide
complete x86 PC emulation, including the x86 processor, hardware
devices, and memory.  This allows you to run OS's and software within
the emulator on your workstation, much like you have a machine
inside of a machine.  Bochs will allow you to run Windows
applications on a Solaris machine with X11, for example.

Bochs is distributed under the GNU LGPL. See LICENSE and COPYING for details.

GETTING CURRENT SOURCE CODE

Source code for Bochs is available from the Bochs home page at
https://bochs.sourceforge.io.  You can download the most recent
release, use SVN to get the latest sources, or grab a SVN
snapshot which is updated frequently. The releases contain the most
stable code, but if you want the very newest features try the
SVN version instead.

WHERE ARE THE DOCS?

The Bochs documentation is written in Docbook.  Docbook is a text
format that can be rendered to many popular browser formats such
as HTML, PDF, and Postscript.  Each binary release contains the
HTML rendering of the documentation.  Also, you can view the
latest documentation on the web at
  https://bochs.sourceforge.io/doc/docbook/index.html

WHERE CAN I GET MORE INFORMATION?  HOW DO I REPORT PROBLEMS?

Both the documentation and the Bochs website have instructions on how
to join the bochs-developers mailing list, which is the primary
forum for discussion of Bochs.  The main page of the website also
has links to bug reports and feature requests.  You can browse and
add to the content in these areas even if you do not have a (free)
SourceForge account.  We need your feedback so that we know what
parts of Bochs to improve.

There is a patches section on the web site too, if you have made
some changes to Bochs that you want to share.

HOW CAN I HELP?

If you would like contribute to the Bochs project, a good first step
is to join the bochs-developers mailing list, and read the archive
of recent messages to see what's going on.

If you are a technical person (can follow hardware specs, can write
C/C++) take a look at the list of open bug reports and feature
requests to see if you are interested in working on any of the
problems that are mentioned in them.  If you check out the SVN
sources, make some changes, and create a patch, one of the
developers will be very happy to apply it for you.  Developers who
frequently submit patches, or who embark on major changes in the
source can get write access to SVN.  Be sure to communicate with the
bochs-developers list to avoid several people working on the same
thing without realizing it.

If you are a Bochs user, not a hardware/C++ guru, there are still
many ways you could help out.  For example:
  - write instructions on how to install a particular operating system
  - writing/cleaning up documentation
  - testing out Bochs on every imaginable operating system and
    reporting how it goes.

CHANGES

Brief summary of changes in 2.7:
  - Bugfixes for CPU emulation correctness (CPUID/VMX/SVM fixes to support
    Windows Hyper-V as guest in Bochs)
  - Improvements for the plugin handling to simplify Bochs extensions
  - Added "multiple NICs" support to the NE2000 and E1000 devices
  - Added experimental FTP service for networking modules 'vnet' and 'socket'
  - Fixes and improvements for all supported Voodoo graphics adapters
  - Added USB keyboard emulation with most of the keys supported
  - GUI "cmdmode": create a headerbar event with key combo starting with F7
  - LGPL'd VGABIOS updated to version 0.8a (new VGABIOS for Voodoo Banshee)

See CHANGES file for more information!

Readme for wxWidgets Interface
Updated Tue Dec 24 09:54:00 CET 2013

Contributors to wxWidgets port:
  Don Becker (Psyon)
  Bryce Denney
  Dave Poirier
  Volker Ruppert

wxWidgets Configuration Interface

The wxWidgets (formerly called wxWindows) port began in June 2001 around the
time of Bochs 1.2.1.  Dave Poirier and Bryce Denney started adding a wxWidgets
configuration interface. We made some progress, but stopped after a while.
Then in March/April 2002 Bryce and Psyon revived the wxWidgets branch and turned
it into a usable interface.  Psyon did most of the work to get text and graphics
working, and Bryce worked on event passing between threads, and keyboard
mapping. Starting in August 2002, Bryce added lots of dialog boxes to allow you
to set all the bochsrc parameters.  At the time of release 2.0, there
are still some bugs but it is pretty stable and usable.

Bochs should be build with wxWidgets 2.3.3 or later. The release wxWidgets 2.3.3
includes a patch by Bryce Denney to allow us to get raw keycode data for several
OSes.

On any UNIX platform with wxWidgets installed, configure with
--with-wx to enable the wxWidgets display library.

To build in MS VC++:
- edit .conf.win32-vcpp and add "--with-wx" to the configure line.
  If you want different configure options from what you see, change them
  too.
- in cygwin, do "sh .conf.win32-vcpp" to run configure
- unzip build/win32/wxworkspace.zip into the main directory.
  For cygwin: unzip build/win32/wxworkspace.zip
  or use winzip or whatever else.
- open up bochs.dsw, the workspace file
- edit project settings so that VC++ can find the wxWidgets include
  files and libraries on your system.  Bryce installed them in
  d:/wx/wx233/include and d:/wx/wx233/lib.  Specifically, edit
  - Project>Settings>C/C++>Category=Preprocessor: include directories.
  - Project>Settings>Link>Category=Input: additional library path.
- build

Note that the project is set up for wxWidgets 2.3.3.  To use on other
wxWidgets versions, you will have to change some of the names of the libraries
to include.  Use the samples that came with that version of wxWidgets for
reference.

------------------------------------------------------

Random notes follow

Added some sketches.  I'm thinking that the control
panel will be able to basically show one of these screens at a time.  When
you first start you would see ChooseConfigScreen which chooses between the
configurations that you have loaded recently (which it would remember
by the pathname of their bochsrc).  Whether you choose an existing
configuration to be loaded or a new one, when you click Ok you go to
the first configuration screen, ConfigDiskScreen.

Each of the configuration screens takes up the whole control panel window.
We could use tabs on the top and/or "<-Prev" and "Next->" buttons to make
it quick to navigate the configuration screens.  Each screen should
probably have a Prev, Next, Revert to Saved, and Accept button.
The menu choices like Disk..., VGA..., etc. just switch directly to
that tab.


------------------------------------------------------
Notes:

events from gui to sim:
- [async] key pressed or released
- [async] mouse motion with button state
- [sync] query parameter
- [sync] change parameter
- [async] start, pause, stop, reset simulation.  Can be implemented
  as changing a parameter.
- [async] request notification when some param changes

events from sim to gui:
- [async] log message to be displayed (or not)
- [async] ask user how to proceed (like panic: action=ask)
- [async] param value changed
- make my thread sleep for X microseconds  (call wxThread::sleep then return)

In a synchronous event, the event object will contain space for the entire
response.  The sender allocates memory for the event and builds it.  The
receiver fills in blanks in the event structure (or could overwrite parts)
and returns the same event pointer as a response.  For async events, probably
the sender will allocate and the receiver will have to delete it.

implement the floppyA and floppyB change buttons using new event
structure.  How should it work?

vga gui detects a click on floppyA bitmap
construct a BxEvent type BX_EVT_ASK_PARAM
post the event to the wxWidgets gui thread (somehow) and block for response
when it arrives in the gui thread, show a modal dialog box
get the answer back to the simulator thread


right now, this is working ok within the simulator thread using
wxMutexGuiEnter/Leave.  Still I'm going to change it so that the
siminterface.cc code builds an event structure and the gui code
fills in the blank in the structure, instead of the stupid
notify_get_int_arg stuff.


Starting and Killing Threads

When a detachable (default) thread finishes (returns from its Entry()
function), wxWidgets frees the memory associated with that thread.
Unless the thread is never going to end, it is potentially dangerous to have a
pointer to it at all.  Even if you try to "check if it's alive" first, you may
be dereferencing the pointer after it has already been deleted, leading to it
claiming to be alive when it's not, or a segfault.  To solve this, the approach
used in the wxWidgets threads example is to have code in the thread's OnExit()
method remove the thread's pointer from the list of usable threads.  In
addition, any references or changes to the list of threads is controlled by a
critical section to ensure that it stays correct.  This post finally
explained what I was seeing.