View source for X2000

{{Experiment|X2000}}
==Files==
{{FileTable|X2000|
{{FileRow|@heart.c@|Multiplexed heart animation}}
{{FileHardware}}
{{FileScripts|X2000}}}}

==Demonstration==
Compile and upload the program in directory @x2000-heart@.  The program uses the General Purpose Input/Output (GPIO) pins of the {{microbit}} to control the 25 on-board LEDs in a flashing heart pattern.

==Activity==
The program contains a subroutine @show(image, time)@ that displays an image for a certain time, expressed in units of {{Number|15}} milliseconds.  After some initialisation, the main program @init()@ contains a loop that shows the same sequence of images over and over again.
<pre>
/* init -- main program */
void init(void)
{
    ...

    while (1) {
        show(heart, 70);
        show(small, 10);
        show(heart, 10);
        show(small, 10);
    }
}
</pre>
The two images, @heart@ and @small@, are specified in a way that will be explained shortly, but as an initial experiment, you could try modifying this code that uses them, without changing the images themselves.
* The times, 70+10+10+10, add up to 100 units, so ought to take {{Number|1.5}} seconds for each repetition of the pattern.  Is this time accurate?
* Try modifying the times so that the flashing pattern goes at twice the speed.
* Change the sequence of calls so that the heart pulses three times in each repetition of the pattern rather than just twice.

==Background==

This experiment moves beyond the core of the processor (designed by ARM) to look at I/O devices (designed by Nordic Semiconductor and documented in their separate datasheet).  The simplest I/O device is called GPIO (General Purpose Input/Output) and allows 32 pins of the chip to be individually configured either as outputs, producing a voltage under control of the program, or as inputs, so that the program can sense whether an externally applied voltage on the pin is high or low.  On the {{microbit}}, we can put the GPIO pins to immediate use because some of them are connected to 25 LEDs and two push-buttons. 

===Basics of LEDs===
[[Image:Digisys-led-basics.jpg|thumb|center|500px|Basics of LEDs]]

LEDs, like most semiconductor diodes, conduct in only one direction, shown by the arrow on the circuit symbol.  Thus, the circuit on the left lights the LED because current can flow through the LED from the positive to the negative terminal of the battery, in the direction shown by the arrow that forms part of the diode symbol.  On the other hand, in the circuit on the right, no current will flow, and the LED  will produce no light.  It is necessary to connect a resistor in series with the LED in order to control the current.  For a 3V supply, about 2V will be dropped across the LED, the remaining 1V will be dropped across the resistor, and a resistor of 220&Omega; will give a sensible current of 4.5mA through resistor and LED.  It doesn't matter which side of the LED the resistor is connected, so long as it is there.

[[Image:Digisys-led-matrix.jpg|thumb|center|500px|A matrix of LEDs]]

A single GPIO pin can control an LED connected (with a series resistor) between the pin and ground: this is useful as a debugging aid in many prototypes.  Alternatively, an LED and resistor could be connected between two GPIO pins A and B, and would light only if A is high and B is low.  This is a useless idea, until we see that multiple LEDs can be connected in this way, as in the picture at the right.  With these connections, the fourth LED from the left will light if B is high and Y is low; we can prevent the other LEDs from lighting by setting A low and X and Y high.  In fact we can light any single LED by setting the pins appropriately, and we can light one group of three LEDs or the other in any pattern by setting either A or B high, and choosing to set X, Y and Z low in a pattern that corresponds to the LEDs we want to light.  The series resistors at X, Y and Z control the current through individual LEDs in the setup just mentioned, so that each lit LED receives the same current whether the others are lit or not.  To show a pattern on all six LEDs, we will have to show the two groups alternately, changing between them quickly enough that the flickering is invisible.  This "matrix" of six LEDs is the smallest that gives any saving over wiring the LEDs to individual I/O pins, since it uses five pins rather than six.

On the V1 {{microbit}}, though they are arranged physically in a 5x5 array, the LEDs are wired as three 'rows' of nine LEDs each (with two missing), with a documented correspondence to the physical layout.
[[Image:Led-schematic.png|thumb|500px|center|{{microbit}} LEDs and buttons]]
Bits 4--12 of the GPIO register are used for the column lines, and bits 13--15 for the row lines, so the layout of the GPIO register looks like this:
 0000|0000|0000|0000|0000|R3 R2 R1 C9|C8 C7 C6 C5|C4 C3 C2 C1|0000
We will use this layout later to work out what patterns of bits to use for various images.

{{Context|Ad-hoc matrices of LEDs like the one on the {{microbit}} seem a bit amateurish (though fun).  But the idea of LEDs addressed as a matrix is very common, because the 7-segment LED displays seen everywhere are usually built in this way.  Each individual digit has seven (or eight with the decimal point) individual anodes and a common cathode.  In a multi-digit display, we can connect together corresponding anodes from each digit, and connect these through series resistors to eight GPIO pins.  The common cathode for each display also gets its own GPIO pin, so the total number of pins needed is 8 plus the number of digits.  In simple designs, the display can be multiplexed (as on the {{microbit}}) by bit-banging in software.  But there are also special-purpose LED driver chips like the HT16K33 that do the same job in hardware, reducing the load on the processor.}}

===Device registers===
On the ARM, I/O devices appear as special storage locations (called ''device registers'') in the same address space as RAM and Flash.  Loading from or storing to one of these locations gives information about the external world, or has a side-effect that is externally visible.  For example, there are two storage locations, one at address 0x50000514 that we shall call @GPIO.DIR@, and another at address 0x50000504 that we shall call @GPIO.OUT@.  Storing a bit pattern in @GPIO.DIR@ lets us configure the individual pins as inputs or outputs, and storing to @GPIO.OUT@ sets the voltage on each output pin to high (if 1) or low (if 0).  We can set these locations like any other, using an @str@ instruction with a specific address; so to set the @GPIO.DIR@ register to the constant 0xfff0 (thereby configuring 12 of the GPIO pins as outputs), we can use the code
<pre>
ldr r0, =0x50000514
ldr r1, =0xfff0
str r1, [r0]
</pre>
In a C program, things are a bit easier.  There's a header file @hardware.h@ that contains definitions of all the device registers we shall use in the course; including it allows us to use @GPIO.DIR@ in a program to denote the device register with address 0x50000514, and we can store the constant 0xfff0 in that register just by writing
 GPIO.DIR = 0xfff0;
The compiler translates this into exactly the code shown earlier.

The @GPIO.DIR@ register has a row of latches that remember whether each GPIO pin is configured as an input (0) or an output (1), and the @GPIO.OUT@ register has a row of latches that remember the output voltage that has been selected for each pin, either low (0) or high (1).  Internally, the same electronic signals that for an ordinary RAM location would cause the RAM to update the contents of a word in this case sets the latches and therefore the output directions or values.
(On other architectures such as the x86, I/O devices usually do not appear as storage locations accessed with the usual load and store instructions, but there are separate @in@ and @out@ instructions, and effectively a separate address space.)  To use the LEDs, we first need to configure the GPIO port so that the relevant bits are outputs: this is achieved with the assignment @GPIO.DIR = 0xfff0@.
 
To light a single LED, we should connect its row to +3.3V and its column to 0V.  Then current can flow through from the row pin, through the LED and its series resistor, to the column pin, and the LED will light up.  The series resistor limits the current that can flow through the LED to a value that is safe both for the LED and the microcontroller pins that are connected to it.
If we set the other row lines, apart from the one belonging to our chosen LED, to 0V and the other column lines to +3.3V, then other LEDs in the same row or column as the lit LED will have their anode and cathode at the same potential, and will carry no current.  LEDs that are not in the same row or column will have their anode and 0V and their cathode at +3.3V, so they will be reverse biassed, and they also will carry no current, and only the one chosen LED will light.  So to light the middle LED in the 5x5 array, which is electrically in row 2 and column 3, we set @GPIO.OUT@ like this:
 R3 R2 R1 C9 |C8 C7 C6 C5 |C4 C3 C2 C1 | 0 0 0 0
  0  1  0  1 | 1  1  1  1 | 1  0  1  1 | 0 0 0 0
       5            f            b           0
The needed assignment is @GPIO.OUT = 0x5fb0@.

{{V2Box|The V2 {{microbit}} has the LEDs and the GPIO registers arranged in a different way.  Instead of being wired in three rows of nine, the LEDs are wired in a more logical ways as five rows of five, using ten GPIO pins in all.  The V1 microcontroller has 32 GPIO pins arranged as a single 32-bit word, but the microcontroller on the V2 board has more, and in place of the single register @GPIO.OUT@ there are two registers @GPIO0.OUT@ and @GPIO1.OUT@ (and similarly two direction registers @GPIO0.DIR@ and @GPIO1.DIR@).  Irritatingly, the ten pins needed for the LEDs are not arranged contiguously, but spread across both GPIO registers, so that lighting the central LED requires the two assignments,
<pre>
GPIO0.OUT = 0x50008800;
GPIO1.OUT = 0x00000020;
</pre>
Further details are given below.}}

===Multiplexing===
We could light all 25 LEDs at once by setting all the column lines high and all the rows low -- 0xe000.  Each individual LED would be a bit dimmer, because the current available in each column (set by the 220&Omega; series resistor) would be shared among three LEDs.  For most patterns, however, we will need to ''multiplex'' the three rows, lighting the correct LEDs in each row in turn, and pausing a bit before moving on the next row.  If the pauses are short enough, persistence of vision will make it seem that all the LEDs making up the pattern are lit together.  For example, a heart pattern
 . X . X .
 X X X X X
 X X X X X
 . X X X .
 . . X . .
is made (according to the map shown above) by lighting LEDs 5, 6, 7, 9 in row 1, LEDs 1, 2, 3, 4, 5 in row 2, and LEDs 1, 4, 5, 6, 7, 8, 9 in row 3, so we want to use the bit patterns
 0010 1000 1111 0000 = 0x28f0
 0101 1110 0000 0000 = 0x5e00
 1000 0000 0110 0000 = 0x8060
in succession.  In each case, one of the column bits is 1, and some of the row bits are 0 according to which LEDs we want to light in that column.  Suitable code might be
<pre>
while (1) {
    GPIO.OUT = 0x28f0;
    delay(JIFFY);
    GPIO.OUT = 0x5e00;
    delay(JIFFY);
    GPIO.OUT = 0x8060;
    delay(JIFFY);
}
</pre>
The @delay()@ subroutine accepts a time in microseconds, so a suitable value of the constant @JIFFY@ would be 5000, for a delay of 5 milliseconds.  Then an iteration of the loop will take just about 15 milliseconds, or about 66 frames per second, fast enough that no flickering will be visible.

If we want to display more than one image from the program, a better plan is to represent each image by an array, and write a subroutine that can display image data from an array for a specified time.  We can define a fixed array @heart@ like this, containing the three rows of image data given above.
<pre>
const unsigned heart[] = {
    0x28f0, 0x5e00, 0x8060
};
</pre>
Using the keyword @const@ makes @heart@ into a constant array, which the C compiler will arrange to store in ROM space.

Here is the subroutine @show()@ that takes such an array and an integer count as parameters, and displays the three rows of the image successively, repeating the specified number of times.
<pre>
/* show -- display three rows of a picture n times */
void show(const unsigned img[], int n)
{
    while (n-- > 0) {
        /* Takes 15msec per iteration */
        for (int p = 0; p < 3; p++) {
            GPIO.OUT = img[p];
            delay(JIFFY);
        }
    }
}
</pre>
The subroutine receives as @img@ a pointer to the array of image data. The body of the subroutine contains a nested loop, with the outer loop repeating @n@ times, and the inner loop showing the three rows of the image in turn, pausing briefly between each row and the next, taking a total of @15n@ milliseconds.

Calculating images manually like we did earlier is worth doing once or twice to see how it works, but obviously the process is one that could be automated.  The header file @hardware.h@ in fact defines a macro @IMAGE@ that can be used like this to define any fixed image.
<pre>
const unsigned square[] =
    IMAGE(1,1,1,1,1,
          1,0,0,0,1,
          1,0,0,0,1,
          1,0,0,0,1,
          1,1,1,1,1);
</pre>

{{V2Box|The different wiring of the V2 board means that two words of data are needed for each of five rows of LEDs, so we can make an array of ten 32-bit integers to represent the whole image. While the LEDs have a more logical wiring layout, the assignment of GPIO pins to the signals is more haphazard, so calculating the hexadecimal constants needed for an image is no less tedious than for the V1 board.  This definition of @heart@ has comments showing the layout of the row and column pins, with two hexadecimal constants following each pair of rows.  As before, each frame of the display (now two integers) has a 1 bit for exactly one row pin, and 1 bits for those column pins that correspond to ''unlit'' LEDs.
<pre>
const unsigned heart[] = {
/*     31       27      23      19      15      11      7       3     0
GPIO0: C3 C5.C1|. . .R4|.R2 R1.|R5. . .|R3. . .|C2. . .|. . . .|. . . .
GPIO1:  . . . .|. . . .|. . . .|. . . .|. . . .|. . . .|. .C4 .|. . . . */

     /* 1 1 0 1|0 0 0 0|0 0 1 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0
        0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0 */
        0xd0200000, 0x00000000,
     /* 0 0 0 0|0 0 0 0|0 1 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0
        0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0 */
        0x00400000, 0x00000000,
     /* 0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|1 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0
        0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0 */
        0x00008000, 0x00000000,
     /* 0 1 0 1|0 0 0 1|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0
        0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0 */
        0x51000000, 0x00000000,
     /* 0 1 0 1|0 0 0 0|0 0 0 0|1 0 0 0|0 0 0 0|1 0 0 0|0 0 0 0|0 0 0 0
        0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 0 0|0 0 1 0|0 0 0 0 */
        0x50080800, 0x00000020
};
</pre>
Thankfully, once we have seen that this calculation can be done, we can forever after rely on a suitable definition of the @IMAGE(...)@ macro to compute all the images we need.  In the version of @hardware.h@ intended for the V2 board, the macro is defined differently, so that it produces the correct array of ten integers for use with @show()@ and similar functions.}}

{{V2Box|The @show()@ function for V2 is similar to the function for V1, but it deals in five rows with two GPIO registers to be set for each row.
<pre>
/* show -- display five rows of a picture n times */
void show(const unsigned img[], int n)
{
    while (n-- > 0) {
        /* Takes 15msec per iteration */
        for (int p = 0; p < 10; p += 2) {
            GPIO0.OUT = img[p];
            GPIO1.OUT = img[p+1];
            delay(JIFFY);
        }
    }
}
</pre>
To get the same total time of 15 milliseconds per iteration, we can make @JIFFY@ be 3000 instead of 5000.}}

What about those delays?  The easiest way of implementing them is to write a loop that counts down from some constant, creating a predictable delay.  With a bit of care, we can write a loop that takes {{Number|500 nsec}} per iteration, to do delay @@d@@ microseconds we need to make it iterate @@2d@@ times.
<pre>
void delay(unsigned usec)
{
    unsigned n = 2*usec;
    while (n > 0) {
        nop(); nop(); nop();
        n--;
    }
}
</pre>
Looking at the compiler output (and timing it with an oscilloscope) reveals that the loop takes 5 cycles per iteration without the @nop@ instructions, so adding three of them brings it up to 8 cycles per iteration, or {{Number|500 nsec}} at {{Number|16 MHz}}.  Delays were commonly implemented like this in old-fashioned MS-DOS games, and the games become unplayable when they were moved to a machine with a faster clock than the original PC.  The same thing happens to us for the V2 {{microbit}}, where the clock runs at {{Number|64 MHz}}.

A more serious problem with delay loops is that they force the machine to do nothing useful during the delay.  That is a problem we will solve later -- by using a hardware timer in place of the delay loop, then making the program interrupt controlled, and ultimately by introducing an operating system that is able to schedule other processes to run while waiting for the timer to fire.

{{V2Box|On the V2, delay loops like this are made more complicated by variations in the time it takes to execute an instruction.  The processor clock ticks at {{Number|64 MHz}}, rather than the {{Number|16 MHz}} on the V1, and the flash memory where the program is stored can't feed instructions to the processor core fast enough to keep up with this rate.  This means that there are sometimes delays between instructions while the processor core waits to fetch code from flash memory, and that makes it difficult to calculate the exact number of clock cycles that a sequence of instructions will take.  The poor flash performance can be hidden to some extent by activating a small, RAM-based cache between the processor core and the flash.  Although this speeds things up on average, it also makes the timing still more unpredictable.  The best solution to this problem is to avoid delay loops entirely; but in the interim, we can improve matters by arranging to copy the code for timing-critical subroutines like @delay@ into RAM when the program starts.  The experimental setup is arranged so that this will happen automatically if the magic word @CODERAM@ appears at the start of the subroutine.}}

The push-buttons on the {{Microbit}} are connected to other GPIO pins that can be configured as inputs.  For various reasons, the buttons are wired with pull-up resistors as shown in the schematic above, so that the input signal to the chip is +3.3V if the button is not pushed (a logical 1), and drops to 0V (a logical 0) when it is pushed.  Lab 2 begins with a program (an electronic Valentine's card) that shows a beating heart pattern, and asks you enhance it so that pressing the buttons changes pattern shown on the display.

==Challenges==
* See if you can work out how to make (by hand if you have the patience) an image @hollow@ that shows a heart shape as an outline: it the solid heart shape without the pixels that are lit in the small heart shape.  Make a more elaborate animation that uses all three shapes.
* The constant @JIFFY@ determines the time for which each row of an image is displayed.  Try changing it: how big can it be before the image visibly flickers?
* Code is already present to test the state of the two push-buttons.  Modify the program so that it shows different animations when one or both of the buttons are pressed.

==Questions==
{{Question|What does the assignment statement @GPIO.OUT {{=}} 0x4000@ look like in assembly language?}}

@GPIO.OUT@ is defined (in a slightly convoluted way) in @hardware.h@ as an unsigned integer variable at the address {{Hex|0x50000504}}, a constant obtained from the nRF51822 datasheet.  The same assignment can be written directly as
 (* (unsigned volatile *) 0x50000504) = 0x4000
The @volatile@ keyword says to the C compiler, "Please just do the assignment now: don't try to be clever and optimise this in any way, such as combining this assignment with a later one that targets the same address."

To achieve this in assembly language, we need an @str@ instruction for the assignment.  But both the address being assigned to and the value being assigned are large constants, so we'll need to put the constants in registers first, using the @pc@-relative load instructions for which "@ldr&nbsp;=@" is a shorthand.  So suitable code is
 ldr r0, =0x4000
 ldr r1, =0x50000504
 str r0, [r1]

Note: that code works fine, and is reasonably efficient.  But there's another way of putting the constant 0x4000 in register @r0@ that takes the same time on the Cortex-M0 and uses marginally less code space:
 movs r0, #0x4
 lsls r0, r0, #12
That code exploits that fact that the constant only has one non-zero bit, and that (or something very similar) is the code that @gcc@ actually generates in place of the first @ldr =@.

{{Question|What does the magic word @CODERAM@ do on V2?}}

This magic word is defined in @hardware.h@ as an abbreviation for the GCC annotation
 __attribute((noinline, section(".xram")))
Functions labelled with this attribute will be collected together into a linker section @.xram@, different from the section @.text@ that contains the rest of the program.  The linker script @nRF52833.ld@ gives instructions to keep this code separate, and the startup code in @startup.c@ copies the code into the right place in RAM.  An area of 4kB (out of the 128kB of RAM in the machine) is set aside for this purpose, even in programs that do not use @CODERAM@; this should be enough for the timing-critical code in any of our programs.  The @.xram@ section appears at address {{Hex|81f000}} in the address space of the machine, putting it within the range reachable by @bl@ instructions stored in the Flash.  In addition, RAM at this address is accessed by a different channel from the same RAM in the space above {{Hex|20000000}}, speeding up access.