From 8b0843b8b24a910351169f5d1d9afb584e3a4107 Mon Sep 17 00:00:00 2001 From: Vladislav Bolkhovitin Date: Fri, 25 Mar 2011 18:37:06 +0000 Subject: [PATCH] Small sections rearrange git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@3308 d57e44dd-8a1f-0410-8b47-8ef2f437770f --- doc/scst_user_spec.sgml | 1124 ++++++++++++++++++++------------------- 1 file changed, 563 insertions(+), 561 deletions(-) diff --git a/doc/scst_user_spec.sgml b/doc/scst_user_spec.sgml index 2d09fa4e0..afdb995fb 100644 --- a/doc/scst_user_spec.sgml +++ b/doc/scst_user_spec.sgml @@ -336,567 +336,8 @@ SCST_USER_REPLY_AND_GET_CMD or SCST_USER_REPLY_CMD function to tell SCST that the subcommand's processing is finished, although some subcommands don't return a value. - -Possible subcommands: - - SCST_USER_ATTACH_SESS - -

-SCST_USER_ATTACH_SESS notifies the user space handler that a new -initiator's session is about to be attached to the device. Payload -contains struct scst_user_sess, which is defined as the following: - - -struct scst_user_sess -{ - uint64_t sess_h; - uint64_t lun; - uint16_t threads_num; - uint8_t rd_only; - uint16_t scsi_transport_version; - uint16_t phys_transport_version; - char initiator_name[SCST_MAX_NAME]; - char target_name[SCST_MAX_NAME]; -}, - - -where: - - - - -When SCST_USER_ATTACH_SESS is returned, it is guaranteed that there are -no other commands are being executed or pending. - -After SCST_USER_ATTACH_SESS function completed, the user space device -handler shall reply using "result" field of the corresponding reply -command. - - - SCST_USER_DETACH_SESS - -

-SCST_USER_DETACH_SESS notifies the user space handler that the -corresponding initiator is about to be detached from the particular -device. Payload contains struct scst_user_sess, where only handle field -is valid. - -When SCST_USER_DETACH_SESS is returned, it is guaranteed that there are -no other commands are being executed or pending. - -This command doesn't reply any return value, although -SCST_USER_REPLY_AND_GET_CMD or SCST_USER_REPLY_CMD function must be -called. - - - SCST_USER_PARSE - -

-SCST_USER_PARSE returns SCSI command on PARSE state of the SCST -processing. The PARSE state is intended to check validity of the -command, determine data transfer type and the necessary data buffer -size. This subcommand is returned only if SCST_USER_SET_OPTIONS -parse_type isn't set to SCST_USER_PARSE_STANDARD. In this case the -standard SCST internal parser for this SCSI device type will do all the -job. - -Payload contains struct scst_user_scsi_cmd_parse, which is defined as -the following: - - -struct scst_user_scsi_cmd_parse -{ - uint64_t sess_h; - - uint8_t cdb[SCST_MAX_CDB_SIZE]; - uint16_t cdb_len; - - uint32_t timeout; - int32_t bufflen; - int32_t out_bufflen; - - uint32_t op_flags; - - uint8_t queue_type; - uint8_t data_direction; - - uint8_t expected_values_set; - uint8_t expected_data_direction; - int32_t expected_transfer_len; - int32_t expected_out_transfer_len; - - uint32_t sn; -}, - - -where: - - - - -Bits of scst_cdb_flags can be: - - - - -In the PARSE state of SCSI commands processing the user space device -handler shall check and provide SCST values for command data buffer -length, data flow direction and timeout, which it shall reply using the -corresponding reply command. - -In case of any error the error reporting should be deferred until -SCST_USER_EXEC subcommand, where the appropriate SAM status and sense -shall be set. - - - SCST_USER_ALLOC_MEM - -

