]>
Commit | Line | Data |
---|---|---|
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 struct members 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->malloc = my_malloc; | |
16 | gd->jt->free = my_free; | |
17 | ||
18 | Note that the pointers to the functions are real function pointers | |
19 | so the compiler can 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, MIPS, Blackfin and Nios II | |
23 | architectures use a dedicated register to hold the pointer to the | |
24 | 'global_data' structure: r2 on PowerPC, r9 on ARM, k0 on MIPS, | |
25 | P3 on Blackfin and gp on Nios II. The x86 architecture does not | |
26 | use such a register; instead, the pointer to the 'global_data' | |
27 | structure is passed as 'argv[-1]' pointer. | |
28 | ||
29 | The application can access the 'global_data' structure in the same | |
30 | way as U-Boot does: | |
31 | ||
32 | DECLARE_GLOBAL_DATA_PTR; | |
33 | ||
34 | printf("U-Boot relocation offset: %x\n", gd->reloc_off); | |
35 | ||
36 | 3. The application should call the app_startup() function before any | |
37 | call to the exported functions. Also, implementor of the | |
38 | application may want to check the version of the ABI provided by | |
39 | U-Boot. To facilitate this, a get_version() function is exported | |
40 | that returns the ABI version of the running U-Boot. I.e., a | |
41 | typical application startup may look like this: | |
42 | ||
43 | int my_app (int argc, char * const argv[]) | |
44 | { | |
45 | app_startup (argv); | |
46 | if (get_version () != XF_VERSION) | |
47 | return 1; | |
48 | } | |
49 | ||
50 | 4. The default load and start addresses of the applications are as | |
51 | follows: | |
52 | ||
53 | Load address Start address | |
54 | x86 0x00040000 0x00040000 | |
55 | PowerPC 0x00040000 0x00040004 | |
56 | ARM 0x0c100000 0x0c100000 | |
57 | MIPS 0x80200000 0x80200000 | |
58 | Blackfin 0x00001000 0x00001000 | |
59 | NDS32 0x00300000 0x00300000 | |
60 | Nios II 0x02000000 0x02000000 | |
61 | ||
62 | For example, the "hello world" application may be loaded and | |
63 | executed on a PowerPC board with the following commands: | |
64 | ||
65 | => tftp 0x40000 hello_world.bin | |
66 | => go 0x40004 | |
67 | ||
68 | 5. To export some additional function long foobar(int i,char c), the following steps | |
69 | should be undertaken: | |
70 | ||
71 | - Append the following line at the end of the include/_exports.h | |
72 | file: | |
73 | ||
74 | EXPORT_FUNC(foobar, long, foobar, int, char) | |
75 | ||
76 | Parameters to EXPORT_FUNC: | |
77 | - the first parameter is the function that is exported (default implementation) | |
78 | - the second parameter is the return value type | |
79 | - the third parameter is the name of the member in struct jt_funcs | |
80 | this is also the name that the standalone application will used. | |
81 | the rest of the parameters are the function arguments | |
82 | ||
83 | - Add the prototype for this function to the include/exports.h | |
84 | file: | |
85 | ||
86 | long foobar(int i, char c); | |
87 | ||
88 | Initialization with the default implementation is done in jumptable_init() | |
89 | ||
90 | You can override the default implementation using: | |
91 | ||
92 | gd->jt->foobar = another_foobar; | |
93 | ||
94 | The signature of another_foobar must then match the declaration of foobar. | |
95 | ||
96 | - Increase the XF_VERSION value by one in the include/exports.h | |
97 | file | |
98 | ||
99 | - If you want to export a function which depends on a CONFIG_XXX | |
100 | use 2 lines like this: | |
101 | #ifdef CONFIG_FOOBAR | |
102 | EXPORT_FUNC(foobar, long, foobar, int, char) | |
103 | #else | |
104 | EXPORT_FUNC(dummy, void, foobar, void) | |
105 | #endif | |
106 | ||
107 | ||
108 | 6. The code for exporting the U-Boot functions to applications is | |
109 | mostly machine-independent. The only places written in assembly | |
110 | language are stub functions that perform the jump through the jump | |
111 | table. That said, to port this code to a new architecture, the | |
112 | only thing to be provided is the code in the examples/stubs.c | |
113 | file. If this architecture, however, uses some uncommon method of | |
114 | passing the 'global_data' pointer (like x86 does), one should add | |
115 | the respective code to the app_startup() function in that file. | |
116 | ||
117 | Note that these functions may only use call-clobbered registers; | |
118 | those registers that are used to pass the function's arguments, | |
119 | the stack contents and the return address should be left intact. |