| released | permalink | title | toc |
|---|---|---|---|
true |
/assignments/assign7/ |
Assignment 7: System Monitor with Interrupts |
true |
{% comment %} Task list to copy/paste when creating PR for this assign:
Before releasing assign7:
- Review writeup/starter code (instructor)
- Consider changes for clarity of spec/ease of grading (TA)
- Followup on any github issue from previous
To prep for assign7:
- [ ]
{% endcomment %}
Written by Philip Levis, updated by Julie Zelenski
{% include duedate.html n=7 %}
Your Raspberry Pi now reads input from a keyboard and responds to your commands via a graphical console display, thanks to all your hard work on the keyboard, shell, graphics, and console modules. In this final week, you'll improve your keyboard driver so that you can type as fast as the wind without dropping characters. After completing this upgrade, you will have transformed your Raspberry Pi into a standalone computer, ready to be extended and improved in your final project!
In this assignment, you will
- Change your PS/2 keyboard driver to be interrupt-driven. From an external perspective, the keyboard module is unchanged, but it will have the internal smarts to detect bits as they arrive and save them, rather than relying on the call to
keyboard_read_scancodeto have come at the right time.
In addition, there is a second goal for those of you aiming for the complete system bonus:
- Bundle the collection of modules you've written into a complete, self-contained library and show off your console running on your library.
The amount of new code needed for this assignment is much less than in previous weeks. This should give you a little extra bandwidth to revisit any of your previous modules that need attention in order to claim the complete system bonus.
It's also time to start planning for your final project. Please refer to the project instructions for full information about the project schedule. The important step to attend to now is the team formation due Monday March 4. Fill in this Google form with your team members.
Navigate to your copy of the cs107e.github.io repository and do a git pull to be sure you have the latest versions of the courseware files.
As usual, your assign7-basic branch has been created for you. Navigate to your assignments directory and check out the new branch.
$ cd cs107e_home/assignments
$ git fetch origin
$ git checkout assign7-basic
You should also verify you have the up-to-date contents for all of your modules: timer.c, gpio.c,strings.c, printf.c, malloc.c, backtrace.c, keyboard.c, shell.c, fb.c, gl.c, and console.c. Note that the assign7-basic branch may contain an outdated version of your module if you pushed any new fixes to previous assignment branches. You may want to run git merge <previous assign branch> or copy over the previous modules to assign7-basic branch.
Pay careful attention to the assignment 7 Makefile: The starter Makefile assumes that you are going for the complete system bonus and MY_MODULES is set to use all of your own modules. If you need to use the reference implementation for some modules, you must edit the Makefile to remove them. If you later fix the issues and want to include those modules in your testing, you must edit the Makefile to add them back.
When submitting your completed assign 7, be sure the Makefile is set for the exact configuration you intend to be graded. If MY_MODULES contains all 11 modules, your work will be evaluated as such and will be considered for the complete system bonus. If you do not have confidence in one or more of your modules, remove them from MY_MODULES and the reference module will be used instead. Your work will be evaluated with the combination of your and reference modules as set by your Makefile and will not be eligible for the bonus.
First, read over the code in the starter tests/test_keyboard_interrupts.c and try it out with your existing keyboard driver. You should see that any keys typed while the test program is paused inside timer_delay will be missed. Employing interrupts to fix this is the focus of the final assignment.
You are going to modify how your keyboard driver reads PS/2 scancodes. Your current implementation of keyboard_read_scancode repeatedly polls the clock GPIO until it sees the level transition from high to low. If your code doesn't happen to be reading the GPIO at the essential moment, the event is lost. If you instead arrange for an interrupt to be generated by each falling edge, the interrupt handler jumps in and grabs the data bit before it passes by.
The amount of code you need to add is relatively small, but the code needs to be just right. Given that interrupt code can be very difficult to debug and bugs are non-deterministic, you will want to take epsilon-steps and save known working points you can revert to if necessary. Commit often!
Using your code from lab 7 as a reference, change your keyboard_init function
to set up your Pi so it will generate interrupts on the falling edge of the
clock line and attach a handler that responds to the event. Don't forget
to clear the event when you handle it, or the event will trigger forever.
As a starting point, the version of the interrupt handler could simply increment a global counter of interrupts received. Modify the tests/test_keyboard_interrupts.c program to add your own test main function that watches the global counter and prints the updated value when it changes.
Each scancode should generate 11 interrupts: one for the start bit, 8 for the data bits, one for the parity bit, and one for the stop bit. A standard typed key consists of 3 scancodes (1 for key down and 2 for key up) so should generate 33 interrupts in total.
Test that your code to see the count of interrupts received and don't move on until you verify this code works correctly.
Remember, the code in an interrupt handler should be simple and streamlined. This is both because you don't want to delay the processing of the next interrupt and because debugging interrupts
can be so hard. Putting a printf in your handler would likely cause you to miss a closely-following event, for example.
Extend your interrupt handler so that it reads a bit from the PS/2 data line. Because the handler reads a single bit at a time, you will need to store the bits as they come until you've received a full scan code. Be sure to retain the logic to synchronize on the start bit and verify the parity and stop bits.
Upon receiving the stop bit, write the completed scancode to a global variable. Have your test main watch for a change to that global variable and print the scancode when complete.
(As a side note, the reference version of the keyboard module is capable of reading either by polling or by interrupts. Our module includes a function keyboard_use_interrupts(), which can be called to change the read mode. Your keyboard does not need to support this feature. You can directly re-purpose your previous code to read scancodes to instead read via interrupts without trying to preserve the old way of doing things.)
Almost there! The scancode read by the interrupt handler will be handed over to
the now-gutted keyboard_read_scancode by storing it in a queue implemented using an interrupt-safe ring buffer as described in lecture. Review the header and source files (cs107e/include/ringbuffer.h , cs107e/src/ringbuffer.c) to learn more about this data structure.
When a correct, complete scancode is read, have your handler enqueue it. Rewrite keyboard_read_scancode such that it dequeues a scancode if one is available, or spins waiting while the queue is empty. Note how a call to keyboard_read_scancode behaves as before to
the caller: it returns a scancode, either one that was already ready or waits
for the next one. Because it now uses a queue, keyboard_read_scancode no longer misses scancodes that came in when the caller wasn't ready to ask for them.
Once you get this working, you should be able to run your console shell application as in assignment 6, and all should work as before, except this time you never miss a key.
You now have a fully operational console that uses the full power of your hardware! What you have running is not too far from an Apple II computer.
The make lib target of the Makefile takes the modules named in MY_MODULES and bundles them into a single library libmypi.a.
If your libmypi.a uses only your own libpi modules for this assignment (no use of reference modules) and your interrupt-driven console works correctly,
you will receive a full 10-point bonus. This is a big reward for a big
accomplishment -- you have built the complete system yourself, from the ground up!
To be considered for the bonus, libmypi.a must use your own code
for all modules. We will not re-test your individual modules to the extent that they were
tested when grading each assignment, but all shell commands should at
least work correctly. This means, for example, your printf must handle
printing padded hexadecimal numbers (which are needed for peek), but
need not necessarily handle negative values perfectly (since they are
not used in the full shell).
If you fulfill this bonus, you've successfully built a complete computer system, and every line of code for that system is sitting in your assign7 folder. Congratulations!
That libmypi.a is a complete library that packages up all your battle-tested code in a form ready to be incorporated into any future project. Here is
a sample, bare-bones project template
which builds with libmypi.
To start a new project, copy those template files into a folder, copy
your libmypi.a in, and assign CS107E in the Makefile to your
CS107e folder to locate the library header files. Then you should be able to make install right
away and see that the main() in main.c runs and prints "Hello,
world!" You can program your Pi almost like an Arduino with this
high-level library you wrote.
We have two proposed
extensions. Choose one OR the other (not both). Remember to create an
assign7-extension branch based off your assign7-basic branch with git checkout -b assign7-extension (this assumes you currently have your basic
branch checked out).
One extension is to add profiling support to your shell. A profiler is a developer tool that tracks where in the code a program is spending its execution time.
If trying to diagnose what to fix in a slow program, your first task would be to measure the program when it runs and find out where it spends most of its time. Speeding up those sections of the code will have the greatest effect on the overall run time.
There is a simple and clever way to do this using a sampling strategy. First, you configure the ARM timer to periodically interrupt your program. On each timer event, you record a sample of the PC. (Recall that the argument to the interrupt handler is the PC of the instruction that was about to execute at the time of the interruption.) The probability that a given value of the PC is the argument to the interrupt handler is proportional to the time spent executing that instruction. The more often that an instruction is executed, the more times the interrupt handler will be called with that PC. A profile is created by creating a histogram that counts the number of times the program is interrupted at each PC.
For this extension, you add periodic timer interrupts, and write profiling code that creates a histogram of the PCs. You will also add an new command to your shell to profile your program.
The header file cs107e/include/gprof.h declares the interface to the
profiling functions.
The profiling will maintain an array of counters, one for each instruction address in the text (code) segment.
There is a known address where the text segment starts (what value is that again?), but to know the extent, you will need to edit the linker map to mark the end. It may help to revisit lab4 for information on linker maps.
Open the project file memmap and, patterning after
how symbols are used to mark the bounds of the bss section, add a symbol to identify
the end of the text section. Use this symbol in gprof_init to compute the
correct amount of space needed to have a counter for each instruction in the text segment.
All of those counters should be initialized to zero at the start of profiling.
gprof_init should configure a timer interrupt scheduled for the
interval defined in gprof.c using the libpi armtimer module. (See
the header file
armtimer.h). Attach the function gprof_handler as an interrupt handler. gprof_handler takes one
argument, the value of the PC at the time of the interrupt, and will increment the counter for that value of the PC. Remember that all handler functions are called for all interrupts, so your handler should be sure to differentiate between GPIO and timer events so that it handles only the events it was intended to.
Add the command profile [on | off | status | results] to
your shell commands. profile on should initialize or zero-out all profile
counts and start profiling (enable timer interrupts). profile off should stop
the profiling (disable timer interrupts). profile status should print Status: on or Status: off, depending on whether the profiler is on or off,
respectively. profile results should print current (if status is on) or most
recent (if status is off) counts to the debugger console using the gprof_dump
function. The gprof_dump should print the highest 10 counts to the console (in any order).
The final touch for your profiler is to provide the function name that each high-count instruction belongs to. If you remember back to the backtrace function from assignment 4, compiling -mpoke-function-name will embed each function's name as a string of characters before its first instruction. Thus if you walk backwards from a given instruction to look for the "magic" byte that marks the name, you can dig out the function's name from that location.
For each high-count instruction, you should report the address of the instruction, the function it belongs to, the instruction offset within the function, and the count of samples recorded for that instruction. Thus your profiler results look something like this:
0x0000ae0c uart_putchar+36: 13358
0x0000be1c timer_get_ticks+16: 23219
0x0000be5c timer_delay_us+24: 36209
Cool, you now have a profiler!
For this extension, you'll write a small paint application using your
libmypi.a.
Make a paint subdirectory in your assign7 directory. We've
provided one starter file, mouse.c, but you'll add files around it
so that the paint directory is actually a complete standalone
application, with its own Makefile and everything.
Copy the starter project files in
cs107e.github.io/assignments/assign7/libmypi-usage into paint,
and copy your finished libmypi.a in as well.
Make sure you can build and run the "Hello, world" application right now.
Let's start implementing mouse support. Read these pages on the PS/2 protocol and PS/2 mouse specifically for details on how to talk to a mouse.
Connect your mouse clock and data lines to the appropriate GPIO pins. Add mouse.o to the OBJECTS in your Makefile.
Start by writing mouse_read_scancode. For now, just poll the clock pin
to wait for the falling edge and then read the data pin; the logic should be almost identical to your
old polling keyboard_read_scancode.
Next, implement mouse_write, the other half of the PS/2 protocol:
sending a byte from the Pi to the mouse. We need to tell the mouse to
set up before it'll send us anything. See "Host-to-Device
Communication" on the PS/2 protocol page for the full write
process. Here are some notes:
-
You need to temporarily reconfigure the mouse's clock and data GPIO pins as output pins so you can pull them low when needed. 'Release' (set as input again) the clock line after you delay 100 us and write the start bit, and release the data line after you write the parity bit and see a falling clock edge.
-
Over the course of a write, you should wait for a falling clock edge 11 times (before sending each of 8 data bits, before sending the parity bit, before releasing the data line, and before reading the acknowledgment bit from the mouse). After that last falling clock edge, spin until the data line goes high (that's the end of the ack bit transmission).
Now carry out the mouse initialization sequence (as specified on the
PS/2 mouse page) in mouse_init:
- Write a Reset scancode to the mouse to put it in Reset mode.
- Read the ACK scancode from the mouse (should be 0xFA).
- Read the BAT Successful scancode from the mouse (should be 0xAA).
- Read the Device ID scancode from the mouse (should be 0x00).
- Write the Enable Data Reporting scancode to the mouse.
- Read the ACK scancode from the mouse (should be 0xFA).
Run mouse_init from main.c and confirm that the mouse is sending.
you the scancodes you expect during this sequence. After calling
mouse_init, you should be able to read and print movement scancodes
from the mouse in a loop.
Next, let's use interrupts to read scancodes from the mouse instead of polling.
Set your mouse clock GPIO to detect falling edge events and attach a mouse_handler function to handle the interrupt. mouse_handler reads a single bit per interrupt, gathers the bits until a full scancode is received and enqueues the scancode on the ring buffer. This function is a near-identical twin to your keyboard_handler, the only change being to read from the GPIO pins used for the mouse clock and data in place of those used for the keyboard.
Then make mouse_read_scancode pull a scancode out of the ring
buffer instead of polling. Make sure you can still read scancodes in a
loop.
Now implement the high-level mouse_read_event function on top, which
you will call from your paint program to read mouse-movement
events. See the cs107e/include/mouse.h file for more details on the
mouse_event_t structure, and consult the PS/2 mouse page to find how
scancode bits map to event details. Be careful about the 9-bit two's
complement representation of distances! Test this function with a loop
in main.c.
Now you can read mouse events! Finally, implement a paint application
in main.c: initialize the graphics library in single-buffer mode,
then loop, reading mouse events and drawing on the screen in response
to them.
It should be possible to:
- draw stuff [like a smiley face :-)] by holding down the left mouse button and moving the mouse
- when not holding down the button, move some mouse pointer-like shape around on the screen without disrupting stuff that's been painted
Other than that, the details of the UI are up to you. Describe in your README how we should use your paint program!
Commit your code to your repository and make a pull request.
Make sure you add all the necessary source files to Git so that we can clone your assignment and build and run it. If you are aiming for the complete system bonus, double-check that all of your libpi source files are added and committed to the repository. If you are submitting the paint extension, be sure all of the needed files in your paint subdirectory are committed as well.
One means to verify what was included with your submission is to push and then clone it again from GitHub in a separate assign7-clone folder. Build and run from this clone to be sure all essential files are present.
Three cheers for YOU! 👏👏 👏 This is your computer system, the one you built yourself from the ground up. Each line of code is there because you put it there, you know what it does, and why it is needed. We are in awe of the effort you put in to arrive here and hope you are as proud of your work as we are.
Reflecting on where you started, it has been an impressive journey. Take stock of the progress you have made on mastering these course learning goals:
- To understand how computers represent information, execute programs, and control peripherals.
- Binary and hexadecimal number systems, machine encoding of instructions
- Memory layout, pointers, arrays, structs
- ARM assembly, use of registers, instruction control flow
- Runtime use of stack and heap memory
- Memory-mapped I/O to access to peripherals, device drivers (keyboard, display)
- Interrupts, simple multi-processing
- To master command-line programming tools and the C programming language.
- Build tools (assembler, compiler, linker, make, bootloader)
- Implementation of standard C library functions (strings, printf, malloc, graphics)
- Strategies for testing and debugging code, using gdb
- Establishing a productive and effective programming workflow
Bring these skills into the final project, mix with your creativity and initiative, and something fabulous will surely result. We're looking forward to it!