Specifications

This is the Title of the Book, eMatter Edition

The mmap Device Operation

425

The value returned by the function is the usual 0 or a negative error code. Let’s look

at the exact meaning of the function’s arguments:

vma

The virtual memory area into which the page range is being mapped.

virt_addr

The user virtual address where remapping should begin. The function builds

page tables for the virtual address range between

virt_addr and virt_addr+size.

pfn

The page frame number corresponding to the physical address to which the vir-

tual address should be mapped. The page frame number is simply the physical

address right-shifted by

PAGE_SHIFT bits. For most uses, the vm_pgoff field of the

VMA structure contains exactly the value you need. The function affects physi-

cal addresses from

(pfn<<PAGE_SHIFT) to (pfn<<PAGE_SHIFT)+size.

size

The dimension, in bytes, of the area being remapped.

prot

The “protection” requested for the new VMA. The driver can (and should) use

the value found in

vma->vm_page_prot.

The arguments to remap_pfn_range are fairly straightforward, and most of them are

already provided to you in the VMA when your mmap method is called. You may be

wondering why there are two functions, however. The first (remap_pfn_range)is

intended for situations where

pfn refers to actual system RAM, while io_remap_

page_range should be used when

phys_addr points to I/O memory. In practice, the

two functions are identical on every architecture except the SPARC, and you see

remap_pfn_range used in most situations. In the interest of writing portable drivers,

however, you should use the variant of remap_pfn_range that is suited to your partic-

ular situation.

One other complication has to do with caching: usually, references to device mem-

ory should not be cached by the processor. Often the system BIOS sets things up

properly, but it is also possible to disable caching of specific VMAs via the protec-

tion field. Unfortunately, disabling caching at this level is highly processor depen-

dent. The curious reader may wish to look at the pgprot_noncached function from

drivers/char/mem.c to see what’s involved. We won’t discuss the topic further here.

A Simple Implementation

If your driver needs to do a simple, linear mapping of device memory into a user address

space, remap_pfn_range is almost all you really need to do the job. The following code is

,ch15.13676 Page 425 Friday, January 21, 2005 11:04 AM