- added instructions how to update the online documentation

[bochs-mirror.git] / README-plugins

README-plugins

This is the README file that came from the CVS branch called BRANCH_PLUGINS.
It's not intended to be user documentation for plugins.  It's more like a
bunch of to-do lists that the developers used to coordinate their efforts
while working on plugins.  At the bottom are some miscellaneous notes by the
plugin developers and some references to useful usenet articles.

-------------------------------------------------------------------------
BRANCH_PLUGINS

The branch is called BRANCH_PLUGINS.  There is a normal tag called
BRANCH_PLUGINS_BASE that marks the point where the branch began.  The
base marker will help at merge time.

This branch is a place to experiment with Bochs plugins.  Bryce created
the branch on October 4, 2002, and he and Christophe began working on
Bochs plugins.

We started from Bryce's patch.plugins3, which was a patch from December 2001
that copied in some of the plugin architecture from plex86.  Here are the
comments from that patch:

> Patch name: patch.plugins3
> Author: Bryce Denney
> Date: Wed Dec 12 17:56:11 EST 2001
>
> This patch replaces the Bochs keyboard with a slightly modified version
> of the plex86 keyboard device, which is implemented as a plugin.  This
> is sort of a proof of concept, rather than anything that I'm about to
> check in.  It uses GNU libtool to compile the plex86 keyboard code into
> a shared library, and installs that shared library in
> /tmp/bochslib/libplex-keyboard.so.  Then the new code in plugin.cc (which
> is adapted from the plex86 plugin code) loads the libplex-keyboard library
> during initialization and installs the plex86 keyboard instead of the
> bochs keyboard.
>
> I chose the keyboard because it takes about 2 seconds to test that it's
> basically working, and because the bochs and plex86 implementations hadn't
> changed very much since they split.
>
> If you look at plex-keyboard.cc and plex-keyboard.h, it is fundamentally the
> same as the current plex86 code.  I have changed lots of names from bx_* to
> plex_* just to reduce confusion and mayhem when I was compiling with both
> kbd implementations.  I didn't change anything except to get it to compile.

Christophe had made a plugins5 patch, so he checked it in, with these
changes:
 - plex86 keyboard device was marged with Bochs keyboard, as a plugin
 - plugin.cc was cleaned up
 - a device registration mechanism was set up
 - the biosdev and unmapped devices were plugin-ized

TO DO:
- (LATER) some plugins, such as the GUI, PIT, SB, and NE2000, have several different
  possible implementations.  In this case, all implementations should be
  children of a single stub class.  The stub's methods produce errors or
  panics if they are called, depending on the importance of the device.
  There is always one instance of the stub class lying around, which will be
  used if none of the implementation plugins is loaded.  Either an optional
  plugin or a user plugin can fill in these slots.

- platform specific issues
  - (LATER) make sure LTDL works on VC++.  It doesn't and won't without
    significant work.  Maybe it's easier to support VC++ with ifdefs in
    plugin.cc rather than using ltdl at all.  This will have to wait.
  - (DONE) nmake build: we must use lib.exe, not $(LIBTOOL) $(CXX) stuff

- configure script work
  - LTDL has a feature called dlpreload which sort of emulates dlopen
    by linking all the modules statically and then emulating dlopen calls.
    I don't see any value in this for plugins.  If the platform cannot
    support dlopen or some equivalent, let the configure script crash and
    tell the user to configure without plugins instead.
  - (DONE) to support plugins on MacOSX, the user must install dlcompat.
    Otherwise libtool's configure script will discover that no dlopen() or
    equivalent function is found, and it will not be able to build/load
    plugins.  The configure script should bomb in this case, with an error
    that says where to find dlcompat.  dlcompat IS installed on SF compile
    farm in /sw/include and /sw/lib.

