diff options
Diffstat (limited to 'doc/README.standalone')
| -rw-r--r-- | doc/README.standalone | 226 |
1 files changed, 83 insertions, 143 deletions
diff --git a/doc/README.standalone b/doc/README.standalone index a5992ab..3998831 100644 --- a/doc/README.standalone +++ b/doc/README.standalone @@ -1,156 +1,96 @@ Design Notes on Exporting U-Boot Functions to Standalone Applications: ====================================================================== -1. Add a field to the global_data structure, the pointer to a jump - table. - -2. Jump table itself is allocated and filled in the same way as the - syscall table is (allocated with malloc() after the code has been - relocated to RAM); a special function, fixed to the table element - number 0, will be added which returns the ABI version so - applications can check for compatibility issues. - -3. It is application's responsibility to check the ABI version and - act accordingly. - -4. Pointer to the global_data is passed to the application in the - dedicated register that is used in the U-Boot to hold this - pointer. This assumes that the application is built with the same - register- allocation flags as the U-Boot itself. (Actually, this - is a requirement even now, as the 'go' command does not perform - any actions to protect this register against being clobbered by - the application). - - This approach won't work on the x86 architecture. See below. - -5. Application now calls standard library functions like printf() - instead of specially prefixed names like mon_printf() as it did - before. Present implementation of these functions (using the - system calls mechanism) will be replaced with jump stubs. - -6. To export additional functions, the following steps will have to be - taken: - - - Add the xxx() U-Boot function to the EXPORT_FUNC list - - Add initialization of the appropriate slot in the jump table - -7. To port to a new architecture, the appropriate stub code should be - provided. No other machine-dependent code is used. Once the stub - template is available, no additional coding is needed when - exporting new U-Boot functions. A pre-processor macro will be used - to automatically instantiate the stub definition for each exported - function. - -Note the following: - -- This approach uses a jump table with fixed slot allocation. That - said, to retain the ABI compatibility, no table reordering, - inserting new functions in the middle of the list or deleting - functions from the list is allowed. Any such action will break the - ABI compatibility. - -- The x86 architecture does not use a dedicated register to store the - pointer to the global_data structure. There are the following - approaches available: - - * Pass the global_data pointer to the application in a register or - as an additional argument. This requires special machine- - dependent startup code to be compiled into the application. - - * Make the x86 consistent with the rest of architectures and use a - dedicated register. This renders one register unusable in the - rest of the U-Boot code and thus increases the size of the U-Boot - binary and decreases it performance. - -The following changes will be made: - -- The syscall handling code will be removed. - -- The include/_exports.h file will be introduced, containing the list - of the exported functions in the following form: +1. The functions are exported by U-Boot via a jump table. The jump + 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 + 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; + + Note that the pointers to the functions all have 'void *' type and + thus the compiler cannot perform type checks on these assignments. + +2. The pointer to the jump table is passed to the application in a + machine-dependent way. PowerPC, ARM and MIPS architectures use a + dedicated register to hold the pointer to the 'global_data' + structure: r29 on PowerPC, r8 on ARM and k0 on MIPS. 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: + + DECLARE_GLOBAL_DATA_PTR; + + printf("U-Boot relocation offset: %x\n", gd->reloc_off); + +3. The application should call the app_startup() function before any + call to the exported functions. Also, implementor of the + application may want to check the version of the ABI provided by + U-Boot. To facilitate this, a get_version() function is exported + 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[]) + { + app_startup (argv); + if (get_version () != XF_VERSION) + return 1; + } + +4. The default load and start addresses of the applications are as + follows: + + Load address Start address + x86 0x00040000 0x00040000 + PowerPC 0x00040000 0x00040004 + ARM 0x0c100000 0x0c100000 + MIPS 0x80200000 0x80200000 + + For example, the "hello world" application may be loaded and + executed on a PowerPC board with the following commands: + + => tftp 0x40000 hello_world.bin + => go 0x40004 - EXPORT_FUNC(getc) - EXPORT_FUNC(tstc) - ... +5. To export some additional function foobar(), the following steps + should be undertaken: - This list will be used to assign the slot numbers in the jump - table, to determine the size of the jump table and to generate the - code for the stub functions. + - Append the following line at the end of the include/_exports.h + file: -- The include/exports.h file will be introduced, containing the - prototypes of the exported functions and the assigned slot numbers. + EXPORT_FUNC(foobar) -- The examples/stubs.c file will be introduced, containing the code - for the jump stubs for each of the exported functions. + - Add the prototype for this function to the include/exports.h + file: -Implementation Notes on Exporting U-Boot Functions: -=================================================== + void foobar(void); -1. The patch was applied against TOT as of 7/24 12:50 MEST; the - resulting images were tested on the following boards: + - Add the initialization of the jump table slot wherever + appropriate (most likely, to the jumptable_init() function): - * lwmon (PowerPC) - * trab (ARM) - * inca (MIPS) + gd->jt[XF_foobar] = foobar; - The hello_world application was loaded and executed then: + - Increase the XF_VERSION value by one in the include/exports.h + file - [lwmon] - => tftp 0x40000 /tftpboot/LWMON/hello_world.bin-avn - => go 0x40004 +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 + table. That said, to port this code to a new architecture, the + only thing to be provided is the code in the examples/stubs.c + file. If this architecture, however, uses some uncommon method of + passing the 'global_data' pointer (like x86 does), one should add + the respective code to the app_startup() function in that file. - [trab] - TRAB # tftp 0xc100000 /tftpboot/TRAB/hello_world.bin-avn - TRAB # go 0xc100000 - - [inca] - INCA-IP # tftp 0x80200000 /tftpboot/INCA/hello_world.bin-avn - INCA-IP # go 0x80200000 - -2. As neither of supported x86 boards can be built from the TOT - sources currently, the patch build was verified by manually - running the following command in the U-Boot top directory: - - > make -C examples TOPDIR=`pwd` ARCH=i386 CROSS_COMPILE= - - The rest of the code is mostly machine-independent and was not - verified. - -3. To test the x86 assembly code, a small standalone application was - written. It was built and run on the RedHat Linux 8.0 (x86). The - application performs a jump using a pointer to jump table and a - function's index in it. - -4. For the MIPS architecture, the linker script is also provided for - linking applications. The default linker script places the .text - and .data sections too far from each other so that the resulting - .bin files span about 256Mb in size. - -5. Several example applications required updating for the new API. - These applications relied upon the bd_t pointer being passed as - the 1st argument to the main function; this had changed when the - system calls were introduced, but apparently, these applications - weren't fixed at that moment. This is fixed now. - -6. GCC issues warnings for the 'sched' application. Since now the - mon_printf() function is renamed to printf(), GCC applies its - knowledge of the format specifiers to check the arguments, - complaining about ints passed as longs and vice versa. This is not - fixed yet. - -7. Only the hello_world example application was modified to make use - of the newly supplied get_version() function. The application now - prints two ABI versions, the one that the application was compiled - for and the other, actual ABI version. - -8. The following new files were added: - common/exports.c - examples/mips.lds - examples/stubs.c - include/_exports.h - include/exports.h - doc/README.standalone - - The following files are no longer used and will be removed: - examples/syscall.S - include/syscall.h + Note that these functions may only use call-clobbered registers; + those registers that are used to pass the function's arguments, + the stack contents and the return address should be left intact. |