-SCST_USER_ALLOC_MEM returns SCSI command on memory allocation state of -the SCST processing. On this state the user space device handler shall -allocate the command's data buffer with bufflen length and then return -it to SCST using the corresponding reply command. Then SCST internally -will convert it in SG vector in order to use it itself and by target -drivers. - -If the memory reuse type is disabled (i.e. set to SCST_USER_MEM_NO_REUSE) -there are no special requirements for buffer memory or its alignment, it -could be just what malloc() returned. If the memory reuse type is enabled, -the buffer shall be page size aligned, for example using memalign() -function. - -Payload contains struct scst_user_scsi_cmd_alloc_mem, which is defined -as the following: - - -struct scst_user_scsi_cmd_alloc_mem -{ - uint64_t sess_h; - - uint8_t cdb[SCST_MAX_CDB_SIZE]; - uint16_t cdb_len; - - int32_t alloc_len; - - uint8_t queue_type; - uint8_t data_direction; - - uint32_t sn; -}, - - -where: - - - - -Memory allocation, preparation and freeing are ones of the most -complicated and expensive operations during SCSI commands processing. -Module scst_user provides a way to almost completely eliminate those -operations by reusing once allocated memory for subsequent SCSI -commands. It is controlled by for more -details. - -Since the SGV cache caches SG vectors, which can be bigger, than actual -data sizes of SCSI commands, alloc_len field could also be bigger, than -actually required by the SCSI command. - -The memory reuse could be used in both SCSI tagged and untagged queuing -environments. In the SCSI tagged queuing environment the SGV cache will -take care that several commands don't use the same buffer simultaneously -by asking the user space handler to allocate a new data buffer, when all -cached ones are busy. - -Some important notes: - - - If the user space handler needs to call fork(), it must call -madvise() with MADV_DONTFORK flag for all allocated data buffers, -otherwise parent or child process could loose the connection with them, -which could lead to data corruption. See -for details. - - The interface assumes that all allocated memory by the user space -handler is DMA'able by the target hardware. This is almost always true -for most modern systems, except if the target hardware isn't capable of -using 64-bit address space and the system has >4GB of memory or the -memory addresses are in address space, which is unavailable with 32-bit -addresses. - - -In case of any error the error reporting should be deferred until -SCST_USER_EXEC subcommand, where the appropriate SAM status and sense -should be set. - - - SCST_USER_EXEC - -

-SCST_USER_EXEC returns SCSI command on execution state of the SCST -processing. The user space handler should execute the SCSI command and -reply using the corresponding reply command. - -In some cases for performance reasons for READ-type SCSI commands -SCST_USER_ALLOC_MEM subcommand isn't returned before SCST_USER_EXEC. -Thus, if pbuf pointer is 0 and the SCSI command needs data transfer, the -user space handler should be prepared to allocate the data buffer with -size alloc_len, which could be bigger (due to the SGV cache), than -actually required by the SCSI command. But field bufflen will contain -the correct value. All the memory reusage rules, described for -SCST_USER_ALLOC_MEM, apply to SCST_USER_EXEC as well. - -Payload contains struct scst_user_scsi_cmd_exec, which is defined as the -following: - - -struct scst_user_scsi_cmd_exec -{ - uint64_t sess_h; - - uint8_t cdb[SCST_MAX_CDB_SIZE]; - uint16_t cdb_len; - - int32_t data_len; - int32_t bufflen; - int32_t alloc_len; - uint64_t pbuf; - uint8_t queue_type; - uint8_t data_direction; - uint8_t partial; - uint32_t timeout; - - aligned_u64 p_out_buf; - int32_t out_bufflen; - - uint32_t sn; - - uint32_t parent_cmd_h; - int32_t parent_cmd_data_len; - uint32_t partial_offset; -}, - - -where: - - - - - - - -It is guaranteed that only commands of the same queue_type per session -can be returned simultaneously. - -In case of any error it should be reported via appropriate SAM status -and sense. If it happens for a subcommand of a partial data transfers -command, all other subcommands of this command, which already passed the -the user space handler or will be passed in the future, will be aborted -by scst_user, the user space handler should ignore them. - - - SCST_USER_ON_FREE_CMD - -

-SCST_USER_ON_FREE_CMD returns SCSI command when the command is about to -be freed. At this stage, the user space device handler could do any -necessary cleanups, for instance, free allocated for data buffer memory. - - -struct scst_user_scsi_on_free_cmd -{ - uint64_t pbuf; - int32_t resp_data_len; - uint8_t buffer_cached; - uint8_t aborted; - uint8_t status; - uint8_t delivery_status; -}, - - -where: - - - - - - -The user space handler should reply using the corresponding reply -command. No error code is needed. - - - SCST_USER_ON_CACHED_MEM_FREE - -

-SCST_USER_ON_CACHED_MEM_FREE subcommand is returned, when SGV cache -decided that this buffer isn't needed anymore. This happens after some -time of inactivity or when the system is under memory pressure. - -Payload contains struct scst_user_on_cached_mem_free, which is defined -as the following: - - -struct scst_user_scsi_cmd_alloc_mem -{ - uint64_t pbuf; -}, - - -where: - - - - - - SCST_USER_TASK_MGMT - -

