doc: document object layout and definitions

doc/objects.rst

@@ -0,0 +1,120 @@
+=================
+THE OBJECT SYSTEM
+=================
+
+Objects are the primary means of managing and controlling access to
+user-facing resources a uniform way. This document provides an
+overview of the object system in the Socks kernel, including:
+
+1. Object Layout and Definition.
+2. The Object Lifecycle.
+3. Object Operations and Conventions.
+4. References and Handles.
+5. Attributes.
+
+
+Object Layout and Definition
+============================
+
+An object is made up of two distinct halves: the **header** and the
+**data**. The header contains bookkeeping data used by the object
+system, while the data is the programmer-defined part of the object,
+and can be used however the object-creator wants.
+
+Object behaviour is defined by an `object_type_t` instance.
+An `object_type_t` provides the object system with all the information
+it needs to instantiate and interact with your objects.
+
+
+The Object Header
+-----------------
+
+The object header is defined in `include/socks/object.h` as `object_t`.
+It contains information that is used by the object system, and typically
+should not be directly accessed outside of the object system.
+
+The contents of the object header include:
+
+* `ob_magic`: A magic value used to identify active objects.
+  Functions that retrieve an object's header from its data (and vice versa)
+  do not have type checking (i.e. they convert between `object_t *` and `void *`
+  using simple pointer arithmetic), so checking for this magic number helps
+  protect against non-objects being passed to functions expecting objects.
+* `ob_type`: A pointer to the `object_type_t` that was used to create the
+  object. Outside of the object system, this can be used as a read-only
+  way to query type information about an object.
+* `ob_lock`: A general-purpose per-object lock. This lock is *not* reserved
+  for the object system to use, and can be used by the programmer. You
+  can lock and unlock an object by using `object_lock()` and `object_unlock()`
+  respectively.
+* `ob_refcount` and `ob_handles`: The number of kernel references and open
+  handles to an object. See :ref:`References and Handles` for more details.
+* `ob_attrib`: A list of attributes that are accessible for this object.
+  See :ref:`Attributes` for more details.
+* `ob_list`: A general-purpose queue entry for adding the object to a linked
+  list. Note that some internal object types (such as `set`) make use of this
+  queue entry.
+
+
+The Object Data
+---------------
+
+The object data section is the programmer-defined part of the object, and
+can be used for any purpose, although it is typically used as storage space
+for a C structure. For example the data section of a `task` object is used
+to store an instance of a `task_t` C structure containing the task data.
+
+The object header and data are allocated together in a single contiguous
+chunk, with the data coming after the header. **However**, you should
+interactive with the object as if you don't know this. The only safe
+way to convert between an object header pointer and data pointer is to
+use the `object_header()` and `object_data()` functions respectively.
+
+The object data pointer is guaranteed to be aligned on a `long` boundary.
+
+
+The Object Type
+---------------
+
+The object type defines the name, size, and behaviour of an object.
+It is defined using the `object_type_t` C structure.
+
+Some notable parts of `object_type_t` include:
+
+* `ob_name`: Human-readable name of the object type. For example:
+  "namespace", "set", "task", etc.
+* `ob_size`: The length of the data section of the object in bytes.
+* `ob_cache`: An instance of `vm_cache_t` from which objects of this
+  type are allocated. This cache is initialised and managed by the
+  object system on behalf of the programmer, so this can be ignored
+  outside of the object system.
+* `ob_list`: A queue entry used internally by the object system.
+* `ob_attrib`: A list of object attributes defined for objects of
+  this type.
+* `ob_ops`: A set of function pointers that are used by the object
+  system to interact with the object. See
+  :ref:`Object Operations and Conventions` for more details.
+
+
+The Object Lifecycle
+====================
+
+TODO
+
+
+Object Operations and Conventions
+=================================
+
+TODO
+
+
+References and Handles
+======================
+
+TODO
+
+
+Attributes
+==========
+
+TODO