- Understand/resolve simulation differences between CVS head and
  BRANCH_PLUGINS.  Simulation is slightly different.
  - compare four versions
    - BRANCH_PLUGINS with --enable-plugins
    - BRANCH_PLUGINS without --enable-plugins
    - BRANCH_PLUGINS_BASE
    - CVS head
  - these differences seem to be explained by a few things:
    1. devices are initialized in a different order, so they are assigned
       different timer id.  For any events that occur at the same tick, the
       timer handlers would get called in a different order.  I believe I
       have fixed the order of timer registration so that it matches, and
       that cleaned up some simulation differences.
    2. bx_gui->handle_events is now called from iodev/devices.cc instead of
       from iodev/keyboard.cc.
    3. bx_keyb_c::periodic() used to be called directly from devices.cc
       but now the keyboard registers its own timer
  - I have never seen any problems caused by the sim differences, but they
    make me nervous. -Bryce

- (LATER) convert remaining devices

- (LATER) maybe the implementation class for each plugin device should go into
  the .cc file instead of the header file.  If all their methods are called
  through the stub class virtual functions, and no external file has access to
  the real non-stub class, then maybe there is no point in letting anybody
  else see the real class at all?  (If you do use the class you will get
  undefined symbols when you compile for plugins anyway.)  For the hard drive,
  we could put bx_hard_drive_stub_c in harddrv.h, and any constants or types
  that external files might need, and then put the real class, bx_hard_drive_c,
  at the top of harddrv.cc.


- (LATER) eventually we need to clarify the connection between plugins and
  devices.  At the moment, each plugin creates exactly one device, but it does
  not have to work that way.
  - it would be more correct to mark the devices as core, optional, etc. than
    to use a type field in the plugin struct.  The reason that the type
    (core,optional,user) is currently passed into the PLUG_load_plugin macro
    and placed in the plugin struct instead of letting the device code decide
    is: devices.cc is responsible for initting and resetting devices, so I
    wanted devices.cc to decide whether the device would be managed by the
    plugin infrastructure (init_all, reset_all) or not.  This is not that
    important yet, but when Volker wants to write a plugin with multiple
    devices, we will need to sort it out.

- (LATER) make a way for users to replace a core plugin with one of their
  choice.

- (LATER) implement user plugins.  These are plugins that Bochs does not know
  anything about at compile time.  The user asks Bochs to load a plugin using
  just its filename.  It loads the plugin and registers any bx_params that
  the user can configure, and either the text config interface or the
  wxWindows interface can display this param list as a menu or dialog.
  Then at simulation start time, we call init() on the user device and
  it can be used like any other device.

- (LATER) make plugin CPU???

DONE:
- applied patch.plugins5
- updated makefile dependencies now that plugin.h is in there
- all guis converted to plugins
- 8 I/O devices are converted to plugins
- make the Makefile use libtool to build dynamic libraries
- use libtool's ltdl library to open and read dynamic libraries, since it
  has cross platform support
- the Boolean/bx_bool thing will be resolved in the main branch.  I have
  made patch.replace-Boolean.gz which I will apply later, after the
  plugins branch has been merged.  This become more urgent because it
  caused bug #623152 MacOSX: Triple Exception Booting win95
- take a look at the code generated by calls to virtual functions, to
  check if there's huge overhead that I don't know about.
  Answer: I don't believe there is that much extra overhead.  If you call
  a nonvirtual function, it must push all the args onto the stack, then
  push the THIS pointer, then call the method using a known constant address.
  With a virtual function, you push all the args onto the stack, then push
  the THIS pointer, then do one extra memory reference to THIS+constant to read
  the pointer to the virtual method, and call it.  This is just what I
  expected to find--no strange and magicial code was inserted by the
  compiler in this case.
- wxWindows configuration interface and display works fine as a plugin now
- selection of config interface is controlled by the bochsrc line
  "config_interface: NAME" and the parameter bx_options.Osel_config.
- selection of display library is controlled by the bochsrc line
  "display_library: NAME" and the parameter bx_options.Osel_displaylib.
