Rockbox.org home
release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Rockbox mail archive

Subject: Plugins
From: Björn Stenberg (bjorn_at_haxx.se)
Date: 2003-06-29


Hi all.

I have just added plugin loading capability to CVS.

Plugins consist of code and data that is loaded to a 32KB reserved memory area at the top of ram. After a plugin has been loaded, it is started with two parameters:
  plugin_start(struct plugin_api* rockbox, void* parameter)

The first parameter is a pointer to a struct containing the api for accessing rockbox functions. The struct contains a number of function pointers that the plugin can use to call rockbox code.

The second parameter is for data that is passed to the plugin at startup. Currently only the text viewer plugin uses this parameter.

Only one plugin can be loaded at a time. Plugins run in the GUI thread and have exclusive control over the user interface. This means you cannot switch back and forth between a plugin and rockbox. A plugin is loaded, ran and then exited, which returns control to rockbox.

Plugins have the file extension .rock after a word joke on irc: A box full of .rocks == rockbox.

In the apps/plugins directory, there is a short example plugin called helloworld.c. It describes a few necessary things a plugin must contain and do:
  http://rockbox.haxx.se/apps/plugins/helloworld.c

One thing it doesn't address is target dependency: If your plugin only works on a specific target, you must place #ifdef HAVE_xxx around the entire code (but *after* #include "plugin.h"!) so that the source file can still compile for all targets. This will result in a 0-byte .rock file which the plugin loader can safely reject.

The plugin API currently does not offer access the entire rockbox code base. It merely defines the functions used by today's plugins. However the api is designed to be extended over time. It contains api version and hardware model checks that should make it relatively safe against accidentally mixing rockbox and plugin versions. If there are functions you would like to see added to the api, just send a mail here with your suggestions.

As implied by this, plugins do not only work against the exact rockbox binary they were compiled with. They will work with any binary that was built with the same api version and target as the plugin. This means you can download and install new plugins without having to install an updated rockbox binary.

Plugins are intended to be completely self-contained when it comes to data. This means that they do not use the rockbox language handling code, and must handle any internationalization by their own.

Currently, the plugins are sort of shoe-horned into the code in a rather inflexible way. The game and demo menus have simply been modified to load respective plugin, and the text viewer is hardcoded to load when a text file is to be viewed.
In the near future, I would like to replace this with a more flexible system. Brian King's .rockbox browsing patch will most likely be used for this purpose. Perhaps we should also split the /.rockbox/rocks directory into subdirs for different categories, although I think defining categories is always a difficult thing.

Also, we need some way of registering viewer plugins. Currently we only have a text viewer, but i foresee hex viewers, plugin editor, id3 editors, mp3 cutting tools and a wealth of other useful things, easily accessible from the ON+PLAY menu. Currently I'm leaning towards using a simple text config file to specify which plugins are file viewers. (Perhaps with a specific plugin for managing the config file...)

To make plugin development and debugging easier, plugins work on the x11 uisimulators too. They are implemented as dynamically loaded shared libraries.

There's probably a bunch of things I've forgotten to mention here, but I'm sure you will ask me about those. :-)

-- 
Björn



Page was last modified "Jan 10 2012" The Rockbox Crew
aaa