NASD Programmer's Documentation
Drive operations

NASD Drive Operations

RPCs to the drive

nasd_cl_p_null_dr
nasd_cl_p_initialize_dr
nasd_cl_p_part_creat_dr
nasd_cl_p_create_dr
nasd_cl_p_remove_dr
nasd_cl_p_getattr_dr
nasd_cl_p_setattr_dr
nasd_cl_p_write_simple_dr
nasd_cl_p_read_simple_dr
nasd_cl_p_tread_simple_dr
nasd_cl_p_sync_dr
nasd_cl_p_flush_obj_dr
nasd_cl_p_eject_obj_dr
nasd_cl_p_read2_simple_dr
nasd_cl_p_range_read
nasd_cl_p_range_tread
nasd_cl_p_range_write


nasd_cl_p_null_dr

void nasd_cl_p_null_dr(
nasd_drive_handle_t handle,
nasd_status_t*nasd_status,
nasd_rpc_status_t*rpc_status)

This can be used as a standard "ping" no-op. It can also be used to measure round-trip times to and from the drive, for the purpose of measuring communication channel overhead. The drive receives and immediately responds to this message, performing only those actions which are necessary and currently enabled on all drive RPCs (network overhead, tracing/logging, etc).

Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs


nasd_cl_p_initialize_dr

