cbdma: add documentation

Signed-off-by: Aditya Basu <mitthu@google.com>
Signed-off-by: Barret Rhoden <brho@cs.berkeley.edu>

Documentation/cbdma.md

diff --git a/Documentation/cbdma.md b/Documentation/cbdma.md
new file mode 100644
index 0000000..54a0426
--- /dev/null
+++ b/Documentation/cbdma.md
@@ -0,0 +1,137 @@
+Intel CBDMA
+===========
+**2019-08-16** Aditya Basu (`mitthu`)
+
+Contents
+-------------------------------
++ About the driver
++ Example Interaction via sysfs
+
+About the driver
+-------------------------------
+* Only one CBDMA function gets registered by the driver.
+* Also the driver only works with CBDMA devices on bus 0. This is to avoid
+  dealing with scoped DRHDs when performing IOMMU passthru.
+
+Example Interaction via sysfs
+-------------------------------
+```bash
+# Mount the device
+bash-4.3$ mkdir -p /sys/cbdma
+bash-4.3$ /bin/bind \#cbdma /sys/cbdma
+bash-4.3$ cd /sys/cbdma/
+
+# All files
+bash-4.3$ ls
+iommu  ktest  reset  stats  ucopy
+
+# Display information about CBDMA
+bash-4.3$ cat stats
+Intel CBDMA [8086:2021] registered at 00:03.0
+    Driver Information:
+        mmio: 0xfffffff0000a0000
+        mmio_phy: 0xfebf0000
+        mmio_sz: 16384
+        total_channels: 1
+        desc_kaddr: 0xffff8001104c2000
+        desc_paddr: 0x00000001104c2000
+        desc_num: 1
+        ver: 0x33
+        status_kaddr: 0xffff80010c8d5960
+        status_paddr: 0x000000010c8d5960
+        status_value: 0x91c1420
+    PCIe Config Registers:
+        PCICMD: 0x406
+        PCISTS: 0x10
+        RID: 0x4
+        CB_BAR: 0xfebf0004
+        DEVSTS: 0x0
+        PMCSR: 0x8
+        DMAUNCERRSTS: 0x0
+        DMAUNCERRMSK: 0x0
+        DMAUNCERRSEV: 0x98
+        DMAUNCERRPTR: 0xa
+        DMAGLBERRPTR: 0x0
+        CHANERR_INT: 0x0
+        CHANERRMSK_INT: 0x60000
+        CHANERRSEV_INT: 0x10000
+        CHANERRPTR: 0x2
+    CHANNEL_0 MMIO Registers:
+        CHANCMD: 0x0
+        CBVER: 0x33 major=3 minor=3
+        CHANCTRL: 0x10c
+        CHANSTS: 0x3 [HALTED], desc_addr: 0x0000000000000000, raw: 0x3
+        CHAINADDR: 0x0000000000000000
+        CHANCMP: 0x0000000000000000
+        DMACOUNT: 0
+        CHANERR: 0x0
+
+# Perform self-test (multiple runs)
+bash-4.3$ cat ktest
+cbdma: info: DMACOUNT = 1
+Self-test Intel CBDMA [8086:2021] registered at 00:03.0
+        Channel Status: ACTIVE (raw: 0x0)
+        Copy Size: 64 (0x40)
+        srcfill: 2 (0x32)
+        dstfill: 0 (0x30)
+        src_str (after copy): 111111111111111111111111111111111111111111111111111111111111111
+        dst_str (after copy): 111111111111111111111111111111111111111111111111111111111111111
+
+bash-4.3$ cat ktest
+cbdma: info: DMACOUNT = 1
+Self-test Intel CBDMA [8086:2021] registered at 00:03.0
+        Channel Status: ACTIVE (raw: 0x0)
+        Copy Size: 64 (0x40)
+        srcfill: 3 (0x33)
+        dstfill: 0 (0x30)
+        src_str (after copy): 222222222222222222222222222222222222222222222222222222222222222
+        dst_str (after copy): 222222222222222222222222222222222222222222222222222222222222222
+
+# Reset the CBDMA
+bash-4.3$ echo 1 >reset
+cbdma: reset performed
+
+bash-4.3$ cat reset
+Status: No pending reset
+Write '1' to perform reset!
+
+# Performing DMA with the user-space companion program (with IOMMU in front)
+# Note: This will not work with QEMU! Akaros should be running bare-metal.
+bash-4.3$ echo 1 >iommu
+bash-4.3$ cat iommu
+IOMMU enabled = yes
+Write '0' to disable or '1' to enable the IOMMU
+
+bash-4.3$ ucbdma 00:03.0
+got device: 00:04.0
+Mappings for iommu@0xffff80007bebfce8
+    <empty>
+Mappings for iommu@0xffff800009376ae8
+    pid = 72
+        device = 0:3.0
+[user] page size: 4096 bytes
+[user] src: 1111111111111111111
+[user] dst: 0000000000000000000
+[user] ucbdma: 0x100000000, size: 80 (or 0x50)
+[user]  desc->xref_size: 20
+[user]  desc->src_addr: 0x1000000b4
+[user]  desc->dest_addr: 0x1000000c8
+[user]  desc->next_desc_addr: 0x100000000
+[user]  ndesc: 1
+[user]  status: 0x0
+[user] ucbdma ptr: 0x100000000
+[kern] value from userspace: 0x0000000100000000
+[kern] IOMMU = ON
+[kern] ucbdma: user: 0x0000000100000000 kern: 0xffff8002929a4000 ndesc: 1
+cbdma: info: DMACOUNT = 1
+[user] ucbdma: 0x100000000, size: 80 (or 0x50)
+[user]  desc->xref_size: 20
+[user]  desc->src_addr: 0x1000000b4
+[user]  desc->dest_addr: 0x1000000c8
+[user]  desc->next_desc_addr: 0x100000000
+[user]  ndesc: 1
+[user]  status: 0x1b041003
+[user] channel_status: 1b041003
+[user] src: 1111111111111111111
+[user] dst: 0000000000000000000
+```