3 MEMORY CHANNEL API Library Interface

This chapter describes the functions that are provided by the MEMORY CHANNEL API library application programming interface (API). It discusses the following topics:

Header files (Section 3.1)

Library (Section 3.2)

Compiling applications that use the MEMORY CHANNEL API library (Section 3.3)

Overview of MEMORY CHANNEL API library commands and functions (Section 3.4)

Command descriptions (Section 3.5)

Function descriptions (Section 3.6)

The descriptions of the MEMORY CHANNEL API library functions are presented in alphabetical order and in reference page style.

3.1 Header Files

The MEMORY CHANNEL API library includes the imc.h header file. This file defines the data structures, data types, and constants associated with the MEMORY CHANNEL API library, including a definition for the version of MEMORY CHANNEL software. The header file is called imc.h and is located in the /usr/include/sys directory. Use the following line to include the header file in programs that use the MEMORY CHANNEL API library:

#include <sys/imc.h>

3.2 Library

The MEMORY CHANNEL API library functions are located in the system library. The shared version is located in the /usr/shlib directory; it is called libimc.so. The nonshared version is located in the /usr/ccs/lib directory; it is called libimc.a.

3.3 Compiling Applications that Use the MEMORY CHANNEL API Library

Use the cc command to compile applications based on the MEMORY CHANNEL API library, making sure that you include the library. The following example shows how to compile a program called program.c:

cc -o program program.c -limc

3.4 Overview of MEMORY CHANNEL API Library Commands and Functions

This section contains reference information that introduces the MEMORY CHANNEL API library commands and functions.

imc(3)

NAME

imc - Introduction to the MEMORY CHANNEL Application Programming Interface (API)

Description

The MEMORY CHANNEL Application Programming Interface (API) library provides user space access to the MEMORY CHANNEL services available in the TruCluster environment.

MEMORY CHANNEL API library functions provide the following services:

MEMORY CHANNEL API cluster information

Access to MEMORY CHANNEL address space

A clusterwide lock system

MEMORY CHANNEL API cluster signals

MEMORY CHANNEL API library management

Commands

The following MEMORY CHANNEL API library commands are available:

imc_init(1): Initializes and configures the MEMORY CHANNEL API library on the current host.
imcs(1): Reports on MEMORY CHANNEL status.

Functions

MEMORY CHANNEL API functions can be grouped into categories. An introduction to each category and a brief description of each function follows.

MEMORY CHANNEL API Cluster Information

A MEMORY CHANNEL API cluster is formed when a number of hosts are physically connected by a MEMORY CHANNEL interconnect, and when each host has invoked the imc_init(1) command.

Independent MEMORY CHANNEL interconnects, or physical rails, can be configured as logical rails, in one of the following styles:

Single-rail
This configuration has a one-to-one relationship between a physical rail and a logical rail, with no failover properties.

Failover pair
In this configuration, a logical rail consists of two physical rails, with one physical rail inactive and available on standby in case the active physical rail fails. Failover is transparent to the user.

The following functions provide information about the MEMORY CHANNEL API cluster:

imc_getclusterinfo(3): Gets information about the hosts and the logical rails that form a MEMORY CHANNEL API cluster.
imc_wait_cluster_event(3): Blocks the caller until a MEMORY CHANNEL API cluster event occurs. MEMORY CHANNEL API cluster events include hosts entering the MEMORY CHANNEL API cluster or leaving the MEMORY CHANNEL API cluster, and logical rails coming on line or going off line.

Accessing MEMORY CHANNEL Address Space

A process accesses MEMORY CHANNEL address space by mapping a region of the address space into its own process virtual address space. This is done by allocating a region and then attaching the allocated region to the virtual address space of a process.

By attaching the same region to the virtual address space of two different processes, it is possible for one process to write data into the virtual address space of the other process using standard store and load instructions.

The following functions are available to allow access to MEMORY CHANNEL address space:

imc_asalloc(3): Allocates a region of MEMORY CHANNEL address space on a specified logical rail.
imc_asattach(3): Attaches a region of MEMORY CHANNEL address space to the virtual address space of a process.
imc_asattach_ptp(3): Attaches in point-to-point mode a region of MEMORY CHANNEL address space to the virtual address space of a process.
imc_bcopy(3): Provides an efficient way of copying data into MEMORY CHANNEL address space.
imc_asdetach(3): Detaches a region of MEMORY CHANNEL address space from the virtual address space of the calling process.
imc_dealloc(3): Deallocates a region of MEMORY CHANNEL address space.

The MEMORY CHANNEL hardware takes care of all error detection. The MEMORY CHANNEL API provides the following routines to access the error state of the hardware:

imc_ckerrcnt_mr(3): Checks for the existence of outstanding errors on a specified logical rail on MEMORY CHANNEL hosts.
imc_rderrcnt_mr(3): Reads the clusterwide error count for a specified logical rail.

Clusterwide Lock System

The MEMORY CHANNEL API provides a clusterwide lock facility. Locks are allocated in sets; they are not allocated individually. Clusterwide locks are managed using the following functions:

imc_lkalloc(3): Creates a lock set.
imc_lkacquire(3): Acquires a lock from a lock set.
imc_lkrelease(3): Releases a lock from a lock set.
imc_lkdealloc(3): Deallocates a lock set.

MEMORY CHANNEL API Cluster Signals

The MEMORY CHANNEL API allows processes to send signals to processes executing on other hosts in the MEMORY CHANNEL API cluster, using the following function:

imc_kill(3): Sends a signal to a running process.

MEMORY CHANNEL API Management

The following MEMORY CHANNEL API management functions are available:

imc_api_init(3)

Initializes the MEMORY CHANNEL API library.

Note

The imc_api_init function must be called before any other MEMORY CHANNEL API function is called.

imc_perror(3)

Prints a message that explains a MEMORY CHANNEL function error.

3.5 Command Descriptions

This section contains reference information for the MEMORY CHANNEL API library initialization command, and the MEMORY CHANNEL API library status report command.

imc_init(1)

NAME

imc_init - Initializes and configures the MEMORY CHANNEL API library on the current host

Synopsis

/usr/sbin/imc_init [-amaxalloc] [-rmaxrecv]

Options

-a maxalloc: Specifies, in MB, the total amount of MEMORY CHANNEL address space to be made available to the MEMORY CHANNEL API library. The default amount of address space is 10 MB. This is a clusterwide limit.
-r maxrecv: Specifies, in MB, the maximum amount of MEMORY CHANNEL address space that can be attached for receive on the host. The default amount of receive space is 10 MB. This limit applies only to the current host.

Description

The imc_init command, available in a Production Server or MEMORY CHANNEL software configuration, initializes and configures the MEMORY CHANNEL API library on the current host. Initialization of the MEMORY CHANNEL API library occurs either by automatic execution of the imc_init command at system boot time, or by the system administrator invoking the command from the command line after the system boots.

Initialization of the MEMORY CHANNEL API library at system boot time is controlled by the IMC_AUTO_INIT variable in the /etc/rc.config file. If the value of this variable is set to 1, the imc_init command is invoked at system boot time. When the MEMORY CHANNEL API library is initialized at boot time, the values of the -a maxalloc and -a maxrecv flags are set to the values specified by the IMC_MAX_ALLOC and IMC_MAX_RECV variables in the /etc/rc.config file.

