Blame view
doc/README.standalone
4.4 KB
27b207fd0 * Implement new m... |
1 2 |
Design Notes on Exporting U-Boot Functions to Standalone Applications: ====================================================================== |
778467485 * Allow crc32 to ... |
3 4 5 6 |
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 |
49cad5478 Export redesign |
7 |
'global_data' structure. The struct members for the jump table are |
778467485 * Allow crc32 to ... |
8 9 10 11 12 |
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; |
49cad5478 Export redesign |
13 14 |
gd->jt->malloc = my_malloc; gd->jt->free = my_free; |
778467485 * Allow crc32 to ... |
15 |
|
49cad5478 Export redesign |
16 17 |
Note that the pointers to the functions are real function pointers so the compiler can perform type checks on these assignments. |
778467485 * Allow crc32 to ... |
18 19 |
2. The pointer to the jump table is passed to the application in a |
0df01fd3d nios2: fix r15 is... |
20 21 |
machine-dependent way. PowerPC, ARM, MIPS, Blackfin and Nios II architectures use a dedicated register to hold the pointer to the |
6a10560ce doc: fix README.s... |
22 |
'global_data' structure: r2 on PowerPC, r9 on ARM, k0 on MIPS, |
0df01fd3d nios2: fix r15 is... |
23 24 25 |
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. |
778467485 * Allow crc32 to ... |
26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
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 ", 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: |
54841ab50 Make sure that ar... |
41 |
int my_app (int argc, char * const argv[]) |
778467485 * Allow crc32 to ... |
42 43 44 45 46 47 48 49 |
{ app_startup (argv); if (get_version () != XF_VERSION) return 1; } 4. The default load and start addresses of the applications are as follows: |
4c58eb555 add some more Bla... |
50 51 52 53 54 55 |
Load address Start address x86 0x00040000 0x00040000 PowerPC 0x00040000 0x00040004 ARM 0x0c100000 0x0c100000 MIPS 0x80200000 0x80200000 Blackfin 0x00001000 0x00001000 |
afc1ce828 doc/README: docum... |
56 |
NDS32 0x00300000 0x00300000 |
0df01fd3d nios2: fix r15 is... |
57 |
Nios II 0x02000000 0x02000000 |
778467485 * Allow crc32 to ... |
58 59 60 61 62 63 |
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 |
27b207fd0 * Implement new m... |
64 |
|
49cad5478 Export redesign |
65 |
5. To export some additional function long foobar(int i,char c), the following steps |
778467485 * Allow crc32 to ... |
66 |
should be undertaken: |
27b207fd0 * Implement new m... |
67 |
|
778467485 * Allow crc32 to ... |
68 69 |
- Append the following line at the end of the include/_exports.h file: |
27b207fd0 * Implement new m... |
70 |
|
49cad5478 Export redesign |
71 72 73 74 75 76 77 78 |
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 |
27b207fd0 * Implement new m... |
79 |
|
778467485 * Allow crc32 to ... |
80 81 |
- Add the prototype for this function to the include/exports.h file: |
27b207fd0 * Implement new m... |
82 |
|
49cad5478 Export redesign |
83 84 85 86 87 |
long foobar(int i, char c); Initialization with the default implementation is done in jumptable_init() You can override the default implementation using: |
27b207fd0 * Implement new m... |
88 |
|
49cad5478 Export redesign |
89 |
gd->jt->foobar = another_foobar; |
27b207fd0 * Implement new m... |
90 |
|
49cad5478 Export redesign |
91 |
The signature of another_foobar must then match the declaration of foobar. |
27b207fd0 * Implement new m... |
92 |
|
778467485 * Allow crc32 to ... |
93 94 |
- Increase the XF_VERSION value by one in the include/exports.h file |
27b207fd0 * Implement new m... |
95 |
|
49cad5478 Export redesign |
96 97 98 99 100 101 102 |
- 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 |
778467485 * Allow crc32 to ... |
103 104 105 106 107 108 109 110 |
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. |
27b207fd0 * Implement new m... |
111 |
|
778467485 * Allow crc32 to ... |
112 113 114 |
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. |