Aksal/nuttx
3
1
Fork 1
mirror of https://github.com/apache/nuttx.git synced 2026-08-10 15:05:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Modules: Move sched/module/module.h to include/nuttx/lib/modlib.h

Browse source
This commit is contained in:
Gregory Nutt 2017-01-29 08:24:42 -06:00
parent 3af8da9c48
commit b79ca9dcdd
18 changed files with 21 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

525
include/nuttx/lib/modlib.h Normal file
View file

@ -0,0 +1,525 @@
/****************************************************************************
* include/nuttx/lib/modlib.h
*
* Copyright (C) 2015, 2017 Gregory Nutt. All rights reserved.
* Author: Gregory Nutt <gnutt@nuttx.org>
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
* 3. Neither the name NuttX nor the names of its contributors may be
* used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
****************************************************************************/
#ifndef __INCLUDE_NUTTX_LIB_MODLIB_H
#define __INCLUDE_NUTTX_LIB_MODLIB_H
/****************************************************************************
* Included Files
****************************************************************************/
#include <nuttx/config.h>
#include <sys/types.h>
#include <elf32.h>
#include <nuttx/arch.h>
#include <nuttx/module.h>
/****************************************************************************
* Public Types
****************************************************************************/
/* This describes the file to be loaded. */
struct symtab_s;
struct module_s
{
FAR struct module_s *flink; /* Supports a singly linked list */
FAR char modulename[MODULENAME_MAX]; /* Module name */
#if defined(CONFIG_FS_PROCFS) && !defined(CONFIG_FS_PROCFS_EXCLUDE_MODULE)
mod_initializer_t initializer; /* Module initializer function */
#endif
struct mod_info_s modinfo; /* Module information */
FAR void *alloc; /* Allocated kernel memory */
#if defined(CONFIG_FS_PROCFS) && !defined(CONFIG_FS_PROCFS_EXCLUDE_MODULE)
size_t textsize; /* Size of the kernel .text memory allocation */
size_t datasize; /* Size of the kernel .bss/.data memory allocation */
#endif
#if CONFIG_MODULE_MAXDEPEND > 0
uint8_t dependents; /* Number of modules that depend on this module */
/* This is an upacked array of pointers to other modules that this module
* depends upon.
*/
FAR struct module_s *dependencies[CONFIG_MODULE_MAXDEPEND];
#endif
};
/* This struct provides a description of the currently loaded instantiation
* of the kernel module.
*/
struct mod_loadinfo_s
{
/* elfalloc is the base address of the memory that is allocated to hold the
* module image.
*
* The alloc[] array in struct module_s will hold memory that persists after
* the module has been loaded.
*/
uintptr_t textalloc; /* .text memory allocated when module was loaded */
uintptr_t datastart; /* Start of.bss/.data memory in .text allocation */
size_t textsize; /* Size of the module .text memory allocation */
size_t datasize; /* Size of the module .bss/.data memory allocation */
off_t filelen; /* Length of the entire module file */
Elf32_Ehdr ehdr; /* Buffered module file header */
FAR Elf32_Shdr *shdr; /* Buffered module section headers */
uint8_t *iobuffer; /* File I/O buffer */
uint16_t symtabidx; /* Symbol table section index */
uint16_t strtabidx; /* String table section index */
uint16_t buflen; /* size of iobuffer[] */
int filfd; /* Descriptor for the file being loaded */
};
/****************************************************************************
* Public Data
****************************************************************************/
FAR const struct symtab_s *g_mod_symtab;
FAR int g_mod_nsymbols;
/****************************************************************************
* Public Function Prototypes
****************************************************************************/
/****************************************************************************
* Name: mod_initialize
*
* Description:
* This function is called to configure the library to process an kernel
* module.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_initialize(FAR const char *filename,
FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_uninitialize
*
* Description:
* Releases any resources committed by mod_init(). This essentially
* undoes the actions of mod_initialize.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_uninitialize(FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_load
*
* Description:
* Loads the binary into memory, allocating memory, performing relocations
* and initializing the data and bss segments.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_load(FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_bind
*
* Description:
* Bind the imported symbol names in the loaded module described by
* 'loadinfo' using the exported symbol values provided by mod_setsymtab().
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_bind(FAR struct module_s *modp, FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_unload
*
* Description:
* This function unloads the object from memory. This essentially undoes
* the actions of mod_load. It is called only under certain error
* conditions after the module has been loaded but not yet started.
*
* Input Parameters:
* modp - Module state information
* loadinfo - Load state information
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_unload(struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_depend
*
* Description:
* Set up module dependencies between the exporter and the importer of a
* symbol. The happens when the module is installed via insmod and a
* symbol is imported from another module.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
* Assumptions:
* Caller holds the registry lock.
*
****************************************************************************/
#if CONFIG_MODULE_MAXDEPEND > 0
int mod_depend(FAR struct module_s *importer, FAR struct module_s *exporter);
#endif
/****************************************************************************
* Name: mod_undepend
*
* Description:
* Tear down module dependencies between the exporters and the importer of
* symbols. This happens when the module is removed via rmmod (and on
* error handling cases in insmod).
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
* Assumptions:
* Caller holds the registry lock.
*
****************************************************************************/
#if CONFIG_MODULE_MAXDEPEND > 0
int mod_undepend(FAR struct module_s *importer);
#endif
/****************************************************************************
* Name: mod_verifyheader
*
* Description:
* Given the header from a possible ELF executable, verify that it is
* an ELF executable.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_verifyheader(FAR const Elf32_Ehdr *header);
/****************************************************************************
* Name: mod_read
*
* Description:
* Read 'readsize' bytes from the object file at 'offset'. The data is
* read into 'buffer.'
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_read(FAR struct mod_loadinfo_s *loadinfo, FAR uint8_t *buffer,
size_t readsize, off_t offset);
/****************************************************************************
* Name: mod_loadshdrs
*
* Description:
* Loads section headers into memory.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_loadshdrs(FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_findsection
*
* Description:
* A section by its name.
*
* Input Parameters:
* loadinfo - Load state information
* sectname - Name of the section to find
*
* Returned Value:
* On success, the index to the section is returned; A negated errno value
* is returned on failure.
*
****************************************************************************/
int mod_findsection(FAR struct mod_loadinfo_s *loadinfo,
FAR const char *sectname);
/****************************************************************************
* Name: mod_findsymtab
*
* Description:
* Find the symbol table section.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_findsymtab(FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_readsym
*
* Description:
* Read the ELFT symbol structure at the specfied index into memory.
*
* Input Parameters:
* loadinfo - Load state information
* index - Symbol table index
* sym - Location to return the table entry
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_readsym(FAR struct mod_loadinfo_s *loadinfo, int index,
FAR Elf32_Sym *sym);
/****************************************************************************
* Name: mod_symvalue
*
* Description:
* Get the value of a symbol. The updated value of the symbol is returned
* in the st_value field of the symbol table entry.
*
* Input Parameters:
* modp - Module state information
* loadinfo - Load state information
* sym - Symbol table entry (value might be undefined)
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
* EINVAL - There is something inconsistent in the symbol table (should only
* happen if the file is corrupted)
* ENOSYS - Symbol lies in common
* ESRCH - Symbol has no name
* ENOENT - Symbol undefined and not provided via a symbol table
*
****************************************************************************/
int mod_symvalue(FAR struct module_s *modp,
FAR struct mod_loadinfo_s *loadinfo, FAR Elf32_Sym *sym);
/****************************************************************************
* Name: mod_freebuffers
*
* Description:
* Release all working buffers.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_freebuffers(FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_allocbuffer
*
* Description:
* Perform the initial allocation of the I/O buffer, if it has not already
* been allocated.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_allocbuffer(FAR struct mod_loadinfo_s *loadinfo);
/****************************************************************************
* Name: mod_reallocbuffer
*
* Description:
* Increase the size of I/O buffer by the specified buffer increment.
*
* Returned Value:
* 0 (OK) is returned on success and a negated errno is returned on
* failure.
*
****************************************************************************/
int mod_reallocbuffer(FAR struct mod_loadinfo_s *loadinfo, size_t increment);
/****************************************************************************
* Name: mod_registry_lock
*
* Description:
* Get exclusive access to the module registry.
*
* Input Parameters:
* None
*
* Returned Value:
* None
*
****************************************************************************/
void mod_registry_lock(void);
/****************************************************************************
* Name: mod_registry_unlock
*
* Description:
* Relinquish the lock on the module registry
*
* Input Parameters:
* None
*
* Returned Value:
* None
*
****************************************************************************/
void mod_registry_unlock(void);
/****************************************************************************
* Name: mod_registry_add
*
* Description:
* Add a new entry to the module registry.
*
* Input Parameters:
* modp - The module data structure to be registered.
*
* Returned Value:
* None
*
* Assumptions:
* The caller holds the lock on the module registry.
*
****************************************************************************/
void mod_registry_add(FAR struct module_s *modp);
/****************************************************************************
* Name: mod_registry_del
*
* Description:
* Remove a module entry from the registry
*
* Input Parameters:
* modp - The registry entry to be removed.
*
* Returned Value:
* Zero (OK) is returned if the registry entry was deleted. Otherwise,
* a negated errno value is returned.
*
* Assumptions:
* The caller holds the lock on the module registry.
*
****************************************************************************/
int mod_registry_del(FAR struct module_s *modp);
/****************************************************************************
* Name: mod_registry_find
*
* Description:
* Find an entry in the module registry using the name of the module.
*
* Input Parameters:
* modulename - The name of the module to be found
*
* Returned Value:
* If the registry entry is found, a pointer to the module entry is
* returned. NULL is returned if the they entry is not found.
*
* Assumptions:
* The caller holds the lock on the module registry.
*
****************************************************************************/
FAR struct module_s *mod_registry_find(FAR const char *modulename);
/****************************************************************************
* Name: mod_registry_verify
*
* Description:
* Verify that a module handle is valid by traversing the module list and
* assuring that the module still resides in the list. If it does not,
* the handle is probably a stale pointer.
*
* Input Parameters:
* modp - The registry entry to be verified.
*
* Returned Value:
* Returns OK is the module is valid; -ENOENT otherwise.
*
* Assumptions:
* The caller holds the lock on the module registry.
*
****************************************************************************/
int mod_registry_verify(FAR struct module_s *modp);
#endif /* __INCLUDE_NUTTX_LIB_MODLIB_H */