alenlist_ops(D3X)alenlist_ops(D3X)NAME
alenlist_ops: alenlist_append, alenlist_clear, alenlist_create,
alenlist_cursor_create, alenlist_cursor_destroy, alenlist_cursor_init,
alenlist_cursor_offset, alenlist_destroy, alenlist_get, alenlist_size,
kvaddr_to_alenlist, uvaddr_to_alenlist, buf_to_alenlist - operations on
address/length lists
SYNOPSIS
#include <sys/types.h>
#include <sys/alenlist.h>
#include <sys/ddi.h>
alenlist_t
alenlist_create(unsigned flags);
void
alenlist_clear(alenlist_t plist);
void
alenlist_destroy(alenlist_t plist);
int
alenlist_size(alenlist_t plist);
alenlist_cursor_t
alenlist_cursor_create(alenlist_t plist, unsigned flags);
void
alenlist_cursor_destroy(alenlist_cursor_t ocursor);
int
alenlist_get(alenlist_t plist,
alenlist_cursor_t icursor,
size_t maxlength,
alenaddr_t *paddr,
size_t *plength,
unsigned flags);
int
alenlist_cursor_init(alenlist_t plist,
size_t offset,
alenlist_cursor_t icursor);
size_t
alenlist_cursor_offset(alenlist_t plist, alenlist_cursor_t icursor);
int
alenlist_append(alenlist_t plist,
alenaddr_t address,
size_t length,
unsigned flags);
Page 1
alenlist_ops(D3X)alenlist_ops(D3X)
alenlist_t
kvaddr_to_alenlist(alenlist_t plist,
caddr_t kvaddr,
size_t length,
unsigned flags);
alenlist_t
uvaddr_to_alenlist( alenlist_t plist,
uvaddr_t uvaddr,
size_t length,
unsigned flags);
alenlist_t
buf_to_alenlist(alenlist_t plist,
struct buf *buf,
unsigned flags);
Arguments
address An address in some address space.
buf Address of a buf struct.
flags A Boolean combination of the flags declared in
sys/alenlist.h.
icursor A handle to an existing cursor, or NULL to indicate the
implicit cursor in plist.
kvaddr A valid address in kernel virtual memory.
length The length related to an address.
maxlength The maximum length allowed in the returned address/length
pair, or 0 to indicate no maximum applies.
ocursor A handle to an existing cursor, the target of the operation.
offset An initial byte offset for icursor, usually 0.
paddr A pointer to a variable to receive the address from an
address/length pair.
plength A pointer to a variable to receive the length from an
address/length pair.
plist A handle to an existing alenlist.
uvaddr A valid address in user virtual memory for the in-context
process.
Page 2
alenlist_ops(D3X)alenlist_ops(D3X)DESCRIPTION
For an overview of address/length lists (alenlists) see alenlist(D4X).
Allocation and Release
Create an empty list using alenlist_create(). The AL_NOSLEEP flag
ensures that the caller will not sleep waiting for memory. If memory
cannot be allocated, NULL is returned. The returned list has no pairs in
it, and its implicit cursor is initialized to point to the start of the
(empty) list.
The functions kvaddr_to_alenlist(), uvaddr_to_alenlist(), and
buf_to_alenlist(), when the plist argument is NULL, allocate a new
alenlist and return it. However, these functions do not honor
AL_NOSLEEP, either when creating a list or when getting memory to extend
an existing list. If it is important not to sleep, preallocate the list.
Empty a list by applying alenlist_clear(). The implicit cursor is reset
to the start of the (empty) list.
Release a list using alenlist_destroy(). This lets the system know that
the specified List is no longer in use.
Create a cursor by calling alenlist_cursor_create(). Pass AL_NOSLEEP to
avoid sleeping on memory allocation. When a cursor cannot be created,
NULL is returned. The new cursor is associated with plist and is
initialized to point to the head of that list. More than one cursor can
point to a given list.
Use alenlist_cursor_destroy() to tell the system the cursor is no longer
needed. The cursor must not be used after this call is made.
Reading a List
Use the alenlist_get() function to retrieve pairs from the list. An
address/length pair from plist is stored based on paddr and plength. The
pair to retrieve is established by a cursor, either icursor or the
implicit cursor in plist when icursor is NULL. The cursor used is
updated by the length returned, provided the AL_LEAVE_CURSOR flag is not
used.
It is not necessary to read out exactly the pairs that were added to the
list. When maxlength is nonzero, it establishes the maximum length
retrieved. When maxlength is also an integral power of 2, the returned
length is further constrained so that the returned address and length do
not cross a maxlength boundary. For example, when maxlength is 512, the
address/length values returned are such that the next pair returned will
begin on a 512-boundary.
Returns ALENLIST_SUCCESS or ALENLIST_FAILURE. The normal cause for
failure is that the list is exhausted.
Page 3
alenlist_ops(D3X)alenlist_ops(D3X)
Call alenlist_cursor_init() to initialize a cursor to a specified offset
(usually 0). If cursorp is NULL, the implicit internal cursor of plist
is initialized.
To retrieve the current byte offset of a cursor, call
alenlist_cursor_offset(). When icursor is NULL, the offset of the
implicit cursor in plist is returned.
Call alenlist_size() to determine the number of address/length pairs in
the list.
Loading a List
The basic operation to add an address/length pair to a list is
alenlist_append(). The list is expanded if necessary. Use the
AL_NOSLEEP flag to prevent sleeping on memory allocation that might be
necessary to resize the list. Use AL_NOCOMPACT to prevent the added pair
from being merged into a logically-adjacent preceding pair. Returns
ALENLIST_SUCCESS or ALENLIST_FAILURE.
To build an alenlist that describes a buffer in kernel virtual memory,
call kvaddr_to_alenlist(). The specified kernel virtual address is
converted into a list of physical address/length pairs and the pairs are
appended to an alenlist. A handle to the alenlist is returned. When
plist is NULL, a new list is created, and this list is returned.
To build an alenlist that describes a buffer in user virtual memory, call
uvaddr_to_alenlist(). The specified user virtual address for the
specified length is converted into a list of physical address/length
pairs and the pairs are appended to an alenlist. A handle to the
alenlist is returned. When plist is NULL, a new list is created, and
this list is returned.
To build an alenlist that describes a buffer mapped by a buf structure,
call buf_to_alenlist(). The memory described by the buf is converted
into a list of physical address/length pairs and the pairs are appended
to an alenlist. A handle to the alenlist is returned. When plist is
NULL, a new list is created, and this list is returned.
SEE ALSOalenlist(D4X), IRIX Device Driver Programmer's Guide
Page 4