Module System

Introduction

TODO this is a work in progress, please help fill it in.

Starting with version 1.1, CHDK uses loadable binary modules (similar to .dll or .so files on other platforms). This reduces memory requirements and allows platform independent binaries to be made.

Development thread http://chdk.setepontos.com/index.php?topic=847.0

Thanks to tsvstar for the initial implementation of the module system.

For end users

In 1.1 and later, a minimal install of CHDK must include the modules as well as well as the CHDK core (DISKBOOT.BIN and/or PS.FI2, PS.FIR). Modules reside in CHDK/MODULES and have a .flt extension.

On multi-partition cards, the modules must be installed in the main (large) partition that the camera sees, not the small boot partition with diskboot.

For developers [TODO]

---

Common module processing sequence

1. Module loaded using function: module_load( char* name, _module_bind_t callback).

   name = module name (path relative to A/CHDK/MODULES/ or from root if started from '/')
   callback = callback function to bind/unbind module symbols to CHDK

   1. Allocate space, load module, made relocations
   2. Check module format type and version to strict correspondence. Any load is canceled
   3. Replace imported by modules symbols with real adresses. If no such symbol (by hash) found in CHDK core list, load is canceled
   4. Call callback() if it is defined.
      Purpose of this function - a) bind exported by modules symbol to core variables; b) Check all specific to module and required by core prerequisites. If something wrong module loading could be canceled by returning value !=0.
   5. Call _module_loader() function of module if it is exist.
      Purpose of this function is check prerequisites (such as API versions for example) and make module initialization. If something wrong (fail compatibility of required API version check, for example) - return !=0 and module loading will be canceled (at this stage callback(0) will be called to unbind this module).
2. Module usage.
   • Module could have _module_run() function. This is main entry point of module and it is used to standalone and mixed modules. It is called with variable length list of arguments and returned value is returned at call point
     Simple syntax (standalone modules) to call module main entry is rv =module_run("module.flt", callback, sizeof(argv)/sizeof(argv[0]), argv, UNLOAD_IF_ERR);
     Note: If module support case with empty argument list (argn=0, argv=0) then it could be ran with file browser and dynamic menus. Otherwise it could be called only if such call is defined in the CHDK code.
   • Module could be raw library. Then CHDK core decide when and which one imported from modules symbols should be called.
3. Module unload. When module not needed anymore it should be unloaded to free memory and module slot (limited number of modules could be loaded by CHDK at same time).
   Important note: Please be careful with load/unload. A lot of possible nuances exists. For example, owned by module resources could be used somewhere else (LUA), or should exists until shutdown (edge map), etc.
   • Unload sequence is:
     1. Call _module_unloader function of module if it is exist.
        Purpose of this function free allocated by module resources
     2. Call core unbind callback function (parameter "callback" of module_load/module_run).
        Purpose of this function - unbind modules symbols from variables of the core of CHDK
     3. Unallocate module
   • How module could be unloaded:
     • Just unload.
       Caller (module or core) could unload loaded module if it is not needed (Using module_unload()/module_unload_idx()).
     • Asynchronous unload.
       Module could unload itself when it is finished. Because it is unsafe to unallocate module while execution control flow is inside it, this happens asynchronously.
       How to do this: call module_async_unload() right before end of function. Do this only if right after this execution flow will leave module and you are sure that it will not returned back to module without module_load() call before.
     • Automatical unload on finish run handler.
       If module was ran with flag UNLOAD_ALWAYS it will be unloaded right after finishing its _module_run callback.
     • Automatical unload on press <ALT>.
       GUI mode could be switched to none at any moment of time by pressing <ALT> button. This event cause automatical unloading of all loaded modules. Because module doesn't know that it lost focus and probably will not get it again.
       But sometimes such behaviour is not desirable (need to keep resources till shutdown; this is library and should be unloaded by caller; unsafe because caller wait finishing with callback; etc). To prevent such kind automatic use module_set_flags(module_idx, MODULE_FLAG_DISABLE_AUTOUNLOAD);

Module templates

How to add new module