# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1626388822 -7200
# Node ID ca21679a1f5cc4176ac9bd11d8e35faa3c5e594c
# Parent  83c79809b8530bb654e3a11284bbb73176bfe99f
Added the start of some documentation for this project.

diff -r 83c79809b853 -r ca21679a1f5c docs/tools/make_docs.sh
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/tools/make_docs.sh	Fri Jul 16 00:40:22 2021 +0200
@@ -0,0 +1,30 @@
+#!/bin/sh
+
+THISDIR=`dirname "$0"`
+INDIR="$THISDIR/../wiki"
+OUTDIR="$THISDIR/../html"
+
+ROOT="Filesystems"
+
+MAPPING='--mapping WikiPedia https://en.wikipedia.org/wiki/'
+THEME='--theme mercurial'
+
+if [ "$1" = '--web' ] ; then
+    DOCINDEX=
+    shift 1
+else
+    DOCINDEX='--document-index index.html'
+fi
+
+FILENAMES=${*:-'--all'}
+
+moinconvert --input-dir "$INDIR" \
+            --input-page-sep '--' \
+            --output-dir "$OUTDIR" \
+            --root "$ROOT" \
+            --format html \
+            --macros \
+            $DOCINDEX \
+            $MAPPING \
+            $THEME \
+            $FILENAMES
diff -r 83c79809b853 -r ca21679a1f5c docs/wiki/Files
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Files	Fri Jul 16 00:40:22 2021 +0200
@@ -0,0 +1,121 @@
+= Files =
+
+Access to files is provided by a number of programs acting as components. For
+convenience, the component-level operations are wrapped up in a client library
+that aims to provide simpler, more familiar mechanisms for opening, reading,
+writing, and closing files, together with various other operations.
+
+<<TableOfContents(2,3)>>
+
+== Components ==
+
+At the lowest level in L4Re, files are accessed via a suite of components.
+
+=== Filesystems ===
+
+Filesystems implement the `Opener` interface which provides the `context`
+operation:
+
+{{{
+context(out cap context)
+}}}
+
+Each client program, task or thread obtains its own context because it will
+need its own dedicated channel for communication with the filesystem.
+
+=== Contexts ===
+
+A context acts as a dataspace, meaning that it can be attached to a task using
+a region manager and provide a buffer via a region of mapped memory that the
+task can write to. In the case of a context, the task will write a filesystem
+path indicating the file to be opened.
+
+Each context allows a client program to request access to individual files via
+operations provided by the `OpenerContext` interface, of which the most
+pertinent is the `open` operation:
+
+{{{
+open(in flags_t flags, out offset_t size, out cap file)
+}}}
+
+Using the path information written to the context's memory region, the `open`
+operation will obtain a reference to a file.
+
+=== Files ===
+
+Files themselves act as dataspaces, meaning that they can be attached to a
+task using a region manager and provide their content via a region of mapped
+memory. Files implement the `MappedFile` interface.
+
+Control over the region of the file provided via mapped memory occurs
+using the `mmap` operation:
+
+{{{
+mmap(in offset_t position, in offset_t length,
+     out offset_t start_pos, out offset_t end_pos,
+     out offset_t size)
+}}}
+
+Files also implement the more general `File` interface that provides the
+`resize` operation:
+
+{{{
+resize(inout offset_t size)
+}}}
+
+This allows the portion of the memory region dedicated to the file's contents
+to be extended.
+
+== Libraries ==
+
+The filesystem client library offers abstractions and a number of layers of
+functionality to support interaction with components and the provision of
+higher-level mechanisms and abstractions for file access.
+
+=== Client Library ===
+
+The client library provides functions somewhat resembling the traditional C
+library and low-level Unix interfaces for file access, and these functions are
+intended to support such traditional interfaces.
+
+Since files are accessed using file references, the `file_t` data structure is
+used to wrap such references and other relevant state. Thus, such structures
+can be broadly regarded as similar to the traditional `FILE` data structure.
+
+Files are opened and closed using the following functions:
+
+{{{
+file_t *client_open(const char *name, flags_t flags);
+void client_close(file_t *file);
+}}}
+
+Reading and writing files involves functions resembling the traditional
+low-level `read` and `write` functions:
+
+{{{
+offset_t client_read(file_t *file, void *buf, offset_t count);
+offset_t client_write(file_t *file, const void *buf, offset_t count);
+}}}
+
+Support for navigation in files is provided using functions resembling the
+traditional higher-level `fseek` and `ftell` functions:
+
+{{{
+offset_t client_seek(file_t *file, offset_t offset, int whence);
+long client_tell(file_t *file);
+}}}
+
+Although the client library (and the provision of files) employs mapped
+memory, a function can be used to explicitly reference memory for file access:
+
+{{{
+void *client_mmap(file_t *file, offset_t position, offset_t length);
+}}}
+
+For synchronisation purposes, either with the filesystem itself or with other
+users of the filesystem, a function resembling the traditional `fflush`
+function is provided:
+
+{{{
+long client_flush(file_t *file);
+}}}
diff -r 83c79809b853 -r ca21679a1f5c docs/wiki/Filesystems
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Filesystems	Fri Jul 16 00:40:22 2021 +0200
@@ -0,0 +1,8 @@
+= Filesystems =
+
+This distribution aims to provide components and libraries to implement and
+deliver filesystem access in the L4 Runtime Environment.
+
+== Topics ==
+
+ * [[Files]]