mirrors/scst
1
0
Fork 0
mirror of https://github.com/SCST-project/scst.git synced 2026-05-14 09:11:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

Removed trailing whitespace.

Browse Source 
git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@1614 d57e44dd-8a1f-0410-8b47-8ef2f437770f
This commit is contained in:
Bart Van Assche
2010-04-14 18:03:04 +00:00
parent fa80e59bdc
commit 3a7fae9677
3 changed files with 68 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
doc/scst_user_spec.txt
View File

@@ -21,13 +21,13 @@ http://scst.st.net.
II. User space API.
Module scst_user provides /dev/scst_user character device with the
following system calls available:
following system calls available:
- open() - allows to open the device and get a file handle, which
will be used in all subsequent actions until close() is called
- close() - closes file handle returned by open()
- poll() - allows to wait until some pending command from SCST to
process is available.
@@ -165,10 +165,10 @@ where:
- parse_type - defines how the user space handler wants to process
PARSE subcommand. Possible values are:
* SCST_USER_PARSE_STANDARD - tells SCST use standard internal parser
for this SCSI device type.
* SCST_USER_PARSE_CALL - tells SCST generate SCST_USER_PARSE for all
SCSI commands
@@ -187,7 +187,7 @@ where:
- memory_reuse_type - defines how memory allocated by the user space
handler for a SCSI commands data buffers is then reused by the SCST
core as data buffer for subsequent commands. Possible values are:
* SCST_USER_MEM_NO_REUSE - no memory reuse is possible, for each
commands the user space handler will each time allocate a dedicated
data buffer
@@ -216,7 +216,7 @@ where:
have in that field SCST_USER_SUBCOMMAND_FINAL flag. All the
subcommands will have the original unmodified CDB. Possible values
are:
* SCST_USER_PARTIAL_TRANSFERS_NOT_SUPPORTED - the partial data
transfers are not supported
@@ -329,7 +329,7 @@ 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.
@@ -394,27 +394,27 @@ where:
- cdb - SCSI CDB
- cdb_len - SCSI CDB length
- ext_cdb_len - size of extended CDB, see SCST_USER_GET_EXTENDED_CDB
for more details
- timeout - CDB execution timeout
- bufflen - command's buffer length
- in_bufflen - for bidirectional commands command's IN, i.e. from
initiator to target, buffer length
- op_flags - CDB flags, one or more scst_cdb_flags bits, see below.
- queue_type - SCSI task attribute (queue type)
- data_direction - command's data flow direction, one of SCST_DATA_*
constants
- expected_values_set - true if expected_data_direction and
expected_transfer_len contain valid values
- expected_data_direction - remote initiator supplied command's data
flow direction
@@ -439,7 +439,7 @@ Bits of scst_cdb_flags can be:
- SCST_IMPLICIT_HQ - this command is an implicit HEAD OF QUEUE command
- SCST_SKIP_UA - Unit Attentions shouldn't be delivered for this command
- SCST_SKIP_UA - Unit Attentions shouldn't be delivered for this command
- SCST_WRITE_MEDIUM - this command writes data on the medium, so should be
forbidden for read-only devices
@@ -454,7 +454,7 @@ 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.
4.4.4. SCST_USER_ALLOC_MEM
@@ -502,7 +502,7 @@ where:
for more details
- alloc_len - command's buffer length
- queue_type - SCSI task attribute (queue type )
- data_direction - command's data flow direction, one of SCST_DATA_*
@@ -519,7 +519,7 @@ set by SCST_USER_SET_OPTIONS function. If any type memory reusage is
enabled, then SCST will use its internal SGV cache in order to cache
allocated and fully built SG vectors for subsequent commands of this
type, so for them SCST_USER_ALLOC_MEM subfunction will not be called and
in SCST_USER_EXEC pbuf pointer will point to that reused buffer.
in SCST_USER_EXEC pbuf pointer will point to that reused buffer.
SGV cache is a backend cache made on top of Linux kernel kmem cache. It
caches unused SG vectors for future allocations to improve performance.
@@ -618,7 +618,7 @@ where:
- data_len - command's data length. Could be different from bufflen for
commands like VERIFY, which transfer different amount of data, than
process, or even none of them
- bufflen - command's buffer length
- alloc_len - command's buffer length, which should be allocated, if pbuf
@@ -636,7 +636,7 @@ where:
have the following OR'ed flags:
* SCST_USER_SUBCOMMAND - set if the command is a partial subcommand
* SCST_USER_SUBCOMMAND_FINAL - set if the subcommand is a final one
- timeout - CDB execution timeout
@@ -707,7 +707,7 @@ where:
- delivery_status - status of cmd's status/data delivery to remote
initiator. Can be:
* SCST_CMD_DELIVERY_SUCCESS - delivery succeeded
* SCST_CMD_DELIVERY_FAILED - delivery failed
@@ -736,7 +736,7 @@ where:
4.4.8. 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:
@@ -763,7 +763,7 @@ where:
more details.
- cmd_sn_set - specifies if cmd_sn is valid
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
@@ -786,9 +786,9 @@ Possible values of "fn" field:
- SCST_NEXUS_LOSS_SESS - notifies about nexus loss event for the session
- SCST_ABORT_ALL_TASKS_SESS - all tasks in the session shall be aborted
- SCST_NEXUS_LOSS - notifies about global nexus loss event
- SCST_ABORT_ALL_TASKS - all tasks shall be aborted
Possible return values are:
@@ -839,7 +839,7 @@ struct scst_user_scsi_cmd_reply_parse
{
uint8_t queue_type;
uint8_t data_direction;
int16_t cdb_len;
int16_t cdb_len;
uint32_t op_flags;
int32_t data_len;
int32_t bufflen;
@@ -848,7 +848,7 @@ struct scst_user_scsi_cmd_reply_parse
where:
- queue_type - SCSI task attribute (queue type )
- data_direction - command's data flow direction, one of SCST_DATA_* constants
- cdb_len - length of CDB
@@ -856,7 +856,7 @@ where:
- op_flags - commands flags, one or more scst_cdb_flags bits, see above.
- data_len - command's data length
- bufflen - command's buffer length
@@ -890,14 +890,14 @@ where:
original SCST_USER_EXEC subcommand pbuf field is 0
- reply_type - could be one of the following constants:
* SCST_EXEC_REPLY_BACKGROUND - tells SCST send to the remote
initiator GOOD status, but the command not yet completed by the
user space handler, it is being executed in the background. When
it will be completed, the user space handler will call
SCST_USER_REPLY_CMD again with reply_type
SCST_EXEC_REPLY_COMPLETED.
* SCST_EXEC_REPLY_COMPLETED - the user space handler completed the command
- status - SAM status of the commands execution
@@ -988,9 +988,9 @@ Structure scst_user_prealloc_buffer_in has the following definition:
where:
- pbuf - pointer to the buffer
- bufflen - size of the buffer
- for_clust_pool - if 1, then the buffer will be preallocated in the
clustered pool. If 0, then the buffer will be preallocated in the
normal pool.
@@ -1014,7 +1014,7 @@ and errno is set appropriately.
As the example consider a simple synchronous VTL, which serves one
virtual SCSI tape device and can process only one command at time from
any initiator.
any initiator.
At the beginning the VTL opens using open() call /dev/scst_user in the
default blocking mode.
@@ -1039,9 +1039,9 @@ prepares scst_user_reply_cmd structure, where:
- cmd_h set to returned by SCST_USER_REPLY_AND_GET_CMD ioctl() cmd_h
- subcode set to SCST_USER_ATTACH_SESS
- result set to 0
Then it prepares struct scst_user_get_cmd with reply set to the prepared
scst_user_reply_cmd structure, calls SCST_USER_REPLY_AND_GET_CMD ioctl()
and waits for some SCSI command arrives from the initiator.
@@ -1061,12 +1061,12 @@ scst_user_reply_cmd structure, where:
- exec_reply.resp_data_len set to length of the read data
- exec_reply.pbuf set to the data buffer, where the data were read
- exec_reply.reply_type set to SCST_EXEC_REPLY_COMPLETED
- exec_reply.status set to the SAM defined status of the
operation
- exec_reply.sense_len set and exec_reply.psense_buffer filled with
sense data, if necessary

38
doc/sgv_cache.txt
View File

@@ -35,12 +35,12 @@ In fileio_tgt application, which uses a regular malloc() function to
allocate data buffers, this facility allows ~30% less CPU load and
considerable performance increase.
- Prevent each initiator or all initiators altogether to allocate too
- Prevent each initiator or all initiators altogether to allocate too
much memory and DoS the target. Consider 10 initiators, which can have
access to 10 devices each. Any of them can queue up to 64 commands, each
can transfer up to 1MB of data. So, all of them in a peak can allocate
up to 10*10*64 = ~6.5GB of memory for data buffers. This amount must be
limited somehow and the SGV cache performs this function.
limited somehow and the SGV cache performs this function.
From implementation POV the SGV cache is a simple extension of the kmem
cache. It can work in 2 modes:
@@ -58,10 +58,10 @@ below). This mode is in average allows less memory overhead comparing
with the fixed size buffers mode.
Consider how the SGV cache works in the set of buffers mode. When a
request to allocate new SG vector comes, sgv_pool_alloc() via
request to allocate new SG vector comes, sgv_pool_alloc() via
sgv_get_obj() checks if there is already a cached vector with that
order. If yes, then that vector will be reused and its length, if
necessary, will be modified to match the requested size. In the above
order. If yes, then that vector will be reused and its length, if
necessary, will be modified to match the requested size. In the above
example request for 11KB buffer, 4 pages vector will be reused and
modified using trans_tbl to contain 3 pages and the last entry will be
modified to contain the requested length - 2*PAGE_SIZE. If there is no
@@ -88,7 +88,7 @@ sgv_shrink() called by system, when it's asking for memory.
struct sgv_pool *sgv_pool_create(const char *name,
enum sgv_clustering_types clustered, int single_alloc_pages,
bool shared, int purge_interval)
This function creates and initializes an SGV cache. It has the following
arguments:
@@ -105,7 +105,7 @@ arguments:
* sgv_full_clustering - free merging of pages at any place in
the SG is allowed. This mode usually provides the best merging
rate.
- single_alloc_pages - if 0, then the SGV cache will work in the set of
power 2 size buffers mode. If >0, then the SGV cache will work in the
fixed size buffers mode. In this case single_alloc_pages sets the
@@ -151,11 +151,11 @@ user space pages.
alloc_pages_fn() has the following parameters:
- sg - SG entry, to which the allocated page should be added.
- gfp - the allocation GFP flags
- priv - pointer to a private data supplied to sgv_pool_alloc()
This function should return the allocated page or NULL, if no page was
allocated.
@@ -163,9 +163,9 @@ allocated.
free_pages_fn() has the following parameters:
- sg - SG vector to free
- sg_count - number of SG entries in the sg
- priv - pointer to a private data supplied to the corresponding sgv_pool_alloc()
@@ -181,26 +181,26 @@ following parameters:
- size - size of the resulting SG vector in bytes
- gfp_mask - the allocation mask
- flags - the allocation flags. The following flags are possible and
can be set using OR operation:
* SGV_POOL_ALLOC_NO_CACHED - the SG vector must not be cached.
* SGV_POOL_NO_ALLOC_ON_CACHE_MISS - don't do an allocation on a
cache miss.
* SGV_POOL_RETURN_OBJ_ON_ALLOC_FAIL - return an empty SGV object,
i.e. without the SG vector, if the allocation can't be completed.
For instance, because SGV_POOL_NO_ALLOC_ON_CACHE_MISS flag set.
- count - the resulting count of SG entries in the resulting SG vector.
- sgv - the resulting SGV object. It should be used to free the
resulting SG vector.
- mem_lim - memory limits, see below.
- priv - pointer to private for this allocation data. This pointer will
be supplied to alloc_pages_fn() and free_pages_fn() and can be
retrieved by sgv_get_priv().