If the IMC_AUTO_INIT variable is set to zero (0), the MEMORY CHANNEL API library is not initialized at system boot time. The system administrator must invoke the imc_init command to initialize the library. The parameter values in the /etc/rc.config file are not used when the imc_init command is manually invoked.

The imc_init command initializes the MEMORY CHANNEL API library the first time it is invoked, whether this happens at system boot time or after the system has booted. The value of the -a maxalloc flag must be the same on all hosts in the MEMORY CHANNEL API cluster. If different values are specified, the maximum value specified for any host determines the clusterwide value that applies to all hosts.

After the MEMORY CHANNEL API library has initialized on the current host, the system administrator can invoke the imc_init command again to reconfigure the values of the maxalloc and maxrecv resource limits, without forcing a reboot. The system administrator can increase or decrease either limit, but the new limits cannot be lower than the current usage of the resources. Reconfiguring the MEMORY CHANNEL API cluster from the command line does not read or modify the values specified in the /etc/rc.config file. The system administrator can use the rcmgr(8) command to modify the parameters and have them take effect when the system reboots.

You must have root privileges to execute the imc_init command.

Error Messages

The imc_init command prints the following error messages:

Receive area is bigger than the maximum allocation
The receive size is larger than the maximum allocation size.

No MEMORY CHANNEL memory available
There is not enough MEMORY CHANNEL address space to initialize the MEMORY CHANNEL API library.

No MEMORY CHANNEL resources available
There are insufficient MEMORY CHANNEL data structures available to initialize the MEMORY CHANNEL API library.

MEMORY CHANNEL is not initialized for user access
This host has not been initialized to use the MEMORY CHANNEL API. Ensure that the MEMORY CHANNEL cables are properly connected.

Privileged command
You do not have root privileges. You must have root privileges to execute the imc_init command.

System wired memory limit cannot be exceeded. See kernel vm parameter vm-syswiredpercent
An attempt has been made to exceed the maximum quantity of system wired memory. The amount of MEMORY CHANNEL address space that can be attached for receive on the host cannot be increased beyond the limit imposed by the system parameter vm-syswiredpercent.

Invalid parameter specification
An attempt has been made to set the maxalloc parameter or the maxrecv parameter to zero (0), or to a non-numeric or a negative value.

FILES

/usr/sbin/imc_init: Specifies the command path.
/etc/rc.config: Contains the variables that control whether or not the MEMORY CHANNEL API library is initialized at system boot time, and specifies the parameter values to be applied on initialization.

imcs(1)

NAME

imcs - Reports on MEMORY CHANNEL status

Synopsis

/usr/sbin/imcs [-m] [-l] [-r] [-f] [-h]

Options

-m: Displays the names of all hosts that have initialized the MEMORY CHANNEL API.
-l: Displays information about all lock sets in use in the MEMORY CHANNEL API cluster.
-r: Displays information about all allocated regions in the MEMORY CHANNEL API cluster.
-f: Displays full MEMORY CHANNEL status information.
-h: Displays a user help message on the imcs command.

Description

The imcs command writes information to the standard output about currently active MEMORY CHANNEL facilities. The details displayed vary according to the flags used with the command. If no flags are specified, the imcs command displays the names of all MEMORY CHANNEL API cluster members, and information about active MEMORY CHANNEL regions and MEMORY CHANNEL lock sets.

The information is displayed as a list of regions or lock sets under the following headings:

Type

The type of the subsystem that created the region. Possible values are:

IMC: Region was created using MEMORY CHANNEL API.
PVM: Region was created using DIGITAL Parallel Virtual Machine (PVM).

ID

An identifier that uniquely identifies the MEMORY CHANNEL region.

KEY

An application-specific key that refers to the MEMORY CHANNEL region.

SIZE

The size, in bytes, of the MEMORY CHANNEL address space region allocated.

MODE

The access mode of the region or lock set. The access mode consists of nine bits and is similar to the UNIX permission convention, except that there is no execute bit. There are three sets of three bits each. The first set of three bits refers to the owner's permissions; the next set refers to permissions of others in the user group of the region; and the last set refers to all other permissions.

Within each set of three bits, the first character indicates permission to read the region, the second character indicates permission to write to the region, and the last character is currently unused. The permissions are indicated as follows:

r: Read permission is granted
w: Write permission is granted
-: This character is not used at present

OWNER

The username of the owner of the region or lock set.

GROUP

The group of the owner of the region or lock set.

RAIL

Specifies the MEMORY CHANNEL logical rail used for the region. The first logical rail is numbered zero (0), the second logical rail is numbered 1, and so on, up to a maximum defined by a constant, IMC_MAXRAILS.

FLAG

Specifies whether an allocated region was created as coherent, point-to-point, point-to-point coherent, or non-coherent. Flags apply only to MEMORY CHANNEL regions, not to locks.

NLOCKS: The number of locks available in the lock set.

Examples

When the /usr/sbin/imcs command is entered with no flags specified, details of MEMORY CHANNEL API cluster members, active MEMORY CHANNEL regions, and MEMORY CHANNEL lock sets are displayed, as shown in the following example:

            MEMORY CHANNEL Cluster Members:
                    member1.mydmn.myorg
                    member2.mydmn.myorg
                    member3.mydmn.myorg
 
            MEMORY CHANNEL Regions:
 
            Type  ID     KEY            SIZE       MODE       OWNER     GROUP
            IMC   1740   5634309        204800     rw-rw-rw-  user1     users
            IMC   1686   5634307        204800     rw-rw-rw-  user2     users
            IMC   1627   5634306        483228     rw-rw-rw-  user2     users
            IMC   1626   5634305        8192       rw-rw-rw-  user3     users
            PVM   1576   17231442411520 393216     rw-rw-rw-  user4     users
            IMC   612    611            4382720    r--------  user5     users
 
            MEMORY CHANNEL Lock Sets:
 
            Type  KEY            MODE       OWNER     GROUP     NLOCKS
            IMC   37231          rw-rw-rw-  user1     users     110
            PVM   17231442345984 rw-rw-rw-  user2     users     2
            IMC   612            ------rw-  root      users     4

When the -f flag is used with the /usr/sbin/imcs command, the logical rail used is displayed under the RAIL heading, and the coherency of each allocated region is displayed under the FLAG heading, in addition to the details displayed in the previous example. Possible values under the FLAG heading are:

Coherent

Point-to-point

Point-to-point coherent

Non-coherent

3.6 Function Descriptions

This section contains reference information for each of the MEMORY CHANNEL API library functions.

imc_api_init(3)

NAME

imc_api_init() - Initializes the MEMORY CHANNEL API library

Synopsis

#include <sys/imc.h>

int imc_api_init( unsigned long* i_param );

Parameters

i_param: This parameter is reserved for future use by DIGITAL. You must set the value of this parameter to NULL.

Description

The imc_api_init() function initializes the MEMORY CHANNEL API library. A process must call the imc_api_init() function before calling any of the other MEMORY CHANNEL API functions.

If a process forks, the imc_api_init() function must be called before calling any other API functions in the child process, or undefined behavior will result.

Return Values

