udmabuf(User space mappable DMA Buffer)

Overview

Introduction of udmabuf

udmabuf is a Linux device driver that allocates contiguous memory blocks in the kernel space as DMA buffers and makes them available from the user space. It is intended that these memory blocks are used as DMA buffers when a user application implements device driver in user space using UIO (User space I/O).

A DMA buffer allocated by udmabuf can be accessed from the user space by opneing the device file (e.g. /dev/udmabuf0) and mapping to the user memory space, or using the read()/write() functions.

CPU cache for the allocated DMA buffer can be disabled by setting the O_SYNC flag when opening the device file. It is also possible to flush or invalidate CPU cache while retaining CPU cache enabled.

The physical address of a DMA buffer allocated by udmabuf can be obtained by reading /sys/class/udmabuf/udmabuf0/phys_addr.

The size of a DMA buffer and the device minor number can be specified when the device driver is loaded (e.g. when loaded via the insmod command). Some platforms allow to specify them in the device tree.

Architecture of udmabuf

Figure 1. Architecture

Supported platforms

OS : Linux Kernel Version 3.6 - 3.8, 3.18, 4.4, 4.8, 4.12 (the author tested on 3.18, 4.4, 4.8 and 4.12).
CPU: ARM Cortex-A9 (Xilinx ZYNQ / Altera CycloneV SoC)
CPU: x86(64bit) However, verification is not enough. I hope the results from everyone. In addition, there is a limit to the following feature at the moment.
- Can not control of the CPU cache by O_SYNC flag . Always CPU cache is valid.
- Can not control of the CPU cache of manually by sync_for_device or sync_for_cpu.
- Can not various settings by the device tree.

Usage

Compile

The following Makefile is included in the repository.

ARCH            := arm
KERNEL_SRC_DIR  ?= /lib/modules/$(shell uname -r)/build
ifeq ($(shell uname -m | sed -e s/arm.*/arm/),arm)
else
 CROSS_COMPILE  ?= arm-linux-gnueabihf-
endif
obj-m := udmabuf.o
all:
	make -C $(KERNEL_SRC_DIR) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) M=$(PWD) modules
clean:
	make -C $(KERNEL_SRC_DIR) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) M=$(PWD) clean

Install

Load the udmabuf kernel driver using insmod. The size of a DMA buffer should be provided as an argument as follows. The device driver is created, and allocates a DMA buffer with the specified size. The maximum number of DMA buffers that can be allocated using insmod is 4 (udmabuf0/1/2/3).

zynq$ insmod udmabuf.ko udmabuf0=1048576
udmabuf udmabuf0: driver installed
udmabuf udmabuf0: major number   = 248
udmabuf udmabuf0: minor number   = 0
udmabuf udmabuf0: phys address   = 0x1e900000
udmabuf udmabuf0: buffer size    = 1048576
zynq$ ls -la /dev/udmabuf0
crw------- 1 root root 248, 0 Dec  1 09:34 /dev/udmabuf0

In the above result, the device is only read/write accessible by root. If the permission needs to be changed at the load of the kernel module, create /etc/udev/rules.d/99-udmabuf.rules with the following content.

KERNEL=="udmabuf[0-9]*", GROUP="root", MODE="0666"

The module can be uninstalled by the rmmod command.

zynq$ rmmod udmabuf
udmabuf udmabuf0: driver uninstalled

Configuration via the device tree file

In addition to the allocation via the insmod command and its arguments, DMA buffers can be allocated by specifying the size in the device tree file. When a device tree file contains an entry like the following, udmabuf will allocate buffers and create device drivers when loaded by insmod.

		udmabuf@0x00 {
			compatible = "ikwzm,udmabuf-0.10.a";
			device-name = "udmabuf0";
			minor-number = <0>;
			size = <0x00100000>;
		};

The DMA buffer size can be specified via the size option.

The name of the device can be specified via the device-name option.

The minor-number option is used to set the minor number. The valid minor number range is 0 to 255. A minor number provided as insmod argument will has higher precedence, and when definition in the device tree has colliding number, creation of the device defined in the device tree will fail. When the minor number is not specified, udmabuf automatically assigns an appropriate one.

