← Back to branch summary

~pmdj/ubuntu/trusty/qemu/2.9+applesmc+fadtv3

« back to all changes in this revision

Viewing changes to roms/u-boot/doc/README.standalone

  • Committer: Phil Dennis-Jordan
  • Date: 2017-07-21 08:03:43 UTC
  • mfrom: (1.1.1)
  • Revision ID: phil@philjordan.eu-20170721080343-2yr2vdj7713czahv
New upstream release 2.9.0.

Show diffs side-by-side

added added

removed removed

Lines of Context:
roms/u-boot/doc/README.standalone
 
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 slot numbers 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[XF_malloc]       = my_malloc;
 
16
        gd->jt[XF_free]         = my_free;
 
17
 
 
18
   Note that the pointers to the functions all have 'void *' type and
 
19
   thus the compiler cannot 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, r8 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 foobar(), 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)
 
75
 
 
76
   - Add the prototype for this function to the include/exports.h
 
77
     file:
 
78
 
 
79
        void foobar(void);
 
80
 
 
81
   - Add the initialization of the jump table slot wherever
 
82
     appropriate (most likely, to the jumptable_init() function):
 
83
 
 
84
        gd->jt[XF_foobar] = foobar;
 
85
 
 
86
   - Increase the XF_VERSION value by one in the include/exports.h
 
87
     file
 
88
 
 
89
6. The code for exporting the U-Boot functions to applications is
 
90
   mostly machine-independent. The only places written in assembly
 
91
   language are stub functions that perform the jump through the jump
 
92
   table. That said, to port this code to a new architecture, the
 
93
   only thing to be provided is the code in the examples/stubs.c
 
94
   file. If this architecture, however, uses some uncommon method of
 
95
   passing the 'global_data' pointer (like x86 does), one should add
 
96
   the respective code to the app_startup() function in that file.
 
97
 
 
98
   Note that these functions may only use call-clobbered registers;
 
99
   those registers that are used to pass the function's arguments,
 
100
   the stack contents and the return address should be left intact.