diff --git a/www/scst_pg.html b/www/scst_pg.html deleted file mode 100644 index 1cb2b2791..000000000 --- a/www/scst_pg.html +++ /dev/null @@ -1,2208 +0,0 @@ - - -
- -SCST is a SCSI target mid-level subsystem for Linux. It is designed to -provide unified, consistent interface between SCSI target drivers and -Linux kernel and simplify target drivers development as much as -possible. It has the following features:
--
Interoperability between SCST and local SCSI initiators (like sd, st) is -the additional issue that SCST is going to address (it is not -implemented yet). It is necessary, because local SCSI initiators can -change the state of the device, for example RESERVE the device, or some -of its parameters and that would be done behind SCST, which could lead -to various problems. Thus, RESERVE/RELEASE commands, locally generated -UNIT ATTENTIONs, etc. should be intercepted and processed as if local -SCSI initiators act as remote SCSI initiators connected to SCST. This -feature requires some the kernel modification. Since in the current -version it is not implemented, SCST and the target drivers are able to -work with any unpatched 2.4 kernel version.
-Interface between SCST and the target drivers is based on work, done by -University of New Hampshire Interoperability Labs (UNH IOL).
-All described below data structures and function could be found in -scst.h. The SCST's Internet page is -http://scst.sourceforge.net.
- -SCSI initiator device
-A SCSI device that originates service and task management requests to be -processed by a SCSI target device and receives device service and task -management responses from SCSI target devices.
-Think of the 'SCSI LLDD' as a BE (Back End) driver.
-SCSI target device
-A SCSI device that receives device service and task management requests -for processing and sends device service and task management responses -to SCSI initiator devices or drivers.
-Think of the 'Target Driver' as an FE (Front End) driver.
-The FE driver interfaces to the initiators (via the -storage-fabric-cloud) and also to the upper edge of the SCST. Whereas -the BE driver interfaces to the targets, i.e. disk-enclosures/JBODs/tapes etc. -and also to the bottom edge of the SCST.
-SCST session
-SCST session is the object that describes relationship between a remote -initiator and SCST via a target driver. All the commands from the remote -initiator is passed to SCST in the session. For example, for connection -oriented protocols, like iSCSI, SCST session could be mapped to the TCP -connection (as well as iSCSI session). SCST session is the close -equivalent of I_T nexus object.
-Local SCSI initiator
-A SCSI initiator that is located on the same host as SCST subsystem. -Examples are sg and st drivers.
-Remote SCSI initiator
-A SCSI initiator that is located on the remote host for SCST subsystem -and makes client connections to SCST via SCSI target drivers.
-SCSI target driver
-A Linux hardware or logical driver that acts as a SCSI target for remote -SCSI initiators, i.e. accepts remote connections, passes incoming SCSI -requests to SCST and sends SCSI responses from SCST back to their -originators.
-Device handler driver
-Also known as "device type specific driver" or "dev handler", is plugin -for SCST, which helps SCST to analyze incoming requests and determine -parameters, specific to various types of devices as well as perform some -processing. See appropriate section for details.
- --SCST accepts commands and passes them to SCSI mid-level at the same -way as SCSI high-level drivers (sg, sd, st) do. Figure 1 shows -interaction between SCST, its drivers and Linux SCSI subsystem.
-
-
-
Interaction between SCST, its drivers and Linux SCSI subsystem.
To work with SCST a target driver must register its template in SCST by -calling scst_register_target_template(). The template lets SCST know the -target driver's entry points. It is defined as the following:
- --
-struct scst_tgt_template
-{
- int sg_tablesize;
- const char name[15];
-
- unsigned unchecked_isa_dma:1;
- unsigned use_clustering:1;
-
- unsigned xmit_response_atomic:1;
- unsigned rdy_to_xfer_atomic:1;
- unsigned report_aen_atomic:1;
-
- int (* detect) (struct scst_tgt_template *tgt_template);
- int (* release)(struct scst_tgt *tgt);
-
- int (* xmit_response)(struct scst_cmd *cmd);
- int (* rdy_to_xfer)(struct scst_cmd *cmd);
-
- void (*on_free_cmd) (struct scst_cmd *cmd);
-
- void (* task_mgmt_fn_done)(struct scst_mgmt_cmd *mgmt_cmd);
- void (* report_aen)(int mgmt_fn, const uint8_t *lun, int lun_len);
-
- int (*proc_info) (char *buffer, char **start, off_t offset,
- int length, int *eof, struct scst_tgt *tgt, int inout);
-}
-
-
-Where:
--
Functions xmit_response(), rdy_to_xfer() are expected to be -non-blocking, i.e. return immediately and don't wait for actual data -transfer to finish. Blocking in such command could negatively impact on -overall system performance. If blocking is necessary, it is worth to -consider creating dedicated thread(s) in target driver, to which the -commands would be passed and which would perform blocking operations -instead of SCST. If the function allowed to sleep or not is defined by -"atomic" attribute of the cmd that can be get via -scst_cmd_atomic(), which is true, if sleeping is not allowed. In -this case, if the function requires sleeping, it can return -SCST_TGT_RES_NEED_THREAD_CTX in order to be recalled in the thread -context, where sleeping is allowed.
-Functions task_mgmt_fn_done() and report_aen() are recommended -to be non-blocking as well. Blocking there will stop all management -processing for all target drivers in the system (there is only one -management thread in the system).
-Functions xmit_response(), rdy_to_xfer() and report_aen() -can return the following error codes:
--
-As already written above, function xmit_response() should transmit -the response data and the status from the cmd parameter. Either it -should transmit the data or the status is defined by bits of the value, -returned by scst_cmd_get_tgt_resp_flags(). They are:
--
If SCST_TSC_FLAG_DATA is set, the data contained in the buffer, -returned by scst_cmd_get_buffer() (pay attention to -scst_cmd_get_use_sg() for scatter/gather) with length, returned by -scst_cmd_get_resp_data_len(). It is recommended to use -scst_get_buf_*()scst_put_buf()/ family of function instead of -direct access to the data buffers, because they hide all HIGHMEM and -SG/plain buffer issues.
-If SCST_TSC_FLAG_STATUS is set the status could be received by the -appropriate scst_cmd_get_*_status() functions (see below).
-The sense, if any, is contained in the buffer, returned by -scst_cmd_get_sense_buffer(), with length, returned by -scst_cmd_get_sense_buffer_len(). SCST always works in -autosense mode. If a low-level SCSI driver/device doesn't support -autosense mode, SCST will issue REQUEST SENSE command, if necessary. -Thus, if CHECK CONDITION established, target driver will always see -sense in the sense buffer and isn't required to request the sense -manually.
-It is possible, that SCST_TSC_FLAG_DATA is set, but -SCST_TSC_FLAG_STATUS is not set. In this case the driver should -only transmit the data, but not finish the command and transmit the -status. Function xmit_response() will be called again either to -transmit the status or data once more.
-After the response is completely sent, the target should call -scst_tgt_cmd_done() function in order to allow SCST to free the -command.
-Function xmit_response() returns one of the SCST_TGT_RES_* -constants, described above. Pay attention to "atomic" attribute of the -cmd, which can be get via scst_cmd_atomic(): it is true if the -function called in the atomic (non-sleeping) context.
- -Function scst_register_target_template() is defined as the following:
--
-int scst_register_target_template( - struct scst_tgt_template *vtt) -- -
Where:
--
Returns 0 on success or appropriate error code otherwise.
- -Function scst_register() is defined as the following:
--
-struct scst_tgt *scst_register( - struct scst_tgt_template *vtt) -- -
Where:
--
Returns target structure based on template vtt or NULL in case of error.
- -In order to unregister itself target driver should at first call -scst_unregister() for all its adapters and then call -scst_unregister_target_template() for its template.
- -Function scst_unregister() is defined as the following:
--
-void scst_unregister( - struct scst_tgt *tgt) -- -
Where:
--
Function scst_unregister_target_template() is defined as the following:
--
-void scst_unregister_target_template( - struct scst_tgt_template *vtt) -- -
Where:
--
When target driver determines that it needs to create new SCST session -(for example, by receiving new TCP connection), it should call -scst_register_session(), that is defined as the following:
--
-struct scst_session *scst_register_session( - struct scst_tgt *tgt, - int atomic, - const char *initiator_name, - void *data, - void (*result_fn) ( - struct scst_session *sess, - void *data, - int result)); -- -
Where:
--
A session creation and initialization is a complex task, which requires -sleeping state, so it can't be fully done in interrupt context. -Therefore the "bottom half" of it, if scst_register_session() is -called from atomic context, will be done in SCST thread context. In this -case scst_register_session() will return not completely initialized -session, but the target driver can supply commands to this session via -scst_rx_cmd(). Those commands processing will be delayed inside -SCST until the session initialization is finished, then their processing -will be restarted. The target driver will be notified about finish of -the session initialization by function result_fn(). On success the -target driver could do nothing, but if the initialization fails, the -target driver must ensure that no more new commands being sent or will -be sent to SCST after result_fn() returns. All already sent to SCST -commands for failed session will be returned in xmit_response() -with BUSY status. In case of failure the driver shall call -scst_unregister_session() inside result_fn(), it will NOT be -called automatically. Thus, scst_register_session() can be called -even on IRQ context.
-Session registration is illustrated on Figure 2 and Figure 3.
-
-
-
Session registration when atomic parameter is false
-
-
Session registration when atomic parameter is true
SCST session unregistration basically is the same, except that instead of -atomic parameter there is wait one.
--
-void scst_unregister_session( - struct scst_session *sess, - int wait, - void (* unreg_done_fn)( - struct scst_session *sess)) -- -
Where:
--
All outstanding commands will be finished regularly. After -scst_unregister_session() returned no new commands must be sent to -SCST via scst_rx_cmd(). Also, the caller must ensure that no -scst_rx_cmd() or scst_rx_mgmt_fn_*() is called in parallel -with scst_unregister_session().
-Function scst_unregister_session() can be called before -result_fn() of scst_register_session() called, i.e. during the -session registration/initialization.
- -The commands processing by SCST started when target driver calls -scst_rx_cmd(). This function returns SCST's command. Then the target -driver finishes the command's initialization, if necessary, for -example, storing necessary target driver specific data there, and calls -scst_cmd_init_done() telling SCST that it can start the processing. -Then SCST translates the command's LUN to local device, determines the -command's data direction and required data buffer size by calling -appropriate device handler's parse() function. Then:
--
When the command is finished by SCSI mid-level, device handler's -dev_done() is called to notify it about the command's -completion. Then in order to send the response the target's -xmit_response() is called. When the response, including data, if -any, is transmitted, the target will call scst_tgt_cmd_done() -telling SCST that it can free the command and its data buffer.
-Then during the command's deallocation device handler's and the target's -on_free_cmd() will be called in this order, if set.
-This sequence is illustrated on Figure 4. To simplify the picture, sign -"..." means SCST's waiting state for the corresponding command to -complete. During this state SCST and its drivers continue processing of -other commands, if there are any. One way arrow, for example to -xmit_response(), means that after this function returns, nothing -valuable for the current command will be done and SCST goes sleeping or -to the next command processing until corresponding event happens.
-
-
-
The commands processing flow
Additionally, before calling scst_cmd_init_done() the target driver can -set the following the command's flags or parameters:
--
Function scst_rx_cmd() creates and sends new command to SCST. Returns -the command on success or NULL otherwise. It is defined as the -following:
--
-struct scst_cmd *scst_rx_cmd( - struct scst_session *sess, - const uint8_t *lun, - int lun_len, - const uint8_t *cdb, - int cdb_len, - int atomic) -- -
Where:
--
Function scst_cmd_init_done() notifies SCST that the driver finished -its part of the command initialization, and the command is ready for -execution. It is defined as the following:
--
-void scst_cmd_init_done( - struct scst_cmd *cmd, - int pref_context) -- -
Where:
--
Function scst_rx_data() notifies SCST that the driver received all -the necessary data and the command is ready for further processing. It -is defined as the following:
--
-void scst_rx_data( - struct scst_cmd *cmd, - int status, - int pref_context) -- -
Where:
--
Parameter status can have one of the following values:
--
Function scst_tgt_cmd_done() notifies SCST that the driver sent the -data and/or response. It must not been called if there are an error and -xmit_response() returned something other, than -SCST_TGT_RES_SUCCESS. It is defined as the following:
--
-void scst_tgt_cmd_done( - struct scst_cmd *cmd) -- -
Where: -
Execution context often is a major problem in the kernel drivers -development, because many contexts, like IRQ one, greatly limit -available functionality, therefore require additional complex code in -order to pass processing to more simple context. SCST does its best to -undertake most of the context handling.
-On the initialization time SCST creates for internal command processing -as many threads as there are processors in the system or specified by -user via scst_threads module parameter. Similarly, as many tasklets -created as there are processors in the system.
-Each command can be processed in one of four contexts:
--
The target driver sets this context as pref_context parameter for -scst_cmd_init_done() and scst_rx_data(). Additionally, target's -template's xmit_response_atomic and rdy_to_xfer_atomic flags -have direct influence on the context. If one of them is false, the -corresponding function will never be called in the atomic context and, -if necessary, the command will be rescheduled to one of the SCST's -threads.
-SCST in some circumstances can change preferred context to less -restrictive one, for example, for large data buffer allocation, if -there is not enough GFP_ATOMIC memory.
- -There are the following preferred context constants:
--
There are the following task management functions supported:
--
Function scst_rx_mgmt_fn_tag() tells SCST to perform the specified -task management function, based on the command's tag. Can be used only -for SCST_ABORT_TASK.
-It is defined as the following:
--
-int scst_rx_mgmt_fn_tag( - struct scst_session *sess, - int fn, - uint32_t tag, - int atomic, - void *tgt_specific) -- -
Where:
--
Returns 0 if the command was successfully created and scheduled for -execution, error code otherwise. On success, the completion status of -the command will be reported asynchronously via task_mgmt_fn_done() -driver's callback.
- -Function scst_rx_mgmt_fn_lun() tells SCST to perform the specified -task management function, based on the LUN. Currently it can be used for -any function, except SCST_ABORT_TASK.
-It is defined as the following:
--
-int scst_rx_mgmt_fn_lun( - struct scst_session *sess, - int fn, - const uint8_t *lun, - int lun_len, - int atomic, - void *tgt_specific); -- -
Where:
--
Returns 0 if the command was successfully created and scheduled for -execution, error code otherwise. On success, the completion status of -the command will be reported asynchronously via task_mgmt_fn_done() -driver's callback.
- -Device specific drivers are plugins for SCST, which help SCST to analyze -incoming requests and determine parameters, specific to various types -of devices. Device handlers are intended for the following:
--
Device handlers performs very lightweight processing and therefore -should not considerably affect performance or CPU load. They are -considered to be part of SCST, so they could directly access any fields -in SCST's structures as well as use the corresponding functions.
-Without appropriate device handler SCST hides devices of this type from -remote initiators and returns HARDWARE ERROR sense data to any -requests to them.
- -To work with SCST a device specific driver must register itself in SCST by -calling scst_register_dev_driver(). It is defined as the following:
--
-int scst_register_dev_driver( - struct scst_dev_type *dev_type) -- -
Where:
--
The function returns 0 on success or appropriate error code otherwise.
- -Structure scst_dev_type is defined as the following:
--
-struct scst_dev_type
-{
- char name[15];
- int type;
-
- unsigned parse_atomic:1;
- unsigned exec_atomic:1;
- unsigned dev_done_atomic:1;
-
- int (*init) (struct scst_dev_type *dev_type);
- void (*release) (struct scst_dev_type *dev_type);
-
- int (*attach) (struct scst_device *dev);
- void (*detach) (struct scst_device *dev);
-
- int (*attach_tgt) (struct scst_tgt_device *tgt_dev);
- void (*detach_tgt) (struct scst_tgt_device *tgt_dev);
-
- int (*parse) (struct scst_cmd *cmd);
- int (*exec) (struct scst_cmd *cmd,
- void (*scst_cmd_done)(struct scsi_cmnd *cmd, int next_state));
- int (*dev_done) (struct scst_cmd *cmd);
- int (*task_mgmt_fn) (struct scst_mgmt_cmd *mgmt_cmd,
- struct scst_tgt_dev *tgt_dev, struct scst_cmd *cmd_to_abort);
- int (*on_free_cmd) (struct scst_cmd *cmd);
-
- int (*proc_info) (char *buffer, char **start, off_t offset,
- int length, int *eof, struct scst_dev_type *dev_type,
- int inout)
-
- struct module *module;
-}
-
-
-Where:
--
Structure scst_info_cdb is defined as the following:
--
-struct scst_info_cdb
-{
- enum scst_cdb_flags flags;
- scst_data_direction direction;
- unsigned int transfer_len;
- unsigned short cdb_len;
- const char *op_name;
-}
-
-
-Where:
--
Field cmd->data_direction, set by parse(), can have one of the -following values:
--
Device specific driver is unregistered by calling -scst_unregister_dev_driver(). It is defined as the following:
--
-void scst_unregister_dev_driver( - struct scst_dev_type *dev_type) -- -
Where:
--
-There are the following states, which a SCST command passes through -during execution and which could be returned by device handler's -parse() and dev_done() (but not all states are allowed to be -returned):
--
Target drivers must not directly access any fields in SCST's structures, -they must use only described below functions.
- --Function scst_tgt_get_tgt_specific() returns pointer to the target -driver specific data, set by scst_tgt_set_tgt_specific(). It is -defined as the following:
--
-void *scst_tgt_get_tgt_specific( - struct scst_tgt *tgt) -- -
Function scst_tgt_set_tgt_specific() stores the target driver -specific data that could be retrieved later by -byscst_tgt_get_tgt_specific(). It is defined as the following:
--
-void scst_tgt_set_tgt_specific( - struct scst_tgt *tgt, - void *val) -- -
Where:
--
Function scst_sess_get_tgt_specific() returns pointer to the target -driver specific data, set by scst_sess_set_tgt_specific(). It is -defined as the following:
--
-void *scst_sess_get_tgt_specific( - struct scst_session *sess) -- -
Function scst_sess_set_tgt_specific() stores the target driver -specific data that could be retrieved later by -byscst_sess_get_tgt_specific(). It is defined as the following:
--
-void scst_sess_set_tgt_specific( - struct scst_session *sess, - void *val) -- -
Where:
--
Function scst_cmd_atomic() returns true if the command is -being executed in the atomic context or false otherwise. It is defined -as the following:
--
-int scst_cmd_atomic( - struct scst_cmd *cmd) -- -
Where:
--
Function scst_cmd_get_session() returns the command's session. It -is defined as the following:
--
-struct scst_session *scst_cmd_get_session( - struct scst_cmd *cmd) -- -
Where:
--
Function scst_cmd_get_resp_data_len() returns the command's -response data length. It is defined as the following:
--
-unsigned int scst_cmd_get_resp_data_len( - struct scst_cmd *cmd) -- -
Where:
--
Function scst_cmd_get_tgt_resp_flags() returns the command's -response data response flags (SCST_TSC_FLAG_* constants). It is defined -as the following:
--
-int scst_cmd_get_tgt_resp_flags( - struct scst_cmd *cmd) -- -
Where:
--
Function scst_cmd_get_buffer() returns the command's data buffer. -It is defined as the following:
--
-void *scst_cmd_get_buffer( - struct scst_cmd *cmd) -- -
Where:
--
It is recommended to use scst_get_buf_*()scst_put_buf()/ family of -function instead of direct access to the data buffers, because they hide -all HIGHMEM and SG/plain buffer issues.
- -Function scst_cmd_get_bufflen() returns the command's data buffer -length. It is defined as the following:
--
-unsigned int scst_cmd_get_bufflen( - struct scst_cmd *cmd) -- -
Where:
--
It is recommended to use scst_get_buf_*()scst_put_buf()/ family of -function instead of direct access to the data buffers, because they hide -all HIGHMEM and SG/plain buffer issues.
- -Function scst_cmd_get_use_sg() returns the command's use_sg -value. Its meaning is the same as for scsi_cmnd. The function is -defined as the following:
--
-unsigned short scst_cmd_get_use_sg( - struct scst_cmd *cmd) -- -
Where:
--
It is recommended to use scst_get_buf_*()scst_put_buf()/ family of -function instead of direct access to the data buffers, because they hide -all HIGHMEM and SG/plain buffer issues.
- -Function scst_cmd_get_data_direction() returns the command's data -direction (SCST_DATA_* constants). It is defined as the following:
--
-scst_data_direction scst_cmd_get_data_direction( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_get_status() returns the status byte from -host device. It is defined as the following:
--
-uint8_t scst_cmd_get_status( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_get_masked_status() returns the status byte set -from host device by status_byte(). It is defined as the following:
--
-uint8_t scst_cmd_get_masked_status( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_get_msg_status() returns the status from host -adapter itself. It is defined as the following:
--
-uint8_t scst_cmd_get_msg_status( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_get_host_status() returns the status set by -low-level driver to indicate its status. It is defined as the following:
--
-uint16_t scst_cmd_get_host_status( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_get_driver_status() returns the status set by -SCSI mid-level. It is defined as the following:
--
-uint16_t scst_cmd_get_driver_status( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_get_sense_buffer() returns pointer to the sense -buffer. It is defined as the following:
--
-uint8_t *scst_cmd_get_sense_buffer( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_get_sense_buffer_len() returns the sense buffer -length. It is defined as the following:
--
-int scst_cmd_get_sense_buffer_len( - struct scst_cmd *cmd) -- -
Where:
--
Function scst_cmd_get_tag() returns the command's tag, set by -scst_cmd_set_tag(). It is defined as the following:
--
-uint32_t scst_cmd_get_tag( - struct scst_cmd *cmd) -- -
Function scst_cmd_set_tag() sets command's tag that could be -retrieved later by scst_cmd_get_tag(). It is defined as the -following:
--
-void scst_cmd_set_tag( - struct scst_cmd *cmd, - uint32_t tag) -- -
Where:
--
Functions scst_cmd_get_tgt_specific() and -scst_cmd_get_tgt_specific_lock() return pointer to the target -driver specific data, set by scst_cmd_set_tgt_specific() or -scst_cmd_set_tgt_specific_lock(). Both function are basically the -same, but the later one additionally takes lock, which helps to prevent -some races. See scst_find_cmd() below for details.
-They are defined as the following:
--
-void *scst_cmd_get_tgt_specific( - struct scst_cmd *cmd) -- -
-
-void *scst_cmd_get_tgt_specific_lock( - struct scst_cmd *cmd) -- -
Where:
--
Functions scst_cmd_set_tgt_specific() and -scst_cmd_set_tgt_specific_lock() store the target driver specific -data, that could be retrieved later by scst_cmd_get_tgt_specific() -or scst_cmd_get_tgt_specific_lock(). Both function are basically -the same, but the later one additionally takes lock, which helps to -prevent some races. See scst_find_cmd() below for details.
-They are defined as the following:
--
-void *scst_cmd_set_tgt_specific( - struct scst_cmd *cmd, - void *val) -- -
-
-void *scst_cmd_set_tgt_specific_lock( - struct scst_cmd *cmd, - void *val) -- -
Where:
--
Function scst_cmd_get_data_buff_alloced() returns the state of the -SCST_CMD_DATA_BUF_ALLOCED flag. It is defined as the following:
--
-int scst_cmd_get_data_buff_alloced( - struct scst_cmd *cmd) -- -
Function scst_cmd_set_data_buff_alloced() tells SCST that the data -buffer is alloced by target driver or device handler by setting the -SCST_CMD_DATA_BUF_ALLOCED flag on. Could be useful, for instance, -for iSCSI unsolicited data. It is defined as the following:
--
-void scst_cmd_set_data_buff_alloced( - struct scst_cmd *cmd) -- -
Where:
--
Function scst_cmd_set_expected() tells SCST expected data transfer -direction and its length, as supplied by remote initiator. It is defined -as the following:
--
-void scst_cmd_set_expected( - struct scst_cmd *cmd, - scst_data_direction expected_data_direction, - unsigned int expected_transfer_len) -- -
Function scst_cmd_is_expected_set() returns true, if the expected -values were set by target driver and false otherwise. It is defined as -the following:
--
-int scst_cmd_is_expected_set( - struct scst_cmd *cmd) -- -
Function scst_cmd_get_expected_data_direction() returns expected -data direction set by target driver, if any. If this value was not set, -the return value is undefined. It is defined as the following:
--
-scst_data_direction scst_cmd_get_expected_data_direction( - struct scst_cmd *cmd) -- -
Function scst_cmd_get_expected_transfer_len() returns expected -transfer length set by target driver, if any. If this value was not set, -the return value is undefined. It is defined as the following:
--
-unsigned int scst_cmd_get_expected_transfer_len( - struct scst_cmd *cmd) -- -
Where:
--
These functions are designed to simplify and unify access to the -commands data (SG vector or plain data buffer) in all possible -conditions, including HIGHMEM environment, and should be used instead of -direct access.
-Function scst_get_buf_first() starts access to the data. It is defined -as the following:
--
-int scst_get_buf_first( - struct scst_cmd *cmd, - uint8_t **buf) -- -
Where:
--
Returns the length of the chunk of data for success, 0 for the end of -data, negative error code otherwise.
-Function scst_get_buf_next() continues access to the data. It is defined -as the following:
--
-int scst_get_buf_next( - struct scst_cmd *cmd, - uint8_t **buf) -- -
Where:
--
Returns the length of the chunk of data for success, 0 for the end of -data, negative error code otherwise.
-Function scst_put_buf() tells SCST that the user of the chunk of -data, returned by scst_get_buf_first() or scst_get_buf_next(), -finished accessing the data. This function must be called for all chunks -of data, returned by scst_get_buf_first() or -scst_get_buf_next(). It is defined as the following:
--
-void scst_put_buf( - struct scst_cmd *cmd, - uint8_t *buf) -- -
Where:
--
Function scst_get_buf_count() returns the approximate higher -rounded count of data chunks that scst_get_buf_[first|next]() will -return. It is defined as the following:
--
-int scst_get_buf_count( - struct scst_cmd *cmd) -- -
Where:
--
Function scst_mgmt_cmd_get_tgt_specific() returns pointer to the -target driver specific data, set on call of scst_rx_mgmt_fn_tag() -or scst_rx_mgmt_fn_lun(). It is defined as the following:
--
-void *scst_mgmt_cmd_get_tgt_specific( - struct scst_mgmt_cmd *mcmd) -- -
Where:
--
Functions scst_mgmt_cmd_get_status() returns task management -command's completion status. It is defined as the following:
--
-void *scst_mgmt_cmd_get_status( - struct scst_mgmt_cmd *mcmd) -- -
Where:
--
The following status values are possible:
--
Function scst_find_cmd_by_tag() is designed to find SCST's command -based on the supplied tag comparing it with one that previously set by -scst_cmd_set_tag(). This value should be set by the target driver -on the command's initialization time.
-It is defined as the following:
--
-struct scst_cmd *scst_find_cmd_by_tag( - struct scst_session *sess, - uint32_t tag) -- -
Where:
--
Returns found command or NULL otherwise.
- -Function scst_find_cmd() is designed to find SCST's command. For example, -it can be used to find the command by internal serial number that was -supplied by a remote target's response.
-It is defined as the following:
--
-struct scst_cmd *scst_find_cmd( - struct scst_session *sess, - void *data, - int (*cmp_fn)(struct scst_cmd *cmd, void *data)) -- -
Where:
--
Returns found command or NULL otherwise.
-IMPORTANT
-SCST is designed in a such way that any command is always processed only -by one thread at any time, so no locking is necessary. But there is one -exception from that rule, it is scst_find_cmd() function. Since it -calls the callback over all commands of the session in the internal -lists, despite of the command's current state, there is a race -possibility accessing to target specific data pointer between -scst_cmd_set_tgt_specific() caller and cmp_fn(), which usually -calls scst_cmd_get_tgt_specific() from the different context. The -only place, where it is safe to call scst_cmd_set_tgt_specific() -without the race probability, is between scst_rx_cmd() and -scst_cmd_init_done(). Thus, if you call -scst_cmd_set_tgt_specific() only there, there is nothing to worry, -always use the functions without "lock" suffix. Otherwise, be careful -and, if necessary, use "lock" functions. In addition, cmp_fn() is -allowed to use only target specific data and forbidden to call any -SCST's functions.
- -Function scst_get_cdb_info() provides various CDB info. It is -defined as the following:
--
-int scst_get_cdb_info( - const uint8_t *cdb_p, - int dev_type, - struct scst_info_cdb *info_p) -- -
Where:
--
Returns 0 on success, -1 otherwise.
- -Function scst_to_dma_dir() translates SCST's data direction to -DMA one. It is defined as the following:
--
-int scst_to_dma_dir( - int scst_dir) -- -
Where:
--
Returns the corresponding PCI_DMA_* constant.
- -Function scst_is_cmd_local() checks if the command is handled -by SCST (i.e. locally, as, e.g., REPORT LUNS command). Intended to be -used in device handler's exec(), when the device handler wants to -perform all the commands, except ones that should be done by SCST -itself.
-It is defined as the following:
--
-int scst_is_cmd_local( - struct scst_cmd *cmd) -- -
Where:
--
Returns 1, if the command's CDB is locally handled by SCST or 0 -otherwise
- -These functions provide a way for device handlers to register a virtual -(emulated) device, which will be visible only by remote initiators. For -example, FILEIO device handler uses files on file system to makes from -them virtual remotely available SCSI disks.
-Function scst_register_virtual_device() registers a virtual device. -During the registration the device handlers functions init() and -attach() will be called, if defined. The function is defined as the -following:
--
-int scst_register_virtual_device( - struct scst_dev_type *dev_handler) -- -
Where:
--
Returns assigned to the device ID on success, or negative value otherwise.
-Function scst_unregister_virtual_device() unregisters a virtual -device. During the unregistration the device handlers functions -detach() and release() will be called, if defined. The -function is defined as the following:
--
-void scst_unregister_virtual_device( - int id) -- -
Where:
--
These functions allows to add or delete some SCST threads. For example, -if exec() function in your device handler works synchronously, i.e. -wait for job's completion, in order to prevent performance loss you -can add for SCST as many threads as there are devices serviced by your -device handler.
-Function scst_add_threads() starts requested number of threads. It -is defined as the following:
--
-int scst_add_threads( - int num) -- -
Where:
--
Returns 0 on success, error code otherwise.
-Function scst_del_threads() stops requested number of threads. It -is defined as the following:
--
-void scst_del_threads( - int num) -- -
Where:
--
Function scst_proc_get_tgt_root() returns target driver's root -entry in SCST's /proc hierarchy. The driver can create own -files/directories here, which should be deleted in the driver's -release(). It is defined as the following:
--
-struct proc_dir_entry *scst_proc_get_tgt_root( - struct scst_tgt_template *vtt) -- -
Where:
--
Returns proc_dir_entry on success, NULL otherwise.
- -Function scst_proc_get_dev_type_root() returns device handler's -root entry in SCST's /proc hierarchy. The driver can create own -files/directories here, which should be deleted in the driver's -detach() or release(). It is defined as the following:
--
-struct proc_dir_entry *scst_proc_get_dev_type_root( - struct scst_dev_type *dtt) -- -
Where:
--
Returns proc_dir_entry on success, NULL otherwise.
- - - diff --git a/www/scst_pg.pdf b/www/scst_pg.pdf deleted file mode 100644 index 80e19cd44..000000000 --- a/www/scst_pg.pdf +++ /dev/null @@ -1,4966 +0,0 @@ -%PDF-1.4 -% -5 0 obj -<< /S /GoTo /D (section.1) >> -endobj -8 0 obj -(Introduction) -endobj -9 0 obj -<< /S /GoTo /D (section.2) >> -endobj -12 0 obj -(Terms and Definitions) -endobj -13 0 obj -<< /S /GoTo /D (section.3) >> -endobj -16 0 obj -(SCST Architecture) -endobj -17 0 obj -<< /S /GoTo /D (section.4) >> -endobj -20 0 obj -(Target driver registration) -endobj -21 0 obj -<< /S /GoTo /D (subsection.4.1) >> -endobj -24 0 obj -(Structure scst\137tgt\137template) -endobj -25 0 obj -<< /S /GoTo /D (subsubsection.4.1.1) >> -endobj -28 0 obj -(More about xmit\137response\(\)) -endobj -29 0 obj -<< /S /GoTo /D (subsection.4.2) >> -endobj -32 0 obj -(Target driver registration functions) -endobj -33 0 obj -<< /S /GoTo /D (subsubsection.4.2.1) >> -endobj -36 0 obj -(scst\137register\137target\137template\(\)) -endobj -37 0 obj -<< /S /GoTo /D (subsubsection.4.2.2) >> -endobj -40 0 obj -(scst\137register\(\)) -endobj -41 0 obj -<< /S /GoTo /D (section.5) >> -endobj -44 0 obj -(Target driver unregistration) -endobj -45 0 obj -<< /S /GoTo /D (subsection.5.1) >> -endobj -48 0 obj -(scst\137unregister\(\)) -endobj -49 0 obj -<< /S /GoTo /D (subsection.5.2) >> -endobj -52 0 obj -(scst\137unregister\137target\137template\(\)) -endobj -53 0 obj -<< /S /GoTo /D (section.6) >> -endobj -56 0 obj -(SCST session registration) -endobj -57 0 obj -<< /S /GoTo /D (section.7) >> -endobj -60 0 obj -(SCST session unregistration) -endobj -61 0 obj -<< /S /GoTo /D (section.8) >> -endobj -64 0 obj -(The commands processing and interaction between SCST and its drivers) -endobj -65 0 obj -<< /S /GoTo /D (subsection.8.1) >> -endobj -68 0 obj -(The commands processing functions) -endobj -69 0 obj -<< /S /GoTo /D (subsubsection.8.1.1) >> -endobj -72 0 obj -(scst\137rx\137cmd\(\)) -endobj -73 0 obj -<< /S /GoTo /D (subsubsection.8.1.2) >> -endobj -76 0 obj -(scst\137cmd\137init\137done\(\)) -endobj -77 0 obj -<< /S /GoTo /D (subsubsection.8.1.3) >> -endobj -80 0 obj -(scst\137rx\137data\(\)) -endobj -81 0 obj -<< /S /GoTo /D (subsubsection.8.1.4) >> -endobj -84 0 obj -(scst\137tgt\137cmd\137done\(\)) -endobj -85 0 obj -<< /S /GoTo /D (subsection.8.2) >> -endobj -88 0 obj -(The commands processing context) -endobj -89 0 obj -<< /S /GoTo /D (subsubsection.8.2.1) >> -endobj -92 0 obj -(Preferred context constants) -endobj -93 0 obj -<< /S /GoTo /D (section.9) >> -endobj -96 0 obj -(Task management functions) -endobj -97 0 obj -<< /S /GoTo /D (subsection.9.1) >> -endobj -100 0 obj -(scst\137rx\137mgmt\137fn\137tag\(\)) -endobj -101 0 obj -<< /S /GoTo /D (subsection.9.2) >> -endobj -104 0 obj -(scst\137rx\137mgmt\137fn\137lun\(\)) -endobj -105 0 obj -<< /S /GoTo /D (section.10) >> -endobj -108 0 obj -(Device specific drivers \(device handlers\)) -endobj -109 0 obj -<< /S /GoTo /D (subsection.10.1) >> -endobj -112 0 obj -(Device specific driver registration) -endobj -113 0 obj -<< /S /GoTo /D (subsubsection.10.1.1) >> -endobj -116 0 obj -(scst\137register\137dev\137driver\(\)) -endobj -117 0 obj -<< /S /GoTo /D (subsubsection.10.1.2) >> -endobj -120 0 obj -(Structure scst\137dev\137type) -endobj -121 0 obj -<< /S /GoTo /D (subsection.10.2) >> -endobj -124 0 obj -(Device specific driver unregistration) -endobj -125 0 obj -<< /S /GoTo /D (section.11) >> -endobj -128 0 obj -(SCST commands' states) -endobj -129 0 obj -<< /S /GoTo /D (section.12) >> -endobj -132 0 obj -(SCST's structures manipulation functions) -endobj -133 0 obj -<< /S /GoTo /D (subsection.12.1) >> -endobj -136 0 obj -(SCST target driver manipulation functions) -endobj -137 0 obj -<< /S /GoTo /D (subsubsection.12.1.1) >> -endobj -140 0 obj -(scst\137tgt\137get\137tgt\137specific\(\) and scst\137tgt\137set\137tgt\137specific\(\)) -endobj -141 0 obj -<< /S /GoTo /D (subsection.12.2) >> -endobj -144 0 obj -(SCST session manipulation functions) -endobj -145 0 obj -<< /S /GoTo /D (subsubsection.12.2.1) >> -endobj -148 0 obj -(scst\137sess\137get\137tgt\137specific\(\) and scst\137sess\137set\137tgt\137specific\(\)) -endobj -149 0 obj -<< /S /GoTo /D (subsection.12.3) >> -endobj -152 0 obj -(SCST command manipulation functions) -endobj -153 0 obj -<< /S /GoTo /D (subsubsection.12.3.1) >> -endobj -156 0 obj -(scst\137cmd\137atomic\(\)) -endobj -157 0 obj -<< /S /GoTo /D (subsubsection.12.3.2) >> -endobj -160 0 obj -(scst\137cmd\137get\137session\(\)) -endobj -161 0 obj -<< /S /GoTo /D (subsubsection.12.3.3) >> -endobj -164 0 obj -(scst\137cmd\137get\137resp\137data\137len\(\)) -endobj -165 0 obj -<< /S /GoTo /D (subsubsection.12.3.4) >> -endobj -168 0 obj -(scst\137cmd\137get\137tgt\137resp\137flags\(\)) -endobj -169 0 obj -<< /S /GoTo /D (subsubsection.12.3.5) >> -endobj -172 0 obj -(scst\137cmd\137get\137buffer\(\)) -endobj -173 0 obj -<< /S /GoTo /D (subsubsection.12.3.6) >> -endobj -176 0 obj -(scst\137cmd\137get\137bufflen\(\)) -endobj -177 0 obj -<< /S /GoTo /D (subsubsection.12.3.7) >> -endobj -180 0 obj -(scst\137cmd\137get\137use\137sg\(\)) -endobj -181 0 obj -<< /S /GoTo /D (subsubsection.12.3.8) >> -endobj -184 0 obj -(scst\137cmd\137get\137data\137direction\(\)) -endobj -185 0 obj -<< /S /GoTo /D (subsubsection.12.3.9) >> -endobj -188 0 obj -(scst\137cmd\137get\137status\(\)) -endobj -189 0 obj -<< /S /GoTo /D (subsubsection.12.3.10) >> -endobj -192 0 obj -(scst\137cmd\137get\137masked\137status\(\)) -endobj -193 0 obj -<< /S /GoTo /D (subsubsection.12.3.11) >> -endobj -196 0 obj -(scst\137cmd\137get\137msg\137status\(\)) -endobj -197 0 obj -<< /S /GoTo /D (subsubsection.12.3.12) >> -endobj -200 0 obj -(scst\137cmd\137get\137host\137status\(\)) -endobj -201 0 obj -<< /S /GoTo /D (subsubsection.12.3.13) >> -endobj -204 0 obj -(scst\137cmd\137get\137driver\137status\(\)) -endobj -205 0 obj -<< /S /GoTo /D (subsubsection.12.3.14) >> -endobj -208 0 obj -(scst\137cmd\137get\137sense\137buffer\(\)) -endobj -209 0 obj -<< /S /GoTo /D (subsubsection.12.3.15) >> -endobj -212 0 obj -(scst\137cmd\137get\137sense\137buffer\137len\(\)) -endobj -213 0 obj -<< /S /GoTo /D (subsubsection.12.3.16) >> -endobj -216 0 obj -(scst\137cmd\137get\137tag\(\) and scst\137cmd\137set\137tag\(\)) -endobj -217 0 obj -<< /S /GoTo /D (subsubsection.12.3.17) >> -endobj -220 0 obj -(scst\137cmd\137get\137tgt\137specific\(\) and scst\137cmd\137get\137tgt\137specific\137lock\(\)) -endobj -221 0 obj -<< /S /GoTo /D (subsubsection.12.3.18) >> -endobj -224 0 obj -(scst\137cmd\137set\137tgt\137specific\(\) and scst\137cmd\137set\137tgt\137specific\137lock\(\)) -endobj -225 0 obj -<< /S /GoTo /D (subsubsection.12.3.19) >> -endobj -228 0 obj -(scst\137cmd\137get\137data\137buff\137alloced\(\) and scst\137cmd\137set\137data\137buff\137alloced\(\)) -endobj -229 0 obj -<< /S /GoTo /D (subsubsection.12.3.20) >> -endobj -232 0 obj -(scst\137cmd\137set\137expected\(\), scst\137cmd\137is\137expected\137set\(\), scst\137cmd\137get\137expected\137data\137direction\(\) and scst\137cmd\137get\137expected\137transfer\137len\(\)) -endobj -233 0 obj -<< /S /GoTo /D (subsubsection.12.3.21) >> -endobj -236 0 obj -(scst\137get\137buf\137first\(\), scst\137get\137buf\137next\(\), scst\137put\137buf\(\) and scst\137get\137buf\137count\(\)) -endobj -237 0 obj -<< /S /GoTo /D (subsection.12.4) >> -endobj -240 0 obj -(SCST task management commands manipulation functions) -endobj -241 0 obj -<< /S /GoTo /D (subsubsection.12.4.1) >> -endobj -244 0 obj -(scst\137mgmt\137cmd\137get\137tgt\137specific\(\)) -endobj -245 0 obj -<< /S /GoTo /D (subsubsection.12.4.2) >> -endobj -248 0 obj -(scst\137mgmt\137cmd\137get\137status\(\)) -endobj -249 0 obj -<< /S /GoTo /D (section.13) >> -endobj -252 0 obj -(Miscellaneous functions) -endobj -253 0 obj -<< /S /GoTo /D (subsection.13.1) >> -endobj -256 0 obj -(scst\137find\137cmd\137by\137tag\(\)) -endobj -257 0 obj -<< /S /GoTo /D (subsection.13.2) >> -endobj -260 0 obj -(scst\137find\137cmd\(\)) -endobj -261 0 obj -<< /S /GoTo /D (subsection.13.3) >> -endobj -264 0 obj -(scst\137get\137cdb\137info\(\)) -endobj -265 0 obj -<< /S /GoTo /D (subsection.13.4) >> -endobj -268 0 obj -(scst\137to\137dma\137dir\(\)) -endobj -269 0 obj -<< /S /GoTo /D (subsection.13.5) >> -endobj -272 0 obj -(scst\137is\137cmd\137local\(\)) -endobj -273 0 obj -<< /S /GoTo /D (subsection.13.6) >> -endobj -276 0 obj -(scst\137register\137virtual\137device\(\) and scst\137unregister\137virtual\137device\(\)) -endobj -277 0 obj -<< /S /GoTo /D (subsection.13.7) >> -endobj -280 0 obj -(scst\137add\137threads\(\) and scst\137del\137threads\(\)) -endobj -281 0 obj -<< /S /GoTo /D (subsection.13.8) >> -endobj -284 0 obj -(scst\137proc\137get\137tgt\137root\(\)) -endobj -285 0 obj -<< /S /GoTo /D (subsection.13.9) >> -endobj -288 0 obj -(scst\137proc\137get\137dev\137type\137root\(\)) -endobj -289 0 obj -<< /S /GoTo /D [290 0 R /Fit ] >> -endobj -315 0 obj << -/Length 1595 -/Filter /FlateDecode ->> -stream -xYKs6WVjxؤm&f589($dsKR~(z[V$Ŕ@÷5M|5] -*a(d2'%* U\Yd^|?t&JkWwEO\s0<7x1[2&ЀF$P&ap.j UXɃ'&hIU |wBwE]p1+b>)D"e`~FYM0õYNF+bb8M\ee{xST S7㐫YY|w:uTwϨ."LBD}߅7 ?z/hQGS¢MQ;ttuZcVYaq9[}}'}K?T!V»!tw'1t6AP,N Wƭ1pQ5 -*#zaMXd@J|括ӂd!h!6Ɖ'ΰonC`D2gڋ+n$+"Tf&&VEm@/=!<+ .m -Oq3ν\)&hM @\DzvU?KU? KHDXE#Mr|&ܚ侙:EQIrM@sYzфȝR¤^t[/@5?9?krI6;n-DkBexRuE@l=L-D,dh{ˌcp%$D+]uhy'N Rɗ6I % $-[N,З4#X̲-5;KaON -͗$xF! -0W8&S7Ak>bT۔LgeL5AƄUP|V3>ҟ(! jx*KpKA_\ wv -m_Nd7 谖6)qb=O®DPXpgնmO5+)kֻ -컬TDsY|h8bPN eXNmW<,}|>VDhمޙu||6,xw| @5BO'.pф#jR* h -B@z/AY,q$