This fixes a problem found on MSD class where data read from from disks were sometimes partially overwritten by the status MSD message ("USBS...").
The function introduced wait for the hw fifo pipe to be empty, that prevent that new writing in the fife overwrite data which are not yet be transmitted by hw.
- merge addr0 ep to pool
- add control status to xact in/out
- use atomic flag busy to ensure only 1 transfer is active at any time
- execute pending transfer after one is complete (or clear busy flag)
- change rtt mode to block if full
previosuly users of TinyUSB (e.g. pico-examples) would have to decide this for themselves. This function couples
the check closer with the actual version of Pico-PIO-USB used (since TinyUSB picks)
* include_guard requires GLOBAL as family.cmake is included in multiple non child places
* the following recently added check is suprfluous (family_configure_host_example for rp2040 should do this already),
and breaks if pico_pio_usb is not avaialble, so i have removed
# Add pico-pio-usb for rp2040 since user can choose to run on bit-banging host
if(FAMILY STREQUAL "rp2040")
family_add_pico_pio_usb(${PROJECT})
endif()
* added new familt_example_missing_dependency functino to print missing dependency warning, so
pico-examples can override it to be less in your face, and also more contextual to pico-examples
There were typos in symlinks target names resulting in following
warrning on checkout (at least in Mynewt newt tool):
* Warning: stat mynewt/repos/tinyusb/docs/contributing/code_of_conduct.rst: no such file or directory
* Warning: stat mynewt/repos/tinyusb/docs/info/contributors.rst: no such file or directory
During enumeration, when there are multiple devices attached to the
hub as it's plugged into the Pi Pico, enumeration hangs, because we
get a "status change" callback with value zero. With this patch, we
retry several times on "zero" status change callbacks, until
eventually we succeed.
This is the cheapo hub that exhibits this behavior, but I assume it's
not the only one: https://www.amazon.com/gp/product/B083RQMC7S.
While debugging this, I consulted the implementation in the Linux
kernel. There, hub setup explicitly checks each port individually,
before starting to depend on "status change" interrupts:
https://elixir.bootlin.com/linux/latest/source/drivers/usb/core/hub.c#L1133.
We probably should do something like that here, but it's a much bigger
change.
* update chipidea dcd, remove manual ep_count and use DCCPARAMS to get number of endpoint instead
* add dcd dcache for chipidea
* add cmake for lpc18
* add makefile build for mcx
* use fork of mcu sdk
* fix ci build with nrf
* flash rp2040 with openocd
- change CFG_TUH_ENDPOINT_MAX to 16 (max endpoint pair per device) if
not defined
- change QHD_MAX for EHCI, should be user configurable and more
optimized in the future
While calling tud_cdc_n_get_line_coding, the structure is copied into
the destination.
Dump of assembler code for function tud_cdc_n_get_line_coding:
0x000193f4 <+0>: mov.w r2, #2112 @ 0x840
0x000193f8 <+4>: ldr r3, [pc, #20] @ (0x19410
<tud_cdc_n_get_line_coding+28>)
0x000193fa <+6>: mla r0, r2, r0, r3
=> 0x000193fe <+10>: ldr.w r3, [r0, #6]
0x00019402 <+14>: str r3, [r1, #0]
On some platform (tested on LPC55S28), the address needs to be 4-bytes
aligned. Without this, the address is
(gdb) p &_cdcd_itf.line_coding
$3 = (cdc_line_coding_t *) 0x40100006 <_cdcd_itf+6>
which leads to a HardFault. With this fix
(gdb) p &_cdcd_itf.line_coding
$5 = (cdc_line_coding_t *) 0x40100008 <_cdcd_itf+8>
and the function can be called properly
Signed-off-by: Jean-Baptiste Theou <jb@thing.com>
add per family freeRTOSConfig.h also make changes to build with
freertos_kernel cmake
- hard coded configPRIO_BITS based on family
- change configSUPPORT_STATIC_ALLOCATION to 0,
configSUPPORT_DYNAMIC_ALLOCATION to 1
- enable configRECORD_STACK_HIGH_ADDRESS for tracing
- enable INCLUDE_xTaskGetCurrentTaskHandle which is required to compile
stream_buffer (although we don't use it).
This commit makes it so that when setting the START_TRANS bit in the
SIE_CTRL register, along with some other bits, we first set all the
other bits, then wait some cycles, and then set the START_TRANS bit.
Doing so protects against a situation where the USB controller is
reading the register at the same time and gets an incorrect value.
This mirrors the procedure already applied to buffer control
registers.
- previously CFG_TUH_HID is max number of interfaces per device which is
rather limited and consume more resources than needed.
- change hid host instance in API to index
For incoming ISO OUT packets it was possible to start
DMA from endpoint to RAM before transfer was started
resulting in unrelated memory corruption.
This is scenario that causes memory corruption:
- ISO OUT packet is received
- Packet is transferred by DMA to transfer buffer
- xfer->started is cleared and xfer->buffer is updated as
it is in every case
- Application takes to long to handle it (it happens when debugger
is connected breakpoint is hit slowing down software).
- Next ISO OUT packet arrives
At this point there was no check if transfer was started and packet
was copied by DMA to location beyond previous data, possibly overwriting
unrelated memory.
This solves the issue by checking that transfer was
started and there is buffer ready for incoming packet.
This fixes https://github.com/hathach/tinyusb/issues/1894. I'm not really
sure if this is the correct way to fix it, and I have not tested on all the
rest of the family members, however, this lets the i.MX1010 work again.
The problem: the latest SDK update does not enable the data cache by default
This causes an assert in board_init() when attemping to control clock
gating. I haven't investigated further as to *why* it's a problem, but it
is a problem.
Mostly copy of stm32h743nucleo.
Linker script generated by STM32CubeIDE.
Since this device has only one HS USB
board.h contains few defines that map on
board HS USB to FS because there is no
ULPI chip mounted on Nucleo board.
For FreeRTOS build:
Set interrupt priority for HS always and for FS if exists.
Ordering by element size prevents alignment holes, and as a consequence the
host mode version of the struct is the same size as device, as pad bytes at
the end are used instead.
Don't mark IN buffers as available during the last 200us of a full-speed
frame. This avoids a situation seen with the USB2.0 hub on a Raspberry
Pi 4 where a late IN token before the next full-speed SOF can cause port
babble and a corrupt ACK packet. The nature of the data corruption has a
chance to cause device lockup.
Use the next SOF to mark delayed buffers as available. This reduces
available Bulk IN bandwidth by approximately 20%, and requires that the
SOF interrupt is enabled while these transfers are ongoing.
Inherit the top-level enable from the corresponding Pico-SDK flag.
Applications that will not use the device in a situation where it could
be plugged into a Pi 4 or Pi 400 (for example, when directly connected
to a commodity hub or other host) can turn off the flag in the SDK.
v2: use a field in hw_endpoint to mark pending.
v3: Partial rewrite following review comments
- Stub functions out if the workaround is not required
- Only force-enable SOF while any vulnerable endpoints are active
- Respect dcd_sof_enable() functionality
- Get rid of all but necessary ifdef hackery
- Fix a bug where the "endpoint lock" was used with an uninitialised pointer.
The next change to the driver requires the export of these functions. Leave the
lock unimplemented for now.
Also move hw_set and hw_clear aliases into the top-level header file.
Some Windows development environments invoke a mingw version of gnu make
with SHELL set to /bin/sh or /bin/bash (either explicitly or by default),
in which case tinyUSB make fails when a $(shell...) command feeds DOS syntax to sh.
We can't just use sh, as many Windows environments won't have unix utilities
like realpath (used by this makefile for sh shell commands).
This fix forces SHELL=cmd.exe on Windows and documents the issue.
Also adds additional documentation to help the next person...
With this fix, tinyUSB can be easily built and debugged in environments like
NXP's MCUxpresso (import as a makefile project).
Introduces a new function tu_memcpy_s, which is effectively
a backport of memcpy_s. The change also refactors calls
to memcpy over to the more secure tu_memcpy_s.
Currently OSS fuzz expects to have complete control over the
sanitizer flags. As we currently have these set it's causing
problems with the OSS fuzz build. Instead we should use the
provided variables from the OSS fuzz build environment. For
local testing we'll create a set a well defined defaults.
Use macro argument instead of 0x16 constant value.
At least Linux kernel was complaining about this value:
"config 1 interface 0 altsetting 0 endpoint 0x82 has an invalid bInterval 22, changing to 8"
(warning obtained using usbtmc device config)
- rename wr/rd absolute to index, and rel to pointer.
- fix crash with _tu_fifo_remaining()
- change get_relative_pointer() to idx2ptr() and merge with _ff_mod()
Fix handling of interrupt endpoints. i.e. no ZLPs.
Fix the assignation of endpoint types.
Add button support for MM900evx boards.
On board support do not block for UART input.
Correct USB FIFO use for setup data phases (OUT transfers). We cannot stop traffic on the control endpoint so we set a flag and pull data from host when tinyUSB requests it from the USB FIFO. Extend this for all endpoints although currently not required.
Rename all instances of ft90x which can apply to ft93x as ft9xx.
Add support for the cdc_dual_ports example for ft9xx.
Add LED pin definition for board LED in a simple to access place on the Bridgetek MM900EVx boards.
The SetLineCoding would fail as host would send the SETUP OUT phase before tinyUSB had setup a transaction for it. ft9xx port would ignore the transfer since there was no valid transaction setup for it. One SETUP data phase packet is cached now.
This allows to set custom descriptive names for virtual MIDI
ports/cables. A MIDI port offers different functionality on
the same physical USB device. The names make it easier to
distinguish one from the other.
IAR generates warning Pa167 'the "fallthrough" attribute is not supported'.
It doesn't generate warnings when one switch case falls through to another,
so simply make TU_ATTR_FALLTHROUGH expand to an empty string.
Also replace one instance of __attribute__ with the macro.
This affects struct rspMsg in usbtmc_app.c (unconditionally) and uint8_t
termChar in usbtmc_device.c (when NDEBUG is defined). IAR generates warning
Pe550 'variable was set but never used'.
IAR generates warning Pe111 'statement is unreachable'. In a couple of
cases, replace return statements with TU_ATTR_FALLTHROUGH; because some
compilers apparently can't figure out that the return statements are
unreachable but do whinge about an imagined fall-through without them!
This is a GCC extension, illegal in ISO C. IAR generates errors Pa152
'these operand types cannot be used here' and Pe852 'expression must be a
pointer to a complete object type'.
Replace with uint8_t*.
ISO packet size is up to 1023 for full speed device.
Upon completion of ISO reception, reported length of incoming packet
was truncated to one byte only.
This results in incorrect data stream for higher bit rates
48 samples * 4 bytes per sample * 2 channels = 384 bytes of data
and 128 was reported.
There is no change in logic extending xact_len to uint16_t fixes the issue.
Some compilers don't support the GNU extension `typeof` so their definitions
of `hw_set_alias` can't inherit their type from their argument, and the best
we can do is have `hw_set_alias` act the same as `hw_set_alias_untyped`.
This requires an explicit cast when the macro is used instead, otherwise
IAR generates error Pe132 'expression must have pointer-to-struct-or-union
type but it has type "void *"'.
The same goes for `hw_clear_alias`.
strings.h is not an ISO header file, so IAR generates fatal error Pe1696
'cannot open source file "strings.h"'. Even though strncasecmp isn't an
ISO C library function, IAR's runtime library defines it, though it
declares it in string.h instead.
Field started (regardind transfer) was only cleaed when transfer
was finished.
For audio devices set interface is called many times.
When there is no audio (silence) set interface requests zero
lenght bandwithd that in turn calls dcd_edpt_close().
When endpoint is closed due to set interface request transfer
should not longer be started since it will block next start transfer
with assert.
This just sets 'started' to false when endpoint is closed.
Removing the Hardcoded interface numbers from the video descriptors allow the user to add other interfaces before or after the Video Control Interface and Video Streaming Interface
dfu_moded_open() only works correct when its called on DFU interface
descriptor. It means that DFU is the only one interface in configuration
or driver is called after all others interface drivers were tried and
gave up.
If other interface is supported and but driver for DFU is called first
(this is the case for BTH and RNDIS).
Code after while loop (that was not entered) has an TU_ASSERT that will
make set_configuration to fail.
Now TU_VERIFY is called first to make sure open code is called for DFU
only and not other interface descriptors like in other drivers.
- remove "-Wno-stringop-overflow -Wno-array-bounds"
- skip -Wconversion for gcc 9 and prior
- suppress_tinyusb_warnings only when building with gcc 9 and below
* gcc 9.2.1 has some spurious -Wconversion warnings
* cmake 3.18 and above require set_target_properties to be added from the target directory (so added it to all examples)
* fixed a few warnings in a couple of examples
This PR fixes a transmit lock-up, which happens, when data is received
and sent at the sime time at moderate to high speeds, like code
which just echoes incoming data.
In my case, an issue was reported here:
https://github.com/micropython/micropython/issues/8521
since HS interrupt endpoint can be up to 1024, 8-bit is not enough.
affected APIs are:
- tud_hid_n_report() / tud_hid_report()
- tud_hid_report_complete_cb()
The Teensy 4.1 board has an 8MB W25Q64JV as opposed to the 2MB flash
on the Teensy 4.0. This largely doensn't matter for TinyUsb, except
when you attempt to access any memory in the flash above the 2MB
boundary, when it fails with a hard fault.
Tested on SAMD51 - we can allow more packet sizes by checking that the set size value is greater than the requested packet size instead of exactly the same.
Not having this prevents the device from finishing the mounting process.
Tested on a SAMD51 and didn't seem to need to actually do anything in the close function.
- Stall now has priority over other interrupt responses
- Delete eunused hcd_edpt_busy
- Assert !ep->active when trying to start a new xfer
- Assert !ep->active when handling buff_status bits
- Set ep->xferred_len to 8 once a setup packet is finished so the data
structure is accurate
There were two problems:
- dma_running flag could be checked in USB interrupt (not set yet) then higher priority
interrupt could start transfer, check dma_running (not set yet) set it to true start
DMA; then when USB interrupt continues it starts another DMA that is not allowed
- when DMA is started some registers can't be safely accessed, read can yield invalid
values (SIZE.EPOUT, SIZE.EPISO)
current implementation could start DMA for one OUT endpoint then check that another
endpoint also has data and while DMA was not started right away, SIZE.EPOUT was copied
already to MAXCNT register. Later on when DMA was started not all data was read from
endpoint due to incorrect DMA size previously set.
To prevent both cases dma_running is changed in atomic way.
Only code that actually set this value to true starts DMA, code that tried and
had dma_running flag already set simply defers DMA start to USB task.
This eliminates also need to have mutex that was there to limit access to dma_running flag
to one task only.
transfer also now has started flag that is set only after dcd_edpt_xfer() sets up total_len
and actua_len. Previously USB interrupt was disabled when total_len and actual_len were
setup to prevent race condition when data arrived to ednpoint before transfer was setup
was finished.
this allows ports to specify a freertos port outside the FreeRTOS-Kernel lib directory, which would otherwise not be possible
Signed-off-by: Rafael Silva <rafaelsilva@ajtec.pt>
create local register access struct and move mcu specific code
in preparation of support for other mcu families that use the LINK usb core
Signed-off-by: Rafael Silva <rafaelsilva@ajtec.pt>
* Removed some compiler warnings, and cleaned out unnecessary warning suppression from CMake suppress_tinyusb_warnings()
* Made explicit family_configure_dual_usb_example() for DUAL mode examples as family_configure_target() may not generally be called multiple times for the same target
* Renamed library pico_pio_usb to tinyusb_picio_pio_usb to be clearer and avoid conflict if someone already has a pico_pio_usb in their project
* Added family_add_pico_pio_usb() method for adding Pico-PIO_SUB support to an existing example
* Allowed tinyusb_pico_pio_usb to be added to regular apps using the Pico SDK
When transfer was finished rx_fifo_read() read all that
was to read RXPKTRDY was cleared allowing next packet to
be received.
Then xfer_complete was called.
Interrupt for OUT endpoint was left enable, that would not
be a problem if data was handled fast and new transfer was
scheduled.
For MSC when host sends a lot of data this interrupt that was
enabled could cause epn_handle_rx_int() to be called after
transfer was completed and next was not scheduled yet.
Without TU_ASSERT that was added to detect this, incoming
data was written past buffer provided by user code resulting
in random memory corruption.
This just blocks RX interrupt when transfer is finished,
and also only unmasked rx interrupts are handled.
- add synchronous version of all get descriptor API
- update bare example to use sync API for string descriptor
- change order of index, language_id in tuh_descriptor_get_string() to
match similar API of libusb
- add index to tuh_descriptor_get_hid_report()
- change API of tuh_control_xfer and its callback
- rename tuh_control_complete_cb_t to tuh_control_xfer_cb_t
- add user argument to control callback
- migrate usbh and hub
I believe that there is a mistake in the definition of TUD_AUDIO_HEADSET_STEREO_DESCRIPTOR. The nitfs in the audio descriptor is always 3 regardless of ITF_NUM_TOTAL.
* The standard inquiry response additional length field needs to be set to
the length in bytes of the remaining standard inquiry data (i.e. N - 5),
otherwise the kernel driver issues a warning about short inquiry response..
IAR defines __STDC_VERSION__ in cpp as well.
Which causes TU_VERIFY_STATIC to be defined as _Static_assert
instead of cpp's static_assert.
This reorders __cplusplus__ to be first, then to fallback to
__STDC_VERSION__ if not CPP.
If using a USB hub, a request outside the array size can occur
Original line:
ffb257ac17/src/portable/ohci/ohci.h (L162)
It can happen in a few places but one such example is here:
ffb257ac17/src/portable/ohci/ohci.c (L460)
ie. if HUB address is 5, this would be an array index out of bounds on control endpoints as `CFG_TUH_DEVICE_MAX+1` is only 5.
This fix just includes num of hubs in the reserve array size.
Fixing locally fixed this issue.
Going to suspend states disable reception on non-0 RX endpoints.
Now when USB resume condition is detected, all RX endpoints
with pending transfers are resumed.
Bit mask enabling/disabling over-run/unde-run was shifted
by one nibble, so interrupt was never enabled.
It did not force any issue as this situation could only
happen on ISO endpoints without DMA.
So far tud_vendor_n_write() always flushed data.
It requires to have whole vendor packed constructed
before in one buffer.
With this change data do get flushed when endpoint size
is filled on write, when there is no enough data to
fill endpoint data is not sent and subsequent calls to
write functions can add more bytes.
Vendor code needs to call tud_vendor_n_flush() when packet is
ready to be sent.
When two tasks entered dcd_edpt_xfer() it was possible that
first disabled interrupt to setup total_len and actual_len
but second task for another endpoint enabled interrupt
between total_len and actual_len resulting in race
condition with interrupt, hence mutex is added on top of interrupt being blocked.
In multi-thread mode starting DMA in thread mode was
prone to race condition resulting in infinite loop.
It may happen on single core CPU with strict priority based
tasks scheduler where ready high prio task never yields to
ready low prio task (Mynewt).
Sequence that failed (T1 - low priority task, T2 - high priority task)
- T1 called start_dma()
- T1 set _dcd.dma_running (DMA not started yet, context switch happens)
- T2 took CPU and saw that _dcd.dma_running is set, so waits for _dcd.dma_running to be 0
- T1 never gets CPU again, DMA is not started T2 waits forever
OSAL mutex resolves problem of DMA starting from thread-context.
Mynewt (similar to Soft Device) has its own reference counting for
HFXO oscillator.
So far TinyUSB requested HFXO when VBUS was detected and stopped when
VBUS was removed.
But with Mynewt running HFXO can be stopped when other interested parties
don't require HFXO anymore. This results in very difficult to track
USB transmission errors.
This change enables Mynewt specific HFXO management in Soft Device fashion.
Remote wakeup requires 10ms of delay when RESUME bit
is toggled.
It was covered for OS build.
For non-OS build simple delay based on board_millis() is
used to wait required amount of time.
Without this remote wakup may not work.
When dcd_edpt_xfer() starts new transfer two separate problems were observed.
For both problems stream of OUT packets was pouring from host.
First problem was that total_len and actual_len were not atomic.
In case where incoming OUT packets are less (63) than MPS (64), actual_len and total_len
are set 63.
Then transfer complete from USBD is called that will schedule next 64 bytes transfer.
At that point incoming packet would start DMA if there is place in RAM, normally
it does not happen since actual_len == total_len.
If packets arrives and interrupt is raised after total_len is set (64) but actual_len is still 63 from
previous transfer, interrupt code sees that there is place in ram (1 byte) and transfer this 1 byte
to buffer that was already filled with previous packet.
To remedy this USB interrupt is blocked during transfer setup.
Second problem can happen when dcd_edpt_xfer setups xfer->total_len and actual_len correctly
but then context switch happens before xfer->data_received is checked.
If during this time two packets arrive one will be copied to RAM second will stay in endpoint with
data_received set to 1.
Then when xfer_edpt_xfer() checks data_receive flag it starts DMA again overwriting data.
To remedy this, data_received is checked together with check if data was already transferred.
If transfer was complete, there is no need to start DMA yet.
In such case data_received will be handled in same place by next xfer_edpt_xfer() correctly.
Two boards from Olimex are added:
olimex_hmz144 with PIC32MZ2048EFM144
olimex_emz64.c with PIC32MZ2048EFH064
Both can be programmed with Segger JLINK probe using ICSP
interface. (JTAG not tested but could also work but header
is not mounted).
These are different Broadcom chips. The peripherals are essentially
the same. The main differences are:
* The CPU(s)
* The interrupt controller
* The peripheral base address (but not the peripherals that we use)
definition of DEBUG breaks Microchip pic32 builds for Mynewt.
When MCU is not VALENTYUSB_EPTRI there is no need to have any
preprocessor definitions.
It may not look like a big deal but for xc32 builds, compiler
automatically force-includes some file that have structure with field name
DEBUG that result in build error in dcd_eptri.c when this file
is not really needed.
Moving DEBUG and LOG_USB few lines down should not break eptri builds.
Three changes are needed to accommodate xc32 compiler build:
- optimized build flag other than -Os
added CFLAGS_OPTIMIZED that defaults to -Os but can be overridden in boards
- build without -lnosys
added LIBS_GCC with default libraries that can be changed in boards
- build without LD_FILE specification
if LD_FILE is empty -Wl,-T options is not added to LDFLAGS
When NRF5x device is reset by software (after DFU for example),
power event is ready from the beginning.
When power interrupt is triggered before tud_init() finished
USBD_IRQn is enabled before it would be enabled in tud_init().
This in turn may result in BUS RESET event being sent from
USB interrupt to USB task when queue is not initialized yet.
This scenario often happens in Mynewt build where queue creation
takes more time.
To prevent this scenario USBD_IRQn is not enabled in power event
interrupt handler before dcd_init() was called.
The datasheet says 2KB FIFO, but accroding to many
code examples, the F1C100s has at least 4KB of FIFO memory.
This is working with cdc_msc example,
but I'm not sure, this should be checked.
Allwinner F1Cx00s family is a series of SoCs
with Mentor MUSB controller and HS phy. It comes
with a slightly different register space layout,
and some quirks, so it's not multiplexed with
the existing musb support library.
This library currently requires to be compiled
with https://github.com/hongxuyao/F1C100s_with_Keil_RTX4_emWin5
Bluetooth's specification defines IAD for primary controller.
While it seems that Windows and Linux can leave without this,
there is no reason TinyUSB should not provide it.
Two interfaces that are required by Bluetooth Primary Controller
do not have IAD according to Bluetooth specification.
Those two interfaces were opened separately in process_set_config().
Later interface association was inferred for BTH (along with other
drivers), since then only one call to open() is place for BTH driver
that should prepare both interfaces at once.
To make it work again btd_open() parses two interfaces at once.
dcd_synopsys.c included broadcom/interrupts.h before
preprocessor check whether file should be used.
Since mynewt build does not include all folders it resulted in build
error.
Now offending include is moved few lines after preprocessor check.
USB3CV tool complains about too short serial number being used
in MSC device.
This just extends serial number to 12 characters, it makes it
easier to analyze USB3CV logs where this unnecessary warning
made output red.
Offending warning:
Serial Number string for MSC device : iSerialNumber = 0x3
Checking iSerialNumber String Descriptor: index = 0x03.
String Descriptor : "123456". (ENGLISH_US)
Using Language ID 0x409
MSC Serial Number length = 14
Invalid MSC Serial Number length : should be >= 26
*************************
Invalid MSC Serial Number length
*************************
*************************
(MSC: 5.1.2) Serial number must be a string, 12 characters or longer
(if the device supports a BOT interface, bInterfaceProtocol = 0x50),
or exactly 12 characters long (if the device supports a CBI interface,
bInterfaceProtocol = 0x00 or 0x01, and has a serial number).
USB3CV tool verifies MSC device by sending too short or
too long packets.
In case of too long packets (msc_device requested 31 bytes
but incoming data had 32 bytes) extra byte(s) were left in
FIFO resulting in some data mismatch later on.
Now if more data is received in packet that expected extra
bytes are just dropped.
Normal TX handler for IN non-0 endpoints is called during
outgoing transfer or just after it was finished.
It may need to fill TX fifo with same data if TX_DONE is present
but ACK_STAT is not.
It may need to fill more data when called during transfer.
But it may also be called when STALL was sent.
In this case TX_DONE is set ACK_STAT is not, just like for packets
that were sent but no ACK was received.
Code was trying to send something again. There was nothing to send
so empty ZLP was scheduled for stalled endpoint.
This ZLP was later send to host where valid response was required.
This change checks if notification was for STALL endpoint and
does not try to fill TX FIFO in that case.
- physically suppress warnings in TinyUSB headers using pragmas so they don't break -Werror compilation of external files that include them
- fix compiler warnings in rp2040 port
- add cmake method to rp2040 port to allow an external project to suppress warnings in TinyUSB itself
* add NO_LTO option to make
* add linkermap submodule and linkermap target
* add linkermap to ci build
* linkermap doesn't work with esp32sx map file yet
* add note for linkermap target
Add FT90X and FT93X to the list of devices in tusb_option.h. 1700 for FT90x and 1701 for FT93x.
Set endpoint attributes for FT90x and FT93x in dcd_attr.h.
Add FT90x routines for USB device in src/portable/bridgetek/ft90x/dcd_ft90x.c
The location for hardware header files and libraries is hw/mcu/bridgetek/ft90x/hardware. There are no files in the repository, but files will be linked as a submodule in the future. The required files can be copied from or linked to the location "C:/Program Files(x86)/Bridgetek/FT9xx Toolchain/Toolchain/hardware" once the toolchain is installed.
Makefile for the MM900EV1B board for developing with an FT900 device is present. Use "BOARD=mm900ev1b".
Windows and Linux host during enumeration requests device
descriptor with request size set to 64 bytes when device
was in default state (no address).
Those systems do not want 64 bytes though since usb descriptors is
only 18 bytes long so they silently expect that only one packet
will be received possibly 18 bytes for EPS > 16 or 8 or 16 bytes
for smaller EP0.
For devices with CFG_TUD_ENDPOINT0_SIZE size 8 or 16 there was
workaround that reduced request size to CFG_TUD_ENDPOINT0_SIZE
and that was enough to satisfy Windows and Linux hosts.
However USBCV testing application also requests device descriptor
but with size set to 18 bytes. Workaround for Window/Linux
prevented USBVC to tests devices with 8 bytes EP0 size since it
send only 8 bytes while application did wanted 18 bytes.
Solution that satisfies both cases it to check if in default state device
descriptor request wants more bytes than descriptor size (18).
If so host is expecting to receive less bytes then requested
and workaround would be applied since Linux/Windows only try
to read one packet.
If 18 bytes was requested as is the case for USBCV, core returns
descriptor in 2 or 3 packets as application expects.
Note: this commit does not change any logic.
xfer_ctl_t structure keeps all dynamic data connected with transfer.
It used to have pointer to register set that was constant and was there
for convenience only.
Removing register pointer from structure makes cleanup easier as whole
structure can be erased with memset like function.
In many cases functions were using local variable regs and xfer->regs which
were same, that could be confusing so this part is unified.
Few macros were added for easy conversion between epnum, xfer, and regs.
So far bus reset was handled (with some holes in it).
Sleep and remote wakeup were not really tested and did not work.
With this change:
- bus reset is reworked
- remote wakeup works
- bus signal sleep is handled
Two BSPs with DA146xx MCUs are now adopted to
VBUS handling changed introduced to dcd_da146xx driver.
da14695_dk_usb as bus-powered devices informs driver that
VBUS is present at startup.
da1469x-dk-pro has VBUS change interrupt handler that
informs driver about VBUS changes.
DA146xx are Bluetooth devices that may be battery
powered and when not connected to USB host there
is no need for USB peripheral to be running.
This change allows to enable USB peripheral when
VBUS is present otherwise USB is down reducing
power consumption.
tud_vsub_changed() function must be called
whenever VBUS change was detected.
For bus-powered devices this function should be called
at startup since VBUS must be present while device
is working.
example implement tud_descriptor_device_qualifier_cb() and
tud_descriptor_other_speed_configuration_cb() on high speed device to
fully compliant to usbcv
Added support for Microchip Curiosity Nano SAMD21 board (DM320119) under hw/bsp/samd21/boards/curiosity_nano
The nEDBG on this board requires dap_protocol be specified as SWD (changed in examples/rules.mk)
NOTE: requires entry (03eb:2175) for VID:PID of nEDBG be added to /etc/udev/rules for pyocd
For self powered device if device started without VBUS present
it would not be correctly attached to USB bus even if tusb_vbus_changed()
was later called.
This modifies dcd_init() so it starts USB state machine without checking
if VBUS is present or not, like all others drivers do.
tusb_vbus_changed() function is also removed its content was moved to dcd_init.
dcd_da1469x can work with broader range of MCUs that
share same USB core.
Specific header file that was used DA1469xAB.h now it is changed
to mcu/mcu.h which includes actual MCU specific register file.
Only 48MHz, 72MHz, 96MHz and 120 MHz system clocks derived from an
external crystal are suitable for the usb peripheral, as the internal
oscillator is not stable enough. Also the usb-prescaler only supports
division by 1 (48MHZ), 1.5(72MHz), 2(96MHz) and 2.5(120Mhz).
120Mhz is also out of spec and not added here.
Instead of using the HAL functions we can just use the defines from the
board support for the longan nano that comes with the nuclei-sdk. Also
we move some includes and defines to the header file.
The core of tinyusb must be as independent as possible, we previously
relied on nuclei-sdk or the GD32VF103 firmware library for the synopsys
driver to work with the GD32VF103. Fortunatly we needed very few parts
from them so we implement them here.
Without having __riscv_flen defined we get multiple warinings. But
defining it causes the startup code to contain floating point instructions.
This results in a exception right after booting.
See startup_gd32vf103.S lines 289-294 should open a PR at nuclei sdk
During Adafruit Bootloader compilation, I spotted bellow error which do not allow me build project.
``` c
inlined from 'hfclk_running' at lib/tinyusb/src/portable/nordic/nrf5x/dcd_nrf5x.c:785:13:
lib/tinyusb/src/portable/nordic/nrf5x/dcd_nrf5x.c:792:31: error: 'is_running' may be used uninitialized [-Werror=maybe-uninitialized]
792 | return (is_running ? true : false);
| ~~~~~~~~~~~~~~~~~~~^~~~~~~~
```
- make _hw_endpoint_xfer_sync and _hw_endpoint_start_next_buffer private
- drop prefix _ from _hw_endpoint_xfer_continue and
_hw_endpoint_reset_transfer
* Add MM32 SDK and USB driver
* add mindmotion mm32sdk as submodule
remove the local copy of mm32
* mit license
Signed-off-by: zhangslice <1304224508@qq.com>
Co-authored-by: hathach <thach@tinyusb.org>
- **TinyUSB version** relase version or git hash (preferrably running with master for lastest code)
- **Firmware** e.g examples/device/cdc_msc
**Describe The Bug**
A clear and concise description of what the bug is.
**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. See error
**Screenshots**
If applicable, add screenshots, bus capture to help explain your problem.
**Log**
If applicable, provide the stack's log (uart/rtt/swo) where the issue occurred, best with comments to explain the actual events. If the log is too long, attach it as txt file instead.
Note: To enable logging, add `LOG=2` to to the make command if building with stock examples or set `CFG_TUSB_DEBUG=2` in your tusb_config.h. More information can be found at [example's readme](/docs/getting_started.md)
Thanks for taking the time to fill out this bug report!
It's okay to leave some blank if it doesn't apply to your problem.
- type:dropdown
attributes:
label:Operating System
options:
- Linux
- MacOS
- RaspberryPi OS
- Windows 7
- Windows 10
- Windows 11
- Others
validations:
required:true
- type:input
attributes:
label:Board
placeholder:e.g Feather nRF52840 Express
validations:
required:true
- type:textarea
attributes:
label:Firmware
placeholder:|
e.g examples/device/cdc_msc. If it is custom firmware, it is preferably compiled like one in example folder and reviewable for people to comment on. The easiest way is
- Fork this repo, checkout a new branch
- Add your-own-example based on stock one
- Push and post it here.
validations:
required:true
- type:textarea
attributes:
label:What happened ?
placeholder:A clear and concise description of what the bug is.
validations:
required:true
- type:textarea
attributes:
label:How to reproduce ?
placeholder:|
Exact steps in chronological order, details should be specific e.g if you use a command/script to test with, please post it as well.
1. Go to '...'
2. Click on '....'
3. See error
validations:
required:true
- type:textarea
attributes:
label:Debug Log as txt file (LOG/CFG_TUSB_DEBUG=2)
placeholder:|
Attach your debug log txt file here, where the issue occurred, best with comments to explain the actual events.
Note1:Please DO NOT paste your lengthy log contents here since it hurts the readability.
Note2:To enable logging, add `LOG=2` to to the make command if building with stock examples or set `CFG_TUSB_DEBUG=2` in your tusb_config.h.
More information can be found at [example's readme](https://github.com/hathach/tinyusb/blob/master/docs/getting_started.md)
validations:
required:true
- type:textarea
attributes:
label:Screenshots
description:If applicable, add screenshots to help explain your problem.
validations:
required:false
- type:checkboxes
attributes:
label:I have checked existing issues, dicussion and documentation
description:You agree to check all the resources above before opening a new issue.
options:
- label:I confirm I have checked existing issues, dicussion and documentation.
TinyUSB is an open-source cross-platform USB Host/Device stack for embedded system, designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events are deferred then handled in the non-ISR task function.
[Here is the list of supported Boards](docs/boards.md) that can be used with provided examples.
## Device Stack
Supports multiple device configurations by dynamically changing usb descriptors. Low power functions such like suspend, resume, and remote wakeup. Following device classes are supported:
- Audio Class 2.0 (UAC2) still work in progress
- Bluetooth Host Controller Interface (BTH HCI)
- Communication Class (CDC)
- Device Firmware Update (DFU): DFU mode (WIP) and Runtinme
- Human Interface Device (HID): Generic (In & Out), Keyboard, Mouse, Gamepad etc ...
- Mass Storage Class (MSC): with multiple LUNs
- Musical Instrument Digital Interface (MIDI)
- Network with RNDIS, CDC-ECM (work in progress)
- USB Test and Measurement Class (USBTMC)
- Vendor-specific class support with generic In & Out endpoints. Can be used with MS OS 2.0 compatible descriptor to load winUSB driver without INF file.
- [WebUSB](https://github.com/WICG/webusb) with vendor-specific class
If you have special need, `usbd_app_driver_get_cb()` can be used to write your own class driver without modifying the stack. Here is how RPi team add their reset interface [raspberrypi/pico-sdk#197](https://github.com/raspberrypi/pico-sdk/pull/197)
## Host Stack
**Most active development is on the Device stack. The Host stack is under rework and largely untested.**
- Human Interface Device (HID): Keyboard, Mouse, Generic
- Mass Storage Class (MSC)
- Hub currently only supports 1 level of hub (due to my laziness)
## OS Abstraction layer
TinyUSB is completely thread-safe by pushing all ISR events into a central queue, then process it later in the non-ISR context task function. It also uses semaphore/mutex to access shared resources such as CDC FIFO. Therefore the stack needs to use some of OS's basic APIs. Following OSes are already supported out of the box.
- **No OS**
- **FreeRTOS**
- **Mynewt** Due to the newt package build system, Mynewt examples are better to be on its [own repo](https://github.com/hathach/mynewt-tinyusb-example)
## Getting Started
[Here are the details for getting started](docs/getting_started.md) with the stack.
## Porting
Want to help add TinyUSB support for a new MCU? Read [here](docs/porting.md) for an explanation on the low-level API needed by TinyUSB.
## License
MIT license for all TinyUSB sources `src` folder, [Full license is here](LICENSE). However, each file is individually licensed especially those in `lib` and `hw/mcu` folder. Please make sure you understand all the license term for files you use in your project.
## Uses
TinyUSB is currently used by these other projects:
Here is the list of `Supported Devices`_ that can be used with provided examples.
Device Stack
============
Supports multiple device configurations by dynamically changing USB descriptors, low power functions such like suspend, resume, and remote wakeup. The following device classes are supported:
- Audio Class 2.0 (UAC2)
- Bluetooth Host Controller Interface (BTH HCI)
- Communication Device Class (CDC)
- Device Firmware Update (DFU): DFU mode (WIP) and Runtime
- Human Interface Device (HID): Generic (In & Out), Keyboard, Mouse, Gamepad etc ...
- Mass Storage Class (MSC): with multiple LUNs
- Musical Instrument Digital Interface (MIDI)
- Network with RNDIS, Ethernet Control Model (ECM), Network Control Model (NCM)
- Test and Measurement Class (USBTMC)
- Video class 1.5 (UVC): work in progress
- Vendor-specific class support with generic In & Out endpoints. Can be used with MS OS 2.0 compatible descriptor to load winUSB driver without INF file.
- `WebUSB <https://github.com/WICG/webusb>`__ with vendor-specific class
If you have a special requirement, `usbd_app_driver_get_cb()` can be used to write your own class driver without modifying the stack. Here is how the RPi team added their reset interface `raspberrypi/pico-sdk#197 <https://github.com/raspberrypi/pico-sdk/pull/197>`_
Host Stack
==========
- Human Interface Device (HID): Keyboard, Mouse, Generic
- Mass Storage Class (MSC)
- Communication Device Class: CDC-ACM
- Vendor serial over USB: FTDI, CP210x
- Hub with multiple-level support
Similar to the Device Stack, if you have a special requirement, `usbh_app_driver_get_cb()` can be used to write your own class driver without modifying the stack.
TypeC PD Stack
==============
- Power Delivery 3.0 (PD3.0) with USB Type-C support (WIP)
- Super early stage, only for testing purpose
- Only support STM32 G4
OS Abstraction layer
====================
TinyUSB is completely thread-safe by pushing all Interrupt Service Request (ISR) events into a central queue, then processing them later in the non-ISR context task function. It also uses semaphore/mutex to access shared resources such as Communication Device Class (CDC) FIFO. Therefore the stack needs to use some of the OS's basic APIs. Following OSes are already supported out of the box.
- **Mynewt** Due to the newt package build system, Mynewt examples are better to be on its `own repo <https://github.com/hathach/mynewt-tinyusb-example>`_
Docs
====
- Info
- `Uses`_
- `Changelog`_
- `Contributors`_
- `Reference`_
- `Supported Devices`_
- `Getting Started`_
- `Dependencies`_
- `Concurrency`_
- `Contributing`_
- `Code of Conduct`_
- `Structure`_
- `Porting`_
License
=======
All TinyUSB sources in the ``src`` folder are licensed under MIT
license, the `Full license is here <LICENSE>`__. However, each file can be
individually licensed especially those in ``lib`` and ``hw/mcu`` folder.
Please make sure you understand all the license term for files you use
The board support code is only used for self-contained examples and testing. It is not used when TinyUSB is part of a larger project. It is responsible for getting the MCU started and the USB peripheral clocked with minimal of on-board devices
- One LED : for status
- One Button : to get input from user
- One UART : optional for device, but required for host examples
## Supported Boards
This code base already had supported for a handful of following boards (sorted alphabetically)
### Dialog DA146xx
- [DA14695 Development Kit – USB](https://www.dialog-semiconductor.com/products/da14695-development-kit-usb)
- [DA1469x Development Kit – Pro](https://www.dialog-semiconductor.com/products/da14695-development-kit-pro)
- [LPCXpresso18S37 Development Board](https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/lpc4000-cortex-m4/lpcxpresso18s37-development-board:OM13076)
If you don't possess any of supported board above. Don't worry you can easily implemented your own one by following this guide as long as the mcu is supported.
- Create new makefile for your board at `hw/bsp/<board name>/board.mk` and linker file as well if needed.
- Create new source file for your board at `hw/bsp/<board name>/<board name>.c` and implement following APIs
### Board APIs
#### board_init()
Is responsible for starting the MCU, setting up the USB clock and USB pins. It is also responsible for initializing LED and button pins.
One useful clock debugging technique is to set up a PWM output at a known value such as 500hz based on the USB clock so that you can verify it is correct with a logic probe or oscilloscope.
Setup your USB in a crystal-less mode when available. That makes the code easier to port across boards.
#### board_led_write()
Set the pin corresponding to the led to output a value that lights the LED when `state` is true.
#### board_button_read()
Return current state of button, a `1` means active (pressed), a `0` means inactive.
#### board_millis()
The function returns the elapsed number of milliseconds since startup. On ARM this is commonly done with SysTick or Timer. This provide examples a way to measure time to blink LED or delay properly. It is only required when run examples without RTOS `CFG_TUSB_OS == OPT_OS_NONE`.
TinyUSB is designed to be a universal USB protocol stack for microcontrollers. It
handles most of the high level USB protocol and relies on the microcontroller's USB peripheral for
@ -8,129 +11,165 @@ for the microcontroller to other projects, especially those already using TinyUS
Below are instructions on how to get the cdc_msc device example running on a new microcontroller. Doing so includes adding the common code necessary for other uses while minimizing other extra code. Whenever you see a phrase or word in <> it should be replaced.
## Register defs
Register defs
-------------
The first step to adding support is including the register definitions and startup code for the
microcontroller in TinyUSB. We write the TinyUSB implementation against these structs instead of higher level functions to keep the code small and to prevent function name collisions in linking of larger projects. For ARM microcontrollers this is the CMSIS definitions. They should be
placed in the `hw/mcu/<vendor>/<chip_family>` directory.
placed in the ``hw/mcu/<vendor>/<chip_family>`` directory.
Once this is done, create a directory in `hw/bsp/<your board name>` for the specific board you are using to test the code. (Duplicating an existing board's directory is the best way to get started.) The board should be a readily available development board so that others can also test.
Once this is done, create a directory in ``hw/bsp/<your board name>`` for the specific board you are using to test the code. (Duplicating an existing board's directory is the best way to get started.) The board should be a readily available development board so that others can also test.
Build
-----
## Build
Now that those directories are in place, we can start our iteration process to get the example building successfully. To build, run from the root of TinyUSB:
`make -C examples/device/cdc_msc BOARD=<board>`
``make -C examples/device/cdc_msc BOARD=<board>``
Unless, you've read ahead, this will fail miserably. Now, lets get it to fail less by updating the files in the board directory. The code in the board's directory is responsible for setting up the microcontroller's clocks and pins so that USB works. TinyUSB itself only operates on the USB peripheral. The board directory also includes information what files are needed to build the example.
One of the first things to change is the `-DCFG_TUSB_MCU` cflag in the `board.mk` file. This is used to tell TinyUSB what platform is being built. So, add an entry to `src/tusb_option.h` and update the CFLAG to match.
One of the first things to change is the ``-DCFG_TUSB_MCU`` cflag in the ``board.mk`` file. This is used to tell TinyUSB what platform is being built. So, add an entry to ``src/tusb_option.h`` and update the CFLAG to match.
Update `board.mk`'s VENDOR and CHIP_FAMILY values when creating the directory for the struct files. Duplicate one of the other sources from `src/portable` into `src/portable/<vendor>/<chip_family>` and delete all of the implementation internals. We'll cover what everything there does later. For now, get it compiling.
Update ``board.mk``\ 's VENDOR and CHIP_FAMILY values when creating the directory for the struct files. Duplicate one of the other sources from ``src/portable`` into ``src/portable/<vendor>/<chip_family>`` and delete all of the implementation internals. We'll cover what everything there does later. For now, get it compiling.
## Implementation
At this point you should get an error due to an implementation issue and hopefully the build is setup for the new MCU. You will still need to modify the `board.mk` to include specific CFLAGS, the linker script, linker flags, source files, include directories. All file paths are relative to the top of the TinyUSB repo.
Implementation
--------------
At this point you should get an error due to an implementation issue and hopefully the build is setup for the new MCU. You will still need to modify the ``board.mk`` to include specific CFLAGS, the linker script, linker flags, source files, include directories. All file paths are relative to the top of the TinyUSB repo.
Board Support (BSP)
^^^^^^^^^^^^^^^^^^^
### Board Support (BSP)
The board support code is only used for self-contained examples and testing. It is not used when TinyUSB is part of a larger project. Its responsible for getting the MCU started and the USB peripheral clocked. It also optionally provides LED definitions that are used to blink an LED to show that the code is running.
It is located in `hw/bsp/<board name>/board_<board name>.c`.
It is located in ``hw/bsp/<board name>/board_<board name>.c``.
#### board_init
`board_init` is responsible for starting the MCU, setting up the USB clock and USB pins. It is also responsible for initializing LED pins.
board_init
~~~~~~~~~~
``board_init`` is responsible for starting the MCU, setting up the USB clock and USB pins. It is also responsible for initializing LED pins.
One useful clock debugging technique is to set up a PWM output at a known value such as 500hz based on the USB clock so that you can verify it is correct with a logic probe or oscilloscope.
Setup your USB in a crystal-less mode when available. That makes the code easier to port across boards.
#### board_led_write
Feel free to skip this until you want to verify your demo code is running. To implement, set the pin corresponding to the led to output a value that lights the LED when `state` is true.
board_led_write
~~~~~~~~~~~~~~~
### OS Abstraction Layer (OSAL)
Feel free to skip this until you want to verify your demo code is running. To implement, set the pin corresponding to the led to output a value that lights the LED when ``state`` is true.
The OS Abstraction Layer is responsible for providing basic data structures for TinyUSB that may allow for concurrency when used with an RTOS. Without an RTOS it simply handles concurrency issues between the main code and interrupts.
OS Abstraction Layer (OSAL)
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The code is almost entirely agnostic of MCU and lives in `src/osal`.
The OS Abstraction Layer is responsible for providing basic data structures for TinyUSB that may allow for concurrency when used with an RTOS. Without an RTOS it simply handles concurrency issues between the main code and interrupts. The code is almost entirely agnostic of MCU and lives in ``src/osal``.
### Device API
In RTOS configurations, tud_task()/tuh_task() blocks behind a synchronization structure when the event queue is empty, so that the scheduler may give the CPU to a different task. To take advantage of the library's capability to yield the CPU when there are no actionable USB device events, ensure that the `CFG_TUSB_OS` symbol is defined, e.g `OPT_OS_FREERTOS` enables the FreeRTOS scheduler to schedule other threads than that which calls `tud_task()/tuh_task()`.
After the USB device is setup, the USB device code works by processing events on the main thread (by calling `tud_task`). These events are queued by the USB interrupt handler. So, there are three parts to the device low-level API: device setup, endpoint setup and interrupt processing.
Device API
^^^^^^^^^^
All of the code for the low-level device API is in `src/portable/<vendor>/<chip family>/dcd_<chip family>.c`.
After the USB device is setup, the USB device code works by processing events on the main thread (by calling ``tud_task``\ ). These events are queued by the USB interrupt handler. So, there are three parts to the device low-level API: device setup, endpoint setup and interrupt processing.
#### Device Setup
All of the code for the low-level device API is in ``src/portable/<vendor>/<chip family>/dcd_<chip family>.c``.
##### dcd_init
Device Setup
~~~~~~~~~~~~
dcd_init
""""""""
Initializes the USB peripheral for device mode and enables it.
This function should enable internal D+/D- pull-up for enumeration.
##### dcd_int_enable / dcd_int_disable
dcd_int_enable / dcd_int_disable
""""""""""""""""""""""""""""""""
Enables or disables the USB device interrupt(s). May be used to prevent concurrency issues when mutating data structures shared between main code and the interrupt handler.
##### dcd_int_handler
dcd_int_handler
"""""""""""""""
Processes all the hardware generated events e.g Bus reset, new data packet from host etc ... It will be called by application in the MCU USB interrupt handler.
##### dcd_set_address
dcd_set_address
"""""""""""""""
Called when the device is given a new bus address.
If your peripheral automatically changes address during enumeration (like the nrf52) you may leave this empty and also no queue an event for the corresponding SETUP packet.
##### dcd_remote_wakeup
dcd_remote_wakeup
"""""""""""""""""
Called to remote wake up host when suspended (e.g hid keyboard)
##### dcd_connect / dcd_disconnect
dcd_connect / dcd_disconnect
""""""""""""""""""""""""""""
Connect or disconnect the data-line pull-up resistor. Define only if MCU has an internal pull-up. (BSP may define for MCU without internal pull-up.)
#### Special events
Special events
~~~~~~~~~~~~~~
You must let TinyUSB know when certain events occur so that it can continue its work. There are a few methods you can call to queue events for TinyUSB to process.
##### dcd_event_bus_signal
dcd_event_bus_signal
""""""""""""""""""""
There are a number of events that your peripheral may communicate about the state of the bus. Here is an overview of what they are. Events in **BOLD** must be provided for TinyUSB to work.
* **DCD_EVENT_RESET** - Triggered when the host resets the bus causing the peripheral to reset. Do any other internal reset you need from the interrupt handler such as resetting the control endpoint.
* DCD_EVENT_SOF - Signals the start of a new USB frame.
The first `0` is the USB peripheral number. Statically saying 0 is common for single USB device MCUs.
The `true` indicates the call is from an interrupt handler and will always be the case when porting in this way.
The first ``0`` is the USB peripheral number. Statically saying 0 is common for single USB device MCUs.
##### dcd_setup_received
The ``true`` indicates the call is from an interrupt handler and will always be the case when porting in this way.
SETUP packets are a special type of transaction that can occur at any time on the control endpoint, numbered `0`. Since they are unique, most peripherals have special handling for them. Their data is always 8 bytes in length as well.
dcd_setup_received
""""""""""""""""""
SETUP packets are a special type of transaction that can occur at any time on the control endpoint, numbered ``0``. Since they are unique, most peripherals have special handling for them. Their data is always 8 bytes in length as well.
Calls to this look like:
..code-block::
dcd_event_setup_received(0, setup, true);
As before with `dcd_event_bus_signal` the first argument is the USB peripheral number and the third is true to signal its being called from an interrupt handler. The middle argument is byte array of length 8 with the contents of the SETUP packet. It can be stack allocated because it is copied into the queue.
#### Endpoints
As before with ``dcd_event_bus_signal`` the first argument is the USB peripheral number and the third is true to signal its being called from an interrupt handler. The middle argument is byte array of length 8 with the contents of the SETUP packet. It can be stack allocated because it is copied into the queue.
Endpoints
~~~~~~~~~
Endpoints are the core of the USB data transfer process. They come in a few forms such as control, isochronous, bulk, and interrupt. We won't cover the details here except with some caveats in open below. In general, data is transferred by setting up a buffer of a given length to be transferred on a given endpoint address and then waiting for an interrupt to signal that the transfer is finished. Further details below.
Endpoints within USB have an address which encodes both the number and direction of an endpoint. TinyUSB provides `tu_edpt_number` and `tu_edpt_dir` to unpack this data from the address. Here is a snippet that does it.
Endpoints within USB have an address which encodes both the number and direction of an endpoint. TinyUSB provides ``tu_edpt_number`` and ``tu_edpt_dir`` to unpack this data from the address. Here is a snippet that does it.
..code-block::
uint8_t epnum = tu_edpt_number(ep_addr);
uint8_t dir = tu_edpt_dir(ep_addr);
##### dcd_edpt_open
dcd_edpt_open
"""""""""""""
Opening an endpoint is done for all non-control endpoints once the host picks a configuration that the device should use. At this point, the endpoint should be enabled in the peripheral and configured to match the endpoint descriptor. Pay special attention to the direction of the endpoint you can get from the helper methods above. It will likely change what registers you are setting.
Also make sure to enable endpoint specific interrupts.
##### dcd_edpt_close
dcd_edpt_close
""""""""""""""
Close an endpoint. his function is used for implementing alternate settings.
@ -138,16 +177,17 @@ After calling this, the device should not respond to any packets directed toward
Implementation is optional. Must be called from the USB task. Interrupts could be disabled or enabled during the call.
##### dcd_edpt_xfer
dcd_edpt_xfer
"""""""""""""
`dcd_edpt_xfer` is responsible for configuring the peripheral to send or receive data from the host. "xfer" is short for "transfer". **This is one of the core methods you must implement for TinyUSB to work (one other is the interrupt handler).** Data from the host is the OUT direction and data to the host is IN. It is used for all endpoints including the control endpoint 0. Make sure to handle the zero-length packet STATUS packet on endpoint 0 correctly. It may be a special transaction to the peripheral.
``dcd_edpt_xfer`` is responsible for configuring the peripheral to send or receive data from the host. "xfer" is short for "transfer". **This is one of the core methods you must implement for TinyUSB to work (one other is the interrupt handler).** Data from the host is the OUT direction and data to the host is IN. It is used for all endpoints including the control endpoint 0. Make sure to handle the zero-length packet STATUS packet on endpoint 0 correctly. It may be a special transaction to the peripheral.
Besides that, all other transactions are relatively straight-forward. The endpoint address provides the endpoint
number and direction which usually determines where to write the buffer info. The buffer and its length are usually
written to a specific location in memory and the peripheral is told the data is valid. (Maybe by writing a 1 to a
register or setting a counter register to 0 for OUT or length for IN.)
The transmit buffer alignment is determined by `CFG_TUSB_MEM_ALIGN`.
The transmit buffer alignment is determined by ``CFG_TUSB_MEM_ALIGN``.
One potential pitfall is that the buffer may be longer than the maximum endpoint size of one USB
packet. Some peripherals can handle transmitting multiple USB packets for a provided buffer (like the SAMD21).
@ -155,37 +195,47 @@ Others (like the nRF52) may need each USB packet queued individually. To make th
some state for yourself and queue up an intermediate USB packet from the interrupt handler.
Once the transaction is going, the interrupt handler will notify TinyUSB of transfer completion.
During transmission, the IN data buffer is guarenteed to remain unchanged in memory until the `dcd_xfer_complete` function is called.
During transmission, the IN data buffer is guaranteed to remain unchanged in memory until the ``dcd_xfer_complete`` function is called.
The dcd_edpt_xfer function must never add zero-length-packets (ZLP) on its own to a transfer. If a ZLP is required,
then it must be explicitly sent by the stack calling dcd_edpt_xfer(), by calling dcd_edpt_xfer() a second time with len=0.
For control transfers, this is automatically done in `usbd_control.c`.
For control transfers, this is automatically done in ``usbd_control.c``.
At the moment, only a single buffer can be transmitted at once. There is no provision for double-buffering. new dcd_edpt_xfer() will not
be called again on the same endpoint address until the driver calls dcd_xfer_complete() (except in cases of USB resets).
##### dcd_xfer_complete
dcd_xfer_complete
"""""""""""""""""
Once a transfer completes you must call dcd_xfer_complete from the USB interrupt handler to let TinyUSB know that a transaction has completed. Here is a sample call:
* the actual length of the transfer. (OUT transfers may be smaller than the buffer given in `dcd_edpt_xfer`)
* the actual length of the transfer. (OUT transfers may be smaller than the buffer given in ``dcd_edpt_xfer``\ )
* the result of the transfer. Failure isn't handled yet.
* `true` to note the call is from an interrupt handler.
* ``true`` to note the call is from an interrupt handler.
##### dcd_edpt_stall / dcd_edpt_clear_stall
dcd_edpt_stall / dcd_edpt_clear_stall
"""""""""""""""""""""""""""""""""""""
Stalling is one way an endpoint can indicate failure such as when an unsupported command is transmitted. The pair of `dcd_edpt_stall`, `dcd_edpt_clear_stall` help manage the stall state of all endpoints.
Stalling is one way an endpoint can indicate failure such as when an unsupported command is transmitted. The pair of ``dcd_edpt_stall``\ , ``dcd_edpt_clear_stall`` help manage the stall state of all endpoints.
## Woohoo!
Woohoo!
-------
At this point you should have everything working! ;-) Of course, you may not write perfect code. Here are some tips and tricks for debugging.
Use [WireShark](https://www.wireshark.org/) or [a Beagle](https://www.totalphase.com/protocols/usb/) to sniff the USB traffic. When things aren't working its likely very early in the USB enumeration process. Figuring out where can help clue in where the issue is. For example:
Use `WireShark <https://www.wireshark.org/>`_ or `a Beagle <https://www.totalphase.com/protocols/usb/>`_ to sniff the USB traffic. When things aren't working its likely very early in the USB enumeration process. Figuring out where can help clue in where the issue is. For example:
* If the host sends a SETUP packet and its not ACKed then your USB peripheral probably isn't started correctly.
* If the peripheral is started correctly but it still didn't work, then verify your usb clock is correct. (You did output a PWM based on it right? ;-) )
* If the SETUP packet is ACKed but nothing is sent back then you interrupt handler isn't queueing the setup packet correctly. (Also, if you are using your own code instead of an example `tud_task` may not be called.) If thats OK, the `dcd_xfer_complete` may not be setting up the next transaction correctly.
* If the SETUP packet is ACKed but nothing is sent back then you interrupt handler isn't queueing the setup packet correctly. (Also, if you are using your own code instead of an example ``tud_task`` may not be called.) If that's OK, the ``dcd_xfer_complete`` may not be setting up the next transaction correctly.
It is relatively simple to incorporate tinyusb to your (existing) project
- Copy or `git submodule` this repo into your project in a subfolder. Let's say it is *your_project/tinyusb*
- Add all the .c in the `tinyusb/src` folder to your project
- Add *your_project/tinyusb/src* to your include path. Also make sure your current include path also contains the configuration file tusb_config.h.
- Make sure all required macros are all defined properly in tusb_config.h (configure file in demo application is sufficient, but you need to add a few more such as CFG_TUSB_MCU, CFG_TUSB_OS since they are passed by IDE/compiler to maintain a unique configure for all boards).
- If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to implement all **tud_descriptor_** callbacks for the stack to work.
- Add tusb_init() call to your reset initialization code.
- Call `tud_int_handler()` (device) and/or `tuh_int_handler()` (host) in your USB IRQ Handler
- Implement all enabled classes's callbacks.
- If you don't use any RTOSes at all, you need to continuously and/or periodically call tud_task()/tuh_task() function. All of the callbacks and functionality are handled and invoked within the call of that task runner.
~~~{.c}
int main(void)
{
your_init_code();
tusb_init(); // initialize tinyusb stack
while(1) // the mainloop
{
your_application_code();
tud_task(); // device task
tuh_task(); // host task
}
}
~~~
## Examples
For your convenience, TinyUSB contains a handful of examples for both host and device with/without RTOS to quickly test the functionality as well as demonstrate how API() should be used. Most examples will work on most of [the supported Boards](boards.md). Firstly we need to `git clone` if not already
Some TinyUSB examples also requires external submodule libraries in `/lib` such as FreeRTOS, Lightweight IP to build. Run following command to fetch them
```
$ git submodule update --init lib
```
In addition, MCU driver submodule is also needed to provide low-level MCU peripheral's driver. Luckily, it will be fetched if needed when you run the `make` to build your board.
Note: some examples especially those that uses Vendor class (e.g webUSB) may requires udev permission on Linux (and/or macOS) to access usb device. It depends on your OS distro, typically copy `/examples/device/99-tinyusb.rules` file to /etc/udev/rules.d/ then run `sudo udevadm control --reload-rules && sudo udevadm trigger` is good enough.
### Build
To build example, first change directory to an example folder.
```
$ cd examples/device/cdc_msc
```
Then compile with `make BOARD=[board_name] all`, for example
```
$ make BOARD=feather_nrf52840_express all
```
Note: `BOARD` can be found as directory name in `hw/bsp`, either in its family/boards or directly under bsp (no family).
#### Port Selection
If a board has several ports, one port is chosen by default in the individual board.mk file. Use option `PORT=x` To choose another port. For example to select the HS port of a STM32F746Disco board, use:
```
$ make BOARD=stm32f746disco PORT=1 all
```
#### Port Speed
A MCU can support multiple operational speed. By default, the example build system will use the fastest supported on the board. Use option `SPEED=full/high` e.g To force F723 operate at full instead of default high speed
```
$ make BOARD=stm32f746disco SPEED=full all
```
### Debug
To compile for debugging add `DEBUG=1`, for example
```
$ make BOARD=feather_nrf52840_express DEBUG=1 all
```
#### Log
Should you have an issue running example and/or submitting an bug report. You could enable TinyUSB built-in debug logging with optional `LOG=`. LOG=1 will only print out error message, LOG=2 print more information with on-going events. LOG=3 or higher is not used yet.
```
$ make BOARD=feather_nrf52840_express LOG=2 all
```
#### Logger
By default log message is printed via on-board UART which is slow and take lots of CPU time comparing to USB speed. If your board support on-board/external debugger, it would be more efficient to use it for logging. There are 2 protocols:
- `LOGGER=rtt`: use [Segger RTT protocol](https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/)
- Cons: requires jlink as the debugger.
- Pros: work with most if not all MCUs
- Software viewer is JLink RTT Viewer/Client/Logger which is bundled with JLink driver package.
- `LOGGER=swo`: Use dedicated SWO pin of ARM Cortex SWD debug header.
- Cons: only work with ARM Cortex MCUs minus M0
- Pros: should be compatible with more debugger that support SWO.
- Software viewer should be provided along with your debugger driver.
```
$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=rtt all
$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=swo all
```
### Flash
`flash` target will use the default on-board debugger (jlink/cmsisdap/stlink/dfu) to flash the binary, please install those support software in advance. Some board use bootloader/DFU via serial which is required to pass to make command
```
$ make BOARD=feather_nrf52840_express flash
$ make SERIAL=/dev/ttyACM0 BOARD=feather_nrf52840_express flash
```
Since jlink can be used with most of the boards, there is also `flash-jlink` target for your convenience.
```
$ make BOARD=feather_nrf52840_express flash-jlink
```
Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can be generated with `uf2` target
TinyUSB is an open-source cross-platform USB Host/Device stack for embedded systems,
designed to be memory-safe with no dynamic allocation and thread-safe with all interrupt events being deferred and then handled in the non-ISR task function.
- Allow the use of non-static allocation for FreeRTOS
- Fix FreeRTOS wrong task switch in some cases
- Fix tu_fifo memory overflown when repeatedly write to overwritable fifo (accumulated more than 2 depths)
- Better support for IAR (ARM) with ci build check for stm32 mcus.
- Fix Windows build for some mingw gnu make situations
Controller Driver (DCD & HCD)
-----------------------------
- Add new port support (WIP) for WCH CH32V307 USB Highspeed
- Add new port support (WIP) for PIC32MM/MX & PIC24
- [nRF]
- Fix endpoint internal state when closed
- Fix reception of large ISO packets
- [rp2040]
- [dcd] Implement workaround for Errata 15. This enable SOF when bulk-in endpoint is in use and reduce its bandwidth to only 80%
- [hcd] Fix shared irq slots filling up when hcd_init() is called multiple times
- [hcd] Support host bulk endpoint using hw "interrupt" endpoint. Note speed limit is 64KB/s
- [samd][dcd] Add support for ISO endpoint
- [dwc2][dcd] Add support for stm32u5xx
- [esp32sx] Fix Isochronous transfers only transmitted on even frame
- [lpc_ip3511][dcd] Add isochronous support and fix endpoint accidental write
- [ft90x] Improve and enhance support for FT9xx MCU, tested with more examples
Device Stack
------------
- [Video]
- Add support for MJPEG
- Fix probe on macOS
- [MIDI]
- Support port name strings
- fix MS Header wTotalLength computation
- [HID]
- Add FIDO descriptor template
- change length in tud_hid_report_complete_cb() from uint8 to uint16
- [CDC]
- Fix autoflush for FIFO < MPS
- Fix tx fifo memory overflown when DTR is not set and tud_cdc_write() is called repeatedly with large enough data
- [USBTMC] Fix packet size with highspeed
Host Stack
----------
- Retry a few times with transfers in enumeration since device can be unstable when starting up
- [MSC] Rework host masstorage API. Add new **host/msc_file_explorer** example
- [CDC]
- Add support for host cdc
- Fix host cdc with device without IAD e.g Arduino Due
0.14.0
======
- Improve compiler support for CCRX and IAR
- Add timeout to osal_queue_receive()
- Add tud_task_ext(timeout, in_isr) as generic version of tud_task(). Same as tuh_task_ext(), tuh_task()
- Enable more warnings -Wnull-dereference -Wuninitialized -Wunused -Wredundant-decls -Wconversion
- Add new examples
- host/bare_api to demonstrate generic (app-level) enumeration and endpoint transfer
- dual/host_hid_to_device_cdc to run both device and host stack concurrently, get HID report from host and print out to device CDC. This example only work with multiple-controller MCUs and rp2040 with the help of pio-usb as added controller.
Controller Driver (DCD & HCD)
-----------------------------
- Enhance rhports management to better support dual roles
- CFG_TUD_ENABLED/CFG_TUH_ENABLED, CFG_TUD_MAX_SPEED/CFG_TUH_MAX_SPEED can be used to replace CFG_TUSB_RHPORT0_MODE/CFG_TUSB_RHPORT1_MODE
- tud_init(rphort), tuh_init(rhport) can be used to init stack on specified roothub port (controller) instead of tusb_init(void)
- Add dcd/hcd port specific defines `TUP_` (stand for tinyusb port-specific)
- [dwc2]
- Update to support stm32 h72x, h73x with only 1 otg controller
- Fix overwrite with grstctl when disable endpoint
- [EHCI] Fix an issue with EHCI driver
- [msp430] Fix for possible bug in msp430-elf-gcc 9.3.0
- [nrf5x] Fix DMA access race condition using atomic function
- [pic32] Fix PIC32 santiy
- [rp2040]
- Add PICO-PIO-USB as controller (device/host) support for rp2040
- Use shared IRQ handlers, so user can also hook the USB IRQ
- Fix resumed signal not reported to device stack
- [stm32fsdev] Add support for stm32wb55
Device Stack
------------
- [Audio] Add support for feedback endpoint computation
- New API tud_audio_feedback_params_cb(), tud_audio_feedback_interval_isr().
- Supported computation method are: frequency with fixed/float or power of 2. Feedback with fifo count is not yet supported.
- Fix nitfs (should be 3) in TUD_AUDIO_HEADSET_STEREO_DESCRIPTOR
- Fix typo in audiod_rx_done_cb()
- [DFU] Fix coexistence with other interfaces BTH, RNDIS
- [MSC] Fix inquiry response additional length field
- [Venndor] Improve write performance
Host Stack
----------
- Add new API tuh_configure(rhport, cfg_id, cfg_param) for dynamnic port specific behavior configuration
- [HID] Open OUT endpoint if available
- [Hub] hub clear port and device interrupts
- [USBH] Major improvement
- Rework usbh control transfer with complete callback. New API tuh_control_xfer() though still only carry 1 usbh (no queueing) at a time.
- Add generic endpoint transfer with tuh_edpt_open(), tuh_edpt_xfer(). Require `CFG_TUH_API_EDPT_XFER=1`
- [ChipIdea] rename Transdimension to more popular ChipIdea Highspeed,
- [RP2040] various update/fix for hcd/dcd
- [FT9XX] new DCD port for Bridgetek FT90x and FT93x devices
- [DA1469X] Fix resume
- [OHCI] Fix device array out of bound
Note: legacy drivers such as st/synopsys, nxp/transdimension are still present in this release but won't receive more update and could be removed in the future.
Device Stack
------------
- [Audio] Support disabling feedback format correction (16.16 <-> 10.14 format)
- [MSC] Add tud_msc_request_sense_cb() callback, change most default sense error to medium not present (0x02, 0x3A, 0x00)
- [Video] Fix video_capture example fails enumeration when 8FPS
Host Stack
----------
No notable changes
0.12.0
======
- add CFG_TUSB_OS_INC_PATH for os include path
Device Controller Driver (DCD)
------------------------------
- Getting device stack to pass USB Compliance Verification test (chapter9, HID, MSC). Ports are tested:
- Add CFG_TUH_MSC_MAXLUN (default to 4) to hold lun capacities
### Others
Others
------
- Add basic support for rt-thread OS
- Change zero bitfield length to more explicit padding
@ -177,25 +516,33 @@ MSC
- LPCXpresso 55s28
- LPCXpresso 18s37
## 0.8.0 - 2021.02.05
### Device Controller Driver
0.8.0 (2021-02-05)
==================
Device Controller Driver
------------------------
- Added new device support for Raspberry Pi RP2040
- Added new device support for NXP Kinetis KL25ZXX
- Use dcd_event_bus_reset() with link speed to replace bus_signal
- ESP32-S2:
- Add bus suspend and wakeup support
- SAMD21:
- Fix (walkaround) samd21 setup_packet overflow by USB DMA
- STM32 Synopsys:
- Rework USB FIFO allocation scheme and allow RX FIFO size reduction
- Sony CXD56
- Update Update Spresense SDK to 2.0.2
- Fix dcd issues with setup packets
- Correct EP number for cdc_msc example
### USB Device
USB Device
----------
**USBD**
@ -207,13 +554,17 @@ MSC
- CDC
- Allow to transmit data, even if the host does not support control line states i.e set DTR
- HID
- change default CFG_TUD_HID_EP_BUFSIZE from 16 to 64
- MIDI
- Fix midi sysex sending bug
- MSC
- Invoke only scsi complete callback after status transaction is complete.
- Fix scsi_mode_sense6_t padding, which cause IAR compiler internal error.
- USBTMC
- Change interrupt endpoint example size to 8 instead of 2 for better compatibility with mcu
@ -222,11 +573,14 @@ MSC
- Support make from windows cmd.exe
- Add HID Consumer Control (media keys) to hid_composite & hid_composite_freertos examples
### USB Host
USB Host
--------
No noticeable changes to host stack
### New Boards
New Boards
----------
- NXP/Freescale Freedom FRDM-KL25Z
- Feather Double M33 express
@ -241,14 +595,18 @@ No noticeable changes to host stack
- Adafruit PyPortal
- Great Scott Gadgets' LUNA D11 & D21
## 0.7.0 - 2020.11.08
### Device Controller Driver
0.7.0 (2020-11-08)
==================
Device Controller Driver
------------------------
- Added new support for Espressif ESP32-S2
- Added new support for Dialog DA1469x
- Enhance STM32 Synopsys
- Support bus events disconnection/suspend/resume/wakeup
- Support bus events disconnection/suspend/resume/wakeup
- Improve transfer performance with optimizing xfer and fifo size
- Support Highspeed port (OTG_HS) with both internal and external PHY
- Support multiple usb ports with rhport=1 is highspeed on selected MCUs e.g H743, F23. It is possible to have OTG_HS to run on Fullspeed PHY (e.g lacking external PHY)
@ -256,23 +614,30 @@ No noticeable changes to host stack
- Fix FIFO flush during stall
- Implement dcd_edpt_close() API
- Support F105, F107
- Enhance STM32 fsdev
- Improve dcd fifo allocation
- Fix ISTR race condition
- Support remap USB IRQ on supported MCUs
- Implement dcd_edpt_close() API
- Enhance NUC 505: enhance set configure behavior
- Enhance SAMD
- Fix race condition with setup packet
- Add SAMD11 option `OPT_MCU_SAMD11`
- Add SAME5x option `OPT_MCU_SAME5X`
- Fix SAMG control data toggle and stall race condition
- Enhance nRF
- Fix hanged when tud_task() is called within critical section (disabled interrupt)
- Fix disconnect bus event not submitted
- Implement ISO transfer and dcd_edpt_close()
### USB Device
USB Device
----------
**USBD**
@ -289,10 +654,12 @@ No noticeable changes to host stack
- Add IAR compiler support
- Support multiple configuration descriptors. `TUD_CONFIG_DESCRIPTOR()` template has extra config_num as 1st argument
- Improve USB Highspeed support with actual link speed detection with `dcd_event_bus_reset()`
- Enhance class driver management
- `usbd_driver_open()` add max length argument, and return length of interface (0 for not supported). Return value is used for finding appropriate driver
- Add application implemented class driver via `usbd_app_driver_get_cb()`
@ -347,13 +725,16 @@ No noticeable changes to host stack
- Microchip: Great Scoot Gadgets' LUNA, samd11_xplained, D5035-01, atsamd21 xplained pro
- nRF: ItsyBitsy nRF52840
## 0.6.0 - 2020.03.30
Added **CONTRIBUTORS.md** to give proper credit for contributors to the stack. Special thanks to [Nathan Conrad](https://github.com/pigrew), [Peter Lawrence](https://github.com/majbthrd) and [William D. Jones](https://github.com/cr1901) and others for spending their precious time to add lots of features and ports for this release.
0.6.0 (2020-03-30)
==================
### Added
Added**CONTRIBUTORS.md** to give proper credit for contributors to the stack. Special thanks to `Nathan Conrad <https://github.com/pigrew>`__ , `Peter Lawrence <https://github.com/majbthrd>`__ , `William D. Jones <https://github.com/cr1901>`__ and `Sean Cross <https://github.com/xobs>`__ and others for spending their precious time to add lots of features and ports for this release.
**MCUs**
Added
-----
**MCU**
- Added support for Microchip SAMG55
- Added support for Nordic nRF52833
@ -389,62 +770,8 @@ Following examples are added:
- usbtmc
- webusb_serial
**Boards**
Following boards are added:
- adafruit_clue
- arduino_nano33_ble
- circuitplayground_bluefruit
- circuitplayground_express
- feather_m0_express
- feather_nrf52840_sense
- feather_stm32f405
- fomu
- itsybitsy_m0
- itsybitsy_m4
- lpcxpresso11u37
- lpcxpresso1549
- lpcxpresso51u68
- lpcxpresso54114
- lpcxpresso55s69
- mbed1768
- mimxrt1010_evk
- mimxrt1015_evk
- mimxrt1020_evk
- mimxrt1050_evkb
- mimxrt1060_evk
- mimxrt1064_evk
- msp_exp430f5529lp
- ngx4330
- nrf52840_mdk_dongle
- nutiny_nuc121s
- nutiny_nuc125s
- nutiny_nuc126v
- nutiny_sdk_nuc120
- nutiny_sdk_nuc505
- pca10059
- pca10100
- pyboardv11
- raytac_mdbt50q_rx
- samg55xplained
- seeeduino_xiao
- spresense
- stm32f070rbnucleo
- stm32f072disco
- stm32f103bluepill
- stm32f207nucleo
- stm32f401blackpill
- stm32f411blackpill
- stm32f411disco
- stm32f412disco
- stm32f767nucleo
- stm32h743nucleo
- stm32l0538disco
- stm32l476disco
- teensy_40
### Changed
Changed
-------
- Changed `tud_descriptor_string_cb()` to have additional Language ID argument
- Merged hal_nrf5x.c into dcd_nrf5x.c
@ -452,7 +779,7 @@ Following boards are added:
- Generalized dcd_stm32f4.c to dcd_synopsys.c
- Changed cdc_msc_hid to cdc_msc (drop hid) due to limited endpoints number of some MCUs
- Improved usbd/usbd_control with proper hanlding of zero-length packet (ZLP)
- Improved usbd/usbd_control with proper handling of zero-length packet (ZLP)
- Improved STM32 DCD FSDev
- Improved STM32 DCD Synopsys
- Migrated CI from Travis to Github Action
@ -460,9 +787,12 @@ Following boards are added:
- Fixed mynewt osal queue definition
- Fixed cdc_msc_freertos example build for all MCUs
## 0.5.0 (Initial Release) - 2019.07.10
0.5.0 (2019-06)
===============
First release, device stack works great, host stack works but still need improvement.
- Special thanks to @adafruit team, especially @tannewt to help out immensely to rework device stack: simplify osal & control transfer, adding SAMD21/SAMD51 ports, writing porting docs, adding MIDI class support etc...
The TinyUSB library is designed to operate on single-core MCUs with multi-threaded applications in mind. Interaction with interrupts is especially important to pay attention to.
It is compatible with optionally using a RTOS.
## General
General
-------
When writing code, keep in mind that the OS (if using a RTOS) may swap out your code at any time. Also, your code can be preempted by an interrupt at any time.
## Application Code
Application Code
----------------
The USB core does not execute application callbacks while in an interrupt context. Calls to application code are from within the USB core task context. Note that the application core will call class drivers from within their own task.
## Class Drivers
Class Drivers
-------------
Class driver code should never be called from an interrupt context by the USB core, though the application is allowed to call class driver functions from interrupts. USB core functions may be called simultaneously by multiple tasks. Use care that proper locking is used to guard the USBD core functions from this case.
Class drivers are allowed to call `usbd_*` functions, but not `dcd_*` functions.
Class drivers are allowed to call ``usbd_*`` functions, but not ``dcd_*`` functions.
## USB Core
USB Core
--------
All functions that may be called from an (USB core) interrupt context have a `bool in_isr` parameter to remind the implementer that special care must be taken.
All functions that may be called from an (USB core) interrupt context have a ``bool in_isr`` parameter to remind the implementer that special care must be taken.
Interrupt handlers must not directly call class driver code, they must pass a message to the USB core's task.
`usbd_*` functions may be called from interrupts without any notice. They may also be called simultaneously by multiple tasks.
``usbd_*`` functions may be called from interrupts without any notice. They may also be called simultaneously by multiple tasks.
## Device Drivers
Device Drivers
--------------
Much of the processing of the USB stack is done in an interrupt context, and care must be taken in order to ensure variables are handled in the appropriate ways by the compiler and optimizer.
In particular:
- Ensure that all memory-mapped registers (including packet memory) are marked as volatile. GCC's optimizer will even combine memory access (like two 16-bit to be a 32-bit) if you don't mark the pointers as volatile. On some architectures, this can use macros like `_I`, `_O`, or `_IO'.
- All defined global variables are marked as `static`.
* Ensure that all memory-mapped registers (including packet memory) are marked as volatile. GCC's optimizer will even combine memory access (like two 16-bit to be a 32-bit) if you don't mark the pointers as volatile. On some architectures, this can use macros like _I , _O , or _IO.
* All defined global variables are marked as ``static``.
It is relatively simple to incorporate tinyusb to your (existing) project
* Copy or ``git submodule`` this repo into your project in a subfolder. Let's say it is *your_project/tinyusb*
* Add all the .c in the ``tinyusb/src`` folder to your project
* Add *your_project/tinyusb/src* to your include path. Also make sure your current include path also contains the configuration file tusb_config.h.
* Make sure all required macros are all defined properly in tusb_config.h (configure file in demo application is sufficient, but you need to add a few more such as CFG_TUSB_MCU, CFG_TUSB_OS since they are passed by IDE/compiler to maintain a unique configure for all boards).
* If you use the device stack, make sure you have created/modified usb descriptors for your own need. Ultimately you need to implement all **tud descriptor** callbacks for the stack to work.
* Add tusb_init() call to your reset initialization code.
* Call ``tud_int_handler()`` (device) and/or ``tuh_int_handler()`` (host) in your USB IRQ Handler
* Implement all enabled classes's callbacks.
* If you don't use any RTOSes at all, you need to continuously and/or periodically call tud_task()/tuh_task() function. All of the callbacks and functionality are handled and invoked within the call of that task runner.
..code-block::
int main(void)
{
your_init_code();
tusb_init(); // initialize tinyusb stack
while(1) // the mainloop
{
your_application_code();
tud_task(); // device task
tuh_task(); // host task
}
}
Examples
--------
For your convenience, TinyUSB contains a handful of examples for both host and device with/without RTOS to quickly test the functionality as well as demonstrate how API() should be used. Most examples will work on most of `the supported boards <supported.rst>`_. Firstly we need to ``git clone`` if not already
Some ports will also require a port-specific SDK (e.g. RP2040) or binary (e.g. Sony Spresense) to build examples. They are out of scope for tinyusb, you should download/install it first according to its manufacturer guide.
Build
^^^^^
To build example, first change directory to an example folder.
..code-block::
$ cd examples/device/cdc_msc
Before building, we firstly need to download dependencies such as: MCU low-level peripheral driver and external libraries e.g FreeRTOS (required by some examples). Run the ``get-deps`` target in one of the example folder as follow. You only need to do this once per mcu. Check out `complete list of dependencies and their designated path here <dependencies.rst>`_
..code-block::
$ make BOARD=raspberry_pi_pico get-deps
Then compile with ``make BOARD=[board_name] all``\ , for example
..code-block::
$ make BOARD=raspberry_pi_pico all
Note: ``BOARD`` can be found as directory name in ``hw/bsp``\ , either in its family/boards or directly under bsp (no family).
Note: some examples especially those that uses Vendor class (e.g webUSB) may requires udev permission on Linux (and/or macOS) to access usb device. It depends on your OS distro, typically copy ``99-tinyusb.rules`` and reload your udev is good to go
$ sudo udevadm control --reload-rules && sudo udevadm trigger
Port Selection
~~~~~~~~~~~~~~
If a board has several ports, one port is chosen by default in the individual board.mk file. Use option ``PORT=x`` To choose another port. For example to select the HS port of a STM32F746Disco board, use:
..code-block::
$ make BOARD=stm32f746disco PORT=1 all
Port Speed
~~~~~~~~~~
A MCU can support multiple operational speed. By default, the example build system will use the fastest supported on the board. Use option ``SPEED=full/high`` e.g To force F723 operate at full instead of default high speed
..code-block::
$ make BOARD=stm32f746disco SPEED=full all
Size Analysis
~~~~~~~~~~~~~
First install `linkermap tool <https://github.com/hathach/linkermap>`_ then ``linkermap`` target can be used to analyze code size. You may want to compile with ``NO_LTO=1`` since -flto merges code across .o files and make it difficult to analyze.
..code-block::
$ make BOARD=feather_nrf52840_express NO_LTO=1 all linkermap
Debug
^^^^^
To compile for debugging add ``DEBUG=1``\ , for example
..code-block::
$ make BOARD=feather_nrf52840_express DEBUG=1 all
Log
~~~
Should you have an issue running example and/or submitting an bug report. You could enable TinyUSB built-in debug logging with optional ``LOG=``. LOG=1 will only print out error message, LOG=2 print more information with on-going events. LOG=3 or higher is not used yet.
..code-block::
$ make BOARD=feather_nrf52840_express LOG=2 all
Logger
~~~~~~
By default log message is printed via on-board UART which is slow and take lots of CPU time comparing to USB speed. If your board support on-board/external debugger, it would be more efficient to use it for logging. There are 2 protocols:
* `LOGGER=rtt`: use `Segger RTT protocol <https://www.segger.com/products/debug-probes/j-link/technology/about-real-time-transfer/>`_
* Cons: requires jlink as the debugger.
* Pros: work with most if not all MCUs
* Software viewer is JLink RTT Viewer/Client/Logger which is bundled with JLink driver package.
* ``LOGGER=swo``\ : Use dedicated SWO pin of ARM Cortex SWD debug header.
* Cons: only work with ARM Cortex MCUs minus M0
* Pros: should be compatible with more debugger that support SWO.
* Software viewer should be provided along with your debugger driver.
..code-block::
$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=rtt all
$ make BOARD=feather_nrf52840_express LOG=2 LOGGER=swo all
Flash
^^^^^
``flash`` target will use the default on-board debugger (jlink/cmsisdap/stlink/dfu) to flash the binary, please install those support software in advance. Some board use bootloader/DFU via serial which is required to pass to make command
..code-block::
$ make BOARD=feather_nrf52840_express flash
$ make SERIAL=/dev/ttyACM0 BOARD=feather_nrf52840_express flash
Since jlink can be used with most of the boards, there is also ``flash-jlink`` target for your convenience.
..code-block::
$ make BOARD=feather_nrf52840_express flash-jlink
Some board use uf2 bootloader for drag & drop in to mass storage device, uf2 can be generated with ``uf2`` target
..code-block::
$ make BOARD=feather_nrf52840_express all uf2
IAR Support
^^^^^^^^^^^
IAR Project Connection files are provided to import TinyUSB stack into your project.
* A buldable project of your MCU need to be created in advance.
* Take example of STM32F0:
- You need `stm32l0xx.h`, `startup_stm32f0xx.s`, `system_stm32f0xx.c`.
- `STM32L0xx_HAL_Driver` is only needed to run examples, TinyUSB stack itself doesn't rely on MCU's SDKs.
* Open `Tools -> Configure Custom Argument Variables` (Switch to `Global` tab if you want to do it for all your projects)
Click `New Group ...`, name it to `TUSB`, Click `Add Variable ...`, name it to `TUSB_DIR`, change it's value to the path of your TinyUSB stack,
Supports multiple device configurations by dynamically changing usb descriptors. Low power functions such like suspend, resume, and remote wakeup. Following device classes are supported:
- Audio Class 2.0 (UAC2)
- Bluetooth Host Controller Interface (BTH HCI)
- Communication Class (CDC)
- Device Firmware Update (DFU): DFU mode (WIP) and Runtinme
- Human Interface Device (HID): Generic (In & Out), Keyboard, Mouse, Gamepad etc ...
- Mass Storage Class (MSC): with multiple LUNs
- Musical Instrument Digital Interface (MIDI)
- Network with RNDIS, CDC-ECM (work in progress)
- USB Test and Measurement Class (USBTMC)
- Vendor-specific class support with generic In & Out endpoints. Can be used with MS OS 2.0 compatible descriptor to load winUSB driver without INF file.
- `WebUSB <https://github.com/WICG/webusb>`__ with vendor-specific class
If you have special need, `usbd_app_driver_get_cb()` can be used to write your own class driver without modifying the stack. Here is how RPi team add their reset interface `raspberrypi/pico-sdk#197 <https://github.com/raspberrypi/pico-sdk/pull/197>`__
Host Stack
==========
- Human Interface Device (HID): Keyboard, Mouse, Generic
- Mass Storage Class (MSC)
- Hub currently only supports 1 level of hub (due to my laziness)
OS Abstraction layer
====================
TinyUSB is completely thread-safe by pushing all ISR events into a central queue, then process it later in the non-ISR context task function. It also uses semaphore/mutex to access shared resources such as CDC FIFO. Therefore the stack needs to use some of OS's basic APIs. Following OSes are already supported out of the box.
- **No OS**
- **FreeRTOS**
- **Mynewt** Due to the newt package build system, Mynewt examples are better to be on its `own repo <https://github.com/hathach/mynewt-tinyusb-example>`__
License
=======
All TinyUSB sources in the `src` folder are licensed under MIT license. However, each file can be individually licensed especially those in `lib` and `hw/mcu` folder. Please make sure you understand all the license term for files you use in your project.
The board support code is only used for self-contained examples and testing. It is not used when TinyUSB is part of a larger project. It is responsible for getting the MCU started and the USB peripheral clocked with minimal of on-board devices
- One LED : for status
- One Button : to get input from user
- One UART : optional for device, but required for host examples
The following boards are supported (sorted alphabetically):
Broadcom
--------
- `Raspberry Pi CM4 <https://www.raspberrypi.com/products/compute-module-4>`__
Dialog DA146xx
--------------
- `DA14695 Development Kit – USB <https://www.dialog-semiconductor.com/products/da14695-development-kit-usb>`__
- `DA1469x Development Kit – Pro <https://www.dialog-semiconductor.com/products/da14695-development-kit-pro>`__
- `LPCXpresso18S37 Development Board <https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/general-purpose-mcus/lpc4000-cortex-m4/lpcxpresso18s37-development-board:OM13076>`__
#define CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX 2 // This value is not required by the driver, it parses this information from the descriptor once the alternate interface is set by the host - we use it for the setup
#define CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX 4 // This value is not required by the driver, it parses this information from the descriptor once the alternate interface is set by the host - we use it for the setup
#define CFG_TUD_AUDIO_EP_SZ_IN (48 + 1) * CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX * CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX // 48 Samples (48 kHz) x 2 Bytes/Sample x CFG_TUD_AUDIO_N_CHANNELS_TX Channels - the Windows driver always needs an extra sample per channel of space more, otherwise it complains... found by trial and error
#define CFG_TUD_AUDIO_FUNC_1_CHANNEL_PER_FIFO_TX 2 // One I2S stream contains two channels, each stream is saved within one support FIFO - this value is currently fixed, the driver does not support a changing value
#define CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX 2 // Driver gets this info from the descriptors - we define it here to use it to setup the descriptors and to do calculations with it below
#define CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX 1 // Driver gets this info from the descriptors - we define it here to use it to setup the descriptors and to do calculations with it below - be aware: for different number of channels you need another descriptor!
#define CFG_TUD_AUDIO_EP_SZ_IN 48 * CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX * CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX // 48 Samples (48 kHz) x 2 Bytes/Sample x 1 Channel
#define CFG_TUD_AUDIO_EP_SZ_IN (48 + 1) * CFG_TUD_AUDIO_FUNC_1_N_BYTES_PER_SAMPLE_TX * CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX // 48 Samples (48 kHz) x 2 Bytes/Sample x CFG_TUD_AUDIO_N_CHANNELS_TX Channels - One extra sample is needed for asynchronous transfer adjustment, see feedback EP
#define CFG_TUD_AUDIO_FUNC_1_EP_IN_SZ_MAX CFG_TUD_AUDIO_EP_SZ_IN // Maximum EP IN size for all AS alternate settings used
#define CFG_TUD_AUDIO_FUNC_1_N_AS_INT 1 // Number of Standard AS Interface Descriptors (4.9.1) defined per audio function - this is required to be able to remember the current alternate settings of these interfaces - We restrict us here to have a constant number for all audio functions (which means this has to be the maximum number of AS interfaces an audio function has and a second audio function with less AS interfaces just wastes a few bytes)
#define CFG_TUD_AUDIO_FUNC_1_CTRL_BUF_SZ 64 // Size of control request buffer
#define CFG_TUD_AUDIO_ENABLE_EP_IN 1
#define CFG_TUD_AUDIO_FUNC_1_N_CHANNELS_TX 1 // Driver gets this info from the descriptors - we define it here to use it to setup the descriptors and to do calculations with it below - be aware: for different number of channels you need another descriptor!
#define CFG_TUD_AUDIO_FUNC_1_EP_IN_SZ_MAX TU_MAX(CFG_TUD_AUDIO_FUNC_1_FORMAT_1_EP_SZ_IN, CFG_TUD_AUDIO_FUNC_1_FORMAT_2_EP_SZ_IN) // Maximum EP IN size for all AS alternate settings used
