Question:

when using the mmap() function , why must user applications 
define a map size which is a multiple of the page size?


Answer:

to answer this question we can look at the devmem2 application
( thanks to J.D.Bakker and Erik Mouw) which is available at the 
LART pages ( http://www.lart.tudelft.nl/lartware/port ).

the devmem2 is intended to receive an address as an argument
and return the value stored at that address.in order to do this
devmem2 uses mmap() to change its private view of the CPU's address 
space. mmap(), as used in devmem2, works by re-mapping parts of the 
CPU's address space by (asking the kernel to) change the 
physical->virtual memory mapping as provided by the MMU.

from the man page of mmap():

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

	The mmap function asks to map length bytes starting
	at offset offset from the file(or other object)
	specified by the file descriptor fd into memory,
	preferably at address start. This latter address
	is a hint only, and is usually specified as 0.The
	actual place where the object is mapped is returned
	by mmap, and is never 0. offset should be a multiple
	of the page size as returned by getpagesize(2).


The MMU cannot map single bytes or words; it has a minimal 
granularity; this is called the page size; this tends to be fixed in 
silicon. With a few (rare) exceptions, all MMU mappings must have a 
starting address and length of a multiple of the page size.

function call from devmem2.c:

mmap(0, MAP_SIZE, PROT_READ | PROT_WRITE, MAP_SHARED, fd, target & ~MAP_MASK);

the page size can be read using the getpagesize() function. this
can be used if the application will be designed to be portable
between platforms and architectures. because devmem2 was intended
as a tool for ARM based devices, MAP_SIZE hardcodes the ARM page
size as 4k (which happens to be the same on x86 and most other archs).
the mmap() function call in devmem2, AND's the target address with
~MAP_MASK which is rounded down to an even multiple of the page size.

defines from devmem2.c:

	#define MAP_SIZE 4096UL
	#define MAP_MASK (MAP_SIZE - 1)



Resources:

http://www.lart.tudelft.nl/	- LART pages
man page for mmap()
man page for getpagesize()

special thanks to J.D.Bakker and Erik Mouw