Linux Kernel & Device Driver Programming

Ch 15 - Memory Mapping and DMA

This file uses the W3C HTML Slidy format. The "a" key toggles between one-slide-at-a-time and single-page mode, and the "c" key toggles on and off the table of contents. The ← and → keys can be used to page forward and backward. For more help on controls see the "help?" link at the bottom.

Sub-Topics

Linux Address Types
Virtual Memory
Virtual Memory Areas (VMAs)
Device Driver Memory Mapping
DMA I/O

Memory Mapping

Translation of address issued by some device (e.g., CPU or I/O device) to address sent out on memory bus (physical address)
Mapping is performed by memory management units
CPU(s) and I/O devices may have different (or no) memory management units
- No MMU means direct (trivial) mapping
Memory mapping is implemented by the MMU(s) using page (translation) tables stored in memory
The OS is responsible for defining the mappings, by managing the page tables

AGP and PCI Express graphics cards us a Graphics Remapping Table (GART), which is one example of an IOMMU. See Wiki article on IOMMU for more detail on memory mapping with I/O devices.

Address Mapping Function (Review)

Unmapped Pages

The mapping is sparse. Some pages are unmapped.

Why don't we map all pages?

Unmapped Pages

Pages may be mapped to locations on devices.

And some pages may be mapped to both.

MMU Function (Review)

Compute address translation
Uses special associative cache (TLB) to speed up translation
Falls back on full page translation tables, in memory, if TLB misses
Falls back to OS if page translation table misses

Such a reference to an unmapped address causes a page fault
If by a CPU (MMU), it enters the OS through a trap handler
If by an I/O device (IOMMU), some CPU enters the OS through an interrupt handler

Possible Handler Actions

Map the page to a valid physical memory location
- May require creating a page table entry
- May require bringing data in to memory from a device
Treat the event as an erro (e.g., SIG_SEGV)
Pass the exception on to a device-specific handler
- The device's fault method

Linux Page Tables Have 4 Levels

How does having multiple levels save memory?

Linux Page Tables

Logically, Linux now has four levels of page tables:
- PGD - top level, array of pgd_t items
- PUD - array of pud_t items
- PMD - array of pmd_t items
- PTE - bottom level, array of pte_t items
On architectures that do not require all four levels, inner levels may be collapsed (easy via macro definitions)
Page table lookups (and address translation) are done by the hardware (MMU) so long as the page is mapped and resident
Kernel is responsible for setting the tables up and handling page faults
Table are located in struct mm object for each process

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Kernel 2.6 provides functions that allow drivers to ignore page table internals, so these details can change without affecting drivers.

Don't confuse page table entries with struct page.

Linux has page tables for internal use, even if the hardware doesn't require them. For example, apparently, the PowerPC hardware does not access the page tables at all. It uses some memory and a hashing scheme to cache recently used TLB entries, but if that misses, the software handler needs to explicitly load the TLB by doing the actual page

Kernel Memory Mapping

Each OS process (Linux "task") has its own memory mapping
Part of each virtual address space is reserved for the kernel
This is the same range for every process
So, when a process traps into the kernel, there is no change of page mappings
This is called "kernel memory"
The mapping of the rest of the virtual address range varies from one process to another

Kernel Logical Addresses

Most of the kernel memory is mapped linearly onto physical addresses
Virtual addresss in this range are called kernel logical addresses

Examples of PAGE_OFFSET values:

64-bit X86: 0xffffffff80000000
ARM & 32-bit X86: CONFIG_PAGE_OFFSET
default on most architectures = 0xc0000000

Kernel Logical Addresses

Mapped using page table by MMU, like user virtual addresses
But mapped linearly 1:1 to contiguous physical addresses
- __pa(x) adds PAGE_OFFSET to get physical address associated with virtual address
- __va(x) subtracts PAGE_OFFSET to get virtual address associated with physical address
May cover all of physical memory, or not
All memory allocated by kmalloc() with GFP_KERNEL fall into this category

Physical Address Extension (PAE)

Allows processors with 32-bit-address ISA to access more than 4Gbytes of physical memory
Introduced on Pentium Pro (36 bits), and extended by AMD and later Pentiums up to 52 bits
Linux "flat" memory model ignores PAE and only uses 32 bits of physical address
Linux "large" memory model uses MMU to provide access to PAE by mapping tricks

See Wiki article on PAE for more detail.

Linux "High" vs. "Low" Memory

Applies only to machines with larger physical than virtual address space.

Low memory - memory for which direct mapping to virtual address is possible
- first 1Gbyte on x86 systems in 32-bit mode
High memory - the rest of the physical memory

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Do not confuse Linux low memory here with DOS/Windows 0-640K "low memory" range.

It seems that some Linux writers also use the term "low memory" for kernel memory, which can be confusing.

The following output of /proc/meminfo on a Pentium III machine with 1 GB of RAM shows the split between high and low memory as follows:

MemTotal:      1030888 kB
HighTotal:      131008 kB
LowTotal:       899880 kB

Kernel Virtual Addresses

In a machine whose virtual paddresses do not permit addressing all of physical memory (e.g., 32-bit machine with PAE), part of the kernel memory is not mapped in the above fashion, so that we can access "high memory".

Diagram from LDD3 Book

Page Size Symbolic Constants

PAGE_SIZE
- value varies across architectures and kernel configurations
- code should never use a hard-coded integer literal like 4096
PAGE_SHIFT
- the number of bits to shift to convert virtual address to page number
- and physical address to page frame number

What are the advantages of larger page size? Disadvantages?

How does page size relate to the size of physical memory supported, and the amount of space occupied by page tables?

struct page

Describes a page of physical memory.

One exists for each physical memory page, in an array
Pointer to struct page can be used to refer to a physical page, regardless of whether it is in high or low memory
members:
- atomic_t count = number of references to this page
- void * virtual = virtual address of the page, if it is mapped (in the kernel memory space)
  otherwise NULL
