SCST User Space Device Handler Interface Description

3y ago
107 Views
2 Downloads
189.94 KB
22 Pages
Last View : 2d ago
Last Download : 3m ago
Upload by : Allyson Cromer
Transcription

SCST user space device handler interface descriptionVladislav BolkhovitinVersion 3.0.0Contents1 Introduction22 User space API23 IOCTL() functions23.1 SCST USER REGISTER DEVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23.2 SCST USER UNREGISTER DEVICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43.3 SCST USER SET OPTIONS/SCST USER GET OPTIONS . . . . . . . . . . . . . . .43.4 SCST USER REPLY AND GET CMD . . . . . . . . . . . . . . . . . . . . . . . . . . . .63.5 SCST USER REPLY AND GET MULTI . . . . . . . . . . . . . . . . . . . . . . . . . . .73.6 SCST USER REPLY CMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73.7 SCST USER FLUSH CACHE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.8 SCST USER DEVICE CAPACITY CHANGED . . . . . . . . . . . . . . . . . . . . . . . 103.9 SCST USER GET EXTENDED CDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.10 SCST USER PREALLOC BUFFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 SCST USER subcommands124.1 SCST USER ATTACH SESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.2 SCST USER DETACH SESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124.3 SCST USER PARSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.4 SCST USER ALLOC MEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154.5 SCST USER EXEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164.6 SCST USER ON FREE CMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.7 SCST USER ON CACHED MEM FREE . . . . . . . . . . . . . . . . . . . . . . . . . . 194.8 SCST USER TASK MGMT RECEIVED . . . . . . . . . . . . . . . . . . . . . . . . . . . 194.9 SCST USER TASK MGMT DONE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Commands processing ow example.21

1. Introduction21 IntroductionSCST user space device handler module scst user is a device handler for SCST, which provides a way toimplement in the user space complete, full feature virtual SCSI devices in the SCST environment.This document assumes that the reader is familiar with the SCST architecture and the states through whichSCSI commands go during processing in SCST. Module scst user basically only provides hooks to them.Their description could be found on the SCST web page on http://scst.sf.net.2 User space APIModule scst user provides /dev/scst user character device with the following system calls available: open() - allows to open the device and get a le handle, which will be used in all subsequent actionsuntil close() is called close() - closes le handle returned by open() poll() - allows to wait until some pending command from SCST to process is available. ioctl() - main call, which allows commands interchange with the SCST core.Device /dev/scst user could be opened in blocking or non-blocking mode using O NONBLOCKag. In the blocking mode ioctl() SCST USER REPLY GET CMD function blocks until there isa new subcommand to process. In the non-blocking mode if there are no pending subcommandsSCST USER REPLY GET CMD function returns immediately with EAGAIN error code, and the userspace device handler can use poll() call to get noti cation about new subcommands arrival. The blockingmode is the default.The module scst user API is de ned in scst user.h le.3 IOCTL() functionsThere are following IOCTL functions available. All of them has one argument. They all, exceptSCST USER REGISTER DEVICE return 0 for success or -1 in case of error, and errno is set appropriately.3.1SCST USER REGISTER DEVICESCST USER REGISTER DEVICE registers new virtual user space device. The argument is:struct scst user dev desc{aligned u64 version str;aligned u64 license str;uint8 t type;uint8 t sgv shared;

