README.md
1<!--
2 Copyright 2019, Data61
3 Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4 ABN 41 687 119 230.
5
6 This software may be distributed and modified according to the terms of
7 the BSD 2-Clause license. Note that NO WARRANTY is provided.
8 See "LICENSE_BSD2.txt" for details.
9
10 @TAG(DATA61_BSD)
11-->
12# C Run-time
13
14The standard convention for a static C run-time provides the following 3
15files:
16
17* `crt0.o`; This provides the `_start` symbol which is used as the entry
18 point into a C program.
19* `crti.o`; This provides the prologue to the `_init` and `_fini`
20 symbols. As it occurs in the linker arguments _before_ other object
21 files, other object files may add function calls to the body of these
22 symbols.
23* `crtn.o`; This provides the epilogue to the `_init` and `_fini`
24 symbols and occurs in the linker arguments after all other object
25 files.
26
27## Constructors and Destructors.
28
29The C runtime provides a mechanism for providing functions to be
30executed before and after `main` as constructors and destructors for
31object files and global state.
32
33There are two mechanisms that provide this as documented in the [System
34V ABI][system-v-abi].
35
36The first is the aforementioned `_init` and `_fini` symbols. The second
37is a set of regions called `.preinit_array`, `.init_array`, and
38`.fini_array`. Each of these is simply a vector of void function
39pointers to be executed.
40
41The runtime must, before `main`, execute `_init`, all function pointers
42in `.preinit_array`, then all function pointers in `.init_array`. The
43runtime must also, at `exit`, execute all function pointers in
44`.fini_array` in reverse, then execute `_fini`.
45
46To assist in iterating through these arrays, GCC's internal linker
47script defines the symbols `__(preinit,init,fini)_array_(start,end)` in
48the appropriate sections marking the first function in each and the end
49of the array.
50
51[system-v-abi]: http://www.sco.com/developers/gabi/latest/ch4.sheader.html#special_sections
52
53## The `_start` Symbol
54
55Arguments to `_start` are on the stack for all platforms.
56The top of the stack is structured as so:
57
58* argument count
59* array of argument pointers
60* an empty string
61* array of environment pointers
62* a null terminator
63* array of auxiliary vector entries
64* an 'zero' auxiliary vector
65* unspecified data
66
67For simplicity, we simply pass a pointer to the stack to the C entry in
68the runtime and dissasemble the stack there. The entry we use is as
69follows:
70
71```c
72void __sel4_start_c(void *stack);
73```
74
75NOTE: `__sel4_start_c` is a void function as it should call the
76non-returning `_exit` symbol after calling `main`.
77
78
79