-SCST_USER_TASK_MGMT subcommand returns a task management functions. -Payload contains struct scst_user_tm, which is defined as the following: - - -struct scst_user_tm -{ - uint64_t sess_h; - uint32_t fn; - uint32_t cmd_h_to_abort; - uint32_t cmd_sn; - uint8_t cmd_sn_set; -}, - - -where: - - - - -After TM function is completed, the user space device handler shall -reply using "result" field of the corresponding reply command. It isn't -necessary to wait for aborted command(s) finished, the result of TM -function shall be returned immediately. SCST core will take care that -the reply to the TM function isn't sent before all affection SCSI -commands finished. - -Possible values of - - -Possible return values are: - - - +You can see description of possible subcommands in section +. SCST_USER_REPLY_CMD @@ -1155,6 +596,567 @@ where: SCST_USER_PREALLOC_BUFFER returns 0 on success or -1 in case of error, and errno is set appropriately. + SCST_USER subcommands

+SCST_USER_ATTACH_SESS notifies the user space handler that a new +initiator's session is about to be attached to the device. Payload +contains struct scst_user_sess, which is defined as the following: + + +struct scst_user_sess +{ + uint64_t sess_h; + uint64_t lun; + uint16_t threads_num; + uint8_t rd_only; + uint16_t scsi_transport_version; + uint16_t phys_transport_version; + char initiator_name[SCST_MAX_NAME]; + char target_name[SCST_MAX_NAME]; +}, + + +where: + + + + +When SCST_USER_ATTACH_SESS is returned, it is guaranteed that there are +no other commands are being executed or pending. + +After SCST_USER_ATTACH_SESS function completed, the user space device +handler shall reply using "result" field of the corresponding reply +command. + + + SCST_USER_DETACH_SESS + +

+SCST_USER_DETACH_SESS notifies the user space handler that the +corresponding initiator is about to be detached from the particular +device. Payload contains struct scst_user_sess, where only handle field +is valid. + +When SCST_USER_DETACH_SESS is returned, it is guaranteed that there are +no other commands are being executed or pending. + +This command doesn't reply any return value, although +SCST_USER_REPLY_AND_GET_CMD or SCST_USER_REPLY_CMD function must be +called. + + + SCST_USER_PARSE + +

+SCST_USER_PARSE returns SCSI command on PARSE state of the SCST +processing. The PARSE state is intended to check validity of the +command, determine data transfer type and the necessary data buffer +size. This subcommand is returned only if SCST_USER_SET_OPTIONS +parse_type isn't set to SCST_USER_PARSE_STANDARD. In this case the +standard SCST internal parser for this SCSI device type will do all the +job. + +Payload contains struct scst_user_scsi_cmd_parse, which is defined as +the following: + + +struct scst_user_scsi_cmd_parse +{ + uint64_t sess_h; + + uint8_t cdb[SCST_MAX_CDB_SIZE]; + uint16_t cdb_len; + + uint32_t timeout; + int32_t bufflen; + int32_t out_bufflen; + + uint32_t op_flags; + + uint8_t queue_type; + uint8_t data_direction; + + uint8_t expected_values_set; + uint8_t expected_data_direction; + int32_t expected_transfer_len; + int32_t expected_out_transfer_len; + + uint32_t sn; +}, + + +where: + + + + +Bits of scst_cdb_flags can be: + + + + +In the PARSE state of SCSI commands processing the user space device +handler shall check and provide SCST values for command data buffer +length, data flow direction and timeout, which it shall reply using the +corresponding reply command. + +In case of any error the error reporting should be deferred until +SCST_USER_EXEC subcommand, where the appropriate SAM status and sense +shall be set. + + + SCST_USER_ALLOC_MEM + +

+SCST_USER_ALLOC_MEM returns SCSI command on memory allocation state of +the SCST processing. On this state the user space device handler shall +allocate the command's data buffer with bufflen length and then return +it to SCST using the corresponding reply command. Then SCST internally +will convert it in SG vector in order to use it itself and by target +drivers. + +If the memory reuse type is disabled (i.e. set to SCST_USER_MEM_NO_REUSE) +there are no special requirements for buffer memory or its alignment, it +could be just what malloc() returned. If the memory reuse type is enabled, +the buffer shall be page size aligned, for example using memalign() +function. + +Payload contains struct scst_user_scsi_cmd_alloc_mem, which is defined +as the following: + + +struct scst_user_scsi_cmd_alloc_mem +{ + uint64_t sess_h; + + uint8_t cdb[SCST_MAX_CDB_SIZE]; + uint16_t cdb_len; + + int32_t alloc_len; + + uint8_t queue_type; + uint8_t data_direction; + + uint32_t sn; +}, + + +where: + + + + +Memory allocation, preparation and freeing are ones of the most +complicated and expensive operations during SCSI commands processing. +Module scst_user provides a way to almost completely eliminate those +operations by reusing once allocated memory for subsequent SCSI +commands. It is controlled by for more +details. + +Since the SGV cache caches SG vectors, which can be bigger, than actual +data sizes of SCSI commands, alloc_len field could also be bigger, than +actually required by the SCSI command. + +The memory reuse could be used in both SCSI tagged and untagged queuing +environments. In the SCSI tagged queuing environment the SGV cache will +take care that several commands don't use the same buffer simultaneously +by asking the user space handler to allocate a new data buffer, when all +cached ones are busy. + +Some important notes: + + + If the user space handler needs to call fork(), it must call +madvise() with MADV_DONTFORK flag for all allocated data buffers, +otherwise parent or child process could loose the connection with them, +which could lead to data corruption. See +for details. + + The interface assumes that all allocated memory by the user space +handler is DMA'able by the target hardware. This is almost always true +for most modern systems, except if the target hardware isn't capable of +using 64-bit address space and the system has >4GB of memory or the +memory addresses are in address space, which is unavailable with 32-bit +addresses. + + +In case of any error the error reporting should be deferred until +SCST_USER_EXEC subcommand, where the appropriate SAM status and sense +should be set. + + + SCST_USER_EXEC + +

