source: mainline/uspace/lib/usbvirt/include/usbvirt/device.h@ bd8c753d

lfn serial ticket/834-toolchain-update topic/msim-upgrade topic/simplify-dev-export
Last change on this file since bd8c753d was bd8c753d, checked in by Vojtech Horky <vojtechhorky@…>, 15 years ago

Doxygen group for USB virtualization

Virtual host controller and libusbvirt has separate Doxygen groups because
the usb group was polluted way too much.
  • Property mode set to 100644
File size: 8.9 KB
Line 
1/*
2 * Copyright (c) 2010 Vojtech Horky
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/** @addtogroup libusbvirt
30 * @{
31 */
32/** @file
33 * @brief Virtual USB device.
34 */
35#ifndef LIBUSBVIRT_DEVICE_H_
36#define LIBUSBVIRT_DEVICE_H_
37
38#include <usb/usb.h>
39#include <usb/descriptor.h>
40#include <usb/devreq.h>
41
42/** Request type of a control transfer. */
43typedef enum {
44 /** Standard USB request. */
45 USBVIRT_REQUEST_TYPE_STANDARD = 0,
46 /** Standard class USB request. */
47 USBVIRT_REQUEST_TYPE_CLASS = 1
48} usbvirt_request_type_t;
49
50/** Recipient of control request. */
51typedef enum {
52 /** Device is the recipient of the control request. */
53 USBVIRT_REQUEST_RECIPIENT_DEVICE = 0,
54 /** Interface is the recipient of the control request. */
55 USBVIRT_REQUEST_RECIPIENT_INTERFACE = 1,
56 /** Endpoint is the recipient of the control request. */
57 USBVIRT_REQUEST_RECIPIENT_ENDPOINT = 2,
58 /** Other part of the device is the recipient of the control request. */
59 USBVIRT_REQUEST_RECIPIENT_OTHER = 3
60} usbvirt_request_recipient_t;
61
62/** Possible states of virtual USB device.
63 * Notice that these are not 1:1 mappings to those in USB specification.
64 */
65typedef enum {
66 /** Default state, device listens at default address. */
67 USBVIRT_STATE_DEFAULT,
68 /** Device has non-default address assigned. */
69 USBVIRT_STATE_ADDRESS,
70 /** Device is configured. */
71 USBVIRT_STATE_CONFIGURED
72} usbvirt_device_state_t;
73
74typedef struct usbvirt_device usbvirt_device_t;
75struct usbvirt_control_transfer;
76
77typedef int (*usbvirt_on_device_request_t)(usbvirt_device_t *dev,
78 usb_device_request_setup_packet_t *request,
79 uint8_t *data);
80
81/** Callback for control request over pipe zero.
82 *
83 * @param dev Virtual device answering the call.
84 * @param request Request setup packet.
85 * @param data Data when DATA stage is present.
86 * @return Error code.
87 */
88typedef int (*usbvirt_control_request_callback_t)(usbvirt_device_t *dev,
89 usb_device_request_setup_packet_t *request,
90 uint8_t *data);
91
92/** Handler for control transfer on endpoint zero. */
93typedef struct {
94 /** Request type bitmap.
95 * Use USBVIRT_MAKE_CONTROL_REQUEST_TYPE for creating the bitmap.
96 */
97 uint8_t request_type;
98 /** Request code. */
99 uint8_t request;
100 /** Request name for debugging. */
101 const char *name;
102 /** Callback for the request.
103 * NULL value here announces end of a list.
104 */
105 usbvirt_control_request_callback_t callback;
106} usbvirt_control_transfer_handler_t;
107
108/** Create control request type bitmap.
109 *
110 * @param direction Transfer direction (use usb_direction_t).
111 * @param type Request type (use usbvirt_request_type_t).
112 * @param recipient Recipient of the request (use usbvirt_request_recipient_t).
113 * @return Request type bitmap.
114 */
115#define USBVIRT_MAKE_CONTROL_REQUEST_TYPE(direction, type, recipient) \
116 ((((direction) == USB_DIRECTION_IN) ? 1 : 0) << 7) \
117 | (((type) & 3) << 5) \
118 | (((recipient) & 31))
119
120/** Create last item in an array of control request handlers. */
121#define USBVIRT_CONTROL_TRANSFER_HANDLER_LAST { 0, 0, NULL, NULL }
122
123/** Device operations. */
124typedef struct {
125 /** Callbacks for transfers over control pipe zero. */
126 usbvirt_control_transfer_handler_t *control_transfer_handlers;
127
128 int (*on_control_transfer)(usbvirt_device_t *dev,
129 usb_endpoint_t endpoint, struct usbvirt_control_transfer *transfer);
130
131 /** Callback for all other incoming data. */
132 int (*on_data)(usbvirt_device_t *dev,
133 usb_endpoint_t endpoint, void *buffer, size_t size);
134
135 /** Callback for host request for data. */
136 int (*on_data_request)(usbvirt_device_t *dev,
137 usb_endpoint_t endpoint, void *buffer, size_t size, size_t *actual_size);
138
139 /** Decides direction of control transfer. */
140 usb_direction_t (*decide_control_transfer_direction)(
141 usb_endpoint_t endpoint, void *buffer, size_t size);
142
143 /** Callback when device changes its state.
144 *
145 * It is correct that this function is called when both states
146 * are equal (e.g. this function is called during SET_CONFIGURATION
147 * request done on already configured device).
148 *
149 * @warning The value of <code>dev->state</code> before calling
150 * this function is not specified (i.e. can be @p old_state or
151 * @p new_state).
152 */
153 void (*on_state_change)(usbvirt_device_t *dev,
154 usbvirt_device_state_t old_state, usbvirt_device_state_t new_state);
155} usbvirt_device_ops_t;
156
157/** Extra configuration data for GET_CONFIGURATION request. */
158typedef struct {
159 /** Actual data. */
160 uint8_t *data;
161 /** Data length. */
162 size_t length;
163} usbvirt_device_configuration_extras_t;
164
165/** Single device configuration. */
166typedef struct {
167 /** Standard configuration descriptor. */
168 usb_standard_configuration_descriptor_t *descriptor;
169 /** Array of extra data. */
170 usbvirt_device_configuration_extras_t *extra;
171 /** Length of @c extra array. */
172 size_t extra_count;
173} usbvirt_device_configuration_t;
174
175/** Standard USB descriptors. */
176typedef struct {
177 /** Standard device descriptor.
178 * There is always only one such descriptor for the device.
179 */
180 usb_standard_device_descriptor_t *device;
181
182 /** Configurations. */
183 usbvirt_device_configuration_t *configuration;
184 /** Number of configurations. */
185 size_t configuration_count;
186 /** Index of currently selected configuration. */
187 uint8_t current_configuration;
188} usbvirt_descriptors_t;
189
190/** Information about on-going control transfer.
191 */
192typedef struct usbvirt_control_transfer {
193 /** Transfer direction (read/write control transfer). */
194 usb_direction_t direction;
195 /** Request data. */
196 void *request;
197 /** Size of request data. */
198 size_t request_size;
199 /** Payload. */
200 void *data;
201 /** Size of payload. */
202 size_t data_size;
203} usbvirt_control_transfer_t;
204
205typedef enum {
206 USBVIRT_DEBUGTAG_BASE = 1,
207 USBVIRT_DEBUGTAG_TRANSACTION = 2,
208 USBVIRT_DEBUGTAG_CONTROL_PIPE_ZERO = 4,
209 USBVIRT_DEBUGTAG_ALL = 255
210} usbvirt_debug_tags_t;
211
212/** Virtual USB device. */
213struct usbvirt_device {
214 /** Callback device operations. */
215 usbvirt_device_ops_t *ops;
216
217 /** Custom device data. */
218 void *device_data;
219
220 /** Reply onto control transfer.
221 */
222 int (*control_transfer_reply)(usbvirt_device_t *dev,
223 usb_endpoint_t endpoint, void *buffer, size_t size);
224
225 /** Device name.
226 * Used in debug prints and sent to virtual host controller.
227 */
228 const char *name;
229
230 /** Standard descriptors. */
231 usbvirt_descriptors_t *descriptors;
232
233 /** Current device state. */
234 usbvirt_device_state_t state;
235
236 /** Device address. */
237 usb_address_t address;
238 /** New device address.
239 * This field is used during SET_ADDRESS request.
240 * On all other occasions, it holds invalid address (e.g. -1).
241 */
242 usb_address_t new_address;
243
244 /** Process OUT transaction. */
245 int (*transaction_out)(usbvirt_device_t *dev,
246 usb_endpoint_t endpoint, void *buffer, size_t size);
247 /** Process SETUP transaction. */
248 int (*transaction_setup)(usbvirt_device_t *dev,
249 usb_endpoint_t endpoint, void *buffer, size_t size);
250 /** Process IN transaction. */
251 int (*transaction_in)(usbvirt_device_t *dev,
252 usb_endpoint_t endpoint, void *buffer, size_t size, size_t *data_size);
253
254 /** State information on control-transfer endpoints. */
255 usbvirt_control_transfer_t current_control_transfers[USB11_ENDPOINT_MAX];
256
257 /* User debugging. */
258
259 /** Debug print. */
260 void (*debug)(usbvirt_device_t *dev, int level, uint8_t tag,
261 const char *format, ...);
262
263 /** Current debug level. */
264 int debug_level;
265
266 /** Bitmap of currently enabled tags. */
267 uint8_t debug_enabled_tags;
268
269 /* Library debugging. */
270
271 /** Debug print. */
272 void (*lib_debug)(usbvirt_device_t *dev, int level, uint8_t tag,
273 const char *format, ...);
274
275 /** Current debug level. */
276 int lib_debug_level;
277
278 /** Bitmap of currently enabled tags. */
279 uint8_t lib_debug_enabled_tags;
280};
281
282#endif
283/**
284 * @}
285 */
Note: See TracBrowser for help on using the repository browser.