# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1560264563 -7200
# Node ID 82a63936a118754c8862e2d6cac2c9247b04b197
# Parent  a7af613384c71ee16d5c9bd858635c255b79e4e3
Added initial library documentation.

diff -r a7af613384c7 -r 82a63936a118 docs/wiki/CommonPIC32
--- a/docs/wiki/CommonPIC32	Mon May 20 23:34:28 2019 +0200
+++ b/docs/wiki/CommonPIC32	Tue Jun 11 16:49:23 2019 +0200
@@ -7,4 +7,5 @@
 == Documentation ==
 
  * [[Examples]]
+ * [[Library]]
  * [[VGA Signal Output]]
diff -r a7af613384c7 -r 82a63936a118 docs/wiki/Library
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Library	Tue Jun 11 16:49:23 2019 +0200
@@ -0,0 +1,10 @@
+= Library =
+
+Software developed using the CommonPIC32 distribution, such as the [[Examples|
+examples]] provided in the distribution, relies on the library functionality
+found in the `lib` directory.
+
+ `cpu.S`     :: [[/cpu|Low-Level CPU Routines]]
+ `init.c`    :: [[/init|Initialisation Routines]]
+ `payload.c` :: [[/payload|Payload Initialisation]]
+ `start.S`   ::  [[/start|Payload Start Routine]]
diff -r a7af613384c7 -r 82a63936a118 docs/wiki/Library--cpu
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Library--cpu	Tue Jun 11 16:49:23 2019 +0200
@@ -0,0 +1,33 @@
+= Low-Level CPU Routines =
+
+The `lib/cpu.S` file contains low-level routines for handling specific
+conditions related to the operation of the CPU:
+
+ `init_interrupts`   :: Configures the location of exception and interrupt
+                        vectors.
+
+ `enable_interrupts` :: Enables the delivery of interrupts to the configured
+                        non-bootloader vectors.
+
+ `handle_error_level`:: Handles the initial state of the CPU, making exception
+                        and interrupt conditions possible.
+
+These routines are called in an appropriate order in the general [[../init|
+initialisation]] code.
+
+To support exceptions and interrupts, the following routines are defined in
+the `.vectors' section of the payload:
+
+ `ebase`       :: Handles TLB exceptions, jumping to the general exception
+                  handler. The PIC32 products tested with this software do not
+                  provide hardware that should raise such exceptions, however.
+
+ `exc_handler` :: Handles exception conditions, switching to a dedicated stack
+                  and jumping to the `exception_handler` routine defined by an
+                  application.
+
+ `int_handler` :: Handles interrupt conditions, switching to a dedicated
+                  stack, saving register values, jumping to the
+                  `interrupt_handler` routine defined by an application, then
+                  restoring register values, switching back to the application
+                  stack and returning to the interrupted code.
diff -r a7af613384c7 -r 82a63936a118 docs/wiki/Library--init
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Library--init	Tue Jun 11 16:49:23 2019 +0200
@@ -0,0 +1,5 @@
+= Initialisation Routines =
+
+Above the lowest level code written in assembly language, a selection of
+C language routines is provided for performing other essential initialisation
+tasks. These are found in the `lib/init.c` file.
diff -r a7af613384c7 -r 82a63936a118 docs/wiki/Library--payload
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Library--payload	Tue Jun 11 16:49:23 2019 +0200
@@ -0,0 +1,14 @@
+= Payload Initialisation =
+
+The `lib/payload.c` file contains routines for completing the basic
+initialisation of a payload before any application main program can be
+invoked. These routines are called by the [[../start|start-up]] routine but
+are implemented in C for convenience.
+
+ `init_bss` :: Initialises the `.bss` section of the payload so that
+               uninitialised global and static variables have a well-defined
+               initial value of zero.
+
+ `relocate_data` :: Copies the contents of the payload's `.data` section to
+                    writable memory so that mutable data structures can be
+                    modified.
diff -r a7af613384c7 -r 82a63936a118 docs/wiki/Library--start
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/wiki/Library--start	Tue Jun 11 16:49:23 2019 +0200
@@ -0,0 +1,16 @@
+= Payload Start Routine =
+
+The `lib/start.S` file contains the start-up routine for a deployed payload.
+Its responsibilities are as follows:
+
+ 1. To enable caching, if available.
+ 1. To initialise a kernel stack for privileged routines to use.
+ 1. To set up the globals pointer so that symbols can be looked up.
+ 1. To [[../payload|initialise payload data]].
+ 1. To enter the main program of the payload.
+
+The start-up routine is positioned in the `.boot` section of the payload.
+
+Alongside the start-up routine are definitions of device configuration
+registers: `.devcfg0`, `.devcfg1` and `.devcfg2`. The actual values set for
+these registers should be defined in an application's `devconfig.h` file.