The device name is determined as follow:

If device-name is specifed use device-name.
If device-name is not present, and if minor-number is specified, sprintf("udmabuf%d", minor-number) is used.
If device-name is not present, and if minor-number is not present, the entry name of the device tree is used (udmabuf@0x00 in this example).

zynq$ insmod udmabuf.ko
udmabuf udmabuf0: driver installed
udmabuf udmabuf0: major number   = 248
udmabuf udmabuf0: minor number   = 0
udmabuf udmabuf0: phys address   = 0x1e900000
udmabuf udmabuf0: buffer size    = 1048576
zynq$ ls -la /dev/udmabuf0
crw------- 1 root root 248, 0 Dec  1 09:34 /dev/udmabuf0

Device file

When udmabuf is loaded into the kernel, the following device files are created. <device-name> is a placeholder for the device name described in the previous section.

/dev/<device-name>
/sys/class/udmabuf/<device-name>/phys_addr
/sys/class/udmabuf/<device-name>/size
/sys/class/udmabuf/<device-name>/sync_mode
/sys/class/udmabuf/<device-name>/sync_offset
/sys/class/udmabuf/<device-name>/sync_size
/sys/class/udmabuf/<device-name>/sync_direction
/sys/class/udmabuf/<device-name>/sync_owner
/sys/class/udmabuf/<device-name>/sync_for_cpu
/sys/class/udmabuf/<device-name>/sync_for_device

/dev/<device-name>

/dev/<device-name> is used when mmap()-ed to the user space or accessed via read()/write().

    if ((fd  = open("/dev/udmabuf0", O_RDWR)) != -1) {
        buf = mmap(NULL, buf_size, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
        /* Do some read/write access to buf */
        close(fd);
    }

The device file can be directly read/written by specifying the device as the target of dd in the shell.

zynq$ dd if=/dev/urandom of=/dev/udmabuf0 bs=4096 count=1024
1024+0 records in
1024+0 records out
4194304 bytes (4.2 MB) copied, 3.07516 s, 1.4 MB/s

zynq$dd if=/dev/udmabuf4 of=random.bin
8192+0 records in
8192+0 records out
4194304 bytes (4.2 MB) copied, 0.173866 s, 24.1 MB/s

phys_addr

The physical address of a DMA buffer can be retrieved by reading /sys/class/udmabuf/<device-name>/phys_addr.

    unsigned char  attr[1024];
    unsigned long  phys_addr;
    if ((fd  = open("/sys/class/udmabuf/udmabuf0/phys_addr", O_RDONLY)) != -1) {
        read(fd, attr, 1024);
        sscanf(attr, "%x", &phys_addr);
        close(fd);
    }

size

The size of a DMA buffer can be retrieved by reading /sys/class/udmabuf/<device-name>/size.

    unsigned char  attr[1024];
    unsigned int   buf_size;
    if ((fd  = open("/sys/class/udmabuf/udmabuf0/size", O_RDONLY)) != -1) {
        read(fd, attr, 1024);
        sscanf(attr, "%d", &buf_size);
        close(fd);
    }

sync_mode

The device file /sys/class/udmabuf/<device-name>/sync_mode is used to configure the behavior when udmabuf is opened with the O_SYNC flag.

    unsigned char  attr[1024];
    unsigned long  sync_mode = 2;
    if ((fd  = open("/sys/class/udmabuf/udmabuf0/sync_mode", O_WRONLY)) != -1) {
        sprintf(attr, "%d", sync_mode);
        write(fd, attr, strlen(attr));
        close(fd);
    }

Details on O_SYNC and cache management will be described in the next section.

sync_offset

The device file /sys/class/udmabuf/<device-name>/sync_offset is used to specify the start address of a memory block of which cache is manually managed.

    unsigned char  attr[1024];
    unsigned long  sync_offset = 0x00000000;
    if ((fd  = open("/sys/class/udmabuf/udmabuf0/sync_offset", O_WRONLY)) != -1) {
        sprintf(attr, "%d", sync_offset);
        write(fd, attr, strlen(attr));
        close(fd);
    }