doc/README.standalone

   1 Design Notes on Exporting U-Boot Functions to Standalone Applications:
   2 ======================================================================
   3
   4 1. The functions are exported by U-Boot via a jump table. The jump
   5    table is allocated and initialized in the jumptable_init() routine
   6    (common/exports.c). Other routines may also modify the jump table,
   7    however. The jump table can be accessed as the 'jt' field of the
   8    'global_data' structure. The slot numbers for the jump table are
   9    defined in the <include/exports.h> header. E.g., to substitute the
  10    malloc() and free() functions that will be available to standalone
  11    applications, one should do the following:
  12
  13         DECLARE_GLOBAL_DATA_PTR;
  14
  15         gd->jt[XF_malloc]       = my_malloc;
  16         gd->jt[XF_free]         = my_free;
  17
  18    Note that the pointers to the functions all have 'void *' type and
  19    thus the compiler cannot perform type checks on these assignments.
  20
  21 2. The pointer to the jump table is passed to the application in a
  22    machine-dependent way. PowerPC, ARM and MIPS architectures use a
  23    dedicated register to hold the pointer to the 'global_data'
  24    structure: r29 on PowerPC, r8 on ARM and k0 on MIPS. The x86
  25    architecture does not use such a register; instead, the pointer to
  26    the 'global_data' structure is passed as 'argv[-1]' pointer.
  27
  28    The application can access the 'global_data' structure in the same
  29    way as U-Boot does:
  30
  31         DECLARE_GLOBAL_DATA_PTR;
  32
  33         printf("U-Boot relocation offset: %x\n", gd->reloc_off);
  34
  35 3. The application should call the app_startup() function before any
  36    call to the exported functions. Also, implementor of the
  37    application may want to check the version of the ABI provided by
  38    U-Boot. To facilitate this, a get_version() function is exported
  39    that returns the ABI version of the running U-Boot. I.e., a
  40    typical application startup may look like this:
  41
  42         int my_app (int argc, char *argv[])
  43         {
  44                 app_startup (argv);
  45                 if (get_version () != XF_VERSION)
  46                         return 1;
  47         }
  48
  49 4. The default load and start addresses of the applications are as
  50    follows:
  51
  52                 Load address    Start address
  53         x86     0x00040000      0x00040000
  54         PowerPC 0x00040000      0x00040004
  55         ARM     0x0c100000      0x0c100000
  56         MIPS    0x80200000      0x80200000
  57
  58    For example, the "hello world" application may be loaded and
  59    executed on a PowerPC board with the following commands:
  60
  61    => tftp 0x40000 hello_world.bin
  62    => go 0x40004
  63
  64 5. To export some additional function foobar(), the following steps
  65    should be undertaken:
  66
  67    - Append the following line at the end of the include/_exports.h
  68      file:
  69
  70         EXPORT_FUNC(foobar)
  71
  72    - Add the prototype for this function to the include/exports.h
  73      file:
  74
  75         void foobar(void);
  76
  77    - Add the initialization of the jump table slot wherever
  78      appropriate (most likely, to the jumptable_init() function):
  79
  80         gd->jt[XF_foobar] = foobar;
  81
  82    - Increase the XF_VERSION value by one in the include/exports.h
  83      file
  84
  85 6. The code for exporting the U-Boot functions to applications is
  86    mostly machine-independent. The only places written in assembly
  87    language are stub functions that perform the jump through the jump
  88    table. That said, to port this code to a new architecture, the
  89    only thing to be provided is the code in the examples/stubs.c
  90    file. If this architecture, however, uses some uncommon method of
  91    passing the 'global_data' pointer (like x86 does), one should add
  92    the respective code to the app_startup() function in that file.
  93
  94    Note that these functions may only use call-clobbered registers;
  95    those registers that are used to pass the function's arguments,
  96    the stack contents and the return address should be left intact.