1% 2% Copyright 2014, General Dynamics C4 Systems 3% 4% This software may be distributed and modified according to the terms of 5% the GNU General Public License version 2. Note that NO WARRANTY is provided. 6% See "LICENSE_GPLv2.txt" for details. 7% 8% @TAG(GD_GPL) 9% 10 11\chapter{\label{ch:bootup}System Bootstrapping} 12 13\section{Initial Thread's Environment} 14 15The seL4 kernel creates a minimal boot environment for the initial thread. 16This environment consists of the initial thread's TCB, CSpace and VSpace, 17consisting of frames that contain the userland image (code/data of the initial 18thread) and the IPC buffer. 19The initial thread's CSpace consists of exactly one CNode 20which contains capabilities to the initial 21thread's own resources was well as to all available global resources. 22The CNode size can be configured at compile time (default is $2^{12}$ 23slots), but the guard is always chosen so that the CNode resolves exactly 2432 bits. This means, the first slot of the CNode has CPTR 0x0, the 25second slot has CPTR 0x1 etc. 26 27The first 12 slots contain specific capabilities as listed in 28\autoref{tab:cnode_content}. 29 30\begin{table}[htb] 31 \begin{center} 32 \caption{Initial thread's CNode content.} 33 \label{tab:cnode_content} 34 \begin{tabularx}{\textwidth}{lX} 35 \toprule 36 Enum Constant & Capability \\ 37 \midrule 38 \texttt{seL4\_CapNull} & null \\ 39 \texttt{seL4\_CapInitThreadTCB} & initial thread's TCB \\ 40 \texttt{seL4\_CapInitThreadCNode} & initial thread's CNode \\ 41 \texttt{seL4\_CapInitThreadVSpace} & initial thread's VSpace \\ 42 \texttt{seL4\_CapIRQControl} & global IRQ controller (see \autoref{sec:interrupts}) \\ 43 \texttt{seL4\_CapASIDControl} & global ASID controller (see \autoref{ch:vspace}) \\ 44 \texttt{seL4\_CapInitThreadASIDPool} & initial thread's ASID pool (see \autoref{ch:vspace}) \\ 45 \texttt{seL4\_CapIOPort} & global I/O port cap, null cap if unsupported 46\ifxeightsix 47(see \autoref{sec:ioports}) 48\fi 49\\ 50 \texttt{seL4\_CapIOSpace} & global I/O space cap, null cap if unsupported 51\ifxeightsix 52(see \autoref{sec:iospace}) 53\fi 54\\ 55 \texttt{seL4\_CapBootInfoFrame} & BootInfo frame (see \autoref{ch:bootup:bootinfo}) \\ 56 \texttt{seL4\_CapInitThreadIPCBuffer} & initial thread's IPC buffer (see \autoref{sec:messageinfo}) \\ 57 \texttt{seL4\_CapDomain} & domain cap (see \autoref{sec:domains}) \\ 58 \bottomrule 59 \end{tabularx} 60 \end{center} 61\end{table} 62 63\section{\label{ch:bootup:bootinfo}BootInfo Frame} 64 65CNode slots with CPTR \texttt{seL4\_NumInitialCaps} (defined in the seL4 66userland library) and above are filled dynamically during 67bootstrapping. Their exact contents depend on the userland image size, 68platform configuration (devices) etc. In order to tell the initial thread 69which capabilities are stored where in its CNode, the kernel provides 70a \emph{BootInfo Frame} which is mapped into the initial thread's address 71space. The mapped address is chosen by the kernel and given to the initial 72thread via a CPU register. 73 74The BootInfo Frame contains the C struct described in 75\autoref{tab:bootinfo_struct}. 76It is defined in the seL4 userland library. Besides talking about 77capabilities, it also informs the initial thread about 78the current platform's configuration. 79 80The type \texttt{seL4\_SlotRegion} is a C struct 81which contains \texttt{start} and \texttt{end} slot CPTRs. It denotes a region 82of slots in the initial thread's CNode, starting with CPTR \texttt{start} and with 83\texttt{end} being the CPTR of the first slot after the region ends, i.e.\ 84\texttt{end - 1} points to the last slot of the region. 85 86\begin{table}[htb] 87 \begin{center} 88 \caption{BootInfo struct.} 89 \label{tab:bootinfo_struct} 90 \begin{tabularx}{\textwidth}{llX} 91 \toprule 92 Field Type & Field Name & Description \\ 93 \midrule 94 \texttt{seL4\_Word} & \texttt{extraLen} & length of additional bootinfo information in bytes \\ 95 \texttt{seL4\_Word} & \texttt{nodeID} & node ID \\ 96 \texttt{seL4\_Word} & \texttt{numNodes} & number of nodes \\ 97 \texttt{seL4\_Word} & \texttt{numIOPTLevels} & number of I/O page-table levels (-1 if CONFIG\_IOMMU unset) \\ 98 \texttt{seL4\_IPCBuffer*} & \texttt{ipcBuffer} & pointer to the initial thread's IPC buffer \\ 99 \texttt{seL4\_SlotRegion} & \texttt{empty} & empty slots (null caps) \\ 100 \texttt{seL4\_SlotRegion} & \texttt{sharedFrames} & reserved \\ 101 \texttt{seL4\_SlotRegion} & \texttt{userImageFrames} & frames containing the userland image \\ 102 \texttt{seL4\_SlotRegion} & \texttt{userImagePaging} & userland-image paging structure caps \\ 103 \texttt{seL4\_SlotRegion} & \texttt{ioSpaceCaps} & I/O space capabilities for ARM SMMU \\ 104 \texttt{seL4\_SlotRegion} & \texttt{extraBIPages} & frames backing additional bootinfo information \\ 105 \texttt{seL4\_UntypedDesc[]} & \texttt{untypedList} & array of information about each untyped \\ 106 \texttt{seL4\_Uint8} & \texttt{initThreadCNodeSizeBits} & CNode size ($2^n$ slots) \\ 107 \texttt{seL4\_Word} & \texttt{initThreadDomain} & domain of the initial thread (see \autoref{sec:domains}) \\ 108 \texttt{seL4\_SlotRegion} & \texttt{untyped} & untyped-memory capabilities \\ 109 \bottomrule 110 \end{tabularx} 111 \end{center} 112\end{table} 113 114Depending on the architecture and platform there might be additional pieces of boot 115information. If \texttt{extraLen} is greater then zero then 4K after the start of bootinfo 116is a region of extraLen bytes containing additional bootinfo structures. Each chunk starts 117with a \texttt{seL4\_BootInfoHeader}, described in \autoref{tab:bi_header_struct}, that 118describes what the chunk is and how long it is, where the length includes the header. The 119length can be used to skip over chunks that you do not understand. The only generally 120defined chunk type is \texttt{SEL4\_BOOTINFO\_HEADER\_PADDING} and describes an empty 121chunk that has no data, any other types are platform or architecture specific. The 122\texttt{extraBIPages} slot region gives the frames capabilities for the pages that make up 123the additional boot info region. 124 125\begin{table}[htb] 126 \begin{center} 127 \caption{BootInfoHeader struct.} 128 \label{tab:bi_header_struct} 129 \begin{tabular}{lll} 130 \toprule 131 Field Type & Field Name & Description \\ 132 \midrule 133 \texttt{seL4\_Word} & \texttt{id} & Identifier indicating the contents of the chunk \\ 134 \texttt{seL4\_Uint8} & \texttt{len} & Length in bytes of the chunk \\ 135 \bottomrule 136 \end{tabular} 137 \end{center} 138\end{table} 139 140The capabilities in \texttt{userImageFrames} are 141ordered such that the first capability references the first frame of the 142userland image and so on. 143The capabilities in \texttt{userImagePaging} are ordered in descending order 144of paging structure size. Within a given paging structure size, capabilities are 145ordered by the virtual address at which the corresponding objects are mapped 146into the initial thread's address space. 147 148It is up to userland to infer the virtual address of frames referenced by 149the capabilities in \texttt{userImageFrames} and the virtual address and 150types of paging structures 151referenced by the capabilities in \texttt{userImagePaging}. 152Userland typically has a way of finding out to which virtual addresses its 153code and data is mapped (e.g.\ in GCC, with the standard linker script, the 154symbols \texttt{\_\_executable\_start} and \texttt{\_end} are available). 155Additionally, the initial thread can assume that its address space is virtually 156contiguous, and is made up of the smallest frames available on the architecture. 157It's also assumed that the initial thread knows which paging structures are 158available on the architecture it's running on. 159This, along with knowledge of how capabilities in \texttt{userImageFrames} and 160\texttt{userImagePaging} are ordered, is sufficient information for userland to infer 161the virtual address of each 162frame capability, and the virtual address and type of each paging structure capability. 163 164Untyped memory is given in no particular order. The array entry 165\texttt{untypedList[i]} stores the untyped-memory information of 166the i-th untyped cap of the slot region \texttt{untyped}. Therefore, the array 167length is at least \texttt{untyped.end - untyped.start}. The actual length is 168hardcoded in the kernel and irrelevant to the reader of the array. The untyped 169memory information is stored in a \texttt{seL4\_UntypedDesc} struct, described 170in \autoref{tab:untyped_desc_struct}, and details the address, size and kind of 171the memory backing the untyped. This allows userland to infer physical memory 172addresses of retyped frames and use them to initiate DMA transfers when no 173IOMMU is available. The kernel makes no guarantees about certain sizes of untyped 174memory being available. 175 176\begin{table}[htb] 177 \begin{center} 178 \caption{seL4\_UntypedDesc struct} 179 \label{tab:untyped_desc_struct} 180 \begin{tabular}{lll} 181 \toprule 182 Field Type & Field Name & Description \\ 183 \midrule 184 \texttt{seL4\_Word} & \texttt{paddr} & physical base address of the untyped object \\ 185 \texttt{seL4\_Uint8} & \texttt{padding1} & manual padding so final struct is a multiple of the word size \\ 186 \texttt{seL4\_Uint8} & \texttt{padding2} & manual padding so final struct is a multiple of the word size \\ 187 \texttt{seL4\_Uint8} & \texttt{sizeBits} & size ($2^n$ bytes) of the untyped object \\ 188 \texttt{seL4\_Uint8} & \texttt{isDevice} & is this untyped a device or not (see \autoref{sec:kernmemalloc}) \\ 189 \bottomrule 190 \end{tabular} 191 \end{center} 192\end{table} 193 194If the platform has an seL4-supported IOMMU, \texttt{numIOPTLevels} contains 195the number of IOMMU-page-table levels. This information is needed by userland 196when constructing an IOMMU address space (IOSpace). If there is no IOMMU 197support, \texttt{numIOPTLevels} is \texttt{0}. 198 199On ARM if the platform has any available SMMU units the capabilities for them 200will be described by the \texttt{ioSpaceCaps} slot region. The mapping of a 201capability from this region to a specific SMMU is platform specific. 202 203\ifxeightsix 204\section{Boot Command-line Arguments} 205 206On IA-32, seL4 accepts boot command-line arguments which are passed to the 207kernel via a multiboot-compliant bootloader (e.g.\ GRUB, syslinux). Multiple 208arguments are separated from each other by whitespace. Two forms of arguments 209are accepted: 210(1) key-value arguments of the form ``key=value'' and (2) single keys of the 211form ``key''. The value field of the key-value form may be a string, a decimal 212integer, a hexadecimal integer beginning with ``0x'', or an integer list where 213list elements are separated by commas. 214Keys and values can't have any whitespace in them and there can be no 215whitespace before or after an ``='' or a comma either. 216Arguments are listed in \autoref{tab:bootargs} along with their default values (if left unspecified). 217 218 219\begin{table}[htb] 220 \caption{IA-32 boot command-line arguments.} 221 \begin{tabularx}{\textwidth}{lXX} 222 \toprule 223 Key & Value & Default \\ 224 \midrule 225 \texttt{console\_port} & 226 I/O-port base of the serial port that the kernel prints to 227 (if compiled in debug mode) & 228 0x3f8 \\ 229 \texttt{debug\_port} & 230 I/O-port base of the serial port that is used for kernel debugging 231 (if compiled in debug mode) & 232 0x3f8 \\ 233 \texttt{disable\_iommu} & 234 none & 235 The IOMMU is enabled by default on VT-d-capable platforms \\ 236 \bottomrule 237 \end{tabularx} 238 \label{tab:bootargs} 239\end{table} 240\fi 241