paul@149 | 1 | = Examples = |
paul@149 | 2 | |
paul@149 | 3 | To investigate various kinds of applications and to demonstrate techniques |
paul@149 | 4 | discovered and employed, a collection of examples has been provided: |
paul@149 | 5 | |
paul@149 | 6 | * [[/demo|Demo]] |
paul@149 | 7 | * [[VGA Output Examples]] |
paul@149 | 8 | |
paul@149 | 9 | == Common Example Characteristics == |
paul@149 | 10 | |
paul@149 | 11 | Each example provides the following resources: |
paul@149 | 12 | |
paul@149 | 13 | `devconfig.h`:: device configuration details |
paul@149 | 14 | `Makefile`:: a build configuration for the example |
paul@149 | 15 | `main.c`:: the example main program |
paul@149 | 16 | `main.h`:: definitions for the main program |
paul@149 | 17 | |
paul@149 | 18 | === Device Configuration === |
paul@149 | 19 | |
paul@149 | 20 | The `devconfig.h` file is intended to provide configuration settings related |
paul@149 | 21 | to the device configuration and oscillator (clock) frequency. The following |
paul@149 | 22 | definitions are employed: |
paul@149 | 23 | |
paul@149 | 24 | `DEVCFG1_CONFIG`:: the value with which the `DEVCFG1` register will be |
paul@149 | 25 | programmed, this typically being constructed using symbols |
paul@149 | 26 | defining values for various register fields |
paul@149 | 27 | |
paul@149 | 28 | `DEVCFG2_CONFIG`:: the value with which the `DEVCFG2` register will be |
paul@149 | 29 | programmed |
paul@149 | 30 | |
paul@149 | 31 | `FPB`:: the peripheral clock frequency, whose value will be a consequence of |
paul@149 | 32 | the above register settings |
paul@149 | 33 | |
paul@149 | 34 | === Build Configuration === |
paul@149 | 35 | |
paul@149 | 36 | The `Makefile` is concerned with defining source and program (target) files, |
paul@149 | 37 | build artefacts, configuration flags, employing the common definitions and |
paul@149 | 38 | rules found in the `mk` directory located at the top level of the CommonPIC32 |
paul@149 | 39 | distribution. |
paul@149 | 40 | |
paul@149 | 41 | === Main Program === |
paul@149 | 42 | |
paul@149 | 43 | The `main.c` and `main.h` files are concerned with providing a `main` function |
paul@149 | 44 | with the following signature: |
paul@149 | 45 | |
paul@149 | 46 | {{{ |
paul@149 | 47 | void main(void); |
paul@149 | 48 | }}} |
paul@149 | 49 | |
paul@149 | 50 | Since the `mk/common.mk` definitions file used by the build configuration |
paul@149 | 51 | provides access to various library files, the first tasks performed by the |
paul@149 | 52 | `main` function are likely to involve initialisation using various |
paul@149 | 53 | `init_`-prefixed functions. |
paul@149 | 54 | |
paul@149 | 55 | Other necessary functions are those handling exceptions and interrupts, having |
paul@149 | 56 | the following signatures: |
paul@149 | 57 | |
paul@149 | 58 | {{{ |
paul@149 | 59 | void exception_handler(void); |
paul@149 | 60 | void interrupt_handler(void); |
paul@149 | 61 | }}} |
paul@149 | 62 | |
paul@149 | 63 | These functions are called by the low-level library functionality when CPU |
paul@149 | 64 | exceptions and interrupts occur. |