From 9b66034f3fe3e452a71bce3c84588c2a630df6be Mon Sep 17 00:00:00 2001 From: Vladislav Bolkhovitin Date: Wed, 6 May 2015 00:49:13 +0000 Subject: [PATCH] T10-PI documentation git-svn-id: http://svn.code.sf.net/p/scst/svn/trunk@6201 d57e44dd-8a1f-0410-8b47-8ef2f437770f --- scst/T10-PI | 141 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 scst/T10-PI diff --git a/scst/T10-PI b/scst/T10-PI new file mode 100644 index 000000000..28c0c8a4c --- /dev/null +++ b/scst/T10-PI @@ -0,0 +1,141 @@ +GENERAL CONSIDERATIONS +====================== + +SCST has almost full features implementation of T10-PI standard +supporting all protection modes. The only missing feature is Application +Tag mode page. A patch implementing it is welcome. + +SCST T10-PI implementation has 2 modes of operations: + +1. Computing. In this mode no protection information (PI) is stored. It +only checked upon arrival (WRITEs) and calculated from the data upon +sending (READs). Goal of this mode to provide protection against uplink, +i.e. path to initiator, corruptions. + +2. Storing. In this mode PI is stored either in a file/device as simple +array with 8 bytes entries, or inside block device using block integrity +extensions. In this mode full end-to-end protection could be +implemented. + +In both "computing" and "storing" modes PI can be checked on any stages +of commands processing: + +1. Target HW + +2. SCST + +3. Backend HW, if it supports block integrity extensions. + +Any of them or all can be independently enabled or disabled depending +from level of performance overhead and required protection. For +instance, the target HW stage is the cheapest from performance +perspective, but doesn't protect against corruptions or misdirections on +PCI bus between the target HW and system. Another example, if backend HW +supports T10-PI, no checks on other stages are generally needed, but can +be used to localize place where corruption happened. Checking on each +stage to be able to localize corruption place is the recommended by T10 +way of processing. + + +USER INTERFACE +============== + +Currently only scst_vdisk handler supports T10-PI. + +See in the main README description of SCST sysfs attributes: +dif_capabilities, dif_checks_failed, dif_mode, dif_type, +dif_static_app_tag and dif_filename. + +Examples: +--------- + +dif_mode=tgt, dif_type=1 - TGT level only check, type 1 + +dif_mode=scst, dif_type=1, dif_static_app_tag=0x4149 - + SCST level only check, type 1, static app tag 0x4149 + +dif_mode=scst|dev_store, dif_type=1, dif_filename=/var/lib/scst/dif_tags/rd1_dif.dif - + SCST level only check and storing PI data in the file + +dif_mode=scst, dif_type=2 - SCST level only check, type 2 (32-byte commands) + +dif_mode=tag|scst|dev_check|dev_store, dif_type=1 - all levels check + storing tags using block integrity extensions, type 1 + + +INTERFACE BETWEEN SCST AND TARGET DRIVERS +========================================= + +To support T10-PI struct scst_tgt_template has several new fields: +supported_dif_block_sizes, dif_supported, hw_dif_type1_supported, +hw_dif_type2_supported, hw_dif_type3_supported, hw_dif_ip_supported, +hw_dif_same_sg_layout_required. See their description in their comments +in scst.h. + +A READ-direction workflow from a target driver perspective should look +like: + +1. No extra actions until xmit_response() stage* + +2. On xmit_response() stage call scst_cmd_get_dif_sg(cmd)**. If returned +value is NULL, no further PI actions are needed. + +3. Otherwise, call scst_get_read_dif_tgt_actions(cmd) to find out what +PI actions are needed. The return value has encoded 2 types of actions: +action itself and tags checks. + +Possible actions, which could be extracted by using scst_get_dif_action(), +are: + + - SCST_DIF_ACTION_STRIP - check, then strip the protection info, if it + is OK + + - SCST_DIF_ACTION_INSERT - insert the protection info + + - SCST_DIF_ACTION_PASS_CHECK - check the protection info, then pass it + to the initiator + + - SCST_DIF_ACTION_PASS - then pass the protection information to the + initiator without checking + +Possible tags checks, which could be extracted by using +scst_get_dif_checks() are: + + - SCST_DIF_CHECK_GUARD_TAG - check the guard tags + + - SCST_DIF_CHECK_REF_TAG - check the reference tags + + - SCST_DIF_CHECK_APP_TAG - check the application tags comparing them to + the static tag set by dif_static_app_tag attribute + +4. Perform the requested PI actions and transfer PI from the returned +dif_sg together with the regular data**. + + +A WRITE-direction workflow from a target driver perspective should look +like: + +1. No extra actions until rdy_to_xfer() stage* + +2. On rdy_to_xfer() stage call scst_cmd_get_dif_sg(cmd)**. If returned +value is NULL, no further PI actions are needed. + +3. Otherwise, call scst_get_write_dif_tgt_actions(cmd) to find out what +PI actions are needed. + +4. Perform the requested PI actions and transfer PI to the returned +dif_sg together with regular data**. + + +(*) If the target driver uses custom data buffer, on this stage it must +together with data sg by scst_cmd_set_tgt_dif_sg() function also set the +corresponding PI sg. + +(**) The PI SG returned by scst_cmd_get_dif_sg() does not have the +corresponding SG-segments counter, because it is strictly bound to +number of blocks in the data SG. + + +You can find full external SCST T10-PI interface if you look in scst.h +functions with "_dif_" string in their name. They are well documented in +comments near them.