Simtec USB technical

Note: the information on this page has mostly been established through unofficial channels and experimentation, and has a high chance of being wrong. It is not supported by Simtec or STD and may be subject to change in future versions of the USB firmware.

USB stack

The Simtec USB stack and HID drivers are poorly documented.

USB stack introduction riscos-usb.org site: low-level API description

HID drivers

The mouse drivers don't use the RISC OS 3.5+ mouse driver interface. This means they work in parallel with the configured mouse: a USB mouse and a quadrature mouse can work at the same time. It is suspected it inserts mouse events into PointerV instead. The scrollwheel is supported on RISC OS Adjust, using the WindowScroll module to move windows; on Adjust OS_Pointer provides an interface to read scrollwheel events (see Adjust documentation or StrongHelp OS manual).

MassFS

MassFS supports only USB Mass Storage devices with class:subclass:protocol of 08:06:50, that is, "Mass Storage:SCSI transparent command set:Bulk-only transport". This group includes most pen drives. It doesn't support devices that using the ATAPI subclass.

Plug in a USB drive and it appears with its name on the iconbar, eg USB_DISK, with hard spaces (Alt-160) replacing spaces in the DOS disc name. Drives available may be enumerated:

SWI MassFS_GetDriveCount (&56700)

On exit:

r0 = number of drives managed by MassFS

SWI MassFS_GetDriveInfo (&56701)

On entry:

r0 = drive number (from zero to number of drives managed by MassFS minus one)

On exit:

r0 = ?

r1 -> drive name

r1+20 -> connection?:drive_name:vendor_id:product_id (separated by colons, &3A)

r2 = size in sectors (512 bytes each)

r3 = flags?

Apart from GetDriveCount, some other MassFS_ SWIs use the drive name as parameter in r0.

MassFS presents the drive as a single file of filetype DOSDisc. This is then openable using DOSFS. This means native (FileCore) formatted flash drives aren't supported, though it might be possible using a FileCore image filing system such as FCFS. It doesn't support devices over 2GB (due to the limitations of the RISC OS image filing systems) and doesn't provide any means to access the raw sector data of such devices. It appears devices larger than 2GB aren't recognised even if they have a partition smaller than 2GB.

To save off a DOSDisc image of the disc, do

*Copy MassFS::USB_DISK ADFS::HardDisc.$.usbimage

To format the disc as FAT16 (DOS) format, use MkDOSDisc from the PC card sources (download the 3.06 source and extract MkDOSDisc from inside PCConfig/MKDOSdisc/ ). To format as 32MByte, do

*MkDOSDisc MassFS::USB_DISK.$ 32 -initdos

Don't try to format the disc larger than the size it actually is: it might be worth stepping down a megabyte or two from the published size, and beware that some devices are measured in sizes of million bytes (i.e. 32MB is 32,000,000 bytes rather than 32*1024*1024 bytes).

To read the raw blocks of a disc, open as a file then use OS_GBPB 3/4:

DIM block% 512
handle%=OPENIN("MassFS::USB_DISK")
address%=&4000
SYS "OS_GBPB",3,handle%,block%,512,address% TO ,,,not_read%
CLOSE#handle%

Reads 512 bytes from the disc starting at offset &4000. Writing is believed to work in the same way. (Note: MassFS::discname and MassFS::discname.$ seem to be used interchangeably)

To eject a USB Zip disc:

drive$="USB_DISK"
DIM block% 12
block%!0=&1B
block%!4=2
block%!8=0
SYS "MassFS_DriveOp",drive$,0,block%,12,0,0 TO err%:REM SWI &56706
IF err%>0 SYS "MassFS_CodetoError",err% TO err%:REM SWI &56707

This looks like a SCSI START/STOP UNIT command. It might be possible to send other SCSI commands to MassFS devices in a similar way.

OtherDevs file

The !MassFS.OtherDevs file is a way of tweaking various options to persuade MassFS to work with a USB Mass Storage device. It won't help if the device is not supported by the underlying USB stack, if it is not detected by *USBDevices, or hangs *USBDevices. It consists of a list of entries VVVV:PPPP=FFFFF where

• VVVV: 4 digit hex vendor ID
• PPPP: 4 digit hex product ID
• FFFFF: alphanumeric codes describing flag settings for this device.

The codes mean as follows:

• U: do not attempt to support this device (in case it's accidentally inserted)
• w: disable writing (make read-only)
• R: is a card reader
• r: might be a card reader, so check
• L: correctly supports "get maximum LUNs" command
• 2: has 2 LUNs
• 3: has 3 LUNs
• and so on until
• 8: has 8 LUNs
• Q: doesn't support Request Sense
• q: supports Request Sense if an error occurs
• _: supports reset recovery (experimental)
• T: requires test before Read Size
• t: doesn't support START up command
• C: supports READ CAPACITY (if not, READ FORMAT CAPACITIES will be used instead)

For example:

# Device: TwinMOS 256MB Pen Drive
# Submitted by CJE
126f:2035=LR_T

The default is:

• supported
• may be written to
• not a card reader
• maximum LUNs may be read correctly
• if we can't read the number of LUNs, it has 1 LUN
• supports Request Sense all the time
• doesn't support reset recovery
• doesn't require test before Read Size
• supports START up
• supports READ FORMAT CAPACITIES

References

Postings by Jason Tribbeck:

• MassFS eject
• MassFS formatting
• Mass storage classes

Other sites:

• Simtec USB site
• Iyonix USB information