Move header information into the section on CHERI C APIs. Rename that

section to make it more general.  Add some notes, including about whether,
in the future, we'll want information on CheriABI headers.

cheri-c-programming.tex

@@ -541,18 +541,6 @@ \section{Impact on the C/\cppInHeader{} programming model}
 In the following sections, we consider various kinds of programmer-visible
 changes required in the pure-capability programming environment.
 
-\subsection{CHERI-related header files}
-
-Two new header files provide access to CHERI-related programming interfaces:
-
-\begin{description}
-\item[\pathname{cheri/cheri.h}] defines constants such as those used in the
-  capability permission mask.
-
-\item[\pathname{cheri/cheric.h}] defines interfaces to access and
-  modify capability properties.
-\end{description}
-
 \subsection{Capability-related faults}
 \label{sec:faults}
 
@@ -1012,7 +1000,7 @@ \subsubsection{Other sources of bounds}
 \Cref{sec:cheriabi}), and the system library may set bounds on pointers
 into returned buffers from APIs -- e.g., \cfunc{fgetln}.
 More detailed information on how C/\cpp{} code can set bounds can be found in
-\Cref{sec:setbounds}.
+\Cref{sec:cheri-apis}.
 
 \subsubsection{Out-of-bounds pointers}
 \label{sec:oob}
@@ -1347,8 +1335,9 @@ \subsubsection{Restrictions in capability locations in memory}
 invalid capabilities that cannot be dereferenced, if, for example, pointer
 values are copied into inappropriately aligned allocations.
 
-\section{C APIs for restricting capability permissions and bounds}
-\label{sec:setbounds}
+\section{C APIs to get and set capability properties}
+%\section{C APIs for restricting capability permissions and bounds}
+\label{sec:cheri-apis}
 
 \rwnote{I wonder if we should talk more about permissions?  Perhaps not in
   this document, in which case possibly we should talk about them less?}
@@ -1357,16 +1346,33 @@ \section{C APIs for restricting capability permissions and bounds}
   of CHERI programming patterns then we probably want a section that talks
   about permissions as well.}
 
+\purecapCOrCpp supports a number of new APIs to get and set capability
+properties given a pointer argument.
 Although most software does not need to directly manage capability properties,
 there are some cases when application code needs to further constrain
 permissions or limit bounds associated with pointers.
 For example, high-performance applications may contain custom memory
 allocators and wish to narrow bounds and permissions on returned pointers
 to prevent overflows between its own allocations.
-CHERI C therefore provides several new APIs to get and set capability
-properties given a pointer argument, which are defined in
-\pathname{cheri/cheric.h}.
-\amnote{We should make it clear that we are referring to headers in the CheriBSD tree.}
+
+\subsection{CHERI-related header files}
+
+A set of compiler built-in functions provide access to capability properties
+of pointers.
+Two new header files provide access to further CHERI-related programming
+interfaces including more human-friendly macro wrappers around the compiler
+built-ins, and also definitions of key CHERI constants:
+
+\begin{description}
+\item[\pathname{cheri/cheri.h}] defines constants such as those used in the
+  capability permission mask.
+
+\item[\pathname{cheri/cheric.h}] defines interfaces to access and
+  modify capability properties.
+\end{description}
+
+\rwnote{This section may need updating once we've converged OS and compiler
+  versions of cheri.h, and done any necessary header refactoring.}
 
 \subsection{Retrieving capability properties}
 
@@ -1582,6 +1588,10 @@ \section{The CheriABI POSIX process environment}
 pointer values and I/O) or new functionality (such as relates to handling
 capability-related faults).
 
+\rwnote{Should there be information on a further CHERI C header here, which
+  contains OS API bits and bobs?  Or is everything either in cheri.h/cheric.h
+  or existing OS headers?}
+
 \subsection{POSIX API changes}
 
 \begin{description}