binman: fit: Allow running fdtgrep on devicetree blobs

[u-boot.git] / doc / README.standalone

diff --git a/doc/README.standalone b/doc/README.standalone
index 885c92fb3a27d969c0b60bbbf2174dedcb2deccb..3306c300cf9200167ff4b47d28af5926319d67fa 100644 (file)
--- a/doc/README.standalone
+++ b/doc/README.standalone
@@ -5,26 +5,26 @@ Design Notes on Exporting U-Boot Functions to Standalone Applications:
    table is allocated and initialized in the jumptable_init() routine
    (common/exports.c). Other routines may also modify the jump table,
    however. The jump table can be accessed as the 'jt' field of the
    table is allocated and initialized in the jumptable_init() routine
    (common/exports.c). Other routines may also modify the jump table,
    however. The jump table can be accessed as the 'jt' field of the

-   'global_data' structure. The slot numbers for the jump table are
+   'global_data' structure. The struct members for the jump table are

    defined in the <include/exports.h> header. E.g., to substitute the
    malloc() and free() functions that will be available to standalone
    applications, one should do the following:
 
        DECLARE_GLOBAL_DATA_PTR;
 
    defined in the <include/exports.h> header. E.g., to substitute the
    malloc() and free() functions that will be available to standalone
    applications, one should do the following:
 
        DECLARE_GLOBAL_DATA_PTR;
 

-       gd->jt[XF_malloc]       = my_malloc;
-       gd->jt[XF_free]         = my_free;
+       gd->jt->malloc  = my_malloc;
+       gd->jt->free = my_free;

 
 

-   Note that the pointers to the functions all have 'void *' type and
-   thus the compiler cannot perform type checks on these assignments.
+   Note that the pointers to the functions are real function pointers
+   so the compiler can perform type checks on these assignments.

 
 2. The pointer to the jump table is passed to the application in a
 
 2. The pointer to the jump table is passed to the application in a

-   machine-dependent way. PowerPC, ARM, MIPS and Blackfin architectures
-   use a dedicated register to hold the pointer to the 'global_data'
-   structure: r2 on PowerPC, r8 on ARM, k0 on MIPS, and P3 on Blackfin.
-   The x86 architecture does not use such a register; instead, the
-   pointer to the 'global_data' structure is passed as 'argv[-1]'
-   pointer.
+   machine-dependent way. PowerPC, ARM, MIPS, Blackfin and Nios II
+   architectures use a dedicated register to hold the pointer to the
+   'global_data' structure: r2 on PowerPC, r9 on ARM, k0 on MIPS,
+   P3 on Blackfin and gp on Nios II. The x86 architecture does not
+   use such a register; instead, the pointer to the 'global_data'
+   structure is passed as 'argv[-1]' pointer.

 
    The application can access the 'global_data' structure in the same
    way as U-Boot does:
 
    The application can access the 'global_data' structure in the same
    way as U-Boot does:


@@ -40,7 +40,7 @@ Design Notes on Exporting U-Boot Functions to Standalone Applications:
    that returns the ABI version of the running U-Boot. I.e., a
    typical application startup may look like this:
 
    that returns the ABI version of the running U-Boot. I.e., a
    typical application startup may look like this:
 

-       int my_app (int argc, char *argv[])
+       int my_app (int argc, char *const argv[])

        {
                app_startup (argv);
                if (get_version () != XF_VERSION)
        {
                app_startup (argv);
                if (get_version () != XF_VERSION)


@@ -56,6 +56,8 @@ Design Notes on Exporting U-Boot Functions to Standalone Applications:
        ARM             0x0c100000      0x0c100000
        MIPS            0x80200000      0x80200000
        Blackfin        0x00001000      0x00001000
        ARM             0x0c100000      0x0c100000
        MIPS            0x80200000      0x80200000
        Blackfin        0x00001000      0x00001000

+       Nios II         0x02000000      0x02000000
+       RISC-V          0x00600000      0x00600000

 
    For example, the "hello world" application may be loaded and
    executed on a PowerPC board with the following commands:
 
    For example, the "hello world" application may be loaded and
    executed on a PowerPC board with the following commands:


@@ -63,27 +65,46 @@ Design Notes on Exporting U-Boot Functions to Standalone Applications:
    => tftp 0x40000 hello_world.bin
    => go 0x40004
 
    => tftp 0x40000 hello_world.bin
    => go 0x40004
 

-5. To export some additional function foobar(), the following steps
+5. To export some additional function long foobar(int i,char c), the following steps

    should be undertaken:
 
    - Append the following line at the end of the include/_exports.h
      file:
 
    should be undertaken:
 
    - Append the following line at the end of the include/_exports.h
      file:
 

-       EXPORT_FUNC(foobar)
+       EXPORT_FUNC(foobar, long, foobar, int, char)
+
+       Parameters to EXPORT_FUNC:
+        - the first parameter is the function that is exported (default implementation)
+        - the second parameter is the return value type
+        - the third  parameter is the name of the member in struct jt_funcs
+          this is also the name that the standalone application will used.
+          the rest of the parameters are the function arguments

 
    - Add the prototype for this function to the include/exports.h
      file:
 
 
    - Add the prototype for this function to the include/exports.h
      file:
 

-       void foobar(void);
+       long foobar(int i, char c);
+
+       Initialization with the default implementation is done in jumptable_init()
+
+       You can override the default implementation using:

 
 

-   - Add the initialization of the jump table slot wherever
-     appropriate (most likely, to the jumptable_init() function):
+       gd->jt->foobar = another_foobar;

 
 

-       gd->jt[XF_foobar] = foobar;
+       The signature of another_foobar must then match the declaration of foobar.

 
    - Increase the XF_VERSION value by one in the include/exports.h
      file
 
 
    - Increase the XF_VERSION value by one in the include/exports.h
      file
 

+   - If you want to export a function which depends on a CONFIG_XXX
+       use 2 lines like this:
+       #ifdef CONFIG_FOOBAR
+               EXPORT_FUNC(foobar, long, foobar, int, char)
+       #else
+               EXPORT_FUNC(dummy, void, foobar, void)
+       #endif
+
+

 6. The code for exporting the U-Boot functions to applications is
    mostly machine-independent. The only places written in assembly
    language are stub functions that perform the jump through the jump
 6. The code for exporting the U-Boot functions to applications is
    mostly machine-independent. The only places written in assembly
    language are stub functions that perform the jump through the jump