Scatter-Gather Access

The rsm_memseg_import_putv() and rsm_memseg_import_getv() functions allow the use of a list of I/O requests instead of a single source and single destination address.

Function Prototypes:

int rsm_memseg_import_putv(rsm_scat_gath_t *sg_io);
int rsm_memseg_import_getv(rsm_scat_gath_t *sg_io);

The I/O vector component of the scatter-gather list (sg_io) enables the specification of local virtual addresses or local_memory_handles. Handles are an efficient way to repeatedly use a local address range. Allocated system resources, such as locked down local memory, are maintained until the handle is freed. The supporting functions for handles are rsm_create_localmemory_handle() and rsm_free_localmemory_handle().

You can gather virtual addresses or handles into the vector in order to write to a single remote segment. You can also scatter the results of reading from a single remote segment to the vector of virtual addresses or handles.

I/O for the entire vector is initiated before returning. The barrier mode attribute of the import segment determines whether the I/O has completed before the function returns. Setting the barrier mode attribute to implicit guarantees that data transfer is completed in the order entered in the vector. An implicit barrier open and close surrounds each list entry. If an error is detected, I/O for the vector is terminated and the function returns immediately. The residual count indicates the number of entries for which the I/O either did not complete or was not initiated.

You can specify that a notification event be sent to the target segment when a putv or getv operation is successful. To specify the delivery of a notification event, specify the RSM_IMPLICIT_SIGPOST value in the flags entry of the rsm_scat_gath_t structure. The flags entry can also contain the value RSM_SIGPOST_NO_ACCUMULATE, which is passed on to the signal post operation if RSM_IMPLICIT_SIGPOST is set.

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

RSMERR_BAD_SGIO

Invalid scatter-gather structure pointer

RSMERR_BAD_SEG_HNDL

Invalid segment handle

RSMERR_BAD_CTLR_HNDL

Invalid controller handle

RSMERR_BAD_ADDR

Bad address

RSMERR_BAD_OFFSET

Invalid offset

RSMERR_BAD_LENGTH

Invalid length

RSMERR_PERM_DENIED

Permission denied

RSMERR_BARRIER_FAILURE

I/O completion error

RSMERR_CONN_ABORTED

Connection aborted

RSMERR_INSUFFICIENT_RESOURCES

Insufficient resources

RSMERR_INTERRUPTED

Operation interrupted by signal

Get Local Handle

int rsm_create_localmemory_handle(rsmapi_controller_handle_t cntrl_handle, rsm_localmemory_handle_t *local_handle, caddr_t local_vaddr, size_t length);

This function obtains a local handle for use in the I/O vector for subsequent calls to putv or getv. Freeing the handle as soon as possible conserves system resources, notably the memory spanned by the local handle, which might be locked down.

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

RSMERR_BAD_CTLR_HNDL

Invalid controller handle

RSMERR_BAD_LOCALMEM_HNDL

Invalid local memory handle

RSMERR_BAD_LENGTH

Invalid length

RSMERR_BAD_ADDR

Invalid address

RSMERR_INSUFFICIENT_MEM

Insufficient memory

Free Local Handle

rsm_free_localmemory_handle(rsmapi_controller_handle_t cntrl_handle, rsm_localmemory_handle_t handle);

This function releases the system resources associated with the local handle. While all handles that belong to a process are freed when the process exits, calling this function conserves system resources.

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

RSMERR_BAD_CTLR_HNDL

Invalid controller handle

RSMERR_BAD_LOCALMEM_HNDL

Invalid local memory handle

The following example demonstrates the definition of primary data structures.

---

Example 2–1 Primary Data Structures

typedef void *rsm_localmemory_handle_t
typedef struct {
    ulong_t    io_request_count;     /* number of rsm_iovec_t entries */
    ulong_t    io_residual_count;    /* rsm_iovec_t entries not completed */

    int        flags;
    rsm_memseg_import_handle_t    remote_handle;    /* opaque handle for import segment */
    rsm_iovec_t    *iovec;           /* pointer to array of io_vec_t */
} rsm_scat_gath_t;

typedef struct {
    int    io_type;                  /* HANDLE or VA_IMMEDIATE */
    union {
        rsm_localmemory_handle_t    handle;          /* used with HANDLE */
        caddr_t                     virtual_addr;    /* used with VA_IMMEDIATE */
    } local;
    size_t     local_offset;             /* offset from handle base vaddr */
    size_t     import_segment_offset;    /* offset from segment base vaddr */
    size_t     transfer_length;
} rsm_iovec_t;

---