File Types: How to guides

XSIM Command-Line Manual

XSIM performs a cycle-based simulation of an XMOS Executable (XE) file.
The XE file contains a description of the target hardware.

Overall Options

  • xe-file

    Specifies an XE file to simulate.

  • --max-cycles n

    Exits when n system cycles is reached.

  • --plugin name args

    Loads a plugin DLL. The format of args is determined by the plugin;
    if args contains any spaces, it must be enclosed in quotes.

  • --stats

    On exit, prints the following:

    • A breakdown of the instruction counts for each logical core.
    • The number of data and control tokens sent through the switches.
  • --help

    Prints a description of the supported command line options.

  • --version

    Displays the version number and copyrights.

Warning Options

  • --warn-resources

    Prints (on standard error) warning messages for the following:

    • A timed input or output operation specifies a time in the past.
    • The data in a buffered port’s transfer register is overwritten
      before it is input by the processor.

  • --warn-stack

    Turns on warnings about possible stack corruption.

    XSIM prints a warning if one XC task attempts to read
    or write to another task’s workspace. This can happen if the stack
    space for a task is specified using either #pragma stackfunction

    or #pragma stackcalls
    .

  • --no-warn-registers

    Don’t warn when a register is read before being written.

Tracing Options

Trace output for XS1 processors
Core Core State Address Instruction Mem Cycle
Name
from
XN
I0 I1 I2 S0S1(T0) … S0S1(Tn) . M S K N PC ( sym + offset) : name operands address @val

D
*
P

d

a
A
i
I
p
m
s
w

i
e
n status pairs  
m

s

k

n
    val
rm(val)
res[id]
L[adr]
S[adr]
 
I0: – No debug interrupt S1: – Interrupts and events disabled
I0: D Instruction caused debug interrupt S1: b Interrupts and events enabled
I1: * Instruction excepted S1: i Interrupts enabled and events disabled
I1: P Instruction paused S1: e Interrupts disabled and events enabled
I2: – Not in debug mode M: – MSYNC not set
I2: d Tile in debug mode M: m MSYNC set
S0: – Core not in use S: – SSYNC not set
S0: a Core active S: s SSYNC set
S0: A Core active (traced instruction belongs to this core) K: – INK not set
S0: i Core active with ININT bit set K: k INK set
S0: I Core active with ININT bit set (belongs to this core) N: – INENB not set
S0: p Core paused due to instruction fetch N: n INENB set
S0: m Core paused with MSYNC bit set rn (val) Value of register n
S0: s Core paused withSSYNC bit set res[id] Resource identifier
S0: w Core paused with WAITING bit set L/S[adr] Load from/Store to address

  • --trace-to file

    Turns on instruction tracing for all tiles. The trace is output to
    file.

  • --disable-rom-tracing

    Turns off tracing for all instructions executed from ROM.

  • --enable-fnop-tracing

    Turns on tracing of FNOP instructions.

  • --vcd-tracing args

    Enables signal tracing. The trace data is output in the standard VCD
    file format.

    If args contains any spaces, it must be enclosed in quotes. Its
    format is:

    global-optionsopt < -tile name <trace-options*>*>

    The global options are:

    • -pads

      Turns on pad tracing.

    • -o file

      Places output in file.

    The trace options are specific to the tile associated with the XN
    core declaration name, for example tile[0].

    The trace options are:

    • -ports

      Turns on port tracing.

    • -ports-detailed

      Turns on more detailed port tracing.

    • -cycles

      Turns on clock cycle tracing.

    • -clock-blocks

      Turns on clock block tracing.

    • -cores

      Turns on logical core tracing.

    • -instructions

      Turns on instruction tracing.

    To output traces from different nodes, tiles or logical cores to different
    files, this option can be specified multiple times.

    For example, the following command configures the simulator to trace
    the ports on tile[0] to the file trace.vcd.

    xsim a.xe –vcd-tracing “-o trace.vcd -start-disabled -tile tile[0] -ports”

    Tracing by the VCD plugin can be enabled and disabled using the
    _traceStart() and _traceStop() syscalls. The -start-disabled argument disables
    the vcd tracing from the start, allowing the user to enable/disable only those sections
    of code where tracing is desired. For example:

    #include <xs1.h>
    #include <syscall.h>
    
    port p1 = XS1_PORT_1A;
    
    int main() {
       p1 <: 1;
       p1 <: 0;
    
       _traceStart();
       p1 <: 1;
       p1 <: 0;
       _traceStop();
    
       p1 <: 1;
       p1 <: 0;
    
       return 0;
    }
    

Loopback Plugin Options

The XMOS Loopback plugin configures any two ports on the target platform
to be connected together. The format of the arguments to the plugin are:

  • -pin package pin

    Specifies the pin by its name on a package datasheet. The value of
    package must match the Id attribute of a Package node

    in the XN file used to compile the program.

  • -port name n offset

    Specifies n pins that correspond to a named port.

    The value of name must match the Name attribute of a
    Port node

    in the XN file used to compile the program.

    Setting offset to a non-zero value specifies a subset of the
    available pins.

  • -port tile p n offset

    Specifies n pins that are connected to the port p on a tile.

    The value of tile must match the Reference attribute of a
    Tile node
    in the XN file used to compile the program.

    p can be any of the port identifiers defined in <xs1.h>. Setting
    offset to a non-zero value specifies a subset of the available pins.

The plugin options are specified in pairs, one for each end of the
connection. For example, the following command configures the simulator
to loopback the pin connected to port XS1_PORT_1A on tile[0]
to the pin defined by the port UART_TX in the program.

xsim uart.xe –plugin LoopbackPort.dll ‘-port tile[0] XS1_PORT_1A 1 0 -port UART_TX 1 0’

xSCOPE Options

  • --xscope args

    Enables xSCOPE.
    file format.

    If args contains any spaces, it must be enclosed in quotes.
    One of the following 2 options is mandatory:

    • -offline <filename>

      Runs with xSCOPE in offline mode, placing the xSCOPE output in the given file.

    • -realtime <URL:port>

      Runs with xSCOPE in realtime mode, sending the xSCOPE output in the given URL:port.

    The following argument is optional:

    • -limit <num records>

      Limts the xSCOPE output records to the given number.

For example, the following will run xsim with xSCOPE enabled in offline mode:

xsim app.xe –xscope “-offline xscope.xmt”

For example, the following will run xsim with xSCOPE enabled in reatime mode:

xsim app.xe –xscope “-realtime localhost:12345”

DFU loader for XMOS USB AUDIO devices

The DFU loader is a flash device firmware upgrade mechanism. To work correctly
your development board must contain the latest DFU enabled firmware.

The firmware upgrade for XMOS USB devices implementation uses the USB standard
DFU device class mechanism and is based on the following specification:
http://www.usb.org/developers/devclass_docs/DFU_1.1.pdf

Supported functionality:

  • Download of new firmware to device
  • Upload of existing firmware from device
  • Revert device back to factory image
  • Automatic reboot of device on firmware upgrade

You must use XMOS Development Tools version 10.4.1 (or later).

The DFU device on Windows requires the Theyscon USB Audio 2.0 Windows driver
version 1.13.3 or later.

Installing the factory image to the device

The DFU device interface is enabled by default in the XMOS USB Audio framework
(see devicedefines.h), and explicitly enabled in each reference design
by the following line included in the customdefines.h file of each
application:

#define DFU                (1)

Use the XMOS Development Tools to run the command:

xflash --boot-partition-size 0x30000 --factory usb_audio.xe

Where the size passed using the --boot-partition-size n argument specifies
in bytes the minimum size required to store the boot loader, factory image and
any upgrade images.

The following can be used as a guide to help calculate the required boot
partition size for a design:

  • boot partition size = loader size + maximum size of factory image +
    maximum size of upgrade images + padding to sector boundaries

Where:

  • loader size = 0x1000 bytes, or 0x4000 bytes if secure boot functionality is
    used (for tools version 13.1.0 and older)
  • maximum size of factory image = number of xCORE tiles *
    xCORE SRAM size
  • maximum size of upgrade images = (number of xCORE tiles *
    xCORE SRAM size) * number of images to be held in flash concurrently

The above example sets the boot partition to a size appropriate for designs
based on a single xCORE tile, where a single upgrade image is required
in flash at any one time.

This programs the factory default firmware image into the flash device.
The device will now support the DFU mechanism, and can use it to safely receive
firmware updates, as well as revert to the factory firmware image when required,
such as in the event of a failed upgrade attempt.

Creating the upgrade image

To use the firmware upgrade mechanism you need to build a firmware upgrade
image:

  1. Edit the customdefines.h file of the application for the hardware in use,
    and change the Device Version Number by defining BCD_DEVICE.
  2. Rebuild the application.

To generate the firmware upgrade image run the following command:

xflash --factory-version 13 --upgrade 1 usb_audio.xe -o new_firmware.bin

Where the tools version passed using the --factory-version version
argument specifies the version of the tools used to create the factory image.
This should be passed as 12 for images created using tools versions 10, 11
and 12.

The --upgrade id xe-file [size] argument specifies xe-file as an upgrade
image with version id. Each version number must be a unique number greater
than 0.

You should now have the file new_firmware.bin which contains the
firmware with the newly specified Device Version Number.

For further details of the DFU features included in the XMOS USB Audio
framework and their configuration please see the Device Firmware Upgrade (DFU)

and the Configuration Defines
sections of the USB Audio Design
Guide.

For further details on the use of XFLASH to create factory and upgrade firmware
images please see the XFLASH Command-Line Manual section of the
xTIMEcomposer User Guide
.

Thesycon provide both GUI and CLI DFU tools, TUSBAudioDfu.exe and dfucons.exe
respectively. The use of the GUI tool is not covered by this document.

The correct installation of the Thesycon driver and DFU tools exceeds
the scope of this document.

Set up the image loader

Run the DFU console tool (dfucons.exe) from the Thesycon install folder,
in a Command Prompt by navigating to:

C:\Program Files\Thesycon\TUSBAudio_Driver\

To check the device has been detected, run the following command in the DFU
console:

dfucons info

The console shows the DFU devices that have been detected.

Download new firmware

To program the new firmware run the command:

dfucons download new_firmware.bin

Note that once this is done the device restarts. The original factory default
application is still present but the device is now running the upgraded
application firmware.

You can check the device has been updated by running the command:

dfucons info

This will display the device revision.

Uploading existing firmware from the device

You can retrieve a firmware image from the device, providing an upgrade image is
present.
Run the command:

dfucons upload currentfirmware.bin

The file currentfirmware.bin contains the latest upgrade image. This file is
an exact copy of the data from the flash and can be downloaded to the device
again to test.

Reverting firmware to factory image

To revert the device back to its factory (i.e XFLASH) installed state from the
new firmware, run the command:

dfucons revertfactory

The device will now be running, and only contain the factory firmware, which can
be seen by checking the device version once more.

For further details on the use of the Thesycon DFU tools please see
Thesycon USB Audio 2.0 Driver for Windows User Manual
.

The XMOS DFU loader is provided as source as part of the XMOS USB Audio software
framework, see Building the XMOS DFU loader – OS X
.

Set up the image loader

  1. Open a terminal
  2. Change directory to where the loader has been built
  3. Run the command:

    source setup.sh

Download new firmware

To program the new firmware run the command:

./xmosdfu --download new_firmware.bin

Note that once this is done the device restarts. The original factory default
application is still present but the device is now running the upgraded
application firmware.

Uploading existing firmware from the device

You can retrieve a firmware image from the device, providing an upgrade image is
present.

Run the command:

./xmosdfu --upload currentfirmware.bin

The file currentfirmware.bin contains the latest upgrade image. This file is
an exact copy of the data from the flash and can be downloaded to the device
again to test.

Reverting firmware to factory image

To revert the device back to its factory (i.e XFLASH) installed state from the
new firmware, run the command:

./xmosdfu --revertfactory

The device will now be running, and only contain the factory firmware.

The XMOS DFU loader is provided as source as part of the USB Audio
framework, located in sc_usb_audio/module_dfu/host/xmos_dfu_osx.

The loader is compiled using libusb, the code for the loader is contained in the
file xmosdfu.cpp

To build the loader a Makefile is provided, which can be run as follows:

make -f Makefile.OSX all

This Makefile contains the following:

all:
	g++ -g -o xmosdfu xmosdfu.cpp -I. -IOSX libusb-1.0.0.dylib -m32

XMOS USB Device (XUD) Library

This document details the XMOS USB Device (XUD) Library. This library
enables the development of USB 2.0 devices on the XMOS xCORE architecture.

This document describes the structure of the library, its basic use
and resources required.

This document assumes familiarity with the XMOS xCORE architecture, the
Universal Serial Bus 2.0 Specification (and related specifications),
the XMOS tool chain and XC language.

The XUD library allows the implementation of both full-speed and
high-speed USB 2.0 devices on L-Series, G-series and U-Series devices.

For the L and G series the implementation requires the use of an
external ULPI transceiver such as the SMSC USB33XX range. U-Series
devices include an integrated USB transceiver. Three libraries, with
identical API, are provided – one each for L, G and U-Series
devices.

Please note, G-series is not recommended for new designs.

The library performs all the low-level I/O operations required to meet
the USB 2.0 specification. This processing goes up to and includes the
transaction level. It removes all low-level timing requirements from the
application, allowing quick development of all manner of USB devices.

The XUD library runs in a single core with endpoint and application
cores communicating with it via a combination of channel communication
and shared memory variables.

One channel is required per IN or OUT endpoint. Endpoint 0 (the control
endpoint) requires two channels, one for each direction. Please note that
throughout this document the USB nomenclature is used: an OUT endpoint
is used to transfer data from the host to the device, an IN endpoint is
used when the host requests data from the device.

An example task diagram is shown in XUD Overview
. Circles
represent cores running with arrows depicting communication
channels between these cores. In this configuration there is one
core that deals with endpoint 0, which has both the input and output
channel for endpoint 0. IN endpoint 1 is dealt with by a second core,
and OUT endpoint 2 and IN endpoint 5 are dealt with by a third core.
Cores must be ready to communicate with the XUD library whenever the
host demands its attention. If not, the XUD library will NAK.

It is important to note that, for performance reasons, cores
communicate with the XUD library using both XC channels and shared
memory communication. Therefore, all cores using the XUD library must
be on the same tile as the library itself
.

XUD Overview

The following list gives a brief description of the files that make up
the XUD layer:

include/xud.h

User defines and functions for the XUD library.

lib/xs1b/libxud_l.a

Library for L-Series devices.

lib/xs1b/libxud_u.a

Library for U-Series devices.

lib/xs1b/libxud_g.a

Library for G-Series devices.

src/XUD_EpFunctions.xc

User functions that control the XUD library.

src/XUD_EpFuncs.S

Assembler stubs of access functions.

src/XUD_Ports.xc

Definition of port mapping.

The XUD library requires the resources described in the following
sections.

Ports/Pins

G/L-Series

The ports used for the physical connection to the external ULPI transceiver must
be connected as shown in the table below.

ULPI required pin/port connections

Pin 1b

Port 4b

Signal 8b

X0D12

P1E0

 

ULPI_STP

X0D13

P1F0

 

ULPI_NXT

X0D14

 

P4C0

P8B0

ULPI_DATA[7:0]

X0D15

P4C1

P8B1

X0D16

P4D0

P8B2

X0D17

P4D1

P8B3

X0D18

P4D2

P8B4

X0D19

P4D3

P8B5

X0D20

P4C2

P8B6

X0D21

P4C3

P8B7

X0D22

P1G0

 

ULPI_DIR

X0D23

P1H0

 

ULPI_CLK

X0D24

P1I0

 

ULPI_RST_N

In addition some ports are used internally when the XUD library is in
operation. For example pins X0D2-X0D9, X0D26-X0D33 and X0D37-X0D43 on
an XS1-L device should not be used.

Please refer to the device datasheet for further information on which ports
are available.

U-Series

The U-Series of devices have an integrated USB transceiver. Some ports
are used to communicate with the USB transceiver inside the U-Series packages.
These ports/pins should not be used when USB functionality is enabled.
The ports/pins are shown in the table below.

U-Series required pin/port connections

Pin 1b

Port 4b

X0D02

 

P4A0

P8A0

P16A0

P32A20

X0D03

 

P4A1

P8A1

P16A1

P32A21

X0D04

 

P4B0

P8A2

P16A2

P32A22

X0D05

 

P4B1

P8A3

P16A3

P32A23

X0D06

 

P4B2

P8A4

P16A4

P32A24

X0D07

 

P4B3

P8A5

P16A5

P32A25

X0D08

 

P4A2

P8A6

P16A6

P32A26

X0D09

 

P4A3

P8A7

P16A7

P32A27

X0D23

P1H0

 

X0D25

P1J0

 

X0D26

 

P4E0

P8C0

P16B0

 

X0D27

 

P4E1

P8C1

P16B1

 

X0D28

 

P4F0

P8C2

P16B2

 

X0D29

 

P4F1

P8C3

P16B3

 

X0D30

 

P4F2

P8C4

P16B4

 

X0D31

 

P4F3

P8C5

P16B5

 

X0D32

 

P4E2

P8C6

P16B6

 

X0D33

 

P4E3

P8C7

P16B7

 

X0D34

P1K0

 

X0D36

P1M0

 

P8D0

P16B8

 

X0D37

P1N0

 

P8C1

P16B1

 

X0D38

P1O0

 

P8C2

P16B2

 

X0D39

P1P0

 

P8C3

P16B3

 

Core Speed

Due to I/O requirements, the library requires a guaranteed MIPS rate to
ensure correct operation. This means that core count restrictions must
be observed. The XUD core must run at at least 80 MIPS.

This means that for an xCORE device running at 400MHz there should be no more
than five cores executing at any time when using the XUD. For
a 500MHz device no more than six cores shall execute at any one time
when using the XUD.

This restriction is only a requirement on the tile on which the XUD_Manager is running.
For example, the other tile on an L16 device is unaffected by this restriction.

Clock Blocks

G/L-Series

The XUD library uses one clock block (clock block 0) and configures this
clock block to be clocked by the 60MHz clock from the ULPI transceiver.
The ports it uses are in turn clocked from the clock block.

Since clock block 0 is the default for all ports when enabled it is
important that if a port is not required to be clocked from this 60MHz
clock, then it is configured to use another clock block.

U-Series

The XUD library uses two clock blocks (clock blocks 4 and 5). These are
clocked from the USB clock. Unlike the G/L devices, clock-block 0 is not
used or affected.

Timers

The XUD library allocates and uses four timers.

Memory

The XUD library requires about 9 Kbytes of memory, of which around 6 Kbytes
is code or initialized variables that must be stored in either OTP or
Flash.

This section outlines the basic usage of XUD. Basic use is termed to
mean each endpoint runs in its own dedicated core.
Multiple endpoints in a single core are possible, please see Advanced Usage.

XUD Core: XUD_Manager()

This is the main XUD task that interfaces with the USB transceiver.
It performs power-signalling/handshaking on the USB bus, and passes packets
to/from the various endpoints.

This function should be called directly from the top-level par
statement in main() to ensure that the XUD library is ready
within the 100ms allowed by the USB specification.

  • int XUD_Manager(chanend c_epOut[], int noEpOut, chanend c_epIn[], int noEpIn, chanend ?c_sof, XUD_EpType epTypeTableOut[], XUD_EpType epTypeTableIn[], out port ?p_usb_rst, clock ?clk, unsigned rstMask, XUD_BusSpeed_t desiredSpeed, XUD_PwrConfig pwrConfig)

    This performs the low-level USB I/O operations.

    Note that this needs to run in a thread with at least 80 MIPS worst case execution speed.

    Parameters

    • c_epOut

      An array of channel ends, one channel end per output endpoint (USB OUT transaction); this includes a channel to obtain requests on Endpoint 0.

    • noEpOut

      The number of output endpoints, should be at least 1 (for Endpoint 0).

    • c_epIn

      An array of channel ends, one channel end per input endpoint (USB IN transaction); this includes a channel to respond to requests on Endpoint 0.

    • noEpIn

      The number of input endpoints, should be at least 1 (for Endpoint 0).

    • c_sof

      A channel to receive SOF tokens on. This channel must be connected to a process that can receive a token once every 125 ms. If tokens are not read, the USB layer will lock up. If no SOF tokens are required null should be used for this parameter.

    • epTypeTableOut

      See epTypeTableIn.

    • epTypeTableIn

      This and epTypeTableOut are two arrays indicating the type of the endpoint. Legal types include: XUD_EPTYPE_CTL (Endpoint 0), XUD_EPTYPE_BUL (Bulk endpoint), XUD_EPTYPE_ISO (Isochronous endpoint), XUD_EPTYPE_INT (Interrupt endpoint), XUD_EPTYPE_DIS (Endpoint not used). The first array contains the endpoint types for each of the OUT endpoints, the second array contains the endpoint types for each of the IN endpoints.

    • p_usb_rst

      The port to used to connect to an external phy reset line. Should be null for U-Series.

    • clk

      The clock block to use for the p_usb_rst port – this should not be clock block 0. Should be null for U-Series.

    • rstMask

      The mask to use when taking an external phy into/out of reset. The mask is ORed into the port to disable reset, and unset when deasserting reset. Use ‘-1’ as a default mask if this port is not shared.

    • desiredSpeed

      This parameter specifies what speed the device will attempt to run at i.e. full-speed (ie 12Mbps) or high-speed (480Mbps) if supported by the host. Pass XUD_SPEED_HS if high-speed is desired or XUD_SPEED_FS if not. Low speed USB is not supported by XUD.

    • pwrConfig

      Specifies whether the device is bus or self-powered. When self-powered the XUD will monitor the VBUS line for host disconnections. This is required for compliance reasons. Valid values are XUD_PWR_SELF and XUD_PWR_BUS.

Endpoint Type Table

The endpoint type table should take an array of XUD_EpType to inform XUD
about endpoints being used. This is mainly used to indicate the transfer-type
of each endpoint (bulk, control, isochronous or interrupt) as well as
whether the endpoint wishes to be informed about bus-resets (see Status Reporting
).

Note: endpoints can also be marked as disabled.

Endpoints that are not used will NAK any traffic from the host.

PwrConfig

The PwrConfig parameter to XUD_Manager() indicates if the device is bus or self-powered.

Valid values for this parameter are XUD_PWR_SELF and XUD_PWR_BUS.

When XUD_PWR_SELF is used, XUD_Manager() monitors the VBUS input for a valid voltage and reponds appropriately. The USB Specification states that the devices pull-ups must be disabled when a valid VBUS is not present. This is important when submitting a device for compliance testing since this is explicitly tested.

If the device is bus-powered XUD_PWR_SELF can be used since is assumed that the device is not powered up when VBUS is not present and therefore no voltage monitoring is required. In this configuration the VBUS input to the device/PHY need not be present.

XUD_PWR_BUS can be used in order to run on a self-powered board without provision for VBUS wiring to the PHY/device, but this is not advised.

Endpoint Communication with XUD_Manager()

Communication state between a core and the XUD library is encapsulated
in an opaque type:

  • XUD_ep

    Typedef for endpoint identifiers.

All client calls communicating with the XUD library pass in this type.
These data structures can be created at the start of execution of a
client core with the following call that takes as an argument the
endpoint channel connected to the XUD library:

  • XUD_ep XUD_InitEp(chanend c_ep)

    Initialises an XUD_ep.

    Parameters

    • c_ep

      Endpoint channel to be connected to the XUD library.

    Returns

    Endpoint identifier

Endpoint data is sent/received using three main functions,
XUD_SetData(), XUD_GetData() and XUD_GetSetupData().

These assembly functions implement the low-level shared memory/channel
communication with the XUD_Manager() core. For developer convenience
these calls are wrapped up by XC functions.

These functions will automatically deal with any low-level complications required
such as Packet ID toggling etc.

XUD_GetBuffer()

  • XUD_Result_t XUD_GetBuffer(XUD_ep
     ep_out, unsigned char buffer[], unsigned &length)

    This function must be called by a thread that deals with an OUT endpoint.

    When the host sends data, the low-level driver will fill the buffer. It pauses until data is available.

    Parameters

    • ep_out

      The OUT endpoint identifier (created by XUD_InitEP).

    • buffer

      The buffer in which to store data received from the host. The buffer is assumed to be word aligned.

    • length

      The number of bytes written to the buffer

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting
    .

XUD_SetBuffer()

  • XUD_Result_t XUD_SetBuffer(XUD_ep
     ep_in, unsigned char buffer[], unsigned datalength)

    This function must be called by a thread that deals with an IN endpoint.

    When the host asks for data, the low-level driver will transmit the buffer to the host.

    Parameters

    • ep_in

      The endpoint identifier (created by XUD_InitEp).

    • buffer

      The buffer of data to transmit to the host.

    • datalength

      The number of bytes in the buffer.

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting
    .

XUD_SetBuffer_EpMax()

This function provides a similar function to XUD_SetBuffer function
but it breaks the data up in packets of a fixed
maximum size. This is especially useful for control transfers where large
descriptors must be sent in typically 64 byte transactions.

  • XUD_Result_t XUD_SetBuffer_EpMax(XUD_ep
     ep_in, unsigned char buffer[], unsigned datalength, unsigned epMax)

    Similar to XUD_SetBuffer but breaks up data transfers into smaller packets.

    This function must be called by a thread that deals with an IN endpoint. When the host asks for data, the low-level driver will transmit the buffer to the host.

    Parameters

    • ep_in

      The IN endpoint identifier (created by XUD_InitEp).

    • buffer

      The buffer of data to transmit to the host.

    • datalength

      The number of bytes in the buffer.

    • epMax

      The maximum packet size in bytes.

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting
    .

XUD_DoGetRequest()

  • XUD_Result_t XUD_DoGetRequest(XUD_ep
     ep_out, XUD_ep
     ep_in, unsigned char buffer[], unsigned length, unsigned requested)

    Performs a combined XUD_SetBuffer and XUD_GetBuffer.

    It transmits the buffer of the given length over the ep_in endpoint to answer an IN request, and then waits for a 0 length Status OUT transaction on ep_out. This function is normally called to handle Get control requests to Endpoint 0.

    Parameters

    • ep_out

      The endpoint identifier that handles Endpoint 0 OUT data in the XUD manager.

    • ep_in

      The endpoint identifier that handles Endpoint 0 IN data in the XUD manager.

    • buffer

      The data to send in response to the IN transaction. Note that this data is chopped up in fragments of at most 64 bytes.

    • length

      Length of data to be sent.

    • requested

      The length that the host requested, (Typically pass the value wLength).

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting

XUD_DoSetRequestStatus()

  • XUD_Result_t XUD_DoSetRequestStatus(XUD_ep
     ep_in)

    This function sends an empty packet back on the next IN request with PID1.

    It is normally used by Endpoint 0 to acknowledge success of a control transfer.

    Parameters

    • ep_in

      The Endpoint 0 IN identifier to the XUD manager.

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting
    .

XUD_SetDevAddr()

  • XUD_Result_t XUD_SetDevAddr(unsigned addr)

    Sets the device’s address.

    This function must be called by Endpoint 0 once a setDeviceAddress request is made by the host.

    Must be run on USB core

    Parameters

    • addr

      New device address.

XUD_SetStall()

  • void XUD_SetStall(XUD_ep
     ep)

    Mark an endpoint as STALLed.

    It is cleared automatically if a SETUP received on the endpoint.

    Must be run on same tile as XUD core

    Parameters

    • ep

      XUD_ep type.

XUD_SetStallByAddr()

  • void XUD_SetStallByAddr(int epNum)

    Mark an endpoint as STALL based on its EP address.

    Cleared automatically if a SETUP received on the endpoint. Note: the IN bit of the endpoint address is used.

    Must be run on same tile as XUD core

    Parameters

    • epNum

      Endpoint number.

XUD_ClearStall()

  • void XUD_ClearStall(XUD_ep
     ep)

    Mark an endpoint as NOT STALLed.

    Must be run on same tile as XUD core

    Parameters

    • ep

      XUD_ep type.

XUD_ClearStallByAddr()

  • void XUD_ClearStallByAddr(int epNum)

    Mark an endpoint as NOT STALLed based on its EP address.

    Note: the IN bit of the endpoint address is used.

    Must be run on same tile as XUD core

    Parameters

    • epNum

      Endpoint number.

Status Reporting

Status reporting on an endpoint can be enabled so that bus state is
known. This is achieved by ORing XUD_STATUS_ENABLE into the relevant
endpoint in the endpoint type table.

This means that endpoints are notified of USB bus resets (and
bus-speed changes). The XUD access functions discussed previously
(XUD_GetData, XUD_SetData, etc.) return XUD_RES_RST if
a USB bus reset is detected.

This reset notification is important if an endpoint core is expecting
alternating INs and OUTs. For example, consider the case where an
endpoint is always expecting the sequence OUT, IN, OUT (such as a control
transfer). If an unplug/reset event was received after the first OUT,
the host would return to sending the initial OUT after a replug, while
the endpoint would hang on the IN. The endpoint needs to know of the bus
reset in order to reset its state machine.

Endpoint 0 therefore requires this functionality since it deals with
bi-directional control transfers.

This is also important for high-speed devices, since it is not
guaranteed that the host will detect the device as a high-speed device.
The device therefore needs to know what bus-speed it is currently running at.

After a reset notification has been received, the endpoint must call the
XUD_ResetEndpoint() function. This will return the current bus
speed.

XUD_ResetEndpoint()

  • XUD_BusSpeed_t XUD_ResetEndpoint(XUD_ep
     one, XUD_ep
     &?two)

    This function will complete a reset on an endpoint.

    Can take one or two XUD_ep as parameters (the second parameter can be set to null). The return value should be inspected to find the new bus-speed. In Endpoint 0 typically two endpoints are reset (IN and OUT). In other endpoints null can be passed as the second parameter.

    Parameters

    • one

      IN or OUT endpoint identifier to perform the reset on.

    • two

      Optional second IN or OUT endpoint structure to perform a reset on.

    Returns

    Either XUD_SPEED_HS – the host has accepted that this device can execute at high speed, or XUD_SPEED_FS – the device is runnig at full speed.

SOF Channel

An application can pass a channel-end to the c_sof parameter of
XUD_Manager(). This will cause a word of data to be output every time
the device receives a SOF from the host. This can be used for timing
information for audio devices etc. If this functionality is not required
null should be passed as the parameter. Please note, if a channel-end
is passed into XUD_Manager() there must be a responsive task ready to
receive SOF notifications otherwise the XUD_Manager() task will be
blocked attempting to send these messages.

USB Test Modes

XUD supports the required test modes for USB Compliance testing.

XUD accepts commands from the endpoint 0 channels (in or out) to signal which test mode
to enter via the XUD_SetTestMode() function. The commands are based on the definitions
of the Test Mode Selector Codes in the USB 2.0 Specification Table 11-24. The supported test modes are
summarised in the table below.

Supported Test Mode Selector Codes

Value

Test Mode Description

1

Test_J

2

Test_K

3

Test_SE0_NAK

4

Test_Packet

The passing other codes endpoints other than 0 to XUD_SetTestMode() could result in undefined
behaviour.

As per the USB 2.0 Specification a power cycle or reboot is required to exit the test mode.

XUD_SetTestMode()

  • void XUD_SetTestMode(XUD_ep
     ep, unsigned testMode)

    Enable a specific USB test mode in XUD.

    Must be run on same tile as XUD core

    Parameters

    • ep

      XUD_ep type (must be endpoint 0 in or out)

    • testMode

      The desired test-mode

Advanced usage is termed to mean the implementation of multiple endpoints in a single core as well as the addition of real-time processing to an endpoint core.

The functions documented in Basic Usage such as XUD_SetBuffer() and XUD_GetBuffer() block until data has either been successfully sent or received to or from the host. For this reason it is not generally possible to handle multiple endpoints in a single core efficiently (or at all, depending on the protocols involved).

The XUD library therefore provides functions to allow the separation of requesting to send/receive a packet and the notification of a successful transfer. This is based on the XC select statement language feature.

General operation is as follows:

  • An XUD_SetReady_ function is called to mark an endpoint as ready to send or receive data
  • An select statement is used, along with a select handler to wait for, and capture, send/receive notifications from the XUD_Manager core.

The available XUD_SetReady_ functions are listed below.

XUD_SetReady_Out()

  • int XUD_SetReady_Out(XUD_ep
     ep, unsigned char buffer[])

    Marks an OUT endpoint as ready to receive data.

    Parameters

    • ep

      The OUT endpoint identifier (created by XUD_InitEp).

    • buffer

      The buffer in which to store data received from the host. The buffer is assumed to be word aligned.

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting.

XUD_SetReady_In()

  • XUD_Result_t XUD_SetReady_In(XUD_ep
     ep, unsigned char buffer[], int len)

    Marks an IN endpoint as ready to transmit data.

    Parameters

    • ep

      The IN endpoint identifier (created by XUD_InitEp).

    • buffer

      The buffer to transmit to the host. The buffer is assumed be word aligned.

    • len

      The length of the data to transmit.

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting.

The following functions are also provided to ease integration with more complex buffering schemes than a single packet buffer. A example might be a circular-buffer for an audio stream.

XUD_SetReady_OutPtr()

  • int XUD_SetReady_OutPtr(XUD_ep
     ep, unsigned addr)

    Marks an OUT endpoint as ready to receive data.

    Parameters

    • ep

      The OUT endpoint identifier (created by XUD_InitEp).

    • addr

      The address of the buffer in which to store data received from the host. The buffer is assumed to be word aligned.

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting.

XUD_SetReady_InPtr()

  • XUD_Result_t XUD_SetReady_InPtr(XUD_ep
     ep, unsigned addr, int len)

    Marks an IN endpoint as ready to transmit data.

    Parameters

    • ep

      The IN endpoint identifier (created by XUD_InitEp).

    • addr

      The address of the buffer to transmit to the host. The buffer is assumed be word aligned.

    • len

      The length of the data to transmit.

    Returns

    XUD_RES_OKAY on success, for errors see Status Reporting.

Once an endpoint has been marked ready to send/receive by calling one of the above XUD_SetReady_ functions, an XC select statement can be used to handle notifications of a packet being sent/received from XUD_Manager(). These notifications are communicated via channels.

For convenience, select handler functions are provided to handle events in the select statement. These are documented below.

XUD_GetData_Select()

  • void XUD_GetData_Select(chanend c, XUD_ep
     ep, unsigned &length, XUD_Result_t &result)

    Select handler function for receiving OUT endpoint data in a select.

    Parameters

    • c

      The chanend related to the endpoint

    • ep

      The OUT endpoint identifier (created by XUD_InitEp).

    • length

      Passed by reference. The number of bytes written to the buffer,

    • result

      XUD_Result_t passed by reference. XUD_RES_OKAY on success, for errors see Status Reporting.

XUD_SetData_Select()

  • void XUD_SetData_Select(chanend c, XUD_ep
     ep, XUD_Result_t &result)

    Select handler function for transmitting IN endpoint data in a select.

    Parameters

    • c

      The chanend related to the endpoint

    • ep

      The IN endpoint identifier (created by XUD_InitEp).

    • result

      Passed by reference. XUD_RES_OKAY on success, for errors see Status Reporting.

Example

A simple example of the functionality described in this section is shown below:


void ExampleEndpoint(chanend c_ep_out, chanend c_ep_in)
{
    unsigned char rxBuffer[1024];
    unsigned char txBuffer[] = {0, 1, 2, 3, 4};
    int length, returnVal;


    XUD_ep ep_out = XUD_InitEp(c_ep_out);
    XUD_ep ep_in = XUD_InitEp(c_ep_in);

    /* Mark OUT endpoint as ready to receive */
    XUD_SetReady_Out(ep_out, rxBuffer);
    XUD_SetReady_In(ep_in, txBuffer, 5);

    while(1)
    {
        select
        {
            case XUD_GetData_Select(c_ep_out, ep_out, length):

                /* Packet from host recieved */

                for(int i = 0; i< length; i++)
                {
                    /* Process packet... */
                }

                /* Mark EP as ready again */
                XUD_SetReady_Out(ep_out, rxBuffer);
                break;
                
            case XUD_SetData_Select(c_ep_in, ep_in, returnVal):

                /* Packet successfully sent to host */
        
                /* Create new buffer */
                for(int i = 0; i < 5; i++)
                {
                    txBuffer[i]++;
                }

                /* Mark EP as ready again */
                XUD_SetReady_In(ep_in, txBuffer, 5);
                break;

        }
    }
}
//:

The following documents provide further reading regarding programming USB devices on XMOS platforms:

  • XMOS USB Device Design Guide
  • HID Class USB Device Quick Start Guide
  • USB Custom Bulk Device Quick Start Guide

Version history for this document.

Date

Version

Comment

2014-05-16

2.1

Updates to related to enabling test modes

2014-03-18

2.0

Added XUD_Result_t to API documentation
Added Further Reading section

2014-01-29

1.2

Minor updates. Added Advanced Usage and PwrConfig sections

2013-04-23

1.1

API updates and changes to Standard Request handling

2011-01-06

1.0

Updates for API changes

2010-07-22

1.0b

Beta Release

XS1-L Hardware Design Checklist

The XS1-L Hardware Design Checklist is no longer available. Please refer to the device datasheets, which contain appendices with PCB layout and schematic design checklists.

XTAG-2 Quick Start Guide

Version: 1.1        Date: 2010-09-15 Download Version Released Comments 1.1 2010-09-15 download

Scroll to Top