1.1 --- a/docs/wiki/CommonPIC32 Mon May 20 23:34:28 2019 +0200
1.2 +++ b/docs/wiki/CommonPIC32 Tue Jun 11 16:49:23 2019 +0200
1.3 @@ -7,4 +7,5 @@
1.4 == Documentation ==
1.5
1.6 * [[Examples]]
1.7 + * [[Library]]
1.8 * [[VGA Signal Output]]
2.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2 +++ b/docs/wiki/Library Tue Jun 11 16:49:23 2019 +0200
2.3 @@ -0,0 +1,10 @@
2.4 += Library =
2.5 +
2.6 +Software developed using the CommonPIC32 distribution, such as the [[Examples|
2.7 +examples]] provided in the distribution, relies on the library functionality
2.8 +found in the `lib` directory.
2.9 +
2.10 + `cpu.S` :: [[/cpu|Low-Level CPU Routines]]
2.11 + `init.c` :: [[/init|Initialisation Routines]]
2.12 + `payload.c` :: [[/payload|Payload Initialisation]]
2.13 + `start.S` :: [[/start|Payload Start Routine]]
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/wiki/Library--cpu Tue Jun 11 16:49:23 2019 +0200
3.3 @@ -0,0 +1,33 @@
3.4 += Low-Level CPU Routines =
3.5 +
3.6 +The `lib/cpu.S` file contains low-level routines for handling specific
3.7 +conditions related to the operation of the CPU:
3.8 +
3.9 + `init_interrupts` :: Configures the location of exception and interrupt
3.10 + vectors.
3.11 +
3.12 + `enable_interrupts` :: Enables the delivery of interrupts to the configured
3.13 + non-bootloader vectors.
3.14 +
3.15 + `handle_error_level`:: Handles the initial state of the CPU, making exception
3.16 + and interrupt conditions possible.
3.17 +
3.18 +These routines are called in an appropriate order in the general [[../init|
3.19 +initialisation]] code.
3.20 +
3.21 +To support exceptions and interrupts, the following routines are defined in
3.22 +the `.vectors' section of the payload:
3.23 +
3.24 + `ebase` :: Handles TLB exceptions, jumping to the general exception
3.25 + handler. The PIC32 products tested with this software do not
3.26 + provide hardware that should raise such exceptions, however.
3.27 +
3.28 + `exc_handler` :: Handles exception conditions, switching to a dedicated stack
3.29 + and jumping to the `exception_handler` routine defined by an
3.30 + application.
3.31 +
3.32 + `int_handler` :: Handles interrupt conditions, switching to a dedicated
3.33 + stack, saving register values, jumping to the
3.34 + `interrupt_handler` routine defined by an application, then
3.35 + restoring register values, switching back to the application
3.36 + stack and returning to the interrupted code.
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/wiki/Library--init Tue Jun 11 16:49:23 2019 +0200
4.3 @@ -0,0 +1,5 @@
4.4 += Initialisation Routines =
4.5 +
4.6 +Above the lowest level code written in assembly language, a selection of
4.7 +C language routines is provided for performing other essential initialisation
4.8 +tasks. These are found in the `lib/init.c` file.
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/wiki/Library--payload Tue Jun 11 16:49:23 2019 +0200
5.3 @@ -0,0 +1,14 @@
5.4 += Payload Initialisation =
5.5 +
5.6 +The `lib/payload.c` file contains routines for completing the basic
5.7 +initialisation of a payload before any application main program can be
5.8 +invoked. These routines are called by the [[../start|start-up]] routine but
5.9 +are implemented in C for convenience.
5.10 +
5.11 + `init_bss` :: Initialises the `.bss` section of the payload so that
5.12 + uninitialised global and static variables have a well-defined
5.13 + initial value of zero.
5.14 +
5.15 + `relocate_data` :: Copies the contents of the payload's `.data` section to
5.16 + writable memory so that mutable data structures can be
5.17 + modified.
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/wiki/Library--start Tue Jun 11 16:49:23 2019 +0200
6.3 @@ -0,0 +1,16 @@
6.4 += Payload Start Routine =
6.5 +
6.6 +The `lib/start.S` file contains the start-up routine for a deployed payload.
6.7 +Its responsibilities are as follows:
6.8 +
6.9 + 1. To enable caching, if available.
6.10 + 1. To initialise a kernel stack for privileged routines to use.
6.11 + 1. To set up the globals pointer so that symbols can be looked up.
6.12 + 1. To [[../payload|initialise payload data]].
6.13 + 1. To enter the main program of the payload.
6.14 +
6.15 +The start-up routine is positioned in the `.boot` section of the payload.
6.16 +
6.17 +Alongside the start-up routine are definitions of device configuration
6.18 +registers: `.devcfg0`, `.devcfg1` and `.devcfg2`. The actual values set for
6.19 +these registers should be defined in an application's `devconfig.h` file.