the other README files for spec/

spec/README.md

@@ -0,0 +1,6 @@
+# Formal Specifications of seL4
+
+See the sub directories for more details.
+
+The `Makefile` and `ROOT` file define runnable Isabelle sessions for these
+specifications.

spec/abstract/README.md

@@ -0,0 +1,57 @@
+# The Abstract Specification of seL4
+
+	l4v/spec/abstract/
+
+This directory contains the main Isabelle sources of the seL4 abstract
+specification. The specification draws in additional interface files from
+`design` and `machine`. 
+
+The specification is written in monadic style. See `l4v/lib/wp/NonDetMonad`
+for the definition of this monad.
+
+## Top-Level Theory
+
+The top-level theory file that draws the whole specification together is
+`Syscall_A`, the top-level function in that theory is `call_kernel`.
+
+This top-level function defines in-kernel behaviour. Later in the proof,
+in particular in `invariant-abstract`, this function is further wrapped
+in an automaton that describes system behaviour.
+
+## Entry Points 
+
+Two useful entry points for browsing the abstract specification are the
+theories `Structures_A` and `ARM_Structs_A`. They define the state space
+of the kernel model, including what capabilities and kernel objects are.
+
+The theories `Invocations_A` and `ArchInvocation_A` define datatypes for
+the capability invocations/operations the kernel understands.
+
+Most theories are named after the subsystem of the kernel they specify.
+
+## Building
+
+The corresponding Isabelle session is `ASpec`. It is set up to build a
+human-readable PDF document. `Glossary_Doc` contains definitions of common
+seL4 terms.
+
+To build, run in directory `l4v/spec`:
+
+	make ASpec
+
+## Remarks
+  
+ * Note that this specification is actually an extensible _family_ of
+   specifications, with predefined extension points. These points can
+   either be left generic, as for most of the abstract invariant proofs,
+   or they can be instantiated to more precise behaviour, such as in 
+   the theory `Deterministic_A`, which is used for the information flow
+   proofs.
+
+ * The theory `Init_A` *does not* define real kernel initialisation.
+   Instead it is a dummy initial state for the kernel to demonstrate
+   non-emptiness of abstract kernel invariants.
+
+ * `KernelInit_A` is a paused project and not currently included in 
+   the rest of the specification.
+

spec/capDL/README.md

@@ -0,0 +1,40 @@
+# The capDL Specification of seL4
+
+	l4v/spec/capDL/
+
+This directory contains the Isabelle sources of the seL4 behaviour
+specification on the capDL abstraction level. The key features of this
+abstraction level are that it models the complete protection state of the
+kernel in terms of capabilities, and models, as far as possible, only the
+protection state of the kernel (no memory or other state). This means, the
+capDL specification contains a significantly higher degree of nondeterminism
+compared to the other seL4 specs.
+
+This specification is useful for the user-level initialiser that brings the
+system from boot state into a defined protection state defined by a concrete
+capDL description.
+
+There is a refinement proof between the abstract specification and the capDL
+specification in `proof/drefine/`. The capDL spec also forms the basis of the
+system initialiser proofs.
+
+## Top-Level Theory
+
+The top-level theory file in the specification is `Syscall_D`, the top-level
+function in that theory is `call_kernel`.
+
+
+## Entry Points 
+
+A key theory in the capDL spec is `Types_D` which defines a new capability
+type that in addition to the seL4 capabilities contains 'virtual' capabilities
+which store protection state information. For instance, the state of MMU page
+tables is uniformly modelled as capabilities.
+
+
+## Building
+
+The corresponding Isabelle session is `DSpec`. To build, run in directory
+`l4v/spec`:
+
+	make DSpec

spec/cspec/README.md

@@ -0,0 +1,47 @@
+# The C Semantics of seL4
+
+	l4v/spec/cspec/
+
+This directory contains the entry point for the automatic translation of
+the seL4 source code into Isabelle/HOL.
+
+The C semantics of the kernel is produced by first configuring and
+preprocessing the C sources for a specific platform and then parsing it into
+Isabelle using the C parser in `l4v/tools/c-parser`.
+
+To inspect the output of this translation, build the image `CSpec` and
+interactively inspect the constants the parser has defined.
+
+
+## Top-Level Theory
+
+The top-level theory file for this module is `Kernel_C` for the bare
+translation of seL4 into Isabelle, and `KernelInc_C` for additional automatic
+proofs about generated bitfield functions.
+
+
+## Building
+
+The corresponding Isabelle sessions for this module are `CKernel` and `CSpec`.
+`CSpec` contains `CKernel` plus automated bitfield proofs.
+
+To build the image, run the corresponding session in directory `l4v/spec`,
+e.g.:
+
+	make CSpec
+
+This will also configure and preprocess the kernel sources.
+
+Expect this build to take about 30 min on a modern machine and to require
+close to 4GB of memory. For further sessions building on top of `CSpec`,
+usually at least 16GB of main memory are required together with a 64-bit setup
+of Isabelle.
+
+
+## Remarks
+  
+To speed up interactive development, the bitfield code generator can be
+configured to skip the corresponding proofs and produce sorried property
+statements only. To achieve this, set the environment variable
+`SORRY_BITFIELD_PROOFS` to `yes`.
+

spec/design/README.md

@@ -0,0 +1,41 @@
+# The Executable Design Specification of seL4
+
+	l4v/spec/design/
+
+This directory contains the Isabelle sources of the executable design
+specification for seL4. 
+
+Most theory files in this directory are tool-generated, do not edit!
+
+The files here are also not particularly well suited for human consumption, it
+is recommended to directly read the corresponding Haskell code in
+`seL4/haskell` instead.
+
+
+## Top-Level Theory
+
+The top-level theory file that draws the whole specification together is
+`API_H`, the top-level function in that theory is `callKernel`.
+
+Similarly to the abstract specification, this top-level function is later in
+the proofs further wrapped in an automaton that describes system behaviour on
+this level of abstraction.
+
+
+## Building
+
+The corresponding Isabelle session is `ExecSpec`. Build in `l4v/spec/` with
+
+	make ExecSpec
+
+
+## Remarks
+
+ * for regenerating the design spec from Haskell sources, go to directory
+   `l4v/tools/haskell-translator` and run
+
+  		./make_spec.sh
+
+ * skeleton files that define which parts of which Haskell files get mapped
+   to which Isabelle theories are found in the sub directories `skel` and
+   `m-skel` for `design` and `machine` respectively.

spec/machine/README.md

@@ -0,0 +1,25 @@
+# The Machine Interface Specification of seL4
+
+	l4v/spec/machine/
+
+This directory contains the Isabelle sources for the machine interface
+specification used in the abstract and design specifications of seL4.
+
+## Overview
+
+ * `ARMMachineTypes`: ARM register set and related definitions.
+ * `MachineOps`: definitions for the machine interface functions. Most
+   interface functions are left non-deterministic. Some are assumed not to
+   mutate C-observable state, others are defined in more detail.
+ * `MachineTypes`: entry point to select a machine. Currently ARM only.
+ * `Platform`: word size and other basic platform definitions. 
+
+## Building
+
+This module is not built in isolation, but included in the `ASpec` and
+`ExecSpec` sessions.
+
+## Remarks
+  
+ * the theory `ARMMachineTypes` is generated from Haskell using the tool in
+   `tools/haskell-translator` and the skeleton file in `spec/design/m-skel`.