Skip to content

Advanced testing

Jump to bottom
Uwe Seimet edited this page Nov 25, 2024 · 57 revisions

Table of Contents

Limitations of unit tests

SCSI2Pi has an extensive set of unit tests. But these tests do not fully verify whether the SCSI2Pi emulation and tools correctly handle the SCSI protocol. They also do not test the SCSI2Pi emulation and the SCSI2Pi initiator mode against each other. To run such a test you need two SCSI devices: an initiator, typically a computer, and a target like a hard drive. Initiator and target are connected by the SCSI bus hardware (the PiSCSI board), and they use bus signals to exchange status information and data.

Testing SCSI2Pi against itself

A very useful hardware setup for testing SCSI2Pi are two connected PiSCSI boards. On one of these you emulate a SCSI device with s2p, on the other you run an initiator tool, i.e. s2pdump or s2pexec. This means you are testing SCSI2Pi against itself. With such a setup, whenever something does not work as expected it must be an issue with SCSI2Pi, because no other SCSI devices are involved.
There is a drawback with this approach, though: You need two Pis and two PiSCSI boards. Wouldn't it be great if you could run these interoperability tests without any special hardware, even on a PC or Mac?

The SCSI2Pi "in-process" bus

You can actually do that! SCSI2Pi features a special bus called "in-process bus", which replaces real bus hardware for testing purposes. Essentially, the in-process bus remembers all bus signals in memory. An initiator and a target in the same process communicate via this bus like they do when running on separate computers or devices. No Pi hardware is required, because the in-process bus completely replaces it.
The SCSI2Pi initiator tools s2pdump, s2pexec and s2pproto are all prepared to use an in-process bus instead of real hardware in order to send SCSI commands and the related data.

Running in-process tests

With s2ptool (before SCSI2Pi 4.1 called in_process_test) you can run such a test. The tool creates an s2p instance and an instance of an initiator tool, e.g. s2pexec, in the same process. Both instances are connected by an in-process bus. They run against each other as if they were running on two Pis, connected via SCSI. This setup works on any platform you can compile SCSI2Pi on, i.e. also on any Linux or BSD PC, or even a Mac.
When launching s2ptool you can provide a separate set of command line options for s2p and the respective initiator tool. When running s2pctl against s2p in-process there is a regular network connection between s2p and s2pctl. With the --log-signals/-l option in log level trace you enable bus signal logging. Note that logging bus signals is very verbose.

In-process test initiator/target example

You can run s2pdump against s2p like this:

>s2ptool -c s2pdump -s "-i 0 services" -a "-I -i 0"
With -s and -a you specify the s2p and target startup options, which are identical with the options you would use on the command line. -c supports either s2pdump, s2pexec or s2pproto as the initiator client.
The output resulting from the previous example looks similar to this: 
SCSI Device Emulator and SCSI Tools SCSI2Pi (SCSI/SASI Command Execution Tool)
Version 4.1
Copyright (C) 2016-2020 GIMONS
Copyright (C) 2020-2023 Contributors to the PiSCSI project
Copyright (C) 2021-2024 Uwe Seimet
[info] Set log level to 'info'
[info] Validating: operation=ATTACH, device=0:0, type=UNDEFINED, device parameters='file=services', vendor='', product='', revision='', block size=0
[info] Executing: operation=ATTACH, device=0:0, type=UNDEFINED, device parameters='file=services', vendor='', product='', revision='', block size=0
[info] Attached SCHS 0:0
[info] +----+-----+------+-------------------------------------
[info] | ID | LUN | TYPE | IMAGE FILE
[info] +----+-----+------+-------------------------------------
[info] |  0 |   0 | SCHS | Host Services
[info] +----+-----+------+-------------------------------------
Note: No board hardware support, only client interface calls are supported
----------------------------------------
Board ID is 7
----------------------------------------
Checking SCSI target ID:LUN 0:0
Vendor:               'SCSI2Pi '
Product:              'Host Services   '
Revision:             '0410'
Device Type:          Processor
SCSI Level:           SPC-3
Response Data Format: SCSI-2
Removable:            No

Device properties for s2p property file:
device.0.type=SCHS
device.0.product_name=SCSI2Pi:Host Services:0410
device.0.mode_page.32=20:08:01:00:7c:00:11:15:2c:20
First s2p was started, followed by s2pdump. s2pdump sent a SCSI INQUIRY command to the host services device created by s2p and displayed the device information and the mode pages of the host services in property file format.

You can also run s2pexec against s2p in-process, e.g. in interactive mode. 

