1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/tools/make_docs.sh Fri Jul 16 00:40:22 2021 +0200
1.3 @@ -0,0 +1,30 @@
1.4 +#!/bin/sh
1.5 +
1.6 +THISDIR=`dirname "$0"`
1.7 +INDIR="$THISDIR/../wiki"
1.8 +OUTDIR="$THISDIR/../html"
1.9 +
1.10 +ROOT="Filesystems"
1.11 +
1.12 +MAPPING='--mapping WikiPedia https://en.wikipedia.org/wiki/'
1.13 +THEME='--theme mercurial'
1.14 +
1.15 +if [ "$1" = '--web' ] ; then
1.16 + DOCINDEX=
1.17 + shift 1
1.18 +else
1.19 + DOCINDEX='--document-index index.html'
1.20 +fi
1.21 +
1.22 +FILENAMES=${*:-'--all'}
1.23 +
1.24 +moinconvert --input-dir "$INDIR" \
1.25 + --input-page-sep '--' \
1.26 + --output-dir "$OUTDIR" \
1.27 + --root "$ROOT" \
1.28 + --format html \
1.29 + --macros \
1.30 + $DOCINDEX \
1.31 + $MAPPING \
1.32 + $THEME \
1.33 + $FILENAMES
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/wiki/Files Fri Jul 16 00:40:22 2021 +0200
2.3 @@ -0,0 +1,121 @@
2.4 += Files =
2.5 +
2.6 +Access to files is provided by a number of programs acting as components. For
2.7 +convenience, the component-level operations are wrapped up in a client library
2.8 +that aims to provide simpler, more familiar mechanisms for opening, reading,
2.9 +writing, and closing files, together with various other operations.
2.10 +
2.11 +<<TableOfContents(2,3)>>
2.12 +
2.13 +== Components ==
2.14 +
2.15 +At the lowest level in L4Re, files are accessed via a suite of components.
2.16 +
2.17 +=== Filesystems ===
2.18 +
2.19 +Filesystems implement the `Opener` interface which provides the `context`
2.20 +operation:
2.21 +
2.22 +{{{
2.23 +context(out cap context)
2.24 +}}}
2.25 +
2.26 +Each client program, task or thread obtains its own context because it will
2.27 +need its own dedicated channel for communication with the filesystem.
2.28 +
2.29 +=== Contexts ===
2.30 +
2.31 +A context acts as a dataspace, meaning that it can be attached to a task using
2.32 +a region manager and provide a buffer via a region of mapped memory that the
2.33 +task can write to. In the case of a context, the task will write a filesystem
2.34 +path indicating the file to be opened.
2.35 +
2.36 +Each context allows a client program to request access to individual files via
2.37 +operations provided by the `OpenerContext` interface, of which the most
2.38 +pertinent is the `open` operation:
2.39 +
2.40 +{{{
2.41 +open(in flags_t flags, out offset_t size, out cap file)
2.42 +}}}
2.43 +
2.44 +Using the path information written to the context's memory region, the `open`
2.45 +operation will obtain a reference to a file.
2.46 +
2.47 +=== Files ===
2.48 +
2.49 +Files themselves act as dataspaces, meaning that they can be attached to a
2.50 +task using a region manager and provide their content via a region of mapped
2.51 +memory. Files implement the `MappedFile` interface.
2.52 +
2.53 +Control over the region of the file provided via mapped memory occurs
2.54 +using the `mmap` operation:
2.55 +
2.56 +{{{
2.57 +mmap(in offset_t position, in offset_t length,
2.58 + out offset_t start_pos, out offset_t end_pos,
2.59 + out offset_t size)
2.60 +}}}
2.61 +
2.62 +Files also implement the more general `File` interface that provides the
2.63 +`resize` operation:
2.64 +
2.65 +{{{
2.66 +resize(inout offset_t size)
2.67 +}}}
2.68 +
2.69 +This allows the portion of the memory region dedicated to the file's contents
2.70 +to be extended.
2.71 +
2.72 +== Libraries ==
2.73 +
2.74 +The filesystem client library offers abstractions and a number of layers of
2.75 +functionality to support interaction with components and the provision of
2.76 +higher-level mechanisms and abstractions for file access.
2.77 +
2.78 +=== Client Library ===
2.79 +
2.80 +The client library provides functions somewhat resembling the traditional C
2.81 +library and low-level Unix interfaces for file access, and these functions are
2.82 +intended to support such traditional interfaces.
2.83 +
2.84 +Since files are accessed using file references, the `file_t` data structure is
2.85 +used to wrap such references and other relevant state. Thus, such structures
2.86 +can be broadly regarded as similar to the traditional `FILE` data structure.
2.87 +
2.88 +Files are opened and closed using the following functions:
2.89 +
2.90 +{{{
2.91 +file_t *client_open(const char *name, flags_t flags);
2.92 +void client_close(file_t *file);
2.93 +}}}
2.94 +
2.95 +Reading and writing files involves functions resembling the traditional
2.96 +low-level `read` and `write` functions:
2.97 +
2.98 +{{{
2.99 +offset_t client_read(file_t *file, void *buf, offset_t count);
2.100 +offset_t client_write(file_t *file, const void *buf, offset_t count);
2.101 +}}}
2.102 +
2.103 +Support for navigation in files is provided using functions resembling the
2.104 +traditional higher-level `fseek` and `ftell` functions:
2.105 +
2.106 +{{{
2.107 +offset_t client_seek(file_t *file, offset_t offset, int whence);
2.108 +long client_tell(file_t *file);
2.109 +}}}
2.110 +
2.111 +Although the client library (and the provision of files) employs mapped
2.112 +memory, a function can be used to explicitly reference memory for file access:
2.113 +
2.114 +{{{
2.115 +void *client_mmap(file_t *file, offset_t position, offset_t length);
2.116 +}}}
2.117 +
2.118 +For synchronisation purposes, either with the filesystem itself or with other
2.119 +users of the filesystem, a function resembling the traditional `fflush`
2.120 +function is provided:
2.121 +
2.122 +{{{
2.123 +long client_flush(file_t *file);
2.124 +}}}
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/wiki/Filesystems Fri Jul 16 00:40:22 2021 +0200
3.3 @@ -0,0 +1,8 @@
3.4 += Filesystems =
3.5 +
3.6 +This distribution aims to provide components and libraries to implement and
3.7 +deliver filesystem access in the L4 Runtime Environment.
3.8 +
3.9 +== Topics ==
3.10 +
3.11 + * [[Files]]