- flags = bits describing status of page
  - PG_locked - (temporarily) locked into real memory (can't be swapped out)
  - PG_reserved - memory management system "cannot work on the page at all"
  - ... and others
- and other fields used by the memory management system

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Do not confuse the struct page with a page table entry. A struct page entry corresponds to a page of real memory, and seems to correspond to what is generically called a "page frame table" entry in OS textbooks.

struct page pointers ↔ virtual addresses

virt_to_page returns struct page pointer associated with a kernel logical address
pfn_to_page returns struct page pointer associated with a page frame number after checking with pfn_valid()
page_address returns the kernel virtual address associated with a struct page pointer, if the page is already mapped
- There are multiple versions, depending on kernel configuration parameters.

kmap() &am; kunmap()

kmap is like page_address(), but creates a "special" mapping into kernel virtual memory if the physical page is in high memory
- there are a limited number of such mappings possible at one time
- may sleep if no mapping is currently available
- not needed for 64-bit model
kunmap() - undoes mapping created by kmap()
- reference-count semantics

Some Page Table Operations

pgd_val() - fetches the unsigned value of a PGD entry
pmd_val() - fetches the unsigned value of a PMD entry
pte_val() - fetches the unsigned value of PTE
mm_struct - per-process structure, containing page tables and other MM info
pgd_offset() - pointer to the PGD entry of an address, given a pointer to the specified mm_struct
pmd_offset() - pointer to the PMD entry of an address, given a pointer to the specified PGD entry
2-level systems define pmd_offset(dir,add) as (pmd_t)*dir
pte_page() - pointer to the struct page() entry corresponding to a PTE
pte_present() - whether PTE describes a page that is currently resident

Device drivers should not need to use the above functions, because of the generic memory mapping services described below.

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Kernel 2.6 provides functions that allow drivers to ignore page table internals, so the above details can now change without affecting drivers. However, the following is important to drivers.

Virtual Memory Areas

An range of contiguous VM is represented by an object of type struct vm_area_struct.
Used by kernel to keep track of memory mappings of processes
Each is a contract to handle the VMem→PMem mapping for a given range of addresses
Some kinds of areas:
- Area for program's executable code, a.k.a. text
- Initialized data
- Uninitialized data (BSS = "block started by symbol", normally a data segment for static variables)
- Runtime stack (of main thread)
- An area for each active memory mapping

Process Memory Map

struct mm_struct - contains list of process' VMAs, page tables, etc.
accessible via current-> mm
The threads of a process share one struct mm_struct object

Virtual Memory Regions

From http://duartes.org/gustavo/blog/post/2009/02. I recommend reading the entire article.

Virtual Memory Area Mapping Descriptors

From http://duartes.org/gustavo/blog/post/2009/02. I recommend reading the entire article.

Example of VMA's of a Process

Output of /proc/.../maps for an emacs editing session:

vm_start-vm_stop       mv_pgoff       inode
↓                 vm_page_prot  major:minor      image
↓                 ↓    ↓        ↓     ↓          ↓
baker@websrv: cat /proc/24692/maps
08048000-08195000 r-xp 00000000 09:02 294678     /usr/bin/emacs
08195000-0842f000 rw-p 0014c000 09:02 294678     /usr/bin/emacs
0842f000-08827000 rwxp 00000000 00:00 0          zero-mapped BSS for emacs
40000000-40012000 r-xp 00000000 09:02 211751     /lib/ld-2.2.93.so
40012000-40013000 rw-p 00012000 09:02 211751     /lib/ld-2.2.93.so
40013000-40052000 r-xp 00000000 09:02 896219     /usr/X11R6/lib/libXaw3d.so.7.0
40052000-40058000 rw-p 0003e000 09:02 896219     /usr/X11R6/lib/libXaw3d.so.7.0
40058000-4006b000 rw-p 00000000 00:00 0          BSS for libXaw3d
4006b000-40080000 r-xp 00000000 09:02 896170     /usr/X11R6/lib/libXmu.so.6.2
40080000-40081000 rw-p 00015000 09:02 896170     /usr/X11R6/lib/libXmu.so.6.2
40081000-400cf000 r-xp 00000000 09:02 896182     /usr/X11R6/lib/libXt.so.6.0
400cf000-400d3000 rw-p 0004d000 09:02 896182     /usr/X11R6/lib/libXt.so.6.0
400d3000-400db000 r-xp 00000000 09:02 896152     /usr/X11R6/lib/libSM.so.6.0
400db000-400dc000 rw-p 00007000 09:02 896152     /usr/X11R6/lib/libSM.so.6.0
400dc000-400f0000 r-xp 00000000 09:02 896148     /usr/X11R6/lib/libICE.so.6.3
400f0000-400f1000 rw-p 00013000 09:02 896148     /usr/X11R6/lib/libICE.so.6.3
400f1000-400f3000 rw-p 00000000 00:00 0
400f3000-40100000 r-xp 00000000 09:02 896162     /usr/X11R6/lib/libXext.so.6.4
40100000-40101000 rw-p 0000c000 09:02 896162     /usr/X11R6/lib/libXext.so.6.4
40102000-40104000 r-xp 00000000 09:02 130365     /usr/X11R6/lib/X11/locale/common/xlcDef.so.2
40104000-40105000 rw-p 00001000 09:02 130365     /usr/X11R6/lib/X11/locale/common/xlcDef.so.2
40106000-40108000 r-xp 00000000 09:02 928554     /usr/lib/gconv/ISO8859-1.so
40108000-40109000 rw-p 00001000 09:02 928554     /usr/lib/gconv/ISO8859-1.so
40109000-40149000 r-xp 00000000 09:02 309641     /usr/lib/libtiff.so.3.5
40149000-4014b000 rw-p 0003f000 09:02 309641     /usr/lib/libtiff.so.3.5
4014b000-4014c000 rw-p 00000000 00:00 0
4014c000-40169000 r-xp 00000000 09:02 309545     /usr/lib/libjpeg.so.62.0.0
40169000-4016a000 rw-p 0001c000 09:02 309545     /usr/lib/libjpeg.so.62.0.0
4016a000-40193000 r-xp 00000000 09:02 309633     /usr/lib/libpng12.so.0.1.2.5
40193000-40194000 rw-p 00028000 09:02 309633     /usr/lib/libpng12.so.0.1.2.5
40194000-401a0000 r-xp 00000000 09:02 309632     /usr/lib/libz.so.1.1.4
401a0000-401a2000 rw-p 0000b000 09:02 309632     /usr/lib/libz.so.1.1.4
401a2000-401c3000 r-xp 00000000 09:02 1042441    /lib/i686/libm-2.2.93.so
401c3000-401c4000 rw-p 00021000 09:02 1042441    /lib/i686/libm-2.2.93.so
401c4000-401cb000 r-xp 00000000 09:02 309702     /usr/lib/libungif.so.4.1.0
401cb000-401cc000 rw-p 00007000 09:02 309702     /usr/lib/libungif.so.4.1.0
401cc000-401da000 r-xp 00000000 09:02 896176     /usr/X11R6/lib/libXpm.so.4.11
401da000-401db000 rw-p 0000d000 09:02 896176     /usr/X11R6/lib/libXpm.so.4.11
401db000-401dc000 rw-p 00000000 00:00 0
401dc000-402b7000 r-xp 00000000 09:02 896154     /usr/X11R6/lib/libX11.so.6.2
402b7000-402ba000 rw-p 000da000 09:02 896154     /usr/X11R6/lib/libX11.so.6.2
402ba000-402f0000 r-xp 00000000 09:02 309587     /usr/lib/libncurses.so.5.2
402f0000-402f9000 rw-p 00035000 09:02 309587     /usr/lib/libncurses.so.5.2
402f9000-402fb000 r-xp 00000000 09:02 211764     /lib/libdl-2.2.93.so
402fb000-402fc000 rw-p 00001000 09:02 211764     /lib/libdl-2.2.93.so
402fc000-402fd000 rw-p 00000000 00:00 0
402fd000-404bc000 r--p 00000000 09:02 390925     /usr/lib/locale/locale-archive
404bc000-404c5000 r-xp 00000000 09:02 211784     /lib/libnss_files-2.2.93.so
404c5000-404c6000 rw-p 00008000 09:02 211784     /lib/libnss_files-2.2.93.so
404c6000-404e2000 r-xp 00000000 09:02 130364     /usr/X11R6/lib/X11/locale/common/ximcp.so.2
404e2000-404e4000 rw-p 0001b000 09:02 130364     /usr/X11R6/lib/X11/locale/common/ximcp.so.2
404e4000-404ea000 r--s 00000000 09:02 928609     /usr/lib/gconv/gconv-modules.cache
404ea000-404f3000 r-xp 00000000 09:02 130369     /usr/X11R6/lib/X11/locale/common/xomGeneric.so.2
404f3000-404f4000 rw-p 00008000 09:02 130369     /usr/X11R6/lib/X11/locale/common/xomGeneric.so.2
42000000-42126000 r-xp 00000000 09:02 1042439    /lib/i686/libc-2.2.93.so
42126000-4212b000 rw-p 00126000 09:02 1042439    /lib/i686/libc-2.2.93.so
4212b000-4212f000 rw-p 00000000 00:00 0          stack segment
bffcb000-c0000000 rwxp fffcc000 00:00 0          vsyscall

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Can you make sense of all the VMA's above?

vsyscall is a page of kernel functions mapped into to user space. These are functions which do things that may not require supervisor privilege (like getting the time of day on some systems). Putting them in user space lowers the overhead of calls.

struct vm_area_struct

Represents how a region of virtual memory is mapped
Members include:
- vm_start, vm_end - limits of VMA in virtual address space
- vm_page_prot - permissions (p = private, s = shared)
- vm_pgoff - of memory area in the file (if any) mapped
- vm_file - the struct file (if any) mapped
  provides (indirect) access to:
  - major, minor - device of the file
  - inode - inode of the file
  - image - name of the file
- vm_flags - describe the area, e.g.,
  - VM_IO - memory-mapped I/O region
    will not be included in core dump
  - VM_RESERVED - cannot be swapped
- vm_ops - dispatching vector of functions/methods on this object
- vm_private_data - may be used by the driver

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Implementing the mmap() method requires filling in a VMA structure in the address space of the process mapping the device

vm_operations_struct.vm_ops

void *open (struct vm_area_struct *area);
allows initialization, adjusting reference counts, etc.;
invoked only for additional references, after mmap(), like fork()
void *close (struct vm_area_struct *area);
allows cleanup when area is destroyed;
each process opens and closes exactly once
int page_mkwrite(struct vm_area_struct *vma, struct page *page);
is called when a previously read-only page is about to become writeable; if an error is returned it will cause a SIGBUS
int fault (struct vm_area_struct *vma, struct vm_fault *vmf);
general page fault handler;
set_policy(), get_policy(), migrate() - ignore for now

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

The populate() method has been phased out.

The nopage() and nopfn() methods are obsolescent. The new method that replaces both is fault()

Uses of Memory Mapping by Device Drivers

A device driver is likely to use memory mapping for two main purposes:

To provide user-level access to device memory and/or control registers
for example, so an Xserver process can access the graphics controller directly
To share access between user and device/kernel I/O buffers, to avoid copying between DMA/kernel buffers and userspace

Using mmap() to Access Device (I/O) Memory

The following I/O device mappings are from /proc/.../maps for an X server process

08048000-081bc000 r-xp 00000000 09:00 742770     /usr/X11R6/bin/XFree86
081bc000-081ee000 rw-p 00174000 09:00 742770     /usr/X11R6/bin/XFree86
081ee000-08d57000 rwxp 00000000 00:00 0
40000000-40015000 r-xp 00000000 09:00 32269      /lib/ld-2.3.2.so
40015000-40016000 rw-p 00014000 09:00 32269      /lib/ld-2.3.2.so
40016000-40017000 rw-p 00000000 00:00 0
40017000-40027000 rw-s fe5e0000 09:00 96996      /dev/mem
4002d000-40039000 r-xp 00000000 09:00 371074     /usr/lib/libz.so.1.1.4
40039000-4003b000 rw-p 0000b000 09:00 371074     /usr/lib/libz.so.1.1.4
4003b000-4005c000 r-xp 00000000 09:00 212428     /lib/tls/libm-2.3.2.so
4005c000-4005d000 rw-p 00020000 09:00 212428     /lib/tls/libm-2.3.2.so
4005d000-40064000 r-xp 00000000 09:00 32396      /lib/libpam.so.0.75
40064000-40065000 rw-p 00007000 09:00 32396      /lib/libpam.so.0.75
40065000-40066000 rw-p 00000000 00:00 0
40066000-40069000 r-xp 00000000 09:00 33817      /lib/libdl-2.3.2.so
40069000-4006a000 rw-p 00002000 09:00 33817      /lib/libdl-2.3.2.so
4006a000-4006c000 r-xp 00000000 09:00 34152      /lib/libpam_misc.so.0.75
4006c000-4006d000 rw-p 00001000 09:00 34152      /lib/libpam_misc.so.0.75
4006d000-4006e000 rw-p 00000000 00:00 0
4006e000-40079000 r-xp 00000000 09:00 34945      /lib/libnss_files-2.3.2.so
40079000-4007a000 rw-p 0000a000 09:00 34945      /lib/libnss_files-2.3.2.so
4007a000-400cd000 rw-p 00000000 00:00 0
400cd000-400dd000 rw-s 000a0000 09:00 96996      /dev/mem
400dd000-4013d000 rw-s 00000000 00:04 71958528   /SYSV00000000 (deleted)
401fe000-40b91000 rw-p 00121000 00:00 0
42000000-4212f000 r-xp 00000000 09:00 212241     /lib/tls/libc-2.3.2.so
4212f000-42132000 rw-p 0012f000 09:00 212241     /lib/tls/libc-2.3.2.so
42132000-42134000 rw-p 00000000 00:00 0
42134000-44134000 rw-s fc000000 09:00 96996      /dev/mem
bffaf000-c0000000 rwxp fffb0000 00:00 0

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Distinguish the above, which are user virtual address mappings implemented by drivers, from the (lower level) mappings of IO addresses to kernel logical addresses implemented by the IO system, like the following from /proc/iomem. The ones shown in color are exported to the X server, via (higher level) memory mapping to user space.

00000000-0009fbff : System RAM
0009fc00-0009ffff : reserved
000a0000-000bffff : Video RAM area
000c0000-000c7fff : Video ROM
000c8000-000c8fff : Extension ROM
000c9000-000cafff : Extension ROM
000f0000-000fffff : System ROM
00100000-3ffeffff : System RAM
  00100000-0025122b : Kernel code
  0025122c-0034b1e3 : Kernel data
3fff0000-3fffefff : ACPI Tables
3ffff000-3fffffff : ACPI Non-volatile Storage
f3fff000-f3ffffff : ServerWorks CNB20HE Host Bridge
f4000000-f5ffffff : ServerWorks CNB20HE Host Bridge
f6200000-fe2fffff : PCI Bus #01
  fa000000-fbffffff : Number 9 Computer Company Revolution 4
  fc000000-fdffffff : Number 9 Computer Company Revolution 4
fe500000-fe5fffff : PCI Bus #01
  fe5e0000-fe5effff : Number 9 Computer Company Revolution 4
  fe5ff000-fe5fffff : Number 9 Computer Company Revolution 4
fe900000-fe9fffff : Intel Corp. 82557/8/9 [Ethernet Pro 100]
  fe900000-fe9fffff : e100
feaed000-feaedfff : Intel Corp. 82557/8/9 [Ethernet Pro 100]
  feaed000-feaedfff : e100
feaee000-feaeefff : ServerWorks OSB4/CSB5 OHCI USB Controller
  feaee000-feaeefff : usb-ohci
feaef000-feaeffff : Adaptec AHA-7850
  feaef000-feaeffff : aic7xxx
feafe000-feafefff : Adaptec AIC-7899P U160/m
  feafe000-feafefff : aic7xxx
feaff000-feafffff : Adaptec AIC-7899P U160/m (#2)
  feaff000-feafffff : aic7xxx
febfc000-febfffff : Promise Technology, Inc. 20268
fec00000-fec01fff : reserved
fee00000-fee00fff : reserved
fff80000-ffffffff : reserved

The mmap() Interfaces

User-level API function:

void *mmap (caddr_t start, size_t len, int prot, int flags, int fd, off_t offset);

Driver-level file operation:

int (*mmap) (struct file *filp, struct vm_area_struct *vma);

Implementing the mmap() Method in a Driver

build suitable page tables for the address range
two ways:
1. right away, using remap_pfn_range or vm_insert_page
2. later (on demand), using the fault() VMA method
replace vma->vm_ops with a new set of operations, if necessary

The remap_pfn_range() Kernel Function

int remap_pfn_range (struct vm_area_struct *vma, unsigned long from,
        unsigned long pfn, unsigned long size, pgprot_t prot);
int io_remap_pfn_range(struct vm_area_struct *vma, unsigned long from,
        unsigned long phys_addr, unsigned long size, pgprot_t prot);

builds page tables for virtual address range virt_addr .. virt_add+size
vma = virtual memory are to which the page range is being mapped
pfn = target page frame number of physical address to which mapped
- normally vma->vm_pgoff>>PAGE_SHIFT
- mapping targets range (pfn<<PAGE_SHIFT) .. (pfn<<PAGE_SHIFT)+size
prot = protection
- normally the same value as found in vma->vm_page_prot
- may need to modify value to disable caching if this is I/O memory

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

As usual, these return 0 for success, and negative error code for failure.

io_remap_pfn_range() is for the case when phys_addr refers to I/O memory.

It may be necessary to do something machine-dependent in the prot to disable caching of specific VMAs. This is architecture-dependent. See pgprot_noncached and treatment of i386 video frame buffer memory protection in drivers/video/fbmem.c.

A simple implementation of mmap()

static struct vm_operations_struct simple_remap_vm_ops = {
   .open =  simple_vma_open,
   .close = simple_vma_close,
};

int simple_remap_mmap(struct file *filp, struct vm_area_struct *vma){ 
   if (remap_pfn_range(vma, vma->vm_start, vma->vm_pgoff,
                       vma->vm_end - vma->vm_start,
                       vma->vm_page_prot))
   return -EAGAIN;
   vma->vm_ops = &simple_remap_vm_ops;
   simple_vma_open(vma);  /* does nothing but print out a message */
   return 0;
}

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

This is from example module simple.c. It does a simple linear 1:1 mapping of physical memory into a user address space. (This is not a serious example. I think you would not ordinarily want to do this. The range of addresses passed by the kernel in vma is a range of unused virtual addresses in the user space. The odds of this range corresponding to useful physical memory appear to be slim.)

The explicit call to simple_vma_open() is necessary in the driver here because the system will not call it on the call to mmap().

remap_pfn_range() can only be used for reserved (always resident) pages, and for pages above the top of physical memory. Otherwise, it would not be safe for a device driver to map them to user space. It can be used to remap high PCI buffers and ISA memory.

It cannot be used to remap pages of "conventional addresses, including ones you obtain by calling get_free_page()". If you attempt to map such pages the user process will see a page of zeroes.

To remap RAM you want to use the fault() method, described further below.

Narrowing the Mapped Region

unsigned long off = vma->vm_pgoff << PAGE_SHIFT;
unsigned long physical = simple_region_start + off;
/* assumes simple_region_start is already page-aligned */
unsigned long vsize = vma->vm_end - vma->vm_start;
unsigned long psize = simple_region_size - off;
if (vsize > psize) return -EINVAL;
if (remap_pfn_range(vma, vma->vm_start, physical, vsize, vma_vm_page_prog)) ...

Using fault()

struct page (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf);

vmf - is a struct vm_fault, which includes:
- flags
  - FAULT_FLAG_WRITE indicates the fault was a write access
  - FAULT_FLAG_NONLINEAR indicates the fault was via a nonlinear mapping
- pgoff - logical page offset, based on vma
- virtual_address - faulting virtual address
- page - set by fault handler to point to a valid page descriptor; ignored if VM_FAULT_NOPAGE or VM_FAULT_ERROR is set

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

This interface has changed since the LDD3 book was written. See the lwn.net article on fault handler for explanation.

The fault() method of a VMA is called when a user process attempts to access a page in the VMA that is not present in memory.

Return value is a word of flags that gives details about how the fault was handled:

VM_FAULT_OOM - out of memory
VM_FAULT_SIGBUS -
VM_FAULT_ERROR = VM_FAULT_OOM| VM_FAULT_SIGBUS
VM_FAULT_MAJOR - out of memory
VM_FAULT_WRITE - out of memory
VM_FAULT_NOPAGE - fault installed the pte, not return page
VM_FAULT_LOCKED - fault locked the returned page

Flags in

It "must locate and return the struct page pointer that refers to the page the user wanted". It must also "take care to increment the usage count for the page it returns by calling the get_page macro".

Note that there is no need to call put_page() (to decrement the page reference count) in this case, since the system will do that automatically for all pages when it deletes the VMA. It is essential that we increment the count here, to prevent that automatic decrement from prematurely putting the page on the free list.

Example Using fault()

static int simple_vma_fault(struct vm_area_struct *vma,
                struct vm_fault *vmf)
{
        struct page *pageptr;
        unsigned long offset = vma->vm_pgoff << PAGE_SHIFT;
        unsigned long address = (unsigned long) vmf->virtual_address;
        unsigned long physaddr = address - vma->vm_start + offset;
        unsigned long pageframe = physaddr >> PAGE_SHIFT;
        if (!pfn_valid(pageframe))
                return VM_FAULT_SIGBUS;
        pageptr = pfn_to_page(pageframe);
        printk (KERN_NOTICE "---- Fault, off %lx pageframe %lx\n", offset, pageframe);
        printk (KERN_NOTICE "page->index = %ld mapping %p\n", pageptr->index, pageptr->mapping);
        get_page(pageptr);
        vmf->page = pageptr;
        return 0;
}

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

This example is still not good style. The lwn.net article on fault says of the virtual_address field:

... anybody who is tempted to use that field should be prepared to justify that use to a crowd of skeptical kernel developers. Most handlers should not care where the page lives in user space, and use of virtual_address will make it impossible to support nonlinear VMAs. So, if at all possible, virtual_address should be ignored. If your code only uses pgoff, it should also set the VM_CAN_NONLINEAR flag in the VMA's vm_flags field to let the kernel know that it is playing by the rules.

I don't yet have enough confidence in my understanding of vmf->pgoff to rewrite the example using that. I believe it is the offset of the faulted page relative to the start of the vm area.

Note that pfn_to_page() assumes there is a corresponding kernel logical address, and so it does not work for high memory. In particular, this is true of PCI memory, which is mapped above the highest system memory. This is the reason for the check pfn_valid().

If the nopage() method is left as NULL, the page is mapped to a copy-on-write page that reads as zero. (So, there is no segmentation fault.)

If the nopage() method cannot map the page, it returns NOPAGE_SIGBUS (page out of range) or NOPAGE_OOM (out of memory).

The specific type of fault is returned via the parameter type, if that is non-null.

Preventing Extension of the Mapping for a Device

struct page *simple_fault(struct vm_area_struct *vma,
    struct vm_fault *vmf)
{ return VM_FAULT_SIGBUS; 
}

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

The LDD3 book says that between kernel versions 2.4 and 2.6 support was dropped for the remap() method, which allowed a driver respond to the mremap() system call (to extend a memory mapping) explicitly. Instead, the system would quietly process such calls without notifying the driver.

If a driver does not want the user to be able to extend (using mremap()) a region of memory that has been mapped earlier (using mmap()), the driver can define the nopage() method to generate a segmentation fault. Otherwise, the user will simply see a copy-on-write page of zeros.

It is not clear whether this is still a valid concern, as I have not yet been able to find any instances in the 2.6.25 kernel where this is done.

Warning

The mmap examples in the LDD3 text are not correct. They need to be updated for the transition from nopage() to fault().

I have updated one example, sculld. You can see my full code for sculld by following this link.

A Slightly More Complete Example

static int sculld_vma_fault(struct vm_area_struct *vma,
                              struct vm_fault *vmf)
{
        struct sculld_dev *ptr, *dev = vma->vm_private_data;
        int result = VM_FAULT_SIGBUS;
        struct page *page;
        void * pageptr = NULL;
        pgoff_t pgoff = vmf->pgoff;  

        down(&dev->sem);
        printk (KERN_NOTICE "sculld_vma_fault: pgoff   = %lx\n", pgoff);
        if (pgoff >= dev->size) goto out;

        /*
         * Now retrieve the sculld device from the list, then the page.
         * If the device has holes, the process receives a SIGBUS when
         * accessing the hole.
         */
        for (ptr = dev; ptr && pgoff >= dev->qset;) {
                ptr = ptr->next;
                pgoff -= dev->qset;
        }
        if (ptr && ptr->data) pageptr = ptr->data[pgoff];
        if (!pageptr) goto out; /* hole or end-of-file */
        /* got it, now convert pointer to a struct page and increment the count */
        page = virt_to_page(pageptr);
        get_page(page);
        vmf->page = page;
        result = 0;
  out:
        up(&dev->sem);
        return result;
}

A Slightly More Complete Example (continued)

struct vm_operations_struct sculld_vm_ops = {
        .open =     sculld_vma_open,
        .close =    sculld_vma_close,
        .fault =    sculld_vma_fault,
};
int sculld_mmap(struct file *filp, struct vm_area_struct *vma)
{
        struct inode *inode = filp->f_dentry->d_inode;

        printk (KERN_NOTICE "sculld: mmap starting\n");
        /* refuse to map if order is not 0 */
        if (sculld_devices[iminor(inode)].order)
                return -ENODEV;

        /* don't do anything here: "fault" will set up page table entries */
        vma->vm_ops = &sculld_vm_ops;
        vma->vm_flags |= VM_RESERVED;
        vma->vm_private_data = filp->private_data;
        sculld_vma_open(vma);
        printk (KERN_NOTICE "sculld: mmap done\n");
        return 0;
}

The above is only for mapping kernel logical addresses. For other kernel virtual addresses, you need to use vmalloc_to_page() instead of virt_to_page().

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

I still have not updated scullp, scullv, etc.

The example in the bttv driver (below) is actually more realistic, since it makes nontrivial use of reference counts in the vm_close() method.

A Special Case: Remapping I/O Memory

remap_pfn_to_page() cannot be used to map addresses returned by ioremap() to user space
instead, use io_remap_pfn_range() directly to remap the I/O areas into user space

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Recall that we used ioremap_nocache() to map the PCI-card's I/O memory into the kernel memory space. Exporting it to user space via mmap() would be an instance of this special case.

Recurrence of Patterns

Even though Microsoft's Windows operating systems have a different API for device drivers, the same underlying operations, such as memory mapping, still need to be done. So, if you read device driver code for Windows you will see some of the same programming patterns. So, you probably can make some sense of the following fragment of code from a Windows NT driver, which performs a function similar to a Linux fault method.

Memory mapping in Windows NT(TM)

static PUCHAR getMappedAddress(
   IN unsigned baseAddr, // User-mode address to convert
   IN INTERFACE_TYPE interfaceType, // PCI, ISA
   IN unsigned busNum,
   IN unsigned bytesNeeded, // Bytes needed at baseAddr
   OUT int *pRetCode) // Extended error info
{
#define MEM_SPACE 0 // 0 => memory space, 1 => I/O space
   PHYSICAL_ADDRESS translatedAddress, physicalAddress; // physical address to map 
   PUCHAR mappedBaseAddr = NULL;
   ULONG memType = MEM_SPACE; // Resource is a memory address, not a port
   BOOLEAN nRc;
   // Reformat base address for function we need to use
   physicalAddress.HighPart = 0;
   physicalAddress.LowPart = baseAddr;
   nRc = HalTranslateBusAddress(
      interfaceType, 
      busNum,
      physicalAddress,
      &memType,
      &translatedAddress);
   if(nRc == FALSE) { ...error recovery...
      }
   else {
      // Assume memType = MEM_SPACE
      mappedBaseAddr = MmMapIoSpace(translatedAddress, bytesNeeded, FALSE);
      if(mappedBaseAddr == NULL) { ...error recovery...
         }
      }
   return(mappedBaseAddr);
}

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Whether the OS be Linux or MS Windows, the work that needs to be performed is still similar, and the internal mechanisms are likely to be similar. The code above is from a Windows NT driver for the PixelSmart video frame grabber.

This use of memory mapping is for the internal use of the driver, to map device memory into kernel memory. A driver may also want to map device memory into user space.

Observe that this seems to be closer to the remap_pfn_range() technique, and it seems to be mapping the actual device memory.

The HalTranslateBusAddress() function "translates a bus-relative physical address into the corresponding system physical address", and the MmMapIoSpace() function "maps a given physical address to nonpage system space".

Performing Direct I/O

Idea: copy data directly from the device into the user-space buffer
Problem: user pages may be swapped
Approach:
- call get_user_pages to get a pointer to the user-space buffer, which is also then locked into memory:
```
down_read(&current->mm->mmap_sem);
if (result=get_user_pages(current, current->mm, ...) ...
up_read(&current->mm->mmap_sem);
```
- convert each struct page pointer to a kernel virtual address using kmap() or kmap_atomic()
- when done, inform the kernel the pages have been modified, by calling set_page_dirty:
```
if (! PageReserved(page)) set_page_dirty (page);
```
- Relase the pages, by calling page_cache_release

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

It is generally a good thing to avoid recopying data. The above is one way of doing this, i.e., by putting the data from the device directly into a user-space buffer. Another way of doing this is to put it into a kernel buffer and then map the kernel buffer into user space. Linux supports both of these methods for video stream input.

Examples from V4L and the bttv driver

The V4L video driver model supports two models of memory-mapped streaming I/O:

V4L2_MEMORY_MMAP - Memory Mapping
- kernel provides buffer space, possibly mapped to device memory
V4L2_MEMORY_USERPTR - User Pointers
- user provides buffer space, driver or device puts data into user buffers

How to Use V4L2_MEMORY_MAP Buffers

request number and type of buffers desired, using ioctl VIDIOC_REQBUFS
get the address of each buffer, using ioctl VIDIOC_QUERYBUF
map the buffer into user space, using a call to mmap()
queue all the buffers for input, using ioctl VIDIOC_QBUF
start capturing data using the ioctly VIDIOC_STREAMON
repeat for each frame:
- wait for a buffer to dequeue, using ioctl VIDIOC_DQBUF, or use select() or poll()
- process the data in the buffer
- return the buffer to the driver, using ioctl VIDIOC_QBUF
stop capturing data using the ioctly VIDIOC_STREAMOFF

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

The application xawtv uses the memory-mapped stream I/O mode to continuously capture video frames, in function v4l2_start_streaming.

How to Use V4L2_MEMORY_USERPTR Buffers

tell the driver to expect user buffers, using ioctl VIDIOC_REQBUFS
allocate some buffers
pass the driver the addresses of the buffer, using calls to ioctl VIDIOC_QBUF
start capturing data using the ioctly VIDIOC_STREAMON
repeat for each frame:
- wait for a buffer to dequeue, using ioctl VIDIOC_DQBUF, or use select() or poll()
- process the data in the buffer
- return the buffer to the driver, using ioctl VIDIOC_QBUF
stop capturing data using the ioctl VIDIOC_STREAMOFF

Implementation of V4L2_MEMORY_MAP Buffers

based on the fault() method
start from bttv_fops
follow links to look at bttv_mmap and the bttv_fops structure
then look at where the mapping is set up in videobuf_mmap_mapper function in video-buf.c. There are actually several versions of this function, which is dispatched via a function pointer specific to the queue. One version is __videobuf_mmap_mapper defined in videobuf-dma-sg.c.
- it installs a link to a vm_operations_struct videobuf_vm_ops
- which contains links to the videobuf_vm_open, videobuf_vm_close(), and videobuf_vm_fault() methods
- note that the VM_DONTEXPAND flag is used, to prevent user extension of the mapping
- and VM_RESERVED is used, to prevent the pages from being swapped out
- the actual pages of memory for the buffer are not allocated until later, by the fault() method

How to Use V4L2_MEMORY_MAP Buffers

videobuf_vm_fault does the following:
1. calls alloc_page() to get a pointer to a descriptor of an unused user-space (virtual) page
2. calls page_address() to get the corresponding pointer value
3. calls clear_user_page() to zero this out
4. sets vmf->page to the struct page* for the newly allocated page back to the user

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Most of the buffer manipulation for the bttv driver is implemented in a device-independent way, that is intended to be shared by other V4L2 drivers. That code is in files with generic-looking names, like video-buf.c.

Note that the PixelSmart (HRT) device does not support DMA, so to support the V4L2 streaming API the driver (instead of the hardware) would need to do the copying from device memory to RAM. If one were to try to re-use the generic V4L2 code to do this, the parts that refer to DMA might be a problem. However, it might be possible to simulate DMA in the driver, having the copy-work done by timer/IRQ handlers.

Use of Memory Mapping for Direct I/O with DMA

allows device to write data directly into user-space buffers
for both V4L2_MEMORY_MMAP and V4L2_MEMORY_USRPTR buffers
videobuf_iolock is a dispatching call to a pointer associated with the specific queue. One of the actual functions that may be called is __videobuf_iolock in videobuf-dma.sg.c.
- It calls videobuf_dma_init_user for the case where there is a buffer in userspace
- videobuf_dma_init_user() calls videobuf_dma_init_user_locked
- videobuf_dma_init_user_locked() calls get_user_pages to get struct page* (pointers to page frame descriptors) for the pages of the user-supplied buffer, and to lock them into memory.
later, videobuf_dma_free calls page_cache_release to unlock the pages of the user-supplied buffer

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

videobuf_iolock() does other interesting work. Notice the handling of the case where no user buffer is provided, and so I/O requires a "bounce" buffer.

The function videobuf_iolock() is called from vbi_buffer_prepare, which is one of the methods of videobuf_queue_ops.

Asynchronous I/O

Due to the time limitation, and because the aynchronous I/O kernel interfaces have changed between the time the LDD3 text was written and the present, we will skip over driver support for asynchronous I/O. If time permits, we may come back to this at the end of the course.

Synchronous ("pulled") DMA Input Steps

process calls read: driver allocates a DMA buffer, instructs the hardware to transfer the data, blocks the process
hardware writes data to the DMA buffer, raises an interrupt when transfer is complete
interrupt handler acknowledges the interrupt, and awakens the process
the process reads the data from the buffer

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

e.g., for a disk read operation

Asynchronous ("pushed") DMA Input Steps

hardware raises an interrupt to announce arrival of new data
interrupt handler allocates buffer, tells hardware where to transfer data
devices writes data to the buffer, raises another interrupt when done
interrupt handler dispatches new data, wakes up any relevant process, does housekeeping

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

e.g., for arrival of a packet on a network interface

For network devices, the process above may be simplified. The driver keeps a ring of buffers available, into which the device writes the data as it arrives. Interrupts are only needed to announce the arrival of new packets, or if the ring of buffers becomes empty or nearly empty.

Allocation of DMA Buffers

need to be in memory addressable by the device
use zone GFP_DMA with kmalloc() or get_free_pages() if physical addresses used by device are limited to 24 bits
each buffer needs to occupy continguous pages of real memory, for ISA and PCI bus
can be allocated at boot time, or runtime (if module, must be at runtime)
how to get big contiguous ranges of physical addresses:
1. reserve part of RAM memory at boot time, for modules
  using the "mem=" kernel argument
2. "aggressive allocation" - request everything in sight, and look for consecutive pages;
  there is a danger of lockup, so at least use timer to give up if attempt fails
better: design to work with smaller buffers

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

The reason getting large blocks of contiquous DMA memory is hard is that the physical memory becomes fragmented over time, as various blocks are allocated and deallocated.

Bus Addresses

For ISA and PCI, bus address = physical address
For other busses, this may not be the case
virt_to_bus() - converts a virtual address to a bus address
bus_to_virt() - converts a bus address to a virtual address
These do not work for all architectures, so use of generic DMA layer is preferred.

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Note that virt_to_bus() and bus_to_virt() are not sufficient in situations where IOMMU must be programmed, or bounce buffers must be used. The generic DMA layer includes architecture-specific code to handle these ugly details.

Jobs of a DMA Device Driver

allocate buffers
pass buffer bus addresses to device
react to interrupts:
- notify users when I/O is complete
- provide more buffers when needed
- recycle used buffers when needed

Generic DMA Layer

introduced since kernel 2.4
tries to address common architecture-specific problems with all DMA devices on a given architecture
- cache coherencey
- ranges of addresses addressable by DMA
- setting up and managing "bounce buffers", if necessary
- setting up and managing IOMMU, if present
based on the device abstraction (covered in Chapter 14)
apparently an evolutionary outgrowth of the generic PCI DMA support
PCI DMA support now seems to be implemented using the generic DMA layer
PCI version still seems to be widely used

This area seems to have evolved a lot since the LDD3 book was last revised. See the new improved Dynamic DMA Mapping Guide, for explanation, which is new since the 2.6.31 kernel documentation on this course's own LXR site.

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

It seems that the PCI-specific versions of the DMA support functions are being phased out, but they are still in use within the OS.

Specifying Address Range Addressable by HW

kernel assumes DMA can use any 32-bit address, unless notified otherwise
```
int dma_set_mask(struct device *Dev, u64 mask);
```
- checks whether the specified range of address is OK for DMA
- if it fails, DMA is not possible with that (narrow) address range
- pci_set_dma_mask() is an earlier version, now a specialized wrapper for the generic one
- See use of pci_set_dma_mask in bttv driver.

DMA Mappings

allocating a DMA buffer & generating an address that is accessible by the device
coherent/consistent DMA mapping
- exists for life of driver
- both CPU and peripheral must see coherent views of the buffer
- needs cache consistency mechanism at hardware level
streaming DMA mapping
- set up for a single operation
- does not require consistency between device and CPU views of memory
- device and CPU take turns logically "owning" the buffer
- calls are provided to effect the change of ownership

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

Design of driver to use streaming DMA mappings is preferred, since it is more portable and can be implemented more efficiently.

Calls to Set Up Coherent DMA Mappings

void *dma_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle, int flag);

bundles allocation, so that buffer is accessible for DMA
dma_free_coherent() - unmaps and frees buffer
PCI versions have different name, are still widely used

See an example of use of pci_alloc_consistent(), the pci version of the above function, in the bttv driver.

Other examples are in the e1000 network driver, which calls it in the following functions:

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

There is not a lot of internal explanation of the BTTV driver, especially regarding the DMA I/O model. I found the following on the web:

The "risc" here is a simple language that is used to tell the BT848 how to do DMA.

You may also want to look at the definition of pci_alloc_consistent in cross-referenced source code. It will require quite a lot of drilling down through calls, and includes architecture-specific code.

Obsolete Material

The LDD3 text treatment of the following topics appears to be obsolete. Due to lack of time, I have not been able to provide updates notes, so I have left out these topics entirely, for now.

DMA Pools
Setting up Streaming DMA Mappings
Setting up a PCI DMA Transfer Using One Buffer
Setting up Scatter-Gather Mappings
Setting up a PCI DMA Transfer Using One Buffer
Responding to a DMA Interrupt

Instead, I am relying on the code in actual drivers for examples.

Example: DMA in BTTV Driver (on PCI Bus)

pci_set_dma_mask - specifies how many bits of address are used by DMA
see example of use in bttv driver

DMA for ISA Devices

Two kinds:
- ISA bus master - device has own controller to drive bus, similar to PCI
- native - DMA controller on motherboard drives bus
  (this is the "interesting" case)
for native, there are a limited number of "channels" of the motherboard DMA controller
OS must allocate and manage channels
resource management similar to that for IRQs

Registering DMA Usage (only for ISA device)

int dad_open (struct inode *inode, struct file *filp)
{  struct dad_device *my_device;
   /* ... */
   if ( (error = request_irq(my_device.irq, dad_interrupt,
                             SA_INTERRUPT, "dad", NULL)) )
      return error;
   /* or implement blocking open */
   if ((error = request_dma(my_device.dma, "dad")) ) {
      free_irq(my_device.irq, NULL); return error;
   /* or implement blocking open */
   }
   /* ... */ return 0;
}
void dad_close (struct inode *inode, struct file *filp)
{  struct dad_device *my_device;
   /* ... */
   free_dma(my_device.dma);
   free_irq(my_device.irq, NULL);
   /* ... */
}

From LDD3 - may be obsolete.

This slide has additional "handout" notes. You need to use the 'a' key to toggle into handout mode, in order to see them.

The /proc/dma file on a system with a DMA sound card installed:

1: Sound Blaster8
4: cascade

The last entry is a place-holder for the controller used to cascade the primary DMA controller into the slave controller, on a system with two DMA controllers.

Talking to DMA Controller (only for ISA device)

Driver needs to configure the DMA controller
when read() or write() is called, or in response to open() or ioctl() if using async transfers
Controller is protected by spinlock dma_spin_lock()

Low-level DMA Operations

claim_dma_lock(), release_dma_lock() - work on this spinlock
set_dma_mode() - DMA_MODE_READ, DMA_MODE_WRITE, DMA_MODE_CASCADE
set_dma_addr() - assigns address of DMA buffer for given DMA channel to given (bus) address value
set_dma_count() - tells how many bytes to transfer
disable_dma() - do this before configuring
enable_dma() - do this after configuring
get_dma_residue() - how many bytes remain to be transferred
clear_dma_ff() - for access to 16-bit register as pair of 8-bit registers

A device driver should not need to use these if it uses the generic DMA layer.

Example Code

int dad_dma_prepare(int channel, int mode, unsigned int buf,
    unsinged int count)
{  unsigned long flags;
   flags = claim_dma_lock();
   disable_dma(channel);
   clear_dma_ff(channel);
   set_dma_mode(channel, mode);
   set_dma_addr(channel, virt_to_bus (buf));
   set_dma_count(channel, coutn);
   enable_dma(channel);
   release_dma_lock(flags);
   return 0;
}
int dad_dma_isdone(int channel)
{ int residue;
  unsigned long flags = claim_dma_lock();
  residue = get_dma_residue(channel);
  release_dma_lock(flags);
  return (residue == 0);
}

From LDD3 - may be obsolete.