rsm_release_controller

int rsm_release_controller(rsmapi_controller_handle_t chdl);

This function releases the controller associated with the given controller handle. Each call to rsm_release_controller must have a matching rsm_get_controller; when all the controller handles associated with a controller are released, the system resources associated with the controller are freed. Attempting to access a controller handle, or attempting to access import or export segments on a released controller handle, is not legal; the results of such an attempt are undefined.

Return Values: Returns 0 if successful; returns an error value otherwise.

rsm_get_controller_attr

int rsm_get_controller_attr(rsmapi_controller_handle_t chdl, rsmapi_controller_attr_t *attr);

This function retrieves attributes for the specified controller handle. The current defined attributes are as follows:

typedef struct {
     uint_t       attr_direct_access_sizes;
     uint_t       attr_atomic_sizes;
     size_t       attr_page_size;
     size_t       attr_max_export_segment_size;
     size_t       attr_tot_export_segment_size;
     ulong_t      attr_max_export_segments;
     size_t       attr_max_import_map_size;
     size_t       attr_tot_import_map_size;
     ulong_t      attr_max_import_segments;
 } rsmapi_controller_attr_t;

Return Values: Returns 0 if successful; returns an error value otherwise.

Cluster Topology Operations

The key interconnect data required for export and import operations are:

• Export cluster node ID

• Import cluster node ID

• Controller name

An application component exporting memory can use the data the interface provides to find the set of existing local controllers and correctly assign controllers for the creation and publishing of segments. Application components can efficiently distribute exported segments over the set of controllers consistent with the hardware interconnect and application software distribution.

An application component that is importing memory must be informed of the segment IDs and controllers used in the memory export. This information is typically conveyed by a predefined segment/controller pair. The importing component can use the topology data to determine the appropriate controllers for the segment import operations.

rsm_get_interconnect_topology

int rsm_get_interconnect_topology(rsm_topology_t **topology_data);

This function returns a pointer to the topology data in a location specified by an application pointer. The topology data structure is defined below.

Return Values: Returns 0 if successful; returns an error value otherwise.

rsm_free_interconnect_topology

void rsm_free_interconnect_topology(rsm_topology_t *topology_data);

The rsm_free_interconnect_topology operation frees the memory allocated by rsm_get_interconnect_topology.

Return Values: None.

Data Structures

The pointer returned from rsm_get_topology_data references a rsm_topology_t structure. This provides the local node ID and an array of pointers to a connections_t structure for each local controller.

typedef struct rsm_topology {
   rsm_nodeid_t    local_nodeid;
   uint_t          local_cntrl_count;
   connections_t   *connections[1];
} rsm_topology_t;

Administrative Operations

RSM segment IDs can be specified by the application or generated by the system using the rsm_memseg_export_publish() function. Applications that specify segment IDs require a reserved range of segment IDs to use. To reserve a range of segment IDs, use rsm_get_segmentid_range and define the reserved range of segment IDs in the segment ID configuration file /etc/rsm/rsm.segmentid. The rsm_get_segmentid_range function can be used by applications to obtain the segment ID range reserved for them. This function reads the segment ID range defined in the /etc/rsm/rsm.segmentid file for a given application ID.

An application ID is a null-terminated string identifying the application. The application can use any value equal to or greater than baseid and less than baseid+length. If baseid or length are modified, the segment ID returned to the application may be outside the reserved range. To avoid this problem, use an offset within the range of reserved segment IDs to obtain a segment ID.

Entries in the /etc/rsm/rsm.segmentid file are of the form:

#keyword      appid      baseid       length
reserve       SUNWfoo    0x600000     100

The entries are composed of strings, which can be separated by tabs or blanks. The first string is the keyword reserve, followed by the application identifier (a string without spaces in it), the baseid (the starting segment ID of the reserved range in hexadecimal), and the length (the number of segment IDs reserved.) Comment lines have a # in the first column. The file should not contain blank or empty lines. Segment IDs reserved for the system are defined in the /usr/include/rsm/rsm_common.h header file and cannot be used by the applications.

The rsm_get_segmentid_range function returns 0 to indicate success. If the function fails, it returns one of the following error values:

Memory Segment Operations

An RSM segment represents a set of (generally) non-contiguous physical memory pages mapped to a contiguous virtual address range. RSM segment export and import operations enable the sharing of regions of physical memory among systems on an interconnect. A process of the node on which the physical pages reside is referred to as the exporter of the memory. An exported segment that is published for remote access will have a segment identifier that is unique for the given node. The segment ID may be specified by the exporter or assigned by the RSMAPI framework.

Processes of nodes on the interconnect obtain access to exported memory by creating an RSM import segment that has a connection with an exported segment rather than local physical pages. When the interconnect supports memory mapping, importers can read and write the exported memory using the local memory-mapped addresses of the import segment. When the interconnect does not support memory mapping, the importing process uses memory access primitives.

Export-Side Memory Segment Operations

When exporting a memory segment, the application begins by allocating memory in its virtual address space through the normal operating system interfaces such as the System V Shared Memory Interface, mmap, or valloc. After allocating memory, the application calls the RSMAPI library interfaces to create and label a segment, bind physical pages to the allocated virtual range, and publish the segment for access by importing processes.

Note - If virtual address space is obtained by using mmap, the mapping must be MAP_PRIVATE.

Export side memory segment operations include:

• Memory segment creation and destruction

• Memory segment publishing and unpublishing

• Rebinding backing store for a memory segment