Software APIs
dif_usbdev.h
Go to the documentation of this file.
1 // Copyright lowRISC contributors.
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_USBDEV_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_USBDEV_H_
7 
8 /**
9  * @file
10  * @brief <a href="/hw/ip/usbdev/doc/">USB Device</a> Device Interface Functions
11  */
12 
13 #include <stddef.h>
14 #include <stdint.h>
17 
18 #ifdef __cplusplus
19 extern "C" {
20 #endif // __cplusplus
21 
22 /**
23  * Hardware constants.
24  */
25 #define USBDEV_NUM_ENDPOINTS 12
26 #define USBDEV_MAX_PACKET_SIZE 64
27 // Internal constant that should not be used by clients. Defined here because
28 // it is used in the definition of `dif_usbdev_buffer_pool` below.
29 #define USBDEV_NUM_BUFFERS 32
30 
31 /**
32  * Free buffer pool.
33  *
34  * A USB device has a fixed number of buffers that are used for storing incoming
35  * and outgoing packets and the software is responsible for keeping track of
36  * free buffers. The pool is implemented as a stack for constant-time add and
37  * remove. `top` points to the last free buffer added to the pool. The pool is
38  * full when `top == USBDEV_NUM_BUFFERS - 1` and empty when `top == -1`.
39  */
40 typedef struct dif_usbdev_buffer_pool {
41  uint8_t buffers[USBDEV_NUM_BUFFERS];
42  int8_t top;
44 
45 /**
46  * Buffer types.
47  */
48 typedef enum dif_usbdev_buffer_type {
49  /**
50  * For reading payloads of incoming packets.
51  */
53  /**
54  * For writing payloads of outgoing packets.
55  */
57  /**
58  * Clients must not use a buffer after it is handed over to hardware or
59  * returned to the free buffer pool. This type exists to protect against such
60  * cases.
61  */
64 
65 /**
66  * A USB device buffer.
67  *
68  * This struct represents a USB device buffer that has been provided to a client
69  * in response to a buffer request. Clients should treat instances of this
70  * struct as opaque objects and should pass them to the appropriate functions of
71  * this library to read and write payloads of incoming and outgoing packets,
72  * respectively.
73  *
74  * See also: `dif_usbdev_recv`, `dif_usbdev_buffer_read`,
75  * `dif_usbdev_buffer_request`, `dif_usbdev_buffer_write`,
76  * `dif_usbdev_send`, `dif_usbdev_buffer_return`.
77  */
78 typedef struct dif_usbdev_buffer {
79  /**
80  * Hardware buffer id.
81  */
82  uint8_t id;
83  /**
84  * Byte offset for the next read or write operation.
85  */
86  uint8_t offset;
87  /**
88  * For read buffers: remaining number of bytes to read.
89  * For write buffers: remaining number of bytes that can be written.
90  */
91  uint8_t remaining_bytes;
92  /**
93  * Type of this buffer.
94  */
95  dif_usbdev_buffer_type_t type;
97 
98 /**
99  * Internal state of a USB device.
100  *
101  * Instances of this struct must be initialized by `dif_usbdev_init()` before
102  * being passed to other functions in this library. Its fields should be
103  * considered private and are only provided here so that callers can allocate
104  * it.
105  */
106 typedef struct dif_usbdev {
107  mmio_region_t base_addr;
108  dif_usbdev_buffer_pool_t buffer_pool;
109 } dif_usbdev_t;
110 
111 /**
112  * Enumeration for enabling/disabling various functionality.
113  */
114 typedef enum dif_usbdev_toggle {
115  kDifUsbdevToggleDisable,
116  kDifUsbdevToggleEnable,
118 
119 /**
120  * Set of allowed configurations for USB power sense override.
121  */
123  kDifUsbdevPowerSenseOverrideDisabled,
124  kDifUsbdevPowerSenseOverridePresent,
125  kDifUsbdevPowerSenseOverrideNotPresent
127 
128 /**
129  * Configuration for initializing a USB device.
130  */
131 typedef struct dif_usbdev_config {
132  /**
133  * Base address of the USB device.
134  */
136  /**
137  * Use the differential rx signal instead of the single-ended signals.
138  */
139  dif_usbdev_toggle_t differential_rx;
140  /**
141  * Use the differential tx signal instead of the single-ended signals.
142  */
143  dif_usbdev_toggle_t differential_tx;
144  /*
145  * Recognize a single SE0 bit as end of packet instead of requiring
146  * two bits.
147  */
148  dif_usbdev_toggle_t single_bit_eop;
149  /**
150  * Override USB power sense.
151  */
152  dif_usbdev_power_sense_override_t power_sense_override;
153  /**
154  * Flip the D+/D- pins.
155  */
156  dif_usbdev_toggle_t pin_flip;
157  /**
158  * Reference signal generation for clock synchronization.
159  */
160  dif_usbdev_toggle_t clock_sync_signals;
162 
163 /**
164  * Common return codes for the functions in this library.
165  */
166 typedef enum dif_usbdev_result {
167  /**
168  * Indicates that the call succeeded.
169  */
171  /**
172  * Indicates that a non-specific error occurred and the hardware is in an
173  * invalid or irrecoverable state.
174  */
176  /**
177  * Indicates that the caller supplied invalid arguments but the call did not
178  * cause any side-effects and the hardware is in a valid and recoverable
179  * state.
180  */
183 
184 /**
185  * Initialize a USB device.
186  *
187  * A USB device must first be initialized by this function before calling other
188  * functions in this library.
189  *
190  * @param config Configuration for initializing a USB device.
191  * @param[out] usbdev Internal state of the initialized USB device.
192  * @return The result of the operation.
193  */
196  dif_usbdev_t *usbdev);
197 
198 /**
199  * Fill the available buffer FIFO of a USB device.
200  *
201  * The USB device has a small FIFO (AV FIFO) that stores free buffers for
202  * incoming packets. It is the responsibility of the software to ensure that the
203  * AV FIFO is never empty. If the host tries to send a packet when the AV FIFO
204  * is empty, the USB device will respond with a NAK. While this will typically
205  * cause the host to retry transmission for regular data packets, there are
206  * transactions in the USB protocol during which the USB device is not allowed
207  * to send a NAK. Thus, the software must make sure that the AV FIFO is never
208  * empty by calling this function periodically.
209  *
210  * @param usbdev A USB device.
211  * @return The result of the operation.
212  */
215 
216 /**
217  * Enable or disable reception of SETUP packets for an endpoint.
218  *
219  * @param usbdev A USB device.
220  * @param endpoint An endpoint.
221  * @param new_state New SETUP packet reception state.
222  * @return The result of the operation.
223  */
226  dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state);
227 
228 /**
229  * Enable or disable reception of OUT packets for an endpoint.
230  *
231  * @param usbdev A USB device.
232  * @param endpoint An endpoint.
233  * @param new_state New OUT packet reception state.
234  * @return The result of the operation.
235  */
238  dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state);
239 
240 /**
241  * Enable or disable STALL for an endpoint.
242  *
243  * @param usbdev A USB device.
244  * @param endpoint An endpoint.
245  * @param new_state New STALL state.
246  * @return The result of the operation.
247  */
250  dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state);
251 
252 /**
253  * Get STALL state of an endpoint.
254  *
255  * @param usbdev A USB device.
256  * @param endpoint An endpoint.
257  * @param[out] state Current STALL state.
258  * @return The result of the operation.
259  */
262  uint8_t endpoint,
263  bool *state);
264 
265 /**
266  * Enable or disable isochronous mode for an endpoint.
267  *
268  * Isochronous endpoints transfer data periodically. Since isochronous transfers
269  * do not have a handshaking stage, isochronous endpoints cannot report errors
270  * or STALL conditions.
271  *
272  * @param usbdev A USB device.
273  * @param endpoint An endpoint.
274  * @param new_state New isochronous state.
275  * @return The result of the operation.
276  */
279  dif_usbdev_t *usbdev, uint8_t endpoint, dif_usbdev_toggle_t new_state);
280 
281 /**
282  * Enable the USB interface of a USB device.
283  *
284  * Calling this function causes the USB device to assert the full-speed pull-up
285  * signal to indicate its presence to the host.
286  *
287  * @param usbdev A USB device.
288  * @param new_state New interface state.
289  * @return The result of the operation.
290  */
293  dif_usbdev_toggle_t new_state);
294 
295 /**
296  * Information about a received packet.
297  */
299  /**
300  * Endpoint of the packet.
301  */
302  uint8_t endpoint;
303  /**
304  * Payload length in bytes.
305  */
306  uint8_t length;
307  /**
308  * Indicates if the packet is a SETUP packet.
309  */
310  bool is_setup;
312 
313 /**
314  * Return codes for `dif_usbdev_recv`.
315  */
317  /**
318  * Indicates that the call succeeded.
319  */
321  /**
322  * Indicates that a non-specific error occurred and the hardware is in an
323  * invalid or irrecoverable state.
324  */
326  /**
327  * Indicates that the caller supplied invalid arguments but the call did not
328  * cause any side-effects and the hardware is in a valid and recoverable
329  * state.
330  */
332  /**
333  * Indicates that RX FIFO is empty.
334  */
337 
338 /**
339  * Get the packet at the front of RX FIFO.
340  *
341  * The USB device has a small FIFO (RX FIFO) that stores received packets until
342  * the software has a chance to process them. It is the responsibility of the
343  * software to ensure that the RX FIFO is never full. If the host tries to send
344  * a packet when the RX FIFO is full, the USB device will respond with a NAK.
345  * While this will typically cause the host to retry transmission for regular
346  * data packets, there are transactions in the USB protocol during which the USB
347  * device is not allowed to send a NAK. Thus, the software must read received
348  * packets as soon as possible.
349  *
350  * Reading received packets involves two main steps:
351  * - Calling this function, i.e. `dif_usbdev_recv`, and
352  * - Calling `dif_usbdev_buffer_read` until the entire packet payload
353  * is read.
354  *
355  * In order to read an incoming packet, clients should first call this function
356  * to get information about the packet and the buffer that holds the packet
357  * payload. Then, clients should call `dif_usbdev_buffer_read` with this buffer
358  * one or more times (depending on the sizes of their internal buffers) until
359  * the entire packet payload is read. Once the entire payload is read, the
360  * buffer is returned to the free buffer pool. If the clients want to ignore the
361  * payload of a packet, e.g. for an unsupported or a zero-length packet, they
362  * can call `dif_usbdev_buffer_return` to immediately return the buffer to the
363  * free buffer pool.
364  *
365  * @param usbdev A USB device.
366  * @param[out] packet_info Packet information.
367  * @param[out] buffer Buffer that holds the packet payload.
368  * @return The result of the operation.
369  */
371 dif_usbdev_recv_result_t dif_usbdev_recv(
372  dif_usbdev_t *usbdev, dif_usbdev_rx_packet_info_t *packet_info,
373  dif_usbdev_buffer_t *buffer);
374 
375 /**
376  * Return codes for `dif_usbdev_buffer_read`.
377  */
379  /**
380  * Indicates that the call succeeded and the entire packet payload is read.
381  */
383  /**
384  * Indicates that a non-specific error occurred and the hardware is in an
385  * invalid or irrecoverable state.
386  */
388  /**
389  * Indicates that the caller supplied invalid arguments but the call did not
390  * cause any side-effects and the hardware is in a valid and recoverable
391  * state.
392  */
394  /**
395  * Indicates that the call was successful but there are remaining bytes to be
396  * read.
397  */
400 
401 /**
402  * Read incoming packet payload.
403  *
404  * Clients should call this function with a buffer provided by `dif_usbdev_recv`
405  * to read the payload of an incoming packet. This function copies the smaller
406  * of `dst_len` and remaining number of bytes in the buffer to `dst`. The buffer
407  * that holds the packet payload is returned to the free buffer pool when the
408  * entire packet payload is read.
409  *
410  * See also: `dif_usbdev_recv`.
411  *
412  * @param usbdev A USB device.
413  * @param buffer A buffer provided by `dif_usbdev_recv`.
414  * @param[out] dst Destination buffer.
415  * @param dst_len Length of the destination buffer.
416  * @param[out] bytes_written Number of bytes written to destination buffer.
417  * @return The result of the operation.
418  */
420 dif_usbdev_buffer_read_result_t dif_usbdev_buffer_read(
421  dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer, uint8_t *dst,
422  size_t dst_len, size_t *bytes_written);
423 
424 /**
425  * Return a buffer to the free buffer pool.
426  *
427  * This function immediately returns the given buffer to the free buffer pool.
428  * Since `dif_usbdev_buffer_read` and `dif_usbdev_get_tx_status` return the
429  * buffers that they work on to the free buffer pool automatically, this
430  * function should only be called to discard the payload of a received
431  * packet or a packet that was being prepared for transmission before it is
432  * queued for transmission from an endpoint.
433  *
434  * See also: `dif_usbdev_recv`, `dif_usbdev_buffer_request`.
435  *
436  * @param usbdev A USB device.
437  * @param buffer A buffer provided by `dif_usbdev_recv` or
438  * `dif_usbdev_buffer_request`.
439  * @return The result of the operation.
440  */
443  dif_usbdev_buffer_t *buffer);
444 
445 /**
446  * Return codes for `dif_usbdev_buffer_request`.
447  */
449  /**
450  * Indicates that the call succeeded.
451  */
453  /**
454  * Indicates that a non-specific error occurred and the hardware is in an
455  * invalid or irrecoverable state.
456  */
458  /**
459  * Indicates that the caller supplied invalid arguments but the call did not
460  * cause any side-effects and the hardware is in a valid and recoverable
461  * state.
462  */
464  /**
465  * Indicates that there are no free buffers.
466  */
469 
470 /**
471  * Request a buffer for outgoing packet payload.
472  *
473  * Clients should call this function to request a buffer to write the payload of
474  * an outgoing packet. Sending a packet from a particular endpoint to the host
475  * involves four main steps:
476  * - Calling this function, i.e. `dif_usbdev_buffer_request`,
477  * - Calling `dif_usbdev_buffer_write`,
478  * - Calling `dif_usbdev_send`, and
479  * - Calling `dif_usbdev_get_tx_status`.
480  *
481  * In order to send a packet, clients should first call this function to obtain
482  * a buffer for the packet payload. Clients should then call
483  * `dif_usbdev_buffer_write` (one or more times depending on the sizes of their
484  * internal buffers) to write the packet payload to this buffer. After writing
485  * the packet payload, clients should call `dif_usbdev_send` to mark the packet
486  * as ready for transmission from a particular endpoint. Then, clients should
487  * call `dif_usbdev_get_tx_status` to check the status of the transmission.
488  * `dif_usbdev_get_tx_status` returns the buffer that holds the packet payload
489  * to the free buffer pool once the packet is either successfully transmitted or
490  * canceled due to an incoming SETUP packet or a link reset. If the packet
491  * should no longer be sent, clients can call `dif_usbdev_buffer_return` to
492  * return the buffer to the free buffer pool as long as `dif_usbdev_send` is not
493  * called yet.
494  *
495  * See also: `dif_usbdev_buffer_write`, `dif_usbdev_send`,
496  * `dif_usbdev_get_tx_status`, `dif_usbdev_buffer_return`.
497  *
498  * @param usbdev A USB device.
499  * @param[out] buffer A buffer for writing outgoing packet payload.
500  * @return The result of the operation.
501  */
503 dif_usbdev_buffer_request_result_t dif_usbdev_buffer_request(
504  dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer);
505 
507  /**
508  * Indicates that the call succeeded.
509  */
511  /**
512  * Indicates that a non-specific error occurred and the hardware is in an
513  * invalid or irrecoverable state.
514  */
516  /**
517  * Indicates that the caller supplied invalid arguments but the call did not
518  * cause any side-effects and the hardware is in a valid and recoverable
519  * state.
520  */
522  /**
523  * Indicates that the requested write exceeds the device buffer size.
524  */
526 } dif_usbdev_buffer_write_result_t;
527 
528 /**
529  * Write outgoing packet payload.
530  *
531  * Clients should call this function with a buffer provided by
532  * `dif_usbdev_buffer_request` to write the payload of an outgoing packet. This
533  * function copies the smaller of `src_len` and remaining number of bytes in the
534  * buffer to the buffer. Clients should then call `dif_usbdev_send` to queue the
535  * packet for transmission from a particular endpoint.
536  *
537  * See also: `dif_usbdev_buffer_request`, `dif_usbdev_send`,
538  * `dif_usbdev_get_tx_status`, `dif_usbdev_buffer_return`.
539  *
540  * @param usbdev A USB device.
541  * @param buffer A buffer provided by `dif_usbdev_buffer_request`.
542  * @param src Source buffer.
543  * @param src_len Length of the source buffer.
544  * @param[out] bytes_written Number of bytes written to the USB device buffer.
545  * @return The result of the operation.
546  */
548 dif_usbdev_buffer_write_result_t dif_usbdev_buffer_write(
549  dif_usbdev_t *usbdev, dif_usbdev_buffer_t *buffer, uint8_t *src,
550  size_t src_len, size_t *bytes_written);
551 
552 /**
553  * Mark a packet ready for transmission from an endpoint.
554  *
555  * The USB device has 12 endpoints, each of which can be used to send packets to
556  * the host. Since a packet is not actually transmitted to the host until the
557  * host sends an IN token, clients must write the packet payload to a device
558  * buffer and mark it as ready for transmission from a particular endpoint. A
559  * packet queued for transmission from a particular endpoint is transmitted once
560  * the host sends an IN token for that endpoint.
561  *
562  * After a packet is queued for transmission, clients should check its status by
563  * calling `dif_usbdev_get_tx_status`. While the USB device handles transmission
564  * errors automatically by retrying transmission, transmission of a packet may
565  * be canceled if the endpoint receives a SETUP packet or the link is reset
566  * before the queued packet is transmitted. In these cases, clients should
567  * handle the SETUP packet or the link reset first and then optionally send the
568  * same packet again. Clients must also make sure that the given endpoint does
569  * not already have a packet pending for transmission before calling this
570  * function.
571  *
572  * See also: `dif_usbdev_buffer_request`, `dif_usbdev_buffer_write`,
573  * `dif_usbdev_get_tx_status`, `dif_usbdev_buffer_return`.
574  *
575  * @param usbdev A USB device.
576  * @param endpoint An endpoint.
577  * @param buffer A buffer provided by `dif_usbdev_buffer_request`.
578  * @return The result of the operation.
579  */
581 dif_usbdev_result_t dif_usbdev_send(dif_usbdev_t *usbdev, uint8_t endpoint,
582  dif_usbdev_buffer_t *buffer);
583 
584 /**
585  * Status of an outgoing packet.
586  */
587 typedef enum dif_usbdev_tx_status {
588  /**
589  * There is no packet for the given endpoint.
590  */
592  /**
593  * Packet is pending transmission.
594  */
596  /**
597  * Packet was sent successfully.
598  */
600  /**
601  * Transmission was canceled due to an incoming SETUP packet.
602  */
605 
606 /**
607  * Get the status of a packet that has been queued to be sent from an endpoint.
608  *
609  * While the USB device handles transmission errors automatically by retrying
610  * transmission, transmission of a packet may be canceled if the endpoint
611  * receives a SETUP packet or the link is reset before the queued packet is
612  * transmitted. In these cases, clients should handle the SETUP packet or the
613  * link reset first and then optionally send the same packet again.
614  *
615  * This function returns the buffer that holds the packet payload to the free
616  * buffer pool once the packet is either successfully transmitted or canceled
617  * due to an incoming SETUP packet or a link reset.
618  *
619  * @param usbdev A USB device.
620  * @param endpoint An endpoint.
621  * @param[out] status Status of the packet.
622  * @return The result of the operation.
623  */
626  uint8_t endpoint,
627  dif_usbdev_tx_status_t *status);
628 
629 /**
630  * Set the address of a USB device.
631  *
632  * @param usbdev A USB device.
633  * @param addr New address. Only the last 7 bits are significant.
634  * @return The result of the operation.
635  */
638 
639 /**
640  * Get the address of a USB device.
641  *
642  * @param usbdev A USB device.
643  * @param[out] addr Current address.
644  * @return The result of the operation.
645  */
648 
649 /**
650  * Get USB frame index.
651  *
652  * @param usbdev A USB device.
653  * @param[out] frame_index USB frame index.
654  * @return The result of the operation.
655  */
658  uint16_t *frame_index);
659 
660 /**
661  * Check if the host is lost.
662  *
663  * The host is lost if the link is still active but a start of frame packet has
664  * not been received in the last 4.096ms.
665  *
666  * @param usbdev A USB device.
667  * @param[out] host_lost Status of the host. `true` if the host is lost, `false`
668  * otherwise.
669  * @return The result of the operation.
670  */
673  bool *host_lost);
674 
675 /**
676  * USB link state.
677  */
678 typedef enum dif_usbdev_link_state {
679  kDifUsbdevLinkStateDisconnected,
680  kDifUsbdevLinkStatePowered,
681  kDifUsbdevLinkStatePoweredSuspend,
682  kDifUsbdevLinkStateActive,
683  kDifUsbdevLinkStateSuspend,
685 
686 /**
687  * Get USB link state.
688  *
689  * @param usbdev A USB device.
690  * @param[out] link_state USB link state.
691  * @return The result of the operation.
692  */
695  dif_usbdev_t *usbdev, dif_usbdev_link_state_t *link_state);
696 
697 /**
698  * Get the state of the sense pin.
699  *
700  * @param usbdev A USB device.
701  * @param[out] sense State of the sense pin. `true` if the host is providing
702  * VBUS, `false` otherwise.
703  * @return The result of the operation.
704  */
707  bool *sense);
708 
709 /**
710  * Get the depth of the AV FIFO.
711  *
712  * See also: `dif_usbdev_fill_available_fifo`.
713  *
714  * @param usbdev A USB device.
715  * @param[out] depth Depth of the AV FIFO.
716  * @return The result of the operation.
717  */
720  dif_usbdev_t *usbdev, uint8_t *depth);
721 /**
722  * Check if AV FIFO is full.
723  *
724  * See also: `dif_usbdev_fill_available_fifo`.
725  *
726  * @param usbdev A USB device.
727  * @param[out] is_full State of the AV FIFO. `true` if full, false otherwise.
728  * @return The result of the operation.
729  */
732  dif_usbdev_t *usbdev, bool *is_full);
733 /**
734  * Get the depth of the RX FIFO.
735  *
736  * See also: `dif_usbdev_recv`.
737  *
738  * @param usbdev A USB device.
739  * @param[out] depth Depth of the RX FIFO.
740  * @return The result of the operation.
741  */
744  uint8_t *depth);
745 
746 /**
747  * Check if the RX FIFO is empty.
748  *
749  * See also: `dif_usbdev_recv`.
750  *
751  * @param usbdev A USB device.
752  * @param[out] is_empty State of the RX FIFO. `true` if empty, `false`
753  * otherwise.
754  * @return The result of the operation.
755  */
758  bool *is_empty);
759 
760 /**
761  * USB device interrupts.
762  */
763 typedef enum dif_usbdev_irq {
764  /**
765  * \internal First USB device interrupt.
766  */
767  kDifUsbdevIrqFirst,
768  /**
769  * A packet was received as part of an OUT or SETUP transaction.
770  */
771  kDifUsbdevIrqPktReceived = kDifUsbdevIrqFirst,
772  /**
773  * A packet was sent as part of an IN transaction.
774  */
776  /**
777  * VBUS was lost and the link was disconnected.
778  */
780  /**
781  * A Start-of-Frame (SOF) packet was not received on an active link
782  * for 4.096 ms. The host must send a SOF packet every 1 ms.
783  */
785  /**
786  * Link was reset by the host.
787  */
789  /**
790  * Link was suspended by the host.
791  */
793  /**
794  * Link became active again after being suspended.
795  */
797  /**
798  * Available buffer FIFO was empty.
799  */
801  /**
802  * Received buffer FIFO was full.
803  */
805  /**
806  * A write was done to available buffer FIFO when it was full.
807  */
809  /**
810  * The ACK packet expected in response to an IN transaction was
811  * not received.
812  */
814  /**
815  * A CRC error occurred.
816  */
818  /**
819  * A packet with an invalid packet identifier (PID) was received.
820  */
822  /**
823  * A packet with invalid bitstuffing was received.
824  */
826  /**
827  * USB frame number was updated with a valid SOF packet.
828  */
830  /**
831  * VBUS was detected.
832  */
834  /**
835  * \internal Last USB device interrupt.
836  */
837  kDifUsbdevIrqLast = kDifUsbdevIrqConnected
839 
840 /**
841  * Enable or disable an interrupt.
842  *
843  * @param usbdev A USB device.
844  * @param irq An interrupt.
845  * @param state New state of the interrupt.
846  * @return The result of the operation.
847  */
850  dif_usbdev_irq_t irq,
851  dif_usbdev_toggle_t state);
852 
853 /**
854  * Check if there is a pending request for an interrupt.
855  *
856  * @param usbdev A USB device.
857  * @param irq An interrupt.
858  * @param[out] state State of the interrupt.
859  * @return The result of the operation.
860  */
863  dif_usbdev_irq_t irq, bool *state);
864 
865 /**
866  * Clear an interrupt.
867  *
868  * @param usbdev A USB device.
869  * @param irq An interrupt.
870  * @return The result of the operation.
871  */
874  dif_usbdev_irq_t irq);
875 
876 /**
877  * Clear all pending interrupts.
878  *
879  * @param usbdev A USB device.
880  * @return The result of the operation.
881  */
884 
885 /**
886  * Disable all interrupts and optionally return the current interrupt
887  * configuration.
888  *
889  * @param usbdev A USB device.
890  * @param[out] cur_config Current interrupt configuration.
891  * @return The result of the operation.
892  */
895  uint32_t *cur_config);
896 
897 /**
898  * Restore interrupt configuration.
899  *
900  * @param usbdev A USB device.
901  * @param new_config New interrupt configuration.
902  * @return The result of the operation.
903  */
906  uint32_t new_config);
907 
908 /**
909  * Test an interrupt.
910  *
911  * @param usbdev A USB device.
912  * @param irq An interrupt.
913  * @return The result of the operation.
914  */
917  dif_usbdev_irq_t irq);
918 
919 #ifdef __cplusplus
920 } // extern "C"
921 #endif // __cplusplus
922 
923 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_USBDEV_H_