blob: 12c1a09f97ed75efea7ef284da0e720581eae424 [file] [log] [blame]
Alphan Ulusoy425450c2020-02-19 07:50:54 -05001// 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
Philipp Wagner847ec7a2020-07-30 13:54:18 +01008/**
9 * @file
10 * @brief <a href="/hw/ip/usbdev/doc/">USB Device</a> Device Interface Functions
11 */
12
Alphan Ulusoy425450c2020-02-19 07:50:54 -050013#include <stddef.h>
14#include <stdint.h>
Timothy Trippele3f8a822021-09-17 06:09:28 +000015
16#include "sw/device/lib/base/macros.h"
Sam Elliottcb76df42020-08-20 17:45:55 +010017#include "sw/device/lib/base/mmio.h"
Timothy Trippelae484372021-10-07 06:42:41 +000018#include "sw/device/lib/dif/dif_base.h"
19
20#include "sw/device/lib/dif/autogen/dif_usbdev_autogen.h"
Alphan Ulusoy425450c2020-02-19 07:50:54 -050021
Michael Munday0c0ece52021-03-22 14:35:57 +000022#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
Alphan Ulusoy425450c2020-02-19 07:50:54 -050026/**
27 * Hardware constants.
28 */
29#define USBDEV_NUM_ENDPOINTS 12
30#define USBDEV_MAX_PACKET_SIZE 64
31// Internal constant that should not be used by clients. Defined here because
32// it is used in the definition of `dif_usbdev_buffer_pool` below.
33#define USBDEV_NUM_BUFFERS 32
34
Alexander Williamse18d88b2022-01-21 16:30:39 -080035// Constants used for the `dif_usbdev_endpoint_id` direction field.
36#define USBDEV_ENDPOINT_DIR_IN 1
37#define USBDEV_ENDPOINT_DIR_OUT 0
38
39typedef struct dif_usbdev_endpoint_id {
40 /**
41 * Endpoint number.
42 */
43 unsigned int number : 4;
44 /**
45 * Reserved. Should be zero.
46 */
47 unsigned int reserved : 3;
48 /**
49 * Endpoint direction. 1 = IN endpoint, 0 = OUT endpoint
50 */
51 unsigned int direction : 1;
52} dif_usbdev_endpoint_id_t;
53
Alphan Ulusoy425450c2020-02-19 07:50:54 -050054/**
55 * Free buffer pool.
56 *
57 * A USB device has a fixed number of buffers that are used for storing incoming
58 * and outgoing packets and the software is responsible for keeping track of
59 * free buffers. The pool is implemented as a stack for constant-time add and
60 * remove. `top` points to the last free buffer added to the pool. The pool is
61 * full when `top == USBDEV_NUM_BUFFERS - 1` and empty when `top == -1`.
62 */
63typedef struct dif_usbdev_buffer_pool {
Alphan Ulusoy364c4112020-07-27 22:54:14 -040064 uint8_t buffers[USBDEV_NUM_BUFFERS];
Alphan Ulusoy425450c2020-02-19 07:50:54 -050065 int8_t top;
66} dif_usbdev_buffer_pool_t;
67
68/**
Alphan Ulusoy364c4112020-07-27 22:54:14 -040069 * Buffer types.
Alphan Ulusoy425450c2020-02-19 07:50:54 -050070 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -040071typedef enum dif_usbdev_buffer_type {
Alphan Ulusoy425450c2020-02-19 07:50:54 -050072 /**
Alphan Ulusoy364c4112020-07-27 22:54:14 -040073 * For reading payloads of incoming packets.
Alphan Ulusoy425450c2020-02-19 07:50:54 -050074 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -040075 kDifUsbdevBufferTypeRead,
Alphan Ulusoy425450c2020-02-19 07:50:54 -050076 /**
Alphan Ulusoy364c4112020-07-27 22:54:14 -040077 * For writing payloads of outgoing packets.
Alphan Ulusoy425450c2020-02-19 07:50:54 -050078 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -040079 kDifUsbdevBufferTypeWrite,
Alphan Ulusoy425450c2020-02-19 07:50:54 -050080 /**
Alphan Ulusoy364c4112020-07-27 22:54:14 -040081 * Clients must not use a buffer after it is handed over to hardware or
82 * returned to the free buffer pool. This type exists to protect against such
83 * cases.
Alphan Ulusoy425450c2020-02-19 07:50:54 -050084 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -040085 kDifUsbdevBufferTypeStale,
86} dif_usbdev_buffer_type_t;
87
88/**
89 * A USB device buffer.
90 *
91 * This struct represents a USB device buffer that has been provided to a client
92 * in response to a buffer request. Clients should treat instances of this
93 * struct as opaque objects and should pass them to the appropriate functions of
94 * this library to read and write payloads of incoming and outgoing packets,
95 * respectively.
96 *
97 * See also: `dif_usbdev_recv`, `dif_usbdev_buffer_read`,
98 * `dif_usbdev_buffer_request`, `dif_usbdev_buffer_write`,
99 * `dif_usbdev_send`, `dif_usbdev_buffer_return`.
100 */
101typedef struct dif_usbdev_buffer {
102 /**
103 * Hardware buffer id.
104 */
105 uint8_t id;
106 /**
107 * Byte offset for the next read or write operation.
108 */
109 uint8_t offset;
110 /**
111 * For read buffers: remaining number of bytes to read.
112 * For write buffers: remaining number of bytes that can be written.
113 */
114 uint8_t remaining_bytes;
115 /**
116 * Type of this buffer.
117 */
118 dif_usbdev_buffer_type_t type;
119} dif_usbdev_buffer_t;
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500120
121/**
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500122 * Configuration for initializing a USB device.
123 */
124typedef struct dif_usbdev_config {
125 /**
Alexander Williamsc4eb9a42022-02-16 08:30:19 -0800126 * Activate the single-ended D signal for detecting K and J symbols, for use
127 * with a differential receiver.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500128 */
Alexander Williamsc4eb9a42022-02-16 08:30:19 -0800129 dif_toggle_t have_differential_receiver;
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500130 /**
Alexander Williamsa784c012022-02-10 15:43:43 -0800131 * Use the TX interface with D and SE0 signals instead of Dp/Dn, for use with
132 * certain transceivers.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500133 */
Alexander Williamsa784c012022-02-10 15:43:43 -0800134 dif_toggle_t use_tx_d_se0;
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500135 /*
136 * Recognize a single SE0 bit as end of packet instead of requiring
137 * two bits.
138 */
Timothy Trippelae484372021-10-07 06:42:41 +0000139 dif_toggle_t single_bit_eop;
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500140 /**
Alphan Ulusoyc340fd62020-07-29 09:50:29 -0400141 * Flip the D+/D- pins.
142 */
Timothy Trippelae484372021-10-07 06:42:41 +0000143 dif_toggle_t pin_flip;
Alphan Ulusoyc340fd62020-07-29 09:50:29 -0400144 /**
145 * Reference signal generation for clock synchronization.
146 */
Timothy Trippelae484372021-10-07 06:42:41 +0000147 dif_toggle_t clock_sync_signals;
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500148} dif_usbdev_config_t;
149
150/**
Timothy Trippel0242a8b2021-10-07 01:23:58 +0000151 * Configures a USB device with runtime information.
152 *
153 * This function should need to be called once for the lifetime of `handle`.
154 *
155 * @param usbdev A USB device.
Timothy Trippel4cbe3cb2021-10-07 05:22:01 +0000156 * @param buffer_pool A USB device buffer pool.
Timothy Trippel0242a8b2021-10-07 01:23:58 +0000157 * @param config Runtime configuration parameters for a USB device.
158 * @return The result of the operation.
159 */
160OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000161dif_result_t dif_usbdev_configure(const dif_usbdev_t *usbdev,
162 dif_usbdev_buffer_pool_t *buffer_pool,
163 dif_usbdev_config_t config);
Timothy Trippel0242a8b2021-10-07 01:23:58 +0000164
165/**
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500166 * Fill the available buffer FIFO of a USB device.
167 *
168 * The USB device has a small FIFO (AV FIFO) that stores free buffers for
169 * incoming packets. It is the responsibility of the software to ensure that the
170 * AV FIFO is never empty. If the host tries to send a packet when the AV FIFO
171 * is empty, the USB device will respond with a NAK. While this will typically
172 * cause the host to retry transmission for regular data packets, there are
173 * transactions in the USB protocol during which the USB device is not allowed
174 * to send a NAK. Thus, the software must make sure that the AV FIFO is never
175 * empty by calling this function periodically.
176 *
177 * @param usbdev A USB device.
Timothy Trippel4cbe3cb2021-10-07 05:22:01 +0000178 * @param buffer_pool A USB device buffer pool.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500179 * @return The result of the operation.
180 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000181OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000182dif_result_t dif_usbdev_fill_available_fifo(
Timothy Trippel054b2462021-10-07 05:41:09 +0000183 const dif_usbdev_t *usbdev, dif_usbdev_buffer_pool_t *buffer_pool);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500184
185/**
186 * Enable or disable reception of SETUP packets for an endpoint.
187 *
Alexander Williamse18d88b2022-01-21 16:30:39 -0800188 * This controls whether the pair of IN and OUT endpoints with the specified
189 * endpoint number are control endpoints.
190 *
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500191 * @param usbdev A USB device.
Alexander Williamse18d88b2022-01-21 16:30:39 -0800192 * @param endpoint An endpoint number.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500193 * @param new_state New SETUP packet reception state.
194 * @return The result of the operation.
195 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000196OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000197dif_result_t dif_usbdev_endpoint_setup_enable(const dif_usbdev_t *usbdev,
198 uint8_t endpoint,
199 dif_toggle_t new_state);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500200
201/**
Alexander Williamsfdddf262022-05-20 10:08:07 -0700202 * Enable or disable reception of OUT packets for an active endpoint.
203 *
204 * When disabling reception of OUT packets, what the endpoint will do depends
205 * on other factors. If the endpoint is currently configured as a control
206 * endpoint (receives SETUP packets) or it is configured as an isochronous
207 * endpoint, disabling reception of OUT packets will cause them to be ignored.
208 *
209 * If the endpoint is neither a control nor isochronous endpoint, then its
210 * behavior depends on whether it is configured to respond with STALL. If the
211 * STALL response is not active, then disabling reception will cause usbdev to
212 * NAK the packet. Otherwise, the STALL response takes priority, regardless of
213 * the setting here.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500214 *
215 * @param usbdev A USB device.
Alexander Williamse18d88b2022-01-21 16:30:39 -0800216 * @param endpoint An OUT endpoint number.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500217 * @param new_state New OUT packet reception state.
218 * @return The result of the operation.
219 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000220OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000221dif_result_t dif_usbdev_endpoint_out_enable(const dif_usbdev_t *usbdev,
222 uint8_t endpoint,
223 dif_toggle_t new_state);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500224
225/**
Alexander Williams7d681e52022-02-14 07:56:08 -0800226 * Enable or disable clearing the out_enable bit after completion of an OUT
227 * transaction to an endpoint.
228 *
229 * If set_nak_out is enabled, an OUT endpoint will disable reception of OUT
230 * packets after each successful OUT transaction to that endpoint, requiring a
231 * call to `dif_usbdev_endpoint_out_enable()` to enable reception again.
232 *
233 * @param usbdev A USB device.
234 * @param endpoint An OUT endpoint number.
235 * @param new_state New set_nak_on_out state.
236 * @return The result of the operation.
237 */
238OT_WARN_UNUSED_RESULT
239dif_result_t dif_usbdev_endpoint_set_nak_out_enable(const dif_usbdev_t *usbdev,
240 uint8_t endpoint,
241 dif_toggle_t new_state);
242
243/**
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500244 * Enable or disable STALL for an endpoint.
245 *
246 * @param usbdev A USB device.
Alexander Williamse18d88b2022-01-21 16:30:39 -0800247 * @param endpoint An endpoint ID.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500248 * @param new_state New STALL state.
249 * @return The result of the operation.
250 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000251OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000252dif_result_t dif_usbdev_endpoint_stall_enable(const dif_usbdev_t *usbdev,
Alexander Williamse18d88b2022-01-21 16:30:39 -0800253 dif_usbdev_endpoint_id_t endpoint,
Timothy Trippelae484372021-10-07 06:42:41 +0000254 dif_toggle_t new_state);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500255
256/**
257 * Get STALL state of an endpoint.
258 *
259 * @param usbdev A USB device.
Alexander Williamse18d88b2022-01-21 16:30:39 -0800260 * @param endpoint An endpoint ID.
Sam Elliottff85e052020-08-28 12:58:55 +0100261 * @param[out] state Current STALL state.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500262 * @return The result of the operation.
263 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000264OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000265dif_result_t dif_usbdev_endpoint_stall_get(const dif_usbdev_t *usbdev,
Alexander Williamse18d88b2022-01-21 16:30:39 -0800266 dif_usbdev_endpoint_id_t endpoint,
267 bool *state);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500268
269/**
270 * Enable or disable isochronous mode for an endpoint.
271 *
272 * Isochronous endpoints transfer data periodically. Since isochronous transfers
273 * do not have a handshaking stage, isochronous endpoints cannot report errors
274 * or STALL conditions.
275 *
276 * @param usbdev A USB device.
277 * @param endpoint An endpoint.
278 * @param new_state New isochronous state.
279 * @return The result of the operation.
280 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000281OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000282dif_result_t dif_usbdev_endpoint_iso_enable(const dif_usbdev_t *usbdev,
Alexander Williamse18d88b2022-01-21 16:30:39 -0800283 dif_usbdev_endpoint_id_t endpoint,
Timothy Trippelae484372021-10-07 06:42:41 +0000284 dif_toggle_t new_state);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500285
286/**
Alexander Williamse18d88b2022-01-21 16:30:39 -0800287 * Enable or disable an endpoint.
288 *
289 * An enabled endpoint responds to packets from the host. A disabled endpoint
290 * ignores them.
291 *
292 * @param usbdev A USB device.
293 * @param endpoint An endpoint.
294 * @param new_state New endpoint state.
295 * @return The result of the operation.
296 */
297OT_WARN_UNUSED_RESULT
298dif_result_t dif_usbdev_endpoint_enable(const dif_usbdev_t *usbdev,
299 dif_usbdev_endpoint_id_t endpoint,
300 dif_toggle_t new_state);
301
302/**
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500303 * Enable the USB interface of a USB device.
304 *
305 * Calling this function causes the USB device to assert the full-speed pull-up
Alexander Williamse18d88b2022-01-21 16:30:39 -0800306 * signal to indicate its presence to the host. Ensure the default endpoint is
307 * set up before enabling the interface.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500308 *
309 * @param usbdev A USB device.
310 * @param new_state New interface state.
311 * @return The result of the operation.
312 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000313OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000314dif_result_t dif_usbdev_interface_enable(const dif_usbdev_t *usbdev,
315 dif_toggle_t new_state);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500316
317/**
318 * Information about a received packet.
319 */
320typedef struct dif_usbdev_rx_packet_info {
321 /**
322 * Endpoint of the packet.
323 */
324 uint8_t endpoint;
325 /**
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400326 * Payload length in bytes.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500327 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400328 uint8_t length;
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500329 /**
330 * Indicates if the packet is a SETUP packet.
331 */
332 bool is_setup;
333} dif_usbdev_rx_packet_info_t;
334
335/**
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400336 * Get the packet at the front of RX FIFO.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500337 *
338 * The USB device has a small FIFO (RX FIFO) that stores received packets until
339 * the software has a chance to process them. It is the responsibility of the
340 * software to ensure that the RX FIFO is never full. If the host tries to send
341 * a packet when the RX FIFO is full, the USB device will respond with a NAK.
342 * While this will typically cause the host to retry transmission for regular
343 * data packets, there are transactions in the USB protocol during which the USB
344 * device is not allowed to send a NAK. Thus, the software must read received
345 * packets as soon as possible.
346 *
347 * Reading received packets involves two main steps:
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400348 * - Calling this function, i.e. `dif_usbdev_recv`, and
349 * - Calling `dif_usbdev_buffer_read` until the entire packet payload
350 * is read.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500351 *
352 * In order to read an incoming packet, clients should first call this function
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400353 * to get information about the packet and the buffer that holds the packet
354 * payload. Then, clients should call `dif_usbdev_buffer_read` with this buffer
355 * one or more times (depending on the sizes of their internal buffers) until
356 * the entire packet payload is read. Once the entire payload is read, the
357 * buffer is returned to the free buffer pool. If the clients want to ignore the
358 * payload of a packet, e.g. for an unsupported or a zero-length packet, they
359 * can call `dif_usbdev_buffer_return` to immediately return the buffer to the
360 * free buffer pool.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500361 *
362 * @param usbdev A USB device.
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400363 * @param[out] packet_info Packet information.
364 * @param[out] buffer Buffer that holds the packet payload.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500365 * @return The result of the operation.
366 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000367OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000368dif_result_t dif_usbdev_recv(const dif_usbdev_t *usbdev,
369 dif_usbdev_rx_packet_info_t *packet_info,
370 dif_usbdev_buffer_t *buffer);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500371
372/**
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400373 * Read incoming packet payload.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500374 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400375 * Clients should call this function with a buffer provided by `dif_usbdev_recv`
376 * to read the payload of an incoming packet. This function copies the smaller
377 * of `dst_len` and remaining number of bytes in the buffer to `dst`. The buffer
378 * that holds the packet payload is returned to the free buffer pool when the
379 * entire packet payload is read.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500380 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400381 * See also: `dif_usbdev_recv`.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500382 *
383 * @param usbdev A USB device.
Timothy Trippel4cbe3cb2021-10-07 05:22:01 +0000384 * @param buffer_pool A USB device buffer pool.
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400385 * @param buffer A buffer provided by `dif_usbdev_recv`.
386 * @param[out] dst Destination buffer.
387 * @param dst_len Length of the destination buffer.
388 * @param[out] bytes_written Number of bytes written to destination buffer.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500389 * @return The result of the operation.
390 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000391OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000392dif_result_t dif_usbdev_buffer_read(const dif_usbdev_t *usbdev,
393 dif_usbdev_buffer_pool_t *buffer_pool,
394 dif_usbdev_buffer_t *buffer, uint8_t *dst,
395 size_t dst_len, size_t *bytes_written);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500396
397/**
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400398 * Return a buffer to the free buffer pool.
399 *
400 * This function immediately returns the given buffer to the free buffer pool.
401 * Since `dif_usbdev_buffer_read` and `dif_usbdev_get_tx_status` return the
402 * buffers that they work on to the free buffer pool automatically, this
403 * function should only be called to discard the payload of a received
404 * packet or a packet that was being prepared for transmission before it is
405 * queued for transmission from an endpoint.
406 *
407 * See also: `dif_usbdev_recv`, `dif_usbdev_buffer_request`.
408 *
409 * @param usbdev A USB device.
Timothy Trippel4cbe3cb2021-10-07 05:22:01 +0000410 * @param buffer_pool A USB device buffer pool.
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400411 * @param buffer A buffer provided by `dif_usbdev_recv` or
412 * `dif_usbdev_buffer_request`.
413 * @return The result of the operation.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500414 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000415OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000416dif_result_t dif_usbdev_buffer_return(const dif_usbdev_t *usbdev,
417 dif_usbdev_buffer_pool_t *buffer_pool,
418 dif_usbdev_buffer_t *buffer);
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400419
420/**
421 * Request a buffer for outgoing packet payload.
422 *
423 * Clients should call this function to request a buffer to write the payload of
424 * an outgoing packet. Sending a packet from a particular endpoint to the host
425 * involves four main steps:
426 * - Calling this function, i.e. `dif_usbdev_buffer_request`,
427 * - Calling `dif_usbdev_buffer_write`,
428 * - Calling `dif_usbdev_send`, and
429 * - Calling `dif_usbdev_get_tx_status`.
430 *
431 * In order to send a packet, clients should first call this function to obtain
432 * a buffer for the packet payload. Clients should then call
433 * `dif_usbdev_buffer_write` (one or more times depending on the sizes of their
434 * internal buffers) to write the packet payload to this buffer. After writing
435 * the packet payload, clients should call `dif_usbdev_send` to mark the packet
436 * as ready for transmission from a particular endpoint. Then, clients should
437 * call `dif_usbdev_get_tx_status` to check the status of the transmission.
438 * `dif_usbdev_get_tx_status` returns the buffer that holds the packet payload
439 * to the free buffer pool once the packet is either successfully transmitted or
440 * canceled due to an incoming SETUP packet or a link reset. If the packet
441 * should no longer be sent, clients can call `dif_usbdev_buffer_return` to
442 * return the buffer to the free buffer pool as long as `dif_usbdev_send` is not
443 * called yet.
444 *
445 * See also: `dif_usbdev_buffer_write`, `dif_usbdev_send`,
446 * `dif_usbdev_get_tx_status`, `dif_usbdev_buffer_return`.
447 *
448 * @param usbdev A USB device.
Timothy Trippel4cbe3cb2021-10-07 05:22:01 +0000449 * @param buffer_pool A USB device buffer pool.
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400450 * @param[out] buffer A buffer for writing outgoing packet payload.
451 * @return The result of the operation.
452 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000453OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000454dif_result_t dif_usbdev_buffer_request(const dif_usbdev_t *usbdev,
455 dif_usbdev_buffer_pool_t *buffer_pool,
456 dif_usbdev_buffer_t *buffer);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500457
458/**
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400459 * Write outgoing packet payload.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500460 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400461 * Clients should call this function with a buffer provided by
462 * `dif_usbdev_buffer_request` to write the payload of an outgoing packet. This
463 * function copies the smaller of `src_len` and remaining number of bytes in the
464 * buffer to the buffer. Clients should then call `dif_usbdev_send` to queue the
465 * packet for transmission from a particular endpoint.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500466 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400467 * See also: `dif_usbdev_buffer_request`, `dif_usbdev_send`,
468 * `dif_usbdev_get_tx_status`, `dif_usbdev_buffer_return`.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500469 *
470 * @param usbdev A USB device.
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400471 * @param buffer A buffer provided by `dif_usbdev_buffer_request`.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500472 * @param src Source buffer.
473 * @param src_len Length of the source buffer.
Sam Elliottff85e052020-08-28 12:58:55 +0100474 * @param[out] bytes_written Number of bytes written to the USB device buffer.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500475 * @return The result of the operation.
476 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000477OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000478dif_result_t dif_usbdev_buffer_write(const dif_usbdev_t *usbdev,
Alexander Williams00c6e2b2022-06-16 17:18:17 -0700479 dif_usbdev_buffer_t *buffer,
480 const uint8_t *src, size_t src_len,
481 size_t *bytes_written);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500482
483/**
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400484 * Mark a packet ready for transmission from an endpoint.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500485 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400486 * The USB device has 12 endpoints, each of which can be used to send packets to
487 * the host. Since a packet is not actually transmitted to the host until the
488 * host sends an IN token, clients must write the packet payload to a device
489 * buffer and mark it as ready for transmission from a particular endpoint. A
490 * packet queued for transmission from a particular endpoint is transmitted once
491 * the host sends an IN token for that endpoint.
492 *
493 * After a packet is queued for transmission, clients should check its status by
494 * calling `dif_usbdev_get_tx_status`. While the USB device handles transmission
495 * errors automatically by retrying transmission, transmission of a packet may
496 * be canceled if the endpoint receives a SETUP packet or the link is reset
497 * before the queued packet is transmitted. In these cases, clients should
498 * handle the SETUP packet or the link reset first and then optionally send the
499 * same packet again. Clients must also make sure that the given endpoint does
500 * not already have a packet pending for transmission before calling this
501 * function.
502 *
503 * See also: `dif_usbdev_buffer_request`, `dif_usbdev_buffer_write`,
504 * `dif_usbdev_get_tx_status`, `dif_usbdev_buffer_return`.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500505 *
506 * @param usbdev A USB device.
Alexander Williamse18d88b2022-01-21 16:30:39 -0800507 * @param endpoint An OUT endpoint number.
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400508 * @param buffer A buffer provided by `dif_usbdev_buffer_request`.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500509 * @return The result of the operation.
510 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000511OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000512dif_result_t dif_usbdev_send(const dif_usbdev_t *usbdev, uint8_t endpoint,
513 dif_usbdev_buffer_t *buffer);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500514
515/**
Alexander Williamsa68ef4b2022-06-15 13:35:19 -0700516 * Get which IN endpoints have sent packets.
517 *
518 * This function provides which endpoints have buffers that have successfully
519 * completed transmission to the host. It may be used to guide calls to
520 * `dif_usbdev_clear_tx_status` to return the used buffer to the pool and clear
521 * the state for the next transaction.
522 *
523 * @param usbdev A USB device.
524 * @param[out] sent A bitmap of which endpoints have sent packets.
525 * @return The result of the operation.
526 */
527OT_WARN_UNUSED_RESULT
528dif_result_t dif_usbdev_get_tx_sent(const dif_usbdev_t *usbdev, uint16_t *sent);
529
530/**
531 * Clear the TX state of the provided endpoint and restore its associated buffer
532 * to the pool.
533 *
534 * Note that this function should only be called when an endpoint has been
535 * provided a buffer. Without it, the buffer pool will become corrupted, as this
536 * function does not check the status.
537 *
538 * In addition, if the endpoint has not yet completed or canceled the
539 * transaction, the user must not call this function while the device is in an
540 * active state. Otherwise, the user risks corrupting an ongoing transaction.
541 *
542 * @param usbdev A USB device.
543 * @param buffer_pool A USB device buffer pool.
544 * @param endpoint An IN endpoint number.
545 * @return The result of the operation.
546 */
547OT_WARN_UNUSED_RESULT
548dif_result_t dif_usbdev_clear_tx_status(const dif_usbdev_t *usbdev,
549 dif_usbdev_buffer_pool_t *buffer_pool,
550 uint8_t endpoint);
551
552/**
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500553 * Status of an outgoing packet.
554 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400555typedef enum dif_usbdev_tx_status {
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500556 /**
Alexander Williamse18d88b2022-01-21 16:30:39 -0800557 * There is no packet for the given OUT endpoint.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500558 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400559 kDifUsbdevTxStatusNoPacket,
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500560 /**
561 * Packet is pending transmission.
562 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400563 kDifUsbdevTxStatusPending,
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500564 /**
565 * Packet was sent successfully.
566 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400567 kDifUsbdevTxStatusSent,
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500568 /**
569 * Transmission was canceled due to an incoming SETUP packet.
570 */
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400571 kDifUsbdevTxStatusCancelled,
572} dif_usbdev_tx_status_t;
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500573
574/**
575 * Get the status of a packet that has been queued to be sent from an endpoint.
576 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400577 * While the USB device handles transmission errors automatically by retrying
578 * transmission, transmission of a packet may be canceled if the endpoint
579 * receives a SETUP packet or the link is reset before the queued packet is
580 * transmitted. In these cases, clients should handle the SETUP packet or the
581 * link reset first and then optionally send the same packet again.
582 *
Alexander Williamsa68ef4b2022-06-15 13:35:19 -0700583 * This function does not modify any device state. `dif_usbdev_clear_tx_status`
584 * can be used to clear the status and return the buffer to the pool.
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400585 *
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500586 * @param usbdev A USB device.
Alexander Williamsa68ef4b2022-06-15 13:35:19 -0700587 * @param endpoint An IN endpoint number.
Sam Elliottff85e052020-08-28 12:58:55 +0100588 * @param[out] status Status of the packet.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500589 * @return The result of the operation.
590 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000591OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000592dif_result_t dif_usbdev_get_tx_status(const dif_usbdev_t *usbdev,
Timothy Trippelae484372021-10-07 06:42:41 +0000593 uint8_t endpoint,
594 dif_usbdev_tx_status_t *status);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500595
596/**
597 * Set the address of a USB device.
598 *
599 * @param usbdev A USB device.
600 * @param addr New address. Only the last 7 bits are significant.
601 * @return The result of the operation.
602 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000603OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000604dif_result_t dif_usbdev_address_set(const dif_usbdev_t *usbdev, uint8_t addr);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500605
606/**
607 * Get the address of a USB device.
608 *
609 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100610 * @param[out] addr Current address.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500611 * @return The result of the operation.
612 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000613OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000614dif_result_t dif_usbdev_address_get(const dif_usbdev_t *usbdev, uint8_t *addr);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500615
616/**
Alexander Williams74f55d52022-05-20 10:08:28 -0700617 * Clear the data toggle bits for the selected endpoint.
618 *
619 * @param usbdev A USB device.
620 * @param endpoint An endpoint number.
621 * @return The result of the operation.
622 */
623OT_WARN_UNUSED_RESULT
624dif_result_t dif_usbdev_clear_data_toggle(const dif_usbdev_t *usbdev,
625 uint8_t endpoint);
626
627/**
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500628 * Get USB frame index.
629 *
630 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100631 * @param[out] frame_index USB frame index.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500632 * @return The result of the operation.
633 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000634OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000635dif_result_t dif_usbdev_status_get_frame(const dif_usbdev_t *usbdev,
636 uint16_t *frame_index);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500637
638/**
639 * Check if the host is lost.
640 *
641 * The host is lost if the link is still active but a start of frame packet has
642 * not been received in the last 4.096ms.
643 *
644 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100645 * @param[out] host_lost Status of the host. `true` if the host is lost, `false`
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500646 * otherwise.
647 * @return The result of the operation.
648 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000649OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000650dif_result_t dif_usbdev_status_get_host_lost(const dif_usbdev_t *usbdev,
651 bool *host_lost);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500652
653/**
654 * USB link state.
655 */
656typedef enum dif_usbdev_link_state {
657 kDifUsbdevLinkStateDisconnected,
658 kDifUsbdevLinkStatePowered,
Alexander Williams6903f742022-02-03 16:56:12 -0800659 kDifUsbdevLinkStatePoweredSuspended,
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500660 kDifUsbdevLinkStateActive,
Alexander Williams6903f742022-02-03 16:56:12 -0800661 kDifUsbdevLinkStateSuspended,
662 kDifUsbdevLinkStateActiveNoSof,
663 kDifUsbdevLinkStateResuming,
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500664} dif_usbdev_link_state_t;
665
666/**
667 * Get USB link state.
668 *
669 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100670 * @param[out] link_state USB link state.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500671 * @return The result of the operation.
672 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000673OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000674dif_result_t dif_usbdev_status_get_link_state(
Timothy Trippel054b2462021-10-07 05:41:09 +0000675 const dif_usbdev_t *usbdev, dif_usbdev_link_state_t *link_state);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500676
677/**
678 * Get the state of the sense pin.
679 *
680 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100681 * @param[out] sense State of the sense pin. `true` if the host is providing
682 * VBUS, `false` otherwise.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500683 * @return The result of the operation.
684 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000685OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000686dif_result_t dif_usbdev_status_get_sense(const dif_usbdev_t *usbdev,
687 bool *sense);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500688
689/**
690 * Get the depth of the AV FIFO.
691 *
692 * See also: `dif_usbdev_fill_available_fifo`.
693 *
694 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100695 * @param[out] depth Depth of the AV FIFO.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500696 * @return The result of the operation.
697 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000698OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000699dif_result_t dif_usbdev_status_get_available_fifo_depth(
Timothy Trippel054b2462021-10-07 05:41:09 +0000700 const dif_usbdev_t *usbdev, uint8_t *depth);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500701/**
702 * Check if AV FIFO is full.
703 *
704 * See also: `dif_usbdev_fill_available_fifo`.
705 *
706 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100707 * @param[out] is_full State of the AV FIFO. `true` if full, false otherwise.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500708 * @return The result of the operation.
709 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000710OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000711dif_result_t dif_usbdev_status_get_available_fifo_full(
Timothy Trippel054b2462021-10-07 05:41:09 +0000712 const dif_usbdev_t *usbdev, bool *is_full);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500713/**
714 * Get the depth of the RX FIFO.
715 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400716 * See also: `dif_usbdev_recv`.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500717 *
718 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100719 * @param[out] depth Depth of the RX FIFO.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500720 * @return The result of the operation.
721 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000722OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000723dif_result_t dif_usbdev_status_get_rx_fifo_depth(const dif_usbdev_t *usbdev,
724 uint8_t *depth);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500725
726/**
727 * Check if the RX FIFO is empty.
728 *
Alphan Ulusoy364c4112020-07-27 22:54:14 -0400729 * See also: `dif_usbdev_recv`.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500730 *
731 * @param usbdev A USB device.
Sam Elliottff85e052020-08-28 12:58:55 +0100732 * @param[out] is_empty State of the RX FIFO. `true` if empty, `false`
733 * otherwise.
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500734 * @return The result of the operation.
735 */
Timothy Trippele3f8a822021-09-17 06:09:28 +0000736OT_WARN_UNUSED_RESULT
Timothy Trippelae484372021-10-07 06:42:41 +0000737dif_result_t dif_usbdev_status_get_rx_fifo_empty(const dif_usbdev_t *usbdev,
738 bool *is_empty);
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500739
Alexander Williams74f55d52022-05-20 10:08:28 -0700740/**
741 * Control whether oscillator test mode is enabled.
742 *
743 * In oscillator test mode, usbdev transmits a continuous 0101 pattern for
744 * evaluating the reference clock's quality.
745 *
746 * @param usbdev A USB device.
747 * @param enable Whether the test mode should be enabled.
748 * @return The result of the operation.
749 */
750OT_WARN_UNUSED_RESULT
751dif_result_t dif_usbdev_set_osc_test_mode(const dif_usbdev_t *usbdev,
752 dif_toggle_t enable);
753
754/**
755 * Control whether the AON wake module is active.
756 *
757 * @param usbdev A USB device.
758 * @param enable Whether the AON wake module is enabled.
759 * @return The result of the operation.
760 */
761OT_WARN_UNUSED_RESULT
762dif_result_t dif_usbdev_set_wake_enable(const dif_usbdev_t *usbdev,
763 dif_toggle_t enable);
764
765typedef struct dif_usbdev_wake_status {
766 /** Whether the AON wake module is active. */
767 bool active;
768 /** Whether the USB disconnected while the AON wake module was active. */
769 bool disconnected;
770 /** Whether the USB was reset while the AON wake module was active. */
771 bool bus_reset;
772} dif_usbdev_wake_status_t;
773
774/**
775 * Get the status of the AON wake module.
776 *
777 * Note that the conditions triggering exit from suspended state must be read
778 * before disabling the AON wake module. Once the AON wake module is
779 * deactivated, that status information is lost.
780 *
781 * Also note that the ordinary resume condition does not report to the usbdev
782 * module. Instead, it should be obtained from the module monitoring wakeup
783 * sources.
784 *
785 * @param usbdev A USB device.
786 * @param[out] status The status of the module.
787 * @return The result of the operation.
788 */
789OT_WARN_UNUSED_RESULT
790dif_result_t dif_usbdev_get_wake_status(const dif_usbdev_t *usbdev,
791 dif_usbdev_wake_status_t *status);
792
793/**
794 * Force the link state machine to resume to an active state.
795 *
796 * This is used when waking from a low-power suspended state to resume to an
797 * active state. It moves the usbdev out of the Powered state (from the USB
798 * device state machine in the spec) without receiving a bus reset. Without help
799 * from software, the usbdev module cannot determine on its own when a bus reset
800 * is required.
801 *
802 * @param usbdev A USB device.
803 * @return The result of the operation.
804 */
805OT_WARN_UNUSED_RESULT
806dif_result_t dif_usbdev_resume_link_to_active(const dif_usbdev_t *usbdev);
807
808typedef struct dif_usbdev_phy_pins_sense {
809 /** USB D+ input. */
810 bool rx_dp : 1;
811 /** USB D- input. */
812 bool rx_dn : 1;
813 /** USB data input from an external differential receiver, if available. */
814 bool rx_d : 1;
815 /** USB transmit D+ output. */
816 bool tx_dp : 1;
817 /** USB transmit D- output. */
818 bool tx_dn : 1;
819 /** USB transmit data value output. */
820 bool tx_d : 1;
821 /** USB single-ended zero output. */
822 bool tx_se0 : 1;
823 /** USB output enable for D+ / D-. */
824 bool output_enable : 1;
825 /** USB VBUS sense pin. */
826 bool vbus_sense : 1;
827} dif_usbdev_phy_pins_sense_t;
828
829/**
830 * Get the current state of the USB PHY pins.
831 *
832 * @param usbdev A USB device.
833 * @param[out] status The current state of the pins.
834 * @return The result of the operation.
835 */
836OT_WARN_UNUSED_RESULT
837dif_result_t dif_usbdev_get_phy_pins_status(
838 const dif_usbdev_t *usbdev, dif_usbdev_phy_pins_sense_t *status);
839
840typedef struct dif_usbdev_phy_pins_drive {
841 /** USB D+ output, for use with dn. */
842 bool dp : 1;
843 /** USB D- output. for use with dp. */
844 bool dn : 1;
845 /** USB data output, encoding K and J when se0 is 0. */
846 bool data : 1;
847 /** USB single-ended zero output. */
848 bool se0 : 1;
849 /** USB output enable for D+ / D-. */
850 bool output_enable : 1;
851 /** Enable control pin for the differential receiver. */
852 bool diff_receiver_enable : 1;
853 /** Controls whether to pull up the D+ pin. */
854 bool dp_pullup_en : 1;
855 /** Controls whether to pull up the D- pin. */
856 bool dn_pullup_en : 1;
857} dif_usbdev_phy_pins_drive_t;
858
859/**
860 * Control whether to override the USB PHY and drive pins as GPIOs.
861 *
862 * @param usbdev A USB device.
863 * @param override_enable Enable / disable the GPIO-like overrides.
864 * @param overrides The values to set the pins to.
865 * @return The result of the operation.
866 */
867OT_WARN_UNUSED_RESULT
868dif_result_t dif_usbdev_set_phy_pins_state(
869 const dif_usbdev_t *usbdev, dif_toggle_t override_enable,
870 dif_usbdev_phy_pins_drive_t overrides);
871
Michael Munday0c0ece52021-03-22 14:35:57 +0000872#ifdef __cplusplus
873} // extern "C"
874#endif // __cplusplus
875
Alphan Ulusoy425450c2020-02-19 07:50:54 -0500876#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_USBDEV_H_