doc/cenv(9): describe the C environment of the kernel

4 files changed, 108 insertions, 7 deletions

diff --git a/doc/Makefrag.am b/doc/Makefrag.am
index 86c468c9..4f9083d9 100644
--- a/doc/Makefrag.am
+++ b/doc/Makefrag.am
@@ -1,6 +1,7 @@
 EXTRA_DIST += doc/asciidoc.conf
 
 x15_DOCS =                                                  \
+        doc/cenv.9.txt                                      \
         doc/init.9.txt                                      \
         doc/intro.9.txt                                     \
         doc/style.9.txt
diff --git a/doc/asciidoc.conf b/doc/asciidoc.conf
index a413768e..6e0874ca 100644
--- a/doc/asciidoc.conf
+++ b/doc/asciidoc.conf
@@ -9,6 +9,7 @@ the-art-of-unix-programming=http://www.catb.org/esr/writings/taoup/html/[The Art
 (?su)(?P<name>module_mutex):(?P<impl>\w+)=
 (?su)(?P<name>module):(?P<component>\w+)/(?P<module>\w+)=
 (?su)(?P<name>manpage):(?P<page>\w+)=
+(?su)(?P<name>cheader):(?P<header>\w+)=
 (?su)(?P<name>cfunction):(?P<function>\w+)=
 (?su)(?P<name>cmacro):(?P<macro>\w+)=
 (?su)(?P<name>shell):{(?P<command>[^}]+)}=
@@ -37,6 +38,14 @@ ifdef::basebackend-docbook[]
 <ulink url="{page}.9.html"><emphasis role="bold">{page}</emphasis>(9)</ulink>
 endif::basebackend-docbook[]
 
+[cheader-inlinemacro]
+ifdef::basebackend-html[]
+&lt;{header}.h&gt;
+endif::basebackend-html[]
+ifdef::basebackend-docbook[]
+&lt;{header}.h>
+endif::basebackend-docbook[]
+
 [cfunction-inlinemacro]
 ifdef::basebackend-html[]
 <i>{function}()</i>
diff --git a/doc/cenv.9.txt b/doc/cenv.9.txt
new file mode 100644
index 00000000..693d813f
--- /dev/null
+++ b/doc/cenv.9.txt
@@ -0,0 +1,93 @@
+CENV(9)
+========
+:doctype:       manpage
+:man source:    X15
+:man manual:    X15 C environment
+
+NAME
+----
+
+cenv - C environment
+
+DESCRIPTION
+-----------
+
+This document describes the C environment of the kernel, including
+available standard headers and interfaces.
+
+Standard
+~~~~~~~~
+
+X15 must be built with a C compiler supporting the ISO/IEC 9899:2011
+(C11) specification with some GCC extensions. It can currently be built
+with the GCC and Clang compilers.
+
+Environment
+~~~~~~~~~~~
+
+The kernel uses the freestanding execution environment. This means the
+compiler is expected to provide the following headers :
+
+** cheader:float
+** cheader:iso646
+** cheader:limits
+** cheader:stdalign
+** cheader:stdarg
+** cheader:stdbool
+** cheader:stddef
+** cheader:stdint
+** cheader:stdnoreturn
+
+X15 augments the environment with a small subset of the functions provided
+in hosted environments. The additional headers are :
+
+** cheader:assert
+** cheader:limits
+** cheader:stdio
+** cheader:string
+
+Note that these headers do not provide the complete set of interfaces
+expected in a hosted environment.
+
+Formatting functions
+~~~~~~~~~~~~~~~~~~~~
+
+Of particular interest is the cheader:stdio header which provides a subset
+of the printf and scanf family of functions.
+
+The supported functions are :
+
+** cfunction:getchar
+** cfunction:putchar
+** cfunction:sprintf
+** cfunction:snprintf
+** cfunction:vsprintf
+** cfunction:vsnprintf
+** cfunction:sscanf
+** cfunction:vsscanf
+
+The *EOF* macro is also provided.
+
+The formatting functions only implement a subset of what the standard
+defines, namely :
+
+** cfunction:sprintf :
+*** flags: # 0 - ' ' (space) +
+*** field width is supported
+*** precision is supported
+** cfunction:sscanf :
+*** flags: *
+*** field width is supported
+** common to both :
+*** modifiers: hh h l ll z t
+*** specifiers: d i o u x X c s p n %
+
+Floating point conversions are currently not supported, but this may change
+in the future.
+
+SEE
+---
+
+manpage:intro
+
+{x15-operating-system}
diff --git a/doc/intro.9.txt b/doc/intro.9.txt
index 903be63d..e023d86b 100644
--- a/doc/intro.9.txt
+++ b/doc/intro.9.txt
@@ -151,16 +151,12 @@ module:kern/list::
   Doubly-linked list.
 module:kern/macros::
   Useful generic macros.
-module:kern/printf::
-  Formatted output functions.
 module:kern/rbtree::
   Red-black tree.
 module:kern/rdxtree::
   Radix tree (with integer keys).
 module:kern/slist::
   Singly-linked list.
-module:kern/sprintf::
-  Formatted string functions.
 module:kern/syscnt::
   Generic 64-bits counter.
 module:kern/timer::
@@ -171,8 +167,8 @@ often vary too much. Similarly, it doesn't provide a hash table interface.
 Instead, users can easily build specialized queues, hash tables and ring
 buffers on top of the provided facilities.
 
-TODO List supported standard C interfaces and remove the printf/sprintf
-modules from the list above.
+See manpage:cenv for information about the subset of standard C interfaces
+supported.
 
 [[multiprocessor_support]]
 MULTIPROCESSOR SUPPORT
@@ -272,8 +268,10 @@ the future.
 SEE
 ---
 
-manpage:style
+manpage:cenv
 
 manpage:init
 
+manpage:style
+
 {x15-operating-system}