The imc_api_init function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.
IMC_NORESOURCES: There are insufficient MEMORY CHANNEL data structures available to initialize the MEMORY CHANNEL API library.
IMC_INITERR: An error occurred while initializing the MEMORY CHANNEL API environment.

imc_asalloc(3)

NAME

imc_asalloc() - Allocates a region of MEMORY CHANNEL address space on a specified logical rail

Synopsis

#include <sys/imc.h>

int imc_asalloc( imc_key_t key, imc_size_t size, imc_perm_t perm, int flag, imc_asid_t* id, int logical_rail );

Parameters

key

Specifies an application-specific key that refers to the region. Other processes that allocate the region also specify this key. This ensures that access to the region is coordinated on a clusterwide basis.

size

Specifies the size, in bytes, of the MEMORY CHANNEL address space region to be allocated. The imc_asalloc()function allocates address space, in pages, and it rounds up the value specified by the size parameter accordingly.

perm

Specifies the read and write permissions for the allocated region. The permission code is similar to the UNIX permission convention, except that there is no execute flag. The value of the perm parameter is obtained by carrying out a logical OR operation on the following values:

`IMC_URW`	User read and write
`IMC_UR`	User read
`IMC_UW`	User write
`IMC_GRW`	Group read and write
`IMC_GR`	Group read
`IMC_GW`	Group write
`IMC_ORW`	Other read and write
`IMC_OR`	Other read
`IMC_OW`	Other write

flag

Specifies whether or not the region is to be mapped into all hosts on the MEMORY CHANNEL API cluster at the time of allocation. The flag parameter has the following values:

IMC_COHERENT: Allocate a coherent region. When other processes allocate and attach this region, they will see all updates to the region since the region was created. When the IMC_COHERENT flag is specified, the physical pages that underlie the region are nonpageable on all hosts.
ZERO (0): Do not allocate a coherent region. When processes on other hosts allocate and attach the region, they will see all updates to the region from then on. However, the initial contents of the region are indeterminate.

id

Returns an identifier that uniquely identifies the allocated MEMORY CHANNEL region.

logical_rail

Specifies the MEMORY CHANNEL logical rail to use. The first logical rail is numbered zero ( 0 ), the second logical rail is numbered 1, and so on, up to a maximum defined by a constant, IMC_MAXRAILS.

Description

The imc_asalloc() function allocates a region of MEMORY CHANNEL address space on a specified logical rail. If the function successfully allocates the region, it returns the region identifier in the id parameter. If the function call is unsuccessful, the value of the id parameter is undefined. If a region with the key specified in the key parameter has already been allocated on the MEMORY CHANNEL API cluster, then the imc_asalloc() function returns the identifier of that region, and does not allocate a new region. Individual applications should define their own naming scheme for keys. The use of meaningful application-specific keys is recommended.

It is possible for multiple processes on a given host to allocate the same region of MEMORY CHANNEL address space. When multiple processes allocate a region, the permissions specified by each process must be compatible clusterwide; otherwise, an error condition will result.

The permissions associated with a region are determined by the first process to allocate the region.

When processes on multiple hosts allocate a region, the initial contents of the region might not be the same on all hosts. This situation can arise because a process that has mapped the same MEMORY CHANNEL region for transmit might update the contents of the region before other processes map the region for receive. To ensure that the region is coherent on all hosts in the MEMORY CHANNEL API cluster, specify the IMC_COHERENT flag when allocating the region.

The MEMORY CHANNEL API library maintains the total amount of available MEMORY CHANNEL address space as a clusterwide resource. If the imc_asalloc()function tries to allocate a region that exceeds the amount of address space available, an error condition will result.

Return Values

The imc_asalloc function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_asalloc()function.
IMC_BADRAIL: The logical rail number specified in the call to the imc_asalloc() function is invalid, or the logical rail is inactive.
IMC_BADSIZE: The specified region is already allocated, and the size of the region as specified in this call to the imc_asalloc()function does not match the size specified in the previous call.
IMC_COHERENCYERR: The specified region is already allocated, and the value of the flag parameter IMC_COHERENT specified in this call to the imc_asalloc() function does not match the value specified in the previous call.
IMC_MCFULL: There is not enough MEMORY CHANNEL address space to allocate the amount specified by the size parameter.
IMC_NOMEM: There is insufficient local memory available to allocate the region.
IMC_NORESOURCES: There are insufficient MEMORY CHANNEL data structures available to allocate the region.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.
IMC_PERMIT: The specified region is already allocated, with a permission code that is incompatible with the code specified in the perm parameter.
IMC_PRIOR: The region has already been allocated by this process.
IMC_WRONGRAIL: The specified region has already been allocated by a process on the MEMORY CHANNEL API cluster, using the same key, on a specific logical rail; the specified region cannot now be allocated on a different logical rail.

imc_asattach(3)

NAME

imc_asattach - Attaches an allocated region of MEMORY CHANNEL address space to the virtual address space of a process

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 number 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 MEMORY CHANNEL API 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 a coherent 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 MEMORY CHANNEL API 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 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.

imc_asattach_ptp(3)

NAME

imc_asattach_ptp - Attaches in point-to-point mode an allocated region of MEMORY CHANNEL address space to the virtual address space of a process

Synopsis

#include <sys/imc.h>

