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