drivers for l4-hurd

[Daniel Wagner]

Hello

Peter De Schrijver and I started to write a proposal for a driver
framework for l4-hurd. We would like to here some feedback. As I said
it's just a draft and nothing definitive.




Main Menu
*********

   This is Edition 0.1, last updated 2002-11-26, of `L4 Hurd Device
Driver Framework'.

Introduction
************

   This is a draft of a l4-hurd-devicedriver-framework.

   This document is intented to describe exaclty how we plan to
implenent drivers for the Hurd port to L4. Jork Löser and Michael
Hohmuth describe in their paper (1)  about a portable interface to
interrupt hardware for L4 system. We won't implement exactly this
interface but something simalery which will be explained in this
document.

   XXX I took some paragraphs from the mentioned L4 papers. I didn't
ask yet. So don't distribute it yet. I might have to rewrite some parts.

   ---------- Footnotes ----------

   (1) J. Löser, M. Hohmuth. Omega0: A portable interface to interrupt
hardware for L4 systems. Dresden University of Technology, Departement
of Computer Sience, D-01062 Dresden, Germany. URL: www.l4ka.org /* XXX
url? */

Audience
========

   To whom it may concern... No, no. Everybody who is interested to hack
on Hurd.

Overview
========

   Requirements:   - Performance   - Portability   - Flexibility (hot
plugging of devices etc)   - Convenient interfaces   - Consistency   -
Safety : driver failure should have as minimal system impact as
possible.    - Hurdish !

Structure
*********

   The framework basically consists of 2 kinds of objects: Bus drivers
and Device drivers.

Bus Drivers
===========

   A bus driver is responsible to manage the bus and provide access to
devices connected to it. In practice it means a bus driver has to
perform the following tasks:

Handle hotplug events
     Busses which do not support hotplugging, will treated   as if
     there is 1 insertion event for every device connected to it when
     the   bus driver is started. Drivers which don't support
     autoprobing of devices   will probably have to read some
     configuration data from a file. In some cases   the bus doesn't
     generate insertion/removal events, but can still support some
     form of hotplug functionality if the user tells the driver when a
     change to   the bus configuration has happened (eg. SCSI).

Configure client device drivers
     The bus driver should start the appropriate   client device driver
     translator when an insertion event is detected. It   should also
     provide the client device driver with all necessary
     configuration info, so it can access the device it needs. This
     configuration   data typically consists of the bus addresses of
     the device and possibly IRQ   numbers or DMA channel ID's.

Handle powermanagement
     A bus driver should be able to power up or down the   bus it is
     responsible for. Obviously it should notify the device drivers
     of the devices connected to the bus of the new powerstate.

Provide access to devices
     This means the bus driver should be able to   perform a bus
     transaction on behalf of a client device driver. In some   cases
     this involves sending a message and waiting for reply (eg. SCSI,
     USB, IEEE 1394, Fibre Channel,...). The driver should provide
     send/receive   message primitives in this case. In other cases
     devices on the bus can be   accessed by doing a memory accesses or
     by using special I/O instructions.    In this case the driver
     should provide mapping and unmapping primitives so   a client
     device driver can get access to the memory range or is allowed to
     access the I/O addresses. The client device driver should use a
     library,   which is bus dependant, to access the device on the
     bus. This library hides   the platform specific details of
     accessing the bus.

Device Drivers
==============

   Generic operations:

start
     Initialize hardware and internal states of the driver and prepare
     the device for normal operation. Part of this work can be done
     when   the driver is started, part of it when the device is opened
     by an   application.

stop
     Stop the hardware and cleanup all state in the driver. (This
     operation   also has to work if the hardware is removed from the
     system). This is   necessary because a device can be unplugged and
     the device driver has   to be notified.

suspend
     Put the hardware in low power mode and save all the necessary state
      for resume

resume
     Reenable the device and restore the state saved at suspend time.

   We want interfaces to devices to be as uniform as possible, while
still being able to use the capabilities of specific device. I devised
a number standard interface classes devices can provide. Obviously not
all interface classes are applicable to all devices.

   Classes:
character devices
     This the standard tty as known in the Unix environment.

block

human input
     (Keyboard/mouse/...)

packet switched network

    send packet

    receive packet

    get/set HW filtering

    get/set maximum packet size

    get statistics

circuit switched network

framebuffer

streaming audio

streaming video

solid state storage (Flash memory)

    get size

    get erase block size

    get write block size

    erase block

    read/write block

...
Human input devices (HID)
-------------------------

Powermanagement
---------------

Drivers and the filesystem
--------------------------

   Each bus driver is an active translator. The translator will provide
a filesystem node for each device attached to the bus. These nodes will
be used by the device driver to get access to the device. I will give
an example to make this more clear. Note that this tree is dynamic!

   Example: Consider the PCI devices in my laptop:

00:00.0 Host bridge: Intel Corp. 440BX/ZX/DX - 82443BX/ZX/DX Host bridge (rev 
03)
00:01.0 PCI bridge: Intel Corp. 440BX/ZX/DX - 82443BX/ZX/DX AGP bridge (rev 03)
00:02.0 CardBus bridge: Texas Instruments PCI1450 (rev 03)
00:02.1 CardBus bridge: Texas Instruments PCI1450 (rev 03)
00:03.0 Ethernet controller: Intel Corp. 82557/8/9 [Ethernet Pro 100] (rev 09)
00:03.1 Serial controller: Xircom Mini-PCI V.90 56k Modem
00:05.0 Multimedia audio controller: Cirrus Logic CS 4614/22/24 [CrystalClear 
SoundFusion Audio Accelerator] (rev 01)
00:07.0 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ISA (rev 02)
00:07.1 IDE interface: Intel Corp. 82371AB/EB/MB PIIX4 IDE (rev 01)
00:07.2 USB Controller: Intel Corp. 82371AB/EB/MB PIIX4 USB (rev 01)
00:07.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 03)
01:00.0 VGA compatible controller: ATI Technologies Inc Rage Mobility P/M AGP 
2x (rev 64)

   This would result in the following device tree:

/servers/hardware/pci0-+
                       |-bridge00-AGP-+
                                      |-1002:4c4d
                       |-bridge01-Cardbus
                       |-bridge02-Cardbus
                       |-bridge03-ISA
                       |-bridge04-IDE
                       |-bridge05-USB
                       |-bridge06-ACPI
                       |-8086:1229
                       |-115D:000c
                       |-1013:6003

   For each of the buses we have one bus driver:
/servers/hardware/
     This is the 'rootbus' driver. It abstracts the interface between
     the CPU   and the I/O system. It knows which I/O buses are
     connected to the CPU and   knows where in the CPU physical address
     space they are located.

/servers/hardware/pci0
     This is the PCI hostbridge driver. It will get its resources from
     its parent,   the rootbus driver. It will assign resources to all
     devices and bridges   attached to it and load the appropriate
     device and bus drivers.

/servers/hardware/pci0/bridge00-AGP
     This is the AGP bridge driver. It will get its resources from its
     parent,   the PCI hostbridge driver. It will assign resources to
     all devices attached   to it.

/servers/hardware/pci0/bridge0[1-2]-Cardbus
     This is the Cardbus bridge driver. It will get its resources from
     its   parent, PCI hostbridge driver. It will watch card insertion
     and removal   events and load the appropriate driver.

/servers/hardware/pci0/bridge03-ISA
     This is the ISA bus driver. As ISA does not support autoconfig (at
     least not   all ISA devices support autoconfig). The driver will
     either have to rely on   adhoc probes or have a list of devices.
     It will load all drivers for the   devices attach to the ISA bus.

/servers/hardware/pci0/bridge04-IDE
     This is the IDE bus driver. It will probe for all the devices
     attached to   the IDE channels and load the approriate device
     driver. The device driver   will use IDE bus driver to handle all
     the transactions.

/servers/hardware/pci0/bridge05-USB
     This is the USB bus driver. It will watch device insertion and
     removal   events and load the appropriate device driver. The
     device driver will use   the USB bus driver to handle USB
     transactions.

/servers/hardware/pci0/bridge06-ACPI
     XXX Fix Me

/servers/hardware/pci0/8086:1229
     This is the entry for the Intel EEPRO 100 ethernet controller. The
     eepro   device driver will open this 'file' to talk to the eepro
     chip.

/servers/hardware/pci0/115D:000c
     This is the entry for the Lucent modem hardware. Good luck writing
     a driver   for this one.

/servers/hardware/pci0/1013:6003
     This is the entry for the cirrus logic audio chip.

/servers/hardware/pci0/bridge00-AGP/1002:4c4d
     This is the entry for the ATI Rage Mobility video controller.

Resource Management
*******************

IRQ handling
============

IRQ based interrupt vectors
---------------------------

   Some CPU architectures (eg 68k, IA32) can directly jump to an
interrupt vector depending on the IRQ number. This is typically the
case on CISC CPU's. In this case there is some priorization scheme. On
IA32 for example, the lowest IRQ number has the highest priority.
Sometimes the priorities are programmable.  Most RISC CPU's have only a
few interrupt vectors which are connected external IRQs. (typically 1
or 2). This means the IRQ handler should read a register in the
interrupt controller to determine which IRQ handler has to be executed.
Sometimes the hardware assists here by providing a register which
indicates the highest priority interrupt according to some
(programmable) scheme.

IRQ acknowlegdement
-------------------

   The IRQ acknowledgement is done in two steps. First inform the
hardware about the successful IRQ acceptance. Then inform the ISRs
about the IRQ event.

Edge versus level triggered IRQs
--------------------------------

   Edge triggered IRQs typically don't need explicit acknowledgment by
the CPU at the device level. You can just acknowledge them at the
interrupt controller level.  Level triggered IRQs typically need to
explicitly acknowledged by the CPU at the device level. The CPU has to
read or write a register from the IRQ generating peripheral to make the
IRQ go away. If this is not done, the IRQ handler will be reentered
immediatly after it ended, effectively creating an endless loop.
Another way of preventing this would be to mask the IRQ.

Multiple interrupt controllers
------------------------------

   Some systems have multiple interrupt controllers in cascade. This is
for example the case on a PC, where you have 2 8259 interrupt
controllers. The second controller is connected to the IRQ 2 pin of the
first controller. It is also common in non PC systems which still use
some standard PC components such as a Super IO controller. In this case
the 2 8259's are connected to 1 pin of the primary interrupt
controller. Important for the software here is that you need to
acknowledge IRQ's at each controller. So to acknowledge an IRQ from the
second 8259 connected to the first 8259 connected to another interrupt
controller, you have to give an ACK command to each of those
controllers.  Another import fact is that on PC architecture the order
of the ACKs is important.

Shared IRQs
-----------

   Some systems have shared IRQs. In this case the IRQ handler has to
look at all devices using the same IRQ...

IRQ priorities
--------------

   All IRQs on L4 have priorities, so if an IRQ occurs any IRQ lower
then the first IRQ will be blocked until the first IRQ has been
acknowlegded.  ISR priorities must much the hardware priority (danger
of priority inversion).  Furthermore the IRQ acknowledgment order is
important.

   The 8259 also supports a specific IRQ acknowledge iirc. But, this
scheme does not work in most level triggered IRQ environments. In these
environments you must acknowledge (or mask) the IRQ before leaving the
IRQ handler, otherwise the CPU will immediately reenter the IRQ handler,
effectively creating an endless loop. In this case L4 would have to mask
the IRQ. The IRQ thread would have to unmask it after acknowledgement
and processing.

IRQ handling by L4/x86
----------------------

   The L4 kernel does not handle IRQ acknowlegdment. For each IRQ is a
thread assigned which has to do the acknowlegdment. But the IRQ threads
has to know how the PIC is programmed.

Omega0
======

   Omega0 is a system-central IRQ-logic server. Instead of hiding all
IRQ logic from device drivers like the proposal [1], we decided to
allow drivers to set up their own ISR. Doing so, we hope to keep the
latency of handling a IRQ event low. The idea is to have a shared
library with certain prototypes of ISR which can be installed into a
specific IRQ thread.

   If an IRQ is shared between several devices, all registered ISR will
be activated (in random order). The IRQ handler would be responsible
for acknowledging the IRQ at the PIC level. Each ISR would be
responsible for acknowledging the IRQ at the device level (if
necessary).

   L4 hooks all CPU interrupt vectors and can signal one thread when a
specific interrupt vector is activated by the CPU.  Omega0 consists of
a number of threads which all live in 1 small AS.  There is 1 thread
per interrupt vector which is used by a device driver.  (We assume
unused IRQs are masked). This thread is responsible for acknowledging
the IRQ at the PIC level and unmasking the IRQ. This thread also calls
all ISRs provided by the device drivers requesting the IRQ. An ISR is a
small piece of code which is loaded into the Omega0 AS by the Omega0
management thread. The ISR could reside in a shared library or be sent
to the management thread via an IPC message.  The ISR should
acknowledge the IRQ at the device level and perform any latency
critical tasks (such as filling/emptying fifo's, ...) It should report
the device status to a thread of the device driver using IPC.  This
thread can then do all necessary processing for the event.  For most
devices using busmastering the ISR can probably consist of a few lines
of code reading a status register, acknowledging the IRQ by writing to a
register if necessary and sending the status via IPC to the driver. The
driver can in it's turn process the data written in memory by the
hardware and pass it to the higher layer software. In case the device
has low latency requirements (eg. a softmodem driver which needs to
read/write fifo's at 8Khz), the ISR performs the low latency part of
the work and passes the rest on to the device driver thread(s).

IO
==

Memory
======

Drivers
*******

Hardware Bus
============

Hardware Bus
============

PCI services
------------

   pci_find_device: search for PCI device by vendor/device id
pci_read_config_byte: read configuration BYTE register of PCI device
pci_write_config_byte: write configuration BYTE register of PCI device

Bootstraping
************

   XXX How do we boot the system?

Documentation License
*********************

   This manual is copyrighted and licensed under the GNU Free
Documentation license.

Concept Index
*************

FDL, GNU Free Documentation License:
          See ``GNU Free Documentation License''.
Function and Data Index
***********************

Short Contents
**************

Main Menu
Introduction
Structure
Resource Management
Drivers
Bootstraping
Documentation License
Concept Index
Function and Data Index


Table of Contents
*****************


Main Menu

Introduction
  Audience
  Overview

Structure
  Bus Drivers
  Device Drivers
    Human input devices (HID)
    Powermanagement
    Drivers and the filesystem

Resource Management
  IRQ handling
    IRQ based interrupt vectors
    IRQ acknowlegdement
    Edge versus level triggered IRQs
    Multiple interrupt controllers
    Shared IRQs
    IRQ priorities
    IRQ handling by L4/x86
  Omega0
  IO
  Memory

Drivers
  Hardware Bus
  Hardware Bus
    PCI services

Bootstraping

Documentation License
  GNU Free Documentation License
      ADDENDUM: How to use this License for your documents

Concept Index

Function and Data Index