[docs][objects] Re-organize kernel object documentation

Also add some stub entries for previously undocumented stuff

Change-Id: I0ac90ac5753a691a2b155d308de89c92e49ada5d

docs/index.md

@@ -7,8 +7,8 @@ This page is a non-comprehensive index of the magenta documentation.
 + [Getting Started](getting_started.md)
 + [Relationship with LK](mg_and_lk.md)
 + [Kernel Objects](kernel_objects.md)
-    + [Process Objects](process_object.md)
-    + [Thread Objects](thread_object.md)
+    + [Process Objects](objects/process.md)
+    + [Thread Objects](objects/thread.md)
 + [Handles](handles.md)
 + [Futexes](futex.md)
 + [System Calls](syscalls.md)

docs/kernel_objects.md

@@ -7,13 +7,12 @@ with OS resources via object handles which map kernel objects to processes.
 
 ## Kernel objects in progress
 
-+ [Process](process_object.md)
-+ [Thread](thread_object.md)
-+ Event
-+ Message pipe
-+ Interrupt request
-+ Futex
-+ VMObject
++ [Process](objects/process.md)
++ [Thread](objects/thread.md)
++ [Event](objects/event.md)
++ [Message pipe](objects/message_pipe.md)
++ [Interrupt request](objects/interrupt_request.md)
++ [VMObject](objects/vm_object.md)
 
 ## Kernel objects planned
 

docs/objects/event.md

@@ -0,0 +1,13 @@
+# Event Object
+
+## NAME
+
+event - Signalable event for concurrent programming
+
+## SYNOPSIS
+
+TODO
+
+## DESCRIPTION
+
+TODO

docs/objects/interrupt_request.md

@@ -0,0 +1,13 @@
+# Interrupt Request Object
+
+## NAME
+
+interrupt\_request - Usermode I/O interrupt delivery
+
+## SYNOPSIS
+
+TODO
+
+## DESCRIPTION
+
+TODO

docs/objects/message_pipe.md

@@ -0,0 +1,18 @@
+# Message Pipe Object
+
+## NAME
+
+message\_pipe - Bidirectional interprocess communication
+
+## SYNOPSIS
+
+TODO
+
+## DESCRIPTION
+
+TODO
+
+## SEE ALSO
+
+[message_read](../syscalls/message_read.md),
+[message_write](../syscalls/message_write.md).

docs/process_object.md → docs/objects/process.md

@@ -1,20 +1,32 @@
 # Process Object
-The process object, just like on other OSes is a container of the following
-resources:
+
+## NAME
+
+process - Process abstraction
+
+## SYNOPSIS
+
+TODO
+
+## DESCRIPTION
+
+The process object is a container of the following resources:
 
 + Handle table
 + Memory regions
-+ [Threads](thread_object.md)
++ [Threads](thread.md)
 
-In general it operates more or less like a Linux or Windows process in
-terms of being it associated with code (one or more ELF binaries) which it
-is executing until it is forcefully terminated or the program exits.
+In general, it is associated with code which it is executing until it is
+forcefully terminated or the program exits.
 
-## Lifetime
+### Lifetime
 A process is created via `sys_process_create()` which take no parameters.
 The process starts destruction when main thread terminates or the last handle
 is closed. [⚠ not implemented].
 
 Next, the main binary is loaded into the process via `sys_process_load()` and
 its execution begins with `sys_process_start()`.
 
+## SEE ALSO
+
+TODO (add links to process syscall docs)

docs/objects/thread.md

@@ -0,0 +1,29 @@
+# Thread Object
+
+## NAME
+
+thread - Thread abstraction
+
+## SYNOPSIS
+
+TODO
+
+## DESCRIPTION
+
+The thread object is the construct that represents a time-shared CPU execution
+context. Thread objects live associated to a particular
+[Process Object](process.md) which provides the memory and the handles to other
+objects necessary for I/O and computation.
+
+### Lifetime
+A thread can be created implicitly by calling `sys_process_start()`, in which
+case the new thread is the "main thread" and the thread entrypoint is defined by
+the previously loaded binary. Or it can be created by calling
+`sys_thread_create()` which takes the entrypoint as a parameter.
+
+A thread terminates when it `return`s from executing the routine specified as
+the entrypoint or by calling `sys_thread_exit()`.
+
+## SEE ALSO
+
+TODO (add links to thread syscall docs)

docs/objects/vm_object.md

@@ -0,0 +1,18 @@
+# Virtual Memory Object
+
+## NAME
+
+vm\_object - Virtual memory containers
+
+## SYNOPSIS
+
+A Virtual Memory Object (VMO) represents a contiguous region of virtual memory
+that may be mapped into multiple address spaces.
+
+## DESCRIPTION
+
+TODO
+
+## SEE ALSO
+
+TODO (add links to vmo syscalls)