COSC440

Assignment 2 - driver for a dummy GPIO port device (30%)

In this assignment, you are going to design and code a driver for a dummy GPIO port device. The device has a virtual port of half-byte (4 bits). Every time the data is ready at the port, an interrupt is triggered by the device. The IRQ number of the device is assigned automatically by the kernel, which you can find out from the init() function of the dummy GPIO device.

A device node named /dev/asgn2 should be created for this device driver. The device should be read-only and only one process is allowed to open the device at a time.

A user-space program provided by us will write to the dummy port half-byte by half-byte and when each half-byte is put to the port, an interrupt will be signalled to the CPU.

The interrupt handler in your module should be triggered to read the port and store the half-byte. Every pair of half-bytes should be assembled into one byte that is stored to a circular buffer. A bottom-half (tasklet) should be used to read data in the circular buffer to a buffer pool (e.g. a page list). The data in the buffer pool is ready for a reader to consume. The device should behave like a pipe (a byte stream) between the dummy port and the reader.

Each session is demarcated by a '\0' (NULL) character. The reader should be able to read up to the next NULL. (The NULL character itself is not copied to the user-space reader.) Then the reader should not be allowed to read anything until it close() the device. Then the next reader queued will open the device and read the next session.

The test commands should be:

data generator: (each file represents a session) 

$ sudo ./data_generator <file 1> <file 2>...

reader: (to read a session) 

$ cat /dev/asgn2

The content read by the reader should be the same as put by the data_generator.
Note: use only txt (ASCII) file for testing.

The user-space data generator program can be downloaded at here. For test purposes, you need to create a dummy module by adding the two gpio functions in gpio.c, gpio_dummy_init() and gpio_dummy_exit(), into the module's __init and __exit functions respectively. Then install the dummy module and use sendhalfbyte to test individual pins.

Preparing your system to install the dummy port device

Before connecting the dummy port device below to your Raspberry Pi (RPI), you MUST shutdown your RPI and disconnect the power supply.

Carefully unclip and lift up the lid of your RPI. You will see the board as below. Caution: when handling RPI, DO NOT touch anything else except the metals lablled as GROUND in the image of the RPI board below.

You will see 40 pins on the top right side of board above. These 40 pins are labelled as below.

Then you should use jump wires to connect the 11 pins of the dummy port device to the corresponding pins on the board. Make sure you connect the pins with the same label using the same wire. There are two GROUND pins on the dummy port device and you can connect any of them to the GND pin on the board. Double check you have connected all pins correctly before turning on power. A wrong connection could DAMAGE the RPI!

The code gpio.c for handling the dummy port is here. You just need to initialise the port using gpio_dummy_init(void) and release the port using gpio_dummy_exit(void). Use read_half_byte(void) to read the half-byte from the port. The IRQ number requested for the dummy port will be displayed once gpio_dummy_init(void) succeeds.

Requirements

  1. The module should be read-only and only one reader can open /dev/asgn2 and other processes should wait for the current reader to finish
  2. Data races should be carefully prevented
  3. The reader should get exactly what the data generator put to the dummy port
  4. When /dev/asgn2 is busy (used by a reader), open() should wait (being suspended) until it is available
  5. When there is no data in the buffer pool, the current reader should wait for data; when there is any data available, the current reader should wake up immediately.

Assessment schedule

  • 20% for working code
  • 8% for a 1-page report discussing possible design issues, particularly on data race preventation and security issues.
  • 2% for understandable comments

Submission due date: 4pm Wednesday 20 September.