From ed4d7d7f378fa17e2c7867939afd01c066bb4a79 Mon Sep 17 00:00:00 2001 From: Daniel Markstedt Date: Wed, 31 Dec 2025 14:26:36 +0100 Subject: [PATCH 1/3] improve mdoc syntax in man pages Use proper idiomatic mdoc syntax, notably removing any empty lines or trailing white spaces Explicitly set a project name to suppress the default OS label --- doc/piscsi.1 | 11 ++++------- doc/scsictl.1 | 13 +++++-------- doc/scsidump.1 | 8 ++------ doc/scsiloop.1 | 6 ++---- doc/scsimon.1 | 5 +---- 5 files changed, 14 insertions(+), 29 deletions(-) diff --git a/doc/piscsi.1 b/doc/piscsi.1 index 213b82776d..4880b8de54 100644 --- a/doc/piscsi.1 +++ b/doc/piscsi.1 @@ -1,6 +1,6 @@ .Dd December 18, 2025 .Dt PISCSI 1 -.Os +.Os PiSCSI .Sh NAME .Nm piscsi .Nd Emulates SCSI devices using the Raspberry Pi GPIO pins @@ -57,15 +57,14 @@ If the file extension is not recognized, the device type can be specified explic .Pp For example, if you want to specify an Apple-compatible HD image on ID 0, you can use the following command: sudo piscsi -ID0 /path/to/drive/hdimage.hda - +.Pp Note: PiSCSI is a fork of RaSCSI. The two cannot be run in parallel on the same system. - +.Pp Once PiSCSI starts, it will open a socket (default port is 6868) to allow external management commands. If another process is using this port, PiSCSI will terminate, since it is likely another instance of PiSCSI or RaSCSI. Once PiSCSI has initialized, the scsictl utility can be used to send commands. - +.Pp To quit PiSCSI, press Control + C. If it is running in the background, you can kill it using an INT signal. - .Sh OPTIONS .Bl -tag -width Ds .It Fl b Ar BLOCK_SIZE @@ -99,7 +98,6 @@ n is the SCSI ID number (0-7). u (0-31) is the optional LUN (logical unit). The .Pp FILE is the name of the image file to use for a SCSI mass storage device. For devices that do not support an image file (SCDP, SCLP, SCHS) the filename may have a special meaning or a dummy name can be provided. For SCDP it is a prioritized list of network interfaces with an IP address and netmask, e.g. "interface=eth0,eth1,wlan0:inet=10.10.20.1/24". For SCLP it is the print command to be used and a reservation timeout in seconds, e.g. "cmd=lp -oraw %f:timeout=60". .El - .Sh EXAMPLES Launch PiSCSI with no emulated drives attached: .Dl Nm piscsi @@ -115,7 +113,6 @@ To create an empty, 100MiB HD image, use the following command: .Pp In case the fallocate command is available a much faster alternative to the dd command is: .Dl fallocate -l 104857600 /path/to/newimage.hda - .Sh SEE ALSO .Xr scsictl 1 , .Xr scsimon 1 , diff --git a/doc/scsictl.1 b/doc/scsictl.1 index 15e39adda5..9c0860497c 100644 --- a/doc/scsictl.1 +++ b/doc/scsictl.1 @@ -1,6 +1,6 @@ .Dd December 18, 2025 .Dt SCSICTL 1 -.Os +.Os PiSCSI .Sh NAME .Nm scsictl .Nd Sends management commands to the piscsi process @@ -31,13 +31,12 @@ .Sh DESCRIPTION .Nm sends commands to the piscsi process to make configuration adjustments at runtime or to check the status of the devices. - -Either the -i or -l option should be specified at one time. Not both. - +.Pp +Either the -i or -l option should be specified at one time. Not both. +.Pp You do NOT need root privileges to use scsictl. scsictl also runs on non-Pi Linux platforms. - +.Pp Note: The command and type arguments are case insensitive. Only the first letter of the command/type is evaluated by the tool. - .Sh OPTIONS .Bl -tag -width Ds .It Fl b Ar BLOCK_SIZE @@ -143,7 +142,6 @@ Overrides the default locale for client-facing error messages. .It Fl u Ar UNIT Unit number (0-31). This will default to 0. This option is only used when there are multiple SCSI devices on a shared SCSI controller. (This is not common) .El - .Sh EXAMPLES Show a listing of all of the SCSI devices and their current status. .Dl Nm scsictl Fl l @@ -159,7 +157,6 @@ Example output: .Pp Request the PiSCSI process to attach a disk (assumed) to SCSI ID 0 with the contents of the file system image "HDIIMAGE0.HDS". .Dl Nm scsictl Fl i 0 Fl f HDIIMAGE0.HDS - .Sh SEE ALSO .Xr piscsi 1 , .Xr scsimon 1 , diff --git a/doc/scsidump.1 b/doc/scsidump.1 index 69106208f1..7fb7f3fc22 100644 --- a/doc/scsidump.1 +++ b/doc/scsidump.1 @@ -1,6 +1,6 @@ .Dd October 30, 2023 .Dt SCSIDUMP 1 -.Os +.Os PiSCSI .Sh NAME .Nm scsidump .Nd SCSI disk dumping tool for PiSCSI @@ -21,14 +21,12 @@ has two modes of operation: dump and restore. These can be used with physical st .Pp When operating in dump mode, scsidump will copy all data from a remote SCSI drive to an image on the local filesystem. If enabled, it will also generate a .properties file that can be used to more closely emulate the source drive. .Pp -If you are operating in restore mode, scsidump will copy the data from a local binary image to a remote physical SCSI drive. The remote SCSI drive MUST be writable. - +If you are operating in restore mode, scsidump will copy the data from a local binary image to a remote physical SCSI drive. The remote SCSI drive MUST be writable. .Sh NOTES .Nm requires either a direct connection (one without transceivers) or a FULLSPEC PiSCSI/RaSCSI board. .Pp If the generated drive image is intended to be used with PiSCSI, the drive image should be moved by the user to ~/images (or the location specified to the piscsi service). - .Sh OPTIONS .Bl -tag -width Ds .It Fl I Ar ID Ns Oo : Ar LUN Oc @@ -50,7 +48,6 @@ SCSI ID and optional LUN of the remote SCSI device. The remote SCSI device will .It Fl v Enable verbose logging. .El - .Sh EXAMPLES Dump Mode: [SCSI Drive] ---> [PiSCSI host] .Pp @@ -61,7 +58,6 @@ Restore Mode: [PiSCSI host] ---> [SCSI Drive] .Pp Launch scsidump to restore/upload a drive image from the local file system to SCSI ID 0 with block size 1MiB: .Dl Nm scsidump Fl r Fl t 0 Fl f ./outimage.hda Fl s 1048576 - .Sh SEE ALSO .Xr scsictl 1 , .Xr piscsi 1 , diff --git a/doc/scsiloop.1 b/doc/scsiloop.1 index 6f71a5b03f..29dc33f63c 100644 --- a/doc/scsiloop.1 +++ b/doc/scsiloop.1 @@ -1,6 +1,6 @@ .Dd December 5, 2022 .Dt SCSILOOP 1 -.Os +.Os PiSCSI .Sh NAME .Nm scsiloop .Nd Tool for testing the PiSCSI board with a loopback adapter installed @@ -26,14 +26,12 @@ The loopback connections for the DB25 connector are shown here: | 15 | C/D | 23 | DB4 | | 17 | ATN | 22 | DB2 | | 19 | SEL | 21 | DB1 | -.Ed - +.Ed .Sh OPTIONS .Bl -tag -width Ds .It Fl L Ar LOG_LEVEL The piscsi log level (trace, debug, info, warn, err, off). The default log level is 'info'. .El - .Sh SEE ALSO .Xr scsictl 1 , .Xr piscsi 1 , diff --git a/doc/scsimon.1 b/doc/scsimon.1 index 3f0adfa1ee..a5abca3a6f 100644 --- a/doc/scsimon.1 +++ b/doc/scsimon.1 @@ -1,6 +1,6 @@ .Dd December 18, 2025 .Dt SCSIMON 1 -.Os +.Os PiSCSI .Sh NAME .Nm scsimon .Nd Acts as a data capture tool for all traffic on the SCSI bus. Data is stored in a Value Change Dump (VCD) file. @@ -18,7 +18,6 @@ If the -i option is specified, scsimon will parse the provided JSON file instead The logged data is stored in files with the base name specified by output_file, or "log" if not specified. The appropriate file extension (e.g., .json or .vcd) will be appended. .Pp To quit scsimon, press Control + C. - .Sh OPTIONS .Fl i Ar input_file_json scsimon will parse the json file instead of capturing new data. If -i option is not specified, scsimon will read the gpio pins. @@ -26,13 +25,11 @@ scsimon will parse the json file instead of capturing new data. If -i option is Override the default buffer size of 1000000. .Ar output_file Base name of the output files. The file extension (ex: .json) will be appended to this file name. - .Sh EXAMPLES Make sure you've stopped the piscsi service. Then launch scsimon to capture all SCSI traffic available to the PiSCSI hardware: .Dl Nm scsimon .Pp If you're trying to capture a specific scenario, you'll want to wait to start scsimon until immediately before the scenario. - .Sh SEE ALSO .Xr scsictl 1 , .Xr piscsi 1 , From c13a6027b31d98d040c2b4f38489d5499e51d5e5 Mon Sep 17 00:00:00 2001 From: Daniel Markstedt Date: Wed, 31 Dec 2025 15:31:01 +0100 Subject: [PATCH 2/3] force man page to plain text output to 80 char width --- cpp/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cpp/Makefile b/cpp/Makefile index 56863b4e30..bc754094eb 100644 --- a/cpp/Makefile +++ b/cpp/Makefile @@ -270,7 +270,7 @@ $(MAN_PAGE_DIR)/%.1 : $(DOC_DIR)/%.1 | $(MAN_PAGE_DIR)/ $(DOC_DIR)/%_man_page.txt : $(DOC_DIR)/%.1 @echo "!! ------ THIS FILE IS AUTO_GENERATED! DO NOT MANUALLY UPDATE!!!" > $@ @echo "!! ------ The native file is $(notdir $<). Re-run 'make docs' after updating\n\n" >> $@ - man -l $< | col -bx >> $@ + MANWIDTH=80 man -l $< | col -bx >> $@ $(SYSTEMD_CONF) : $(OS_FILES)/$(notdir $(SYSTEMD_CONF)) @echo "-- Copying $@" From 28a4e467bd0888704d600fc95febbd8d3d76807e Mon Sep 17 00:00:00 2001 From: Daniel Markstedt Date: Wed, 31 Dec 2025 15:44:10 +0100 Subject: [PATCH 3/3] regenerate plain test man pages --- doc/piscsi_man_page.txt | 218 ++++++++++++++++++++---------------- doc/scsictl_man_page.txt | 226 +++++++++++++++++++------------------- doc/scsidump_man_page.txt | 105 +++++++++--------- doc/scsiloop_man_page.txt | 42 +++---- doc/scsimon_man_page.txt | 44 +++++--- 5 files changed, 341 insertions(+), 294 deletions(-) diff --git a/doc/piscsi_man_page.txt b/doc/piscsi_man_page.txt index 4816dfb761..d46890ab3c 100644 --- a/doc/piscsi_man_page.txt +++ b/doc/piscsi_man_page.txt @@ -1,151 +1,175 @@ !! ------ THIS FILE IS AUTO_GENERATED! DO NOT MANUALLY UPDATE!!! -!! ------ The native file is piscsi.1. Re-run 'make docs' after updating\n\n -piscsi(1) General Commands Manual piscsi(1) +!! ------ The native file is piscsi.1. Re-run 'make docs' after updating + + +PISCSI(1) General Commands Manual PISCSI(1) NAME - piscsi - Emulates SCSI devices using the Raspberry Pi GPIO pins + piscsi — Emulates SCSI devices using the Raspberry Pi GPIO pins SYNOPSIS - piscsi [-F FOLDER] [-L LOG_LEVEL[:ID:[LUN]]] [-P ACCESS_TOKEN_FILE] [-R - SCAN_DEPTH] [-h] [-n VENDOR:PRODUCT:REVISION] [-p PORT] [-r RE‐ - SERVED_IDS] [-n TYPE] [-v] [-z LOCALE] [-IDn:[u] FILE] [-HDn[:u] - FILE]... + piscsi [-b BLOCK_SIZE] [-F FOLDER] [-L LOG_LEVEL[: ID[: LUN]]] + [-n VENDOR:PRODUCT:REVISION] [-P ACCESS_TOKEN_FILE] [-p PORT] + [-R SCAN_DEPTH] [-r RESERVED_IDS] [-s MICROSECONDS] [-t TYPE] + [-z LOCALE] [-IDn[:u] FILE] [-HDn[:u] FILE ...] + piscsi [-h] + piscsi [-v] DESCRIPTION piscsi emulates SCSI devices using the Raspberry Pi GPIO pins. - In the arguments to PiSCSI, one or more SCSI (-IDn[:u]) devices can be - specified. The number (n) after the ID or HD identifier specifies the - ID number for that device. The optional number (u) specifies the LUN - (logical unit) for that device. The default LUN is 0. For SCSI: The ID - is limited from 0-7. However, typically SCSI ID 7 is reserved for the + In the arguments to PiSCSI, one or more SCSI (-IDn[:u]) devices can be + specified. The number (n) after the ID or HD identifier specifies the + ID number for that device. The optional number (u) specifies the LUN + (logical unit) for that device. The default LUN is 0. For SCSI: The ID + is limited from 0-7. However, typically SCSI ID 7 is reserved for the "initiator" (the host computer). The LUN is limited from 0-31. - PiSCSI will determine the type of device based upon the file extension + PiSCSI will determine the type of device based upon the file extension of the FILE argument. - hd1: SCSI Hard Disk image (generic, non-removable, SCSI-1) - hds: SCSI Hard Disk image (generic, non-removable) - hdr: SCSI Hard Disk image (generic, removable) - hdn: SCSI Hard Disk image (NEC compatible - only used with PC-98 + hds: Hard Disk image (generic, non-removable) + hd1: Hard Disk image (generic, non-removable, SCSI-1 compatibility + mode) + hdr: Hard Disk image (generic, removable) + hdn: Hard Disk image (NEC compatible - only used with PC-98 comput‐ + ers) + hdi: Hard Disk image (Anex86 proprietary - only used with PC-98 com‐ + puters) + nhd: Hard Disk image (T98Next proprietary - only used with PC-98 computers) - hdi: SCSI Hard Disk image (Anex86 proprietary - only used with - PC-98 computers) - nhd: SCSI Hard Disk image (T98Next proprietary - only used with - PC-98 computers) - hda: SCSI Hard Disk image (Apple compatible - typically used with - Macintosh computers) - mos: SCSI Magneto-Optical image (generic - typically used with - NeXT, X68000, etc.) - iso: SCSI CD-ROM or DVD-ROM image (ISO 9660 image) - is1: SCSI CD-ROM or DVD-ROM image (ISO 9660 image, SCSI-1) - - For example, if you want to specify an Apple-compatible HD image on ID + hda: Hard Disk image (Apple compatible - typically used with Macin‐ + tosh computers) + mos: Magneto-Optical image (generic - typically used with NeXT, + X68000, etc.) + iso: CD-ROM or DVD-ROM image (ISO 9660 image) + is1: CD-ROM or DVD-ROM image (ISO 9660 image, SCSI-1 compatibility + mode) + tap: Tape image (raw tape image containing non-block data) + tar: Tape archive (tape block data in tar format) + + If the file extension is not recognized, the device type can be speci‐ + fied explicitly using the -t option and a four letter code. + SCCD: SCSI CD-ROM (generic CD-ROM or DVD-ROM drive) + SCDP: SCSI DaynaPort (DaynaPort compatible network adapter) + SCHD: SCSI Hard Disk (generic, non-removable) + SCHS: SCSI Host Services (used for special host services) + SCLP: SCSI Printer (generic line printer) + SCMO: SCSI Magneto-Optical Drive (generic MO drive) + SCRM: SCSI Removable Hard Disk (generic, removable) + SCTP: SCSI Tape Drive (generic tape, or streamer, drive) + + For example, if you want to specify an Apple-compatible HD image on ID 0, you can use the following command: sudo piscsi -ID0 /path/to/drive/hdimage.hda - Note: PiSCSI is a fork of RaSCSI. The two cannot be run in parallel on + Note: PiSCSI is a fork of RaSCSI. The two cannot be run in parallel on the same system. - Once PiSCSI starts, it will open a socket (default port is 6868) to al‐ - low external management commands. If another process is using this - port, PiSCSI will terminate, since it is likely another instance of - PiSCSI or RaSCSI. Once PiSCSI has initialized, the scsictl utility can + Once PiSCSI starts, it will open a socket (default port is 6868) to al‐ + low external management commands. If another process is using this + port, PiSCSI will terminate, since it is likely another instance of + PiSCSI or RaSCSI. Once PiSCSI has initialized, the scsictl utility can be used to send commands. - To quit PiSCSI, press Control + C. If it is running in the background, + To quit PiSCSI, press Control + C. If it is running in the background, you can kill it using an INT signal. OPTIONS -b BLOCK_SIZE - The optional block size, either 512, 1024, 2048 or 4096 bytes. - Default size is 512 bytes. + The optional block size, either 512, 1024, 2048 or 4096 bytes. + Default size is 512 bytes. -F FOLDER - The default folder for image files. For files in this folder no - absolute path needs to be specified. The initial default folder - is '~/images'. + The default folder for image files. For files in this folder no + absolute path needs to be specified. The initial default folder + is '~/images'. - -L LOG_LEVEL[:ID:[LUN]] - The piscsi log level (trace, debug, info, warning, error, off). - The default log level is 'info' for all devices unless a partic‐ - ular device ID and an optional LUN was provided. + -h Show a help page. - -P ACCESS_TOKEN_FILE - Enable authentication and read the access token from the speci‐ - fied file. The access token file must be owned by root and must - be readable by root only. - - -R SCAN_DEPTH - Scan for image files recursively, up to a depth of SCAN_DEPTH. - Depth 0 means to ignore any folders within the default image - filder. Be careful when using this option with many sub-folders - in the default image folder. The default depth is 1. - - -h Show a help page. + -L LOG_LEVEL[: ID[: LUN]] + The piscsi log level (trace, debug, info, warning, error, off). + The default log level is 'info' for all devices unless a partic‐ + ular device ID and an optional LUN was provided. -n VENDOR:PRODUCT:REVISION - Set the vendor, product and revision for the device, to be re‐ - turned with the INQUIRY data. A complete set of name components - must be provided. VENDOR may have up to 8, PRODUCT up to 16, RE‐ - VISION up to 4 characters. Padding with blanks to the maxium - length is automatically applied. Once set the name of a device - cannot be changed. + Set the vendor, product and revision for the device, to be re‐ + turned with the INQUIRY data. A complete set of name components + must be provided. VENDOR may have up to 8, PRODUCT up to 16, RE‐ + VISION up to 4 characters. Padding with blanks to the maxium + length is automatically applied. Once set the name of a device + cannot be changed. + + -P ACCESS_TOKEN_FILE + Enable authentication and read the access token from the speci‐ + fied file. The access token file must be owned by root and must + be readable by root only. -p PORT - The piscsi server port, default is 6868. + The piscsi server port, default is 6868. - -r RESERVED_IDS - Comma-separated list of IDs to reserve. Pass an empty list in - order to not reserve anything. -p TYPE The optional case-insen‐ - sitive device type (SAHD, SCHD, SCRM, SCCD, SCMO, SCBR, SCDP, - SCLP, SCHS). If no type is specified for devices that support an - image file, piscsi tries to derive the type from the file exten‐ - sion. + -R SCAN_DEPTH + Scan for image files recursively, up to a depth of SCAN_DEPTH. + Depth 0 means to ignore any folders within the default image + folder. Be careful when using this option with many sub-folders + in the default image folder. The default depth is 1. - -v Display the piscsi version. + -r RESERVED_IDS + Comma-separated list of IDs to reserve. Pass an empty list in + order to not reserve anything. - -z LOCALE - Overrides the default locale for client-faces error messages. - The client can override the locale. + -s MICROSECONDS + Minimum execution time for SCSI commands in microseconds. De‐ + fault is 50. Higher values may be needed for some older SCSI + initiators to work properly. - -IDn[:u] FILE - n is the SCSI ID number (0-7). u (0-31) is the optional LUN - (logical unit). The default LUN is 0. + -t TYPE + The optional case-insensitive device type (see list of type + codes above). If no type is specified for devices that support + an image file, piscsi tries to derive the type from the file ex‐ + tension. - FILE is the name of the image file to use for the SCSI device. - For devices that do not support an image file (SCBR, SCDP, SCLP, - SCHS) the filename may have a special meaning or a dummy name - can be provided. For SCBR and SCDP it is an optioinal priori‐ - tized list of network interfaces, an optional IP address and - netmask, e.g. "interface=eth0,eth1,wlan0:inet=10.10.20.1/24". - For SCLP it is the print command to be used and a reservation - timeout in seconds, e.g. "cmd=lp -oraw %f:timeout=60". + -v Display the piscsi version. - FILE is the name of the image file to use for the SCSI device. + -z LOCALE + Sets the default locale for client-facing error messages. The + client can override the locale. + + -ID n[: u] FILE + n is the SCSI ID number (0-7). u (0-31) is the optional LUN + (logical unit). The default LUN is 0. + + FILE is the name of the image file to use for a SCSI mass stor‐ + age device. For devices that do not support an image file (SCDP, + SCLP, SCHS) the filename may have a special meaning or a dummy + name can be provided. For SCDP it is a prioritized list of net‐ + work interfaces with an IP address and netmask, e.g. "inter‐ + face=eth0,eth1,wlan0:inet=10.10.20.1/24". For SCLP it is the + print command to be used and a reservation timeout in seconds, + e.g. "cmd=lp -oraw %f:timeout=60". EXAMPLES Launch PiSCSI with no emulated drives attached: - piscsi + piscsi - Launch PiSCSI with an Apple hard drive image as ID 0 and a CD-ROM as ID + Launch PiSCSI with an Apple hard drive image as ID 0 and a CD-ROM as ID 2 - piscsi -ID0 /path/to/harddrive.hda -ID2 /path/to/cdimage.iso + piscsi -ID0 /path/to/harddrive.hda -ID2 /path/to/cdimage.iso - Launch PiSCSI with a removable SCSI drive image as ID 0 and the raw de‐ - vice file /dev/hdb (e.g. a USB stick) and a DaynaPort network adapter - as ID 6: - piscsi -ID0 -t scrm /dev/hdb -ID6 -t scdp daynaport + Launch PiSCSI with a removable SCSI drive image as ID 0 and the raw de‐ + vice file /dev/hdb (e.g. a USB stick) and a DaynaPort network adapter as + ID 6: + piscsi -ID0 -t scrm /dev/hdb -ID6 -t scdp daynaport To create an empty, 100MiB HD image, use the following command: - dd if=/dev/zero of=/path/to/newimage.hda bs=512 count=204800 + dd if=/dev/zero of=/path/to/newimage.hda bs=512 count=204800 - In case the fallocate command is available a much faster alternative to + In case the fallocate command is available a much faster alternative to the dd command is: - fallocate -l 104857600 /path/to/newimage.hda + fallocate -l 104857600 /path/to/newimage.hda SEE ALSO scsictl(1), scsimon(1), scsidump(1) Full documentation is available at: - piscsi(1) +PiSCSI December 18, 2025 PISCSI(1) diff --git a/doc/scsictl_man_page.txt b/doc/scsictl_man_page.txt index f98b7208bd..46e1749980 100644 --- a/doc/scsictl_man_page.txt +++ b/doc/scsictl_man_page.txt @@ -1,175 +1,179 @@ !! ------ THIS FILE IS AUTO_GENERATED! DO NOT MANUALLY UPDATE!!! -!! ------ The native file is scsictl.1. Re-run 'make docs' after updating\n\n -piscsi(1) General Commands Manual piscsi(1) +!! ------ The native file is scsictl.1. Re-run 'make docs' after updating + + +SCSICTL(1) General Commands Manual SCSICTL(1) NAME - scsictl - Sends management commands to the piscsi process + scsictl — Sends management commands to the piscsi process SYNOPSIS - scsictl -e | -l | -m | -o | -v | -D | -I | -L | -O | -P | -S | -T | -V - | -X | [-C FILENAME:FILESIZE] | [-E FILENAME] | [-F IMAGE_FOLDER] | [-R - CURRENT_NAME:NEW_NAME] | [-c CMD] | [-f FILE|PARAM] | [-g LOG_LEVEL] | - [-h HOST] | [-i ID[:LUN]] | [-n NAME] | [-p PORT] | [-r RESERVED_IDS] | - [-s [FOLDER_PATTERN:FILE_PATTERN:OPERATIONS]] | [-t TYPE] | [-x CUR‐ - RENT_NAME:NEW_NAME] | [-z LOCALE] + scsictl [-b BLOCK_SIZE] [-C FILENAME:FILESIZE] [-c CMD] [-d FILENAME] + [-E FILENAME] [-F IMAGE_FOLDER] [-f FILE|PARAM] [-h HOST] + [-i ID[: LUN]] [-L LOG_LEVEL] [-n NAME] [-P] [-p PORT] + [-R CURRENT_NAME:NEW_NAME] [-r RESERVED_IDS] + [-s [FOLDER_PATTERN:FILE_PATTERN:OPERATIONS]] [-t TYPE] + [-u UNIT] [-x CURRENT_NAME:NEW_NAME] [-z LOCALE] + scsictl [-D | -e | -I | -l | -m | -N | -O | -o | -S | -T | -V | -v | -X] DESCRIPTION - scsictl sends commands to the piscsi process to make configuration ad‐ + scsictl sends commands to the piscsi process to make configuration ad‐ justments at runtime or to check the status of the devices. Either the -i or -l option should be specified at one time. Not both. - You do NOT need root privileges to use scsictl. scsictl also runs on + You do NOT need root privileges to use scsictl. scsictl also runs on non-Pi Linux platforms. - Note: The command and type arguments are case insensitive. Only the + Note: The command and type arguments are case insensitive. Only the first letter of the command/type is evaluated by the tool. OPTIONS + -b BLOCK_SIZE + The optional block size, either 512, 1024, 2048 or 4096 bytes. + The default size is 512 bytes. + -C FILENAME:FILESIZE - Create an image file in the default image folder with the speci‐ - fied name and size in bytes. + Create an image file in the default image folder with the speci‐ + fied name and size in bytes. + + -c CMD Command is the operation being requested. Options are: + • a(ttach): Attach disk + • d(etach): Detach disk + • i(nsert): Insert media (removable media devices only) + • e(ject): Eject media (removable media devices only) + • p(rotect): Write protect the medium (not for CD-ROMs, which + are always read-only) + • u(nprotect): Remove write protection from the medium (not + for CD-ROMs, which are always read-only) + • s(how): Display device information - -D Detach all devices. + eject, protect and unprotect are idempotent. + + -D Detach all devices. + + -d FILENAME + Delete an image file in the default image folder. -E FILENAME - Display information on an image file. + Display information on an image file. + + -e List all images files in the default image folder. -F IMAGE_FOLDER - Set the default image folder. + Set the default image folder. - -I Gets the list of reserved device IDs. + -f FILE|PARAM + Device-specific: Either a path to a disk image file, or a para‐ + meter for a non-disk device. See the piscsi(1) man page for per‐ + mitted file types. + + -I Gets the list of reserved device IDs. + + -i ID[: LUN] + The SCSI ID and optional LUN that you want to control. + (0-7:0-31) -L LOG_LEVEL - Set the piscsi log level (trace, debug, info, warning, error, - off). + Set the piscsi log level (trace, debug, info, warning, error, + off). + + -l List all of the devices that are currently being emulated by + PiSCSI, as well as their current status. -h HOST - The piscsi host to connect to, default is 'localhost'. + The piscsi host to connect to, default is 'localhost'. - -e List all images files in the default image folder. + -m List all file extensions recognized by PiSCSI and the device + types they map to. - -N Lists all available network interfaces provided that they are - up. + -N Lists all available network interfaces provided that they are + up. - -O Display the available piscsi server log levels and the current - log level. + -n VENDOR:PRODUCT:REVISION + The vendor, product and revision for the device, to be returned + with the INQUIRY data. A complete set of name components must be + provided. VENDOR may have up to 8, PRODUCT up to 16, REVISION up + to 4 characters. Padding with blanks to the maxium length is au‐ + tomatically applied. Once set the name of a device cannot be + changed. - -P Prompt for the access token in case piscsi requires authentica‐ - tion. + -O Display the available piscsi server log levels and the current + log level. - -l List all of the devices that are currently being emulated by - PiSCSI, as well as their current status. + -o Display operation meta data information. - -m List all file extensions recognized by PiSCSI and the device - types they map to. + -P Prompt for the access token in case piscsi requires authentica‐ + tion. - -o Display operation meta data information. + -p PORT + The piscsi port to connect to, default is 6868. -R CURRENT_NAME:NEW_NAME - Rename an image file in the default image folder. - - -p PORT - The piscsi port to connect to, default is 6868. + Rename an image file in the default image folder. -r RESERVED_IDS - Comma-separated list of IDs to reserve. Pass an empty list in - order to not reserve anything. + Comma-separated list of IDs to reserve. Pass an empty list in + order to not reserve anything. - -s [FOLDER_PATTERN:FILE_PATTERN:OPERATIONS] - Display server-side settings like available images or supported - device types. + -S Display statistics. - -S Display statistics. + -s [FOLDER_PATTERN:FILE_PATTERN:OPERATIONS] + Display server-side settings like available images or supported + device types. - -T Display all device types and their properties. + -T Display all device types and their properties. - -v Display the piscsi server version. + -t TYPE + Specifies the device type. This type overrides the type derived + from the file extension of the specified image. See the + piscsi(1) man page for the available device type codes, or use a + shorthand (only the first letter is required): + • cd: CD-ROM + • daynaport: DaynaPort Network Adapter + • hd: Hard Disk + • services: Host Services + • printer: Printer + • mo: Magneto-Optical Drive + • removable: Removable Hard Disk + • tape: Tape Drive - -V Display the scsictl version. + -V Display the scsictl version. - -X Shut down the piscsi process. + -v Display the piscsi server version. - -d FILENAME - Delete an image file in the default image folder. + -X Shut down the piscsi process. -x CURRENT_NAME:NEW_NAME - Copy an image file in the default image folder. + Copy an image file in the default image folder. -z LOCALE - Overrides the default locale for client-facing error messages. - - -i ID[:LUN] - The SCSI ID and optional LUN that you want to control. - (0-7:0-31) - - -c CMD Command is the operation being requested. Options are: - a(ttach): Attach disk - d(etach): Detach disk - i(nsert): Insert media (removable media devices only) - e(ject): Eject media (removable media devices only) - p(rotect): Write protect the medium (not for CD-ROMs, which - are always read-only) - u(nprotect): Remove write protection from the medium (not for - CD-ROMs, which are always read-only) - s(how): Display device information - - eject, protect and unprotect are idempotent. - - -b BLOCK_SIZE - The optional block size, either 512, 1024, 2048 or 4096 bytes. - The default size is 512 bytes. - - -f FILE|PARAM - Device-specific: Either a path to a disk image file, or a param‐ - eter for a non-disk device. See the piscsi(1) man page for per‐ - mitted file types. - - -t TYPE - Specifies the device type. This type overrides the type derived - from the file extension of the specified image. See the - piscsi(1) man page for the available device types. For some - types there are shortcuts (only the first letter is required): - hd: SCSI hard disk drive - rm: SCSI removable media drive - cd: CD-ROM - mo: Magneto-Optical disk - lp: SCSI printer - bridge: Bridge device (Only applicable to the Sharp X68000) - daynaport: DaynaPort network adapter - services: Host services device - - -n VENDOR:PRODUCT:REVISION - The vendor, product and revision for the device, to be returned - with the INQUIRY data. A complete set of name components must be - provided. VENDOR may have up to 8, PRODUCT up to 16, REVISION up - to 4 characters. Padding with blanks to the maxium length is au‐ - tomatically applied. Once set the name of a device cannot be - changed. + Overrides the default locale for client-facing error messages. -u UNIT - Unit number (0-31). This will default to 0. This option is only - used when there are multiple SCSI devices on a shared SCSI con‐ - troller. (This is not common) + Unit number (0-31). This will default to 0. This option is only + used when there are multiple SCSI devices on a shared SCSI con‐ + troller. (This is not common) EXAMPLES Show a listing of all of the SCSI devices and their current status. - scsictl -l + scsictl -l Example output: - +----+-----+------+------------------------------------- - | ID | LUN | TYPE | IMAGE FILE - +----+-----+------+------------------------------------- - | 0 | 1 | SCHD | /home/pi/harddisk.hda - +----+-----+------+------------------------------------- - Request the PiSCSI process to attach a disk (assumed) to SCSI ID 0 with + +----+-----+------+------------------------------------- + | ID | LUN | TYPE | IMAGE FILE + +----+-----+------+------------------------------------- + | 0 | 1 | SCHD | /home/pi/harddisk.hda + +----+-----+------+------------------------------------- + + Request the PiSCSI process to attach a disk (assumed) to SCSI ID 0 with the contents of the file system image "HDIIMAGE0.HDS". - scsictl -i 0 -f HDIIMAGE0.HDS + scsictl -i -0 -f -HDIIMAGE0.HDS SEE ALSO piscsi(1), scsimon(1), scsidump(1) Full documentation is available at: - piscsi(1) +PiSCSI December 18, 2025 SCSICTL(1) diff --git a/doc/scsidump_man_page.txt b/doc/scsidump_man_page.txt index 70d6338960..a1f9b4a7b5 100644 --- a/doc/scsidump_man_page.txt +++ b/doc/scsidump_man_page.txt @@ -1,83 +1,88 @@ !! ------ THIS FILE IS AUTO_GENERATED! DO NOT MANUALLY UPDATE!!! -!! ------ The native file is scsidump.1. Re-run 'make docs' after updating\n\n -scsidump(1) General Commands Manual scsidump(1) +!! ------ The native file is scsidump.1. Re-run 'make docs' after updating + + +SCSIDUMP(1) General Commands Manual SCSIDUMP(1) NAME - scsidump - SCSI disk dumping tool for PiSCSI + scsidump — SCSI disk dumping tool for PiSCSI SYNOPSIS - scsidump -t ID[:LUN] [-i BID] -f FILE [-s BUFFER_SIZE] [-r] [-v] [-p] - [-I] ID[:LUN] [-S] + scsidump [-I ID[: LUN]] [-i BID] -f FILE [-p] [-s BUFFER_SIZE] [-r] [-S] + -t ID[: LUN] [-v] DESCRIPTION - scsidump has two modes of operation: dump and restore. These can be - used with physical storage media, including hard drives and magneto op‐ - tical drives. Dump mode can be used with read-only media such as CD/DVD - drives. - - When operating in dump mode, scsidump will copy all data from a remote - SCSI drive to an image on the local filesystem. If enabled, it will - also generate a .properties file that can be used to more closely emu‐ - late the source drive. - - If you are operating in restore mode, scsidump will copy the data from - a local binary image to a remote physical SCSI drive. The remote SCSI + scsidump has two modes of operation: dump and restore. These can be used + with physical storage media, including hard drives and magneto optical + drives. Dump mode can be used with read-only media such as CD/DVD dri‐ + ves. + + When operating in dump mode, scsidump will copy all data from a remote + SCSI drive to an image on the local filesystem. If enabled, it will also + generate a .properties file that can be used to more closely emulate the + source drive. + + If you are operating in restore mode, scsidump will copy the data from a + local binary image to a remote physical SCSI drive. The remote SCSI drive MUST be writable. NOTES - scsidump requires either a direct connection (one without transceivers) + scsidump requires either a direct connection (one without transceivers) or a FULLSPEC PiSCSI/RaSCSI board. - If the generated drive image is intended to be used with PiSCSI, the - drive image should be moved by the user to ~/images (or the location + If the generated drive image is intended to be used with PiSCSI, the + drive image should be moved by the user to ~/images (or the location specified to the piscsi service). OPTIONS - -t ID[:LUN] - SCSI ID and optional LUN of the remote SCSI device. The remote - SCSI device will be functioning as the "Target" device. + -I ID[: LUN] + Display INQUIRY data of ID[:LUN]. - -i BID SCSI ID of the PiSCSI device. If not specified, the PiSCSI de‐ - vice will use ID 7. The PiSCSI host will be functioning as the - "Initiator" device. + -i BID SCSI ID of the PiSCSI device. If not specified, the PiSCSI de‐ + vice will use ID 7. The PiSCSI host will be functioning as the + "Initiator" device. -f FILE - Path to the dump file. + Path to the dump file. - -s BUFFER_SIZE - The transfer buffer size, specified in bytes. Default is 1 MiB. - This is specified in bytes with a minimum value of 65536 (64 - KiB). + -p Generate a .properties file that is compatible with the PiSCSI + web interface. The output filename will match the image filename + with ".properties" appended. The generated file should be moved + to ~/.config/piscsi. - -r Run in restore mode. Defaults to dump mode if not specified. + -r Run in restore mode. Defaults to dump mode if not specified. - -v Enable verbose logging. + -S Scan SCSI bus for devices. - -p Generate a .properties file that is compatible with the PiSCSI - web interface. The output filename will match the image filename - with ".properties" appended. The generated file should be moved - to ~/.config/piscsi. + -s BUFFER_SIZE + The transfer buffer size, specified in bytes. Default is 1 MiB. + This is specified in bytes with a minimum value of 65536 (64 + KiB). - -I ID[:LUN] - Display INQUIRY data of ID[:LUN]. + -t ID[: LUN] + SCSI ID and optional LUN of the remote SCSI device. The remote + SCSI device will be functioning as the "Target" device. - -S Scan SCSI bus for devices. + -v Enable verbose logging. EXAMPLES - Dump Mode: [SCSI Drive] ---> [PiSCSI host] Launch scsidump to dump an - all data from SCSI ID 3 with block size 64 KiB, store it to the local - filesystem as a drive image named outimage.hda, and generate the outim‐ - age.hda.properties file with the drive's INQUIRY information: - scsidump -t 3 -f ./outimage.hda -s 65536 -p + Dump Mode: [SCSI Drive] ---> [PiSCSI host] + + Launch scsidump to dump an all data from SCSI ID 3 with block size 64 + KiB, store it to the local filesystem as a drive image named outim‐ + age.hda, and generate the outimage.hda.properties file with the drive's + INQUIRY information: + scsidump -t -3 -f -./outimage.hda -s -65536 -p + + Restore Mode: [PiSCSI host] ---> [SCSI Drive] - Restore Mode: [PiSCSI host] ---> [SCSI Drive] Launch scsidump to re‐ - store/upload a drive image from the local file system to SCSI ID 0 with - block size 1MiB: - scsidump -r -t 0 -f ./outimage.hda -s 1048576 + Launch scsidump to restore/upload a drive image from the local file sys‐ + tem to SCSI ID 0 with block size 1MiB: + scsidump -r -t -0 -f -./outimage.hda -s -1048576 SEE ALSO scsictl(1), piscsi(1), scsimon(1) Full documentation is available at: - scsidump(1) +PiSCSI October 30, 2023 SCSIDUMP(1) diff --git a/doc/scsiloop_man_page.txt b/doc/scsiloop_man_page.txt index 7ccccf9ed4..8ab5c70f70 100644 --- a/doc/scsiloop_man_page.txt +++ b/doc/scsiloop_man_page.txt @@ -2,42 +2,46 @@ !! ------ The native file is scsiloop.1. Re-run 'make docs' after updating -scsiloop(1) General Commands Manual scsiloop(1) +SCSILOOP(1) General Commands Manual SCSILOOP(1) NAME - scsiloop - Tool for testing the PiSCSI board with a loopback adapter installed + scsiloop — Tool for testing the PiSCSI board with a loopback adapter in‐ + stalled SYNOPSIS scsiloop [-L LOG_LEVEL] DESCRIPTION - scsiloop Performs a self-test of the PiSCSI hardware to ensure that the board is functioning properly. In order for this - tool to work, a special loopback cable MUST be attached to the PiSCSI SCSI connector. + scsiloop Performs a self-test of the PiSCSI hardware to ensure that the + board is functioning properly. In order for this tool to work, a special + loopback cable MUST be attached to the PiSCSI SCSI connector. - In addition to testing the GPIO signals, scsiloop will perform a self-test of the hardware timers that are built into the - system on a chip (SoC). + In addition to testing the GPIO signals, scsiloop will perform a self- + test of the hardware timers that are built into the system on a chip + (SoC). The loopback connections for the DB25 connector are shown here: - |Pin | Name | Pin | Name | - +----+------+-----+------+ - | 1 | REQ | 13 | DB7 | - | 2 | MSG | 12 | DB6 | - | 3 | I/O | 11 | DB5 | - | 4 | RST | 10 | DB3 | - | 5 | ACK | 8 | DB0 | - | 6 | BSY | 20 | DBP | - | 15 | C/D | 23 | DB4 | - | 17 | ATN | 22 | DB2 | - | 19 | SEL | 21 | DB1 | + |Pin | Name | Pin | Name | + +----+------+-----+------+ + | 1 | REQ | 13 | DB7 | + | 2 | MSG | 12 | DB6 | + | 3 | I/O | 11 | DB5 | + | 4 | RST | 10 | DB3 | + | 5 | ACK | 8 | DB0 | + | 6 | BSY | 20 | DBP | + | 15 | C/D | 23 | DB4 | + | 17 | ATN | 22 | DB2 | + | 19 | SEL | 21 | DB1 | OPTIONS -L LOG_LEVEL - The piscsi log level (trace, debug, info, warn, err, off). The default log level is 'info'. + The piscsi log level (trace, debug, info, warn, err, off). The + default log level is 'info'. SEE ALSO scsictl(1), piscsi(1), scsimon(1) Full documentation is available at: - scsiloop(1) +PiSCSI December 5, 2022 SCSILOOP(1) diff --git a/doc/scsimon_man_page.txt b/doc/scsimon_man_page.txt index f708fbfa7a..11cd5e46e1 100644 --- a/doc/scsimon_man_page.txt +++ b/doc/scsimon_man_page.txt @@ -2,41 +2,51 @@ !! ------ The native file is scsimon.1. Re-run 'make docs' after updating -scsimon(1) General Commands Manual scsimon(1) +SCSIMON(1) General Commands Manual SCSIMON(1) NAME - scsimon - Acts as a data capture tool for all traffic on the SCSI bus. Data is stored in a Value Change Dump - (VCD) file. + scsimon — Acts as a data capture tool for all traffic on the SCSI bus. + Data is stored in a Value Change Dump (VCD) file. SYNOPSIS - scsimon + scsimon [-i input_file_json] [-b buffer_size] [output_file] DESCRIPTION - scsimon monitors all of the traffic on the SCSI bus, using a PiSCSI device. The data is cached in memory while - the tool is running. A circular buffer is used so that only the most recent 1,000,000 transactions are stored. - The tool will continue to run until the user presses CTRL-C, or the process receives a SIGINT signal. + scsimon monitors all of the traffic on the SCSI bus, using a PiSCSI de‐ + vice. The data is cached in memory while the tool is running. A circular + buffer is used so that only the most recent transactions are stored, + with a default size of 1,000,000 unless overridden by the -b option. The + tool will continue to run until the user presses CTRL-C, or the process + receives a SIGINT signal. - The logged data is stored in a file called "log.vcd" in the current working directory from where scsimon was - launched. + If the -i option is specified, scsimon will parse the provided JSON file + instead of capturing new data. If -i option is not specified, scsimon + will read the GPIO pins. - Currently, scsimon doesn't accept any arguments. + The logged data is stored in files with the base name specified by out‐ + put_file, or "log" if not specified. The appropriate file extension + (e.g., .json or .vcd) will be appended. To quit scsimon, press Control + C. OPTIONS - None + -i input_file_json scsimon will parse the json file instead of capturing + new data. If -i option is not specified, scsimon will read the gpio + pins. -b buffer_size Override the default buffer size of 1000000. + output_file Base name of the output files. The file extension (ex: + .json) will be appended to this file name. EXAMPLES - Make sure you've stopped the piscsi service. Then launch scsimon to capture all SCSI traffic available to the - PiSCSI hardware: - scsimon + Make sure you've stopped the piscsi service. Then launch scsimon to cap‐ + ture all SCSI traffic available to the PiSCSI hardware: + scsimon - If you're trying to capture a specific scenario, you'll want to wait to start scsimon until immediately before - the scenario. + If you're trying to capture a specific scenario, you'll want to wait to + start scsimon until immediately before the scenario. SEE ALSO scsictl(1), piscsi(1), scsidump(1) Full documentation is available at: - scsimon(1) +PiSCSI December 18, 2025 SCSIMON(1)