- renamed vga_library to display_library (Christophe's suggestion)
- add --with-all-libs option, which attempts to detect all the display
  libraries that Bochs can compile with.  You can use this with or without
  plugins, compile with multiple guis in the same binary, and select between
  them at runtime.  If the detection fails, you can always write a bunch
  of --with-PACKAGE options yourself.
- load plugins as they are needed, in main.cc and iodev/devices.cc.
  - plugins are loaded using a macro PLUG_load_plugin(plugin_name, plugin_type).
    When plugins are enabled, this macro calls bx_load_plugin() in plugin.cc,
    which loads the plugin with lt_dlopen and calls its plugin_init method.
    When plugins are disabled, the code is already linked into the binary so
    the macro calls the plugin_init method directly.
  - The plugin_init method for plugin ABC is called libABC_LTX_plugin_init()
    and the same prefix is added before the plugin_fini method.  This "name
    mangling" makes the symbols unique so that they can all be linked
    statically into the binary when plugins are turned off.  This turned out
    to be a very useful thing!
  - The choice of lib*_LTX_* is not random...  The libtool LTDL library
    automatically searches for symbols of the form lib<module>_LTX_<symbol>
    before looking for <symbol>.  Libtool recommends making global symbols in
    every plugin unique in some way, and in fact on MacOSX the dynamic linker
    will not allow two libs to be linked in that both have plugin_init symbols,
    so this sort of mangling is required.
- how do we know what plugins should be available when we start Bochs?
  - we have core plugins, optional plugins, and user plugins.
    - (V2.0) core plugin: These are so fundamental that Bochs won't even
      initialize without them, for example the CMOS.  The user can substitute
      his own equivalent plugin to replace the CMOS, but he cannot say "Don't
      load the CMOS at all."  Core plugin devices are initialized and reset
      explictly by code in iodev/devices.cc, since the initialization order for
      some of them is critical.  They are currently NOT added to the device
      list in pluginRegisterDevice and pluginRegisterDeviceDevmodel, so that
      the plugin system does not call init() and reset().  If a core plugin
      cannot be found, Bochs will panic.
      In the bochsrc we can provide a way for the user to REPLACE a core plugin
      with a different plugin that implements the same C++ interface, but there
      is no way to ask bochs to NOT load a core plugin.  I'm not sure how to
      configure the replacement plugin--this may have to be added later.
      Bochsrc line:
        replace_core_plugin: old=pic, new=mypic
    - (V2.0) optional plugin: These can be loaded or not without affecting
      Bochs's ability to start up and simulate.  Initialization and reset for
      all optional plugins are handled by bx_init_plugins() and
      bx_reset_plugins(), which are now called from bx_devices_c::init() and
      bx_devices_c::reset().  Bochs knows how to configure optional plugins at
      compile time, and they are loaded only if the configuration settings
      enables the device.  Examples: serial, parallel, ne2k.  See the call to
      is_serial_enabled() in iodev/devices.cc.  There are some plugins that you
      wouldn't ever want to leave out, like vga.  Maybe the term "optional" is
      not clear and I need to think of a better name.  Bochs will panic if an
      optional plugin cannot be found.  If the plugin was compiled, then
      it should be available at runtime too!
    - (NOT DONE) user plugin: These are plugins that Bochs does not know
      anything about at compile time.  The user asks Bochs to load a plugin
      using just its filename.  It loads the plugin and (somehow) gets
      information about what settings the user can configure.  The settings are
      adjusted by either bochsrc lines or the user interface, and then the
      device can be used.  I'm missing some details here because I haven't
      thought through it all the way.  User plugins may not be supported until
      after v2.0.
  - list of plugins sorted into categories
    - core plugins: unmapped, biosdev, cmos, dma, pic, vga
    - optional: floppy, harddrv, keyboard, serial, parallel
    - user: none yet
- clarify relationship of plugin and device
  - a plugin is a shared object that you load that has a plugin_init() and
    plugin_fini() function inside.  The plugin_init() can create any number of
    "devices" and register them.  Devices are added to a global list so that we
    can do operations on every registered device.
  - There is (now) a pointer from each device to the plugin that created it.
  - Devices created by core plugins are called core devices.  These will not be
    added to the device list because they are managed by existing code in
    devices.cc and elsewhere.  Instead of referring to them by their device_t
    structure, we will use a global pointer to them, similar to the
    bx_devices.pluginKeyboard pointer.  (Alternative: maybe we should add
    them to device list anyway, but exclude them in init_all and reset_all
    functions.)
  - MACOSX PLUGINS WORK!  to support plugins on MacOSX, we must ensure that no
    plugins have any global symbol names in common, including plugin_init!  An
    easy solution to this is to say that all plugin functions which can be
    looked up with dlsym must follow a pattern like "%s_BXPLUG_%s", where the
    first %s is the module name and the second is the plain symbol name, e.g.
    pic_BXPLUG_plugin_init.  Symbols that are used internally can be declared
    static (file scope only).
  - SOLARIS PLUGINS WORK!  to support plugins on Solaris, we must not rely on
    the use of global object constructors.  In fact every global variable in a
    module MUST BE set to a compile-time constant.  We must declare object
    pointers as globals, not actual objects.
  - WIN32 PLUGINS WORK!  to support plugins on win32, I added the
    BOCHSAPI macro which expands to __declspec(dllexport) in the nonplugin
    code and __declspec(dllimport) in the plugin code.  Some makefile hacks
    were required too.  A few differences between win32 and other platforms:
    - use semicolon to separate path names in LTDL_LIBRARY_PATH
    - every path name in LTDL_LIBRARY_PATH should start with a drive letter,
      for example: c:/cygwin/home/bryce/plugins.
- how do we locate plugins on the disk?
  - make install copies the plugins into ${prefix}/lib
  - if people install into a standard location, no action may be needed (?)
  - we can tell people to set the LTDL_LIBRARY_PATH variable.
  - if necessary we can implement a bochsrc command like
      plugin_search_directory: /path/to/libs
    which would call lt_dlsetsearchpath() to add the path to LTDL's list of
    directories it will search.
- change log for BRANCH_PLUGINS is in patches/patch.plugins.  It is
  pretty complete now.






-----------------------------------------------
random notes:

class heirarchy:
 logfunctions
 - bx_devmodel_c
   - bx_keyb_stub_c
     - bx_keyb_c

bx_devmodel_c is an abstract class that defines standard functions that all
devices should define, like init and reset.  Each method is defined as empty
in bx_devmodel_c so that child classes can choose to implement them or not.

bx_keyb_stub_c declares the methods that code outside the keyboard would need
to call, such as mouse_motion, gen_scancode, etc.  It declares these methods
virtual, and provides a minimal definition for each that just does a panic.   A
global variable pluginKeyboard initially points to an instance of
bx_keyb_stub_c so that if you forget/fail to load the load the keyboard plugin,
you will see these panics when the methods are called.

bx_keyb_c is the real keyboard code.  In its constructor, it changes
pluginKeyboard to point to "this".  This is equivalent to installing all
the plugin callbacks associated with the keyboard.  It also works in
nonplugin code, which is a plus.


hard drive read_handler.  Right now the read_handler
is a static method so it must get its object pointer from somewhere.
  1) It can get it from global variable bx_hard_drive
  2) The hard drive object can be passed in to it
