mirror of
https://github.com/akuker/RASCSI.git
synced 2026-10-25 12:02:59 +00:00
Daniel Markstedt
485298ffe5
Restore the SCBR device as an X68000 Host Bridge, including the Human68k-compatible host file-system service and the bridge-specific SCSI message handlers. Back its Ethernet path with the TAP driver, derive a stable locally administered MAC address, preserve the driver minimum-frame/FCS expectations, and restrict received traffic to its own unicast frames and broadcasts. Match the RASCTL/RASETHER/RASDRV bridge protocol that originated in the parent RaSCSI project: dispatch its non-standard message format on READ(10)/WRITE(10) (0x28/0x2a), with type, function, phase, and a three-byte byte count carried in the CDB. Advertise the legacy control channel required by RASCTL, translate its list and device-management commands to PiSCSI operations, and defer stop or system-shutdown requests until after the response is sent, while gating this insecure interface behind a new '-c disabled|media|full' runtime option. Preserve the type-1 Ethernet exchange used by RASETHER and the type-2, phased filesystem exchange used by RASDRV. Register the device in the factory, protobuf API, controller transfer path, command-line tooling, device listings, and web UI. Share the explicit bridge and proxy-ARP topology workflow with DaynaPort so both adapters validate and use the same mode/interface pair. Add build support for iconv where needed, extend unit coverage for device creation, RAS* protocol handling, CLI parsing, web attachment, and topology selection, and update the man pages and network-profile documentation for Host Bridge operation and its networking limits.
369 lines
14 KiB
Groff
369 lines
14 KiB
Groff
.Dd August 30, 2026
|
|
.Dt PISCSI 1
|
|
.Os PiSCSI
|
|
.Sh NAME
|
|
.Nm piscsi
|
|
.Nd Emulates SCSI devices using the Raspberry Pi GPIO pins
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl b Ar BLOCK_SIZE
|
|
.Op Fl c Ar RASCTL_CONTROL
|
|
.Op Fl F Ar FOLDER
|
|
.Op Fl L Ar LOG_LEVEL Ns Oo : Ar ID Ns Oo : Ar LUN Oc Oc
|
|
.Op Fl n Ar VENDOR:PRODUCT:REVISION
|
|
.Op Fl P Ar ACCESS_TOKEN_FILE
|
|
.Op Fl p Ar PORT
|
|
.Op Fl R Ar SCAN_DEPTH
|
|
.Op Fl r Ar RESERVED_IDS
|
|
.Op Fl s Ar MICROSECONDS
|
|
.Op Fl t Ar TYPE
|
|
.Op Fl z Ar LOCALE
|
|
.Op Fl IDn Ns Oo :u Oc Ar FILE
|
|
.Nm
|
|
.Op Fl C Ar TYPE
|
|
.Op Fl h
|
|
.Nm
|
|
.Op Fl v
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
emulates a range of SCSI devices using the Raspberry Pi GPIO pins.
|
|
It can also emulate SASI hard drives, which is a predecessor of SCSI.
|
|
.Pp
|
|
In the arguments to PiSCSI, one or more SCSI or SASI (-IDn[:u]) devices can be
|
|
specified.
|
|
The number (n) after the ID 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.
|
|
SASI hard disks support LUNs 0-1 only.
|
|
.Pp
|
|
Note: PiSCSI cannot be run in parallel with other applications that use the same GPIO pins, such as RaSCSI or SCSI2Pi.
|
|
.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.
|
|
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 CONNECTION TYPES
|
|
The GPIO-facing tools select the board layout when they start. Use
|
|
.Fl C
|
|
to select one of the following types:
|
|
.Bl -tag -offset indent-two -width GAMERNIUM
|
|
.It Dv FULLSPEC
|
|
For boards with initiator support.
|
|
.It Dv STANDARD
|
|
For simpler boards that use fewer pins.
|
|
.It Dv GAMERNIUM
|
|
For the early GAMERnium.com board variant.
|
|
.El
|
|
.Pp
|
|
Note: As of PiSCSI v26.8.1, the
|
|
.Dv AIBOM
|
|
board variant is no longer supported.
|
|
.Pp
|
|
Use the board's silkscreen or the Hardware Versions wiki page at
|
|
.Lk https://github.com/PiSCSI/piscsi/wiki/Hardware-Versions
|
|
to identify it. Selecting the wrong type can prevent devices from appearing on
|
|
the SCSI bus.
|
|
.Pp
|
|
The default is
|
|
.Dv FULLSPEC .
|
|
For example:
|
|
.Dl sudo piscsi Fl C Ar STANDARD Fl r Ar 7
|
|
.Pp
|
|
.Nm ,
|
|
.Xr scsimon 1 ,
|
|
.Xr scsiloop 1 ,
|
|
.Xr scsidump 1 ,
|
|
and
|
|
.Xr sasidump 1
|
|
support this option. The type is fixed for the lifetime of the process; stop
|
|
and restart a tool before choosing another mapping.
|
|
.Pp
|
|
The supplied systemd service defaults to
|
|
.Dv FULLSPEC .
|
|
Override its
|
|
.Ev PISCSI_CONNECTION_TYPE
|
|
environment variable and restart the service to use a different mapping.
|
|
.Sh DEVICE TYPES
|
|
PiSCSI can emulate the following device types.
|
|
The four letter code (case insensitive) can be passed to the -t option to select the device.
|
|
A non-removable disk drive must be attached with an image file,
|
|
while a removable disk drive can be attached either empty or with an image file.
|
|
The other device types may require other parameters to attach, see the FILE argument documentation below.
|
|
.Bl -tag -offset indent-two -width SAHD
|
|
.It Dv SAHD
|
|
SASI Hard Disk (takes image, non-removable)
|
|
.It Dv SCBR
|
|
SCSI Host Bridge (X68000 host bridge and Neptune-X compatible network adapter)
|
|
.It Dv SCCD
|
|
SCSI CD-ROM (CD-ROM or DVD-ROM drive, takes images, removable)
|
|
.It Dv SCDP
|
|
SCSI DaynaPort (DaynaPort SCSI/Link compatible network adapter)
|
|
.It Dv SCHD
|
|
SCSI Hard Disk (takes image, non-removable)
|
|
.It Dv SCHS
|
|
SCSI Host Services (used for special host services)
|
|
.It Dv SCLP
|
|
SCSI Printer (generic line printer)
|
|
.It Dv SCMO
|
|
SCSI Magneto-Optical Drive (takes image, removable)
|
|
.It Dv SCRM
|
|
SCSI Removable Hard Disk (takes image, removable)
|
|
.It Dv SCTP
|
|
SCSI Tape Drive (takes image, removable)
|
|
.El
|
|
.Pp
|
|
If the device type is not specified as described above,
|
|
PiSCSI will determine the type of device based upon the file extension of the FILE argument.
|
|
.Bl -tag -offset indent-two -width toast
|
|
.It Dv hds
|
|
Hard Disk image (generic, non-removable)
|
|
.It Dv hd1
|
|
Hard Disk image (generic, non-removable, SCSI-1 compatibility mode)
|
|
.It Dv hdr
|
|
Hard Disk image (generic, removable)
|
|
.It Dv hdn
|
|
Hard Disk image (NEC compatible - only used with PC-98 computers)
|
|
.It Dv hdi
|
|
Hard Disk image (Anex86 proprietary - only used with PC-98 computers)
|
|
.It Dv nhd
|
|
Hard Disk image (T98Next proprietary - only used with PC-98 computers)
|
|
.It Dv hda
|
|
Hard Disk image (Apple compatible - typically used with Macintosh computers)
|
|
.It Dv hdf
|
|
Hard Disk image (raw SASI HD image - typically used with X68000)
|
|
.It Dv mos
|
|
Magneto-Optical image (generic, typically used with NeXT, X68000, etc.)
|
|
.It Dv iso
|
|
CD-ROM or DVD-ROM image (ISO 9660 image)
|
|
.It Dv cdr
|
|
CD-ROM or DVD-ROM image (ISO 9660 image)
|
|
.It Dv toast
|
|
CD-ROM or DVD-ROM image (ISO 9660 image)
|
|
.It Dv is1
|
|
CD-ROM or DVD-ROM image (ISO 9660 image, SCSI-1 compatibility mode)
|
|
.It Dv tap
|
|
Tape image (raw tape image containing non-block data)
|
|
.It Dv tar
|
|
Tape archive (tape block data in tar format)
|
|
.El
|
|
.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
|
|
.Sh IMAGE FILE FORMATS
|
|
File extensions are case-insensitive.
|
|
They select the default device type as described above, and some also enable
|
|
compatibility handling or cause PiSCSI to read an image-format header.
|
|
Most other hard disk images are raw block images and have no PiSCSI-specific
|
|
on-disk header.
|
|
.Ss Apple hard disks
|
|
The
|
|
.Pa .hda
|
|
extension selects a generic hard disk with the INQUIRY identification
|
|
.Dq QUANTUM FIREBALL .
|
|
This compatibility identity allows Apple HD SC Setup on classic Mac OS to
|
|
recognize and format the hard disk.
|
|
.Ss PC-98 hard disks
|
|
The
|
|
.Pa .hdn ,
|
|
.Pa .hdi ,
|
|
and
|
|
.Pa .nhd
|
|
extensions select the PC-98 hard-disk implementation.
|
|
It reports SCSI-1 CCS inquiry data and supplies PC-98 disk geometry in MODE
|
|
SENSE pages.
|
|
.Pp
|
|
.Pa .hdn
|
|
is a raw NEC PC-9801-55-style image.
|
|
PiSCSI treats its data as beginning at offset zero and uses a geometry of 512
|
|
bytes per sector, 25 sectors per track, and 8 heads.
|
|
.Pp
|
|
.Pa .hdi
|
|
is the Anex86 format.
|
|
PiSCSI reads its 512-byte image header for the data offset, image size, sector
|
|
size, and geometry.
|
|
.Pp
|
|
.Pa .nhd
|
|
is the T98Next format.
|
|
PiSCSI requires the
|
|
.Dq T98HDDIMAGE.R0
|
|
signature in its header and reads the data offset and geometry from that
|
|
header.
|
|
For both formats, this metadata determines how PiSCSI accesses the payload;
|
|
it is not interpreted as a PC-98 boot sector.
|
|
.Ss SASI hard disks
|
|
The
|
|
.Pa .hdf
|
|
extension selects a SASI hard disk, typically used with X68000 systems.
|
|
It is a raw image, not a separately parsed HDF container.
|
|
The default sector size is 256 bytes; use
|
|
.Fl b
|
|
to select 256, 512, or 1024 bytes.
|
|
SASI addressing limits an image to 2,097,152 blocks.
|
|
.Pp
|
|
PiSCSI derives the capacity from the file length; it does not recognize
|
|
capacity-specific HDF variants.
|
|
.Ss Other extension-specific handling
|
|
.Pa .hd1
|
|
and
|
|
.Pa .is1
|
|
select SCSI-1 CCS compatibility for hard disks and CD-ROMs, respectively.
|
|
.Pa .hdr
|
|
selects a removable hard disk.
|
|
.Pa .mos
|
|
selects a removable magneto-optical disk; several common medium capacities
|
|
have predefined geometry.
|
|
.Pp
|
|
.Pa .iso ,
|
|
.Pa .cdr ,
|
|
and
|
|
.Pa .toast
|
|
select a read-only CD-ROM.
|
|
PiSCSI inspects the beginning of the file to distinguish a raw Mode 1 CD image
|
|
from a normal ISO image; CUE sheets are detected and rejected.
|
|
.Sh NETWORK INTERFACES
|
|
PiSCSI emulates two SCSI network interfaces: SCDP (DaynaPort) and SCBR (Host Bridge).
|
|
For these devices, the
|
|
.Ar FILE
|
|
argument is not an image file; it selects a host networking profile with a complete
|
|
.Cm mode
|
|
and
|
|
.Cm interface
|
|
pair.
|
|
For example, use
|
|
.Dq mode=bridge:interface=piscsi_bridge
|
|
or
|
|
.Dq mode=proxyarp:interface=wlan0 .
|
|
The
|
|
.Xr piscsi-network-profile 8
|
|
script configures the host-side profile before the network adapter is attached;
|
|
see its manual page for setup instructions and examples.
|
|
.Ss Device compatibility
|
|
SCDP is reverse engineered from the DaynaPort SCSI/Link Ethernet adapter and uses its drivers or compatible drivers.
|
|
SCBR is reverse engineered from the Neptune-X Ethernet adapter and uses its drivers or compatible drivers, including the RASETHER driver from the RaSCSI project.
|
|
SCBR also provides the X68000 host bridge, including its host file-system service and support for the RASCTL wire protocol.
|
|
.Ss Wired bridge
|
|
The
|
|
.Cm bridge
|
|
profile connects the emulated adapter to a preconfigured wired Linux bridge and provides complete Ethernet service, including DHCP, AppleTalk, multicast, and non-IP Ethernet protocols.
|
|
Configure this profile with a NetworkManager-managed Ethernet interface.
|
|
It creates the
|
|
.Pa piscsi_bridge
|
|
bridge, which owns the physical Ethernet port, its address, and DHCP configuration.
|
|
Attach an adapter using
|
|
.Dq mode=bridge:interface=piscsi_bridge .
|
|
SCDP can use the complete Ethernet service; the SCBR driver accepts only its own unicast frames and Ethernet broadcasts.
|
|
.Ss Wi-Fi proxy ARP
|
|
The
|
|
.Cm proxyarp
|
|
profile connects an emulated adapter to a NetworkManager-managed Wi-Fi uplink.
|
|
Configure it with the Wi-Fi interface holding the Pi's IPv4 lease.
|
|
This profile requires the
|
|
.Pa parprouted
|
|
and
|
|
.Pa dhcp-helper
|
|
packages.
|
|
It provides IPv4 unicast and DHCP only; it is not an Ethernet bridge and does not support IPv6, AppleTalk, multicast, mDNS, or other non-IP Ethernet traffic.
|
|
Attach an adapter using
|
|
.Dq mode=proxyarp:interface=wlan0 .
|
|
The SCBR driver remains limited to its own unicast frames and Ethernet broadcasts.
|
|
.Ss Profile management
|
|
The profile script manages only the named PiSCSI NetworkManager connections and
|
|
.Pa /etc/piscsi/network.conf .
|
|
Applying or removing a profile may interrupt host connectivity; see
|
|
.Xr piscsi-network-profile 8
|
|
for its usage and examples.
|
|
Always provide both
|
|
.Cm mode
|
|
and
|
|
.Cm interface ;
|
|
the retired
|
|
.Cm inet
|
|
parameter and comma-separated interface lists are not supported.
|
|
.Sh OPTIONS
|
|
.Bl -tag -width Ds
|
|
.It Fl b Ar BLOCK_SIZE
|
|
The optional block size.
|
|
SASI hard disks support 256, 512, or 1024 bytes per sector and default to 256 bytes.
|
|
Other disk devices support 512, 1024, 2048, or 4096 bytes and default to 512 bytes.
|
|
.It Fl C Ar TYPE
|
|
Select the board connection type for this process. See
|
|
.Sx CONNECTION TYPE
|
|
for the available mappings and their appropriate boards.
|
|
.It Fl c Ar RASCTL_CONTROL
|
|
Enable the unauthenticated RASCTL compatibility control channel on SCBR host bridges.
|
|
The default is
|
|
.Dq off .
|
|
Use
|
|
.Dq media
|
|
to permit listing and media-management commands, or
|
|
.Dq full
|
|
to additionally permit PiSCSI and system shutdown commands.
|
|
Only enable this option when all SCSI initiators are trusted.
|
|
.It Fl F Ar FOLDER
|
|
The default folder for image files. For files in this folder no absolute path needs to be specified. The folder must already exist. The initial default folder is '/var/lib/piscsi/images'.
|
|
.It Fl h
|
|
Show a help page.
|
|
.It Fl L Ar LOG_LEVEL Ns Oo : Ar ID Ns Oo : Ar LUN Oc Oc
|
|
The piscsi log level (trace, debug, info, warning, error, off). The default log level is 'info' for all devices unless a particular device ID and an optional LUN was provided.
|
|
.It Fl n Ar VENDOR:PRODUCT:REVISION
|
|
Set 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 maximum length is automatically applied. Once set the name of a device cannot be changed.
|
|
.It Fl P Ar ACCESS_TOKEN_FILE
|
|
Enable authentication and read the access token from the specified file. The access token file must be owned by root and must be readable by root only.
|
|
.It Fl p Ar PORT
|
|
The piscsi server port, default is 6868.
|
|
.It Fl R Ar 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.
|
|
.It Fl r Ar RESERVED_IDS
|
|
Comma-separated list of IDs to reserve. Pass an empty list in order to not reserve anything.
|
|
.It Fl s Ar MICROSECONDS
|
|
Minimum execution time for SCSI commands in microseconds. Default is 50 for SCSI and 100 for SASI.
|
|
Higher values may be needed for some older SCSI initiators to work properly.
|
|
.It Fl t Ar 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 extension.
|
|
.It Fl v
|
|
Display the piscsi version.
|
|
.It Fl z Ar LOCALE
|
|
Sets the default locale for client-facing error messages. The client can override the locale.
|
|
.It Fl ID Ar n Ns Oo : Ar u Oc Ar FILE
|
|
n is the SCSI or SASI ID number (0-7).
|
|
u is the optional LUN (logical unit): 0-31 for SCSI and 0-1 for SASI.
|
|
The default LUN is 0.
|
|
.Pp
|
|
FILE is the name of the image file to use for a SCSI or SASI mass storage 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 selects the host networking profile; see
|
|
.Sx NETWORK INTERFACES .
|
|
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
|
|
.Pp
|
|
Launch PiSCSI with an Apple hard drive image as ID 0 and a CD-ROM as ID 2
|
|
.Dl Nm piscsi Fl ID0 Ar /path/to/harddrive.hda Fl ID2 Ar /path/to/cdimage.iso
|
|
.Pp
|
|
Launch PiSCSI with a removable SCSI drive image as ID 0 and the raw device file /dev/hdb (e.g. a USB stick) and a DaynaPort network adapter as ID 6:
|
|
.Dl Nm piscsi Fl ID0 Fl t Ar scrm Ar /dev/hdb Fl ID6 Fl t Ar scdp Ar daynaport
|
|
.Pp
|
|
Launch PiSCSI with a DaynaPort on the preconfigured wired bridge:
|
|
.Dl Nm piscsi Fl ID6 Fl t Ar scdp Ar "mode=bridge:interface=piscsi_bridge"
|
|
.Pp
|
|
For a configured Wi-Fi proxy-ARP uplink named wlan0:
|
|
.Dl Nm piscsi Fl ID6 Fl t Ar scdp Ar "mode=proxyarp:interface=wlan0"
|
|
.Pp
|
|
To create an empty, 100MiB HD image, use the following command:
|
|
.Dl dd if=/dev/zero of=/path/to/newimage.hda bs=512 count=204800
|
|
.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 ,
|
|
.Xr scsidump 1
|
|
.Pp
|
|
Full documentation is available at: <https://www.piscsi.com>
|