usb: Add a note about buffer thread safety.

projectgus · projectgus · commit f3f434920f3d · 2024-07-11T11:23:23.000+10:00
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 &lt;angus@redyak.com.au&gt;
diff --git a/micropython/usb/README.md b/micropython/usb/README.md
@@ -134,3 +134,16 @@ 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).
+
