xref: /seL4-l4v-master/seL4/manual/parts/api.tex

%
% Copyright 2014, General Dynamics C4 Systems
%
% SPDX-License-Identifier: GPL-2.0-only
%

%macros for API documentation
\newcommand{\param}[3]{\texttt{#1}&\texttt{#2}&#3\\ }

\newcommand{\inputapidoc}[1] {\input{parts/api/#1.tex}}
\newcommand{\inputgeneratedapidoc}[1] {\input{generated/#1.tex}}

\newcommand{\apidoc}[8][subsection]
{
    \ifthenelse{\equal{#1}{subsection}}{
        \subsection{\label{api:#2}#3}
    }{}
    \ifthenelse{\equal{#1}{subsubsection}}{
        \subsubsection{\label{api:#2}#3}
    }{}

    \texttt{#5}
    \vspace*{6pt}

    #4

    \begin{center}
    \begin{minipage}{0.95\textwidth}
    \begin{tabularx}{\textwidth}{llX}
    \toprule
    \textbf{Type} & \textbf{Name} & \textbf{Description} \\
    \midrule
    #6
    \bottomrule
    \end{tabularx}
    \end{minipage}
    \end{center}

    \textit{Return value:} #7 \par

    \textit{Description:} #8 \par

    \vfill
}

%Common parameter descriptions

\newcommand{\debugargbpnumshortdesc}{
The API-ID of a target breakpoint. This ID will be a positive integer, with
values ranging from \texttt{0} to \texttt{seL4\_NumHWBreakpoints - 1}.
}

\newcommand{\debugargvaddrshortdesc}{A virtual address which forms part of the
match conditions for the triggering of the breakpoint.
}

\newcommand{\debugargtypeshortdesc}{One of: \texttt{seL4\_InstructionBreakpoint}, which specifies
that the breakpoint should occur on instruction execution at the specified
\texttt{vaddr} or \texttt{seL4\_DataBreakpoint}, which states that the breakpoint
should occur on data access at the specified \texttt{vaddr}.
}

\newcommand{\debugargsizeshortdesc}{A positive integer indicating the
trigger-span of the watchpoint. Must be zero when 'type' is \texttt{seL4\_InstructionBreakpoint}.
}

\newcommand{\debugargrwshortdesc}{One of \texttt{seL4\_BreakOnRead}, meaning the breakpoint will only be
triggered on read-access; \texttt{seL4\_BreakOnWrite} meaning the
breakpoint will only be triggered on write-access, and
\texttt{seL4\_BreakOnReadWrite} meaning the breakpoint will be triggered on
any access.
}

\ifxeightsix
\newcommand{\vmattribsdescintel}{VM Attributes for the
  mapping. Possible values for this type are given in \autoref{ch:vspace}. }
\fi

\newcommand{\noret}{This method does not return anything.}
\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.}
\newcommand{\tcbgetbreakpointtdesc}{Struct that contains
'\texttt{seL4\_Error error}', an seL4 API error value,
'\texttt{seL4\_Word vaddr}', the virtual address at which the breakpoint will currently
be triggered;
'\texttt{seL4\_Word type}', the type of operation which will currently trigger the
breakpoint, whether instruction execution, or data access;
'\texttt{seL4\_Word size}', integer value for the span-size of the breakpoint.
Usually a multiple of two (1, 2, 4, etc.);
'\texttt{seL4\_Word rw}', the access direction that will currently trigger the breakpoint,
whether read, write, or both and
'\texttt{seL4\_Bool is\_enabled}', which indicates whether or not the breakpoint
will currently be triggered if the match conditions are met.
}
\newcommand{\tcbconfiguresinglesteppingtdesc}{Struct that contains
'\texttt{seL4\_Error error}', an seL4 API error value,
'\texttt{seL4\_Bool bp\_was\_consumed}', a boolean which indicates whether or not the \texttt{bp\_num}
breakpoint ID that was passed to the function, was consumed in the setup of the single-stepping
functionality: if this is \texttt{true}, the caller should not attempt to re-use \texttt{bp\_num}
until it has disabled the single-stepping functionality via a subsequent call to
seL4\_TCB\_ConfigureSingleStepping with an \texttt{nun\_instructions} argument of 0.
}

\newcommand{\todo}{TODO}

\section{Error Codes}
\label{sec:errors}

Invoking a capability with invalid parameters will result in an error.
seL4 system calls return an error code in the message tag and a short
error description in the message registers to aid the programmer in
determining the cause of errors.\\

\subsection{Invalid Argument}

A non-capability argument is invalid.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_InvalidArgument} \\
    \ipcbloc{IPCBuffer[0]} & Invalid argument number \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Invalid Capability}

A capability argument is invalid.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_InvalidCapability} \\
    \ipcbloc{IPCBuffer[0]} & Invalid capability argument number \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Illegal Operation}

The requested operation is not permitted.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_IllegalOperation} \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Range Error}

An argument is out of the allowed range.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_RangeError} \\
    \ipcbloc{IPCBuffer[0]} & Minimum allowed value \\
    \ipcbloc{IPCBuffer[1]} & Maximum allowed value \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Alignment Error}

A supplied argument does not meet the alignment requirements.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_AlignmentError} \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Failed Lookup}

A capability could not be looked up.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_FailedLookup} \\
    \ipcbloc{IPCBuffer[0]} & 1 if the lookup failed for a source capability, 0 otherwise\\
    \ipcbloc{IPCBuffer[1]} & Type of lookup failure\\
    \ipcbloc{IPCBuffer[2..]} & Lookup failure description as described in \autoref{sec:lookup_fail_desc}\\
\bottomrule
\end{tabularx}
\vfill

\subsection{Truncated Message}

Too few message words or capabilities were sent in the message.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_TruncatedMessage} \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Delete First}

