Skip to content

Commit f6656e2

Browse files
bbrcknlmbrcknl
authored andcommitted
Add a glossary to the manual
Add a glossary with seL4-specific terms and their definitions. Remove chapter number from bibliography Tweak Makefile for glossary Signed-off-by: Birgit Brecknell <[email protected]>
1 parent 43607ed commit f6656e2

File tree

7 files changed

+152
-19
lines changed

7 files changed

+152
-19
lines changed

.gitignore

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,11 @@
1717
*.blg
1818
*.toc
1919
*.mpx
20+
*.acn
21+
*.glo
22+
*.gls
23+
*.ilg
24+
*.ist
2025

2126
tools/parsetab.py
2227
manual/env.tex

include/machine/interrupt.h

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ static inline bool_t isIRQPending(void);
8080
* When an IRQ is disabled, it should not raise an interrupt on the processor.
8181
*
8282
* @param[in] disable True to disable IRQ, False to enable IRQ
83-
* @param[in] irq The irq to modify
83+
* @param[in] irq The IRQ to modify
8484
*/
8585
static inline void maskInterrupt(bool_t disable, irq_t irq);
8686

@@ -93,7 +93,7 @@ static inline void maskInterrupt(bool_t disable, irq_t irq);
9393
* but before user level has handled the cause and does not imply that the cause
9494
* of the interrupt has been handled.
9595
*
96-
* @param[in] irq irq to ack
96+
* @param[in] irq IRQ to ack
9797
*/
9898
static inline void ackInterrupt(irq_t irq);
9999

libsel4/include/sel4/syscalls.h

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,14 +87,14 @@ seL4_DebugSnapshot(void);
8787

8888
/**
8989
* @xmlonly <manual name="Cap Identify" label="sel4_debugcapidentify"/> @endxmlonly
90-
* @brief Identify the type of a capability in the current cspace.
90+
* @brief Identify the type of a capability in the current CSpace.
9191
*
9292
* This debugging system call returns the type of capability in a capability
93-
* slot in the current cspace. The type returned is not a libsel4 type, but
93+
* slot in the current CSpace. The type returned is not a libsel4 type, but
9494
* refers to an internal seL4 type. This can be looked up in a built kernel by
9595
* looking for the (generated) `enum cap_tag`, type `cap_tag_t`.
9696
*
97-
* @param cap A capability slot in the current cspace.
97+
* @param cap A capability slot in the current CSpace.
9898
* @return The type of capability passed in.
9999
*
100100
*/

manual/Makefile

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,7 @@ clean:
228228
*.out *.ps *-diff.tex *.mps .log *.pdf *.tgz *~ *.lof *.lot env.tex
229229
rm -rf ${DoxygenOutput} ${GeneratedLatexDir} ${GeneratedMarkdownDir}
230230
rm -rf ${Stage}
231+
rm -rf *.acn *.glo *.gls *.ilg *.ist
231232

