linux-user: arm: Remove ARM_cpsr and similar #defines
[qemu.git] / docs / specs / edu.txt
1
2 EDU device
3 ==========
4
5 Copyright (c) 2014-2015 Jiri Slaby
6
7 This document is licensed under the GPLv2 (or later).
8
9 This is an educational device for writing (kernel) drivers. Its original
10 intention was to support the Linux kernel lectures taught at the Masaryk
11 University. Students are given this virtual device and are expected to write a
12 driver with I/Os, IRQs, DMAs and such.
13
14 The devices behaves very similar to the PCI bridge present in the COMBO6 cards
15 developed under the Liberouter wings. Both PCI device ID and PCI space is
16 inherited from that device.
17
18 Command 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
26 PCI specs
27 ---------
28
29 PCI ID: 1234:11e8
30
31 PCI Region 0:
32    I/O memory, 1 MB in size. Users are supposed to communicate with the card
33    through this memory.
34
35 MMIO area spec
36 --------------
37
38 Only size == 4 accesses are allowed for addresses < 0x80. size == 4 or
39 size == 8 for the rest.
40
41 0x00 (RO) : identification (0xRRrr00edu)
42             RR -- major version
43             rr -- minor version
44
45 0x04 (RW) : card liveness check
46             It is a simple value inversion (~ C operator).
47
48 0x08 (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
53 0x20 (RW) : status register, bitwise OR
54             0x01 -- computing factorial (RO)
55             0x80 -- raise interrupt 0x01 after finishing factorial computation
56
57 0x24 (RO) : interrupt status register
58             It contains values which raised the interrupt (see interrupt raise
59             register below).
60
61 0x60 (WO) : interrupt raise register
62             Raise an interrupt. The value will be put to the interrupt status
63             register (using bitwise OR).
64
65 0x64 (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
70 0x80 (RW) : DMA source address
71             Where to perform the DMA from.
72
73 0x88 (RW) : DMA destination address
74             Where to perform the DMA to.
75
76 0x90 (RW) : DMA transfer count
77             The size of the area to perform the DMA on.
78
79 0x98 (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
84 IRQ controller
85 --------------
86 An IRQ is generated when written to the interrupt raise register. The value
87 appears in interrupt status register when the interrupt is raised and has to
88 be written to the interrupt acknowledge register to lower it.
89
90 DMA controller
91 --------------
92 One has to specify, source, destination, size, and start the transfer. One
93 4096 bytes long buffer at offset 0x40000 is available in the EDU device. I.e.
94 one can perform DMA to/from this space when programmed properly.
95
96 Example of transferring a 100 byte block to and from the buffer using a given
97 PCI address 'addr':
98 addr     -> DMA source address
99 0x40000  -> DMA destination address
100 100      -> DMA transfer count
101 1        -> DMA command register
102 while (DMA command register & 1)
103         ;
104
105 0x40000  -> DMA source address
106 addr+100 -> DMA destination address
107 100      -> DMA transfer count
108 3        -> DMA command register
109 while (DMA command register & 1)
110         ;