USB device stack, with KL25Z fixes for USB 3.0 hosts and sleep/resume interrupt handling

Dependents:   frdm_Slider_Keyboard idd_hw2_figlax_PanType idd_hw2_appachu_finger_chording idd_hw3_AngieWangAntonioDeLimaFernandesDanielLim_BladeSymphony ... more

Fork of USBDevice by mbed official

This is an overhauled version of the standard mbed USB device-side driver library, with bug fixes for KL25Z devices. It greatly improves reliability and stability of USB on the KL25Z, especially with devices using multiple endpoints concurrently.

I've had some nagging problems with the base mbed implementation for a long time, manifesting as occasional random disconnects that required rebooting the device. Recently (late 2015), I started implementing a USB device on the KL25Z that used multiple endpoints, and suddenly the nagging, occasional problems turned into frequent and predictable crashes. This forced me to delve into the USB stack and figure out what was really going on. Happily, the frequent crashes made it possible to track down and fix the problems. This new version is working very reliably in my testing - the random disconnects seem completely eradicated, even under very stressful conditions for the device.


  • Overall stability improvements
  • USB 3.0 host support
  • Stalled endpoint fixes
  • Sleep/resume notifications
  • Smaller memory footprint
  • General code cleanup

Update - 2/15/2016

My recent fixes introduced a new problem that made the initial connection fail most of the time on certain hosts. It's not clear if the common thread was a particular type of motherboard or USB chip set, or a specific version of Windows, or what, but several people ran into it. We tracked the problem down to the "stall" fixes in the earlier updates, which we now know weren't quite the right fixes after all. The latest update (2/15/2016) fixes this. It has new and improved "unstall" handling that so far works well with diverse hosts.

Race conditions and overall stability

The base mbed KL25Z implementation has a lot of problems with "race conditions" - timing problems that can happen when hardware interrupts occur at inopportune moments. The library shares a bunch of static variable data between interrupt handler context and regular application context. This isn't automatically a bad thing, but it does require careful coordination to make sure that the interrupt handler doesn't corrupt data that the other code was in the middle of updating when an interrupt occurs. The base mbed code, though, doesn't do any of the necessary coordination. This makes it kind of amazing that the base code worked at all for anyone, but I guess the interrupt rate is low enough in most applications that the glitch rate was below anyone's threshold to seriously investigate.

This overhaul adds the necessary coordination for the interrupt handlers to protect against these data corruptions. I think it's very solid now, and hopefully entirely free of the numerous race conditions in the old code. It's always hard to be certain that you've fixed every possible bug like this because they strike (effectively) at random, but I'm pretty confident: my test application was reliably able to trigger glitches in the base code in a matter of minutes, but the same application (with the overhauled library) now runs for days on end without dropping the connection.

Stalled endpoint fixes

USB has a standard way of handling communications errors called a "stall", which basically puts the connection into an error mode to let both sides know that they need to reset their internal states and sync up again. The original mbed version of the USB device library doesn't seem to have the necessary code to recover from this condition properly. The KL25Z hardware does some of the work, but it also seems to require the software to take some steps to "un-stall" the connection. (I keep saying "seems to" because the hardware reference material is very sketchy about all of this. Most of what I've figured out is from observing the device in action with a Windows host.) This new version adds code to do the necessary re-syncing and get the connection going again, automatically, and transparently to the user.

USB 3.0 Hosts

The original mbed code sometimes didn't work when connecting to hosts with USB 3.0 ports. This didn't affect every host, but it affected many of them. The common element seemed to be the Intel Haswell chip set on the host, but there may be other chip sets affected as well. In any case, the problem affected many PCs from the Windows 7 and 8 generation, as well as many Macs. It was possible to work around the problem by avoiding USB 3.0 ports - you could use a USB 2 port on the host, or plug a USB 2 hub between the host and device. But I wanted to just fix the problem and eliminate the need for such workarounds. This modified version of the library has such a fix, which so far has worked for everyone who's tried.

Sleep/resume notifications

