mirrors/Bochs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
9c3a4b8dab
Bochs/bochs/README-plugins
Stanislav Shwartsman 55ad3e89b6 another whitespace cleanup by Sebastien
2008-02-05 22:57:43 +00:00

358 lines
19 KiB
Plaintext
Raw Blame History

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....
Reference in New Issue View Git Blame Copy Permalink