Help: ICE_ICELIB_PIC_MAPMEM

Handles allocating/mapping a buffer for DMA transfers

Function PIC_MAPMEM - Handles allocating/mapping a buffer for DMA transfers

PIC	p	Handle to Device 
DMAMAP	map	DMAMAP structure to contain virtual and physical pointers
int	bytes	Number of bytes in the user buffer (or 4Kby pages if < 0)
int	mode	1 = alloc/map, -1 = unmap/dealloc, 2 = map, -2 = unmap

If mode = 1, this routine prepares a user memory buffer for DMA transfers.  

It first allocates a buffer of the requested size.  Depending on the machine
architecture, this is either mmap'ed to reserved physical pages (Linux PC) or
mapped through hardware bus mapping registers (DEC Alpha) to the PCI bus.
The user buffer's virtual address and the physical start address for the DMA
are returned.

If the memory is not allocatable, start is set to zero and a -1 is returned.

To allocate >= 2Gbytes, the size may be specified in 4Kby pages by 
negating the size parameter.

The map structure is inputs to the PIC_DMASETUP routine.  These numbers
are checked by the driver to ensure the addresses are valid before the DMA is
started.

If mode = -1, this routine unmaps and unlocks the memory associated with this 
DMA buffer address.

Syntax EXAMPLE from C:

	DMAMAP map;
	int_4	buffer[], bytes;
	status = pic_mapmem (p, &map, bytes, 1)
	buffer = (int_4 *)map.vaddr
or
	DMAMAP map;
	int_4	buffer[], pages;
        pages = size / 4096;
	status = pic_mapmem (p, &map, -pages, 1)
	buffer = (int_4 *)map.vaddr

Syntax EXAMPLE from FORTRAN:

	record /DMAMAP/ map
	integer*4  buffer(*), bytes;
	pointer	(pbuffer,buffer)
	status = m$pic_mapmem (p, map, bytes, 1)
	pbuffer = map.vaddr

If <mode> is 2 or -2, instead of 1 and -1, the virtual buffer alloc and
free are not performed in pic_mapmem and must be handled by external code.
This has been added to allow acquisition into buffers that are mmapped to
other processes by user code. This mode is currently only supported on VMS.