SCO OpenServer

vas(D3oddi)

vas: vasbind, vasmalloc, vasmapped, vasunbind -- virtual address space memory function

vasbind- bind a specified virtual address to a physical address

vasmalloc- allocate virtual memory

vasmapped- determine if mapping is in place for specified memory range

vasunbind- undo a mapping

Synopsis

int vasbind(paddr_t paddr, caddr_t vaddr, unsigned int nbytes);

caddr_t vasmalloc(paddr_t paddr, unsigned int nbytes);

caddr_t vasmapped(paddr_t paddr, unsigned int nbytes);

int vasunbind(caddr_t vaddr, unsigned int nbytes);

Description

These functions allow a driver to map physical memory so that it can be read from or be written to by both a driver and a calling user process.

vasmalloc: Allocate virtual memory.
vasbind: Bind a specified virtual address to a physical address.
vasmapped: Determine if a mapping is already in place for the memory range specified by paddr and nbytes.
vasunbind: Undo a mapping and free the memory pages associated with the mapped region.

These functions are generally used to allow user processes to access video adapter memory directly. Memory that has been mapped using these functions is visible to the kernel and to a calling process. However, the mapping is not globally visible to all processes.

Arguments

paddr

set to 0 (zero) in code written for SCO OpenServer. vasmalloc( ) returns an address to virtual user memory; no actual physical memory is allocated by this function for SCO OpenServer systems.

vaddr

specifies the virtual address to bind to or unbind from physical memory.

nbytes

specifies the number of bytes of memory to allocate, bind, or unbind. For vasmalloc, nbytes can be specified as 1 to allocate 4MB, although a value less than 0x1 or greater than 0x400000 will cause vasmalloc to return a NULL pointer.

Return values

vasbind returns -1 if an error occurs (that is, if a region could not be allocated, could not be attached to the user process or could not be grown to the required size) or if an error is found in u.u_error.

vasmalloc returns a virtual address, which will be set to NULL if the nbytes parameter was invalid.

vasunbind returns -1 if the virtual address could not be found.

vasmapped returns the virtual address at which the supplied physical address is bound, or a NULL pointer if the physical address is not bound.

Usage

vasmalloc allocates virtual memory. Use this function to obtain virtual address space that is not currently in use. vasmalloc can only allocate 4 megabytes of virtual address space on each call. A call to vasmalloc is usually preceded by a call to vasmapped to see if the physical memory has already been mapped, and followed by a call to vasbind to bind the virtual to the physical address.

vasbind binds a specified virtual address to a physical address. This function ensures that a problem will not occur with the bound memory being swapped out, causing a page fault and panic in the kernel. This function is normally used to bind the virtual address returned by vasmalloc to physical memory. Before using vasbind, vasmapped should be used to determine if the physical memory range required has already been mapped for the calling process.

Note that although vasmalloc returns the address to a free area of 4MB of user virtual memory, the size of the area of physical memory associated with that pointer by vasbind, using the parameter nbytes, may be any value between 1 byte and 4MB.

When vasbind completes, the driver must pass the virtual address returned by vasmalloc back to the user process using copyout(D3oddi) or another similar function. Calls to vasbind must not specify an address in the text, data, or shared data segments of a user process.

The upper limit for user virtual memory is set by the constant KVBASE (defined in <sys/immu.h>); kernel virtual address space lies above KVBASE. The virtual address supplied to vasbind must be in user virtual memory (below KVBASE), and must not be in use by the current process.

Context and synchronization

User context

Hardware applicability

All.

Version applicability

oddi: 1, 2, 2mp, 3, 3mp, 4, 4mp, 5, 5mp, 6, 6mp

Differences between versions

For XENIX systems, the paddr argument gives the physical address at which the specified virtual address is to be bound. When calling vasbind, paddr can be set to -1 to indicate that the requested user virtual memory is to be allocated from the kernel free memory pool or ``heap.'' The physical address supplied to vasbind is usually a memory-mapped I/O address.

SVR5 DDI compatibility

These functions are not supported for DDI drivers. See ``Memory allocation'' in HDK Technical Reference for information about allocating and mapping memory for DDI drivers and current ODDI drivers.

References

copyout(D3oddi), memget(D3oddi), sptalloc(D3oddi), video(D3oddi)

``Memory allocation'' in HDK Technical Reference