alenlist man page on IRIX

Man page or keyword search:  
man Server   31559 pages
apropos Keyword Search (all sections)
Output format
IRIX logo
[printable version]



alenlist(D4X)							 alenlist(D4X)

NAME
     alenlist - overview of Address/Length Lists

DESCRIPTION
     An Address/Length List or alenlist is an abstract object containing a
     sequential list of address/length pairs.

     All addresses in the list belong to the same address space, for example
     kernel virtual address space, physical memory address space, PCI DMA
     space, VME DMA space, and so on.  All lengths are byte counts.  Each
     address/length pair added to a list describes one contiguous segment in
     the relevant address space.  Together, all the pairs in the list describe
     a region of memory, typically an I/O buffer, that is logically, but not
     necessarily physically, contiguous.

     When a driver receives a request for I/O, the request may be specified in
     one of several forms, for example a buf structure page list (see
     buf(D4)), a kernel virtual address, a user virtual address, or a vector
     of addresses from a device register array.	 The driver can convert any of
     these forms into a single alenlist for easy management.

     Other kernel layers (notably, the PCI infrastructure, see pciio(D3))
     accept alenlists.	Translation from one address space to another, a
     constant challenge for device drivers, can be performed on an entire
     alenlist in a single operation, avoiding repeated bouncing up and down
     through layers of software for each segment.

     An alenlist is created by the driver when needed.	It expands
     automatically as address/length pairs are added to the list.  Its memory
     can easily be released for recycling, or a list can be cleared and re-
     used.  There are operations to append a new pair to a list, and to load a
     list based on a buf structure or based on a user or kernel virtual buffer
     address and size.

     Address/length pairs can be read out from a list in sequence, and in
     length units different from the units that were initially loaded (for
     example, load the list based on a user-space buffer, then read out pairs
     in 512-byte segments).

     A cursor marks a position within an alenlist, and is used to scan through
     the pairs in the list.  A cursor can point to the beginning of its list,
     any number of bytes into the list, or at the end of the list.  Every
     alenlist contains an implicit cursor for simple management, but there are
     operations to create, destroy, and initialize additional cursors, so
     multiple positions can be maintained at once.

   Usage
     In order to use any of the Address/Length types or interfaces, a driver
     should include these header files in this order:

									Page 1

alenlist(D4X)							 alenlist(D4X)

	  #include <sys/types.h>
	  #include <sys/alenlist.h>
	  #include <sys/ddi.h>

   Types
     The following abstract types are used and returned by alenlist functions.

     alenaddr_t	 An abstract address in some address space.  This is the type
		 of any address added to a list.  It is guaranteed to be big
		 enough to hold an address in any supported address space
		 (currently 64 bits).

     size_t	 The standard byte-count type.	Every address/length pair in a
		 list comprises one alenaddr_t and one size_t.

     alenlist_t	 A handle to an alenlist.

     alenlist_cursor_t
		 A handle to a cursor, an object that designates a position
		 within an alenlist.  An alenlist_cursor_t value of NULL
		 always designates the implicit cursor of a list.  Non-null
		 values designate cursor objects allocated separate from their
		 lists.

   Operations
     The functions that operate on alenlists are detailed in
     alenlist_ops(D3X).	 Operations to allocate and destroy alenlists are as
     follows:

     o	 alenlist_create() creates a new, empty list.

     o	 alenlist_destroy() recycles the storage used by an alenlist.

     o	 alenlist_cursor_create() creates a new cursor object.

     o	 alenlist_cursor_destroy() recycles the storage used by a cursor.

     Operations to clear and load pairs into an alenlist are as follows:

     o	 alenlist_clear() empties a list.

     o	 alenlist_append() appends one address/length pair to a list.

     o	 kvaddr_to_alenlist() converts a kernel virtual address and length
	 into physical memory address/length pairs and appends the pairs to a
	 list.

     o	 uvaddr_to_alenlist() converts a user process virtual address into
	 physical memory address/length pairs and appends the pairs to a list.

									Page 2

alenlist(D4X)							 alenlist(D4X)

     o	 buf_to_alenlist() examines a buf structure (see buf(D4)) and appends
	 physical memory address/length pairs to describe the buffer to a
	 list.

     In addition, pciio_dma(D3) documents pciio_dmamap_list(), a function that
     translates an alenlist of physical memory addresses into an alenlist of
     PCI bus addresses for DMA use.

     Operations to read out address/length pairs from an alenlist are as
     follows:

     o	 alenlist_get() returns an address/length pair from a list, based on
	 the implicit cursor or on a specified cursor, and optionally advances
	 the cursor.

     o	 alenlist_size() returns the number of address/length pairs in a list.

     o	 alenlist_cursor_init() initializes a specific cursor or an implicit
	 cursor to a specified offset.

     o	 alenlist_cursor_offset() returns the current offset of a cursor.

   Flags
     The following flag values are used with alenlist functions:

     AL_NOSLEEP	 Indicates that the caller does not wish to be put to sleep
		 while waiting for resources such as memory.  If an operation
		 would entail sleeping, the function returns failure.

     AL_NOCOMPACT
		 Indicates that adjacent address/length pairs that happen to
		 be contiguous in their address space should not be compacted
		 and treated as a single unit (which is the default behavior).
		 Rather, they should be treated as if there is a
		 discontiguity.	 This flag is not needed by most drivers.

     AL_LEAVE_CURSOR
		 Indicates that the operation should not affect the position
		 of the internal cursor.

   Error Codes
     The following error codes are used by all alenlist functions:

     ALENLIST_SUCCESS
		 Indicates a successful operation.

     ALENLIST_FAILURE
		 Indicates a failed operation.

									Page 3

alenlist(D4X)							 alenlist(D4X)

SEE ALSO
     alenlist_ops(D3X), pciio_dma(D3), IRIX Device Driver Programmer's Guide

									Page 4

[top]

List of man pages available for IRIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net