Add python-sphinx docs

20 files changed, 211 insertions, 43 deletions

diff --git a/.gitignore b/.gitignore
index 2ca6696..b2847d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,4 @@ isodir
 src/conf.h
 .config.old
 test_*
+doc
diff --git a/Makefile b/Makefile
index d3d8968..ca2f48d 100644
--- a/Makefile
+++ b/Makefile
@@ -3,9 +3,12 @@ MAKEFLAGS += --no-print-directory
 
 include Makefile.config
 
-.PHONY: all run clean test FORCE
+.PHONY: all doc run clean test FORCE
 all: glitch.elf
 
+doc: FORCE
+	sphinx-build -b html doc.src doc
+
 run: glitch.iso
 	@qemu-system-i386 -cdrom glitch.iso -accel kvm -d cpu_reset -display gtk,zoom-to-fit=on
 
diff --git a/README.md b/README.md
index b159313..2886d54 100644
--- a/README.md
+++ b/README.md
@@ -4,19 +4,27 @@
 - uart: 16550 (write)
 - vga text mode
 - pic: 8259
-
+- ps2 controller: i8042, with keyboard and mouse
 
 ## building
+prerequisites:
+* i686-elf-gcc, i686-elf-binutils
+* for bootable iso image: grub, mtools
+* to run: qemu-system-i386
+
 ```sh
-meson setup --cross-file=arch/i686/toolchain.ini build
+make glitch.elf # to build the kernel
+make glitch.iso # to build bootable CD image
+make run        # to run it with qemu
 ```
 
-## code coverage
+## documentation
+prerequisites: sphinx, sphinx-hawkmoth
+
 ```sh
-ninja test
-ninja coverage-html
+make doc
 ```
 
 # musl
-- arch/i686/include/sys/io.h
+- i686/include/sys/io.h
 - lib/string/itoa.c
diff --git a/devices/vga.h b/devices/vga.h
index 7a295a2..daaa482 100644
--- a/devices/vga.h
+++ b/devices/vga.h
@@ -1,6 +1,6 @@
 #pragma once
 
