From 01f45c118f39610d8fcb2064d237b89ec5b81269 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 11 Jul 2024 11:23:23 +1000 Subject: [PATCH] usb: Add a note about buffer thread safety. This is to replace a commit which added locking here but caused some other problems. The idea behind the Buffer class is that a single producer can call pend_write() more than once and it's idempotent, however this is very complex to extend across multiple threads. Signed-off-by: Angus Gratton --- micropython/usb/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/micropython/usb/README.md b/micropython/usb/README.md index 342a0a7e..d4b975d1 100644 --- a/micropython/usb/README.md +++ b/micropython/usb/README.md @@ -134,3 +134,15 @@ USB MIDI devices in MicroPython. The example [midi_example.py](examples/device/midi_example.py) demonstrates how to create a simple MIDI device to send MIDI data to and from the USB host. + +### Limitations + +#### Buffer thread safety + +The internal Buffer class that's used by most of the USB device classes expects data +to be written to it (i.e. sent to the host) by only one thread. Bytes may be +lost from the USB transfers if more than one thread (or a thread and a callback) +try to write to the buffer simultaneously. + +If writing USB data from multiple sources, your code may need to add +synchronisation (i.e. locks).