USB base layer

The file UsbBase.fth contains an (almost) hardware independent USB code base. The hardware layer files, UsbHwxxxx.fth provide a standard interface that isolates hardware from the base layer. Class drivers such as MscDrv.fth should be compiled after the core layer and can reference the hardware layer. After the class files have been compiled, compile UsbEP0.fth, which contain the USB control and initialisation.

The five VALUEs below are used to provide status information for the core layer, but are actually contained in UsbDefs.fth to avoid forward references and to permit easy reference by the class drivers. Note that the endpoint status values are bit masks in a hardware independent form. See EP>mask below.

0 value UsbDevAddr      \ -- u
USB device address

0 value UsbConfig       \ -- x
USB Configuration set. Non-zero when the USB device has been configured.

0 value UsbEPmask       \ -- x
Endpoint mask.

0 value UsbEPhalt       \ -- x
Endpoint halt status.

0 value Usb#IfSet       \ -- n
Number of interfaces set.

: EP>mask       \ ep# -- mask
Decode an endpoint number to a bit mask such that if bit 7 is clear (OUT endpoints), the bit is in the low 16 bits, and if set (IN endpoints) in the upper 16 bits.

#USBifs buffer: USBAltSets      \ -- addr
Alternate settings array

struct /UsbEPdata       \ -- len
USB Endpoint transfer data structure.

UAlign  /UsbEPdata buffer: EP0Data      \ -- addr
Endpoint 0 transfer control structure.

UAlign  /USBSetupPacket buffer: SetupPacket     \ -- addr
Current setup packet.

UAlign  /MaxPacket0 buffer: EP0Buf      \ -- addr
Packet buffer for endpoint 0 data.

: ReqType       \ -- b
Return the first byte in the global SetupPacket.

: ReqDir        \ -- $80|$00
Return the direction bit of the usp.bmRequestType field in the global SetupPacket.

: ReqTypeBits   \ -- %0xx00000
Return the type bits of the usp.bmRequestType field in the global SetupPacket.

: ReqRecipient  \ -- %000xxxxx
Return the recipient bits of the usp.bmRequestType field in the global SetupPacket.

: EP0Addr       \ -- addr|0
The address contained in EP0Data ep.*Data field.

: /EP0Data      \ -- len
The size of the data in EP0Data as given by the ep.Count field.

: NoEP0Data     \ --
Reset EP0data.

: DevResetCore  \ --
Reset the core software configuration. This word is part of USB device reset chain.

: UsbSetupStage \ --
USB Request - Setup Stage

: +EP0Data      \ len --
Update the EP0Data structure by len bytes.

: UsbDataInStage        \ --
USB Request - Data In Stage. Data is taken from the EP0Data global structure.

: doDataIn      \ caddr len --
Set up the data and do the DataIn stage.

: ?MoreDataIn   \ --
Performed in the USB frame check and sends more data if required.

: USBDataOutStage       \ --
USB Request - Data Out Stage. Data is taken from the EP0Data global structure.

: sendZLPin     \ ep# --
Send a zero length packet from the given endpoint.

: USBStatusInStage      \ --
USB Request - Status In Stage.

: USBStatusOutStage     \ --
USB Request - Status Out Stage.

: stall_i       \ --
Stall EP0 input.

: stall_o       \ --
Stall EP0 output.

: RTDst         \ -- flag ; true=success
Get REQUEST_TO_DEVICE status.

: RTIst         \ -- flag ; true=success
Get REQUEST_TO_INTERFACE status.

: RTEst         \ -- flag ; true=success
Get REQUEST_TO_ENDPOINT status.

: USBGetStatus  \ -- flag ; true=success
Get Status USB Request. The data is in the global SetupPacket.

: RTDsetf       \ sc -- flag ; sc, true=set; flag, true=success
Set/Clear Device feature.

: RTEsetf       \ sc -- flag ; sc, true=set; flag, true=success
Set/Clear Endpoint feature.

: USBSetClrFeature      \ sc -- flag ; sc, true=set; flag, true=success
Set/Clear Feature USB Request. The data is in the global SetupPacket.

: maxEP0resp    \ len -- len' ; SFP003
Clip the given length to the wLength value in the setup packet.

: GetCfgDesc    \ -- flag ; true=success
Get Configuration descriptor. The data is in the global SetupPacket.

: GetStrDesc     \ -- flag
Get String descriptor. The data is in the global SetupPacket. Used when USBStr@ has been defined and the string index is a small integer. USBStr@ ( index -- caddr len ) is usually defined in the configuration file. See CdcMscConfig.fth for an example.

: GetStrDesc     \ -- flag
Get String descriptor. The data is in the global SetupPacket. Used when USBStr@ has not been defined and the string index is the byte offset into the string table.

: GetRTDDesc    \ -- flag ; true=success
Get Device Descriptor USB Request. The data is in the global SetupPacket.

: USBGetDescriptor      \ -- flag ; true=success
Get Descriptor USB Request. The data is in the global SetupPacket.

: DisableAllEPs \ --
Disable all endpoints except 0.

: SetCfgConfig  \ desc -- desc'
Process the base configuration descriptor, returning the next descriptor.

: initEP        \ desc ep# mask -- desc
Initialise an endpoint for use.

: termEP        \ ep# mask --
Terminate using an endpoint. Only needed if USBSetIface is provided.

: SetEPConfig   \ desc -- desc
Process an endpoint descriptor, returning the same descriptor.

: SetConfig     \ --
Set the configuration from the descriptor. The CfgDesc Configuration descriptor (see Descriptors.fth is walked and processed.

: ClrConfig     \ --
Clear the existing configuration.

: USBSetConfig  \ -- flag ; true=success
Set Configuration USB Request.

: USBSetIface   \ -- flag ; true=success
Set Interface USB Request. The data is in the global SetupPacket. This word is now unused and is commented out.