+SCST_USER_EXEC returns SCSI command on execution state of the SCST +processing. The user space handler should execute the SCSI command and +reply using the corresponding reply command. + +In some cases for performance reasons for READ-type SCSI commands +SCST_USER_ALLOC_MEM subcommand isn't returned before SCST_USER_EXEC. +Thus, if pbuf pointer is 0 and the SCSI command needs data transfer, the +user space handler should be prepared to allocate the data buffer with +size alloc_len, which could be bigger (due to the SGV cache), than +actually required by the SCSI command. But field bufflen will contain +the correct value. All the memory reusage rules, described for +SCST_USER_ALLOC_MEM, apply to SCST_USER_EXEC as well. + +Payload contains struct scst_user_scsi_cmd_exec, which is defined as the +following: + + +struct scst_user_scsi_cmd_exec +{ + uint64_t sess_h; + + uint8_t cdb[SCST_MAX_CDB_SIZE]; + uint16_t cdb_len; + + int32_t data_len; + int32_t bufflen; + int32_t alloc_len; + uint64_t pbuf; + uint8_t queue_type; + uint8_t data_direction; + uint8_t partial; + uint32_t timeout; + + aligned_u64 p_out_buf; + int32_t out_bufflen; + + uint32_t sn; + + uint32_t parent_cmd_h; + int32_t parent_cmd_data_len; + uint32_t partial_offset; +}, + + +where: + + + + + + + +It is guaranteed that only commands of the same queue_type per session +can be returned simultaneously. + +In case of any error it should be reported via appropriate SAM status +and sense. If it happens for a subcommand of a partial data transfers +command, all other subcommands of this command, which already passed the +the user space handler or will be passed in the future, will be aborted +by scst_user, the user space handler should ignore them. + + + SCST_USER_ON_FREE_CMD + +

+SCST_USER_ON_FREE_CMD returns SCSI command when the command is about to +be freed. At this stage, the user space device handler could do any +necessary cleanups, for instance, free allocated for data buffer memory. + + +struct scst_user_scsi_on_free_cmd +{ + uint64_t pbuf; + int32_t resp_data_len; + uint8_t buffer_cached; + uint8_t aborted; + uint8_t status; + uint8_t delivery_status; +}, + + +where: + + + + + + +The user space handler should reply using the corresponding reply +command. No error code is needed. + + + SCST_USER_ON_CACHED_MEM_FREE + +

+SCST_USER_ON_CACHED_MEM_FREE subcommand is returned, when SGV cache +decided that this buffer isn't needed anymore. This happens after some +time of inactivity or when the system is under memory pressure. + +Payload contains struct scst_user_on_cached_mem_free, which is defined +as the following: + + +struct scst_user_scsi_cmd_alloc_mem +{ + uint64_t pbuf; +}, + + +where: + + + + + + SCST_USER_TASK_MGMT + +

+SCST_USER_TASK_MGMT subcommand returns a task management functions. +Payload contains struct scst_user_tm, which is defined as the following: + + +struct scst_user_tm +{ + uint64_t sess_h; + uint32_t fn; + uint32_t cmd_h_to_abort; + uint32_t cmd_sn; + uint8_t cmd_sn_set; +}, + + +where: + + + + +After TM function is completed, the user space device handler shall +reply using "result" field of the corresponding reply command. It isn't +necessary to wait for aborted command(s) finished, the result of TM +function shall be returned immediately. SCST core will take care that +the reply to the TM function isn't sent before all affection SCSI +commands finished. + +Possible values of + + +Possible return values are: + + + + Commands processing flow example.