doc/README.standalone

   1 Design Notes on Exporting U-Boot Functions to Standalone Applications:
   2 ======================================================================
   3
   4 1. Add a field to the global_data structure, the pointer to a jump
   5    table.
   6
   7 2. Jump table itself is allocated and filled in the same way as the
   8    syscall table is (allocated with malloc() after the code has been
   9    relocated to RAM); a special function, fixed to the table element
  10    number 0, will be added which returns the ABI version so
  11    applications can check for compatibility issues.
  12
  13 3. It is application's responsibility to check the ABI version and
  14    act accordingly.
  15
  16 4. Pointer to the global_data is passed to the application in the
  17    dedicated register that is used in the U-Boot to hold this
  18    pointer. This assumes that the application is built with the same
  19    register- allocation flags as the U-Boot itself. (Actually, this
  20    is a requirement even now, as the 'go' command does not perform
  21    any actions to protect this register against being clobbered by
  22    the application).
  23
  24    This approach won't work on the x86 architecture. See below.
  25
  26 5. Application now calls standard library functions like printf()
  27    instead of specially prefixed names like mon_printf() as it did
  28    before. Present implementation of these functions (using the
  29    system calls mechanism) will be replaced with jump stubs.
  30
  31 6. To export additional functions, the following steps will have to be
  32    taken:
  33
  34    - Add the xxx() U-Boot function to the EXPORT_FUNC list
  35    - Add initialization of the appropriate slot in the jump table
  36
  37 7. To port to a new architecture, the appropriate stub code should be
  38    provided. No other machine-dependent code is used. Once the stub
  39    template is available, no additional coding is needed when
  40    exporting new U-Boot functions. A pre-processor macro will be used
  41    to automatically instantiate the stub definition for each exported
  42    function.
  43
  44 Note the following:
  45
  46 - This approach uses a jump table with fixed slot allocation. That
  47   said, to retain the ABI compatibility, no table reordering,
  48   inserting new functions in the middle of the list or deleting
  49   functions from the list is allowed. Any such action will break the
  50   ABI compatibility.
  51
  52 - The x86 architecture does not use a dedicated register to store the
  53   pointer to the global_data structure. There are the following
  54   approaches available:
  55
  56   * Pass the global_data pointer to the application in a register or
  57     as an additional argument. This requires special machine-
  58     dependent startup code to be compiled into the application.
  59
  60   * Make the x86 consistent with the rest of architectures and use a
  61     dedicated register. This renders one register unusable in the
  62     rest of the U-Boot code and thus increases the size of the U-Boot
  63     binary and decreases it performance.
  64
  65 The following changes will be made:
  66
  67 - The syscall handling code will be removed.
  68
  69 - The include/_exports.h file will be introduced, containing the list
  70   of the exported functions in the following form:
  71
  72   EXPORT_FUNC(getc)
  73   EXPORT_FUNC(tstc)
  74   ...
  75
  76   This list will be used to assign the slot numbers in the jump
  77   table, to determine the size of the jump table and to generate the
  78   code for the stub functions.
  79
  80 - The include/exports.h file will be introduced, containing the
  81   prototypes of the exported functions and the assigned slot numbers.
  82
  83 - The examples/stubs.c file will be introduced, containing the code
  84   for the jump stubs for each of the exported functions.
  85
  86 Implementation Notes on Exporting U-Boot Functions:
  87 ===================================================
  88
  89 1. The patch was applied against TOT as of 7/24 12:50 MEST; the
  90    resulting images were tested on the following boards:
  91
  92    * lwmon (PowerPC)
  93    * trab  (ARM)
  94    * inca  (MIPS)
  95
  96    The hello_world application was loaded and executed then:
  97
  98    [lwmon]
  99    => tftp 0x40000 /tftpboot/LWMON/hello_world.bin-avn
 100    => go 0x40004
 101
 102    [trab]
 103    TRAB # tftp 0xc100000 /tftpboot/TRAB/hello_world.bin-avn
 104    TRAB # go 0xc100000
 105
 106    [inca]
 107    INCA-IP # tftp 0x80200000 /tftpboot/INCA/hello_world.bin-avn
 108    INCA-IP # go 0x80200000
 109
 110 2. As neither of supported x86 boards can be built from the TOT
 111    sources currently, the patch build was verified by manually
 112    running the following command in the U-Boot top directory:
 113
 114    > make -C examples TOPDIR=`pwd` ARCH=i386 CROSS_COMPILE=
 115
 116    The rest of the code is mostly machine-independent and was not
 117    verified.
 118
 119 3. To test the x86 assembly code, a small standalone application was
 120    written. It was built and run on the RedHat Linux 8.0 (x86). The
 121    application performs a jump using a pointer to jump table and a
 122    function's index in it.
 123
 124 4. For the MIPS architecture, the linker script is also provided for
 125    linking applications. The default linker script places the .text
 126    and .data sections too far from each other so that the resulting
 127    .bin files span about 256Mb in size.
 128
 129 5. Several example applications required updating for the new API.
 130    These applications relied upon the bd_t pointer being passed as
 131    the 1st argument to the main function; this had changed when the
 132    system calls were introduced, but apparently, these applications
 133    weren't fixed at that moment. This is fixed now.
 134
 135 6. GCC issues warnings for the 'sched' application. Since now the
 136    mon_printf() function is renamed to printf(), GCC applies its
 137    knowledge of the format specifiers to check the arguments,
 138    complaining about ints passed as longs and vice versa. This is not
 139    fixed yet.
 140
 141 7. Only the hello_world example application was modified to make use
 142    of the newly supplied get_version() function. The application now
 143    prints two ABI versions, the one that the application was compiled
 144    for and the other, actual ABI version.
 145
 146 8. The following new files were added:
 147    common/exports.c
 148    examples/mips.lds
 149    examples/stubs.c
 150    include/_exports.h
 151    include/exports.h
 152    doc/README.standalone
 153
 154    The following files are no longer used and will be removed:
 155    examples/syscall.S
 156    include/syscall.h