void nasd_cl_p_initialize_dr(
nasd_drive_handle_t handle,
nasd_p_initialize_dr_args_t*args,
nasd_p_initialize_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

Initialize the drive security subsystem. This should be called once at start-of-day on new drives before formatting them. The argument structure contains two nasd_key_ts, which are in_master_key and in_drive_key. These become the master and drive keys, respectively. When the drive is compiled without security (NASD_SECURE_RPCS_ENABLE is 0), this operation is a no-op. The result structure contains only nasd_status, a nasd_status_t.

Return CodeMeaning
NASD_SUCCESSdrive initialized successfully
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_INITIALIZEDdrive is already initialized


nasd_cl_p_part_creat_dr

void nasd_cl_p_part_creat_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_part_creat_dr_args_t*args,
nasd_p_part_creat_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

Create a new partition on the drive. in_partnum in the argument structure names the partition to create. in_min_protection is the miniumum protection level allowed for operations in this partition. in_partition_key, in_black_key, and in_red_key are the initial partition key, black key, and red key for this partition, respectively. in_blkcnt is the number of blocks to reserve for this partition. The sole result is a nasd_status_t. This operation must provide the drive key as its key.

Return CodeMeaning
NASD_SUCCESSthe operation completed successfully
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key supplied was not the drive key
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition already exists, or the partition name is out-of-range
NASD_NO_SPACEin_blkcnt exceeds the number of blocks on the disk not reserved for other partitions


nasd_cl_p_create_dr

void nasd_cl_p_create_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_create_dr_args_t*args,
nasd_p_create_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

Create a new object. in_partnum in the arguments structure specifies where this object should be created. in_attribute and in_fieldmask together specify attributes for this new object For a description of these attribute-setting parameters, see nasd_cl_p_setattr_dr(). In addition to the nasd_status_t for the operation, the result structure contains out_identifier, the NASD identifier for the newly-created object, and out_attribute, the attributes of the newly-created object.

Return CodeMeaning
NASD_SUCCESSthe operation completed successfully
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_NO_SPACEthere were not enough blocks remaining in the partition to create a new object
NASD_OP_NOT_SUPPORTEDin_fieldmask specified a field which this drive implementation does not allow to be set
NASD_BAD_ATTR_SETin_fieldmask specified a field which may not be set at creation


nasd_cl_p_remove_dr

void nasd_cl_p_remove_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_remove_dr_args_t*args,
nasd_p_remove_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

Remove a NASD object from the drive. in_identifier and in_partnum in the request specify the object to be removed and its partition. The result structure contains the nasd_status_t for the operation.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLthis operation may not be performed on a control object


nasd_cl_p_getattr_dr

void nasd_cl_p_getattr_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_getattr_dr_args_t*args,
nasd_p_getattr_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation retrieves the attributes of object in_identifier in partition in_partnum as specified in the argument structure, storing those attributes in out_attribute in the result structure.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid


nasd_cl_p_setattr_dr

This op void nasd_cl_p_setattr_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_setattr_dr_args_t*args,
nasd_p_setattr_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation changes attributes for object in_identifier in partition in_partnum as specified in the argument structure. This argument structure contains in_attribute which is of type nasd_attribute_t. The in_fieldmask flags word in the argument structure indicates which portions of this attribute structure should be read and acted upon. Valid bits for in_fieldmask are:
Fieldmask bitMeaning
NASD_ATTR_BLOCK_PREALLOCATIONchange number of blocks preallocated for future object storage
NASD_ATTR_BLOCKS_USEDset number of blocks used to store object
NASD_ATTR_BLOCK_SIZEset object block size
NASD_ATTR_OBJECT_LENset object logical length (may truncate, or extend with zero-fill)
NASD_ATTR_ATTR_MODIFY_TIMEset fs_attr_modify_time
NASD_ATTR_MODIFY_TIMEset fs_object_modify_time
NASD_ATTR_AVset object authentication key version
NASD_ATTR_LAYOUT_HINTset the layout hint for the object
NASD_ATTR_FS_SPECIFICset object fs-specific data
Individual drive implementations may not support all of the above operations on all objects in all partitions. If in_guard in the attributes is nonzero, the attr_modify_time field of in_attribute must match that currently held by the object, or the operation will fail with NASD_GUARD_CHECK_FAILED.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLan attribute change that is not valid for a control object was attempted
NASD_GUARD_CHECK_FAILEDin_guard was nonzero, but the attr_modify_time field of in_attribute did not match that currently held by the object
NASD_BAD_ATTR_SETunrecognized bits were set in in_fieldmask
NASD_OP_NOT_SUPPORTEDsome aspect of the requested change is not supported by this drive implementation


nasd_cl_p_write_simple_dr

void nasd_cl_p_write_simple_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_smpl_op_dr_args_t*args,
void*buf,
nasd_p_fastwrite_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation writes bytes into the NASD object in_identifier in partition in_partnum as specified in the argument structure. It writes in_len bytes at offset in_offset. The bytes written are the first in_len bytes stored at address buf.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLa write was attempted to a control object which does not support writes


nasd_cl_p_read_simple_dr

void nasd_cl_p_read_simple_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_smpl_op_dr_args_t*args,
void*buf,
nasd_p_fastread_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation reads bytes from the NASD object in_identifier in partition in_partnum as specified in the argument structure. It reads in_len bytes at offset in_offset. The bytes read are stored in the first in_len bytes at address buf.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLa read was attempted to a control object which does not support reads


nasd_cl_p_tread_simple_dr

void nasd_cl_p_tread_simple_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_thrtl_op_dr_args_t*args,
void*buf,
nasd_p_fastread_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation performs a throttled read of bytes from the NASD object in_identifier in partition in_partnum as specified in the argument structure. It reads in_len bytes at offset in_offset. The bytes read are stored in the first in_len bytes at address buf. The drive and client will attempt to be sure that the average bandwidth of the data transfer does not exceed in_bms_targ bytes per millisecond (as specified in the argument structure).
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLa read was attempted to a control object which does not support reads


nasd_cl_p_sync_dr

void nasd_cl_p_sync_dr(
nasd_drive_handle_t handle,
nasd_status_t*nasd_status,
nasd_rpc_status_t*rpc_status)

This operation instructs the drive to ensure that any currently-cached writes complete. Internal buffers which have not yet been committed to stable store are so committed. This operation does not complete until the writes to stable store have completed.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs


nasd_cl_p_flush_obj_dr

void nasd_cl_p_flush_obj_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_flush_obj_dr_args_t*args,
nasd_p_flush_obj_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation ensures that any cached writes for an object (in_identifier in partition in_partnum) are completed to stable store before it returns.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLthis operation is not supported on control objects


nasd_cl_p_eject_obj_dr

void nasd_cl_p_eject_obj_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_eject_obj_dr_args_t*args,
nasd_p_eject_obj_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation is intended for debugging and benchmarking only. It instructs the drive to discard any pages cached for in_identifier in partition in_partnum.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLthis operation is not supported on control objects


nasd_cl_p_read2_simple_dr

void nasd_cl_p_read2_simple_dr(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_p_smpl_op_dr_args_t*args,
void*buf,
nasd_p_fastread_dr_res_t*res,
nasd_rpc_status_t*rpc_status)

This operation is completely identical to nasd_cl_p_read_simple_dr(). The two operations, read and read2, exist only to separate different kinds of reads statistically and in traces. For instance, when running a workload against a drive, and periodically extracting statistics and traces from the drive, one may wish to use read2 in place of read so that a trace analysis tool can discard load generated by the instrumentation itself.


nasd_cl_p_range_read

void nasd_cl_p_range_read(

nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_capability_args_t capargs,
int partnum,
nasd_identifier_t nasdid,
nasd_mem_list_t*memlist,
nasd_offset_t in_offset,
nasd_len_t in_len,
nasd_len_t*out_lenp,
nasd_status_t*nasd_status,
nasd_rpc_status_t*rpc_status)

This is parameterized similarly to nasd_cl_p_read_simple_dr(). However, in place of a single buffer in memory in which to store the data, a memory list (memlist) is provided. This is a linked list of strided elements. Each element in the list (linked on the next pointer) has a number of elements nelem offset from one another by stride bytes from the beginning of one buffer to the beginning of the next. The address of the first stride is addr, and each stride contains len bytes.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLa read was attempted to a control object which does not support reads
NASD_BAD_MEM_LISTmemlist is malformed
NASD_MEM_LIST_ERRan error was encountered parsing memlist


nasd_cl_p_range_tread

void nasd_cl_p_range_read(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_capability_args_t capargs,
int partnum,
nasd_identifier_t nasdid,
nasd_uint64 in_bms_targ,
nasd_mem_list_t*memlist,
nasd_offset_t in_offset,
nasd_len_t in_len,
nasd_len_t*out_lenp,
nasd_status_t*nasd_status,
nasd_rpc_status_t*rpc_status)

This is parameterized similarly to nasd_cl_p_range_read(). An additional parameter, in_bms_targ, specifies a maximum number of bytes per millisecond. The drive and client will attempt to achieve an average transfer rate at or below this target.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLa read was attempted to a control object which does not support reads
NASD_BAD_MEM_LISTmemlist is malformed
NASD_MEM_LIST_ERRan error was encountered parsing memlist


nasd_cl_p_range_write

void nasd_cl_p_range_write(
nasd_drive_handle_t handle,
nasd_key_t req_key,
nasd_capability_args_t capargs,
int partnum,
nasd_identifier_t nasdid,
nasd_mem_list_t*memlist,
nasd_offset_t in_offset,
nasd_len_t in_len,
nasd_len_t*out_lenp,
nasd_status_t*nasd_status,
nasd_rpc_status_t*rpc_status)

This is parameterized similarly to nasd_cl_p_write_simple_dr(). However, in place of a single buffer in memory from which the data originates, a memory list (memlist) is provided. This is a linked list of strided elements. Each element in the list (linked on the next pointer) has a number of elements nelem offset from one another by stride bytes from the beginning of one buffer to the beginning of the next. The address of the first stride is addr, and each stride contains len bytes.
Return CodeMeaning
NASD_SUCCESSmessage received
NASD_OFFLINEdrive is not currently accepting RPCs
NASD_DRIVE_UNINITIALIZEDdrive is not initialized (see nasd_cl_p_initialize_dr())
NASD_BAD_KEYTYPEthe key type specified is not valid for this operation
NASD_PART_PROTECTIONrequest did not meet minimum protection for the partition
NASD_WEAK_COOKIEcookie does not have required minimum protection for drive
NASD_CAP_PROTECTIONrequest does not meet minimum protection required by capability
NASD_BAD_DIGEST_REQrequest has a bad digest
NASD_BAD_PARTITIONthe named partition does not exist
NASD_BAD_IDENTIFIERthe nasd identifier specified in the request is not valid
NASD_OP_NOT_ON_CONTROLa write was attempted to a control object which does not support writes
NASD_BAD_MEM_LISTmemlist is malformed
NASD_MEM_LIST_ERRan error was encountered parsing memlist

<--- ---> ^<br>|<br>|
Drive operation calling convention Drive structure NASD Programmer's Documentation