1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/Examples Mon May 20 23:34:28 2019 +0200
1.3 @@ -0,0 +1,64 @@
1.4 += Examples =
1.5 +
1.6 +To investigate various kinds of applications and to demonstrate techniques
1.7 +discovered and employed, a collection of examples has been provided:
1.8 +
1.9 + * [[/demo|Demo]]
1.10 + * [[VGA Output Examples]]
1.11 +
1.12 +== Common Example Characteristics ==
1.13 +
1.14 +Each example provides the following resources:
1.15 +
1.16 + `devconfig.h`:: device configuration details
1.17 + `Makefile`:: a build configuration for the example
1.18 + `main.c`:: the example main program
1.19 + `main.h`:: definitions for the main program
1.20 +
1.21 +=== Device Configuration ===
1.22 +
1.23 +The `devconfig.h` file is intended to provide configuration settings related
1.24 +to the device configuration and oscillator (clock) frequency. The following
1.25 +definitions are employed:
1.26 +
1.27 + `DEVCFG1_CONFIG`:: the value with which the `DEVCFG1` register will be
1.28 + programmed, this typically being constructed using symbols
1.29 + defining values for various register fields
1.30 +
1.31 + `DEVCFG2_CONFIG`:: the value with which the `DEVCFG2` register will be
1.32 + programmed
1.33 +
1.34 + `FPB`:: the peripheral clock frequency, whose value will be a consequence of
1.35 + the above register settings
1.36 +
1.37 +=== Build Configuration ===
1.38 +
1.39 +The `Makefile` is concerned with defining source and program (target) files,
1.40 +build artefacts, configuration flags, employing the common definitions and
1.41 +rules found in the `mk` directory located at the top level of the CommonPIC32
1.42 +distribution.
1.43 +
1.44 +=== Main Program ===
1.45 +
1.46 +The `main.c` and `main.h` files are concerned with providing a `main` function
1.47 +with the following signature:
1.48 +
1.49 +{{{
1.50 +void main(void);
1.51 +}}}
1.52 +
1.53 +Since the `mk/common.mk` definitions file used by the build configuration
1.54 +provides access to various library files, the first tasks performed by the
1.55 +`main` function are likely to involve initialisation using various
1.56 +`init_`-prefixed functions.
1.57 +
1.58 +Other necessary functions are those handling exceptions and interrupts, having
1.59 +the following signatures:
1.60 +
1.61 +{{{
1.62 +void exception_handler(void);
1.63 +void interrupt_handler(void);
1.64 +}}}
1.65 +
1.66 +These functions are called by the low-level library functionality when CPU
1.67 +exceptions and interrupts occur.