CommonPIC32

Changeset

150:82a63936a118
2019-06-11 Paul Boddie raw files shortlog changelog graph Added initial library documentation.
docs/wiki/CommonPIC32 (file) docs/wiki/Library (file) docs/wiki/Library--cpu (file) docs/wiki/Library--init (file) docs/wiki/Library--payload (file) docs/wiki/Library--start (file)
     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.