1% 2% Copyright 2014, General Dynamics C4 Systems 3% 4% SPDX-License-Identifier: GPL-2.0-only 5% 6 7%macros for API documentation 8\newcommand{\param}[3]{\texttt{#1}&\texttt{#2}\\ } 9 10\newcommand{\errortable}[1]{ 11 \begin{center} 12 \begin{minipage}{0.95\textwidth} 13 \begin{tabularx}{\textwidth}{lX} 14 \toprule 15 \textbf{Error Code} & \textbf{Possible Cause} \\ 16 \midrule 17 #1 18 \bottomrule 19 \end{tabularx} 20 \end{minipage} 21 \end{center} 22} 23\newcommand{\error}[2]{\texttt{#1}\\ } 24 25\newcommand{\inputapidoc}[1] {\input{parts/api/#1.tex}} 26\newcommand{\inputgeneratedapidoc}[1] {\input{generated/#1.tex}} 27 28\newcommand{\apidoc}[9][subsection] 29{ 30 \ifthenelse{\equal{#1}{subsection}}{ 31 \subsection{\label{api:#2}#3} 32 }{} 33 \ifthenelse{\equal{#1}{subsubsection}}{ 34 \subsubsection{\label{api:#2}#3} 35 }{} 36 37 \texttt{#5} 38 \vspace*{6pt} 39 40 #4 41 42 \begin{center} 43 \begin{minipage}{0.95\textwidth} 44 \begin{tabularx}{\textwidth}{llX} 45 \toprule 46 \textbf{Type} & \textbf{Name} & \textbf{Description} \\ 47 \midrule 48 #6 49 \bottomrule 50 \end{tabularx} 51 \end{minipage} 52 \end{center} 53 54 \textit{Return value:} #7 \par 55 56 \textit{Description:} #8 \par 57 58 #9 59 60 \vfill 61} 62 63%Common parameter descriptions 64 65\newcommand{\debugargbpnumshortdesc}{ 66The API-ID of a target breakpoint. This ID will be a positive integer, with 67values ranging from \texttt{0} to \texttt{seL4\_NumHWBreakpoints - 1}. 68} 69 70\newcommand{\debugargvaddrshortdesc}{A virtual address which forms part of the 71match conditions for the triggering of the breakpoint. 72} 73 74\newcommand{\debugargtypeshortdesc}{One of: \texttt{seL4\_InstructionBreakpoint}, which specifies 75that the breakpoint should occur on instruction execution at the specified 76\texttt{vaddr} or \texttt{seL4\_DataBreakpoint}, which states that the breakpoint 77should occur on data access at the specified \texttt{vaddr}. 78} 79 80\newcommand{\debugargsizeshortdesc}{A positive integer indicating the 81trigger-span of the watchpoint. Must be zero when 'type' is \texttt{seL4\_InstructionBreakpoint}. 82} 83 84\newcommand{\debugargrwshortdesc}{One of \texttt{seL4\_BreakOnRead}, meaning the breakpoint will only be 85triggered on read-access; \texttt{seL4\_BreakOnWrite} meaning the 86breakpoint will only be triggered on write-access, and 87\texttt{seL4\_BreakOnReadWrite} meaning the breakpoint will be triggered on 88any access. 89} 90 91\ifxeightsix 92\newcommand{\vmattribsdescintel}{VM Attributes for the 93 mapping. Possible values for this type are given in \autoref{ch:vspace}. } 94\fi 95 96\newcommand{\noret}{This method does not return anything.} 97\newcommand{\errorenumdesc}{A return value of \texttt{0} indicates success. A non-zero value indicates that an error occurred. See \autoref{sec:errors} for a description of the message register and tag contents upon error.} 98\newcommand{\tcbgetbreakpointtdesc}{Struct that contains 99'\texttt{seL4\_Error error}', an seL4 API error value, 100'\texttt{seL4\_Word vaddr}', the virtual address at which the breakpoint will currently 101be triggered; 102'\texttt{seL4\_Word type}', the type of operation which will currently trigger the 103breakpoint, whether instruction execution, or data access; 104'\texttt{seL4\_Word size}', integer value for the span-size of the breakpoint. 105Usually a multiple of two (1, 2, 4, etc.); 106'\texttt{seL4\_Word rw}', the access direction that will currently trigger the breakpoint, 107whether read, write, or both and 108'\texttt{seL4\_Bool is\_enabled}', which indicates whether or not the breakpoint 109will currently be triggered if the match conditions are met. 110} 111\newcommand{\tcbconfiguresinglesteppingtdesc}{Struct that contains 112'\texttt{seL4\_Error error}', an seL4 API error value, 113'\texttt{seL4\_Bool bp\_was\_consumed}', a boolean which indicates whether or not the \texttt{bp\_num} 114breakpoint ID that was passed to the function, was consumed in the setup of the single-stepping 115functionality: if this is \texttt{true}, the caller should not attempt to re-use \texttt{bp\_num} 116until it has disabled the single-stepping functionality via a subsequent call to 117seL4\_TCB\_ConfigureSingleStepping with an \texttt{nun\_instructions} argument of 0. 118} 119 120\newcommand{\todo}{TODO} 121 122\section{Error Codes} 123\label{sec:errors} 124 125Invoking a capability with invalid parameters will result in an error. 126seL4 system calls return an error code in the message tag and a short 127error description in the message registers to aid the programmer in 128determining the cause of errors.\\ 129 130\subsection{Invalid Argument} 131 132A non-capability argument is invalid. 133 134\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 135\toprule 136 Field & Meaning \\ 137\midrule 138 \ipcbloc{Label} & \enummem{seL4\_InvalidArgument} \\ 139 \ipcbloc{IPCBuffer[0]} & Invalid argument number \\ 140\bottomrule 141\end{tabularx} 142\vfill 143 144\subsection{Invalid Capability} 145 146A capability argument is invalid. 147 148\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 149\toprule 150 Field & Meaning \\ 151\midrule 152 \ipcbloc{Label} & \enummem{seL4\_InvalidCapability} \\ 153 \ipcbloc{IPCBuffer[0]} & Invalid capability argument number \\ 154\bottomrule 155\end{tabularx} 156\vfill 157 158\subsection{Illegal Operation} 159 160The requested operation is not permitted. 161 162\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 163\toprule 164 Field & Meaning \\ 165\midrule 166 \ipcbloc{Label} & \enummem{seL4\_IllegalOperation} \\ 167\bottomrule 168\end{tabularx} 169\vfill 170 171\subsection{Range Error} 172 173An argument is out of the allowed range. 174 175\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 176\toprule 177 Field & Meaning \\ 178\midrule 179 \ipcbloc{Label} & \enummem{seL4\_RangeError} \\ 180 \ipcbloc{IPCBuffer[0]} & Minimum allowed value \\ 181 \ipcbloc{IPCBuffer[1]} & Maximum allowed value \\ 182\bottomrule 183\end{tabularx} 184\vfill 185 186\subsection{Alignment Error} 187 188A supplied argument does not meet the alignment requirements. 189 190\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 191\toprule 192 Field & Meaning \\ 193\midrule 194 \ipcbloc{Label} & \enummem{seL4\_AlignmentError} \\ 195\bottomrule 196\end{tabularx} 197\vfill 198 199\subsection{Failed Lookup} 200 201A capability could not be looked up. 202 203\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 204\toprule 205 Field & Meaning \\ 206\midrule 207 \ipcbloc{Label} & \enummem{seL4\_FailedLookup} \\ 208 \ipcbloc{IPCBuffer[0]} & 1 if the lookup failed for a source capability, 0 otherwise\\ 209 \ipcbloc{IPCBuffer[1]} & Type of lookup failure\\ 210 \ipcbloc{IPCBuffer[2..]} & Lookup failure description as described in \autoref{sec:lookup_fail_desc}\\ 211\bottomrule 212\end{tabularx} 213\vfill 214 215\subsection{Truncated Message} 216 217Too few message words or capabilities were sent in the message. 218 219\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 220\toprule 221 Field & Meaning \\ 222\midrule 223 \ipcbloc{Label} & \enummem{seL4\_TruncatedMessage} \\ 224\bottomrule 225\end{tabularx} 226\vfill 227 228\subsection{Delete First} 229 230A destination slot specified in the syscall arguments is occupied. 231 232\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 233\toprule 234 Field & Meaning \\ 235\midrule 236 \ipcbloc{Label} & \enummem{seL4\_DeleteFirst} \\ 237\bottomrule 238\end{tabularx} 239\vfill 240 241\subsection{Revoke First} 242 243The object currently has other objects derived from it and the requested 244invocation cannot be performed until either these objects are deleted or 245the revoke invocation is performed on the capability. 246 247\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 248\toprule 249 Field & Meaning \\ 250\midrule 251 \ipcbloc{Label} & \enummem{seL4\_RevokeFirst} \\ 252\bottomrule 253\end{tabularx} 254\vfill 255 256\subsection{Not Enough Memory} 257 258The \obj{Untyped Memory} object does not have enough unallocated space to 259complete the \apifunc{seL4\_Untyped\_Retype}{untyped_retype} request. 260 261\begin{tabularx}{\textwidth}{p{0.25\textwidth}X} 262\toprule 263 Field & Meaning \\ 264\midrule 265 \ipcbloc{Label} & \enummem{seL4\_NotEnoughMemory} \\ 266 \ipcbloc{IPCBuffer[0]} & Amount of memory available in bytes\\ 267\bottomrule 268\end{tabularx} 269\vfill 270 271\section{System Calls} 272 273\subsection{General System Calls} 274This section provides the system call API for non-MCS kernel configurations. 275\inputgeneratedapidoc{GeneralSystemCalls} 276\clearpage 277\subsection{General System Calls (MCS) } 278This section provides the system call API for MCS kernel configurations. 279\inputgeneratedapidoc{MCSSystemCalls} 280\clearpage 281 282\subsection{Debugging System Calls} 283\inputgeneratedapidoc{DebuggingSystemCalls} 284\clearpage 285 286\subsection{Benchmarking System Calls} 287\inputgeneratedapidoc{BenchmarkingSystemCalls} 288\clearpage 289 290\subsection{X86 System Calls} 291\inputgeneratedapidoc{X86SystemCalls} 292\clearpage 293 294\section{Architecture-Independent Object Methods} 295\label{sec:kobj_api} 296\inputgeneratedapidoc{ObjectApi} 297 298\ifxeightsix 299 300\clearpage 301 302\section{x86-Specific Object Methods} 303\inputgeneratedapidoc{ObjectApiX86} 304\clearpage 305 306\section{IA32-Specific Object Methods} 307\inputgeneratedapidoc{ObjectApiIa32} 308\clearpage 309 310\section{x86\_64-Specific Object Methods} 311\inputgeneratedapidoc{ObjectApiX64} 312 313\fi 314 315\clearpage 316 317\section{Arm-Specific Object Methods} 318 319\inputgeneratedapidoc{ObjectApiArm} 320\clearpage 321 322\section{Aarch32-Specific Object Methods} 323\inputgeneratedapidoc{ObjectApiAarch32} 324\clearpage 325 326\section{Aarch64-Specific Object Methods} 327\inputgeneratedapidoc{ObjectApiAarch64} 328\clearpage 329 330\section{RISCV-Specific Object Methods} 331\subsection{General RISCV Object Methods} 332\inputgeneratedapidoc{ObjectApiRISCV} 333