4 files changed, 71 insertions, 0 deletions

diff --git a/documentation/kernel/applications.txt b/documentation/kernel/applications.txt
new file mode 100644
index 0000000..6890c96
--- /dev/null
+++ b/documentation/kernel/applications.txt
@@ -0,0 +1,41 @@
+globally there are:
+  an id-list of processes
+  an id-list of threads
+  a queue of paused threads
+  a single running thread
+
+a paused thread is a thread that can run, but isn't.
+a thread that is not running and is not paused is in a blocking syscall.
+
+each process has:
+  a process id
+  a list of threads
+  a list of open file streams
+  a list of open socket stream ends
+  a list of running socket listeners
+  a list of environment variables (pairs of strings)
+
+a thread has:
+  an owning process
+  optionally:
+    a stream end it is waiting to read from
+    a socket listener it is waiting to accept a connection from
+    a socket listener it is waiting to connect to
+  if not running:
+    saved cpu state
+
+a socket has:
+  two queues
+
+an open socket stream end has:
+  a list of threads waiting to read from it
+  the socket
+  its input queue
+  its output queue
+  if the other side is open:
+    the other process
+    the other stream end
+
+a running socket listener has:
+  a list of threads waiting to accept a connection from it
+  a list of threads waiting to connect to it
diff --git a/documentation/kernel/memory.txt b/documentation/kernel/memory.txt
new file mode 100644
index 0000000..3c0e4f4
--- /dev/null
+++ b/documentation/kernel/memory.txt
@@ -0,0 +1,15 @@
+only the first 32GiB of physical memory are considered. this can be changed
+with pram_pages in paging.cpp. vram layout is as follows:
+
+0x0000.0000.0000 - 0x0000.0000.0fff: always unmapped
+0x0000.0000.1000 - 0x003f.ffff.ffff: available to user process
+0x0040.0000.0000 - 0x007f.ffff.ffff: each 16MB:
+       0x00.0000 -        0x00.0fff: always unmapped
+       0x00.1000 -        0xff.ffff: available for user thread stack
+0x0080.0000.0000 - 0xffff.bfff.ffff: always unmapped
+0xffff.c000.0000 - 0xffff.ffdf.ffff: available to kernel
+0xffff.ffe0.0000 - 0xffff.ffe0.0fff: always unmapped
+0xffff.ffe0.1000 - 0xffff.ffef.efff: interrupt stack
+0xffff.ffef.f000 - 0xffff.fff0.0fff: always unmapped
+0xffff.fff0.1000 - 0xffff.ffff.efff: syscall stack / kernel init stack
+0xffff.ffff.f000 - 0xffff.ffff.ffff: always unmapped
diff --git a/documentation/kernel/panics.txt b/documentation/kernel/panics.txt
new file mode 100644
index 0000000..e1b6ec1
--- /dev/null
+++ b/documentation/kernel/panics.txt
@@ -0,0 +1,8 @@
+when the kernel panics, it fills the screen with a color indicating the type of
+panic. the following are the defined colors so far:
+  #48a6ed - failed to get root node of initfs
+  #5f8860 - no initfs module was given
+  #7e874d - failed to look up /bin/init
+  #9af5e6 - an unimplemented path in the kernel
+  #ba40bb - cpu exception occurred
+  #c39db3 - failed to parse /bin/init
diff --git a/documentation/kernel/storage.txt b/documentation/kernel/storage.txt
new file mode 100644
index 0000000..4fe8ea3
--- /dev/null
+++ b/documentation/kernel/storage.txt
@@ -0,0 +1,7 @@
+a block_device is a block device such as a disk or a partition that has been
+seen since the last boot. when a driver detects a device, it should check if
+a block_device with that id has already been created, and if so, reuse it.
+
+eventually, i would like to implement kernel-space exceptions and
+use those instead of having functions return bd_result or fs_result,
+since it's a bit unwieldy to propogate those results as is.