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 

   in	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; 

---