blob: 874ca2f7c66a15bdd830c2ef64425a3920433ef0 [file] [log] [blame]
wdenk27b207f2003-07-24 23:38:38 +00001Design Notes on Exporting U-Boot Functions to Standalone Applications:
2======================================================================
3
wdenk77846742003-07-26 08:08:08 +000041. 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
Martin Dorwig49cad542015-01-26 15:22:54 -07008 'global_data' structure. The struct members for the jump table are
wdenk77846742003-07-26 08:08:08 +00009 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:
wdenk27b207f2003-07-24 23:38:38 +000012
wdenk77846742003-07-26 08:08:08 +000013 DECLARE_GLOBAL_DATA_PTR;
wdenk27b207f2003-07-24 23:38:38 +000014
Martin Dorwig49cad542015-01-26 15:22:54 -070015 gd->jt->malloc = my_malloc;
16 gd->jt->free = my_free;
wdenk27b207f2003-07-24 23:38:38 +000017
Martin Dorwig49cad542015-01-26 15:22:54 -070018 Note that the pointers to the functions are real function pointers
19 so the compiler can perform type checks on these assignments.
wdenk27b207f2003-07-24 23:38:38 +000020
wdenk77846742003-07-26 08:08:08 +0000212. The pointer to the jump table is passed to the application in a
Thomas Chou0df01fd2010-05-21 11:08:03 +080022 machine-dependent way. PowerPC, ARM, MIPS, Blackfin and Nios II
23 architectures use a dedicated register to hold the pointer to the
Masahiro Yamada6a105602014-10-22 00:41:49 +090024 'global_data' structure: r2 on PowerPC, r9 on ARM, k0 on MIPS,
Thomas Chou0df01fd2010-05-21 11:08:03 +080025 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.
wdenk27b207f2003-07-24 23:38:38 +000028
wdenk77846742003-07-26 08:08:08 +000029 The application can access the 'global_data' structure in the same
30 way as U-Boot does:
wdenk27b207f2003-07-24 23:38:38 +000031
wdenk77846742003-07-26 08:08:08 +000032 DECLARE_GLOBAL_DATA_PTR;
wdenk27b207f2003-07-24 23:38:38 +000033
wdenk77846742003-07-26 08:08:08 +000034 printf("U-Boot relocation offset: %x\n", gd->reloc_off);
wdenk27b207f2003-07-24 23:38:38 +000035
wdenk77846742003-07-26 08:08:08 +0000363. 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:
wdenk27b207f2003-07-24 23:38:38 +000042
Simon Glass09140112020-05-10 11:40:03 -060043 int my_app (int argc, char *const argv[])
wdenk77846742003-07-26 08:08:08 +000044 {
45 app_startup (argv);
46 if (get_version () != XF_VERSION)
47 return 1;
48 }
wdenk27b207f2003-07-24 23:38:38 +000049
wdenk77846742003-07-26 08:08:08 +0000504. The default load and start addresses of the applications are as
51 follows:
wdenk27b207f2003-07-24 23:38:38 +000052
Mike Frysinger4c58eb52008-02-04 19:26:54 -050053 Load address Start address
54 x86 0x00040000 0x00040000
55 PowerPC 0x00040000 0x00040004
56 ARM 0x0c100000 0x0c100000
57 MIPS 0x80200000 0x80200000
58 Blackfin 0x00001000 0x00001000
Macpaul Linafc1ce82011-10-19 20:41:11 +000059 NDS32 0x00300000 0x00300000
Thomas Chou0df01fd2010-05-21 11:08:03 +080060 Nios II 0x02000000 0x02000000
Rick Chen3fafced2017-12-26 13:55:59 +080061 RISC-V 0x00600000 0x00600000
wdenk27b207f2003-07-24 23:38:38 +000062
wdenk77846742003-07-26 08:08:08 +000063 For example, the "hello world" application may be loaded and
64 executed on a PowerPC board with the following commands:
wdenk27b207f2003-07-24 23:38:38 +000065
wdenk77846742003-07-26 08:08:08 +000066 => tftp 0x40000 hello_world.bin
wdenk27b207f2003-07-24 23:38:38 +000067 => go 0x40004
68
Martin Dorwig49cad542015-01-26 15:22:54 -0700695. To export some additional function long foobar(int i,char c), the following steps
wdenk77846742003-07-26 08:08:08 +000070 should be undertaken:
wdenk27b207f2003-07-24 23:38:38 +000071
wdenk77846742003-07-26 08:08:08 +000072 - Append the following line at the end of the include/_exports.h
73 file:
wdenk27b207f2003-07-24 23:38:38 +000074
Martin Dorwig49cad542015-01-26 15:22:54 -070075 EXPORT_FUNC(foobar, long, foobar, int, char)
76
77 Parameters to EXPORT_FUNC:
78 - the first parameter is the function that is exported (default implementation)
79 - the second parameter is the return value type
80 - the third parameter is the name of the member in struct jt_funcs
81 this is also the name that the standalone application will used.
82 the rest of the parameters are the function arguments
wdenk27b207f2003-07-24 23:38:38 +000083
wdenk77846742003-07-26 08:08:08 +000084 - Add the prototype for this function to the include/exports.h
85 file:
wdenk27b207f2003-07-24 23:38:38 +000086
Martin Dorwig49cad542015-01-26 15:22:54 -070087 long foobar(int i, char c);
wdenk27b207f2003-07-24 23:38:38 +000088
Martin Dorwig49cad542015-01-26 15:22:54 -070089 Initialization with the default implementation is done in jumptable_init()
wdenk27b207f2003-07-24 23:38:38 +000090
Martin Dorwig49cad542015-01-26 15:22:54 -070091 You can override the default implementation using:
92
93 gd->jt->foobar = another_foobar;
94
95 The signature of another_foobar must then match the declaration of foobar.
wdenk27b207f2003-07-24 23:38:38 +000096
wdenk77846742003-07-26 08:08:08 +000097 - Increase the XF_VERSION value by one in the include/exports.h
98 file
wdenk27b207f2003-07-24 23:38:38 +000099
Martin Dorwig49cad542015-01-26 15:22:54 -0700100 - If you want to export a function which depends on a CONFIG_XXX
101 use 2 lines like this:
102 #ifdef CONFIG_FOOBAR
103 EXPORT_FUNC(foobar, long, foobar, int, char)
104 #else
105 EXPORT_FUNC(dummy, void, foobar, void)
106 #endif
107
108
wdenk77846742003-07-26 08:08:08 +00001096. The code for exporting the U-Boot functions to applications is
110 mostly machine-independent. The only places written in assembly
111 language are stub functions that perform the jump through the jump
112 table. That said, to port this code to a new architecture, the
113 only thing to be provided is the code in the examples/stubs.c
114 file. If this architecture, however, uses some uncommon method of
115 passing the 'global_data' pointer (like x86 does), one should add
116 the respective code to the app_startup() function in that file.
wdenk27b207f2003-07-24 23:38:38 +0000117
wdenk77846742003-07-26 08:08:08 +0000118 Note that these functions may only use call-clobbered registers;
119 those registers that are used to pass the function's arguments,
120 the stack contents and the return address should be left intact.