# HG changeset patch # User Paul Boddie # Date 1668989988 -3600 # Node ID d431ace6aeaf9f41d0babef5dd4a85cb395cdbec # Parent 8929c3922e962eb61269907b1993254119125cb3 Added header file descriptions and a script to generate them. diff -r 8929c3922e96 -r d431ace6aeaf docs/tools/make_table.sh --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/tools/make_table.sh Mon Nov 21 01:19:48 2022 +0100 @@ -0,0 +1,63 @@ +#!/bin/sh + +# Generate a Moin syntax table for header file documentation. + +DN=$1 + +if [ ! -e "$DN" ] ; then + cat 1>&2 < + +Obtain header file details from within a given include directory. +EOF + exit 1 +fi + +# Obtain the description from the top of a file. + +get_description() +{ + ENDLINE=$(grep -n -m 1 '^ \*$' "$1" | cut -f 1 -d :) + head -n "$ENDLINE" "$1" | tail -n +2 | head -n -1 | sed 's/^ \* //' | concat_lines +} + +# Concatenate lines. + +concat_lines() +{ + while read LINE ; do + echo -n "$LINE " + done +} + +# Format a table of header filenames and descriptions. + +make_table() +{ + for FN in "$1/"*"/"*".h" ; do + + # Detect non-matching patterns. + + if [ ! -e "$FN" ] ; then + break + + # Emit the header at the start. + + elif [ ! "$HEADER" ] ; then + echo "|| '''Header File''' §|| '''Contents''' §||" + HEADER=1 + fi + + PARENT=$(dirname "$FN") + SECTION=$(basename "$PARENT") + FILENAME=$(basename "$FN") + + echo -n '|| `'"$SECTION/$FILENAME"'` §|| ' + get_description "$FN" + echo ' §||' + done +} + +make_table "$DN" | column -s '§' -t + +# vim: tabstop=4 expandtab shiftwidth=4 diff -r 8929c3922e96 -r d431ace6aeaf docs/wiki/Libraries --- a/docs/wiki/Libraries Sat Oct 29 01:19:48 2022 +0200 +++ b/docs/wiki/Libraries Mon Nov 21 01:19:48 2022 +0100 @@ -10,16 +10,38 @@ Convenience functions for `libext2fs` operations. +|| '''Header File''' || '''Contents''' || +|| `e2access/access.h` || Access control functions || +|| `e2access/format.h` || File metadata formatting || +|| `e2access/image.h` || Filesystem image access functions || +|| `e2access/path.h` || Path functions || +|| `e2access/utils.h` || Common utilities for filesystem users || + == libe2access_blockserver == A convenience wrapper around `libext2fs`, providing initialisation functions for the opening of filesystems and for indicating the capability through which a block server, this providing a filesystem, may be accessed. +|| '''Header File''' || '''Contents''' || +|| `e2access/fs.h` || Filesystem opening functions || + == libexec == Support for initialising and executing programs in new tasks. +|| '''Header File''' || '''Contents''' || +|| `exec/common.h` || Common structures and functions || +|| `exec/elf.h` || ELF payload decoding support || +|| `exec/external_pager.h` || A system pager implementation residing in a separate task || +|| `exec/internal_pager.h` || A system pager implementation residing in the same task as a program || +|| `exec/mapped_region.h` || Mapped memory region support || +|| `exec/memory.h` || Program memory initialisation support || +|| `exec/pager.h` || Common system pager functionality || +|| `exec/process.h` || Support for initialising programs in new tasks and threads || +|| `exec/segment.h` || Program memory segment support || +|| `exec/stack.h` || Stack support for new tasks and threads || + == libext2fs == The ext2 filesystem library provided by the @@ -35,20 +57,106 @@ The [[Client Library|client library]] for accessing filesystem servers. +|| '''Header File''' || '''Contents''' || +|| `fsclient/client.h` || Filesystem client functions || +|| `fsclient/file.h` || File access convenience functions and types || +|| `fsclient/notifier.h` || File event notification support || + == libfsserver == The [[Server Library|server library]] providing supporting abstractions and functionality for filesystem-related [[Components|components]]. +|| '''Header File''' || '''Contents''' || +|| `fsserver/access_map.h` || An access map providing memory corresponding to file regions. || +|| `fsserver/accessor.h` || Generic accessor functionality. || +|| `fsserver/accountable.h` || Accountable object support. || +|| `fsserver/block_file_accessor.h` || A file accessor employing a rewritable memory area. || +|| `fsserver/block_file_opener.h` || An opener for a file employing a rewritable memory area. || +|| `fsserver/copied_page_mapper.h` || A page mapper providing copied memory pages or deferring to another page mapper to satisfy file accesses. || +|| `fsserver/directory_accessor.h` || An object providing access to a filesystem directory. || +|| `fsserver/directory_provider.h` || An object providing a directory abstraction with notification facilities. || +|| `fsserver/directory_resource.h` || A resource offering support for directory operations. || +|| `fsserver/ext2_directory_accessor.h` || An object for a directory provided by an Ext2-compatible filesystem. || +|| `fsserver/ext2_file_accessor.h` || A file accessor employing a file provided by an Ext2-compatible filesystem. || +|| `fsserver/ext2_file_opener.h` || An opener for a file provided by an Ext2-compatible filesystem. || +|| `fsserver/ext2_file_operations.h` || File operations supporting an Ext2-compatible filesystem. || +|| `fsserver/ext2_filesystem.h` || A resource supporting the creation of user-specific ext2 filesystem opener resources. || +|| `fsserver/file_opening.h` || Generic support for opening files. || +|| `fsserver/file_pager.h` || File-specific pager functionality. || +|| `fsserver/file_provider.h` || An object encapsulating file resources. || +|| `fsserver/filesystem_resource.h` || A resource supporting the creation of user-specific opener resources. || +|| `fsserver/generic_page_mapper.h` || A generic page mapper providing memory pages to satisfy file accesses. || +|| `fsserver/host_directory_accessor.h` || An object for a "host" directory provided via the C library. || +|| `fsserver/host_file_accessor.h` || A file accessor employing a "host" file provided via the C library. || +|| `fsserver/host_file_opener.h` || An opener for a "host" file provided via the C library. || +|| `fsserver/ipc.h` || Interprocess communication utilities. || +|| `fsserver/masked_page_mapper.h` || A page mapper providing memory pages to satisfy file accesses, masking the limits of a visible region of the file's contents. || +|| `fsserver/notification.h` || Notification support. || +|| `fsserver/opener_context_resource.h` || A context resource offering support for opening files. || +|| `fsserver/opener_resource.h` || A resource offering support for creating contexts and opening files. || +|| `fsserver/page_mapper.h` || A page mapper providing memory pages to satisfy file accesses. || +|| `fsserver/page_owner.h` || A page owner abstraction, indicating the current user of a memory region. || +|| `fsserver/page_queue.h` || A page queue abstraction. || +|| `fsserver/page_queue_partitioned.h` || A page queue retaining two internal collections of memory pages. || +|| `fsserver/page_queue_shared.h` || A page queue whose users take turns to access pages. || +|| `fsserver/pager.h` || Generic pager functionality. || +|| `fsserver/pages.h` || A page collection abstraction providing pages from a queue to users. || +|| `fsserver/pipe_accessor.h` || A pipe accessor merely resetting allocated memory for use. || +|| `fsserver/pipe_opener_resource.h` || A pipe opener resource. || +|| `fsserver/pipe_pager.h` || A pipe pager providing access to pipe content and navigation support. || +|| `fsserver/pipe_paging.h` || A pipe paging coordinator, permitting memory sharing pipe endpoints. || +|| `fsserver/provider.h` || Filesystem object provider support. || +|| `fsserver/provider_registry.h` || A registry of filesystem object providers. || +|| `fsserver/resource.h` || Common resource classes and functions. || +|| `fsserver/resource_registry.h` || A registry of filesystem object resources. || +|| `fsserver/resource_server.h` || Common resource server functions. || +|| `fsserver/simple_pager.h` || A simple pager exposing a single memory region. || +|| `fsserver/test_file_accessor.h` || A test accessor producing generated content. || +|| `fsserver/test_file_opener.h` || An opener for a test file containing generated content. || + == libipc == A library providing IPC (interprocess communication) mechanisms to support communication and interactions between components. +|| '''Header File''' || '''Contents''' || +|| `ipc/cap_alloc.h` || Capability allocation and management || +|| `ipc/direct.h` || Interprocess communication operations || +|| `ipc/factory.h` || Factory-related data types || +|| `ipc/irq.h` || Interrupt request handling || +|| `ipc/macros_ipc.h` || Interprocess communication macros || +|| `ipc/map.h` || Capability mapping between tasks || +|| `ipc/mem_ipc.h` || Memory sharing abstractions || +|| `ipc/message.h` || Interprocess communication message abstraction || +|| `ipc/semaphore.h` || Semaphore utilities || +|| `ipc/server.h` || Server binding/registration || +|| `ipc/thread.h` || Thread-related initialisation || +|| `ipc/util_ipc.h` || Interprocess communication abstractions || + == libmem == A library providing memory-related abstractions and utilities. +|| '''Header File''' || '''Contents''' || +|| `mem/flexpage.h` || A flexpage abstraction || +|| `mem/memory.h` || A generic memory pool abstraction || +|| `mem/memory_incremental.h` || A memory pool allocating a region at a time from the system || +|| `mem/memory_preallocated.h` || A memory pool providing regions from a preallocated amount of memory || +|| `mem/memory_utils.h` || Memory quantity calculation utilities || +|| `mem/region.h` || Memory region abstractions || +|| `mem/send_flexpage.h` || A "send" flexpage abstraction for communicating memory mappings || +|| `mem/types.h` || Miscellaneous types || + == libsystypes == A repository of fundamental types used by the other libraries. + +|| '''Header File''' || '''Contents''' || +|| `systypes/base.h` || Base types used by various other types || +|| `systypes/factory.h` || Factory-related data type macros || +|| `systypes/fcntl.h` || File control definitions || +|| `systypes/format.h` || Format specifiers for output || +|| `systypes/stat.h` || File metadata abstractions || +|| `systypes/timespec.h` || Time-related types || +|| `systypes/user.h` || User abstractions ||