mirror of
https://github.com/asterisk/asterisk.git
synced 2025-11-11 04:18:21 +00:00
merge new_loader_completion branch, including (at least):
- restructured build tree and makefiles to eliminate recursion problems - support for embedded modules - support for static builds - simpler cross-compilation support - simpler module/loader interface (no exported symbols) git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@40722 65c4cc65-6c06-0410-ace0-fbb531ad65f3
This commit is contained in:
Kevin P. Fleming
@@ -4,6 +4,8 @@
|
||||
* Copyright (C) 1999 - 2006, Digium, Inc.
|
||||
*
|
||||
* Mark Spencer <markster@digium.com>
|
||||
* Kevin P. Fleming <kpfleming@digium.com>
|
||||
* Luigi Rizzo <rizzo@icir.org>
|
||||
*
|
||||
* See http://www.asterisk.org for more information about
|
||||
* the Asterisk project. Please do not directly contact
|
||||
@@ -26,19 +28,12 @@
|
||||
#ifndef _ASTERISK_MODULE_H
|
||||
#define _ASTERISK_MODULE_H
|
||||
|
||||
#ifdef STATIC_MODULE
|
||||
#error STATIC_MODULE should not be defined
|
||||
#endif
|
||||
#define STATIC_MODULE --- this is an error
|
||||
#define LOCAL_USER_DECL /* --- this is an error --- */
|
||||
|
||||
#include "asterisk/utils.h"
|
||||
|
||||
#if defined(__cplusplus) || defined(c_plusplus)
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
|
||||
/*! \brief The text the key() function should return. */
|
||||
#define ASTERISK_GPL_KEY \
|
||||
"This paragraph is copyright (c) 2006 by Digium, Inc. \
|
||||
@@ -55,24 +50,31 @@ express written permission of Digium, Inc. is prohibited.\n"
|
||||
|
||||
#define AST_MODULE_CONFIG "modules.conf" /*!< \brief Module configuration file */
|
||||
|
||||
enum unload_mode {
|
||||
AST_FORCE_SOFT = 0, /*! Softly unload a module, only if not in use */
|
||||
AST_FORCE_FIRM = 1, /*! Firmly unload a module, even if in use */
|
||||
AST_FORCE_HARD = 2, /*! as FIRM, plus dlclose() on the module. Not recommended
|
||||
enum ast_module_unload_mode {
|
||||
AST_FORCE_SOFT = 0, /*!< Softly unload a module, only if not in use */
|
||||
AST_FORCE_FIRM = 1, /*!< Firmly unload a module, even if in use */
|
||||
AST_FORCE_HARD = 2, /*!< as FIRM, plus dlclose() on the module. Not recommended
|
||||
as it may cause crashes */
|
||||
};
|
||||
|
||||
enum ast_module_load_result {
|
||||
AST_MODULE_LOAD_SUCCESS = 0, /*!< Module loaded and configured */
|
||||
AST_MODULE_LOAD_DECLINE = 1, /*!< Module is not configured */
|
||||
AST_MODULE_LOAD_SKIP = 2, /*!< Module was skipped for some reason */
|
||||
AST_MODULE_LOAD_FAILURE = -1, /*!< Module could not be loaded properly */
|
||||
};
|
||||
|
||||
/*!
|
||||
* \brief Load a module.
|
||||
* \param resource_name The filename of the module to load.
|
||||
* \param resource_name The name of the module to load.
|
||||
*
|
||||
* This function is run by the PBX to load the modules. It performs
|
||||
* all loading and initilization tasks. Basically, to load a module, just
|
||||
* give it the name of the module and it will do the rest.
|
||||
*
|
||||
* \return Zero on success, -1 on error.
|
||||
* \return See possible enum values for ast_module_load_result.
|
||||
*/
|
||||
int ast_load_resource(const char *resource_name);
|
||||
enum ast_module_load_result ast_load_resource(const char *resource_name);
|
||||
|
||||
/*!
|
||||
* \brief Unloads a module.
|
||||
@@ -82,11 +84,11 @@ int ast_load_resource(const char *resource_name);
|
||||
* This function unloads a module. It will only unload modules that are not in
|
||||
* use (usecount not zero), unless #AST_FORCE_FIRM or #AST_FORCE_HARD is
|
||||
* specified. Setting #AST_FORCE_FIRM or #AST_FORCE_HARD will unload the
|
||||
* module regardless of consequences (NOT_RECOMMENDED).
|
||||
* module regardless of consequences (NOT RECOMMENDED).
|
||||
*
|
||||
* \return Zero on success, -1 on error.
|
||||
*/
|
||||
int ast_unload_resource(const char *resource_name, enum unload_mode);
|
||||
int ast_unload_resource(const char *resource_name, enum ast_module_unload_mode);
|
||||
|
||||
/*!
|
||||
* \brief Notify when usecount has been changed.
|
||||
@@ -150,208 +152,123 @@ int ast_loader_unregister(int (*updater)(void));
|
||||
*/
|
||||
char *ast_module_helper(const char *line, const char *word, int pos, int state, int rpos, int needsreload);
|
||||
|
||||
/* Local user routines keep track of which channels are using a given module
|
||||
/* Opaque type for module handles generated by the loader */
|
||||
|
||||
struct ast_module;
|
||||
|
||||
/* User count routines keep track of which channels are using a given module
|
||||
resource. They can help make removing modules safer, particularly if
|
||||
they're in use at the time they have been requested to be removed */
|
||||
|
||||
struct localuser {
|
||||
struct localuser *next;
|
||||
struct ast_channel *chan;
|
||||
};
|
||||
|
||||
struct module_symbols; /* forward declaration */
|
||||
struct localuser *ast_localuser_add(struct module_symbols *, struct ast_channel *);
|
||||
void ast_localuser_remove(struct module_symbols *, struct localuser *);
|
||||
void ast_hangup_localusers(struct module_symbols *);
|
||||
|
||||
/* XXX deprecated macros, only for backward compatibility */
|
||||
#define LOCAL_USER_ADD(u) do { u = ast_localuser_add(__mod_desc, chan); } while (0)
|
||||
#define LOCAL_USER_REMOVE(u) ast_localuser_remove(__mod_desc, u)
|
||||
#define STANDARD_HANGUP_LOCALUSERS ast_hangup_localusers(__mod_desc)
|
||||
struct ast_module_user;
|
||||
struct ast_module_user_list;
|
||||
|
||||
/*! \page ModMngmnt The Asterisk Module management interface
|
||||
* \par The following is part of the new module management code.
|
||||
*
|
||||
* All modules must implement the module API (load, unload...)
|
||||
* whose functions are exported through fields of a "struct module_symbol";
|
||||
*
|
||||
* Modules exporting extra symbols (data or functions), should list
|
||||
* them into an array of struct symbol_entry:
|
||||
* struct symbol_entry exported_symbols[]
|
||||
* of symbols, with a NULL name on the last entry
|
||||
*
|
||||
* Functions should be added with MOD_FUNC(name),
|
||||
* data structures with MOD_DATA(_name).
|
||||
* The array in turn is referenced by struct module_symbols.
|
||||
* (Typically, a module will export only a single symbol, which points
|
||||
* to a record containing all the methods. This is the API of the module,
|
||||
* and should be known to the module's clients as well.
|
||||
*
|
||||
* \par Connections to symbols in other modules
|
||||
* Modules that require symbols supplied by other modules should
|
||||
* provide an array
|
||||
* struct symbol_entry required_symbols[]
|
||||
* of symbols, with a NULL name on the last entry, containing the
|
||||
* name of the desired symbol.
|
||||
* For good measure, we also provide the size in both caller and calle
|
||||
* to figure out if there is a mismatch (not terribly useful because most
|
||||
* objects are a single word, but still... )
|
||||
* The symbol can be added to the array with MOD_WANT(symbol) macro.
|
||||
* required_symbols is also pointed by through struct module_symbols.
|
||||
*
|
||||
* Typically, the whole interface exported by a module should be
|
||||
* in a single structure named after the module, as follows.
|
||||
* Say the module high level name is 'foo', then we should have
|
||||
* - in include/asterisk/foo.h
|
||||
* struct foo_interface {
|
||||
* int (*f)(int, char *); -- first function exported
|
||||
* const char (*g)(int); -- second function exported
|
||||
* char *buf;
|
||||
* ... -- other fields
|
||||
* }
|
||||
* - in the module exporting the interface, e.g. res/res_foo.c
|
||||
* static int f(int, char *);
|
||||
* static const char *g(int);
|
||||
* const char buf[BUFSZ];
|
||||
* struct foo_interface foo = {
|
||||
* .f = f,
|
||||
* .g = g,
|
||||
* .buf = buf,
|
||||
* }
|
||||
*
|
||||
* \note NOTE: symbol names are 'global' in this module namespace, so it
|
||||
* will be wiser to name exported symbols with a prefix indicating the module
|
||||
* supplying it, e.g. foo_f, foo_g, foo_buf. Internally to the module,
|
||||
* symbols are still static so they can keep short and meaningful names.
|
||||
* The macros MOD_FIELD and METHOD_BASE() below help setting these entries.
|
||||
*
|
||||
* MOD_FIELD(f1), -- field and function name are the same
|
||||
* METHOD_BASE(foo_, f1), -- field and function name differ by a prefix
|
||||
* .f1 = function_name, -- generic case
|
||||
* }
|
||||
*
|
||||
* Note that the loader requires that no fields of exported_symbols
|
||||
* are NULL, because that is used as an indication of the end of the array.
|
||||
*
|
||||
* \par Module states
|
||||
* Modules can be in a number of different states, as below:
|
||||
* - \b MS_FAILED attempt to load failed. This is final.
|
||||
* - \b MS_NEW just added to the list, symbols unresolved.
|
||||
* - \b MS_RESOLVED all symbols resolved, but supplier modules not active yet.
|
||||
* - \b MS_CANLOAD all symbols resolved and suppliers are all active
|
||||
* (or we are in a cyclic dependency and we are breaking a loop)
|
||||
* - \b MS_ACTIVE load() returned successfully.
|
||||
*
|
||||
*
|
||||
* \par Module Types
|
||||
* For backward compatibility, we have 3 types of loadable modules:
|
||||
*
|
||||
* - \b MOD_0 these are the 'old style' modules, which export a number
|
||||
* of callbacks, and their full interface, as globally visible
|
||||
* symbols. The module needs to be loaded with RTLD_LAZY and
|
||||
* RTLD_GLOBAL to make symbols visible to other modules, and
|
||||
* to avoid load failures due to cross dependencies.
|
||||
*
|
||||
* - \b MOD_1 almost as above, but the generic callbacks are all into a
|
||||
* a structure, mod_data. Same load requirements as above.
|
||||
*
|
||||
* - \b MOD_2 this is the 'new style' format for modules. The module must
|
||||
* explictly declare which simbols are exported and which
|
||||
* symbols from other modules are used, and the code in this
|
||||
* loader will implement appropriate checks to load the modules
|
||||
* in the correct order. Also this allows to load modules
|
||||
* with RTLD_NOW and RTLD_LOCAL so there is no chance of run-time
|
||||
* bugs due to unresolved symbols or name conflicts.
|
||||
*/
|
||||
|
||||
struct symbol_entry {
|
||||
const char *name;
|
||||
void *value;
|
||||
int size;
|
||||
struct module *src; /* module sourcing it, filled by loader */
|
||||
enum ast_module_flags {
|
||||
AST_MODFLAG_DEFAULT = 0,
|
||||
AST_MODFLAG_GLOBAL_SYMBOLS = (1 << 0),
|
||||
};
|
||||
|
||||
/*
|
||||
* Constructors for symbol_entry values
|
||||
*/
|
||||
#define MOD_FUNC(f) { .name = #f, .value = f, .size = sizeof(f) }
|
||||
#define MOD_DATA(d) { .name = #d, .value = &d, .size = sizeof(_name) }
|
||||
#define MOD_WANT(s) { .name = #s, .value = &s, 0 } /* required symbols */
|
||||
struct ast_module_info {
|
||||
|
||||
/*
|
||||
* Constructors for fields of foo_interface
|
||||
*/
|
||||
#define MOD_FIELD(f) . ## f = f
|
||||
#define METHOD_BASE(_base, _name) . ## _name = _base ## _name
|
||||
/* The 'self' pointer for a module; it will be set by the loader before
|
||||
it calls the module's load_module() entrypoint, and used by various
|
||||
other macros that need to identify the module.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Each 'registerable' entity has a pointer in the
|
||||
* struct ast_registry, which points to an array of objects of
|
||||
* the same type. The ast_*_register() function will be able to
|
||||
* derive the size of these entries.
|
||||
*/
|
||||
struct ast_registry {
|
||||
struct ast_cli_entry *clis;
|
||||
};
|
||||
|
||||
struct module_symbols {
|
||||
/* load, reload and unload receive as argument a pointer to a module descriptor
|
||||
* to be stored locally and used for local calls and so on.
|
||||
* They all return 0 on success, non zero (-1) on failure.
|
||||
*/
|
||||
|
||||
int (*load_module)(void *); /* register stuff etc. Optional. */
|
||||
|
||||
int (*reload)(void *); /* reload config etc. Optional. */
|
||||
|
||||
int (*unload_module)(void *); /* unload. called with the module locked */
|
||||
|
||||
const char *(*description)(void); /* textual id of the module. */
|
||||
struct ast_module *self;
|
||||
enum ast_module_load_result (*load)(void); /* register stuff etc. Optional. */
|
||||
int (*reload)(void); /* config etc. Optional. */
|
||||
int (*unload)(void); /* unload. called with the module locked */
|
||||
const char *name; /* name of the module for loader reference and CLI commands */
|
||||
const char *description; /* user friendly description of the module. */
|
||||
|
||||
/*!
|
||||
* This returns the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
|
||||
* the GPL stated in the ASTERISK_GPL_KEY. Your module will not load if it does
|
||||
* not return the EXACT message:
|
||||
* This holds the ASTERISK_GPL_KEY, signifiying that you agree to the terms of
|
||||
* the Asterisk license as stated in the ASTERISK_GPL_KEY. Your module will not
|
||||
* load if it does not return the EXACT key string.
|
||||
*/
|
||||
const char *(*key)(void); /*! the asterisk key */
|
||||
|
||||
enum module_flags {
|
||||
MOD_0 = 0x0, /* old module style */
|
||||
MOD_1 = 0x1, /* old style, but symbols here */
|
||||
MOD_2 = 0x2, /* new style, exported symbols */
|
||||
MOD_MASK = 0xf, /* mask for module types */
|
||||
NO_USECOUNT = 0x10, /* do not track usecount */
|
||||
NO_UNLOAD = 0x20, /* only forced unload allowed */
|
||||
DO_LOCALUSERS = 0x40, /* track localusers */
|
||||
} flags;
|
||||
/* the following two fields should go in the astobj. */
|
||||
ast_mutex_t lock;
|
||||
int usecnt; /* number of active clients */
|
||||
|
||||
/* list of clients */
|
||||
struct localuser *lu_head;
|
||||
struct ast_registry *reg; /* list of things to register. */
|
||||
struct symbol_entry *exported_symbols;
|
||||
struct symbol_entry *required_symbols;
|
||||
const char *key;
|
||||
unsigned int flags;
|
||||
};
|
||||
|
||||
#ifndef MOD_LOADER /* the loader does not use these */
|
||||
struct module_symbols mod_data; /* forward declaration */
|
||||
static struct module_symbols *__mod_desc __attribute__ ((__unused__)) = &mod_data; /* used by localuser */
|
||||
void ast_module_register(const struct ast_module_info *);
|
||||
void ast_module_unregister(const struct ast_module_info *);
|
||||
|
||||
#define STD_MOD(t, reload_fn, exp, req) \
|
||||
struct module_symbols mod_data = { \
|
||||
.load_module = load_module, \
|
||||
.unload_module = unload_module, \
|
||||
.description = description, \
|
||||
.key = key, \
|
||||
.reload = reload_fn, \
|
||||
.flags = t, \
|
||||
.exported_symbols = exp, \
|
||||
.required_symbols = req \
|
||||
};
|
||||
struct ast_module_user *__ast_module_user_add(struct ast_module *, struct ast_channel *);
|
||||
void __ast_module_user_remove(struct ast_module *, struct ast_module_user *);
|
||||
void __ast_module_user_hangup_all(struct ast_module *);
|
||||
|
||||
#define STD_MOD1 STD_MOD(MOD_1, NULL, NULL, NULL)
|
||||
#define ast_module_user_add(chan) __ast_module_user_add(ast_module_info->self, chan)
|
||||
#define ast_module_user_remove(user) __ast_module_user_remove(ast_module_info->self, user)
|
||||
#define ast_module_user_hangup_all() __ast_module_user_hangup_all(ast_module_info->self)
|
||||
|
||||
struct ast_module *ast_module_ref(struct ast_module *);
|
||||
void ast_module_unref(struct ast_module *);
|
||||
|
||||
#if defined(__cplusplus) || defined(c_plusplus)
|
||||
#define AST_MODULE_INFO(keystr, flags_to_set, desc, load_func, unload_func, reload_func) \
|
||||
static struct ast_module_info __mod_info = { \
|
||||
NULL, \
|
||||
load_func, \
|
||||
unload_func, \
|
||||
reload_func, \
|
||||
AST_MODULE, \
|
||||
desc, \
|
||||
keystr, \
|
||||
flags_to_set \
|
||||
}; \
|
||||
static void __attribute__ ((constructor)) __reg_module(void) \
|
||||
{ \
|
||||
ast_module_register(&__mod_info); \
|
||||
} \
|
||||
static void __attribute__ ((destructor)) __unreg_module(void) \
|
||||
{ \
|
||||
ast_module_unregister(&__mod_info); \
|
||||
} \
|
||||
const static __attribute__((unused)) struct ast_module_info *ast_module_info = &__mod_info
|
||||
|
||||
#define AST_MODULE_INFO_STANDARD(keystr, desc) \
|
||||
AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc, \
|
||||
load_module, \
|
||||
unload_module, \
|
||||
NULL \
|
||||
)
|
||||
#else
|
||||
/* forward declare this pointer in modules, so that macro/function
|
||||
calls that need it can get it, since it will actually be declared
|
||||
and populated at the end of the module's source file... */
|
||||
const static __attribute__((unused)) struct ast_module_info *ast_module_info;
|
||||
|
||||
#define AST_MODULE_INFO(keystr, flags_to_set, desc, fields...) \
|
||||
static struct ast_module_info __mod_info = { \
|
||||
.name = AST_MODULE, \
|
||||
.flags = flags_to_set, \
|
||||
.description = desc, \
|
||||
.key = keystr, \
|
||||
fields \
|
||||
}; \
|
||||
static void __attribute__ ((constructor)) __reg_module(void) \
|
||||
{ \
|
||||
ast_module_register(&__mod_info); \
|
||||
} \
|
||||
static void __attribute__ ((destructor)) __unreg_module(void) \
|
||||
{ \
|
||||
ast_module_unregister(&__mod_info); \
|
||||
} \
|
||||
const static struct ast_module_info *ast_module_info = &__mod_info
|
||||
|
||||
#define AST_MODULE_INFO_STANDARD(keystr, desc) \
|
||||
AST_MODULE_INFO(keystr, AST_MODFLAG_DEFAULT, desc, \
|
||||
.load = load_module, \
|
||||
.unload = unload_module, \
|
||||
)
|
||||
#endif
|
||||
|
||||
#if defined(__cplusplus) || defined(c_plusplus)
|
||||
|
||||
Reference in New Issue
Block a user