A destination slot specified in the syscall arguments is occupied.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_DeleteFirst} \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Revoke First}

The object currently has other objects derived from it and the requested
invocation cannot be performed until either these objects are deleted or
the revoke invocation is performed on the capability.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_RevokeFirst} \\
\bottomrule
\end{tabularx}
\vfill

\subsection{Not Enough Memory}

The \obj{Untyped Memory} object does not have enough unallocated space to
complete the \apifunc{seL4\_Untyped\_Retype}{untyped_retype} request.

\begin{tabularx}{\textwidth}{p{0.25\textwidth}X}
\toprule
    Field & Meaning \\
\midrule
    \ipcbloc{Label} & \enummem{seL4\_NotEnoughMemory} \\
    \ipcbloc{IPCBuffer[0]} & Amount of memory available in bytes\\
\bottomrule
\end{tabularx}
\vfill

\section{System Calls}

\subsection{General System Calls}
This section provides the system call API for non-MCS kernel configurations.
\inputgeneratedapidoc{GeneralSystemCalls}
\clearpage
\subsection{General System Calls (MCS) }
This section provides the system call API for MCS kernel configurations.
\inputgeneratedapidoc{MCSSystemCalls}
\clearpage

\subsection{Debugging System Calls}
\inputgeneratedapidoc{DebuggingSystemCalls}
\clearpage

\subsection{Benchmarking System Calls}
\inputgeneratedapidoc{BenchmarkingSystemCalls}
\clearpage

\subsection{X86 System Calls}
\inputgeneratedapidoc{X86SystemCalls}
\clearpage

\section{Architecture-Independent Object Methods}
\label{sec:kobj_api}
\inputgeneratedapidoc{ObjectApi}

\ifxeightsix

\clearpage

\section{x86-Specific Object Methods}
\inputgeneratedapidoc{ObjectApiX86}
\clearpage

\section{IA32-Specific Object Methods}
\inputgeneratedapidoc{ObjectApiIa32}
\clearpage

\section{x86\_64-Specific Object Methods}
\inputgeneratedapidoc{ObjectApiX64}

\fi

\clearpage

\section{ARM-Specific Object Methods}

\inputgeneratedapidoc{ObjectApiArm}
\clearpage

\section{Aarch32-Specific Object Methods}
\inputgeneratedapidoc{ObjectApiAarch32}
\clearpage

\section{Aarch64-Specific Object Methods}
\inputgeneratedapidoc{ObjectApiAarch64}
\clearpage

\section{RISCV-Specific Object Methods}
\subsection{General RISCV Object Methods}
\inputgeneratedapidoc{ObjectApiRISCV}