cbdma: add documentation
[akaros.git] / Documentation / cbdma.md
1 Intel CBDMA
2 ===========
3 **2019-08-16** Aditya Basu (`mitthu`)
4
5 Contents
6 -------------------------------
7 + About the driver
8 + Example Interaction via sysfs
9
10 About the driver
11 -------------------------------
12 * Only one CBDMA function gets registered by the driver.
13 * Also the driver only works with CBDMA devices on bus 0. This is to avoid
14   dealing with scoped DRHDs when performing IOMMU passthru.
15
16 Example Interaction via sysfs
17 -------------------------------
18 ```bash
19 # Mount the device
20 bash-4.3$ mkdir -p /sys/cbdma
21 bash-4.3$ /bin/bind \#cbdma /sys/cbdma
22 bash-4.3$ cd /sys/cbdma/
23
24 # All files
25 bash-4.3$ ls
26 iommu  ktest  reset  stats  ucopy
27
28 # Display information about CBDMA
29 bash-4.3$ cat stats
30 Intel CBDMA [8086:2021] registered at 00:03.0
31     Driver Information:
32         mmio: 0xfffffff0000a0000
33         mmio_phy: 0xfebf0000
34         mmio_sz: 16384
35         total_channels: 1
36         desc_kaddr: 0xffff8001104c2000
37         desc_paddr: 0x00000001104c2000
38         desc_num: 1
39         ver: 0x33
40         status_kaddr: 0xffff80010c8d5960
41         status_paddr: 0x000000010c8d5960
42         status_value: 0x91c1420
43     PCIe Config Registers:
44         PCICMD: 0x406
45         PCISTS: 0x10
46         RID: 0x4
47         CB_BAR: 0xfebf0004
48         DEVSTS: 0x0
49         PMCSR: 0x8
50         DMAUNCERRSTS: 0x0
51         DMAUNCERRMSK: 0x0
52         DMAUNCERRSEV: 0x98
53         DMAUNCERRPTR: 0xa
54         DMAGLBERRPTR: 0x0
55         CHANERR_INT: 0x0
56         CHANERRMSK_INT: 0x60000
57         CHANERRSEV_INT: 0x10000
58         CHANERRPTR: 0x2
59     CHANNEL_0 MMIO Registers:
60         CHANCMD: 0x0
61         CBVER: 0x33 major=3 minor=3
62         CHANCTRL: 0x10c
63         CHANSTS: 0x3 [HALTED], desc_addr: 0x0000000000000000, raw: 0x3
64         CHAINADDR: 0x0000000000000000
65         CHANCMP: 0x0000000000000000
66         DMACOUNT: 0
67         CHANERR: 0x0
68
69 # Perform self-test (multiple runs)
70 bash-4.3$ cat ktest
71 cbdma: info: DMACOUNT = 1
72 Self-test Intel CBDMA [8086:2021] registered at 00:03.0
73         Channel Status: ACTIVE (raw: 0x0)
74         Copy Size: 64 (0x40)
75         srcfill: 2 (0x32)
76         dstfill: 0 (0x30)
77         src_str (after copy): 111111111111111111111111111111111111111111111111111111111111111
78         dst_str (after copy): 111111111111111111111111111111111111111111111111111111111111111
79
80 bash-4.3$ cat ktest
81 cbdma: info: DMACOUNT = 1
82 Self-test Intel CBDMA [8086:2021] registered at 00:03.0
83         Channel Status: ACTIVE (raw: 0x0)
84         Copy Size: 64 (0x40)
85         srcfill: 3 (0x33)
86         dstfill: 0 (0x30)
87         src_str (after copy): 222222222222222222222222222222222222222222222222222222222222222
88         dst_str (after copy): 222222222222222222222222222222222222222222222222222222222222222
89
90 # Reset the CBDMA
91 bash-4.3$ echo 1 >reset
92 cbdma: reset performed
93
94 bash-4.3$ cat reset
95 Status: No pending reset
96 Write '1' to perform reset!
97
98 # Performing DMA with the user-space companion program (with IOMMU in front)
99 # Note: This will not work with QEMU! Akaros should be running bare-metal.
100 bash-4.3$ echo 1 >iommu
101 bash-4.3$ cat iommu
102 IOMMU enabled = yes
103 Write '0' to disable or '1' to enable the IOMMU
104
105 bash-4.3$ ucbdma 00:03.0
106 got device: 00:04.0
107 Mappings for iommu@0xffff80007bebfce8
108     <empty>
109 Mappings for iommu@0xffff800009376ae8
110     pid = 72
111         device = 0:3.0
112 [user] page size: 4096 bytes
113 [user] src: 1111111111111111111
114 [user] dst: 0000000000000000000
115 [user] ucbdma: 0x100000000, size: 80 (or 0x50)
116 [user]  desc->xref_size: 20
117 [user]  desc->src_addr: 0x1000000b4
118 [user]  desc->dest_addr: 0x1000000c8
119 [user]  desc->next_desc_addr: 0x100000000
120 [user]  ndesc: 1
121 [user]  status: 0x0
122 [user] ucbdma ptr: 0x100000000
123 [kern] value from userspace: 0x0000000100000000
124 [kern] IOMMU = ON
125 [kern] ucbdma: user: 0x0000000100000000 kern: 0xffff8002929a4000 ndesc: 1
126 cbdma: info: DMACOUNT = 1
127 [user] ucbdma: 0x100000000, size: 80 (or 0x50)
128 [user]  desc->xref_size: 20
129 [user]  desc->src_addr: 0x1000000b4
130 [user]  desc->dest_addr: 0x1000000c8
131 [user]  desc->next_desc_addr: 0x100000000
132 [user]  ndesc: 1
133 [user]  status: 0x1b041003
134 [user] channel_status: 1b041003
135 [user] src: 1111111111111111111
136 [user] dst: 0000000000000000000
137 ```