CAPI Flash Block Layer API
1.1 cblk_init
Purpose
Initializes CAPI block library
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_int(void *arg, int flags)
Parameters
| Parameter | Description |
| arg | Currently unused (set to NULL) |
| flags | Specifies flags for initialization. Currently set to 0. |
Description
The cblk_init API initializes the CAPI block library prior to use. cblk_init must be called before any other API in the library is called.
Return Values
Returns 0 on success; otherwise it is an error.
1.2 cblk_term
Purpose
Cleans up CAPI block library resources after the library is no longer used.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_term(void *arg, int flags)
Parameters
| Parameter | Description |
| arg | Currently unused (set to NULL) |
| flags | Specifies flags for initialization. Currently set to 0. |
Description
The cblk_term API terminates the CAPI block library after use.
Return Values
Returns 0 on success; otherwise it is an error.
1.3 cblk_open
Purpose
Open a collection of contiguous blocks (currently called a “chunk”) on a CAPI flash storage device. for which I/O (read and writes) can be done. A chunk can be thought of as a lun, which the provides access to sectors 0 thru n-1 (where n is the size of the chunk in sectors). If virtual luns are specified then that chunk is a subset of sectors on a physical lun.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
chunk_id_t chunk_id = cblk_open(const char *path, int max_num_requests, int mode, uint64_t ext_arg, int flags)
Parameters
Parameters
| Parameter | Description |
| path | This the CAPI disk special filename (i.e. /dev/sg0 for Linux, /dev/hdisk1 for AIX) |
| max_num_requests | This indicates the maximum number of commands that can be queued to the adapter for this chunk at a given time. If this value is 0, then block layer will choose a default size. If the value specified it too large then the cblk_open request will fail with an ENOMEM errno. |
| mode | Specifies the access mode for the child process (O_RDONLY, O_WRONLY, O_RDWR). |
| ext_arg | Reserved for future use |
| flags | This is a collection of bit flags. The CBLK_OPN_VIRT_LUNindicates a virtual lun on the one physical lun will be provisioned. If the CBLK_OPN_VIRT_LUN is not specified, then direct access to the full physical lun will be provided. The CBLK_OPN_VIRT_LUNflag must be set for Redis shards. The CBLK_OPN_NO_INTRP_THREADSflag indicates that the cflash block library will not start any back ground threads for processing/harvesting of asynchronous completions from the CAPI adapter. Instead the process using this library must either call cblk_aresult, or cblk_listio library calls to poll for I/O completions. The CBLK_OPN_MPIO_FOflag (valid for only AIX) indicates that the cflash block library will use Multi-path I/O failover (i.e. one path will be used for all I/O unless path specific errors are encountered, in which case an alternate path will be used if available. To determine the paths for a CAPI flash disk, use the command lspath -l hdiskN). The CBLK_OPN_RESERVE flag (valid for only AIX) indicates the cflash block library will use the “reserve policy” attribute associated with the disk in terms of establishing disk reservations. The CBLK_OPN_RESERVE flag can not be used in conjunction with the CBLK_OPN_MPIO_FO. The CBLK_OPN_FORCED_RESERVE flag (valid for only AIX) has the same behavior as the CBLK_OPEN_RESERVE flag with the one addition, that when the device is opened it will break any outstanding disk reservations on the first open of this disk. The CBLK_OPN_FORCED_RESERVEflag can not be used in conjunction with the CBLK_OPN_MPIO_FO. |
Description
The cblk_open API creates a “chunk” of blocks on a CAPI flash lun. This chunk will be used for I/O (cblk_read/cblk_write) requests. The returned chunk_id is assigned to a specific path via a specific adapter transparently to the caller. The underlying physical sectors used by a chunk will not be directly visible to users of the block layer.
Upon successful completion, a chunk id representing the newly created chunk instance is returned to the caller to be used for future API calls.
Return Values
Returns NULL_CHUNK_ID on error; otherwise it is a chunk_id handle.
1.4 cblk_close
Purpose
Closes a collection of contiguous blocks (called a “chunk”) on a CAPI flash storage device. for which I/O (read and writes) can be done.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_close(chunk_id_t chunk_id, int flags))
Description
This service releases the blocks associated with a chunk to be reused by others. Prior to them being reused by others the data blocks will need to be “scrubbed” to remove user data if the CBLK_SCRUB_DATA_FLG is set.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which is being closed (released for reuse) |
| flags | This is a collection of bit flags. The CBLK_SCRUB_DATA_FLGindicates data blocks should be scrubbed before they can be reused by others,which is only valid for virtual luns (chunks opened with CBLK_OPN_VIRT_LUNflag). |
Return Values
Returns 0 on success; otherwise it is an error.
1.5 cblk_get_lun_size
Purpose
Returns the “size” (number of blocks) of the physical lun to which this chunk is associated. This call is not valid for a virtual lun.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_get_lun_size(chunk_id_t chunk_id, size_t *size, int flags))
Description
This service returns the number of blocks of the physical lun associated with this chunk. The cblk_get_lun_size service requires one has done a cblk_open to receive a valid chunk_id.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk whose size is about to be changed. |
| size | Total number of 4K block for this physical lun. |
| flags | This is a collection of bit flags. |
Return Values
Returns 0 on success; otherwise it is error.
1.6 cblk_get_size
Purpose
Returns the “size” (number of blocks) assigned to a specific (virtual lun) chunk id, which is a virtual lun (i.e. the cblk_open call that returned this id, had the CBLK_OPN_VIRT_LUN flag). This service is not valid for physical luns.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_get_size(chunk_id_t chunk_id, size_t *size, int flags))
Description
This service returns the number of blocks allocated to this chunk. The cblk_get_size service requires one has done a cblk_open to receive a valid chunk_id.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk whose size is about to be changed. |
| size | Number of 4K block to be used for this chunk. |
| flags | This is a collection of bit flags. |
Return Values
Returns 0 on success; otherwise it is error.
1.7 cblk_set_size
Purpose
Assign “size” blocks to a specific chunk id which is a virtual lun (i.e. the cblk_open call that returned this id, had the CBLK_OPN_VIRT_LUN flag). If blocks are already assigned to this chunk id, then one can increase/decrease the size by specifying a larger/smaller size, respectively. This service is not valid for physical luns.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_set_size(chunk_id_t chunk_id, size_t size, int flags))
Description
This service allocates “size” blocks to this chunk. The cblk_set_size call must be done prior to any cblk_read or cblk_write calls to this chunk. The cblk_set_size service requires one has done a cblk_open to receive a valid chunk_id.
If there were blocks originally assigned to this chunk and they are not being reused after cblk_set_size allocates the new blocks and the CBLK_SCRUB_DATA_FLG is set in the flags parameter, then those originally blocks will be “scrubbed” prior to allowing them to be reused by other cblk_set_size operations.
Upon successful completion, the chunk will has LBAs 0 thru size – 1 that can be read/written.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk whose size is about to be changed. |
| size | Number of 4K block to be used for this chunk. |
| flags | This is a collection of bit flags. The CBLK_SCRUB_DATA_FLG indicates data blocks should be scrubbed before they can be reused by others. |
Return Values
Returns 0 on success; otherwise it is error.
1.8 cblk_get_stats
Purpose
Returns statistics for a specific chunk id.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
typedef struct chunk_stats_s {
uint64_t max_transfer_size; /* Maximum transfer size in */
/* blocks of this chunk. */
uint64_t num_reads; /* Total number of reads issued */
/* via cblk_read interface */
uint64_t num_writes; /* Total number of writes issued */
/* via cblk_write interface */
uint64_t num_areads; /* Total number of async reads */
/* issued via cblk_aread interface */
uint64_t num_awrites; /* Total number of async writes */
/* issued via cblk_awrite interface*/
uint32_t num_act_reads; /* Current number of reads active */
/* via cblk_read interface */
uint32_t num_act_writes; /* Current number of writes active */
/* via cblk_write interface */
uint32_t num_act_areads; /* Current number of async reads */
/* active via cblk_aread interface */
uint32_t num_act_awrites; /* Current number of async writes */
/* active via cblk_awrite interface*/
uint32_t max_num_act_writes; /* High water mark on the maximum */
/* number of writes active at once */
uint32_t max_num_act_reads; /* High water mark on the maximum */
/* number of reads active at once */
uint32_t max_num_act_awrites; /* High water mark on the maximum */
/* number of asyync writes active */
/* at once. */
uint32_t max_num_act_areads; /* High water mark on the maximum */
/* number of asyync reads active */
/* at once. */
uint64_t num_blocks_read; /* Total number of blocks read */
uint64_t num_blocks_written; /* Total number of blocks written */
uint64_t num_errors; /* Total number of all error */
/* responses seen */
uint64_t num_aresult_no_cmplt; /* Number of times cblk_aresult */
/* returned with no command */
/* completion */
uint64_t num_retries; /* Total number of all commmand */
/* retries. */
uint64_t num_timeouts; /* Total number of all commmand */
/* time-outs. */
uint64_t num_fail_timeouts; /* Total number of all commmand */
/* time-outs that led to a command */
/* failure. */
uint64_t num_no_cmds_free; /* Total number of times we didm't */
/* have free command available */
uint64_t num_no_cmd_room ; /* Total number of times we didm't */
/* have room to issue a command to */
/* the AFU. */
uint64_t num_no_cmds_free_fail; /* Total number of times we didn't */
/* have free command available and */
/* failed a request because of this*/
uint64_t num_fc_errors; /* Total number of all FC */
/* error responses seen */
uint64_t num_port0_linkdowns; /* Total number of all link downs */
/* seen on port 0. */
uint64_t num_port1_linkdowns; /* Total number of all link downs */
/* seen on port 1. */
uint64_t num_port0_no_logins; /* Total number of all no logins */
/* seen on port 0. */
uint64_t num_port1_no_logins; /* Total number of all no logins */
/* seen on port 1. */
uint64_t num_port0_fc_errors; /* Total number of all general FC */
/* errors seen on port 0. */
uint64_t num_port1_fc_errors; /* Total number of all general FC */
/* errors seen on port 1. */
uint64_t num_cc_errors; /* Total number of all check */
/* condition responses seen */
uint64_t num_afu_errors; /* Total number of all AFU error */
/* responses seen */
uint64_t num_capi_false_reads; /* Total number of all times */
/* poll indicated a read was ready */
/* but there was nothing to read. */
uint64_t num_capi_adap_resets; /* Total number of all adapter */
/* reset errors. */
uint64_t num_capi_afu_errors; /* Total number of all */
/* CAPI error responses seen */
uint64_t num_capi_afu_intrpts; /* Total number of all */
/* CAPI AFU interrupts for command */
/* responses seen. */
uint64_t num_capi_unexp_afu_intrpts; /* Total number of all of */
/* unexpected AFU interrupts */
uint64_t num_active_threads; /* Current number of threads */
/* running. */
uint64_t max_num_act_threads; /* Maximum number of threads */
/* running simultaneously. */
uint64_t num_cache_hits; /* Total number of cache hits */
/* seen on all reads */
} chunk_stats_t;
int rc = cblk_get_stats(chunk_id_t chunk_id, chunk_stats_t *stats, int flags))
Description
This service returns statistics for a specific chunk_id.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk whose size is about to be changed. |
| stats | Address of a chunk_stats_t structure. |
| flags | This is a collection of bit flags. |
Return Values
Returns 0 on success; otherwise it is error.
1.9 cblk_read
Purpose
Read 4K blocks from the chunk at the specified logical block address (LBA) into the buffer specified. It should be noted that his LBA is not the same as the LUNs LBA, since the chunk does not necessarily start at the lun's LBA 0
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_read(chunk_id_t chunk_id, void *buf, off_t lba, size_t nblocks, int flags));
Description
This service reads data from the chunk and places that data into the supplied buffer. This call will block until the read completes with success or error. The cblk_set_size call must be done prior to any cblk_read, cblk_write, cblk_aread, or cblk_awrite calls to this chunk.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which is being read. |
| buf | Buffer to which data is read into from the chunk must be aligned on 16 byte boundaries. |
| lba | Logical Block Address (4K offset) inside chunk. |
| nblocks | Specifies the size of the transfer in 4K sectors. Upper bound is 16 MB for physical lun. Upper bound for virtual lun is 4K |
| flags | This is a collection of bit flags. |
Return Values
| Return Value | Description |
| -1 | Error and errno is set for more details |
| 0 | No data was read. |
| n >0 | Number, n, of blocks read. |
1.10 cblk_write
Purpose
Write 4K blocks to the chunk at the specified logical block address (LBA) using the data from the buffer. It should be noted that his LBA is not the same as the LUNs LBA, since the chunk does not start at LBA 0
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
int rc = cblk_write(chunk_id_t chunk_id, void *buf, off_t lba, size_t nblocks, int flags));
Description
This service writes data from the chunk and places that data into the supplied buffer. This call will block until the write completes with success or error. The cblk_set_size call must be done prior to any cblk_write calls to this chunk.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which is being written. |
| buf | Buffer to which data is written from onto the chunk must be aligned on 16 byte boundaries. |
| lba | Logical Block Address (4K offset) inside chunk. |
| nblocks | Specifies the size of the transfer in 4K sectors. Upper bound is 16 MB for physical lun. Upper bound for virtual lun is 4K |
| flags | This is a collection of bit flags. |
Return Values
| Return Value | Description |
| -1 | Error and errno is set for more details |
| 0 | No data was written |
| n >0 | Number, n, of blocks written. |
1.11 cblk_aread
Purpose
Read 4K blocks from the chunk at the specified logical block address (LBA) into the buffer specified. It should be noted that his LBA is not the same as the LUNs LBA, since the chunk does not start at LBA 0
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
typedef enum {
CBLK_ARW_STATUS_PENDING = 0, /* Command has not completed */
CBLK_ARW_STATUS_SUCCESS = 1 /* Command completed successfully */
CBLK_ARW_STATUS_INVALID = 2 /* Caller's request is invalid */
CBLK_ARW_STATUS_FAIL = 3 /* Command completed with error */
} cblk_status_type_t;
typedef struct cblk_arw_status_s {
cblk_status_type_t status; /* Status of command */
/* See errno field for additional */
/* details on failure */
size_t blocks_transferred;/* Number of block transferred by */
/* this reqeuest. */
int errno; /* Errno when status indicates */
/* CBLK_ARW_STAT_FAIL */
} cblk_arw_status_t;
int rc = cblk_aread(chunk_id_t chunk_id, void *buf, off_t lba, size_t nblocks, int *tag, cblk_arw_status_t *status, int flags));
Description
This service reads data from the chunk and places that data into the supplied buffer. This call will not block to wait for the read to complete. A subsequent cblk_aresult call must be invoked to poll on completion. The cblk_set_size call must be done prior to any cblk_aread calls to this chunk.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which is being written. |
| buf | Buffer to which data is written from onto the chunk must be aligned on 16 byte boundaries. |
| lba | Logical Block Address (4K offset) inside chunk. |
| nblocks | Specifies the size of the transfer in 4K sectors. Upper bound is 16 MB for physical lun. Upper bound for virtual lun is 4K |
| tag | Returned Identifier that allows the caller to uniquely identify each command issued. |
| status | Address or 64-bit field provided by the caller which the capiblock library will update when a this command completes. This can be used by an application in place of using the cblk_aresult service. It should be noted that the CAPI adapter can not do this directly it would require software threads to update the status region. This field is not used if the CBLK_OPN_NO_INTRP_THREADSflags was specified for cblk_open the returned this chunk_id. |
| flags | This is a collection of bit flags. The CBLK_ARW_WAIT_CMD_FLAGSwill cause this service to block to wait for a free command to issue the request. Otherwise this service could return a value of -1 with an errno of EWOULDBLOCK (if there is no free command currently available). The CBLK_ARW_USER_TAG_FLAGSindicates the caller is specifying a user defined tag for this request. The caller would then need to use this tag with cblk_aresult and set its CBLK_ARESULT_USER_TAG flag. The CBLK_ARW_USER_STATUS_FLAGindicates the caller has set the status parameter which it expects will be updated when the command completes. |
Return Values
| Return Value | Description |
| -1 | Error and errno is set for more details |
| 0 | Successfully issued |
| n >0 | Indicates read completed (possibly from cache) and Number, n, of blocks written. |
1.12 cblk_awrite
Purpose
Write one 4K block to the chunk at the specified logical block address (LBA) using the data from the buffer. It should be noted that his LBA is not the same as the LUNs LBA, since the chunk does not start at LBA 0
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
typedef enum {
CBLK_ARW_STAT_NOT_ISSUED = 0, /* Command is has not been issued */
CBLK_ARW_STAT_PENDING = 1, /* Command has not completed */
CBLK_ARW_STAT_SUCCESS = 2 /* Command completed successfully */
CBLK_ARW_STAT_FAIL = 3 /* Command completed with error */
} cblk_status_type_t;
typedef struct cblk_arw_status_s {
cblk_status_type_t status; /* Status of command */
/* See errno field for additional */
/* details on failure */
size_t blocks_transferred;/* Number of block transferred by */
/* this reqeuest. */
int errno; /* Errno when status indicates */
/* CBLK_ARW_STAT_FAIL */
} cblk_arw_status_t;
int rc = cblk_awrite(chunk_id_t chunk_id, void *buf, off_t lba, size_t nblocks, int *tag, cblk_arw_status_t *status, int flags));
Description
This service writes data from the chunk and places that data into the supplied buffer. This call will not block waiting for the write to complete. A subsequent cblk_aresult call must be invoked to poll on completion. The cblk_set_size call must be done prior to any cblk_awrite calls to this chunk.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which is being written. |
| buf | Buffer to which data is written from onto the chunk must be aligned on 16 byte boundaries. |
| lba | Logical Block Address (4K offset) inside chunk. |
| nblocks | Specifies the size of the transfer in 4K sectors. Upper bound is 16 MB for physical lun. Upper bound for virtual lun is 4K |
| tag | Returned identifier that allows the caller to uniquely identify each command issued. |
| status | Address or 64-bit field provided by the caller which the capiblock library will updatewhen a this command completes. This can be used by an application in place of using the cblk_aresult service. It should be noted that the CAPI adapter can not do this directly it would require software threads to update the status region. This field is not used if the CBLK_OPN_NO_INTRP_THREADSflags was specified for cblk_open the returned this chunk_id. |
| flags | This is a collection of bit flags. The CBLK_ARW_WAIT_CMD_FLAGSwill cause this service to block to wait for a free command to issue the request. Otherwise this service could return a value of -1 with an errno of EWOULDBLOCK (if there is no free command currently available). The CBLK_ARW_USER_TAG_FLAGSindicates the caller is specifying a user defined tag for this request. The caller would then need to use this tag with cblk_aresult and set its CBLK_ARESULT_USER_TAG flag. The CBLK_ARW_USER_STATUS_FLAGindicates the caller has set the status parameter which it expects will be updated when the command completes. |
Return Values
Returns 0 on success; otherwise it returns -1 and errno is set.
1.13 cblk_aresult
Purpose
Return status and completion information for asynchronous requests.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
rc = cblk_aresult(chunk_id_t chunk_id, int *tag, uint64_t *status, int flags);
Description
This service returns an indication if the pending request issued via cblk_aread or cblk_awrite, which may have completed and if so its status.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which is being written. |
| tag | Pointer to tag caller is waiting for completion. If the CBLK_ARESULT_NEXT_TAG is set, then this field returns the tag for the next asynchronous completion |
| status | Pointer to status. The status will be returned when a request completes. |
| flags | Flags passed from the caller to cblk_aresult. The flag CBLK_ARESULT_BLOCKINGis set by the caller if they want cblk_aresult to block until a command completes (provided there are active commands). If the CBLK_ARESULT_NEXT_TAGflag is set, then this call returns whenever any asynchronous I/O request completes. The CBLK_ARESULT_USER_TAG flag indicates the caller checking for status of an asynchronous request that was issued with a user specified tag. |
Return Values
| Return Value | Description |
| -1 | Error and errno is set for more details |
| 0 | Returned without error but no tag is set. This may occur if an I/O request has not yet completed and the CBLK_ARESULT_BLOCKING flag is not set. |
| n >0 | Number, n, of blocks read/written. |
1.14 cblk_clone_after_fork
Purpose
Allows a child process to access the same virtual lun as the parent process. The child process must do this operation immediately after the fork, using the parent's chunk id in order to access that storage. If the child does not do this operation then it will not have any access to the parent's chunk ids. This service is not valid for physical luns. This is service is only valid for linux.
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
rc = cblk_clone_after_fork(chunk_id_t chunk_id, int mode, int flags);
Description
This service allows a child process to access data from the parents process.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which is in use by the parent process. If this call returns successfully, then this chunk id can also be used by the child process. |
| mode | Specifies the access mode for the child process (O_RDONLY, O_WRONLY, O_RDWR). NOTE: child process can not have greater access than parent. cblk_open is O_RDWR for the initial parent. Descendant processes can have less access. |
| flags | Flags passed from the caller. |
Return Values
| Return Value | Description |
| 0 | The request completed successfully. |
| -1 | Error and errno is set for more details |
1.15 cblk_listio
Purpose
Issues multiple I/O requests to CAPI flash disk with a single call and/or waits for multiple I/O requests from a CAPI flash disk to complete..
Syntax
#include <capiblock.h> for linux or <sys/capiblock.h> for AIX
typedef struct cblk_io {
uchar version; /* Version of structure */
#define CBLK_IO_VERSION_0 “I” /* Initial version 0 */
int flags; /* Flags for request */
#define CBLK_IO_USER_TAG 0x0001 /* Caller is specifying a user defined */
/* tag. */
#define CBLK_IO_USER_STATUS 0x0002 /* Caller is specifying a status location */
/* to be updated */
#define CBLK_IO_PRIORITY_REQ 0x0004/* This is (high) priority request that */
/* should be expediated vs non-priority */
/* requests */
uchar request_type; /* Type of request */
#define CBLK_IO_TYPE_READ 0x01 /* Read data request */
#define CBLK_IO_TYPE_WRITE 0x02 /* Write data request */
void *buf; /* Data buffer for request */
offset_t lba; /* Starting Logical block address for */
/* request. */
size_t nblocks; /* Size of request based on number of */
/* blocks. */
int tag; /* Tag for request. */
cblk_arw_status_t stat; /* Status of request */
} cblk_io_t
int rc = cblk_listio(chunk_id_t chunk_id,cblk_io_t *issue_io_list[],int issue_items,cblk_io_t *pending_io_list[],int pending_items, cblk_io_t *wait_io_list[], int wait_items, cblk_io_t *completion_io_list[],int *completion_items, uint64_t timeout, int flags));
Description
This service provides an interface to issue multiple I/O requests with one call and/or poll for completions of multiple I/O requests via one call. The individual requests are specified by the cblk_io_t type, which includes a chunk id, data buffer, starting Logical Block Address, a transfer size in 4K blocks. This service can update the I/O requests associated cblk_io_t (i.e. update status, tags and flags based on disposition of the I/O request).
This service can not be used to check for completion on I/O requests issued via cblk_aread or cblk_awrite.
Parameters
| Parameter | Description |
| chunk_id | The handle for the chunk which these I/O requests are associated. |
| issue_io_list | This specifies an array of I/O requests to issue to CAPI flash disks. Each individual array element of type cblk_io_t specifies an individual I/O request containing chunk id, data buffer, starting Logical Block Address, a transfer size in 4K blocks. These array elements can be updated by this service to indicate completion status and/or tags. The status field of the individual cblk_io_t array elements will be initialized by this service. If this field is null, then this service can be used to wait for completions of other requests issued from previous cblk_listio calls by setting the pending_io_list |
| issue_io_items | Specifies the number of array elements in the issue_io_list array |
| pending_io_list | This specifies an array of I/O requests that were issued via a previous cblk_listio request. This allows one to poll for I/O request completions, without requiring them to wait for all completions (i.e. setting the completion_io_list parameter). |
| pending_io_items | Specifies the number of array elements in the pending_io_list array |
| wait_io_list | Array of I/O requests, which for which this service will block until these requests complete. These I/O requests must also be specified in the either the issue_io_list or the pending_io_list. If an I/O request in the issue_io_list fails to be issued due to invalid settings by the caller or no resources, then that I/O request's elements in the io_list will be updated to indicate this (its status will be left as CBLK_ARW_STAT_NOT_ISSUED) and this service will not wait on that I/O request. Thus all I/O requests in the wait_io_list which completed will have a status of CBLK_ARW_STAT_SUCCESS or CBLK_ARW_STAT_FAIL. I/O requests which did not complete will not have their status updated. |
| wait_items | Specifies the number of array elements in the wait_io_list array |
| completion_io_list | The caller will set this to an initialized (zeroed) array of I/O requests and set the completion_items to the number of array elements in this array. When this service returns the array will contain I/O requests specified in the issue_io_list and/or pending_io_list that were completed by the CAPI device, but which were not specified in the wait_io_list. If an I/O request in the io_list fails to be issued due to invalid settings by the caller or no resources, then that I/O requests element will not be copied to the completion_io_list and its status in the io_list will be updated to indicate this (its status will be left as CBLK_ARW_STAT_NOT_ISSUED) . Thus all I/O requests returned in this list will have a status of CBLK_ARW_STAT_SUCCESS or CBLK_ARW_STAT_FAIL. |
| completion_items | The caller sets this to the address of the number of array elements it placed in the completion_io_list. When this service returns, this value is updated to the number of I/O requests placed in the completion_io_list. |
| timeout | Timeout in microseconds to wait for all I/O requests in the wait_io_list. This is only valid if the wait_io_list is not null. If any of the I/O requests in the wait_io_list do not complete within the time-out value, then this service returns a value of -1 and sets errno to a value ETIMEDOUT (when this occurs some commands may have completed in the wait_io_list, Thus the caller needs to check each request in the wait_io_list to determine which ones completed.) It is the caller's responsibility to remove completed items from the pending_io_list before the next invocation of this service. A timeout value of 0, indicates that this service will block until requests in the wait_io_list complete. |
| flags | This is a collection of bit flags. The CBLK_LISTIO_WAIT_ISSUE_CMD flagswill cause this service to block to wait for a free commands to issue all the requests even if the timeout value is exceeded and CBLK_LISTIO_WAIT_CMD_FLAG is set. Otherwise this service could return a value of -1 with an errno of EWOULDBLOCKif there are not enough free commands currently available (for this situation, some commands may have successfully queued. The caller would need to examine the individual I/O requests in the issue_io_list to determine which ones failed) |
Return Values
| Return Value | Description |
| -1 | Error and errno is set for more details |
| 0 | This service completed without error. |