 |
Index for
Section 3 |
|
 |
Alphabetical
listing for I |
|
 |
Bottom of
page |
|
imc_asattach(3)
NAME
imc_asattach - Attaches a region of Memory Channel address space to the
virtual address space of a process
LIBRARY
Memory Channel API library (libimc.a)
SYNOPSIS
#include <sys/imc.h>
int imc_asattach (
imc_asid_t id,
imc_dir_t dir,
int mode,
int flag,
caddr_t *address );
PARAMETERS
id Identifies the region of Memory Channel address space to be
attached. The identifier specified by the id parameter must have
previously been generated by a call to the imc_asalloc function.
dir Specifies whether the region is attached to transfer data to the
Memory Channel address space or to receive data from it. The dir
parameter contains one of the following values:
IMC_TRANSMIT
Attach the region as a transmit area.
IMC_RECEIVE
Attach the region as a receive area.
mode Specifies the sharing mode, shared or nonshared, for the region.
If the region is designated as shared, multiple processes
executing on a given host can attach the region to their process
virtual address space. The sharing mode is specified by the first
process on the host to attach the region. The sharing mode is
host-specific. Other processes that subsequently attach the
region cannot change the sharing mode. If a calling process tries
to attach a region that has an incompatible sharing mode, an
error condition will result.
The mode parameter has the following values:
IMC_SHARED
The region is shared.
IMC_NONSHARED
The region is not shared.
flag Specifies, for a transmit region, that all writes to the region
are looped back to the host that writes the data; or, for a
receive region, that a user-supplied address will be specified in
the address parameter.
If this flag is not set for a transmit region, processes on this
host that attach the region for receive will not see the data
that is transmitted from the host. The flag to enable the
loopback feature is set by the first process on the host to
attach the transmit region. Subsequent calls to the
imc_asattach() function on the same host must adhere to the
convention established by the first call to the function.
For transmit attaches, you must enable the loopback feature when
attaching to coherent regions. (A coherent region is one for
which the IMC_COHERENT flag is specified in the imc_asalloc()
function call that allocates the region.)
The flag parameter has one of the following values for a transmit
attach:
IMC_LOOPBACK
Enable the loopback feature.
ZERO (0) Disable the loopback feature.
For receive attaches, use the flag parameter to attach to a
user-supplied address. The flag parameter has one of the
following values for attach to a user-supplied address:
IMC_USE_ADDR
Attach to the address specified by the user in the
address parameter.
ZERO (0) Attach to an address in the process virtual address
space assigned by the kernel, and return that address
in the address parameter.
address For transmit attaches, returns the address in the process virtual
address space that is mapped to the attached region of Memory
Channel address space. This address is assigned by the kernel.
This also applies to receive attaches where the flag parameter
has the value ZERO (0).
For receive attaches, if the flag parameter has the value
IMC_USE_ADDR, the address must be user-specified in the address
parameter. The address must be page-aligned, and must represent a
hole in the process virtual address space. Also, the extent of
the hole must be enough to contain the region.
DESCRIPTION
The imc_asattach() function attaches a region of Memory Channel address
space to an address in the virtual address space of the calling process.
The region must first have been allocated by means of a call to the
imc_asalloc() function.
The calling process uses the dir parameter to attach the region for receive
or transmit. Transmit regions are attached as write-only. Any attempt to
read a transmit region will result in a segmentation violation. Therefore,
some C operations, such as postincrement and predecrement, will cause a
segmentation violation. Accesses to storage locations that are not integral
multiples of four bytes will generate read-modify-write cycles that will
also cause segmentation violations. Library functions such as bcopy(3) will
induce this behavior when the length parameter is not an integral multiple
of eight bytes, or when the source or destination arguments are not eight-
byte aligned. The imc_bcopy() function is designed to be used instead of
the bcopy(3) function in such cases, as its src parameter and its dest
parameter can both have an arbitrary alignment.
Attaching a region to receive data does not guarantee that the contents of
the region are the same as for other processes attached to the region. Any
previous writes to the region are not reflected in the process address
space, but subsequent writes do appear. To ensure that the contents of the
region are the same for all processes, specify the IMC_COHERENT flag in the
imc_asalloc() function when allocating the region. Otherwise, the process
must use application-specific mechanisms to transmit any existing memory
content to the new region.
RETURN VALUES
The imc_asattach() function returns one of the following values:
IMC_SUCCESS
Normal successful completion.
IMC_BADADDR
In the case of a receive attach, the flag parameter has the value
IMC_USE_ADDR, and an invalid address was specified in the address
parameter.
IMC_BADPARM
An invalid parameter was specified in the call to the
imc_asattach function.
IMC_BADREGION
The region specified in the call to the imc_asattach function is
invalid.
IMC_LATEJOIN
This host joined the cluster after the region was allocated.
IMC_LOOPBACKERR
Another process on this host has already attached the region,
specifying a different value for the flag parameter than the
value specified in this call to the imc_asattach() function; or,
the value of the flag parameter is incorrect. (If the
IMC_COHERENT flag is specified when the imc_asalloc() function
allocates the region, the IMC_LOOPBACK flag must be specified in
the call to the imc_asattach() function.)
IMC_MAPENTRIES
An attempt has been made to exceed the maximum number of process
map entries. This maximum is set by the vm-mapentries parameter.
IMC_MCFULL
There is not enough Memory Channel address space to attach to the
region.
IMC_NOMAPPER
Attach to a coherent region could not be completed because the
imc_mapper daemon was not found on a host in the cluster.
IMC_NONSHARERR
The region has already been mapped as nonshared; it cannot now be
mapped as shared.
IMC_NORESOURCES
There are insufficient Memory Channel data structures available
to attach the region.
IMC_NOTALLOC
The region is not allocated.
IMC_NOTINIT
This host has not been initialized to use the Memory Channel
Application Programming Interface (API) library.
IMC_PERMIT
The process is not permitted to attach the region.
IMC_PTPERR
An attempt was made to attach for transmit to a region already in
use as a point-to-point attach region; or, an attempt was made to
attach for receive, on a host other than the targeted host, to a
point-to-point attach region.
IMC_RECMAPPED
The region has already been mapped by the process to receive
data.
IMC_RXFULL
There are no more pages of physical memory available to the
Memory Channel API library.
IMC_SHARERR
The region has already been mapped as shared; it cannot now be
mapped as nonshared.
IMC_XMITMAPPED
The region has already been mapped by the process to transmit
data.
RELATED INFORMATION
Introduction: imc(3)
Commands: imc_init(1), imcs(1)
Functions: imc_api_init(3), imc_asalloc(3), imc_asattach_ptp(3),
imc_asdealloc(3), imc_asdetach(3), imc_bcopy(3)
Cluster Highly Available Applications
|
Index for
Section 3 |
|
|
Alphabetical
listing for I |
|
 |
Top of
page |
|