NXFLAT is derived from XFLAT. XFLAT is a toolchain add that provides full shared library and XIP executable - support for processors that have no Memory Management Unit (MMU). + support for processors that have no Memory Management Unit (MMU1). NXFLAT is greatly simplified for the deeply embedded environment targeted by Nuttx:
Rather, the NXFLAT module only imports symbol values. - In the NXFLAT model, the (PIC1) NXFLAT module resides in a FLASH file system and + In the NXFLAT model, the (PIC2) NXFLAT module resides in a FLASH file system and when it is loaded at run time, it is dynamically linked only to the (non-PIC) base NuttX code: The base NuttX exports a symbol table; the NXFLAT module imports those symbol value to dynamically bind the module to the base code.
-1"Position Independent Code"
+ +
+ 1MMU: "Memory Management Unit"
+ 2PIC: "Position Independent Code"
+
- 1"Memory Management Unit"
- 2"Position Independent Code"
+ 1MMU: "Memory Management Unit"
+ 2PIC: "Position Independent Code"
3A work around is under consideration:
At run time, the .rodata offsets will be indexed by a RAM address.
If the dynamic loader were to offset those .rodata offsets properly, it
@@ -406,28 +418,187 @@ any following arguments.
Target 1.
- This target links all of the object files together into one relocation object.
- In this case, there is only a single object file, hello.o, and it is linked to produce hello.r1.
+ This target links all of the module's object files together into one relocatable object.
+ Two relocatable objects will be generated; this is the first one (hence, the suffic .r1).
+ In this "Hello, World!" case, there is only a single object file, hello.o,
+ that is linked to produce the hello.r1 object.
+
+ When the module's object files are compiled, some special compiler CFLAGS must be provided.
+ First, the option -fpic is required to tell the compiler to generate position independent code (other
+ GCC options, like -fno-jump-tables might also be desirable).
+ For ARM compilers, two additional compilation options are required: -msingle-pic-base
+ and -mpic-register=r10.
Target 2.
- Given hello.r1, this target will invoke mknxflat
+ Given the hello.r1 relocatable object, this target will invoke
+ mknxflat
to make the thunk file, hello-thunk.S.
- This thunk contains all of the information needed to create the imported function list.
+ This thunk file contains all of the information needed to create the imported function list.
Target 3
- This this target is similar to Target 1.
- In this case, it will link together the object file, hello.o along with the assembled thunk file,
- hello-thunk.o to create another, single relocatable object, hello.r2.
+ This target is similar to Target 1.
+ In this case, it will link together the module's object files (only hello.o here)
+ along with the assembled thunk file, hello-thunk.o to create the second relocatable object,
+ hello.r2.
The linker script, gnu-nxflat.ld is required at this point to correctly position the sections.
+ This linker script produces two segments:
+ An I-Space (Instruction Space) segment containing mostly .text and a D-Space (Data Space) segment
+ containing .got, .data, and .bss sections.
+ The I-Space section must be origined at address 0 (so that the segment's addresses are really offsets into
+ the I-Space segment)
+ and the D-Space section must also be origined at address 0 (so that segment's addresses are really offsets into
+ the I-Space segment).
+ The option -no-check-sections is required to prevent the linker from failing because these segments overlap.
Target 4.
Finally, this target will use the hello.r2 relocatable object to create the final, NXFLAT module
- hello by calling ldnxflat.
+ hello by executing ldnxflat.
+ 3.0 Binary Loader APIs+ |
+
Relevant Header Files:
+include/nuttx/binfmt.h.
+ A brief summary of the APIs prototyped in that header file are listed below.
+ include/nuttx/nxflat.h.
+ include/nxflat.h.
+ binfmt Registration
+ These first interfaces are used only by a binary loader module, such as NXFLAT itself.
+ NXFLAT (or any future binary loader) calls register_binfmt() to incorporate
+ itself into the system.
+ In this way, the binary loader logic is dynamically extensible to support any kind of loader.
+ Normal application code should not be concerned with these interfaces.
+
int register_binfmt(FAR struct binfmt_s *binfmt)
+
Description: + Register a loader for a binary format +
+Returned Value:
+ This is a NuttX internal function so it follows the convention that
+ 0 (OK) is returned on success and a negated errno is returned on
+ failure.
+
int unregister_binfmt(FAR struct binfmt_s *binfmt)
+
Description: + Register a loader for a binary format +
+Returned Value:
+ This is a NuttX internal function so it follows the convention that
+ 0 (OK) is returned on success and a negated errno is returned on
+ failure.
+
NXFLAT Initialization
+ These interfaces are specific to NXFLAT.
+ Normally, an application needs only call nxflat_initialize() during its initialization
+ to have full NXFLAT support.
+
int nxflat_initialize(void)
+
Description:
+ NXFLAT support is built unconditionally. However, it order to
+ use this binary format, this function must be called during system
+ format in order to register the NXFLAT binary format.
+ This function calls register_binfmt() appropriately.
+
Returned Value: + This is a NuttX internal function so it follows the convention that + 0 (OK) is returned on success and a negated errno is returned on + failure. +
+void nxflat_uninitialize(void)
+
Description: + Unregister the NXFLAT binary loader +
+Returned Value: + None +
+Binary Loader Interfaces. + The remaining APIs are called by user applications to maintain modules in the file system. +
+ +int load_module(FAR struct binary_s *bin)
+
Description: + Load a module into memory, bind it to an exported symbol take, and + prep the module for execution. +
+Returned Value:
+ This is an end-user function, so it follows the normal convention:
+ Returns 0 (OK) on success. On failure, it returns -1 (ERROR) with
+ errno set appropriately.
+
int unload_module(FAR const struct binary_s *bin)
+
Description:
+ Unload a (non-executing) module from memory. If the module has
+ been started (via exec_module()), calling this will be fatal.
+
Returned Value:
+ This is a NuttX internal function so it follows the convention that
+ 0 (OK) is returned on success and a negated errno is returned on
+ failure.
+
int exec_module(FAR const struct binary_s *bin, int priority)
+
Description: + Execute a module that has been loaded into memory by load_module(). +
+Returned Value:
+ This is an end-user function, so it follows the normal convention:
+ Returns the PID of the exec'ed module. On failure, it.returns
+ -1 (ERROR) and sets errno appropriately.
+
|
@@ -438,7 +609,7 @@ any following arguments.
When GCC generate position independent code, new code sections will appear in your programs. - One of these the the GOT (Global Offset Table) and, in ELF environments, the PLT (Procedure + One of these is the GOT (Global Offset Table) and, in ELF environments, another is the PLT (Procedure Lookup Table. For example, if your C code generated (ARM) assembly language like this without PIC: diff --git a/TODO b/TODO index 3370e58c0c..90bc128479 100644 --- a/TODO +++ b/TODO @@ -13,7 +13,7 @@ NuttX TODO List (Last updated June 26, 2009) (8) File system/Generic drivers (fs/, drivers/) (2) Graphics subystem (graphics/) (1) Pascal add-on (pcode/) - (2) Documentation (Documentation/) + (1) Documentation (Documentation/) (6) Build system / Toolchains (3) NuttShell (NSH) (examples/nsh) (3) Other Applications & Tests (examples/) @@ -359,10 +359,6 @@ o Documentation (Documentation/) Status: Open Priority: Low - Description: Need to document binary loader APIs - Status: Open - Priority: Low - o Build system ^^^^^^^^^^^^ |