wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 1 | Design Notes on Exporting U-Boot Functions to Standalone Applications: |
| 2 | ====================================================================== |
| 3 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 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 |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 8 | 'global_data' structure. The struct members for the jump table are |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 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: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 12 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 13 | DECLARE_GLOBAL_DATA_PTR; |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 14 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 15 | gd->jt->malloc = my_malloc; |
| 16 | gd->jt->free = my_free; |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 17 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 18 | Note that the pointers to the functions are real function pointers |
| 19 | so the compiler can perform type checks on these assignments. |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 20 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 21 | 2. The pointer to the jump table is passed to the application in a |
Thomas Chou | 0df01fd | 2010-05-21 11:08:03 +0800 | [diff] [blame] | 22 | machine-dependent way. PowerPC, ARM, MIPS, Blackfin and Nios II |
| 23 | architectures use a dedicated register to hold the pointer to the |
Masahiro Yamada | 6a10560 | 2014-10-22 00:41:49 +0900 | [diff] [blame] | 24 | 'global_data' structure: r2 on PowerPC, r9 on ARM, k0 on MIPS, |
Thomas Chou | 0df01fd | 2010-05-21 11:08:03 +0800 | [diff] [blame] | 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. |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 28 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 29 | The application can access the 'global_data' structure in the same |
| 30 | way as U-Boot does: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 31 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 32 | DECLARE_GLOBAL_DATA_PTR; |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 33 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 34 | printf("U-Boot relocation offset: %x\n", gd->reloc_off); |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 35 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 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: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 42 | |
Wolfgang Denk | 54841ab | 2010-06-28 22:00:46 +0200 | [diff] [blame] | 43 | int my_app (int argc, char * const argv[]) |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 44 | { |
| 45 | app_startup (argv); |
| 46 | if (get_version () != XF_VERSION) |
| 47 | return 1; |
| 48 | } |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 49 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 50 | 4. The default load and start addresses of the applications are as |
| 51 | follows: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 52 | |
Mike Frysinger | 4c58eb5 | 2008-02-04 19:26:54 -0500 | [diff] [blame] | 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 |
Macpaul Lin | afc1ce8 | 2011-10-19 20:41:11 +0000 | [diff] [blame] | 59 | NDS32 0x00300000 0x00300000 |
Thomas Chou | 0df01fd | 2010-05-21 11:08:03 +0800 | [diff] [blame] | 60 | Nios II 0x02000000 0x02000000 |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 61 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 62 | For example, the "hello world" application may be loaded and |
| 63 | executed on a PowerPC board with the following commands: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 64 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 65 | => tftp 0x40000 hello_world.bin |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 66 | => go 0x40004 |
| 67 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 68 | 5. To export some additional function long foobar(int i,char c), the following steps |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 69 | should be undertaken: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 70 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 71 | - Append the following line at the end of the include/_exports.h |
| 72 | file: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 73 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 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 |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 82 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 83 | - Add the prototype for this function to the include/exports.h |
| 84 | file: |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 85 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 86 | long foobar(int i, char c); |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 87 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 88 | Initialization with the default implementation is done in jumptable_init() |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 89 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 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. |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 95 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 96 | - Increase the XF_VERSION value by one in the include/exports.h |
| 97 | file |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 98 | |
Martin Dorwig | 49cad54 | 2015-01-26 15:22:54 -0700 | [diff] [blame^] | 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 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 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. |
wdenk | 27b207f | 2003-07-24 23:38:38 +0000 | [diff] [blame] | 116 | |
wdenk | 7784674 | 2003-07-26 08:08:08 +0000 | [diff] [blame] | 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. |