SerialUSB doc file version 0.04

SerialUSB
=========

SerialUSB provides a DeviceFS serial interface (SerialUSB<n>:) for USB serial devices 

It supports the following USB serial devices:

CH340
CP210x
PL2303
FTDI
CDC

The first device found will be called 'SerialUSB:'. If more than 1 serial usb device
is plugged in they will be given names 'SerialUSB1:' 'SerialUSB2:' etc. To see if the
device is recognised

*SerialUSBDevices

will list the recognised devices.

SerialUSB supports the standard RISC OS DeviceFS serial interface so you can test
output with:

echo test { > SerialUSB: }

which will send 'test ' to 'SerialUSB:' by default 'SerialUSB:' is equivalent to:

SerialUSB#baud=115200;nohandshake;data=8;stop=1;noparity:

So if you only want to change the baud rate/handshake you just need to use:

SerialUSB#baud=9600:
SerialUSB#baud=19200;rts:
SerialUSB#xon:

Device names
============

Device names are of the form SerialUSBn when n is a number between 1 and 999 or n is omitted
omitted altogether. After n reaches 999 it wraps around so 999 is the maximum number given
to a SerialUSB device.

If a device is unplugged and reinserted it is given a new device name.

Commands
========

SerialUSBDevices
----------------

Lists information about the SerialUSB devices connected.

SWIs
====

SerialUSB_Info      0x059c00
--------------

Entry:
    r0 - SerialUSB device name eg SerialUSB3 - 0 terminated
    r1 - reason code
 r2-r9 - reason code dependent
 
Exit:
 r0-r1 - preserved
 r2-r9 - reason code dependent
 

Reason Codes:

Reason: SerialUSB_InfoVendor 0

Entry:

Exit:
    r2 - VendorId
    r3 - Productid
    r4 - Version



Reason: SerialUSB_InfoSerialNumber 1

Entry:
    r2 - buffer
    r3 - buffer size

Exit:
    r2  buffer filled with the serial number USB string descriptor
    r3  actual size of the serial number USB string descriptor in bytes or size of 
        buffer required if r2 = 0 on entry. If r3 = 0 on exit then there is no serial
        number.

Note: The serial number has the following format
      byte 0 - total length (n) of serial number USB string descriptor
      byte 1 - 3
   bytes 2-n - utf-16 (little endian) encoded serial number with no trailing 0.

Note: As the length is 1 byte the maximum size of the string descriptor data is 256.
      
      If buffer size is less than the size of the serial number, and there is a serial
      number, the buffer is filled up to buffer size.
    


Reason: SerialUSB_InfoDeviceDescription 2

Textural description of the device.

Entry:
    r2 - buffer
    r3 - buffer_size

Exit:
    r2 - Filled with textural description of the device including a
         trailing 0. buffer is filled up to buffer_size.
    r3 - actual size of the device description or size of buffer required
         if r2 = 0 on entry. The description is a c string and the buffer 
         size includes the trailing 0.
         


Reason: SerialUSB_InfoUnderlyingUSBDevice 3

Entry:
    r2 - pointer to 20 byte buffer

Exit:
    r2 - filled with the USB device name (eg USB7) and the trailing 0
         
Reason SerialUSB_InfoInterfaceNumber 4

USB interface number on the device

Entry:

Exit:
    r2 -  USB interface number used by the device



Reason SerialUSB_InfoLocation 5

64 bit number locating the port the device is plugged in to.
Entry:

Exit:
    r2 - location lo 32bits
    r3 - location hi 32bits
    




SerialUSB_FindDeviceByLocation  0x059c01
-------------------------------
Entry:
    r0 - location lo
    r1 - location hi
    r2 - Interface number or -1 don't care
    r3 - pointer to 20 byte buffer
    r4 - index, starting from 0 - see note
    
Exit:
    r3 - filled with SerialUSB device name eg SerialUSB4 - 0 terminated - or buffer[0] = 0
         if the location isn't a SerialUSB device.

      If r2 = -1 there may be more than 1 device that matches the search criteria 
      other matches can be found by increasing the index. If buffer[0] = 0 on exit 
      then there wasn't a match with the specified index and there will be no more 
      matches with a greater index.




      
SerialUSB_FindDeviceByVendor 0x059c02
----------------------------
Entry:
    r0 - VendorId or -1 don't care
    r1 - ProductId or -1 don't care
    r2 - Version Number or -1 don't care
    r3 - Interface number or -1 don't care
    r4 - pointer to 20 byte buffer
    r5 - index, starting from 0 - see note
    
Exit:
 r0-r3 - preserved
    r4 - filled with SerialUSB device name eg SerialUSB4 - 0 terminated - or buffer[0] = 0
         if there isn't a match
    r5 - preserved

Note: There may be more than 1 device that matches the search criteria other matches
      can be found by increasing the index. If buffer[0] = 0 on exit then there wasn't
      a match with the specified index and there will be no more matches with a greater
      index.
            
      Setting all search values to -1 allows you to enumerate all connected devices.





SerialUSB_FindDeviceBySerialNumber 0x059c03
----------------------------------
Entry:
    r0 - Buffer containing he device's serial number USB string descriptor as
         returned by SerialUSB_Info SerialUSB_InfoSerialNumber
    r1 - Interface number or -1 don't care
    r2 - pointer to 20 byte buffer
    r3 - index, starting from 0 - see note

Exit:
 r0-r1 - preserved
    r2 - filled with SerialUSB device name eg SerialUSB4 - 0 terminated - or buffer[0] = 0
         if there isn't a match.
    r3 - preserved

Note: If r2 = -1 there may be more than 1 device that matches the search criteria 
      other matches can be found by increasing the index. If buffer[0] = 0 on exit 
      then there wasn't a match with the specified index and there will be no more 
      matches with a greater index.





SerialUSB_DevicesChanged  0x059c04
----------------------------------

Determine if a SerialUSB device has been added or removed.

Entry:
    r0 - reason code
 r2-r9 - reason code dependent

Exit:
    reason code dependent.



Reason Codes:



Reason: SerialUSB_DevicesChangedRegister    1

Register with devices changed service.

Entry:
    none.

Exit:
    r1 = devices_changed_handle;



Reason: SerialUSB_DevicesChangedUnregister    2

Unregister with devices changed service.

Entry:
    r1 = devices_changed_handle returned when registering.

Exit:
    none.


Reason: SerialUSB_DevicesChanged    3

Informs whether any SerialUSB device has been inserted or removed.

Entry:
    r1 = devices_changed_handle returned when registering.

Exit:
    r1 = 0 - no SerialUSB devices were added or removed.
    r1 = 1 - SerialUSB devices were added or removed.





Notes
=====

When opening a SerialUSB device for output, after all of your data is written
some of the data will be in the buffer. In noblock mode if you want to know 
if the data has actually been sent OS_Args 5 (EOF) returns EOF when the 
buffers are empty. This allows you to multitask while the write buffer empties
(Close will block until the write buffer empties).

In common with all DeviceFS drivers if noblock is used eg

SerialUSB#noblock;baud=9600:

OS_GBPB will return immediately with the number of bytes that were available.

