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. After labelling the segment, the RSMAPI library interfaces bind physical pages to the allocated virtual range. After binding the physical pages, the RSMAPI library interfaces publish the segment for access by importing processes.
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
Establishing a new memory segment with rsm_memseg_export_create enables the association of physical memory with the segment at creation time. The operation returns an export-side memory segment handle to the new memory segment. The segment exists for the lifetime of the creating process or until destroyed with rsm_memseg_export_destroy.
If destroy operation is performed before an import side disconnect, the disconnect is forced.
This function creates a segment handle. After the segment handle is created, the segment handle is bound to the specified virtual address range [vaddr..vaddr+size]. The range must be valid and aligned on the controller's alignment property. The flags argument is a bitmask, which enables:
Unbinding on the segment
Rebinding on the segment
Passing RSM_ALLOW_REBIND to flags
Support of lock operations
Passing RSM_LOCK_OPS to flags
The RSM_LOCK_OPS flag is not included in the initial release of RSMAPI.
Return Values: Returns 0 if successful. Returns an error value otherwise.
Invalid controller handle
Controller not present
Invalid segment handle
Length zero or length exceeds controller limits
Invalid address
Permission denied
Insufficient memory
Insufficient resources
Address not aligned on page boundary
Operation interrupted by signal
This function deallocates segment and its free resources. All importing processes are forcibly disconnected.
Return Values: Returns 0 if successful. Returns an error value otherwise.
Invalid segment handle
pollfd in use
The publish operation enables the importing of a memory segment by other nodes on the interconnect. An export segment might be published on multiple interconnect adapters.
The segment ID might be specified from within authorized ranges or specified as zero, in which case a valid segment ID is generated by the RSMAPI framework and is passed back.
The segment access control list is composed of pairs of node ID and access permissions. For each node ID specified in the list, the associated read/write permissions are provided by three octal digits for owner, group and other, as with Solaris file permissions. In the access control list, each octal digit can have the following values:
write access
read only access
read and write access
An access permission value of 0624 specifies the following kind of access:
An importer with the same uid as the exporter has both read and write access.
An importer with the same gid as the exporter has write access only.
All other importers have read access only.
When an access control list is provided, nodes not included in the list cannot import the segment. However, if the access list is null, any node can import the segment. The access permissions on all nodes equal the owner-group-other file creation permissions of the exporting process.
Node applications have the responsibility of managing the assignment of segment identifiers to ensure uniqueness on the exporting node.
typedef struct { rsm_node_id_t ae_node; /* remote node id allowed to access resource */ rsm_permission_t ae_permissions; /* mode of access allowed */ }rsmapi_access_entry_t;.
Return Values: Returns 0 if successful. Returns an error value otherwise.
Invalid segment handle
Segment already published
Invalid access control list
Invalid segment identifier
Segment identifier in use
Segment identifier reserved
Not creator of segment
Bad address
Insufficient memory
Insufficient resources
Authorized Segment ID Ranges:
0
0x0FFFFF
0x100000
0x1FFFFF
0x200000
0x2FFFFF
0x300000
0x3FFFFF
0x400000
0x4FFFFF
The following range is reserved for allocation by the system when the publish value is zero.
0x80000000
0xFFFFFFF
This function establishes a new node access list and segment access mode. These changes only affect future import calls and do not revoke already granted import requests.
Return Values: Returns 0 if successful. Returns an error value otherwise.
Invalid segment handle
Segment not published
Invalid access control list
Not creator of segment
Insufficient memory
Insufficient resources
Operation interrupted by signal
Return Values: Returns 0 if successful. Returns an error value otherwise.
Invalid segment handle
Segment not published
Not creator of segment
Operation interrupted by signal
The rebind operation releases the current backing store for an export segment. After releasing the current backing store for an export segment, the rebind operation allocates a new backing store. The application must first obtain a new virtual memory allocation for the segment. This operation is transparent to importers of the segment.
The application has the responsibility of preventing access to segment data until the rebind operation is complete. Retrieving data from a segment during rebinding does not cause a system failure, but the results of such an operation are undefined.
Return Values: Returns 0 if successful. Returns an error value otherwise.
Invalid segment handle
Invalid length
Invalid address
Rebind not allowed
Not creator of segment
Permission denied
Insufficient memory
Insufficient resources
Operation interrupted by signal