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_LTX_ before looking for . 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....