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