>s2ptool -s "-i 0 test.hds"
SCSI Device Emulator and SCSI Tools SCSI2Pi (SCSI/SASI Command Execution Tool)
Version 4.1
Copyright (C) 2016-2020 GIMONS
Copyright (C) 2020-2023 Contributors to the PiSCSI project
Copyright (C) 2021-2024 Uwe Seimet
[info] Set log level to 'info'
[info] Validating: operation=ATTACH, device=0:0, device parameters='file=test.hds'
[info] Executing: operation=ATTACH, device=0:0, device parameters='file=test.hds'
[info] Attached SCHD 0:0
[info] +----+-----+------+-------------------------------------
[info] | ID | LUN | TYPE | IMAGE FILE
[info] +----+-----+------+-------------------------------------
[info] |  0 |   0 | SCHD | /home/us/images/test.hds
[info] +----+-----+------+-------------------------------------
SCSI Device Emulator and SCSI Tools SCSI2Pi (SCSI/SASI Command Execution Tool)
Version 4.1
Copyright (C) 2023-2024 Uwe Seimet
Entering interactive mode, Ctrl-D, "exit" or "quit" to quit
s2pexec>
You can now enter SCSI commands, which are executed by s2p without any special hardware being involved. 
s2pexec>-i 0 -c 12:00:00:00:30:00
00000000  00:00:02:02:1f:00:00:00:53:43:53:49:32:50:69:20  '........SCSI2Pi '
00000010  53:43:53:49:20:48:44:20:31:36:20:4d:69:42:20:20  'SCSI HD 16 MiB  '
00000020  30:32:30:31                                      '0400'
s2pexec>-c 08:00:00:03:01:00
00000000  f8:0f:ff:0f:03:00:04:00:05:00:06:00:07:00:08:00  '................'
00000010  09:00:0a:00:0b:00:0c:00:0d:00:0e:00:0f:00:10:00  '................'
00000020  11:00:12:00:13:00:14:00:15:00:16:00:17:00:18:00  '................'
...
Settings like the target device ID and the log level are preserved between command invocations for convenience.
While s2ptool is running you can use s2pctl to send commands to the in-process s2p instance from a different terminal. 
>s2pctl -c d -i 0
This example detaches device ID 0.

In-process test network client (s2pctl) example

As an in-process test you can also run s2pctl against s2p. 

>s2ptool -c s2pctl -s "-i 5 printer" -a "--detach-all"
SCSI Device Emulator and SCSI Tools SCSI2Pi (SCSI/SASI Command Execution Tool)
Version 4.1
Copyright (C) 2016-2020 GIMONS
Copyright (C) 2020-2023 Contributors to the PiSCSI project
Copyright (C) 2021-2024 Uwe Seimet
[info] Set log level to 'info'
[info] Validating: operation=ATTACH, device=5:0, type=UNDEFINED, device parameters='file=printer', vendor='', product='', revision='', block size=0
[info] Executing: operation=ATTACH, device=5:0, type=UNDEFINED, device parameters='file=printer', vendor='', product='', revision='', block size=0
[info] Attached SCLP 5:0
[info] +----+-----+------+-------------------------------------
[info] | ID | LUN | TYPE | IMAGE FILE
[info] +----+-----+------+-------------------------------------
[info] |  5 |   0 | SCLP | SCSI Printer
[info] +----+-----+------+-------------------------------------
Note: No board hardware support, only client interface calls are supported
[info] Detached all devices
In this example s2pctl tells s2p to detach all devices, just like it can do this on the command line. When launched without a client argument list, the interactive s2pctl mode is entered and a sequence of commands can be executed.

Test scripts

The interactive modes of s2pexec and s2ptool can be used with test scripts. The console output can be compared with reference data, for instance. 

>cat script.txt
# The target ID
-i 0
# Run INQUIRY
-c 12:00:00:00:ff:00
# Read capacity
-c 25:00:00:00:00:00:00:00:00:00
# Set sector size to 512 bytes
-c 15:10:00:00:0c:00 -d 00:00:00:08:00:00:00:00:00:00:02:00
# Verify result
-c 25:00:00:00:00:00:00:00:00:00
# Set sector size back to 2048 bytes
-c 15:10:00:00:0c:00 -d 00:00:00:08:00:00:00:00:00:00:08:00
# Verify result
-c 25:00:00:00:00:00:00:00:00:00
With s2pexec you can send the commands in this script to your device: 
>s2pexec < script.txt
00000000  05:80:02:02:33:00:00:18:50:4c:45:58:54:4f:52:20  '....3...PLEXTOR '
00000010  43:44:2d:52:4f:4d:20:50:58:2d:34:30:54:53:20:20  'CD-ROM PX-40TS  '
00000020  31:2e:31:31:30:32:2f:32:31:2f:30:30:20:30:31:3a  '1.1102/21/00 01:'
00000030  31:31:20:20:20:20:20:20                          '11      '
00000000  00:00:47:c7:00:00:08:00                          '..G.....'
00000000  00:01:1f:1f:00:00:02:00                          '........'
00000000  00:00:47:c7:00:00:08:00                          '..G.....'
Or you run an in-process test, which you can do on any platform SCSI2Pi compiles on, because a Pi is not needed: 
>s2ptool -s "-i 0 test.hds" < script.txt
Since SCSI2Pi 4.1 you can tell s2p with the --script/-s option to generate a script that contains all SCSI commands and their data in a format suitable for use with s2pexec or s2ptool.
Clone this wiki locally