This modified version also contains an innocuous change to the KL25Z USB HAL code to handle sleep and resume interrupts with calls to suspendStateChanged(). The original KL25Z code omitted these calls (and in fact didn't even enable the interrupts), but I think this was an unintentional oversight - the notifier function is part of the generic API, and other supported boards all implement it. I use this feature in my own application so that I can distinguish sleep mode from actual disconnects and handle the two conditions correctly.

Smaller memory footprint

The base mbed version of the code allocates twice as much memory for USB buffers as it really needed to. It looks like the original developers intended to implement the KL25Z USB hardware's built-in double-buffering mechanism, but they ultimately abandoned that effort. But they left in the double memory allocation. This version removes that and allocates only what's actually needed. The USB buffers aren't that big (128 bytes per endpoint), so this doesn't save a ton of memory, but even a little memory is pretty precious on this machine given that it only has 16K.

(I did look into adding the double-buffering support that the original developers abandoned, but after some experimentation I decided they were right to skip it. It just doesn't seem to mesh well with the design of the rest of the mbed USB code. I think it would take a major rewrite to make it work, and it doesn't seem worth the effort given that most applications don't need it - it would only benefit applications that are moving so much data through USB that they're pushing the limits of the CPU. And even for those, I think it would be a lot simpler to build a purely software-based buffer rotation mechanism.)

General code cleanup

The KL25Z HAL code in this version has greatly expanded commentary and a lot of general cleanup. Some of the hardware constants were given the wrong symbolic names (e.g., EVEN and ODD were reversed), and many were just missing (written as hard-coded numbers without explanation). I fixed the misnomers and added symbolic names for formerly anonymous numbers. Hopefully the next person who has to overhaul this code will at least have an easier time understanding what I thought I was doing!


RevisionDateWhoCommit message
54:2e181d51495a 2017-03-17 mjr Comments default tip
53:c8110529c24b 2016-06-02 mjr Move SET_INTERFACE handling to callbacks; add some constants for documentation; cosmetic touchup
52:d9c520d4704b 2016-05-12 mjr Minor type change for in-ISR flag (int to bool)
51:666cc4fedd3f 2016-04-30 mjr Remove some testing code
50:946bc763c068 2016-04-27 mjr Error handling in the main code with the long explanation
49:03527ce6840e 2016-02-26 mjr const-ify all descriptors to reduce RAM footprint; use new/delete instead of malloc/free to facilitate replacing global allocator
48:b225d025ca1d 2016-02-15 mjr Merge fixes for compatibility problems introduced in USBHAL_Kl25Z overhaul
47:c91e6d7762e4 2016-02-11 mjr Rollback #6 for finding regression
46:619abb369032 2016-02-10 mjr Rollback #5A - fix typo in #5
45:cbf071a0aa62 2016-02-10 mjr Rollback #5 to find regression
44:42bf0aeff6a3 2016-02-10 mjr Rollback #4 to find regression;
43:cd7742a91b58 2016-02-10 mjr Change rollback to find regression #3
42:06345d5ae2e6 2016-02-09 mjr Another rollback to find compatibility problem;
41:bd8b29a6ba76 2016-02-08 mjr Roll back some changes to try to find compatibility problems in new version
40:cd877d5c09ea 2016-02-03 mjr Fix ISTAT updates (assign bits directly, rather than OR masking - OR masking incorrectly clears other currently set bits);
39:d684a8ce5d88 2016-01-16 mjr A few more tweaks.
38:072e12583e73 2016-01-12 mjr Further KL25Z USB HAL cleanup: regularized the ISR callback handlers and fixed a typo.
37:c5ac4ccf6597 2016-01-11 mjr Fixed numerous race conditions and other bugs in KL25Z USB HAL.
36:20bb47609697 2016-01-05 mjr Fix race conditions
35:53e1a208f582 2015-12-25 mjr Race condition changes;
34:884405d998bb 2015-12-24 mjr Fixed several bugs in the KL25Z USB HAL
33:b0a3f6b27b07 2015-12-19 mjr Allow for multiple HID interfaces in GET_DESCRIPTOR messages
32:a8eb758f4074 2014-08-23 mjr Added timeout-limited writeTO() call
31:81f57ea86f8f 2014-07-27 mjr Notify upper layers of a bus reset; return false on ControlOut sync to try to fix reconnect issue (unsuccessful)
30:2f8f4c3822a1 2014-07-25 mjr Changed conditional inclusion of Freescale USB 3.0 bug fix to include all KLxx boards
29:b502c11a3dff 2014-07-25 mjr Revised USB 3.0 port fix to send zero-length reply
28:0596f144dad5 2014-07-24 mjr Fixed USB client connection problem on KL25Z with USB 3.0 ports on machines with Haswell chip sets (some Macs, Win 7, and Win 8). Added SUSPEND and RESUME interrupt handling to KL25Z, with calls to suspendStateChanged().
27:0c6524151939 2014-06-18 mbed_official Synchronized with git revision 2a4bbdfe4f273f3b7371abaf0280a109cb27fb1f
26:8ef73dd868a0 2014-06-12 mbed_official Synchronized with git revision 0b5a92fbc54f70168b85f7a58bab07c5b787ab13
25:7c72828865f3 2014-06-03 mbed_official Synchronized with git revision bcacbb9fbf3432829227430830cca4315b57c1b9
24:33920e3786aa 2014-05-16 mbed_official Synchronized with git revision 71a478f780d9221934b90eab64a2c789ba8e51fb
23:ecbbaf64bc3d 2014-05-10 mbed_official Synchronized with git revision ec1f338b134b8e9c5a13e47e97890af2eeff4b79
22:5b7d31d9d3f3 2014-04-02 mbed_official Synchronized with git revision d537c51d26da35e031d537f7fc90380fc74cb207
21:ee9f2fa6bdbc 2014-03-27 mbed_official Synchronized with git revision 3d49a491d4dd16466354746d3c329428840f5a03
20:d38b72fed893 2014-02-27 mbed_official Synchronized with git revision 6b57b5237463a65d25f0ffa5efa3c8505553da4b
19:fcb63a105965 2014-02-20 mbed_official Synchronized with git revision 87193889326571b560379153239787775654be59
18:78bdbce94509 2014-02-18 mbed_official Synchronized with git revision 3c8f1c0c59bc1b665e9e1b1b3dc00e5fcdde6400
17:bbd6dac92961 2014-01-23 mbed_official Synchronized with git revision b7a925e3cf046d2c5a95f80b14d6c285afbdfa7e
16:4f6df64750bd 2013-12-05 mbed_official Synchronized with git revision fa451a0f0ae4ea99e333083931cc5bfc77b27b42
15:849c0c0f2769 2013-11-05 mbed_official Synchronized with git revision cf71d0831be92a7fff88da13626ef25dd94fa185
14:d495202c90f4 2013-09-12 bogdanm Synchronized with git revision b9d52bda50a692c05a4587bcc8d3219997444f58
13:16731886c049 2013-09-10 bogdanm Sync with git revision 171dda705c947bf910926a0b73d6a4797802554d
12:6030a12b6c62 2013-08-08 emilmont Synch with latest changes
11:eeb3cbbaa996 2013-08-05 bogdanm Bug fixes, added suppor for LPC1347
10:1e3d126a322b 2013-05-30 emilmont Add LPC4088 target
9:354942d2fa38 2013-03-04 samux kl25z: use malloc to allocate only endpoints needed
8:335f2506f422 2013-03-01 samux add FRDM-KL25Z support
7:f8f057664123 2013-01-21 samux modify USBMSD prototypes to fit latest sdfilesystem lib
6:d0945750af57 2012-12-20 samux USBSerial: detect when a terminal is connected
5:d27e4c226965 2012-10-14 samux USBMSD: fixed uninitialized variable (stage, csw, cbw) -> fixed dynamic init
4:eaa07ce86d49 2012-10-14 samux fixed doxygen typo
3:6d85e04fb59f 2012-10-14 samux move EnableIRQ to connect() - add MEDIA_REMOVAL handling
2:34856a6adb5b 2012-07-17 samux Update USBDevice.h
1:80ab0d068708 2012-07-17 samux Update USBDevice lib
0:d8db74b663b3 2012-07-17 mbed_official First commit of the mbed official USB device library