232233
tar: clean
233234
( p=`pwd` && d=`basename "$$p"` && cd .. && \
@@ -291,6 +292,8 @@ references.bib: $(addsuffix .tex, $(Targets))
291292
${Q}if ! test -e $*.bbl || test $(Bib) -nt $*.bbl; then rm -f $*.bbl; fi
292293
@echo "====> LaTeX first pass: $(<)"
293294
${Q}$(LaTeX) $< >.log || if egrep -q $(Error) $*.log ; then cat .log; rm $@; false ; fi
295+
@echo "====> Glossary: $(<)"
296+
${Q}makeindex -s manual.ist -o manual.gls manual.glo
294297
${Q}if egrep -q $(Rerun_Bib) $*.log ; then echo "====> BibTex" && $(BibTeX) $* > /dev/null && echo "====> LaTeX BibTeX pass" && $(LaTeX) >.log $< ; fi
295298
${Q}if egrep -q $(Rerun) $*.log ; then echo "====> LaTeX rerun" && $(LaTeX) >.log $<; fi
296299
${Q}if egrep -q $(Rerun) $*.log ; then echo "====> LaTeX rerun" && $(LaTeX) >.log $<; fi

manual/manual.tex

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,11 @@
1313

1414
\usepackage{url}
1515

16+
% Glossary
17+
\usepackage[acronym,toc]{glossaries}
18+
\input{parts/glossary}
19+
\makeglossaries
20+
1621
% Setting this to true turns on the `draft' watermark
1722
\newif \ifDraft \Draftfalse
1823
%\Drafttrue
@@ -45,7 +50,7 @@
4550
\usepackage{verbatim}
4651
\usepackage[small,bf,up,width=0.75\textwidth]{caption}
4752
\usepackage[htt]{hyphenat}
48-
\usepackage[nottoc,numbib]{tocbibind}
53+
\usepackage[nottoc]{tocbibind}
4954
\renewcommand{\captionfont}{\small}
5055

5156
\renewcommand{\chapterautorefname}{Chapter}
@@ -184,6 +189,10 @@
184189
\label{sec:api_reference}
185190
\input{parts/api}
186191

192+
% glossary
193+
\printglossaries
194+
\glsaddallunused
195+
187196
% Bibliography
188197
\cleardoublepage
189198
\bibliographystyle{plainnat}

manual/parts/glossary.tex

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
%
2+
% Copyright 2014, General Dynamics C4 Systems
3+
%
4+
% SPDX-License-Identifier: GPL-2.0-only
5+
%
6+
7+
\newglossaryentry{asid}{
8+
name=ASID,
9+
description={Address Space Identifier. Depending on architecture, the kernel provides software ASIDs, which are associated with VSpace root objects, and define the virtual address space of a thread. They are mapped to hardware ASIDs on demand when the architecture supports these. Multiple threads may be in the same address space}
10+
}
11+
12+
\newglossaryentry{badge}{
13+
name=Badge,
14+
description={A badge is a piece of extra information stored in a capability, mostly used for endpoint and notification capabilities. It can be used by applications to identify caps previously handed out to clients}
15+
}
16+
17+
\newglossaryentry{cap}{
18+
name=Capability,
19+
description={The main access control concept in seL4. A capability conceptually is a reference to a kernel object together with a set of access rights. Most seL4 capabilities store additional bits of information. Some of this additional information may be exposed to the user, but the bulk of it is kernel-internal book-keeping information. Capabilities are stored in CNodes and TCBs}
20+
}
21+
22+
\newglossaryentry{cdt}{
23+
name=CDT,
24+
description={Capability Derivation Tree. A kernel-internal data structure that tracks the child/parent relationship between capabilities. Capabilities to new objects are children of the Untyped capability the object was created from. Capabilities can also be copied and result in either child or sibling capabilities, depending on the operation that was used and the depth of the existing derivation tree. The revoke operation will delete all children of the invoked capability}
25+
}
26+
27+
\newglossaryentry{cnode}{
28+
name=CNode,
29+
description={Capability Node. Kernel-controlled storage that holds capabilities. Capability nodes can be created in different sizes and be shared between CSpaces}
30+
}
31+
32+
\newglossaryentry{cptr}{
33+
name=CPtr,
34+
description={Capability Pointer. A user-level reference to a capability, relative to a specified root CNode or the thread’s CSpace root}
35+
}
36+
37+
\newglossaryentry{cspace}{
38+
name=CSpace,
39+
description={A directed graph of CNodes. The CSpace of a thread defines the set of capabilities it has access to. The root of the graph is the CNode capability in the CSpace slot of the thread. The edges of the graph are the CNode capabilities residing in the CNodes spanned by this root}
40+
}
41+
42+
\newglossaryentry{endpoint}{
43+
name=Endpoint,
44+
description={IPC is facilitated by small kernel objects known as endpoints, which act as general communication ports. Invocations on endpoint objects are used to send and receive IPC messages}
45+
}
46+
47+
\newglossaryentry{guard}{
48+
name=Guard,
49+
description={Guard of a CNode capability. From the user’s perspetive the CSpace of a thread is organised as a guarded page table. The kernel will resolve user capability pointers into internal capability slot pointers. The guard of one link/edge in the CSpace graph defines a sequence of bits that will be stripped from the user-level capability pointer before resolving resumes at the next CNode}
50+
}
51+
52+
\newglossaryentry{iommu}{
53+
name=IOMMU,
54+
description={Input–Output Memory Management Unit. Applies virtual address translation and memory protection to DMA capable I/O devices}
55+
}
56+
57+
\newglossaryentry{iopagetable}{
58+
name=IOPageTable,
59+
description={This object represents a node in the multilevel page-table structure used by IOMMU hardware to translate hardware memory accesses}
60+
}
61+
62+
\newglossaryentry{iospace}{
63+
name=IOSpace,
64+
description={This object represents the address space associated with a hardware device. It represents the right to modify a device’s address space. See \autoref{ch:io}}
65+
}
66+
67+
\newglossaryentry{ipc}{
68+
name=IPC,
69+
description={Inter Process Communication is facilitated by endpoints, which act as general communication ports. Invocations on endpoint objects are used to send and receive messages}
70+
}
71+
72+
\newglossaryentry{irqcontrol}{
73+
name=IRQControl,
74+
description={A single capability from which IRQHandler capabilities to all IRQ numbers in the system can be derived. This capability can be moved between CSpaces and CSlots but cannot be duplicated. Revoking this capability removes all IRQHandlers}
75+
}
76+
77+
\newglossaryentry{irqhandler}{
78+
name=IRQHandler,
79+
description={Capabilities that represent the ability of a thread to handle a certain interrupt. See \autoref{ch:io}}
80+
}
81+
82+
\newglossaryentry{notificationobject}{
83+
name=Notification Object,
84+
description={A word-size array of flags that provides a non-blocking signalling mechanism similar to a binary semaphore. Operations are signalling a subset of flags in a single operation, polling to check any flags, and blocking until any are signalled. Notification capabilities can be signal-only or wait-only}
85+
}
86+
87+
\newglossaryentry{replyobject}{
88+
name=Reply Object,
89+
description={(MCS only) A reply object is a vessel for tracking reply messages, used to send a reply message and
90+
wake up the caller}
91+
}
92+
93+
\newglossaryentry{schedulingcontext}{
94+
name=Scheduling Context,
95+
description={(MCS only) An abstraction of CPU execution time}
96+
}
97+
98+
\newglossaryentry{tcb}{
99+
name=TCB,
100+
description={Thread Control Block. The kernel object that stores management data for threads, such as the thread's CSpace, VSpace, thread state, or user registers}
101+
}
102+
103+
\newglossaryentry{untypedmemory}{
104+
name=Untyped Memory,
105+
description={Memory that can be used to create kernel objects via the \apifunc{seL4\_Untyped\_Retype}{untyped_retype} invocation. It is the foundation of memory allocation in the seL4 kernel. See \autoref{sec:kernmemalloc}}
106+
}
107+
108+
\newglossaryentry{vm}{
109+
name=VM,
110+
description={Virtual Memory. The concept of translating virtual memory addresses to physical frames. See \autoref{ch:vspace}}
111+
}
112+
113+
\newglossaryentry{vspace}{
114+
name=VSpace,
115+
description={Virtual Address Space. In analogy to CSpace, the virtual memory space of a thread. See \autoref{ch:vspace}}
116+
}

manual/parts/io.tex

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ \subsection{I/O Ports}
9292

9393
The I/O port methods return error codes upon failure.
9494
A \texttt{seL4\_IllegalOperation} code is returned if port access is
95-
attempted outside the range allowed by the \obj{IO Port} capability.
95+
attempted outside the range allowed by the \obj{IO Port} capability.
9696
Since invocations that
9797
read from I/O ports are required to return two values -- the value read
9898
and the error code -- a structure containing two members, \texttt{result}
@@ -135,7 +135,7 @@ \subsection{I/O Space}
135135
either a \obj{VSpace} or an \obj{IOSpace} but never into both at the same time.
136136

137137
\obj{IOSpace} and \obj{VSpace} fault handling differ significantly.
138-
\obj{VSpace} page faults are redirected to the thread's exception handler (see \autoref{sec:faults}),
138+
\obj{VSpace} page faults are redirected to the thread's exception handler (see \autoref{sec:faults}),
139139
which can take the
140140
appropriate action and restart the thread at the faulting instruction.
141141
There is no concept of an exception handler for an \obj{IOSpace}. Instead, faulting
@@ -148,7 +148,7 @@ \subsection{I/O Space}
148148
using the \apifunc{seL4\_CNode\_Mint}{cnode_mint} method, passing the
149149
PCI identifier of the device as the low 16 bits of the \texttt{badge} argument, and
150150
a Domain ID as the high 16 bits of the \texttt{badge} argument.
151-
PCI identifiers are explained fully in the PCI specification
151+
PCI identifiers are explained fully in the PCI specification
152152
\cite{Shanley:PCISA}, but are briefly described here. A PCI identifier is
153153
a 16-bit quantity. The first 8 bits identify the bus that the device is on.
154154
The next 5 bits are the device identifier: the number of the device on
@@ -162,14 +162,14 @@ \subsection{I/O Space}
162162

163163
The IOMMU page-table structure has three levels.
164164
Page tables are mapped into an \obj{IOSpace} using the \apifunc{seL4\_X86\_IOPageTable\_Map}{x86_io_page_table_map} method.
165-
This method takes the \obj{IOPageTable} to map, the \obj{IOSpace} to map into
165+
This method takes the \obj{IOPageTable} to map, the \obj{IOSpace} to map into
166166
and the address to map at. Three levels of page tables must be mapped before
167167
a frame can be mapped successfully. A frame is mapped with the
168168
\apifunc{seL4\_X86\_Page\_MapIO}{x86_page_map_io} method whose parameters are analogous to
169-
the corresponding method that maps \obj{Page}s into \obj{VSpaces} (see \autoref{ch:vspace}),
169+
the corresponding method that maps \obj{Page}s into \obj{VSpaces} (see \autoref{ch:vspace}),
170170
namely \apifunc{seL4\_X86\_Page\_Map}{x86_page_map}.
171171

172-
Unmapping is accomplished with the usual unmap (see \autoref{ch:vspace}) API
172+
Unmapping is accomplished with the usual unmap (see \autoref{ch:vspace}) API
173173
call,
174174
\apifunc{seL4\_X86\_Page\_Unmap}{x86_page_unmap}.
175175

@@ -191,7 +191,7 @@ \subsection{Arm SMMU version 2.0}
191191
SMMU translation context bank (CB). A translation context bank can perform
192192
address translation, memory protection and memory attribute transformation.
193193
The standard specifies different types of address translations that correspond
194-
to stages in the ArmV8 virtual memory system architecture such as either
194+
to stages in the ArmV8 virtual memory system architecture such as either
195195
non-secure EL0, EL1 first and second stage translations, Hyp mode translations
196196
or secure mode translations. It is possible to associate different StreamIDs
197197
with the same context bank and it is possible to share address translation
@@ -218,7 +218,7 @@ \subsection{Arm SMMU version 2.0}
218218
SMMU fault handling and also perform explicit TLB maintenance.
219219
This allows system software to ensure that a device is only able to access and
220220
modify memory contents that it has been explicitly given access to and allow
221-
devices to be presented with a virtualized address space for performing DMA.
221+
devices to be presented with a virtualised address space for performing DMA.
222222

223223
All the StreamIDs and context banks are accessible via capabilities. Control
224224
capabilities are used to create capabilities referring to each StreamID and
@@ -248,7 +248,7 @@ \subsection{Arm SMMU version 2.0}
248248

249249
Four capabilities types provide access to SMMU resources:
250250
\begin{description}
251-
\item[\obj{seL4\_ARM\_SID}] A capability granting access to a single
251+
\item[\obj{seL4\_ARM\_SID}] A capability granting access to a single
252252
transaction stream, which can be used to bind and unbind a stream to a
253253
single context bank.
254254
\item[\obj{seL4\_ARM\_CB}] A capbility representing a single specific context
@@ -280,7 +280,7 @@ \subsubsection{Creating \obj{seL4\_ARM\_SID} capabilities}
280280
\item[\apifunc{seL4\_ARM\_SIDControl\_GetSID}{arm_sid_controlgetsid}] uses the
281281
\obj{seL4\_ARM\_SIDControl} capability to create a new \obj{seL4\_ARM\_SID}
282282
capability that represents a single StreamID. This new capbility is placed
283-
in the provided slot. It is expected that whatever thread controls an
283+
in the provided slot. It is expected that whatever thread controls an
284284
\obj{seL4\_ARM\_SIDControl} capability knows about how StreamIDs are
285285
allocated in a system.
286286
\end{description}
@@ -380,7 +380,7 @@ \subsubsection{Copying and Deleting caps}
380380

381381
Deleting the last ARM\_SID cap will:
382382
\begin{itemize}
383-
\item Perform an \apifunc{seL4\_ARM\_SID\_UnbindCB}{arm_sid_unbindcb},
383+
\item Perform an \apifunc{seL4\_ARM\_SID\_UnbindCB}{arm_sid_unbindcb},
384384
(deleting the copy of the assigned \obj{seL4\_ARM\_CB} cap)
385385
\item Disable the stream ID.
386386
\end{itemize}
@@ -470,7 +470,7 @@ \subsubsection{Fault handling}
470470
\obj{seL4\_ARM\_SIDControl} cap (controlling stream ID distributions) are trusted.
471471
\item SMMU interrupts are handled as same as other IRQs, i,e, the kernel does not
472472
treat the SMMU IRQs special, reporting the interrupt via IRQ notifications.
473-
\item The kernel provides a API for reading the global fault registers:
473+
\item The kernel provides a API for reading the global fault registers:
474474
\apifunc{seL4\_ARM\_SIDControl\_GetFault}{arm_sid_controlgetfault}. Because
475475
the IRQ notification can only deliver information via the badge, the owner
476476
of the StreamControl\_cap can retrieve more information via this API.
@@ -483,7 +483,7 @@ \subsubsection{Fault handling}
483483
cap holder (the \obj{seL4\_ARM\_CB} cap holder).
484484
\item Once the fault handling is done, the server can call
485485
\apifunc{seL4\_ARM\_CB\_CBClearFault}{arm_cb_clearfault} to clear the fault
486-
status on a context bank, and
486+
status on a context bank, and
487487
\apifunc{seL4\_ARM\_SIDControl\_ClearFault}{arm_sid_controlclearfault}
488488
to clear the fault status on SMMU.
489489
\end{itemize}

0 commit comments

Comments
 (0)