OLITARGET

by Olivier Cozette

Table of content:

Goals

Using it !

Main objects

Basic use of object (i.e. main loop)

Objects and basic testing

Code coverage

Other tests

1) Goals:

Using C++ in user mode: there are already lot of C iSCSI targets in kernel mode and some other in java.
Beginning from the blank page, no code reuse (it's much funny).
Monothreading/event driven: I have done a lot of multithreading components and I just want to try!
OS agnostic: I use Windows and Linux, and I like both.
SCSI recent drafts: I whish to implement SPC4, SBC3, probably MMC6 and maybe SAM4 when it will be included in future iSCSI rfc.
Unit/Functional test: test SCSI command layer without iSCSI layer and socket like for Persistent Reservation, Unit Attention Condition and ACA. iSCSI layer need to be tested without any socket or SCSI command layer.
Having a fast iSCSI target.
Be designed to be able to have another SCSI transport layer.
So, there are lot of goals. I wish to meet some of them.

2) Using it !

First, don't hesitate to report me problems using this target, I will try to solve them.

You need at least 2GIB free on your hard drive to create a new hard drive image, if already have a disk image bigger than 2GiB it's no needed.

Under Linux, uncompress the olitarget_second_release.tar.gz and do "make all", and launch "olitarget -h olihd", "olihd" can be replaced by your disk image.

Under Windows get the "iscsi.exe" from the website. and launch "iscsi.exe -h olihd", "olihd" can be replaced by your disk image. If you want to access the iSCSI target from a remote node, you must allow iscsi.exe in your firewall rules. It's "start->config panel"->"windows firewall"->"allow program or feature through windows firewall"->"allow another program"->browse, select iscsi.exe, and click on "Add"->"Ok"

If you use Windows initiator, do "control panel" in "search control panel" type iscsi. Click on "set-up iscsi initiator". It can request that you enable iscsi initiator and/or reboot you PC, but answer "Yes" to all, and redo this clicks.

In targets (near "quick connect" button), give the IP of the target, it can be local target (127.0.0.1), remote windows target or remote Linux one.

Click quick connect. After many seconds, the target is displayed in "discovered target", if it is make as "active" click on connect.

Now, you have one more disk on your PC !

"3) Main objects (at command revision #49/third second release)

Logical Units:
- scsi_lu_task:
  - task attribute (ORDERED/SIMPLE/HEAD OF QUEUE ACA) with common task set or on task set per nexus (TST = 0/1) and all value of queue algorithm modifier (unrestricted reordering, restricting reordering).
  - ACA Condition (Qerr 0/1, TMF ONLY = 0/1, TAS = 0/1)
  - Test: ACA, task attribute and ordering against all value of TAS/Qerr/TMF ONLY/TST/queue algorithm modifier.

Unit Attention Condition. (UA_INTCLK_CTRL=0/1)
Logical Unit Reset task management.

scsi_lu_psersistent_reservation:
- PERSITENT RESERVE IN, PERSISTENT RESERVE OUT (all reservation types).
- RESERVE 6/RELEASE 6 + Logical Unit Reset (clearing them)
- Test: Persistent Reserve out and unit attention

scsi_lu_spc
- REQUEST SENSE, MODE SENSE (6/10), MODE SELECT (6/10), , INQUIRY (VPD device identifier).
- Test: mode sense, mode select, request sense.

scsi_lu_sbc
- caching mode page (WCE/RCD can be changed by mode select).
- inquiry VPD blocks limits.
- read/write 6/10/12/16, read capacity.

scsi_lu_mmc
- read/write 6/10/12/16, read capacity, test unit ready, read disc information, read toc pma atip.
report_luns_well_known_unit
- implement report luns, the well known unit (lun 0).
mmc_miniport
- access the file emulating a CD/DVD.
sbc_miniport
- access the file emulating a Hard Drive.

Target
- scsi_command_interface
  - receive commands completion callback from logical unit.
- scsi_transport_interface
  - receive new commands from transport, receive nexus connection/disconnection
- scsi_command_object
  - link logical units to transports.
  - Can dynamically add/remove a Logical Unit.
Transport
- scsi_transport_miniport_interface
  - receive command completion from target.
- iscsi_miniport
  - Implement intra session management and decode/encode scsi command before giving them to Target.
  - Test: login/logout write/read with/without ready to transfer.
Event
- scsi_event
  - receive asynchronous request
- scsi_os_api
  - asynchronous request implementation for Windows and Linux.
  - Test: waiting, socket, files.


scsi_transport_miniport_interface	scsi_command_interface	scsi_transport_interface
iscsi_miniport	scsi_command_object


scsi_lu_task	scsi_lu_task
scsi_lu_persistent_reservation	scsi_lu_persistent_reservation
scsi_lu_spc	scsi_lu_spc
report_luns_well_known_unit	scsi_lu_sbc
	sbc_miniport

scsi_lu_task	scsi_event
scsi_lu_persistent_reservation	scsi_os_api
scsi_lu_spc
scsi_lu_mmc
mmc_miniport	iscsi_listen

4) Basic use of object (i.e. main loop)

The following code will show how the multiple component are glued. In this sample, a disk is associated with LUN 2 and the iscsi listen on port 3260.

The loop with dispatch process the asynchronous event.

scsi_command_object
scsi_command_interface		scsi_transport_interface
scsi_lu_task	scsi_lu_task	scsi_transport_miniport_interface
scsi_lu_persistent_reservation	scsi_lu_persistent_reservation	iscsi_miniport
scsi_lu_spc	scsi_lu_spc	iscsi_listen
report_luns_well_known_unit	scsi_lu_sbc
	sbc_miniport

