CommonPIC32

Changeset

149:a7af613384c7
2019-05-20 Paul Boddie raw files shortlog changelog graph Expanded the documentation of examples, covering the demo example and the common resources employed by all examples. Consolidated common details of the VGA examples into a signal wiring page.
docs/wiki/CommonPIC32 (file) docs/wiki/Examples (file) docs/wiki/Examples--demo (file) docs/wiki/Examples--vga (file) docs/wiki/Examples--vga-cpu (file) docs/wiki/Examples--vga-dual (file) docs/wiki/Examples--vga-pmp (file) docs/wiki/Examples--vga-timer (file) docs/wiki/VGA_Output_Examples (file) docs/wiki/VGA_Signal_Output (file) docs/wiki/VGA_Signal_Wiring (file)
     1.1 --- a/docs/wiki/CommonPIC32	Sat May 04 22:54:18 2019 +0200
     1.2 +++ b/docs/wiki/CommonPIC32	Mon May 20 23:34:28 2019 +0200
     1.3 @@ -6,5 +6,5 @@
     1.4  
     1.5  == Documentation ==
     1.6  
     1.7 - * [[VGA Output Examples]]
     1.8 + * [[Examples]]
     1.9   * [[VGA Signal Output]]
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/docs/wiki/Examples	Mon May 20 23:34:28 2019 +0200
     2.3 @@ -0,0 +1,64 @@
     2.4 += Examples =
     2.5 +
     2.6 +To investigate various kinds of applications and to demonstrate techniques
     2.7 +discovered and employed, a collection of examples has been provided:
     2.8 +
     2.9 + * [[/demo|Demo]]
    2.10 + * [[VGA Output Examples]]
    2.11 +
    2.12 +== Common Example Characteristics ==
    2.13 +
    2.14 +Each example provides the following resources:
    2.15 +
    2.16 + `devconfig.h`:: device configuration details
    2.17 + `Makefile`:: a build configuration for the example
    2.18 + `main.c`:: the example main program
    2.19 + `main.h`:: definitions for the main program
    2.20 +
    2.21 +=== Device Configuration ===
    2.22 +
    2.23 +The `devconfig.h` file is intended to provide configuration settings related
    2.24 +to the device configuration and oscillator (clock) frequency. The following
    2.25 +definitions are employed:
    2.26 +
    2.27 + `DEVCFG1_CONFIG`:: the value with which the `DEVCFG1` register will be
    2.28 +                    programmed, this typically being constructed using symbols
    2.29 +                    defining values for various register fields
    2.30 +
    2.31 + `DEVCFG2_CONFIG`:: the value with which the `DEVCFG2` register will be
    2.32 +                    programmed
    2.33 +
    2.34 + `FPB`:: the peripheral clock frequency, whose value will be a consequence of
    2.35 +         the above register settings
    2.36 +
    2.37 +=== Build Configuration ===
    2.38 +
    2.39 +The `Makefile` is concerned with defining source and program (target) files,
    2.40 +build artefacts, configuration flags, employing the common definitions and
    2.41 +rules found in the `mk` directory located at the top level of the CommonPIC32
    2.42 +distribution.
    2.43 +
    2.44 +=== Main Program ===
    2.45 +
    2.46 +The `main.c` and `main.h` files are concerned with providing a `main` function
    2.47 +with the following signature:
    2.48 +
    2.49 +{{{
    2.50 +void main(void);
    2.51 +}}}
    2.52 +
    2.53 +Since the `mk/common.mk` definitions file used by the build configuration
    2.54 +provides access to various library files, the first tasks performed by the
    2.55 +`main` function are likely to involve initialisation using various
    2.56 +`init_`-prefixed functions.
    2.57 +
    2.58 +Other necessary functions are those handling exceptions and interrupts, having
    2.59 +the following signatures:
    2.60 +
    2.61 +{{{
    2.62 +void exception_handler(void);
    2.63 +void interrupt_handler(void);
    2.64 +}}}
    2.65 +
    2.66 +These functions are called by the low-level library functionality when CPU
    2.67 +exceptions and interrupts occur.
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/docs/wiki/Examples--demo	Mon May 20 23:34:28 2019 +0200
     3.3 @@ -0,0 +1,57 @@
     3.4 += Demo Example =
     3.5 +
     3.6 +This example demonstrates UART communication using UART1. Interrupt conditions
     3.7 +on the UART peripheral are handled, input is tested, output is produced, and
     3.8 +upon receiving the `0` character, DMA-driven output is initiated.
     3.9 +
    3.10 +The DMA-driven output demonstrates mechanisms employed by some of the [[VGA
    3.11 +Output Examples|VGA examples]]. A channel is enabled by the interrupt handler
    3.12 +and its transfers each initiated by a timer; this should cause text to be
    3.13 +transmitted relatively slowly across the serial connection...
    3.14 +
    3.15 +{{{
    3.16 +Hello!
    3.17 +}}}
    3.18 +
    3.19 +When this first channel completes all transfers, two other channels chained to
    3.20 +it are enabled. Another timer then causes their transfers to be initiated.
    3.21 +Since these two channels effectively compete for access to the UART
    3.22 +peripheral, their transfers are interleaved. Regardless of the configuration
    3.23 +of the example, more text should be transmitted relatively slowly...
    3.24 +
    3.25 +{{{
    3.26 +And once again, hello!
    3.27 +}}}
    3.28 +
    3.29 +Although such DMA channel interleaving is rather exotic, other techniques
    3.30 +employed by the example are likely to be applicable elsewhere.
    3.31 +
    3.32 +== Hardware Details ==
    3.33 +
    3.34 +The pin usage of this solution is documented below.
    3.35 +
    3.36 +=== PIC32MX270F256B-50I/SP Pin Assignments ===
    3.37 +
    3.38 +{{{
    3.39 +MCLR#          1  \/  28
    3.40 +          RA0  2      27
    3.41 +          RA1  3      26 RB15/U1TX
    3.42 +          RB0  4      25 RB14
    3.43 +          RB1  5      24 RB13/U1RX
    3.44 +          RB2  6      23
    3.45 +          RB3  7      22 RB11/PGEC2
    3.46 +               8      21 RB10/PGEC3
    3.47 +          RA2  9      20
    3.48 +          RA3 10      19
    3.49 +          RB4 11      18 RB9
    3.50 +              12      17 RB8
    3.51 +              13      16 RB7
    3.52 +          RB5 14      15
    3.53 +}}}
    3.54 +
    3.55 +Note that RB6 is not available on pin 15 on this device (it is needed for VBUS
    3.56 +unlike the MX170 variant).
    3.57 +
    3.58 +=== UART Connections ===
    3.59 +
    3.60 +UART1 is exposed by the RB13 and RB15 pins.
     4.1 --- a/docs/wiki/Examples--vga	Sat May 04 22:54:18 2019 +0200
     4.2 +++ b/docs/wiki/Examples--vga	Mon May 20 23:34:28 2019 +0200
     4.3 @@ -1,8 +1,9 @@
     4.4  = VGA Output Example =
     4.5  
     4.6 -This example demonstrates the generation of an analogue VGA signal from a
     4.7 -PIC32 microcontroller using general output pins. It follows on from the work
     4.8 -done in the VGAPIC32 project. The result is not entirely satisfactory:
     4.9 +This example demonstrates the generation of an analogue [[VGA Signal Output|
    4.10 +VGA]] signal from a PIC32 microcontroller using general output pins. It
    4.11 +follows on from the work done in the VGAPIC32 project. The result is not
    4.12 +entirely satisfactory:
    4.13  
    4.14   * Every fourth pixel is wider than the others, this apparently being an
    4.15     artefact of the DMA transfer mechanism.
    4.16 @@ -68,33 +69,3 @@
    4.17  HSYNC -> HS
    4.18  VSYNC -> VS
    4.19  }}}
    4.20 -
    4.21 -=== Output Socket Pinout ===
    4.22 -
    4.23 -{{{
    4.24 -5 (GND)  4 (NC)   3 (B)    2 (G)    1 (R)
    4.25 -
    4.26 -    10 (GND) 9 (NC)   8 (GND)  7 (GND)  6 (GND)
    4.27 -
    4.28 -15 (NC)  14 (VS)  13 (HS)  12 (NC)  11 (NC)
    4.29 -}}}
    4.30 -
    4.31 -=== Output Cable Pinout ===
    4.32 -
    4.33 -{{{
    4.34 -    1 (R)    2 (G)    3 (B)    4 (NC)   5 (GND)
    4.35 -
    4.36 -6 (GND)  7 (GND)  8 (GND)  9 (NC)   10 (GND)
    4.37 -
    4.38 -    11 (NC)  12 (NC)  13 (HS)  14 (VS)  15 (NC)
    4.39 -}}}
    4.40 -
    4.41 -== References ==
    4.42 -
    4.43 -https://en.wikipedia.org/wiki/VGA_connector
    4.44 -
    4.45 -http://papilio.cc/index.php?n=Papilio.VGAWing
    4.46 -
    4.47 -http://lucidscience.com/pro-vga%20video%20generator-2.aspx
    4.48 -
    4.49 -https://sites.google.com/site/h2obsession/CBM/C128/rgbi-to-vga
     5.1 --- a/docs/wiki/Examples--vga-cpu	Sat May 04 22:54:18 2019 +0200
     5.2 +++ b/docs/wiki/Examples--vga-cpu	Mon May 20 23:34:28 2019 +0200
     5.3 @@ -1,9 +1,9 @@
     5.4  = VGA Output Example (CPU-Driven Transfers) =
     5.5  
     5.6 -This example demonstrates the generation of an analogue VGA signal from a
     5.7 -PIC32 microcontroller using general output pins. Instead of using DMA, which
     5.8 -was the focus of the VGAPIC32 project and is a central feature of the
     5.9 -approaches demonstrated by other examples ([[../vga|vga]],
    5.10 +This example demonstrates the generation of an analogue [[VGA Signal Output|
    5.11 +VGA]] signal from a PIC32 microcontroller using general output pins. Instead
    5.12 +of using DMA, which was the focus of the VGAPIC32 project and is a central
    5.13 +feature of the approaches demonstrated by other examples ([[../vga|vga]],
    5.14  [[../vga-dual|vga-dual]], [[../vga-pmp|vga-pmp]], [[../vga-timer|vga-timer]]),
    5.15  here the CPU is given the task of transferring pixel data to the output pins.
    5.16  
    5.17 @@ -88,33 +88,3 @@
    5.18  HSYNC -> HS
    5.19  VSYNC -> VS
    5.20  }}}
    5.21 -
    5.22 -=== Output Socket Pinout ===
    5.23 -
    5.24 -{{{
    5.25 -5 (GND)  4 (NC)   3 (B)    2 (G)    1 (R)
    5.26 -
    5.27 -    10 (GND) 9 (NC)   8 (GND)  7 (GND)  6 (GND)
    5.28 -
    5.29 -15 (NC)  14 (VS)  13 (HS)  12 (NC)  11 (NC)
    5.30 -}}}
    5.31 -
    5.32 -=== Output Cable Pinout ===
    5.33 -
    5.34 -{{{
    5.35 -    1 (R)    2 (G)    3 (B)    4 (NC)   5 (GND)
    5.36 -
    5.37 -6 (GND)  7 (GND)  8 (GND)  9 (NC)   10 (GND)
    5.38 -
    5.39 -    11 (NC)  12 (NC)  13 (HS)  14 (VS)  15 (NC)
    5.40 -}}}
    5.41 -
    5.42 -== References ==
    5.43 -
    5.44 -https://en.wikipedia.org/wiki/VGA_connector
    5.45 -
    5.46 -http://papilio.cc/index.php?n=Papilio.VGAWing
    5.47 -
    5.48 -http://lucidscience.com/pro-vga%20video%20generator-2.aspx
    5.49 -
    5.50 -https://sites.google.com/site/h2obsession/CBM/C128/rgbi-to-vga
     6.1 --- a/docs/wiki/Examples--vga-dual	Sat May 04 22:54:18 2019 +0200
     6.2 +++ b/docs/wiki/Examples--vga-dual	Mon May 20 23:34:28 2019 +0200
     6.3 @@ -1,8 +1,9 @@
     6.4  = VGA Output Example (Dual-Channel DMA Transfers) =
     6.5  
     6.6 -This example demonstrates the generation of an analogue VGA signal from a
     6.7 -PIC32 microcontroller using general output pins. It follows on from the work
     6.8 -done in the VGAPIC32 project. The result is not entirely satisfactory:
     6.9 +This example demonstrates the generation of an analogue [[VGA Signal Output|
    6.10 +VGA]] signal from a PIC32 microcontroller using general output pins. It
    6.11 +follows on from the work done in the VGAPIC32 project. The result is not
    6.12 +entirely satisfactory:
    6.13  
    6.14   * Every fourth pixel is wider than the others, this apparently being an
    6.15     artefact of the DMA transfer mechanism.
    6.16 @@ -77,33 +78,3 @@
    6.17  HSYNC -> HS
    6.18  VSYNC -> VS
    6.19  }}}
    6.20 -
    6.21 -=== Output Socket Pinout ===
    6.22 -
    6.23 -{{{
    6.24 -5 (GND)  4 (NC)   3 (B)    2 (G)    1 (R)
    6.25 -
    6.26 -    10 (GND) 9 (NC)   8 (GND)  7 (GND)  6 (GND)
    6.27 -
    6.28 -15 (NC)  14 (VS)  13 (HS)  12 (NC)  11 (NC)
    6.29 -}}}
    6.30 -
    6.31 -=== Output Cable Pinout ===
    6.32 -
    6.33 -{{{
    6.34 -    1 (R)    2 (G)    3 (B)    4 (NC)   5 (GND)
    6.35 -
    6.36 -6 (GND)  7 (GND)  8 (GND)  9 (NC)   10 (GND)
    6.37 -
    6.38 -    11 (NC)  12 (NC)  13 (HS)  14 (VS)  15 (NC)
    6.39 -}}}
    6.40 -
    6.41 -== References ==
    6.42 -
    6.43 -https://en.wikipedia.org/wiki/VGA_connector
    6.44 -
    6.45 -http://papilio.cc/index.php?n=Papilio.VGAWing
    6.46 -
    6.47 -http://lucidscience.com/pro-vga%20video%20generator-2.aspx
    6.48 -
    6.49 -https://sites.google.com/site/h2obsession/CBM/C128/rgbi-to-vga
     7.1 --- a/docs/wiki/Examples--vga-pmp	Sat May 04 22:54:18 2019 +0200
     7.2 +++ b/docs/wiki/Examples--vga-pmp	Mon May 20 23:34:28 2019 +0200
     7.3 @@ -1,8 +1,8 @@
     7.4  = VGA Output Example (Parallel Mode Transfers) =
     7.5  
     7.6 -This example demonstrates the generation of an analogue VGA signal from a
     7.7 -PIC32 microcontroller using the parallel mode (parallel master port, PMP)
     7.8 -peripheral. The result is not entirely satisfactory:
     7.9 +This example demonstrates the generation of an analogue [[VGA Signal Output|
    7.10 +VGA]] signal from a PIC32 microcontroller using the parallel mode (parallel
    7.11 +master port, PMP) peripheral. The result is not entirely satisfactory:
    7.12  
    7.13   * Pixels are very narrow unless buffered using a flip-flop driven by the
    7.14     peripheral, this being a characteristic of the way the peripheral works, it
    7.15 @@ -81,33 +81,3 @@
    7.16  HSYNC -> HS
    7.17  VSYNC -> VS
    7.18  }}}
    7.19 -
    7.20 -=== Output Socket Pinout ===
    7.21 -
    7.22 -{{{
    7.23 -5 (GND)  4 (NC)   3 (B)    2 (G)    1 (R)
    7.24 -
    7.25 -    10 (GND) 9 (NC)   8 (GND)  7 (GND)  6 (GND)
    7.26 -
    7.27 -15 (NC)  14 (VS)  13 (HS)  12 (NC)  11 (NC)
    7.28 -}}}
    7.29 -
    7.30 -=== Output Cable Pinout ===
    7.31 -
    7.32 -{{{
    7.33 -    1 (R)    2 (G)    3 (B)    4 (NC)   5 (GND)
    7.34 -
    7.35 -6 (GND)  7 (GND)  8 (GND)  9 (NC)   10 (GND)
    7.36 -
    7.37 -    11 (NC)  12 (NC)  13 (HS)  14 (VS)  15 (NC)
    7.38 -}}}
    7.39 -
    7.40 -== References ==
    7.41 -
    7.42 -https://en.wikipedia.org/wiki/VGA_connector
    7.43 -
    7.44 -http://papilio.cc/index.php?n=Papilio.VGAWing
    7.45 -
    7.46 -http://lucidscience.com/pro-vga%20video%20generator-2.aspx
    7.47 -
    7.48 -https://sites.google.com/site/h2obsession/CBM/C128/rgbi-to-vga
     8.1 --- a/docs/wiki/Examples--vga-timer	Sat May 04 22:54:18 2019 +0200
     8.2 +++ b/docs/wiki/Examples--vga-timer	Mon May 20 23:34:28 2019 +0200
     8.3 @@ -1,10 +1,10 @@
     8.4  = VGA Output Example (Timed DMA Transfers) =
     8.5  
     8.6 -This example demonstrates the generation of an analogue VGA signal from a
     8.7 -PIC32 microcontroller using general output pins. Unlike the [[../vga|vga]] and
     8.8 -[[../vga-pmp|vga-pmp]] examples, it employs a regular interrupt condition to
     8.9 -schedule single-byte (single-pixel) DMA transfers instead of a single
    8.10 -whole-line transfer.
    8.11 +This example demonstrates the generation of an analogue [[VGA Signal Output|
    8.12 +VGA]] signal from a PIC32 microcontroller using general output pins. Unlike
    8.13 +the [[../vga|vga]] and [[../vga-pmp|vga-pmp]] examples, it employs a regular
    8.14 +interrupt condition to schedule single-byte (single-pixel) DMA transfers
    8.15 +instead of a single whole-line transfer.
    8.16  
    8.17  The principal advantage of this method over the whole-line transfer method is
    8.18  its production of pixels with consistent widths. The principal disadvantage is
    8.19 @@ -115,33 +115,3 @@
    8.20  HSYNC -> HS
    8.21  VSYNC -> VS
    8.22  }}}
    8.23 -
    8.24 -=== Output Socket Pinout ===
    8.25 -
    8.26 -{{{
    8.27 -5 (GND)  4 (NC)   3 (B)    2 (G)    1 (R)
    8.28 -
    8.29 -    10 (GND) 9 (NC)   8 (GND)  7 (GND)  6 (GND)
    8.30 -
    8.31 -15 (NC)  14 (VS)  13 (HS)  12 (NC)  11 (NC)
    8.32 -}}}
    8.33 -
    8.34 -=== Output Cable Pinout ===
    8.35 -
    8.36 -{{{
    8.37 -    1 (R)    2 (G)    3 (B)    4 (NC)   5 (GND)
    8.38 -
    8.39 -6 (GND)  7 (GND)  8 (GND)  9 (NC)   10 (GND)
    8.40 -
    8.41 -    11 (NC)  12 (NC)  13 (HS)  14 (VS)  15 (NC)
    8.42 -}}}
    8.43 -
    8.44 -== References ==
    8.45 -
    8.46 -https://en.wikipedia.org/wiki/VGA_connector
    8.47 -
    8.48 -http://papilio.cc/index.php?n=Papilio.VGAWing
    8.49 -
    8.50 -http://lucidscience.com/pro-vga%20video%20generator-2.aspx
    8.51 -
    8.52 -https://sites.google.com/site/h2obsession/CBM/C128/rgbi-to-vga
     9.1 --- a/docs/wiki/VGA_Output_Examples	Sat May 04 22:54:18 2019 +0200
     9.2 +++ b/docs/wiki/VGA_Output_Examples	Mon May 20 23:34:28 2019 +0200
     9.3 @@ -1,11 +1,18 @@
     9.4  = VGA Output Examples =
     9.5  
     9.6 +A number of examples are provided to demonstrate the generation of a [[VGA
     9.7 +Signal Output|VGA-compatible video signal]] by the microcontroller:
     9.8 +
     9.9   * [[Examples/vga|vga]]
    9.10   * [[Examples/vga-cpu|vga-cpu]]
    9.11   * [[Examples/vga-dual|vga-dual]]
    9.12   * [[Examples/vga-pmp|vga-pmp]]
    9.13   * [[Examples/vga-timer|vga-timer]]
    9.14  
    9.15 +Each one mostly demonstrates the same thing as the others, but certain
    9.16 +implementation choices cause certain trade-offs to be made. Some of these are
    9.17 +discussed below.
    9.18 +
    9.19  == Comparison ==
    9.20  
    9.21  In investigating different techniques, the following observations have been
    10.1 --- a/docs/wiki/VGA_Signal_Output	Sat May 04 22:54:18 2019 +0200
    10.2 +++ b/docs/wiki/VGA_Signal_Output	Mon May 20 23:34:28 2019 +0200
    10.3 @@ -1,7 +1,12 @@
    10.4  = VGA Signal Output =
    10.5  
    10.6 -There are two principal mechanisms for generating a VGA signal demonstrated in
    10.7 -this project:
    10.8 +A number of [[VGA Output Examples|examples]] demonstrate VGA signal generation
    10.9 +from a PIC32 microcontroller. These examples employ a particular [[VGA Signal
   10.10 +Wiring|wiring scheme]] in order to deliver signals to a suitable display or
   10.11 +monitor.
   10.12 +
   10.13 +Within the microcontroller, there are two principal mechanisms demonstrated in
   10.14 +this project for generating a VGA signal:
   10.15  
   10.16   * Using the CPU to "copy" pixel data to an output port
   10.17   * Using DMA transfers to "copy" pixel data to an output port
    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/docs/wiki/VGA_Signal_Wiring	Mon May 20 23:34:28 2019 +0200
    11.3 @@ -0,0 +1,45 @@
    11.4 += VGA Signal Wiring =
    11.5 +
    11.6 +The generation of a VGA-compatible video signal from a PIC32 microcontroller
    11.7 +is demonstrated by a number of [[VGA Output Examples|examples]]. Common to
    11.8 +these are certain hardware characteristics, described here to avoid
    11.9 +unnecessary repetition.
   11.10 +
   11.11 +== Pinouts ==
   11.12 +
   11.13 +For the examples documented in this project, the following pinouts apply. VGA
   11.14 +connectors also support other signals, generally used for querying a display
   11.15 +for supported resolutions, but since a statically configured resolution is
   11.16 +employed by these examples, these other signals are left unconnected.
   11.17 +
   11.18 +=== Output Socket Pinout ===
   11.19 +
   11.20 +{{{
   11.21 +5 (GND)  4 (NC)   3 (B)    2 (G)    1 (R)
   11.22 +
   11.23 +    10 (GND) 9 (NC)   8 (GND)  7 (GND)  6 (GND)
   11.24 +
   11.25 +15 (NC)  14 (VS)  13 (HS)  12 (NC)  11 (NC)
   11.26 +}}}
   11.27 +
   11.28 +=== Output Cable Pinout ===
   11.29 +
   11.30 +{{{
   11.31 +    1 (R)    2 (G)    3 (B)    4 (NC)   5 (GND)
   11.32 +
   11.33 +6 (GND)  7 (GND)  8 (GND)  9 (NC)   10 (GND)
   11.34 +
   11.35 +    11 (NC)  12 (NC)  13 (HS)  14 (VS)  15 (NC)
   11.36 +}}}
   11.37 +
   11.38 +=== References ===
   11.39 +
   11.40 + * [[WikiPedia:VGA connector]]
   11.41 +
   11.42 + * [[http://papilio.cc/index.php?n=Papilio.VGAWing|VGAWing]]
   11.43 +
   11.44 + * [[http://lucidscience.com/pro-vga%20video%20generator-2.aspx|
   11.45 +     LucidScience - Build the VGA VIDEO GENERATOR - Page 2 of 16]]
   11.46 +
   11.47 + * [[https://sites.google.com/site/h2obsession/CBM/C128/rgbi-to-vga|
   11.48 +     RGBI to VGA - H2Obsession]]