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}&#3\\ }
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