int _tmain(int argc, _TCHAR* argv[])
{
scsi_os_api event_class = scsi_os_api(2000);
scsi_command_object command =
    scsi_command_object(event_class);

sbc_miniport sbc =
    sbc_miniport(event_class, "olihd");

iscsi_listen listen =
    iscsi_listen(&event_class, 3260,
                 &command, 2048*1024);

command.register_command_miniport(&sbc, 2);

while (event_class.dispatch())
    {
   }
}

"5) Objects and basic testing

The test of iscsi_miniport_session/iscsi_listen (iSCSI SCSI transport layer) is done by giving a fake scsi_os_api object and simulate socket operation.
The receiving data on simulated socket will come from the test, and and data sent on simulated socket will be compared to the expected response.
The scsi_command_object will also be simulated to read/copy or return error given by the test.
The test of scsi_command_object (SCSI command layer) is done by giving a fake SCSI transport layer. These transport layer will give the test CDB (SCSI command data block = SCSI command) and wait for the results.

The test of scsi_lu_task

scsi_lu_task	scsi_command_interface	scsi_transport_interfacescsi_event	scsi_event
test_lu_task	test_lu	test_iscsi_event

6) Code coverage

Code coverahe done with test previously described, (run "iscsi.exe -t"), commit revision #35 windows version, done with Visual Studio.

With second release it was:

		object	Lines covered	% lines covered
		mmc_miniport scsi_lu_mmc report_luns_well_known_logical_unit scsi_lu_persistent_reservation sbc_miniport scsi_lu_sbc scsi_lu_spc iscsi_miniport_session iscsi_listen scsi_command_object scsi_os_api scsi_buffer_containner scsi_lu_task scsi_list scsi_list_container scsi_buffer_t link_list_t scsi_event	0 0 20 105 17 59 197 502 24 51 389 22 305 44 35 109 72 20	0,00 % 0,00 % 29,41 % 40,08 % 47,22 % 51,30 % 54,12 % 65,11 % 68,57 % 78,46 % 79,39 % 84,62 % 90,24 % 91,67 % 94,59 % 95,61 % 98,63 % 100,00 %

Third release is:

		object	Lines covered	% lines covered
		mmc_miniport scsi_lu_mmc sbc_miniport scsi_lu_sbc scsi_lu_spc scsi_lu_persistent_reservation iscsi_miniport_session iscsi_listen scsi_os_api report_luns_well_known_logical_unit scsi_command_object scsi_buffer_containner scsi_lu_task scsi_list_container scsi_buffer_t link_list_t scsi_event scsi_list	0 0 17 74 198 157 522 24 397 56 78 22 337 35 109 71 20 43	00,00 % 0,00 % 38,64 % 50,68 % 53,51 % 57,93 % 67,79 % 68,57 % 80,20 % 82,35 % 83,87 % 84,62 % 89,39 % 94,59 % 95,61 % 100,00 % 100,00 % 100,00 %

Callgrind result (linux) after scsi compliance test:

7) Other tests

Microsoft scsi compliance test from wlk against commit revision #33 (second release), the test have exactly the same result with olitarget running under Linux or WIndows. The tests have been done with the olitarget Windows (Windows 7) and olitarget Linux (Ubuntu 9.10 x64).

Second release results was:

SCSI Compliance Test Version 1.3.7 A
Copyright (c) 2003-2005 Microsoft Corporation

[...]

===============================================================================
Command                 Total   Pass    Warn    Fail
INQUIRY                 19      14      3       2
MODE SENSE (6)          14      14      0       0
MODE SENSE (10)         6       6       0       0
MODE SELECT (6)         14      14      0       0
MODE SELECT (10)        14      13      1       0
READ (6)                4       4       0       0
READ (10)               4       4       0       0
READ (16)               5       5       0       0
READ CAPACITY           1       1       0       0
REQUEST SENSE           3       3       0       0
RESERVE (6)             0       0       0       0
RELEASE (6)             0       0       0       0
REPORT LUNS             3       3       0       0
PERSISTENT RESERVE      28      28      0       0
MULTI-INITIATOR         9       6       1       2
===============================================================================

Third release results is:

SCSI Compliance Test Version 1.3.7 A
Copyright (c) 2003-2005 Microsoft Corporation

[...]

===============================================================================
Command                 Total   Pass    Warn    Fail
INQUIRY                 19      18      1       0
MODE SENSE (6)          14      14      0       0
MODE SENSE (10)         6       6       0       0
MODE SELECT (6)         14      13      1       0
MODE SELECT (10)        14      14      0       0
READ (6)                4       4       0       0
READ (10)               4       4       0       0
READ (16)               5       5       0       0
READ CAPACITY           1       1       0       0
REQUEST SENSE           3       3       0       0
WRITE (6)               5       5       0       0
WRITE (10)              6       6       0       0
WRITE (16)              6       6       0       0
RESERVE (6)             0       0       0       0
RELEASE (6)             0       0       0       0
REPORT LUNS             3       3       0       0
PERSISTENT RESERVE      28      28      0       0
MULTI-INITIATOR         9       9       0       0
==============================================================================

8) About me

I worked in distributed storage and systems in R&D. I have worked with both Linux and Windows at system level (multithread/network/Infiniband verbs) and kernel level (file systems, add functionalities, storage driver).

I love discovering new technologies like Virtual Storport, PCI-E MR-IOV/SR-IOV, last SCSI advancement, virtualization (hardware like VT and software), new processor instruction set and developing software (user and/or kernel). And I like to get best of these technologies to increase speed or add features to a product.

If you need to contact me, you could leave a mail at olivier.m.cozette@gmail.com or by linkedin http://www.linkedin.com/in/oliviercozette