int imc_asattach_ptp( imc_asid_t id, int mode, int flag, char* hostname, 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.

mode

The mode parameter has the following values:

`IMC_SHARED`	The region is shared.
`IMC_NONSHARED`	The region is not shared.

flag

The loopback feature is not permitted for point-to-point regions.

The flag parameter has the following value for a transmit attach:

ZERO (0): Disable the loopback feature.

hostname

Specifies the name of the host to which the region is attached for point-to-point transmission.

address

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.

Description

The imc_asattach_ptp() 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 imc_asattach_ptp() function attaches the region in point-to-point mode. This means that writes to the region are sent only to the host specified in the hostname parameter. In contrast, writes to regions attached by means of a call to the imc_asattach() function are broadcast to all hosts in the MEMORY CHANNEL API cluster.

Regions attached using the imc_asattach_ptp() function are always attached in transmit mode.

Because of the nature of point-to-point attach mode, looped-back writes are not permitted.

Return Values

The imc_asattach_ptp function returns one of the following values:

IMC_SUCCESS

Normal successful completion.

IMC_BADPARM

An invalid parameter was specified in the call to the imc_asattach_ptp() function.

IMC_BADREGION

The region specified in the call to the imc_asattach_ptp() function is invalid.

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_ptp() function; or the value of the flag parameter is incorrect. You cannot enable the loopback feature when calling the imc_asattach_ptp() function.

IMC_LATEJOIN

This host joined the MEMORY CHANNEL API cluster after the region was allocated.

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 a coherent 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 MEMORY CHANNEL API 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 API library.

IMC_PERMIT

The process is not permitted to attach the region.

IMC_PTPERR

This value is returned if one of the following events occurs:

An attempt is made to attach a region already attached in point-to-point mode to a different target host.

An attempt is made to point-to-point attach a region that is already broadcast attached (attached for read on more than one host).

An attempt is made to point-to-point attach a region that is already broadcast transmit attached.

An attempt is made to point-to-point attach a region that is already attached for read on the local host.

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.

imc_asdealloc(3)

NAME

imc_asdealloc - Deallocates a region of MEMORY CHANNEL address space

Synopsis

#include <sys/imc.h>

int imc_asdealloc( imc_asid_t id );

Parameter

id: Identifies the region of MEMORY CHANNEL address space to be deallocated. The identifier specified by the id parameter must have previously been generated by a call to the imc_asalloc()function.

Description

The imc_asdealloc() function deallocates a region of MEMORY CHANNEL address space. Mapped regions must be detached by means of a call to the imc_asdetach() function before being deallocated; otherwise, an error condition will result.

Deallocating a region will not necessarily free the region of MEMORY CHANNEL address space. This is because multiple processes can allocate a given region; the space is freed only when the last process on the MEMORY CHANNEL API cluster deallocates the region.

All MEMORY CHANNEL regions allocated by a process are automatically deallocated when the process exits.

Return Values

The imc_asdealloc function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_ATTACHED: The specified region of MEMORY CHANNEL address space is attached by the process. The region must be detached before it can be deallocated.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_asdealloc()function.
IMC_BADREGION: The region specified by the id parameter was not found.
IMC_NOTALLOC: The region is not allocated.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.

imc_asdetach(3)

NAME

imc_asdetach - Detaches a region of MEMORY CHANNEL address space from the virtual address space of the calling process

Synopsis

#include <sys/imc.h>

int imc_asdetach( imc_asid_t id );

Parameter

id: Identifies the region of MEMORY CHANNEL address space to be detached. The identifier specified by the id parameter must be the one generated by the call to the imc_asalloc() function that allocated the region.

Description

The imc_asdetach() function detaches a region of MEMORY CHANNEL address space. When the function is called, it detaches all transmit and receive regions associated with the identifier specified by the id parameter. After a region is detached, all addresses associated with the region become invalid.

All MEMORY CHANNEL regions attached by a process are automatically detached when the process exits.

Return Values

The imc_asdetach function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_asdetach() function.
IMC_BADREGION: The region specified in the call to the imc_asdetach() function is invalid.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.

imc_bcopy(3)

NAME

imc_bcopy - Efficient data copy to a MEMORY CHANNEL transmit region

Synopsis

#include <sys/imc.h>

long imc_bcopy( void *src, void *dest, long length, long dest_write_only, long first_dest_quad );

Parameters

src: Points to the source data buffer for the imc_bcopy function.
dest: Points to the destination data buffer for the imc_bcopy function.
length: Specifies the length, in bytes, of the original data buffer.
dest_write_only: Specifies whether the destination is a write-only pointer.
first_dest_quad: Specifies the contents of the first quadword of the destination.

Description

The imc_bcopy() function copies length bytes from the buffer pointed to by the src parameter into the buffer pointed to by the dest parameter.

The imc_bcopy() function is highly optimized for the Alpha architecture and implements an extremely efficient copy operation. You can use the imc_bcopy() function for a high-bandwidth copy between two buffers in normal memory, as well as for copying to MEMORY CHANNEL transmit addresses, regardless of buffer alignment or data length.

A MEMORY CHANNEL region may be attached for transmit (that is, for write) using the imc_asattach() function or the imc_asattach_ptp() function. The address for such a region is write-only, and any attempt to read from a transmit address will result in a segmentation violation. In addition, segmentation violations will result from any operation that causes the compiler to generate read-modify-write cycles. For example:

Assignment to simple data types that are not an integral multiple of four bytes.

Use of the bcopy(3) function where the length parameter is not an integral multiple of eight bytes, or where 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.

If the value of the dest_write_only parameter is zero (0), unaligned writes to the dest address can cause the quadwords containing the first and last destination bytes to be read.

If the value of the dest_write_only parameter is nonzero, as it would be for MEMORY CHANNEL transmit addresses, the first_dest_quad parameter value is used as the contents of the first quadword of the destination, and zero (0) is used as the contents of the last quadword of the destination. If the caller does not know the contents of the first quadword of the destination, use zero (0) as the value of the first_dest_quad parameter. This will result in up to three bytes of zeros before the start of the copied data, and up to three bytes of zeros after the end of the copied data.

The imc_bcopy() function returns the last quadword written to the destination. You can use this capability to concatenate several noncontiguous buffers to a contiguous write-only destination. To perform this operation, known as a gather operation, use the return value from one call to the imc_bcopy() function as the first_dest_quad parameter for the next call to the imc_bcopy() function. If you are not performing a gather operation, that is, if the start of the dest parameter is not in the same quadword as the end of the previous dest parameter, then the value of the first_dest_quad parameter should be zero.

Restrictions

If the source and destination buffers overlap, the result of the copy operation is undefined.

Examples

This example shows how to use the imc_bcopy() function to copy between two buffers that have arbitrary alignment. The destination buffer is not a MEMORY CHANNEL transmit address. In this example, 25 bytes are copied from an aligned source to a destination that is not aligned on a quadword boundary.
```
           int        source[256];
           char       destination[1024];
           long       last_quad;
 
           /* fill in source buffer */
 
           /* copy part of source buffer */
 
           last_quad = imc_bcopy(source,destination+3,25,0,0);
 
 
```

This example shows how to use the imc_bcopy() function to copy data to a MEMORY CHANNEL transmit address. In the example, 18 bytes are copied to a MEMORY CHANNEL transmit address at an offset of 12 bytes from the beginning of the region.

           int        source[256];
           caddr_t    tx_addr;
           imc_asid_t id;
           int        status;
           int        prev_err;
           long       last_quad;
 
           /* allocate and attach destination buffer */
 
           status = imc_api_init(NULL);
           if (status != IMC_SUCCESS)
               imc_perror("imc_api_init",status);
 
           /* allocate a region of size 8K using key 678 on logical rail zero */
           status = imc_asalloc(678,8192,IMC_URW,0,&id,0);
           if (status != IMC_SUCCESS)
               imc_perror("imc_asalloc",status);
 
           /* attach for transmit without LOOPBACK */
 
           status = imc_asattach(id,IMC_TRANSMIT,IMC_SHARED,0,&tx_addr);
           if (status != IMC_SUCCESS)
               imc_perror("imc_asattach",status);
 
           /* fill in source buffer */
 
           /* copy part of the source buffer and check for errors */
 
           do {
               prev_err = imc_rderrcnt_mr(0);
               last_quad = imc_bcopy(source,tx_addr+12,18,1,0);
           } while ((status = imc_ckerrcnt_mr(&prev_err,0)) != IMC_SUCCESS);

This example shows how to use the imc_bcopy() function to copy data to a MEMORY CHANNEL transmit address from several sources. The sources may be noncontiguous.

           int        *src1;
           long       *src2;
           char       *src3;
           long       len1,len2,len3;
           caddr_t    tx_addr;
           int        status;
           int        prev_err;
           long       last_quad;
 
           /* allocate and attach destination buffer */
 
           /* assign and fill source buffers and their lengths */
 
           /* append the source buffers at their destination */
 
           do {
               prev_err = imc_rderrcnt_mr(0);
               last_quad = imc_bcopy(src1,tx_addr,len1,1,0);
               last_quad = imc_bcopy(src2,tx_addr+len1,len2,1,last_quad);
               last_quad = imc_bcopy(src3,tx_addr+len1+len2,len3,1,
                                                              last_quad);
           } while ((status = imc_ckerrcnt_mr(&prev_err,0)) != IMC_SUCCESS);

Return Values

The imc_bcopy() function returns the last quadword written to the destination buffer.

imc_ckerrcnt(3)

NAME

imc_ckerrcnt - Checks for the existence of outstanding errors on MEMORY CHANNEL hosts in a MEMORY CHANNEL API cluster

Synopsis

#include <sys/imc.h>

int imc_ckerrcnt( int *errcnt );

Parameter

errcnt: Specifies the current process error count across all logical rails, and returns the updated error count.

Description

Note

DIGITAL recommends using the imc_ckerrcnt_mr() function rather than the imc_ckerrcnt() function.

The imc_ckerrcnt() function checks for the existence of outstanding errors across all logical rails on the other MEMORY CHANNEL hosts in a MEMORY CHANNEL API cluster. It returns the IMC_MC_ERROR value if any of the following conditions apply:

The function detects an outstanding error on another host in the MEMORY CHANNEL API cluster.

The function detects that error handling is in progress.

The total error count on all logical rails is greater than the value supplied in the errcnt parameter.

If an error count is being updated at the time the imc_ckerrcnt() function is called, the function returns a negative value in the errcnt parameter. Programs should check for this eventuality and call the function again to ensure that the error has been handled.

You can use the imc_ckerrcnt() function along with the imc_rderrcnt() function to construct application-specific error-detection protocols.

Return Values

The imc_ckerrcnt function returns one of the following values:

IMC_SUCCESS: Normal successful completion: no MEMORY CHANNEL errors detected.
IMC_MC_ERROR: A MEMORY CHANNEL error was detected.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_ckerrcnt function.
IMC_INITERR: A fatal error occurred while initializing the error-checking mechanism.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.
IMC_NORESOURCES: There are insufficient MEMORY CHANNEL data structures available to perform the operation.

imc_ckerrcnt_mr(3)

NAME

imc_ckerrcnt_mr - Checks for the existence of outstanding errors on a specified logical rail on MEMORY CHANNEL hosts in a MEMORY CHANNEL API cluster

Synopsis

#include <sys/imc.h>

int imc_ckerrcnt_mr( int *errcnt, int logical_rail );

Parameter

errcnt: Specifies the current process error count on the specified logical rail, and returns the updated error count.
logical_rail: Specifies the MEMORY CHANNEL logical rail that is to be checked for errors. The first logical rail is numbered zero (0), the second logical rail is numbered 1, and so on, up to a maximum defined by a constant, IMC_MAXRAILS.

Description

The imc_ckerrcnt_mr() function checks for the existence of outstanding errors on the specified MEMORY CHANNEL logical rail. It returns the IMC_MC_ERROR value if any of the following conditions apply:

The function detects an outstanding error on the specified logical rail.

The function detects that error handling is in progress.

The error count is greater than the value supplied in the errcnt parameter.

If an error count is being updated at the time the imc_ckerrcnt_mr() function is called, the function returns a negative value in the errcnt parameter. Programs should check for this eventuality and call the function again to ensure that the error has been handled.

You can use the imc_ckerrcnt_mr() function along with the imc_rderrcnt_mr() function to construct application-specific error detection protocols.

Return Values

The imc_ckerrcnt_mr function returns one of the following values:

IMC_SUCCESS: Normal successful completion: no MEMORY CHANNEL errors detected.
IMC_MC_ERROR: A MEMORY CHANNEL error was detected on the specified logical rail; or error handling is in progress; or the error count is greater than the value supplied in the errcnt parameter.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_ckerrcnt_mr function.
IMC_BADRAIL: The logical rail number specified in the call to the imc_ckerrcnt_mr function is invalid; or the logical rail is inactive.
IMC_INITERR: A fatal error occurred while initializing the error-checking mechanism.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.
IMC_NORESOURCES: There are insufficient MEMORY CHANNEL data structures available to complete the operation.

imc_getclusterinfo(3)

NAME

imc_getclusterinfo - Gets information about the hosts participating in a MEMORY CHANNEL API cluster

Synopsis

#include <sys/imc.h>

int imc_getclusterinfo( imc_infotype *i_items, int i_nitems, [,char *io_data, int i_datalen] ... );

Parameters

i_items

Points to an array that contains the enumerated type of each item to be returned. The last element of the array must be zero (0). Valid types are:

IMC_GET_HOSTS: Returns information on the number of hosts in a MEMORY CHANNEL API cluster and the name of each host, in a data structure of type imc_hostinfo.
IMC_GET_NRAILS: Returns the number of logical rails in the MEMORY CHANNEL API cluster, in a variable of type unsigned int.
IMC_GET_ACTIVERAILS: Returns the logical rail numbers of the active logical rails in the MEMORY CHANNEL API cluster, in a variable of type imc_railinfo.

i_nitems

Specifies the number of items in the array i_items.

io_data

Points to a buffer that contains the item of MEMORY CHANNEL API cluster information requested.

i_datalen

Specifies the length of the buffer identified by the io_data parameter.

Description

The imc_getclusterinfo() function returns information on items in a MEMORY CHANNEL API cluster. One or more of the following items may be requested:

A count of the number of hosts participating in the MEMORY CHANNEL API cluster, and the name of each host.

The number of logical rails in the MEMORY CHANNEL API cluster.

The active MEMORY CHANNEL logical rails bitmask, which contains the numbers of the active logical rails.

A request of zero (0) items is valid and will return nothing.

The request items are returned in data structures, as follows:

imc_hostinfo

The data structure of type imc_hostinfo contains the following fields:

name[IMC_MAXHOSTS][MAXHOSTNAMELEN]: The host names are returned in the two-dimensional name array. The string containing the host name is zero-terminated. The elements in the array are numbered zero (0) to (num-1).
num: The number of hosts in the MEMORY CHANNEL API cluster is returned in the num field.

imc_railinfo

The active MEMORY CHANNEL logical rails bitmask is returned in the imc_railinfo array (with bit zero (0) representing logical rail number zero (0), bit 1 representing logical rail number 1, and so on).

Note

The imc_getclusterinfo() function lists only those hosts that have initialized the MEMORY CHANNEL API library.

Examples

The following program extract requests the names of the members of the MEMORY CHANNEL API cluster (functionality that was previously provided by the imc_gethosts function, which is now obsolete):

          imc_hostinfo    hostinfo;
          int             status,i;
          imc_infoType    items[2];
 
          items[0] = IMC_GET_HOSTS;
          items[1] = 0;
 
          status =
              imc_getclusterinfo(items,1,&hostinfo,sizeof(imc_hostinfo));
 
          if (status != IMC_SUCCESS)
               imc_perror("imc_getclusterinfo:",status);
           else
               for (i=0; i<hostinfo.num; i++)
                   printf("Member: %s\n",hostinfo.name[i]);

The following program extract requests the active MEMORY CHANNEL logical rails bitmask and prints out the numbers of the active logical rails:

          imc_railinfo    mask;
          int             status,i;
          imc_infoType    items[2];
 
          items[0] = IMC_GET_ACTIVERAILS;
          items[1] = 0;
 
          status = imc_getclusterinfo(items,1,mask,sizeof(imc_railinfo));
 
          if (status != IMC_SUCCESS)
               imc_perror("imc_getclusterinfo:",status);
           else
               for (i=0; i<IMC_MAXRAILS;i++)
                   if (IMC_IS_RAIL_ACTIVE(mask,i))
                       printf("Rail %d is ACTIVE\n",i);

The following program extract requests the names of the members of the MEMORY CHANNEL API cluster, the number of logical rails, and the active MEMORY CHANNEL logical rails bitmask.

           imc_railinfo mask;
           imc_hostinfo hostinfo;
           unsigned     nrails;
 
           int status;
           imc_infoType items[4];
 
           items[0] = IMC_GET_ACTIVERAILS;
           items[1] = IMC_GET_HOSTS;
           items[2] = IMC_GET_NRAILS;
           items[3] = 0;
 
           status = imc_getclusterinfo(items,3,mask,sizeof(imc_railinfo),\
                       &hostinfo,sizeof(imc_hostinfo),&nrails,sizeof(unsigned));

Return Values

The imc_getclusterinfo() function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_getclusterinfo() function.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.

imc_kill(3)

NAME

imc_kill - Sends a signal to a running process

Synopsis

#include <sys/imc.h>

int imc_kill( char * hostname, pid_t pid, int signal );

Parameters

hostname: Specifies the host on which the target process is executing.
pid: Specifies the process identifier (PID) of the target process.
signal: Specifies the signal to be sent to the target process.

Description

The imc_kill() function sends a signal to a target process that is executing on the MEMORY CHANNEL API cluster member specified by the hostname parameter. A list of valid host names can be obtained by calling the imc_getclusterinfo() function. The PID for the target process is specified by the pid parameter and it must be a valid PID. Zero and negative PID values are not valid.

Processes that are executing with root privileges are not allowed to send signals across the MEMORY CHANNEL API cluster.

The imc_kill() function is similar to the UNIX kill(2) function; however, it does not support the sending of signals to multiple processes.

Return Values

The imc_kill function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADHOST: The host name specified in the hostname parameter is invalid.
IMC_BADPARM: The value specified in the pid parameter is invalid.
IMC_EINVAL: The signal specified in the signal parameter is not a valid signal number. Zero and negative PID values are not permitted.
IMC_EINVAL: The signal parameter is SIGKILL, SIGSTOP, SIGTSTP, or SIGCONT and the PID specified in the pid parameter is 1 (proc1).
IMC_EPERM: The real or saved user ID does not match the real or effective user ID of the receiving process, the calling process does not have appropriate privilege, and the process is not sending a SIGCONT signal to one of its session's processes.
IMC_ESRCH: No process can be found corresponding to that specified by the pid parameter.
IMC_NOROOT: Superuser signalling across the MEMORY CHANNEL API cluster is not permitted.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.

imc_lkacquire(3)

NAME

imc_lkacquire - Acquires a lock from an existing set of locks

Synopsis

#include <sys/imc.h>

int imc_lkacquire( imc_lkid_t lock, int index, int flag, int trylock );

Parameters

lock

Identifies the lock set from which the lock is to be acquired. The lock set specified by the lock parameter must previously have been allocated by a call to the imc_lkalloc() function.

index

Specifies the lock to be acquired. The value of the index parameter is in the range zero (0) to (count-1), where count is the value returned by the imc_lkalloc() function when it created the lock set.

flag

This parameter is reserved for future use by DIGITAL. You must set the value of this parameter to zero (0).

trylock

Specifies whether the imc_lkacquire function should return immediately if the lock is busy or wait until it can acquire the lock. The trylock parameter contains one of the following values:

IMC_LOCKWAIT: Wait until the lock becomes free and then acquire the lock before returning.
IMC_LOCKNOWAIT: Return immediately if the lock is in use.

Description

The imc_lkacquire() function tries to acquire the lock specified by the index parameter from the lock set specified in the lock parameter. If the lock is in use, the function can wait until the lock becomes free, or it can return immediately without acquiring the lock. The return values for the function indicate whether or not the lock was successfully acquired.

When a process acquires a lock, no other process executing on the MEMORY CHANNEL API cluster can acquire that lock.

Waiting for busy locks to become free entails busy spinning and has a significant effect on performance. Therefore, in the interest of overall system performance, applications should acquire locks only as they are needed and release them promptly.

If a system failure occurs on a host on which a process that holds a lock is executing, all locks associated with the host are automatically released.

All locks acquired by a process are automatically released when the process exits.

It is illegal for a process to acquire locks recursively. If a process acquires a lock that it has already acquired and not released, an error will occur. The correct sequence is for the process to acquire the lock, release it, and then acquire it again.

Return Values

The imc_lkacquire function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADLOCK: Either the lock set specified by the lock parameter or the lock specified by the index parameter is out of range.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_lkacquire()function.
IMC_CORRUPTLOCK: An attempt was made to acquire a lock from an invalid or corrupted lock set.
IMC_LOCKPRIOR: The process attempted to acquire a lock that it already holds.
IMC_NOLOCKGOT: The imc_lkacquire() function returned without gaining ownership of the lock.

imc_lkalloc(3)

NAME

imc_lkalloc - Creates a lock set

Synopsis

#include<sys/imc.h>

int imc_lkalloc( imc_key_t key, int *count, imc_perm_t perm, int flag, imc_lkid_t *lock );

Parameters

key

Identifies the lock set to be allocated.

count

Specifies the number of locks created in the lock set, and returns the number of locks actually created.

perm

Specifies the access permission for the lock set. The permission code is similar to the UNIX permission convention, except that there is no execute flag. The value of the perm parameter is obtained by carrying out a logical OR operation on the following values:

IMC_LKU: User access to locks
IMC_LKG: Group access to locks
IMC_LKO: Other access to locks

flag

Specifies the creation flag for the lock set. The flag parameter has one of the following values:

IMC_CREATOR: If the lock set does not already exist on the MEMORY CHANNEL API cluster, allocate the lock set and atomically acquire the first lock (that is, lock zero (0)) in the set. If the IMC_CREATOR flag is specified for a lock set that already exists, an error condition will result.
ZERO (0): Allocate the lock set without attempting to acquire the first lock in the set.

lock

Returns a value that uniquely identifies the allocated lock set. If the imc_lkalloc() function fails to allocate a lock set, the value of the lock parameter is set to NULL.

Description

The imc_lkalloc() function creates a set of locks that enable applications to coordinate access to clusterwide resources. The number of locks in the lock set is specified by the count parameter. The maximum number of locks that a set can contain is specified by the IMC_MAXNUMLOCKS value in the MEMORY CHANNEL API library header file.

The imc_lkalloc() function provides a feature that allows a process to atomically (that is, in a single operation) allocate a lock set and acquire the first lock in the set. This feature can be used to coordinate application initialization in a MEMORY CHANNEL API cluster. To atomically allocate the lock set and acquire the first lock, specify the value IMC_CREATOR for the flag parameter.

The method for establishing a relationship between a lock and a resource is application-specific, and is beyond the scope of the MEMORY CHANNEL API library.

All lock sets allocated by a process are automatically deallocated when the process exits.

Return Values

The imc_lkalloc function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_lkalloc()function.
IMC_BADSIZE: The lock set is already allocated on the MEMORY CHANNEL API cluster, and the size of the set as specified in this call to the imc_lkalloc()function does not match the size specified in the previous call.
IMC_EXISTS: The lock set already exists on the MEMORY CHANNEL API cluster.
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 available to allocate the lock set.
IMC_NOMEM: There is insufficient local memory available to allocate the lock set.
IMC_NORESOURCES: There are insufficient MEMORY CHANNEL data structures available to allocate the lock set.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.
IMC_PERMIT: The lock set is already allocated, with a permission code that is incompatible with the code specified in the perm parameter.
IMC_PRIOR: The lock set has already been allocated by the calling process.

imc_lkdealloc(3)

NAME

imc_lkdealloc - Deallocates a lock set

Synopsis

#include <sys/imc.h>

int imc_lkdealloc( imc_lkid_t *lock );

Parameter

lock: Identifies the lock set to be deallocated. The lock set specified by the lock parameter must previously have been allocated by a call to the imc_lkalloc() function.

Description

The imc_lkdealloc() function deallocates the lock set specified by the lock parameter. An attempt to deallocate a lock set that contains active locks will result in an error condition.

All lock sets allocated by a process are automatically deallocated when the process exits.

Return Values

The imc_lkdealloc function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADLOCK: The lock set specified by the lock parameter does not exist.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_lkdealloc()function.
IMC_CORRUPTLOCK: An attempt was made to deallocate an invalid or corrupted lock set.
IMC_LOCKACTIVE: The lock set has active locks.
IMC_NOTALLOC: The lock set is not allocated.
IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.

imc_lkrelease(3)

NAME

imc_lkrelease - Releases a lock in a lock set

Synopsis

#include <sys/imc.h>

int imc_lkrelease( imc_lkid_t lock, int index );

Parameters

lock: Identifies the lock set that contains the lock to be released. The lock set specified by the lock parameter must previously have been allocated by a call to the imc_lkalloc() function.
index: Specifies the lock to be released. The value of the index parameter is in the range zero (0) to (count-1), where count is the value returned by the imc_lkalloc() function when it created the lock set.

Description

The imc_lkrelease() function releases a lock that is being held as a result of a call to the imc_lkacquire() function or the imc_lkalloc() function.

If the lock specified by the lock and index parameters is not being held, an error condition will result.

If a system failure occurs on a host on which a process that holds a lock is executing, all locks associated with the host are automatically released.

All locks acquired by a process are automatically released when the process exits.

Return Values

The imc_lkrelease function returns one of the following values:

IMC_SUCCESS: Normal successful completion.
IMC_BADLOCK: Either the lock set specified by the lock parameter or the lock specified by the index parameter does not exist.
IMC_CORRUPTLOCK: An attempt was made to release a lock in an invalid or corrupted lock set.
IMC_LOCKNOTHELD: The lock that the imc_lkrelease() function tried to release was not being held.

imc_perror(3)

NAME

imc_perror - Prints a message that explains a MEMORY CHANNEL function error

Synopsis

#include <sys/imc.h>

void imc_perror( char *userstring, int code );

Parameters

userstring: Specifies a string to be prefixed to the error message.
code: Specifies the return status from the MEMORY CHANNEL API library function that failed.

Description

The imc_perror() function prints a message to standard error output that gives an explanation of the error status specified in the code parameter. The message is made up of the following:

The prefix specified in the userstring parameter

A colon (:)

A blank space

The error message

A newline character

Return Values

The imc_perror function does not return any values.

imc_rderrcnt(3)

NAME

imc_rderrcnt - Reads the total error count across all logical rails

Synopsis

#include <sys/imc.h>

int imc_rderrcnt( void/ );

Parameters

The imc_rderrcnt() function does not take any parameters.

Description

Note

DIGITAL recommends that you use the imc_rderrcnt_mr() function rather than the imc_rderrcnt() function.

The imc_rderrcnt() function reads the total error count across all logical rails and returns the value to the calling program. The total error count is updated whenever a MEMORY CHANNEL error occurs. The count is not guaranteed to be up to date with the most recent MEMORY CHANNEL transfer. However, you can use it with the imc_ckerrcnt() function to determine whether any errors occurred since the last time the count was updated.

The MEMORY CHANNEL hardware guarantees that no corrupt data will be written to host systems, and that all data will be delivered to the host systems in the sequence in which the data is written to the MEMORY CHANNEL hardware. The atomic unit of transfer on MEMORY CHANNEL is 32 bits. Statistically, the error rate of the MEMORY CHANNEL hardware is of the order of three errors per year.

If an error count is being updated at the time the imc_rderrcnt() function is called, the function returns a negative value. Programs should check for this eventuality and call the function again to ensure that it reads the correct error count.

You can use the imc_rderrcnt() function along with the imc_ckerrcnt() function to construct application-specific error-detection protocols.

Return Values

On successful completion, the imc_rderrcnt() function returns a positive integer that contains the total error count.

The imc_rderrcnt() function returns a negative value if the error count is being updated when the function is called.

imc_rderrcnt_mr(3)

NAME

imc_rderrcnt_mr - Reads the clusterwide error count for the specified logical rail

Synopsis

#include <sys/imc.h>

int imc_rderrcnt( int logical_rail );

Parameter

logical_rail: Specifies the MEMORY CHANNEL logical rail for which the error count is to be read. The first logical rail is numbered zero (0), the second logical rail is numbered 1, and so on, up to a maximum defined by a constant, IMC_MAXRAILS.

Description

The imc_rderrcnt_mr() function reads the total error count for the specified logical rail and returns the value to the calling program. The error count is updated whenever a MEMORY CHANNEL error occurs. The count is not guaranteed to be up to date with the most recent MEMORY CHANNEL transfer. However, you can use it with the imc_ckerrcnt_mr() function to determine whether any errors occurred since the last time the count was updated.

If the error count is being updated at the time the imc_rderrcnt_mr() function is called, the function returns a negative value. Programs should check for this eventuality and call the function again to ensure that it reads the correct error count.

You can use the imc_rderrcnt_mr() function along with the imc_ckerrcnt_mr() function to construct application-specific error-detection protocols.

Return Values

On successful completion, the imc_rderrcnt_mr function returns a positive integer that contains the error count for the specified logical rail.

The imc_rderrcnt_mr() function returns a negative value if the error count is being updated when the function is called.

imc_wait_cluster_event(3)

NAME

imc_wait_cluster_event - Blocks the caller until a MEMORY CHANNEL API cluster event occurs

Synopsis

#include <sys/imc.h>

int imc_wait_cluster_event( imc_eventType *i_eventType, unsigned long i_numEvents, unsigned long i_unused, [void *io_current_config, unsigned long i_current_config_length]... );

Parameters

i_eventType

Points to a data structure that contains information about valid MEMORY CHANNEL API cluster events for which to wait. The i_eventType parameter has the following values:

IMC_CC_EVENT_HOST: A host has joined the MEMORY CHANNEL API cluster, or a host has been removed from the MEMORY CHANNEL API cluster.
IMC_CC_EVENT_RAIL: The logical rail configuration of the MEMORY CHANNEL API cluster has changed; a logical rail has come on line, or a logical rail has gone off line.

Note

A MEMORY CHANNEL API cluster is formed when a number of hosts are physically connected by a MEMORY CHANNEL interconnect, and when each host has invoked the imc_init(1) command.

i_numEvents

Specifies the number of events in the data structure identified by the i_eventType parameter. This parameter must have a value of 1 or greater.

i_unused

This parameter is currently unused. You must set the value of this parameter to zero (0).

io_current_config

Points to a data structure that contains information about the MEMORY CHANNEL API cluster configuration item being monitored. There are two valid data structure types, as follows:

imc_hostinfo: If the i_eventType parameter has the value IMC_CC_EVENT_HOST, the io_current_config parameter points to a structure of type imc_hostinfo, which is returned by the imc_getclusterinfo() function.
imc_railinfo: If the i_eventType parameter has the value IMC_CC_EVENT_RAIL, the io_current_config parameter points to a structure of type imc_railinfo, which is returned by the imc_getclusterinfo() function.

If a value of NULL is specified for the io_current_config parameter, the imc_wait_cluster_event() function will use the current internal value of the MEMORY CHANNEL API cluster configuration item being monitored. On return, the user must access this value using the imc_getclusterinfo() function.

i_current_config_length

Specifies the length of the io_current_config parameter. If the io_current_config parameter has a value of NULL, the i_current_config_length parameter is ignored.

Description

The imc_wait_cluster_event() function blocks the calling entity until a specified MEMORY CHANNEL API cluster event occurs.

Note

The imc_wait_cluster_event() function waits for MEMORY CHANNEL API cluster events, not Production Server cluster events.

Two MEMORY CHANNEL API cluster events are valid:

A host joins or leaves the MEMORY CHANNEL API cluster.

The logical rail configuration of the MEMORY CHANNEL API cluster changes.

At least one MEMORY CHANNEL API cluster event must be specified in the call to the imc_wait_cluster_event() function; more than one MEMORY CHANNEL API cluster event may be specified.

The imc_wait_cluster_event() function initially checks the current representation of the MEMORY CHANNEL API cluster configuration event being monitored.

On return, the io_current_config parameter points to the new MEMORY CHANNEL API cluster configuration.

If the io_current_config parameter has been set to a value of NULL, the imc_wait_cluster_event() function will use the current internal value of the MEMORY CHANNEL API cluster configuration item being monitored; and the i_current_config_length parameter will be ignored. If this is the case, the user must access the value of the MEMORY CHANNEL API cluster configuration item on return, using the imc_getclusterinfo() function.

Examples

The following program extract requests the names of the members of the MEMORY CHANNEL API cluster using the imc_getclusterinfo() function, and then calls the imc_wait_cluster_event function to wait for a configuration change to be notified:

           imc_hostinfo    hostinfo;
           int             status;
           imc_infotype    items[2];
           imc_eventType   events[2];
 
           items[0] = IMC_GET_HOSTS;
           items[1] = 0;
 
           events[0] = IMC_CC_EVENT_HOSTS;
           events[1] = 0;
 
           status =
                  imc_getclusterinfo(items,1,&hostinfo,sizeof(imc_hostinfo));
 
           if (status != IMC_SUCCESS)
               imc_perror("imc_getclusterinfo:",status);
 
           status =
                  imc_wait_cluster_event(events,1,0,&hostinfo,sizeof(imc_hostinfo));
 
           if (status != IMC_HOST_CHANGE)
               imc_perror("imc_wait_cluster_event didn't complete:",status);

The following program extract requests the names of the members of the MEMORY CHANNEL API cluster and the active MEMORY CHANNEL logical rails bitmask, and then waits for an event change on either:

    imc_railinfo    mask;
    imc_hostinfo    hostinfo;
 
    int             status;
    imc_infoType    items[3];
    imc_eventType   events[3];
 
 
    items[0] = IMC_GET_ACTIVERAILS;
    items[1] = IMC_GET_HOSTS;
    items[2] = 0;
 
    events[0] = IMC_CC_EVENT_RAILS;
    events[1] = IMC_CC_EVENT_HOSTS;
    events[2] = 0;
 
    status = imc_getclusterinfo(items,2,mask,sizeof(imc_railinfo),
                                    &hostinfo,sizeof(imc_hostinfo));
 
    if (status != IMC_SUCCESS)
        imc_perror("imc_getclusterinfo:",status);
 
    status = imc_wait_cluster_event(events, 2, 0, \\
                                    mask, sizeof(imc_railinfo), 
                                    &hostinfo, sizeof(imc_hostinfo));
 
    if ((status != IMC_HOST_CHANGE) && (status != IMC_RAIL_CHANGE))
        imc_perror("imc_wait_cluster_event didn't complete:",status);

The following program extract waits for an event change on either the members of the MEMORY CHANNEL API cluster or the active MEMORY CHANNEL logical rails:

    int status;
    imc_eventType events[3];
 
    events[0] = IMC_CC_EVENT_HOSTS;
    events[1] = IMC_CC_EVENT_RAILS;
    events[2] = 0;
 
    status = imc_wait_cluster_event(events, 2, 0, NULL, 0, NULL, 0);
 
    if ((status != IMC_HOST_CHANGE) && (status != IMC_RAIL_CHANGE))
        imc_perror("imc_wait_cluster_event didn't complete:",status);

Return Values

The imc_wait_cluster_event function returns one of the following values:

IMC_NOTINIT: This host has not been initialized to use the MEMORY CHANNEL API library.
IMC_BADPARM: An invalid parameter was specified in the call to the imc_wait_cluster_event() function.
IMC_INTR: The imc_wait_cluster_event() function was interrupted by a signal.
IMC_HOST_CHANGE: The host configuration has changed.
IMC_RAIL_CHANGE: The logical rail configuration has changed.
IMC_MULTIPLE_CHANGE: More than one of the monitored configuration items has changed.

3 MEMORY CHANNEL API Library Interface

3.1 Header Files

3.2 Library

3.3 Compiling Applications that Use the MEMORY CHANNEL API Library

3.4 Overview of MEMORY CHANNEL API Library Commands and Functions

imc(3)

NAME

Description

Commands

Functions

MEMORY CHANNEL API Cluster Information

Accessing MEMORY CHANNEL Address Space

Clusterwide Lock System

MEMORY CHANNEL API Cluster Signals

MEMORY CHANNEL API Management

Note

3.5 Command Descriptions

imc_init(1)

NAME

Synopsis

Options

Description

Error Messages

FILES

See Also

imcs(1)

NAME

Synopsis

Options

Description

Examples

See Also

3.6 Function Descriptions

imc_api_init(3)

NAME

Synopsis

Parameters

Description

Return Values

See Also

imc_asalloc(3)

NAME

Synopsis

Parameters

Description

Return Values

See Also

imc_asattach(3)

NAME

Synopsis

Parameters

Description

Return Values

See Also

imc_asattach_ptp(3)

NAME

Synopsis

Parameters

Description

Return Values

See Also

imc_asdealloc(3)

NAME

Synopsis

Parameter

Description

Return Values

See Also

imc_asdetach(3)

NAME

Synopsis

Parameter

Description

Return Values

See Also

imc_bcopy(3)

NAME

Synopsis

Parameters

Description