We've always used #2, so every device has methods that look like this:

  static Bit32u read_handler(void *this_ptr, Bit32u address, unsigned io_len);
  static void   write_handler(void *this_ptr, Bit32u address, Bit32u value, unsi

If/when we switch over to using virtual methods, there will no longer be
any problem finding the this pointer.  If we go that route, the this_ptr
can be eliminated.  For now, we must use the this_ptr.  Otherwise we could
never support more than one device of a given type.



------------------------------------------
References

From: Tero Pulkkinen (p150650@zori.cs.tut.fi)
 Subject: Re: undefined reference to `pm virtual table'
 Newsgroups: gnu.g++.help
 Date: 1996/11/15


> The compile goes off OK, but I get this error at link time:
>   pm.o(.text+0xa8): undefined reference to `pm virtual table'

This error comes from that the compiler didnt make virtual function
table for object even though there's implemented functions that use
objects of that type(constructor for example). Probably your pm-class
has all implemented member functions *inline* and you still have
(pure) virtual functions inside the class.

The creation point of virtual function table usually (dunno if g++ does that)
is at position of first seen noninline function body of that class.
Now if every of your function is inline, there's no place where compiler
could make virtual function table.

Fix is to move body of for example constructor(any member is fine) to the .cc
file instead of keeping it in .h-file and linking that .o file to your
executable.

Other sollution is to remove *all* implementations of functions from header
file. If all functions of a class are pure virtual, there's no need for
virtual function table. (Constructor must set pointer to virtual function
table to the object, so, if you have constructor, you'll need virtual
function table too, even in abstract classes...)

> Can someone help me?  Thanks in advance.

Hope this helps....