3. IOCTL() functions3uint8 t sgv disable clustered pool;int32 t sgv single alloc pages;int32 t sgv purge interval;uint8 t has own order mgmt;struct scst user opt opt;uint32 t block size;char name[SCST MAX NAME];char sgv name[SCST MAX NAME];},where: version str - protocol version, shall be DEV USER VERSION. license str - license of this module, for instance, "GPL", "GPL v2", or "Proprietary". This eldserves the same purpose as macroses EXPORT SYMBOL/EXPORT SYMBOL GPL of the Linuxkernel. You can nd more info about it, if you ask at license@scst-tgt.com e-mail address. type - SCSI type of the device. sgv shared - true, if the SGV cache for this device should be shared with other devices. False, if theSGV cache should be dedicated. sgv disable clustered pool - disable usage of clustered pool for this device. Normally, 2 inde-pendent SGV pools created and used for each device - normal and clustered. Clustered pool createsand contains SG vectors, in which coalesced paged merged (clustered) in single SG entries. This isgood for performance. But not all target drivers can use such SG vectors, plus in some cases it is moreconvenient to have a single memory pool. So, this option provides such possibility. sgv single alloc pages - if 0, then the SGV cache for this device will work in the set ofpower 2 size bu ers mode. If 0, then the SGV cache will work in the xed size bu ersmode. In this case it sets the size of each bu er in pages. See the SGV cache documentation(http://scst.sourceforge.net/sgv cache.txt) for more details. sgv purge interval - sets the SGV cache purging interval. I.e. an SG bu er will be freed if it'sunused for time t purge interval t 2*purge interval. If purge interval is 0, then the defaultinterval will be used (60 seconds). If purge interval 0, then the automatic purging will be disabled.Shrinking by the system's demand will also be disabled. has own order mgmt - set it in non-zero, if device implements own ORDERED commands man-agement, i.e. guarantees commands execution order requirements, speci ed by SAM. opt - device options, see SCST USER SET OPTIONS/SCST USER GET OPTIONS below block size - block size, shall be divisible by 512 for block devices name - name of the device sgv name - name of SGV cache for this device

3. IOCTL() functions4SCST USER REGISTER DEVICE returns registered device's handler or -1 in case of error, and errno isset appropriately.In order to unregister the device, either call SCST USER UNREGISTER DEVICE function, or close onits le descriptor.3.2SCST USER UNREGISTER DEVICESCST USER UNREGISTER DEVICE is obsolete and should not be used. Just close the device's fdinstead.3.3SCST USER SET OPTIONS/SCST USER GET OPTIONSSCST USER SET OPTIONS/SCST USER GET OPTIONS allows to set or get correspondingly various options that control various aspects of SCSI commands processing.The argument is:struct scst user opt{uint8 t parse type;uint8 t on free cmd type;uint8 t memory reuse type;uint8 t partial transfers type;uint32 t partial len;uint8 tuint8 tuint8 tuint8 tuint8 ttst;queue alg;tas;swp;d sense;uint8 t has own order mgmt;},where: parse type - de nes how the user space handler wants to process PARSE subcommand. Possiblevalues are: SCST USER PARSE STANDARD - tells SCST use standard internal parser for thisSCSI device type. SCST USER PARSE CALL - tells SCST generate SCST USER PARSE for all SCSIcommands SCST USER PARSE EXCEPTION - tells SCST generate SCST USER PARSE for unknown SCSI commands or SCSI commands that produce errors in the standard parser.

53. IOCTL() functions on free cmd type - de nes how the user space handler wants to process ON FREE CMD sub-command. Possible values are: SCST USER ON FREE CMD CALLSCST USER ON FREE CMD for all SCSI commandstellsSCSTgenerate SCST USER ON FREE CMD IGNORE - tells SCST do nothing on this event. memory reuse type - de nes how memory allocated by the user space handler for a SCSI com-mands data bu ers is then reused by the SCST core as data bu er for subsequent commands. Possiblevalues are: SCST USER MEM NO REUSE - no memory reuse is possible, for each commands theuser space handler will each time allocate a dedicated data bu er SCST USER MEM REUSE READ - memory reuse by only READ-type commands (i.e.which involve data transfer from target to initiator) is allowed. For all WRITE-type commands(i.e. which involves data transfer from initiator to target) the user space handler will each timeallocate a dedicated data bu er SCST USER MEM REUSE WRITE - memory reuse by only WRITE-type commandsis allowed. For all READ-type commands the user space handler will each time allocate a dedicateddata bu er SCST USER MEM REUSE ALL - unlimited memory reuse is possible. partial transfers type - de nes if the user space handler supports partial data transfers, whena SCSI command, which required big data transfer, is broken on several subcommands with smallerdata transfers. This allows to improve performance by simultaneous data transfers from/to remoteinitiator and to/from the underlying storage device as well as lower allocation memory requirementsfor each (sub)command. All subcommands will have the same unique value in "parent cmd h" eldand SCST USER SUBCOMMAND ag in "partial" eld of struct scst user scsi cmd exec. Thenal subcommand will also have in that eld SCST USER SUBCOMMAND FINAL ag. All thesubcommands will have the original unmodi ed CDB. Possible values are: SCST USER PARTIAL TRANSFERS NOT SUPPORTED - the partial datatransfers are not supported SCST USER PARTIAL TRANSFERS SUPPORTED ORDERED - the partialdata transfers are supported, but all the subcommands must come in order of data chunks. Couldbe used, e.g., for tape devices. SCST USER PARTIAL TRANSFERS SUPPORTED - the partial data transfers aresupported without limitations. tst, queue alg, tas, swp, d sense - set values for TST, QUEUE ALGORITHM MODIFIER, TAS,SWP and D SENSE elds from control mode page correspondingly, see SPC. has own order mgmt - true, if the user space handler has full commands execution order man-agement, i.e. guarantees commands execution order as required by SAM. False otherwise.Flags parse type and on free cmd type are designed to improve performance by eliminating contextswitches to the user space handler, when processing of the corresponding events isn't needed.

3. IOCTL() functions6Flag memory reuse type is designed to improve performance by eliminating memory allocation, preparationand then freeing each time for each commands, if the same memory will be allocated again and again. SeeSCST USER ALLOC MEM description below for more info.SCST USER SET OPTIONS should not be used from the same and the only thread, which also handlesincoming commands, otherwise there could be a "deadlock", when SCST USER SET OPTIONS waitsfor active commands nish, but nobody handles them. This "deadlock" will be resolved only when initiator,which sent those commands, aborts them after timeout.IMPORTANT! It is duty of the caller to serialize SCST USER SET OPTIONS invocations. The kernelcode does not have any locking around modifying above properties.3.4SCST USER REPLY AND GET CMDSCST USER REPLY AND GET CMD allows at one call reply on the current subcommand from SCSTand get the next one. If 0 is returned by ioctl(), SCST USER REPLY AND GET CMD returns a SCSTsubcommand in the argument, which is de ned as the following:struct scst user get cmd{uint32 t cmd h;uint32 t subcode;union {uint64 t preply;struct scst user sess sess;struct scst user scsi cmd parse parse cmd;struct scst user scsi cmd alloc mem alloc cmd;struct scst user scsi cmd exec exec cmd;struct scst user scsi on free cmd on free cmd;struct scst user on cached mem free on cached mem free;struct scst user tm tm cmd;};},where: cmd h - command handle used to identify the command in the reply. subcode - subcommand code, see 4.1 below preply - pointer to the reply data or, if 0, there is no reply. See SCST USER REPLY CMD fordescription of struct scst user reply cmd eldsOther union members contain command's speci c ehandlershallcallSCST USER REPLY AND GET CMD or SCST USER REPLY CMD function to tell SCSTthat the subcommand's processing is nished, although some subcommands don't return a value.You can see description of possible subcommands in section 4 (subcommands).

73. IOCTL() functions3.5SCST USER REPLY AND GET MULTISCST USER REPLY AND GET MULTI allows at one call reply on the multiple subcommands fromSCST and get the multiple next subcommands.Its argument is de ned as:struct scst user get multi {aligned u64 preplies;int16 t replies cnt;int16 t replies done;int16 t cmds cnt;struct scst user get cmd cmds[0];},where: preplies - pointer to array of replies with sizedescription of struct scst user reply cmd elds replies cnt - number of entries inreplies cnt . See SCST USER REPLY CMD forpreplies array. If 0, there are no replies replies done - returns how many replies were processed by SCST. If there are unprocessed replies,the user space device handler must retry the unprocessed replies. cmds cnt - on entry: number of available entries inmands in cmds arraycmds array; on exit - number of valid subcom- cmds - returned array of subcommandsReturns 0 on success or -1 in case of error, and errno is set appropriately.3.6SCST USER REPLY CMDSCST USER REPLY CMD IOCTL function allows the user space handler to return the result of a command's execution. Its argument is de ned as:struct scst user reply cmd{uint32 t cmd h;uint32 t subcode;union {int32 t result;struct scst user scsi cmd reply parse parse reply;struct scst user scsi cmd reply alloc mem alloc reply;struct scst user scsi cmd reply exec exec reply;};},

3. IOCTL() functions8where: cmd h - command handle used to identify the command in the reply. subcode - subcommand code, see 4.1Union contains the subcommand's speci c payloads:result - subcommand's result codeORstruct scst user scsi cmd reply parse{uint8 t queue type;uint8 t data direction;uint16 t cdb len;aligned i64 lba;uint32 t op flags;aligned i64 data len;int32 t bufflen;int32 t out bufflen;},where: queue type - SCSI task attribute (queue type). NOTE! In current implementation setting changingthis eld from the provided value a ects commands execution only when then produced by iSCSI-SCSTtarget. With all other target drivers, this eld is ignored. This is because for them commands queueingis set before parse() called. data direction - command's data ow direction, one of SCST DATA * constants cdb len - length of CDB lba - LBA of the command, if any op ags - commands ags,one or more scst cdb ags bits, see above.At leastSCST INFO VALID must be set for correct processing. SCST IMPLICIT HQ not implemented(yet) for single stage init target drivers (all, except iSCSI), because custom parse can reorder commandsdue to multithreaded processing. data len - command's data length. Could be di erent from bu en for commands like VERIFY,which transfer di erent amount of data, than process, or even none of them bu en - command's bu er length out bu en - command's out bu er length (for bidirectional commands)OR

3. IOCTL() functions9struct scst user scsi cmd reply alloc mem{uint64 t pbuf;},where: pbuf - pointer to command's data bu erORstruct scst user scsi cmd reply exec{int32 t resp data len;uint64 t pbuf;uint8 t reply type;uint8 t status;uint8 t sense len;aligned u64 psense buffer;},where: resp data len - length of the response data pbuf - pointer to command's data bu er. Used only when in the original SCST USER EXECsubcommand pbuf eld is 0 reply type - could be one of the following constants: SCST EXEC REPLY BACKGROUND - tells SCST send to the remote initiatorGOOD status, but the command not yet completed by the user space handler, it is being executed in the background. When it completed, the user space handler must callSCST USER REPLY CMD again with reply type SCST EXEC REPLY COMPLETED.This mode can be used only for WRITEs and with no mem reuse for them.Also in this mode SCST USER ON FREE CMD IGNORE supposed to be used.SCST USER ON FREE CMD IGNORE should be OK, because in this mode the user spacehandler knows when this memory can be reused (SCST EXEC REPLY COMPLETED time).In case if the user space handler nishes before SCST sent reply to the initiator, SCST can stillhave reference to that memory, but it is harmless, because SCST is not going to touch this memory anyhow in this processing path, because WRITEs are not sending data, so this memory canbe safely reused for other needs. SCST EXEC REPLY COMPLETED - the user space handler completed the command status - SAM status of the commands execution sense len - length of sense data in psense bu er, if any psense bu er - pointed to sense bu er

3. IOCTL() functions3.710SCST USER FLUSH CACHESCST USER FLUSH CACHE - ushes SGV cache for the corresponding virtual user space device andqueues for all cached memory bu ers corresponding SCST USER ON CACHED MEM FREE subcommands.During execution of SCST USER FLUSH CACHE at least one another thread must process all comingsubcommands, otherwise after timeout it will fail with EBUSY error.SCST USER FLUSH CACHE doesn't have any parameters.SCST USER FLUSH CACHE returns 0 on success or -1 in case of error, and errno is set appropriately.3.8SCST USER DEVICE CAPACITY CHANGEDSCST USER DEVICE CAPACITY CHANGED - queues CAPACITY DATA HAS CHANGED UnitAttention or corresponding Asynchronous Event to the corresponding virtual device. It will notify remoteinitiators, connected to the device, and allow them to automatically refresh new device size. You should useSCST USER DEVICE CAPACITY CHANGED after resize of the device.SCST USER DEVICE CAPACITY CHANGED doesn't have any parameters.SCST USER DEVICE CAPACITY CHANGED returns 0 on success or -1 in case of error, and errno isset appropriately.3.9SCST USER GET EXTENDED CDBSCST USER GET EXTENDED CDB - requests extended CDB, if CDB size is more thanSCST MAX CDB SIZE bytes. In this case SCST USER GET EXTENDED CDB returns additionalCDB data beyond SCST MAX CDB SIZE bytes.SCST USER GET EXTENDED CDB has the following arguments:struct scst user get ext cdb {uint32 t cmd h;aligned u64 ext cdb buffer;},where: cmd h - command handle used to identify the command in the reply. ext cdb bu er - pointer to bu er, where extended CDB will be copied.SCST USER GET EXTENDED CDB returns 0 on success or -1 in case of error, and errno is set appropriately.

3. IOCTL() functions3.1011SCST USER PREALLOC BUFFERSCST USER PREALLOC BUFFER - asks to preallocate a bu er.It has the following arguments:union scst user prealloc buffer {struct scst user prealloc buffer in in;struct scst user prealloc buffer out out;},where: in - provides data about bu er to preallocate out - returns information about preallocated bu erStructure scst user prealloc bu er in has the following de nition:struct scst user prealloc buffer in {aligned u64 pbuf;uint32 t bufflen;uint8 t for clust pool;},where: pbuf - pointer to the bu er bu en - size of the bu er for clust pool - if 1, then the bu er will be preallocated in the clustered pool. If 0, then the bu erwill be preallocated in the normal pool.Structure scst user prealloc bu er out has the following de nition:struct scst user prealloc buffer out {uint32 t cmd h;}where: cmd h - handle used to identify the bu er in SCST USER ON CACHED MEM FREE subcom-mand.SCST USER PREALLOC BUFFER returns 0 on success or -1 in case of error, and errno is set appropriately.

4. SCST USER subcommands124 SCST USER subcommands4.1SCST USER ATTACH SESSSCST USER ATTACH SESS noti es the user space handler that a new initiator's session is about to beattached to the device. Payload contains struct scst user sess, which is de ned 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: sess h - session's h

The module scst_user API is de ned in scst_user.h le. 3 IOCTL() functions There are following IOCTL functions aailable.v All of them has one argument. They all, except SCST_USER_REGISTER_DEVICE return 0 for success or -1 in case of error, and errno is set appro-priately. 3.1 SCST_USER_REGISTER_DEVICE

Related Documents:

8 C 01000 AT6-18F(Z) with COS Air Handler diagram Air Handler Wiring Diagrams - Table of Contents. L-2295B Air Handler Wiring Diagrams 4. L-2295B Air Handler Wiring Diagrams 5. L-2295B Air Handler Wiring Diagrams 6 DWG CREATED BY CAD618-03 TRANS L2 LABEL BLOCK TERMINAL L1 NC COMP L 1 COMP FAN PUMPPUMP L 2 L 2 L 2 L 1 VALVE FAN

User Manuals Simplified. PIONEER High Efficency Air Handler Installation Guide October 30, 2021November 1, 2021 . Home » Pioneer » PIONEER High Efficency Air Handler Installation Guide CENTRAL SPLIT AIR CONDITIONER Installation Manual HIGH-EFFICIENCY AIR HANDLER Models: DR024GHFE18HT2 DR036GHFE18HT2 DR060GHFE18HT2 - R-410A REFRIGERANT .

approved food manager certification program need not obtain a food handler card. To be accepted in place of a food handler card, a food manager certificate must be current and renewed upon expiration. Photocopies of the food handler cards and food manager training certificates should be kept at the facility to show the health inspector upon .

If the handler must leave his/her K9 in the care of non-Service personnel, he/she must ensure it is another handler or a veterinarian. The FWO handler makes the final decision to deploy a K9 (see 471 FW 1 and sections 4.1 through 4.3 of this manual). The FWO handler makes the dec

Dispense Sample (quanitative) Dispense Sample (quanitative) Photometric Measurements. MIX. Understanding liquid handler performance behavior. Managing a Volume Dispensing Device: MVS Uses and Applications for Understanding and Optimizing Liquid Handler Performance. All assays

BASIC DEVICE ATLAS 180MH / 200MH 200MH material handler with quadruple outrigger support and 2 lifting . (A 7.32i) STANDARD EqUIpMENT: Radio preparation with mute function 200MH material handler with DB* on rigid axle, double outrigger support on steering axle and 2 lifting cylinders (A7.33i) Engine: Ready for electric cooling .

BASIC DEVICE ATLAS 180MH / 200MH 180MH / 200MH material handler with quadruple outrigger support and 2 lifting . (A 5.32i / A 7.32i) STANDARD EqUIpMENT: Radio preparation with mute function 180MH / 200MH material handler with DB* on rigid axle, double outrigger support on steering axle and 2 lifting cylinders (A5.33i / A7.33i .

7 COMMERCE (Degree in Finance / Commerce) 10-11 8 ARTS/HUMANITIES (Degrees in Humanities and Social Sciences) 12-13 PROFESIONAL CAREERS AFTER 12th (PCAT) General Degree Courses available after any stream in 12th 9 LAW 14-15 10 BUSINESS MANAGEMENT 16-17 11 HOTEL MANAGEMENT 18-19 12 LIBERAL STUDIES 20 13 MASS COMMUNICATION 21 14 ECONOMICS 22