SPTALLOC(K) UNIX System V SPTALLOC(K)
Name
sptalloc - allocates temporary memory or maps a device into
memory
Syntax
#include "sys/immu.h"
caddr_t
sptalloc(pages, mode, base, flag)
int pages, mode, base, flag;
Description
The sptalloc routine is used to obtain temporary memory for
use by device drivers, or to map a device into memory for
memory mapped I/O. Memory is obtained from the system's
virtual memory pool. When the driver is through with the
memory, the memory should be released via sptfree(K). The
sptalloc routine returns a virtual address usable by any
kernel or driver routine.
Memory allocated is virtually contiguous but not physically
contiguous. The memory allocated is never swapped out, and
it only belongs to the driver that allocated it until the
memory is freed with sptfree(K).
The usual way to call sptalloc is as follows:
sptalloc(pages, PG_P, 0, 1);
Where pages are the number of requested pages, mode
indicates "page present," base (zero) indicates that
requested memory is taken from the kernel memory pool, and
flag (1) indicates to return immediately if memory is not
available.
To use sptalloc for accessing memory mapped I/O, use
sptalloc as shown for an imaginary device being installed at
physical address 0xB8000:
sptalloc(1, PG_P, 0xB8000, 1);
Although vasbind(K) provides a more generalized method of
sharing memory between the kernel and a user process,
sptalloc with mode set to PG_P | PG_RW | PG_US may be used
instead of vasbind, but the results are different.
A mapping performed with vasbind creates a region of memory
shared only between the kernel and a specific user process.
sptalloc creates a mapping accessible by the kernel and all
processes. However, only those processes that have been
told the virtual address returned from sptalloc, will know
the address at which to access the memory.
Parameters
pages the number of requested pages
mode page descriptor table entry field mask.
Possible values are defined in sys/immu.h and
are:
+ PG_P - page-present bit. This flag must
be present for driver use. PG_P causes
the present bit to be set in the page
table entry. The CPU uses the present
bit to differentiate between pages that
have to be faulted in and pages that are
already there.
+ PG_RW - make segment usable for either
reading or writing. If this flag is not
ORed into mode, than the segment is
read-only. This flag only has meaning
when used with PG_US to indicate if a
user can access the segment for both
reading and writing. (Kernel processes
can read or write any present page
whether write access is "permitted' or
not.)
+ PG_US - identify owner of memory. If
ORed in, memory is allocated for a user
process, if omitted, memory is for a
kernel process. If selected, any user
process can access the page. Use with
PG_RW if write permission is required;
without PG_RW, the page is read-only.
To use this capability, a driver must
pass the return value from sptalloc back
to the user process for it to "know"
where the memory is, but this doesn't
limit its use to that process.
base set to 0 (zero) to allocate kernel memory, or
set to an physical address pointing to
previously allocated memory elsewhere.
flag Set to 1 to return immediately if memory is
not available. Set to 0 (zero) to sleep
until memory is available. If only one page
is being requested, and memory is not
available, sleep occurs however flag is set.
When sleeping is requested, sptalloc sleeps
with a priority of 0 (zero) and is not
affected by signals.
Warning
Because sptalloc may sleep, do not use at interrupt time
(from the xxintr routine).
Return Value
This routine returns the kernel virtual address of the
memory allocated. NULL is returned if map space is not
available. The size of the map is determined by the
constant sptmap which is configurable using the Link Kit.
See Also
sptfree(K), vas(K)
(printed 7/6/89)