[CSE]  Advanced Operating Systems 
COMP9242 2013/S2 
UNSW
CRICOS Provider
Number: 00098G

PRINTER Printer-Friendly Version

M1: A timer driver

Your first milestone is fairly straightfoward, and should only take you a few hours to complete. However, you should use this as an opportunity to get to used working with your partner, and probably work out exactly how you can work together so you don't end up duplicating work, or worse still not completing essential parts of the project.

Group Work & Version Control

By now you should have got yourself in a group and you should have a group account setup for you. We recommend that you use Mercurial (or another version control system of your choice) to maintain your source code, (this isn't a requirement, just a suggestion), and that a repository be setup in your group account with the correct permissions and sticky bits set so that you can both access it.

If you are using Mercurial, we recommend you set up the meld (or equivalent) merging tool as the default merge program to avoid painful merges.

Goals

The aim of this milestone is to design and implement device driver to accurately provide time stamps and trigger activities. You should add a file for the timer implementation and modify the main system call loop to handle timer interrupts.

  • Learn and understand the fundamentals of writing a device driver.
  • Play with real hardware.
  • Learn about interrupt handling in seL4.
  • Learn about memory mapped device access and control.
  • Time system behaviour on seL4.

Motivation

For many purposes, such as benchmarking, a high clock resolution is desired. The i.MX6 Sabre Lite platform features a clock controller module which contains several high-frequency and low-frequency counters which are used as timers. A high clock resolution timer is desirable for benchmarking, i.e. accurately measuring elapsed time for completion of some unit of work. Using the timer you implement in this milestone, you will be measuring the performance of the file system that you implement in milestone 6. Thus your timer needs to be capable of providing high resolution time stamps.

The Driver Interface

Your driver needs to export the interface specified in libs/libclock/include/clock/clock.h. There are the following functions:

int start_timer(seL4_CPtr interrupt_ep)
Initialises the driver.
int register_timer(uint64_t delay, seL4_CPtr client)
Registers the calling thread to receive an IPC message after a specified time interval (in microseconds, though actual wakeup resolution will depend on the timer resolution). Several registrations may be pending at any time. Note: As we do not have a system call interface yet, instead of waking up threads your implementation can print out a message showing who would have woken up, and the timestamp. This will also help you test your timer accuracy.

The IPC message sent by the timer contains in MR0 a return code (CLOCK_R_OK, CLOCK_R_UINT, CLOCK_R_CNCL) and in MR1 and MR2 the present value of the real-time clock.

timestamp_t time_stamp(void)
Returns the current real-time clock value (microsecond accurate).
int stop_timer(void)
Stops operation of the driver. This will cancel any outstanding timer requests (by sending them a premature IPC indicating failure).

The above interface is just an internal function call interface. You do not need to export this interface to the users. User programs will indirectly access the clock driver through the time and sleep syscalls that are implemented in a later milestone.

NOTE: After registering an interrupt, you must call seL4_IRQHandler_Ack to ensure the kernel in a sane initial state.

The i.MX6Q Sabre Lite

SabreLite architecture This is a block diagram of the i.MX6Q Sabre Lite. The Sabre Lite is a single chip computer (or system-on a chip, SoC) which has a Quad core ARM9 Cortex A9 processor and lots of integrated hardware. The SoC reference manual can be found here.

Although the Sabre is a complex platform with lots of functionality, we will only be implementing a driver for the Enhanced Periodic Interrupt Timer (EPIT) and/or General Purpose Timer (GPT) modules. If you are interested in device drivers for the other components in the chip, particularly the networking stacks then explore the directory libs/libethdrivers.

General Purpose Timer Modules

Your main job is to learn how to program the Sabre Lite's EPIT and/or GPT timers to generate timer interrupts and how to write a seL4 driver to handle these interrupts.

The Sabre Lite's i.MX6 SoC has many peripherals for various purposes, such as GPU, UART, video, watchdog and so on. For our purposes, we are interested in using the timers EPIT1, EPIT2 and GPT, to set them up as our sources of timer interrupts. The EPIT and GPT timer modules have very similar interfaces.

Implementing a device driver really just a matter of learning about its registers, what values to read and write to those registers, and when to do it. You may choose to start with implementing either the EPIT or the GPT timer. This milestone can be implemented with a single or multiple timers.

The minimal subset of a timer module's functionality that you must understand and use is listed below. You may find the registers for GPT are very similar to EPIT. Refer to Chapter 24, 30 and 18 of the i.MX6 SoC manual for more complete descriptions.

  • Timer Control Register (EPITx_CR, GPT_CR) : The actual timer/counters. You need to use at least one of them (take your pick). You will need to understand one of these to properly configure and enable the corresponding timers. As part of the configuration process, you will need to select an input clock to drive these timers. We recommend the Peripheral Clock (ipg_clk) which you may assume to be configured to 66MHz (see Chapter 18 of the i.MX6 reference manual).
  • Timer Counter Register (EPITx_CNR, GPT_CNT) : Use this register as the lower 32-bits of your timestamp value.
  • Timer Load Register (EPITx_LR): Contains the value that is to be loaded on EPIT overflow.
  • Timer Compare Register (EPITx_CMPR, GPT_OCRn): Contains the comparison value which will trigger a timer interrupt.
  • Timer Status (EPITx_SR, GPT_SR) : When an interrupt occurs, this register provides more information about the source of the interrupt. When you have finished processing the interrupt, you you must clear the appropriate flag in this register and then call seL4_IRQHandler_Ack to clear the interrupt event in the kernel. Note that writing a '1' to any bit in this register will clear the corresponding flag while writing a '0' will have no effect.

This is only the minimal understanding that you need. You are encouraged to explore other registers for a deeper understanding.

NOTE: This section is deliberately kept short (e.g., we do not dictate which timer to use or in what mode to use it in). The idea is for you to develop your own design and implementation. There are only two conditions that must be satisfied:

  1. You must use an interrupt generated from the EPIT or GPT timers.
  2. You must implement the driver interface described above.

Supplied Code

For this project you have been supplied with skeleton code to help you along the way. This code is intended as an implementation guide, not as a 'black-box' library.

It is important that you fully understand all provided code that you use. For the purposes of assessment, we treat any supplied code that you call as your code and as such you may be asked to describe how it works.

Now might be a good time to get familiar with the resources, e.g. the framework documentation

seL4/ARM Interrupts

The seL4/ARM kernel exports specific interrupts to a user level interrupt handler via asynchronous notification.

You will need to perform a series of steps to register to receive interrupts and manage interrupts for the timer device.

  • You need to create an interrupt handling cap using our cspace library irq_handler = cspace_irq_control_get_cap(cur_cspace, seL4_CapIRQControl, irq) (See libsel4cspace documentation and Chapter 3 of the i.MX6 reference manual).
  • We have already created and bound an async endpoint within the framework we have given you. Its cptr is _sos_interrupt_ep_cap. You should register your new interrupt handler with the kernel and direct it to forward the interrupt to the provided async endpoint seL4_IRQHandler_SetEndpoint(irq_handler, _sos_interrupt_ep_cap)

Before attempting this, you should read Chapter 5 of the sel4 documentation to gain an understanding of TCBs, and Section 7.1 to understand how interrupts are delivered.

Device Mappings

In seL4/ARM, device registers are memory mapped. That is, hardware registers can be accessed via normal load/store operations to special addresses. To access device registers, you must first map the device into the driver's virtual address space with the appropriate attributes. A function to achieve this has been provided for you in apps/sos/src/mapping.c.

Issues

You may need to resolve some or all of these issues:

  • At what address do the EPIT or GPT registers need to be mapped and accessed through?
  • What value must be programmed to the timer to get a frequency of x milliseconds?
  • How are the interrupts acknowledged?
  • Periodic timer ticks or variable length time-outs (a so called tickless kernel)?
  • Single or multi-threaded driver?
  • Which data structures should I use?

Assessment

You should be able to show some test code that uses all the functions specified in the driver interface. Specifically set up and demonstrate:

  • A regular 100ms timer tick. Set up your timer to fire an interrupt every 100ms. Then, print the value returned by time_stamp every time this interrupt is received. This should not use register_timer, as this regular tick will later be used to call a function in the NFS library to allow your NFS file system to implement time-outs. Note: This component can share a single (and some underlying code), or it can use a separate dedicated hardware timer. Note: Your timestamps must be more accurate than this regular 100ms tick.
  • Before entering the main system call loop, set up a few calls to register_timer. Make sure the delay used is long enough such that the system call loop is entered before these wake up. As register_timer does not IPC any threads yet, we should see print outs of the timestamp as each delay expires. This part is only as a demo, and can be removed after the milestone demonstration. You will later use register_timer to implement a sleep system call for your user-level processes.

Last modified: 02 Aug 2013.