docs/specs/edu.rst

   1
   2 EDU device
   3 ==========
   4
   5 ..
   6    Copyright (c) 2014-2015 Jiri Slaby
   7
   8    This document is licensed under the GPLv2 (or later).
   9
  10 This is an educational device for writing (kernel) drivers. Its original
  11 intention was to support the Linux kernel lectures taught at the Masaryk
  12 University. Students are given this virtual device and are expected to write a
  13 driver with I/Os, IRQs, DMAs and such.
  14
  15 The devices behaves very similar to the PCI bridge present in the COMBO6 cards
  16 developed under the Liberouter wings. Both PCI device ID and PCI space is
  17 inherited from that device.
  18
  19 Command line switches
  20 ---------------------
  21
  22 ``-device edu[,dma_mask=mask]``
  23     ``dma_mask`` makes the virtual device work with DMA addresses with the given
  24     mask. For educational purposes, the device supports only 28 bits (256 MiB)
  25     by default. Students shall set dma_mask for the device in the OS driver
  26     properly.
  27
  28 PCI specs
  29 ---------
  30
  31 PCI ID:
  32    ``1234:11e8``
  33
  34 PCI Region 0:
  35    I/O memory, 1 MB in size. Users are supposed to communicate with the card
  36    through this memory.
  37
  38 MMIO area spec
  39 --------------
  40
  41 Only ``size == 4`` accesses are allowed for addresses ``< 0x80``.
  42 ``size == 4`` or ``size == 8`` for the rest.
  43
  44 0x00 (RO) : identification
  45             Value is in the form ``0xRRrr00edu`` where:
  46             - ``RR`` -- major version
  47             - ``rr`` -- minor version
  48
  49 0x04 (RW) : card liveness check
  50             It is a simple value inversion (``~`` C operator).
  51
  52 0x08 (RW) : factorial computation
  53             The stored value is taken and factorial of it is put back here.
  54             This happens only after factorial bit in the status register (0x20
  55             below) is cleared.
  56
  57 0x20 (RW) : status register
  58             Bitwise OR of:
  59
  60             0x01
  61               computing factorial (RO)
  62             0x80
  63               raise interrupt after finishing factorial computation
  64
  65 0x24 (RO) : interrupt status register
  66             It contains values which raised the interrupt (see interrupt raise
  67             register below).
  68
  69 0x60 (WO) : interrupt raise register
  70             Raise an interrupt. The value will be put to the interrupt status
  71             register (using bitwise OR).
  72
  73 0x64 (WO) : interrupt acknowledge register
  74             Clear an interrupt. The value will be cleared from the interrupt
  75             status register. This needs to be done from the ISR to stop
  76             generating interrupts.
  77
  78 0x80 (RW) : DMA source address
  79             Where to perform the DMA from.
  80
  81 0x88 (RW) : DMA destination address
  82             Where to perform the DMA to.
  83
  84 0x90 (RW) : DMA transfer count
  85             The size of the area to perform the DMA on.
  86
  87 0x98 (RW) : DMA command register
  88             Bitwise OR of:
  89
  90             0x01
  91               start transfer
  92             0x02
  93               direction (0: from RAM to EDU, 1: from EDU to RAM)
  94             0x04
  95               raise interrupt 0x100 after finishing the DMA
  96
  97 IRQ controller
  98 --------------
  99
 100 An IRQ is generated when written to the interrupt raise register. The value
 101 appears in interrupt status register when the interrupt is raised and has to
 102 be written to the interrupt acknowledge register to lower it.
 103
 104 The device supports both INTx and MSI interrupt. By default, INTx is
 105 used. Even if the driver disabled INTx and only uses MSI, it still
 106 needs to update the acknowledge register at the end of the IRQ handler
 107 routine.
 108
 109 DMA controller
 110 --------------
 111
 112 One has to specify, source, destination, size, and start the transfer. One
 113 4096 bytes long buffer at offset 0x40000 is available in the EDU device. I.e.
 114 one can perform DMA to/from this space when programmed properly.
 115
 116 Example of transferring a 100 byte block to and from the buffer using a given
 117 PCI address ``addr``:
 118
 119 ::
 120
 121   addr     -> DMA source address
 122   0x40000  -> DMA destination address
 123   100      -> DMA transfer count
 124   1        -> DMA command register
 125   while (DMA command register & 1)
 126       ;
 127
 128 ::
 129
 130   0x40000  -> DMA source address
 131   addr+100 -> DMA destination address
 132   100      -> DMA transfer count
 133   3        -> DMA command register
 134   while (DMA command register & 1)
 135       ;