-/* Hardware text mode color constants. */
+/** Hardware text mode color constants. */
 enum vga_color {
   VGA_COLOR_BLACK = 0,
   VGA_COLOR_BLUE = 1,
diff --git a/doc.src/arch.rst b/doc.src/arch.rst
new file mode 100644
index 0000000..44bc9e7
--- /dev/null
+++ b/doc.src/arch.rst
@@ -0,0 +1,14 @@
+=============
+Architectures
+=============
+
+i686
+====
+Supported are CPUs with PSE (Page Size Extentions)
+
+Building for i686
+-----------------
+Requirements:
+
+* i686-elf-gcc `gcc-PKGBUILD <https://neueland.iserlohn-fortress.net/cgit/glitch/i686-elf-gcc/>`_
+* i686-elf-binutils `binutils-PKGBUILD <https://neueland.iserlohn-fortress.net/cgit/glitch/i686-elf-binutils/>`_
diff --git a/doc.src/conf.py b/doc.src/conf.py
new file mode 100644
index 0000000..02bd18c
--- /dev/null
+++ b/doc.src/conf.py
@@ -0,0 +1,28 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'glitch'
+copyright = '2022, aqua@'
+author = 'aqua@'
+release = '0.0.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['hawkmoth']
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ['_static']
diff --git a/doc.src/devices.rst b/doc.src/devices.rst
new file mode 100644
index 0000000..7c8b41d
--- /dev/null
+++ b/doc.src/devices.rst
@@ -0,0 +1,33 @@
+=======
+Devices
+=======
+
+VGA
+===
+
+Text mode
+---------
+osdev wiki: `Text UI <https://wiki.osdev.org/Text_mode>`_
+
+.. c:autodoc:: ../devices/vga.h
+
+PS/2 Controller
+===============
+.. c:autodoc:: ../devices/ps2_controller.h
+
+Keyboard
+--------
+.. c:autodoc:: ../devices/keyboard.h
+
+Mouse
+-----
+.. c:autodoc:: ../devices/mouse.h
+
+Programmable Interrupt Controller
+=================================
+.. c:autodoc:: ../devices/pic.h
+
+UART
+====
+.. c:autodoc:: ../devices/uart_16550.h
+
diff --git a/doc.src/index.rst b/doc.src/index.rst
new file mode 100644
index 0000000..b62b1ad
--- /dev/null
+++ b/doc.src/index.rst
@@ -0,0 +1,23 @@
+.. glitch documentation master file, created by
+   sphinx-quickstart on Mon Nov  7 17:29:02 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the glitch documentation
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   arch
+   libk
+   devices
+   mem
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/doc.src/libk.rst b/doc.src/libk.rst
new file mode 100644
index 0000000..7c30f41
--- /dev/null
+++ b/doc.src/libk.rst
@@ -0,0 +1,17 @@
+====
+libk
+====
+
+libk is the kernel's C standard library implementation.
+
+stdio.h
+=======
+.. c:autodoc:: ../lib/stdio.h
+
+stdlib.h
+========
+.. c:autodoc:: ../lib/stdlib.h
+
+string.h
+========
+.. c:autodoc:: ../lib/string.h
diff --git a/doc.src/mem.rst b/doc.src/mem.rst
new file mode 100644
index 0000000..2dd86a9
--- /dev/null
+++ b/doc.src/mem.rst
@@ -0,0 +1,32 @@
+=================
+Memory management
+=================
+
+A frame is a fixed-sized block of physical memory. A page is a fixed-size block of virtual memory. Both are of the same size (4kB).
+
+Physical memory allocator
+=========================
+The FrameAllocator takes a bitmap describing available physical memory and allocates free frames. There is one global
+instance.
+
+Virtual memory allocator
+========================
+The PageAllocator takes allocated Frames and mounts them in virtual memory.
+
+.. table:: Virtual address space layout
+   :widths: auto
+
+   ============== ==================== ===========
+   address        symbol               description
+   ============== ==================== ===========
+   ``ffff ffff``                       virtual memory end
+   ``d000 0000``                       MMIO
+   ``c040 0000``                       kernel allocator
+   page-aligned   ``__data_begin``    
+   page-aligned   ``__bss_begin``     
+   page-aligned   ``__rodata_begin``  
+   ``c000 0000``  ``__text_begin``     kernel text
+   ``0000 0000``                       virtual memory start
+   ============== ==================== ===========
+
+.. include:: mem/constinit.rst
diff --git a/doc.src/mem/constinit.rst b/doc.src/mem/constinit.rst
new file mode 100644
index 0000000..7e069bf
--- /dev/null
+++ b/doc.src/mem/constinit.rst
@@ -0,0 +1,4 @@
+constinit section
+=================
+
+``constinit`` is a part of ``.rodata``
diff --git a/doc/style.md b/doc/style.md
deleted file mode 100644
index 28b712d..0000000
--- a/doc/style.md
+++ /dev/null
@@ -1,8 +0,0 @@
-## file headers
-```c
-//=====================================================================
-// <component name>
-// spdx-license-identifier: ISC
-// description:
-//=====================================================================
-```
diff --git a/lib/Makefile b/lib/Makefile
index dec0769..66181c8 100644
--- a/lib/Makefile
+++ b/lib/Makefile
@@ -2,11 +2,12 @@ include ../Makefile.config
 
 CCFLAGS += -I. -I..
 
-libk.SRCS = memcpy.c memset.c stdio/printf.c string/itoa.c
+libk.SRCS = stdio/printf.c \
+            stdlib/memcpy.c stdlib/memset.c \
+            string/itoa.c
 
 include ../rules.mk
 
 .PHONY: test
 test: tst/test_mem tst/test_string tst/test_linked_list_allocator
-	@echo $^
 	$(foreach f,$^,./$f;)
diff --git a/lib/memset.c b/lib/memset.c
deleted file mode 100644
index 670e4b6..0000000
--- a/lib/memset.c
+++ /dev/null
@@ -1,14 +0,0 @@
-/**
- * The memset() function fills the first n bytes of the memory area pointed to by s with the constant byte c.
- * @param s
- * @param c
- * @param n
- * @return
- */
-void *
-memset(void *s, int c, long unsigned n)
-{
-  char *pDest = (char *)s;
-  for (unsigned i = 0; i < n; ++i) pDest[i] = c;
-  return s;
-}
diff --git a/lib/stdlib.h b/lib/stdlib.h
index 6b8e09d..7f235f0 100644
--- a/lib/stdlib.h
+++ b/lib/stdlib.h
@@ -1,6 +1,21 @@
 #pragma once
 
-#include <stddef.h>
+/**
+ * Allocate size bytes and return a pointer to the allocated memory
+ */
+void *malloc(unsigned int size);
 
-void *malloc(size_t size);
+/**
+ * Free the memory space pointed to by ptr
+ */
 void free(void *ptr);
+
+/**
+ * Fill the first n bytes of the memory area pointed to by s with the constant byte c.
+ */
+void *memset(void *s, int c, long unsigned n);
+
+/**
+ * Copy n bytes from memory area src to memory area dest.  The memory areas must not overlap.
+ */
+void *memcpy(void *restrict dest, const void *restrict src, long unsigned n);
diff --git a/lib/memcpy.c b/lib/stdlib/memcpy.c
index 059738f..90470d5 100644
--- a/lib/memcpy.c
+++ b/lib/stdlib/memcpy.c
@@ -1,10 +1,3 @@
-/**
- * The  memcpy()  function copies n bytes from memory area src to memory area dest.  The memory areas must not overlap.
- * @param dest
- * @param src
- * @param n
- * @return
- */
 void *
 memcpy(void *restrict dest, const void *restrict src, long unsigned n)
 {
diff --git a/lib/stdlib/memset.c b/lib/stdlib/memset.c
new file mode 100644
index 0000000..ccd46dd
--- /dev/null
+++ b/lib/stdlib/memset.c
@@ -0,0 +1,7 @@
+void *
+memset(void *s, int c, long unsigned n)
+{
+  char *pDest = (char *)s;
+  for (unsigned i = 0; i < n; ++i) pDest[i] = c;
+  return s;
+}
diff --git a/lib/string.h b/lib/string.h
index 9873362..1eb3da2 100644
--- a/lib/string.h
+++ b/lib/string.h
@@ -1,4 +1,14 @@
 #pragma once
 
+#define OCTAL 8
+#define DECIMAL 10
+#define HEX 16
+
+/**
+ * Convert int into a string
+ */
 char *itoa(char *p, int x, int base);
+/**
+ * Convert unsigned int into a string
+ */
 char *utoa(char *p, unsigned x, int base);
diff --git a/lib/tst/mem.cc b/lib/tst/mem.cc
index b233da8..7586a97 100644
--- a/lib/tst/mem.cc
+++ b/lib/tst/mem.cc
@@ -3,8 +3,8 @@
 #define restrict __restrict__
 
 namespace libk {
-#include "../memcpy.c"
-#include "../memset.c"
+#include "../stdlib/memcpy.c"
+#include "../stdlib/memset.c"
 } // namespace libk
 
 TEST(mem, memset)
diff --git a/rules.mk b/rules.mk
index 24895fb..c64265d 100644
--- a/rules.mk
+++ b/rules.mk
@@ -32,5 +32,6 @@ tst/test_%: tst/%.cc
 .PHONY: clean FORCE
 clean:
 	@$(foreach V,$(filter %.OBJS, ${.VARIABLES}), rm -rf $($(V)))
+	@rm -rf tst/test_*
 
 FORCE: