No USB? No Problem!

Grainuum: A software-only USB stack for 48 MHz ARM Cortex M0+ CPUs.

Created by Sean Cross / @xobs

Talk Outline

Why do this thing?
How it's made
What now?

About me

Takeaways

A better understanding low-level USB
Tricks to improve your embedded programming
Know what's important and what's not

Why do this thing?

USB is easy*

*Easy for users, that is

C:\> SET BLASTER=A220 I5 D1

USB is Everywhere

Fernvale

Orchard (Burning Man)

Orchard (MIT)

Gaming Controllers

Project Palawan

Can it be done?

Other Software Stacks

Embedded hardware is a minefield

Special feature: Different D+/D- banks

USB LS signalling is 1.5 MHz

On a 48 MHz chip, that gives us 32 clock cycles per bit

The target CPU: Cortex-M0+ @ 48 MHz

Palawan

Palawan, running Grainuum USB stack

How it's made

Grainuum Architecture

This is the architectural overview of GrainuumUSB. There are lots and lots of books and sites available that describe the top part of this document, but not too many go into detail on the lower part. In this chart, the USB-PHY-LL is the only part written in assembler, and could be replaced with something else if we wanted to port this project to a different CPU or architecture. Everything else is C. We'll start below the bottom of the stack there, with USB electrical work. Then we'll move up to the USB low-level PHY, describe some of the USB PHY, mention the State, and generally gloss over the User Code.

USB Electrical

Palawan USB Schematic

Palawan USB Traces

Detecting USB

If we fab out this board and plug it into a USB port without loading any firmware on it, the pins float and that pullup resistor takes effect. This configuration is enough to convince the host that we're a real device, and it tries to talk to it. You can see the host detected this board as a USB Low Speed device. It then gives Error -32 messages. If we look that up, we see that it's EPIPE, which means a broken pipe. Indeed, the host is trying to access the Endpoint 0 pipe, which doesn't exist because there is no firmware yet. This error means that the hardware is looking good, and it's time to start on the firmware.

USB Signaling

States

Last part of a USB packet

States

K-state

States

J-state

States

SE0-state

States

SE1-state?

Decoding States

Transition	Value
J → J	0
J → K	1
K → J	1
K → K	0

8-bit preamble / sync at start of packet

Data section

SE0 signals EOP

Bit stuffing

Phy: What's important?

Important	Not Important
Timing and sync Bit stuffing Errors: keepalive framing overflow	6 bits to read sync Only check one wire Miss up to 3 packets

What about signal integrity?

Faster is not always better

What about signal integrity?

Using a 32.768 kHz Crystal

32768 × 1464 = 47.972352 MHz

Close enough!

Development System Setup

I'm going to take a break for a moment to describe the hardware that I use to develop this project. This is my development environment. It is a Raspberry Pi running OpenOCD. There are three wires running to the device being debugged: SWD, Clock, and a reset line. The reset line is optional, but it makes it easier to program devices that are brand-nes and unprogrammed. There aren't even any passive components, it's just a straight connection between the two devices. This is the cheapest solution we've found to do development on small embedded devices. Even better, it's cheap enough that if we want to have someone else help with development, this setup is cheap enough to mail to someone along with the hardware to dev on. The Raspberry Pi contians enough horsepower to run a C compiler in addition to OpenOCD, meaning all the person has to do to get up to speed on developing for an embedded device is to plug in a keyboard, mouse, and TV, and they're done. No drivers to set up, no proprietary JTAG boxes, no download links to compilers. If it works for me, it'll work for them.

Other Hardware

Low-Level API


int usbPhyReadI(struct GrainuumUSB *usb,
                uint8_t samples[11]);

void usbPhyWriteI(struct GrainuumUSB *usb,
                  const uint8_t buffer[11],
                  uint32_t count);grainuum-phy-ll.s

void grainuumCaptureI(struct GrainuumUSB *usb,
                      uint8_t packet[12]);grainuum-phy.c

Programming Tricks

Run from RAM to get cycle-accuracy

.section .ramtextgrainuum-phy-ll.s

  .data :
  {
    . = ALIGN(4);
    *(.data .data.*)
    . = ALIGN(4);
    *(.ramtext)
  } > ram AT > flashKL02Z32-app.ld

Use registers for storing data

        mov wpaddr, wdpclrreg             // 1 cycle
        ldr wnaddr, [sp, #0]              // 2 cycles
        ldr rval, [rreg]                  // 1 cycle (Single-cycle port)

Hook the writer to the reader for testing

Low-Level C API


void grainuumConnect(struct GrainuumUSB *usb);
void grainuumDisconnect(struct GrainuumUSB *usb);


void grainuumReceivePacket(struct GrainuumUSB *usb);      // (weak)


void grainuumCaptureI(struct GrainuumUSB *usb,
                      uint8_t packet[12]);

grainuum-phy.c

USB Packets

Reading: Responding

Tip: Clever array [mis]-alignment

Use GRAINUUM_BUFFERs

Frames: What's important?

Important	Not Important
Quick response Frame sequence Outgoing CRC-16 DATA0 vs DATA1	NAK allows for deferring No need to generate CRC-5 We can ignore CRC-16 Can ignore "address"

USB State Machine

USB 2.0 spec figure 8-32, © 2000 Compaq Computer Corporation, Hewlett-Packard Company, Intel Corporation, Lucent Technologies Inc., Microsoft Corporation, NEC Corporation, Koninklijke Philips Electronics N.V.

USB State Machine API

int grainuumSendData(struct GrainuumUSB *usb,
                     int epnum,
                     const void *data,
                     int size);

void grainuumProcess(struct GrainuumUSB *usb,
                     const uint8_t packet[12]);

grainuum-state.c

User Code

struct GrainuumConfig {
  get_usb_descriptor_t      getDescriptor;
  usb_set_config_num_t      setConfigNum;
  usb_get_buffer_t          getReceiveBuffer;
  usb_data_in_t             receiveData;
  usb_data_out_start_t      sendDataStarted;
  usb_data_out_finish_t     sendDataFinished;
  void                     *data;
};

Important	Not Important
getDescriptor getReceiveBuffer receiveData	setConfigNum sendDataStarted sendDataFinished *data

Setup process

Annoyance: Breaking into the debugger sometimes kills USB

Tip: Global variables are handy

int loop_count;
void loop(void) {
  loop_count++;
}

(gdb) load
'minimal.elf' has changed; re-reading symbols.
Loading section .text, size 0x1b0 lma 0x5900
Loading section .data, size 0x3a8 lma 0x5ab0
Start address 0x5938, load size 1368
Transfer rate: 5 KB/sec, 684 bytes/write.
(gdb) c
Continuing.
^C
Program received signal SIGINT, Interrupt.
0x0000141c in ?? ()
(gdb) p loop_count
$1 = 91
(gdb)

Tip: Easier debugging


(gdb) b chSysLockBreakpoint 1 at 0x3c (49 locations) 
(gdb) info break
Num     Type           Disp Enb Address    What
1       breakpoint     keep y   <MULTIPLE>
1.1                         y     0x0000003c <_vectors+60>
1.2                         y     0x00002030 in radioSend at ../os/ext/CMSIS/include/core_cmFunc.h:342
1.3                         y     0x000021ca in usb_worker_thread at ../os/ext/CMSIS/include/core_cmFunc.h:342
1.4                         y     0x00003018 in lockSystem at ../os/ext/CMSIS/include/core_cmFunc.h:342
1.5                         y     0x0000309a in suspendThread at ../os/ext/CMSIS/include/core_cmFunc.h:342
1.6                         y     0x000030da in suspendThreadTimeout at ../os/ext/CMSIS/include/core_cmFunc.h:342
...(gdb) c
Continuing.
Note: automatically using hardware breakpoints for read-only addresses.
Cannot insert hardware breakpoint 1.
...
Cannot insert hardware breakpoint 1.
Could not insert hardware breakpoints:
You may have requested too many hardware breakpoints/watchpoints.

(gdb)

Borrow from Javascript

#define debugger asm("bkpt #0")

uint8_t USB_Available(uint8_t ep) {

  if (rx_buffer_tail == rx_buffer_head) {
    debugger;
    return 0;
  }

  if (ep != rx_buffer_eps[rx_buffer_tail]) {
    debugger;
    return 0;
  }

  return 1;
}

What Now?

Possible Device Types

So what can we do?

Possible Device Types

[DFU?]

Possible Device Types

bcdTeapot = 0x0418;

USB HID devices are "easy"

HID is "easy" on Windows

HID Isn't Super Fast

= 800 bytes/sec

Current Project Status

Reliable bidirectional tranfers
Common codebase for multiple projects

Port: Palawan

ChibiOS, polling using system timer.

Port: Joyboot

Micah Scott / scanlime

Polling in main loop

Port: Love-to-Code

Tomorrow at 4pm

What About Multi-Threading?

(gdb) info thr
  Id   Target Id         Frame
  3    Thread 536871048 (USB poll thread : READY) chSchGoSleepS (
    newstate=newstate@entry=0 '\000') at ../os/rt/src/chschd.c:270
  2    Thread 536872776 (user code : CURRENT) 0x00004850 in can_use_pin (pin=<optimized out>)
    at arduino-io.c:116
* 1    Thread 536870228 (main : READY) 0x00004850 in can_use_pin (pin=<optimized out>)
    at arduino-io.c:116
(gdb)

Future work

Fully-functional updater
GUI for updating
More platform testing

Produce Palawan Hardware

...with functioning updater

I want to produce more Palawan hardware, but I know there will be bugs. So I need a way to update the firmware on it without requiring users to have a SWD box, or even a Raspberry Pi handy. I had basic HID support working a while ago, but it took a while to get more reliable, full-duplex communication going. If I can make sure the USB stack is reliable, then I can push an update in case someone experiences a bug. That way I can make it work as well for them as it works for me.

Thank You

Sean Cross / @xobs

http://grainuum.io/