22
scst/SysfsRules
View File

@@ -29,7 +29,7 @@ I. Rules for target drivers
SCST core for each target driver (struct scst_tgt_template) creates a
root subdirectory in /sys/kernel/scst_tgt/targets with name
scst_tgt_template.name (called "target_driver_name" further in this
document).
document).
For each target (struct scst_tgt) SCST core creates a root subdirectory
in /sys/kernel/scst_tgt/targets/target_driver_name with name
@@ -79,7 +79,7 @@ in all targets, but this is OPTIONAL.
MUST be 0 by default.
2. "trace_level" - this attribute SHOULD allow to change log level of this
driver.
driver.
This attribute SHOULD have read and write permissions for superuser and be
read-only for other users.
@@ -114,7 +114,7 @@ For example:
2.0.0
EXTRACHECKS
DEBUG
4. "mgmt" - this attribute MUST allow to add and delete targets, if
virtual targets are supported by this driver, as well as it MAY allow to
add and delete the target driver's or its targets' attributes.
@@ -138,7 +138,7 @@ Usage: echo "add_target target_name [parameters]" >mgmt
echo "add_target_attribute target_name OutgoingUser name password" >mgmt
echo "del_target_attribute target_name OutgoingUser name" >mgmt
where parameters are one or more param_name=value pairs separated by ';'
where parameters are one or more param_name=value pairs separated by ';'
4.1. "add_target" - if supported, this command MUST add new target with
name "target_name" and specified optional or required parameters. Each
@@ -151,7 +151,7 @@ this command.
All target drivers supporting "add_target" command MUST support all
read-only targets' key attributes as parameters to "add_target" command
with the attributes' names as parameters' names and the attributes'
values as parameters' values.
values as parameters' values.
For example:
@@ -203,7 +203,7 @@ user (attribute
/sys/kernel/scst_tgt/targets/iscsi/iqn.2006-10.net.vlnb:tgt/IncomingUser)
with name "name" and password "password".
4.6. "del_target_attribute" - if supported, this command MUST delete
4.6. "del_target_attribute" - if supported, this command MUST delete
target's attribute with the specified name and values. The values MUST
be specified, because in some cases attributes MAY internally be
distinguished by values. For instance, iSCSI target might have several
@@ -268,7 +268,7 @@ handlers. The children dev handlers depend from the parent dev handlers.
SCST core for each parent dev handler (struct scst_dev_type with
parent member with value NULL) creates a root subdirectory in
/sys/kernel/scst_tgt/handlers with name scst_dev_type.name (called
"dev_handler_name" further in this document).
"dev_handler_name" further in this document).
Parent dev handlers can have one or more subdirectories for children dev
handlers with names scst_dev_type.name of them.
@@ -307,7 +307,7 @@ support in its root subdirectory the following optional attributes. They
MAY also support there other read-only or read-writable attributes.
1. "trace_level" - this attribute SHOULD allow to change log level of this
driver.
driver.
This attribute SHOULD have read and write permissions for superuser and be
read-only for other users.
@@ -383,7 +383,7 @@ separated by ';' symbol.
All dev handlers supporting "add_device" command MUST support all
read-only devices' key attributes as parameters to "add_device" command
with the attributes' names as parameters' names and the attributes'
values as parameters' values.
values as parameters' values.
For example:
@@ -432,7 +432,7 @@ will add for device with name "device1" attribute
/sys/kernel/scst_tgt/devices/device_name/AttributeDX) with value
ValueDX.
6. "del_device_attribute" - if supported, this command MUST delete
6. "del_device_attribute" - if supported, this command MUST delete
device's attribute with the specified name and values. The values MUST
be specified, because in some cases attributes MAY internally be
distinguished by values. If not needed, dev handler might ignore the
@@ -792,7 +792,7 @@ be done in the following order:
- Necessary initiators deleted, if they aren't going to be moved
- LUNs updated
- Necessary initiators added or moved
3.4.6. If this target should be enabled, enable it.