VirtualBox

source: vbox/trunk/src/VBox/ValidationKit/utils/usb/UsbTestServiceGadget.h@ 103914

Last change on this file since 103914 was 98103, checked in by vboxsync, 2 years ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 18.3 KB
Line 
1/* $Id: UsbTestServiceGadget.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * UsbTestServ - Remote USB test configuration and execution server, Gadget API.
4 */
5
6/*
7 * Copyright (C) 2016-2023 Oracle and/or its affiliates.
8 *
9 * This file is part of VirtualBox base platform packages, as
10 * available from https://www.virtualbox.org.
11 *
12 * This program is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU General Public License
14 * as published by the Free Software Foundation, in version 3 of the
15 * License.
16 *
17 * This program is distributed in the hope that it will be useful, but
18 * WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * General Public License for more details.
21 *
22 * You should have received a copy of the GNU General Public License
23 * along with this program; if not, see <https://www.gnu.org/licenses>.
24 *
25 * The contents of this file may alternatively be used under the terms
26 * of the Common Development and Distribution License Version 1.0
27 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
28 * in the VirtualBox distribution, in which case the provisions of the
29 * CDDL are applicable instead of those of the GPL.
30 *
31 * You may elect to license modified versions of this file under the
32 * terms and conditions of either the GPL or the CDDL or both.
33 *
34 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
35 */
36
37#ifndef VBOX_INCLUDED_SRC_usb_UsbTestServiceGadget_h
38#define VBOX_INCLUDED_SRC_usb_UsbTestServiceGadget_h
39#ifndef RT_WITHOUT_PRAGMA_ONCE
40# pragma once
41#endif
42
43#include <iprt/cdefs.h>
44#include <iprt/types.h>
45
46RT_C_DECLS_BEGIN
47
48/** Opaque gadget host handle. */
49typedef struct UTSGADGETHOSTINT *UTSGADGETHOST;
50/** Pointer to a gadget host handle. */
51typedef UTSGADGETHOST *PUTSGADGETHOST;
52
53/** NIL gadget host handle. */
54#define NIL_UTSGADGETHOST ((UTSGADGETHOST)0)
55
56/** Opaque USB gadget handle. */
57typedef struct UTSGADGETINT *UTSGADGET;
58/** Pointer to a USB gadget handle. */
59typedef UTSGADGET *PUTSGADET;
60
61/** NIL gadget handle. */
62#define NIL_UTSGADGET ((UTSGADGET)0)
63
64/**
65 * Gadget/Gadget host configuration item type.
66 */
67typedef enum UTSGADGETCFGTYPE
68{
69 /** Don't use! */
70 UTSGADGETCFGTYPE_INVALID = 0,
71 /** Boolean type. */
72 UTSGADGETCFGTYPE_BOOLEAN,
73 /** UTF-8 string. */
74 UTSGADGETCFGTYPE_STRING,
75 /** Unsigned 8bit integer. */
76 UTSGADGETCFGTYPE_UINT8,
77 /** Unsigned 16bit integer. */
78 UTSGADGETCFGTYPE_UINT16,
79 /** Unsigned 32bit integer. */
80 UTSGADGETCFGTYPE_UINT32,
81 /** Unsigned 64bit integer. */
82 UTSGADGETCFGTYPE_UINT64,
83 /** Signed 8bit integer. */
84 UTSGADGETCFGTYPE_INT8,
85 /** Signed 16bit integer. */
86 UTSGADGETCFGTYPE_INT16,
87 /** Signed 32bit integer. */
88 UTSGADGETCFGTYPE_INT32,
89 /** Signed 64bit integer. */
90 UTSGADGETCFGTYPE_INT64,
91 /** 32bit hack. */
92 UTSGADGETCFGTYPE_32BIT_HACK = 0x7fffffff
93} UTSGADGETCFGTYPE;
94
95/**
96 * Gadget configuration value.
97 */
98typedef struct UTSGADGETCFGVAL
99{
100 /** Value type */
101 UTSGADGETCFGTYPE enmType;
102 /** Value based on the type. */
103 union
104 {
105 bool f;
106 const char *psz;
107 uint8_t u8;
108 uint16_t u16;
109 uint32_t u32;
110 uint64_t u64;
111 int8_t i8;
112 int16_t i16;
113 int32_t i32;
114 int64_t i64;
115 } u;
116} UTSGADGETCFGVAL;
117/** Pointer to a gadget configuration value. */
118typedef UTSGADGETCFGVAL *PUTSGADGETCFGVAL;
119/** Pointer to a const gadget configuration value. */
120typedef const UTSGADGETCFGVAL *PCUTSGADGETCFGVAL;
121
122/**
123 * Gadget configuration item.
124 */
125typedef struct UTSGADGETCFGITEM
126{
127 /** Item key. */
128 const char *pszKey;
129 /** Item value. */
130 UTSGADGETCFGVAL Val;
131} UTSGADGETCFGITEM;
132/** Pointer to a gadget configuration item. */
133typedef UTSGADGETCFGITEM *PUTSGADGETCFGITEM;
134/** Pointer to a const gadget configuration item. */
135typedef const UTSGADGETCFGITEM *PCUTSGADGETCFGITEM;
136
137/**
138 * Type for the gadget host.
139 */
140typedef enum UTSGADGETHOSTTYPE
141{
142 /** Invalid type, don't use. */
143 UTSGADGETHOSTTYPE_INVALID = 0,
144 /** USB/IP host, gadgets are exported using a USB/IP server. */
145 UTSGADGETHOSTTYPE_USBIP,
146 /** Physical connection using a device or OTG port. */
147 UTSGADGETHOSTTYPE_PHYSICAL,
148 /** 32bit hack. */
149 UTSGADGETHOSTTYPE_32BIT_HACK = 0x7fffffff
150} UTSGADGETHOSTTYPE;
151
152/**
153 * USB gadget class.
154 */
155typedef enum UTSGADGETCLASS
156{
157 /** Invalid class, don't use. */
158 UTSGADGETCLASS_INVALID = 0,
159 /** Special test device class. */
160 UTSGADGETCLASS_TEST,
161 /** MSD device. */
162 UTSGADGETCLASS_MSD,
163 /** 32bit hack. */
164 UTSGADGETCLASS_32BIT_HACK = 0x7fffffff
165} UTSGADGETCLASS;
166
167/**
168 * Queries the value of a given boolean key from the given configuration array.
169 *
170 * @returns IPRT status code.
171 * @param paCfg The configuration items.
172 * @param pszKey The key query the value for.
173 * @param pf Where to store the value on success.
174 */
175DECLHIDDEN(int) utsGadgetCfgQueryBool(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
176 bool *pf);
177
178/**
179 * Queries the value of a given boolean key from the given configuration array,
180 * setting a default if not found.
181 *
182 * @returns IPRT status code.
183 * @param paCfg The configuration items.
184 * @param pszKey The key query the value for.
185 * @param pf Where to store the value on success.
186 * @param fDef The default value to assign if the key is not found.
187 */
188DECLHIDDEN(int) utsGadgetCfgQueryBoolDef(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
189 bool *pf, bool fDef);
190
191/**
192 * Queries the string value of a given key from the given configuration array.
193 *
194 * @returns IPRT status code.
195 * @param paCfg The configuration items.
196 * @param pszKey The key query the value for.
197 * @param ppszVal Where to store the pointer to the string on success,
198 * must be freed with RTStrFree().
199 */
200DECLHIDDEN(int) utsGadgetCfgQueryString(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
201 char **ppszVal);
202
203/**
204 * Queries the string value of a given key from the given configuration array,
205 * setting a default if not found.
206 *
207 * @returns IPRT status code.
208 * @param paCfg The configuration items.
209 * @param pszKey The key query the value for.
210 * @param ppszVal Where to store the pointer to the string on success,
211 * must be freed with RTStrFree().
212 * @param pszDef The default value to assign if the key is not found.
213 */
214DECLHIDDEN(int) utsGadgetCfgQueryStringDef(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
215 char **ppszVal, const char *pszDef);
216
217/**
218 * Queries the value of a given uint8_t key from the given configuration array.
219 *
220 * @returns IPRT status code.
221 * @param paCfg The configuration items.
222 * @param pszKey The key query the value for.
223 * @param pu8 Where to store the value on success.
224 */
225DECLHIDDEN(int) utsGadgetCfgQueryU8(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
226 uint8_t *pu8);
227
228/**
229 * Queries the value of a given uint8_t key from the given configuration array,
230 * setting a default if not found.
231 *
232 * @returns IPRT status code.
233 * @param paCfg The configuration items.
234 * @param pszKey The key query the value for.
235 * @param pu8 Where to store the value on success.
236 * @param u8Def The default value to assign if the key is not found.
237 */
238DECLHIDDEN(int) utsGadgetCfgQueryU8Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
239 uint8_t *pu8, uint8_t u8Def);
240
241/**
242 * Queries the value of a given uint16_t key from the given configuration array.
243 *
244 * @returns IPRT status code.
245 * @param paCfg The configuration items.
246 * @param pszKey The key query the value for.
247 * @param pu16 Where to store the value on success.
248 */
249DECLHIDDEN(int) utsGadgetCfgQueryU16(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
250 uint16_t *pu16);
251
252/**
253 * Queries the value of a given uint16_t key from the given configuration array,
254 * setting a default if not found.
255 *
256 * @returns IPRT status code.
257 * @param paCfg The configuration items.
258 * @param pszKey The key query the value for.
259 * @param pu16 Where to store the value on success.
260 * @param u16Def The default value to assign if the key is not found.
261 */
262DECLHIDDEN(int) utsGadgetCfgQueryU16Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
263 uint16_t *pu16, uint16_t u16Def);
264
265/**
266 * Queries the value of a given uint32_t key from the given configuration array.
267 *
268 * @returns IPRT status code.
269 * @param paCfg The configuration items.
270 * @param pszKey The key query the value for.
271 * @param pu32 Where to store the value on success.
272 */
273DECLHIDDEN(int) utsGadgetCfgQueryU32(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
274 uint32_t *pu32);
275
276/**
277 * Queries the value of a given uint32_t key from the given configuration array,
278 * setting a default if not found.
279 *
280 * @returns IPRT status code.
281 * @param paCfg The configuration items.
282 * @param pszKey The key query the value for.
283 * @param pu32 Where to store the value on success.
284 * @param u32Def The default value to assign if the key is not found.
285 */
286DECLHIDDEN(int) utsGadgetCfgQueryU32Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
287 uint32_t *pu32, uint32_t u32Def);
288
289/**
290 * Queries the value of a given uint64_t key from the given configuration array.
291 *
292 * @returns IPRT status code.
293 * @param paCfg The configuration items.
294 * @param pszKey The key query the value for.
295 * @param pu64 Where to store the value on success.
296 */
297DECLHIDDEN(int) utsGadgetCfgQueryU64(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
298 uint64_t *pu64);
299
300/**
301 * Queries the value of a given uint64_t key from the given configuration array,
302 * setting a default if not found.
303 *
304 * @returns IPRT status code.
305 * @param paCfg The configuration items.
306 * @param pszKey The key query the value for.
307 * @param pu64 Where to store the value on success.
308 * @param u64Def The default value to assign if the key is not found.
309 */
310DECLHIDDEN(int) utsGadgetCfgQueryU64Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
311 uint64_t *pu64, uint64_t u64Def);
312
313/**
314 * Queries the value of a given int8_t key from the given configuration array.
315 *
316 * @returns IPRT status code.
317 * @param paCfg The configuration items.
318 * @param pszKey The key query the value for.
319 * @param pi8 Where to store the value on success.
320 */
321DECLHIDDEN(int) utsGadgetCfgQueryS8(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
322 int8_t *pi8);
323
324/**
325 * Queries the value of a given int8_t key from the given configuration array,
326 * setting a default if not found.
327 *
328 * @returns IPRT status code.
329 * @param paCfg The configuration items.
330 * @param pszKey The key query the value for.
331 * @param pi8 Where to store the value on success.
332 * @param i8Def The default value to assign if the key is not found.
333 */
334DECLHIDDEN(int) utsGadgetCfgQueryS8Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
335 int8_t *pi8, uint8_t i8Def);
336
337/**
338 * Queries the value of a given int16_t key from the given configuration array.
339 *
340 * @returns IPRT status code.
341 * @param paCfg The configuration items.
342 * @param pszKey The key query the value for.
343 * @param pi16 Where to store the value on success.
344 */
345DECLHIDDEN(int) utsGadgetCfgQueryS16(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
346 uint16_t *pi16);
347
348/**
349 * Queries the value of a given int16_t key from the given configuration array,
350 * setting a default if not found.
351 *
352 * @returns IPRT status code.
353 * @param paCfg The configuration items.
354 * @param pszKey The key query the value for.
355 * @param pi16 Where to store the value on success.
356 * @param i16Def The default value to assign if the key is not found.
357 */
358DECLHIDDEN(int) utsGadgetCfgQueryS16Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
359 uint16_t *pi16, uint16_t i16Def);
360
361/**
362 * Queries the value of a given int32_t key from the given configuration array.
363 *
364 * @returns IPRT status code.
365 * @param paCfg The configuration items.
366 * @param pszKey The key query the value for.
367 * @param pi32 Where to store the value on success.
368 */
369DECLHIDDEN(int) utsGadgetCfgQueryS32(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
370 uint32_t *pi32);
371
372/**
373 * Queries the value of a given int32_t key from the given configuration array,
374 * setting a default if not found.
375 *
376 * @returns IPRT status code.
377 * @param paCfg The configuration items.
378 * @param pszKey The key query the value for.
379 * @param pi32 Where to store the value on success.
380 * @param i32Def The default value to assign if the key is not found.
381 */
382DECLHIDDEN(int) utsGadgetCfgQueryS32Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
383 uint32_t *pi32, uint32_t i32Def);
384
385/**
386 * Queries the value of a given int64_t key from the given configuration array.
387 *
388 * @returns IPRT status code.
389 * @param paCfg The configuration items.
390 * @param pszKey The key query the value for.
391 * @param pi64 Where to store the value on success.
392 */
393DECLHIDDEN(int) utsGadgetCfgQueryS64(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
394 uint64_t *pi64);
395
396/**
397 * Queries the value of a given int64_t key from the given configuration array,
398 * setting a default if not found.
399 *
400 * @returns IPRT status code.
401 * @param paCfg The configuration items.
402 * @param pszKey The key query the value for.
403 * @param pi64 Where to store the value on success.
404 * @param i64Def The default value to assign if the key is not found.
405 */
406DECLHIDDEN(int) utsGadgetCfgQueryS64Def(PCUTSGADGETCFGITEM paCfg, const char *pszKey,
407 uint64_t *pi64, uint64_t i64Def);
408
409/**
410 * Creates a new USB gadget host.
411 *
412 * @returns IPRT status code.
413 * @param enmType The host type.
414 * @param paCfg Additional configuration parameters - optional.
415 * The array must be terminated with a NULL entry.
416 * @param phGadgetHost Where to store the handle to the gadget host on success.
417 */
418DECLHIDDEN(int) utsGadgetHostCreate(UTSGADGETHOSTTYPE enmType, PCUTSGADGETCFGITEM paCfg,
419 PUTSGADGETHOST phGadgetHost);
420
421/**
422 * Retains the given gadget host handle.
423 *
424 * @returns New reference count.
425 * @param hGadgetHost The gadget host handle to retain.
426 */
427DECLHIDDEN(uint32_t) utsGadgetHostRetain(UTSGADGETHOST hGadgetHost);
428
429/**
430 * Releases the given gadget host handle, destroying it if the reference
431 * count reaches 0.
432 *
433 * @returns New reference count.
434 * @param hGadgetHost The gadget host handle to release.
435 */
436DECLHIDDEN(uint32_t) utsGadgetHostRelease(UTSGADGETHOST hGadgetHost);
437
438/**
439 * Returns the current config of the given gadget host.
440 *
441 * @returns Pointer to a constant array of configuration items for the given gadget host.
442 * @param hGadgetHost The gadget host handle.
443 */
444DECLHIDDEN(PCUTSGADGETCFGITEM) utsGadgetHostGetCfg(UTSGADGETHOST hGadgetHost);
445
446/**
447 * Connects the given gadget to the host.
448 *
449 * @returns IPRT status code.
450 * @param hGadgetHost The gadget host handle.
451 * @param hGadget The gadget handle.
452 */
453DECLHIDDEN(int) utsGadgetHostGadgetConnect(UTSGADGETHOST hGadgetHost, UTSGADGET hGadget);
454
455/**
456 * Disconnects the given gadget from the host.
457 *
458 * @returns IPRT status code.
459 * @param hGadgetHost The gadget host handle.
460 * @param hGadget The gadget handle.
461 */
462DECLHIDDEN(int) utsGadgetHostGadgetDisconnect(UTSGADGETHOST hGadgetHost, UTSGADGET hGadget);
463
464/**
465 * Creates a new USB gadget based the class.
466 *
467 * @returns IPRT status code.
468 * @param hGadgetHost The gadget host the gadget is part of.
469 * @param enmClass The gadget class.
470 * @param paCfg Array of optional configuration items for the gadget.
471 * @param phGadget Where to store the gadget handle on success.
472 */
473DECLHIDDEN(int) utsGadgetCreate(UTSGADGETHOST hGadgetHost, UTSGADGETCLASS enmClass,
474 PCUTSGADGETCFGITEM paCfg, PUTSGADET phGadget);
475
476/**
477 * Retains the given gadget handle.
478 *
479 * @returns New reference count.
480 * @param hGadget The gadget handle to retain.
481 */
482DECLHIDDEN(uint32_t) utsGadgetRetain(UTSGADGET hGadget);
483
484/**
485 * Releases the given gadget handle, destroying it if the reference
486 * count reaches 0.
487 *
488 * @returns New reference count.
489 * @param hGadget The gadget handle to destroy.
490 */
491DECLHIDDEN(uint32_t) utsGadgetRelease(UTSGADGET hGadget);
492
493/**
494 * Returns the current config of the given gadget.
495 *
496 * @returns Pointer to a constant array of configuration items for the given gadget.
497 * @param hGadget The gadget handle.
498 */
499DECLHIDDEN(PCUTSGADGETCFGITEM) utsGadgetGetCfg(UTSGADGET hGadget);
500
501/**
502 * Returns the path of the given gadget from which it can be accessed.
503 *
504 * @returns Access path.
505 * @param hGadget The gadget handle.
506 */
507DECLHIDDEN(const char *) utsGadgetGetAccessPath(UTSGADGET hGadget);
508
509/**
510 * Returns the bus ID the gadget is on.
511 *
512 * @returns Bus ID of the gadget.
513 * @param hGadget The gadget handle.
514 */
515DECLHIDDEN(uint32_t) utsGadgetGetBusId(UTSGADGET hGadget);
516
517/**
518 * Returns the device ID of the gagdet.
519 *
520 * @returns Device ID of the gadget.
521 * @param hGadget The gadget handle.
522 */
523DECLHIDDEN(uint32_t) utsGadgetGetDevId(UTSGADGET hGadget);
524
525/**
526 * Mark the gadget as connected to the host. Depending
527 * on the host type it will be appear as physically attached
528 * or will appear in the exported USB device list.
529 *
530 * @returns IPRT status code.
531 * @param hGadget The gadget handle to connect.
532 */
533DECLHIDDEN(int) utsGadgetConnect(UTSGADGET hGadget);
534
535/**
536 * Mark the gadget as disconnected from the host.
537 *
538 * @returns IPRT status code.
539 * @param hGadget The gadget handle to disconnect.
540 */
541DECLHIDDEN(int) utsGadgetDisconnect(UTSGADGET hGadget);
542
543RT_C_DECLS_END
544
545#endif /* !VBOX_INCLUDED_SRC_usb_UsbTestServiceGadget_h */
546
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette