# Laboratory exercises

The course has four-and-a-bit lab exercises, each designed to be done in a single session or less. There is another page with hints for demonstrators.

I've added a couple of exercises related to things in the Trinity Term part of the course. They are there as a way of preserving and making available some existing materials – the Thumb simulator and a simulation of a carry-lookahead adder – in case participants want to experiment with them. There are no lab sessions in Trinity, and no expectation that participants will actually do these labs.

Is science a kind of playing? – Tom Spivey

## Rules

The labs for this course will run in a way that is slightly different from other courses, reflecting the wide variety of prior experience possessed by participants.

• No lab reports will be required. However, you may print out your code at the end of each lab session and have it initialled by one of the demonstrators if you want physical evidence of participation.
• In order to get a mark of S for the term, you must attend and participate in the lab sessions. Some participants will want to spend the time in the sessions practising assembly language programming; others will find that easy, and want to pass quickly on to later exercises, or pursue ideas of their own. All ways of engaging with the material are acceptable, and you won't be assessed on how far you have got through the sequence of suggested activities.
• In order to get a mark of S+ for the term, you must have shown a spark of originality at some point. Please don't ask us to suggest what degree of originality or what idea would be thought of as a spark.
• If you can't come to the lab sessions in person but want credit for them, then you must contact one of the demonstrators to discuss how you can participate remotely.
• We will be giving credit for participating in the lab sessions in a productive way in the context of your previous experience with low-level programming. It will not be possible to get credit for the lab exercises by attending only towards the end of term, whatever completed work you offer to show at that time.

## Instructions

Each lab has its own page with instructions.

• Lab zero: getting started. Follow the instructions for building, loading and running a simple program that echoes input sent over the serial port. (Beyond building and running the program, there's nothing to do here – it's just a way of getting started and becoming more familiar with the tools.)
• Lab one: assembly language. Implement various arithmetic operations in assembly language.
• Lab two: general purpose I/O. Enhance an electronic Valentine's card to respond to button presses.
• Lab three: interrupts. Investigate a program that uses interrupts to overlap computing a list of primes with printing it.
• Lab four: micro:bian. Experiment with an embedded operating systems that supports concurrent processes communicating by messages.

Though there are no lab sessions scheduled for Trinity Term, nevertheless there are some (entirely optional) lab exercises that illustrate the material in the lectures and problem sheets.

• Lab five: Thumb simulator. Enhance an architectural simulation of a processor that implements the Thumb instruction set.

Software resources for the lab exercises are provided via a Mercurial repository, allowing for updates during term. You can browse the repository using a web interface, and instructions for making a local clone are provided as part of Lab zero. There are seven subdirectories in the repository corresponding to Labs zero to six, plus a setup directory used in the installation process. Several files appear as independent copies in multiple directories, for example, the file hardware.h that specifies the locations of various I/O registers on the micro:bit, and the file startup.c containing the code that runs when the micro:bit starts up. As far as possible, all files with the same name are identical, but in any event, they are consistent with each other. Naturally enough, each directory has its own unique Makefile.

Other pages contain information about programming the micro:bit and using the Linux-hosted toolchain to compile programs.

## Problems and fixes

Problems marked "(Fixed in rev n:123abc)" can be solved by pulling from the software repository and updating your working copy. Instructions for that are given below.

013 The debug script in Labs zero and one does not work.
Typically, gdb gives a message saying that the attempt to connect to :3333 has timed out. The last part of the instructions for Lab zero has instructions for starting the debug adapter and the debugger manually, making the chance of success higher, or at least making the cause of failure apparent.
011 Plugging in a micro:bit doesn't cause the MICROBIT drive to show up.
The micro-USB connector on a new micro:bit can be a little stiff, and if not pushed fully home can result in power and ground being connected but not the two data pins. (USB connectors are designed to connect the pins in that order.) Before suspecting software problems on the lab workstations, check the connector is fully home. Second, check that you don't have a power-only USB cable. Such cables are, in my experience, most commonly supplied for charging bike lights; they have the power and ground wires, but not the two wires that are used for transmitting data. If you use such a cable (or a poorly connected standard cable) to plug in a brand-new micro:bit, then out-of-box software will run, but the micro:bit will not show up as a drive on the host computer.
008 On a Mac, the linking step for Lab 1 may possibly find the wrong version of libgcc.a. The symptom is that the integer division subroutine doesn't work, and the program crashes after printing "foo(" and before converting the argument to decimal for printing.
This is potentially due to misconfiguration or misguided Makefile editing by the participant. A good compromise would be to provide, commented out, the linking command that invokes gcc, so that it can be enabled in case of difficulty.
003 Adding a delay between successive characters output by serial_putc (such as simulating the seven stars of death) leads to a lock-up if characters are typed too quickly.
This happens for a similar reason to problem 002, because the serial_getc routine uses serial_putc to echo each character of input. If that is too slow, an overrun error is the result. The solution is to have the serial I/O and blinking lights run by independent processes: watch this space.
002 Typing in the minicom window when the echo or add program is stopped in the debugger leads to a lock-up.
This is inevitable: when the program is stopped, it is not able to fetch characters from the UART buffer quickly enough, and the UART enters an error state (see also this FAQ entry). Simple programs like those in Labs 0 and 1 assume they are able to fetch the characters fast enough to avoid this, and are not written to recognise or handle such error states, even when they are restarted by the debugger.

## Updating your working copy

The lab materials are delivered via a Mercurial repository. The first act on starting the labs is to make a clone of the master repository, which remains linked to the master for downloading updates. Your working copy consists of a replica of the master repostitory, together with 'checked out' copies of all the files in it, plus other files you have added yourself.

At any time you can safely download updates from the master repository to your own replica, without affecting your 'checked out' copies. The command for this is

$hg pull  (issued from any directory inside your working copy). If that command reports that new revisions have been downloaded, then you can incorporate them into your working copy with the command, $ hg up


This will keep the changes to files you have edited or added, and merge in the changes to other files from the repository. The only problem arises if a file has been edited both by you and by Mike as part of the new revision(s) in the repository. In this case, Mercurial tries to merge the changes, but it doesn't always succeed, and may report a 'conflict'. This is most likely to affect Makefiles, where you have manually incorporated a fix to the build process, and Mike has later added the fix to the master repoitory. If conflicts happen, the Makefile will contain a mixture of the two versions, with lines marked as coming from one or the other. Your original file is preserved as Makefile.orig. If you get into this situation, it's generally safe to go with the updated master copy of Makefile, but I suggest you ask us for help with the commands needed to resolve the situation.

A normal part of interaction with a version control system is to push your modifications back the server. In this case, the server is read-only for you, and attempts to push to it will be rejected. If you have improvements to suggest, you can send Mike a patch.