Loading refers instantiating the binary module in some fashion, usually copy all or some of the binary module into memory and then linking the module with other components.
In most architectures, it is the base FLASH code that is the primary component that the binary module must link with because that is where the RTOS and primary tasks reside.
Program modules can then be executed after they have been loaded.
</p>
<p>
<b>Binary Formats</b>.
The binary loader provides generic support for different binary formats.
It supports a <i>registration interface</i> that allows the number of support binary formats to be loaded at run time.
Each binary format provides a common, interface for use by the binary loader.
When asked to load a binary, the binary loader will query each registered binary format, providing it with the path of the binary object to be loaded.
The binary loader will stop when first binary format the recognizes the binary object and successfully loads it or when all registered binary formats have attempt loading the binary object and failed.
</p>
<p>
At present, the following binary formats are support by NuttX:
</p>
<ul>
<li>
<b>ELF</b>.
Standard ELF formatted files.
</li>
<li>
<b>NXFLAT</b>.
NuttX NXFLAT formatted files.
More information about the NXFLAT binary format can be found in the
The generic binary loader logic does not care what it is that it being loaded. It could load an executable program or a library.
There are no strict rules, but a library will tend to export symbols and a program will tend to import symbols: The program will use the symbols exported by the library.
In the NuttX source code, the short name <code>binfmt</code> is used to refer to the NuttX binary loader.
This is the name of the directory containing the binary loader and the name of the header files and variables used by the binary loader.
</p>
<p>
The name <code>binfmt</code> is the same name used by the Linux binary loader.
However, the NuttX binary loader is an independent development and shares nothing with the Linux binary loader other the same name and the same basic functionality.
It returns either <code>OK</code> (0) meaning that the binary object was loaded successfully, or a negated <code>errno</code> indicating why the object was not loaded.
The type <code>struct binary_s</code> is use both to (2) describe the binary object to be loaded, and if successfully loaded, (2) to provide information about where and how the binary object was loaded.
That structure is shown below:
</p>
<ul><pre>
struct symtab_s;
struct binary_s
{
/* Information provided to the loader to load and bind a module */
FAR const char *filename; /* Full path to the binary to be loaded */
FAR const char **argv; /* Argument list */
FAR const struct symtab_s *exports; /* Table of exported symbols */
int nexports; /* The number of symbols in exports[] */
/* Information provided from the loader (if successful) describing the
* resources used by the loaded module.
*/
main_t entrypt; /* Entry point into a program module */
FAR void *mapped; /* Memory-mapped, address space */
FAR void *alloc[BINFMT_NALLOC]; /* Allocated address spaces */
#ifdef CONFIG_BINFMT_CONSTRUCTORS
FAR binfmt_ctor_t *ctors; /* Pointer to a list of constructors */
FAR binfmt_dtor_t *dtors; /* Pointer to a list of destructors */
uint16_t nctors; /* Number of constructors in the list */
uint16_t ndtors; /* Number of destructors in the list */
#endif
size_t mapsize; /* Size of the mapped address region (needed for munmap) */
size_t stacksize; /* Size of the stack in bytes (unallocated) */
};
</pre></ul>
<p>
Where the types <code>binfmt_ctor_t</code> and <code>binfmt_dtor_t</code> define the type of one C++ constructor or destructor:
</p>
<ul><pre>
typedef FAR void (*binfmt_ctor_t)(void);
typedef FAR void (*binfmt_dtor_t)(void);
</pre></ul>
<h2>2.3 <aname="binfmtfuncif">Binary Loader Function Interfaces</a></h2>
This is a NuttX internal function so it follows the convention that 0 (<code>OK</code>) is returned on success and a negated <code>errno</code> is returned on failure.
int unregister_binfmt(FAR struct binfmt_s *binfmt);
</pre></ul>
<p><b>Description:</b></p>
<ul>
Register a loader for a binary format.
</ul>
<p><b>Returned Value:</b></p>
<ul>
This is a NuttX internal function so it follows the convention that 0 (<code>OK</code>) is returned on success and a negated <code>errno</code> is returned on failure.
int unload_module(FAR const struct binary_s *bin);
</pre></ul>
<p><b>Description:</b></p>
<ul>
<p>
Unload a (non-executing) module from memory.
If the module has been started (via <code>exec_module()</code>) and has not exited, calling this will be fatal.
</p>
<p>
However, this function must be called after the module exist.
How this is done is up to your logic.
Perhaps you register it to be called by <code>on_exit()</code>?
</ul>
<p><b>Returned Value:</b></p>
<ul>
This is a NuttX internal function so it follows the convention that 0 (<code>OK</code>) is returned on success and a negated <code>errno</code> is returned on failure.
int exec(FAR const char *filename, FAR const char **argv,
FAR const struct symtab_s *exports, int nexports);
</pre></ul>
<p><b>Description:</b></p>
<ul>
This is a convenience function that wraps <code>load_</code> and <code>exec_module()</code> into one call.
</ul>
<p><b>Input Parameters:</b></p>
<ul>
<li><code>filename</code>: Fulll path to the binary to be loaded.</li>
<li><code>argv</code>: Argument list.</li>
<li><code>exports</code>: Table of exported symbols.</li>
<li><code>exports</code>: The number of symbols in exports.</li>
</ul>
<p><b>Returned Value:</b></p>
<ul>
This is an end-user function, so it follows the normal convention:
Returns 0 (<code>OK</code>) on success.
On failure, it returns -1 (<code>ERROR</code>) with <code>errno</code> set appropriately.
</ul>
<tablewidth ="100%">
<trbgcolor="#e4e4e4">
<td>
<h1>3.0 <aname="symtab">Symbol Tables</a></h1>
</td>
</tr>
</table>
<p>
<b>Symbol Tables</b>.
Symbol tables are lists of name value mappings:
The name is a string that identifies a symbol, and the value is an address in memory where the symbol of that name has been positioned.
In most NuttX architectures symbol tables are required, as a minimum, in order to dynamically link the loaded binary object with the base code on FLASH.
Since the binary object was separately built and separately linked, these symbols will appear as <i>undefined</i> symbols in the binary object.
The binary loader will use the symbol table to look up the symbol by its name and to provide the address associated with the symbol as needed to perform the dynamic linking of the binary object to the base FLASH code.
