1 2EDU device 3========== 4 5.. 6 Copyright (c) 2014-2015 Jiri Slaby 7 8 This document is licensed under the GPLv2 (or later). 9 10This is an educational device for writing (kernel) drivers. Its original 11intention was to support the Linux kernel lectures taught at the Masaryk 12University. Students are given this virtual device and are expected to write a 13driver with I/Os, IRQs, DMAs and such. 14 15The devices behaves very similar to the PCI bridge present in the COMBO6 cards 16developed under the Liberouter wings. Both PCI device ID and PCI space is 17inherited from that device. 18 19Command 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 28PCI specs 29--------- 30 31PCI ID: 32 ``1234:11e8`` 33 34PCI Region 0: 35 I/O memory, 1 MB in size. Users are supposed to communicate with the card 36 through this memory. 37 38MMIO area spec 39-------------- 40 41Only ``size == 4`` accesses are allowed for addresses ``< 0x80``. 42``size == 4`` or ``size == 8`` for the rest. 43 440x00 (RO) : identification 45 Value is in the form ``0xRRrr00edu`` where: 46 - ``RR`` -- major version 47 - ``rr`` -- minor version 48 490x04 (RW) : card liveness check 50 It is a simple value inversion (``~`` C operator). 51 520x08 (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 570x20 (RW) : status register 58 Bitwise OR of: 59 60 0x01 61 computing factorial (RO) 62 0x80 63 raise interrupt after finishing factorial computation 64 650x24 (RO) : interrupt status register 66 It contains values which raised the interrupt (see interrupt raise 67 register below). 68 690x60 (WO) : interrupt raise register 70 Raise an interrupt. The value will be put to the interrupt status 71 register (using bitwise OR). 72 730x64 (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 780x80 (RW) : DMA source address 79 Where to perform the DMA from. 80 810x88 (RW) : DMA destination address 82 Where to perform the DMA to. 83 840x90 (RW) : DMA transfer count 85 The size of the area to perform the DMA on. 86 870x98 (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 97IRQ controller 98-------------- 99 100An IRQ is generated when written to the interrupt raise register. The value 101appears in interrupt status register when the interrupt is raised and has to 102be written to the interrupt acknowledge register to lower it. 103 104The device supports both INTx and MSI interrupt. By default, INTx is 105used. Even if the driver disabled INTx and only uses MSI, it still 106needs to update the acknowledge register at the end of the IRQ handler 107routine. 108 109DMA controller 110-------------- 111 112One has to specify, source, destination, size, and start the transfer. One 1134096 bytes long buffer at offset 0x40000 is available in the EDU device. I.e. 114one can perform DMA to/from this space when programmed properly. 115 116Example of transferring a 100 byte block to and from the buffer using a given 117PCI 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 ; 136