Add SETUP_EP0_OUT_BUF(), for OUT control transfers.

When processing OUT control transfers, the EP0 buffer is armed when
wriging EP0BCL, while SDPAUTO is high. At this stage it's not
necessary to set HSNAK, because that bit has an effect on the status
stage, not on the data stage.

Beyond it being not necessary to write HSNAK early, it introduces a
race condition, because the host sees the status stage complete early,
before we have fully processed the content of EP0BUF, and as such it
thinks it can send more control transfers. If the host actually sends
more control transfers, then EP0BUF might be overwritten before we have
completed processing EP0BUF, and this can cause data corruption.

The clean way to handle this, is to force the host to wait in the status
stage until we have fully processed the EP0BUF, by NAK-ink the status
stage. This does not mean that the packets in the Data stage will be
NAK'd because, that is controlled by whether the buffer is armed or not.

This commit deprecates `SETUP_EP0_BUF(length)`, and introduces:
- `SETUP_EP0_IN_BUF(length)` as a direct replacement for IN transfers
- `SETUP_EP0_OUT_BUF()` as a new macro to perform OUT transfers

The new recommended way to do OUT control transfers is:

```c
for (each_expected_packet) {
    SETUP_EP0_OUT_BUF();
    handle_packet(EP0BUF, EP0BCL);
      // EP0BCL will have the size of the received packet
}
ACK_EP0();
```

That is: only call `ACK_EP0()`, which clears HSNAK by writing 1 to it,
after we know it's safe to overwrite EP0BUF.

Note: a simple way to reproduce the issue when not following this
procedure, is to run:

```bash
while true; do lsusb -v -d $(DEVICE_VID):$(DEVICE_PID) > /dev/null; done
```

In a terminal. (replacing DEVICE_VID/DEVICE_PID with correct values)
While this loop is running, we expected most applications doing control
out transfers with the old method to become unusable.

Technically speaking a single run of `lsusb` could even cause trouble if
it happes at the wrong time, and I think this could be triggered in
other situations as well, this is just the easiest way to reproduce the
problem.

Author: purdeaandrei

firmware/library/include/fx2usb.h

@@ -53,9 +53,22 @@ void usb_init(bool disconnect);
   } while(0)
 
 /**
- * Configure EP0 for an IN or OUT transfer from or to `EP0BUF`.
- * For an OUT transfer, specify `length` as `0`.
- */
+  * This call is deprecated.
+  *
+  * Old documentation said:
+  * Configure EP0 for an IN or OUT transfer from or to `EP0BUF`.
+  * For an OUT transfer, specify `length` as `0`.
+  *
+  * However using `SETUP_EP0_BUF(0)` for OUT transfers will expose a
+  * race condition when the host is too eager to send more control
+  * transfers.
+  *
+  * For IN control transfers, please use `SETUP_EP0_IN_BUF(length)` instead.
+  *
+  * For OUT control transfers, please use one or more `SETUP_EP0_OUT_BUF()`,
+  * followed by a single `ACK_EP0()` call, but only after all data has been
+  * processed from `EP0BUF`.
+  */
 #define SETUP_EP0_BUF(length) \
   do { \
     SUDPTRCTL = _SDPAUTO; \
@@ -64,6 +77,31 @@ void usb_init(bool disconnect);
     EP0CS = _HSNAK; \
   } while(0)
 
+/**
+ * Configure EP0 for an IN transfer from `EP0BUF`.
+ */
+#define SETUP_EP0_IN_BUF(length) \
+  do { \
+    SUDPTRCTL = _SDPAUTO; \
+    EP0BCH = 0; \
+    EP0BCL = length; \
+    EP0CS = _HSNAK; \
+  } while(0)
+
+/**
+ * Configure EP0 for an OUT transfer from `EP0BUF`.
+ *
+ * For OUT transfers please use one or more calls to
+ * `SETUP_EP0_OUT_BUF()` followed by a single call to `ACK_EP0()`.
+ * Do not call `ACK_EP0()` before processing all pending data in `EP0BUF`
+ */
+#define SETUP_EP0_OUT_BUF() \
+  do { \
+    SUDPTRCTL = _SDPAUTO; \
+    EP0BCH = 0; \
+    EP0BCL = 0; \
+  } while(0)
+
 /**
  * Acknowledge an EP0 SETUP or OUT transfer.
  */