libnx  v4.2.2
usbds.h
Go to the documentation of this file.
1 /**
2  * @file usbds.h
3  * @brief USB (usb:ds) service IPC wrapper.
4  * @brief Switch-as-device<>host USB comms, see also here: https://switchbrew.org/wiki/USB_services
5  * @author SciresM, yellows8
6  * @copyright libnx Authors
7  */
8 #pragma once
9 #include "../types.h"
10 #include "../sf/service.h"
11 #include "../services/usb.h"
12 #include "../kernel/event.h"
13 
14 #define USBDS_DEFAULT_InterfaceNumber 0x4 ///Value for usb_interface_descriptor bInterfaceNumber for automatically allocating the actual bInterfaceNumber.
15 
16 typedef struct {
17  bool initialized;
18  u8 interface_index;
19  Service s;
20 
21  Event SetupEvent;
22  Event CtrlInCompletionEvent;
23  Event CtrlOutCompletionEvent;
25 
26 typedef struct {
27  bool initialized;
28  Service s;
29  Event CompletionEvent;
31 
32 typedef struct {
33  u16 idVendor; ///< VID
34  u16 idProduct; ///< PID
35  u16 bcdDevice;
36  char Manufacturer[0x20];
37  char Product[0x20];
38  char SerialNumber[0x20];
40 
41 typedef struct {
42  u32 id; ///< urbId from post-buffer cmds
43  u32 requestedSize;
44  u32 transferredSize;
45  u32 urb_status;
47 
48 typedef struct {
49  UsbDsReportEntry report[8];
50  u32 report_count;
52 
53 typedef enum {
54  UsbComplexId_Default = 0x2
55 } UsbComplexId;
56 
57 typedef enum {
58  UsbDeviceSpeed_Full = 0x2, ///< USB 1.1 Full Speed
59  UsbDeviceSpeed_High = 0x3, ///< USB 2.0 High Speed
60  UsbDeviceSpeed_Super = 0x4, ///< USB 3.0 Super Speed
62 
63 /// Opens a session with usb:ds.
65 
66 /// Closes the usb:ds session. Any interfaces/endpoints which are left open are automatically closed, since otherwise usb-sysmodule won't fully reset usb:ds to defaults.
67 void usbDsExit(void);
68 
69 /// Gets the Service object for the actual usb:ds service session.
71 
72 /// Helper func.
73 Result usbDsWaitReady(u64 timeout);
74 
75 /// Helper func.
76 Result usbDsParseReportData(UsbDsReportData *reportdata, u32 urbId, u32 *requestedSize, u32 *transferredSize);
77 
78 ///@name IDsService
79 ///@{
80 
81 Event* usbDsGetStateChangeEvent(void);
82 
83 /// Gets the device state. See \ref UsbState.
85 
86 /// Removed in [5.0.0+].
87 Result usbDsGetDsInterface(UsbDsInterface** out, struct usb_interface_descriptor* descriptor, const char* interface_name);
88 
89 /// Removed in [5.0.0+].
90 Result usbDsSetVidPidBcd(const UsbDsDeviceInfo* deviceinfo);
91 
92 /// Only available on [5.0.0+].
94 
95 /// Only available on [5.0.0+].
97 
98 /// Only available on [5.0.0+].
100 
101 /// Only available on [5.0.0+].
102 Result usbDsAddUsbStringDescriptor(u8* out_index, const char* string);
103 
104 /// Only available on [5.0.0+].
105 Result usbDsAddUsbLanguageStringDescriptor(u8* out_index, const u16* lang_ids, u16 num_langs);
106 
107 /// Only available on [5.0.0+].
109 
110 /// Only available on [5.0.0+].
112 
113 /// Only available on [5.0.0+].
114 Result usbDsSetBinaryObjectStore(const void* bos, size_t bos_size);
115 
116 /// Only available on [5.0.0+].
117 Result usbDsEnable(void);
118 
119 /// Only available on [5.0.0+].
120 Result usbDsDisable(void);
121 
122 ///@}
123 
124 ///@name IDsInterface
125 ///@{
126 
127 void usbDsInterface_Close(UsbDsInterface* interface);
128 
129 Result usbDsInterface_GetSetupPacket(UsbDsInterface* interface, void* buffer, size_t size);
130 Result usbDsInterface_EnableInterface(UsbDsInterface* interface);
131 Result usbDsInterface_DisableInterface(UsbDsInterface* interface);
132 Result usbDsInterface_CtrlInPostBufferAsync(UsbDsInterface* interface, void* buffer, size_t size, u32* urbId);
133 Result usbDsInterface_CtrlOutPostBufferAsync(UsbDsInterface* interface, void* buffer, size_t size, u32* urbId);
134 Result usbDsInterface_GetCtrlInReportData(UsbDsInterface* interface, UsbDsReportData* out);
135 Result usbDsInterface_GetCtrlOutReportData(UsbDsInterface* interface, UsbDsReportData* out);
136 Result usbDsInterface_StallCtrl(UsbDsInterface* interface);
137 
138 /// Removed in [5.0.0+].
140 
141 /// Only available on [5.0.0+].
142 Result usbDsInterface_RegisterEndpoint(UsbDsInterface* interface, UsbDsEndpoint** endpoint, u8 endpoint_address);
143 
144 /// Only available on [5.0.0+].
145 Result usbDsInterface_AppendConfigurationData(UsbDsInterface* interface, UsbDeviceSpeed speed, const void* buffer, size_t size);
146 
147 ///@}
148 
149 ///@name IDsEndpoint
150 ///@{
151 
152 void usbDsEndpoint_Close(UsbDsEndpoint* endpoint);
153 
154 Result usbDsEndpoint_Cancel(UsbDsEndpoint* endpoint);
155 Result usbDsEndpoint_PostBufferAsync(UsbDsEndpoint* endpoint, void* buffer, size_t size, u32* urbId);
156 Result usbDsEndpoint_GetReportData(UsbDsEndpoint* endpoint, UsbDsReportData* out);
157 Result usbDsEndpoint_Stall(UsbDsEndpoint* endpoint);
158 Result usbDsEndpoint_SetZlt(UsbDsEndpoint* endpoint, bool zlt); // Sets Zero Length Termination for endpoint
159 
160 ///@}
161 
UsbDsDeviceInfo::idProduct
u16 idProduct
PID.
Definition: usbds.h:34
usbDsClearDeviceData
Result usbDsClearDeviceData(void)
Only available on [5.0.0+].
usbDsInterface_RegisterEndpoint
Result usbDsInterface_RegisterEndpoint(UsbDsInterface *interface, UsbDsEndpoint **endpoint, u8 endpoint_address)
Only available on [5.0.0+].
usbDsExit
void usbDsExit(void)
Closes the usb:ds session. Any interfaces/endpoints which are left open are automatically closed,...
UsbDsDeviceInfo::idVendor
u16 idVendor
VID.
Definition: usbds.h:33
UsbDsReportData
Definition: usbds.h:48
UsbDeviceSpeed_High
@ UsbDeviceSpeed_High
USB 2.0 High Speed.
Definition: usbds.h:59
UsbDsReportEntry::id
u32 id
urbId from post-buffer cmds
Definition: usbds.h:42
UsbDsEndpoint
Definition: usbds.h:26
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
Event
Kernel-mode event structure.
Definition: event.h:13
usbDsInterface_AppendConfigurationData
Result usbDsInterface_AppendConfigurationData(UsbDsInterface *interface, UsbDeviceSpeed speed, const void *buffer, size_t size)
Only available on [5.0.0+].
usbDsAddUsbLanguageStringDescriptor
Result usbDsAddUsbLanguageStringDescriptor(u8 *out_index, const u16 *lang_ids, u16 num_langs)
Only available on [5.0.0+].
usbDsAddUsbStringDescriptor
Result usbDsAddUsbStringDescriptor(u8 *out_index, const char *string)
Only available on [5.0.0+].
usb_endpoint_descriptor
Imported from libusb, with some adjustments.
Definition: usb.h:25
UsbDeviceSpeed_Super
@ UsbDeviceSpeed_Super
USB 3.0 Super Speed.
Definition: usbds.h:60
UsbDsReportEntry
Definition: usbds.h:41
usbDsRegisterInterface
Result usbDsRegisterInterface(UsbDsInterface **out)
Only available on [5.0.0+].
usbDsWaitReady
Result usbDsWaitReady(u64 timeout)
Helper func.
usb_interface_descriptor
Imported from libusb, with some adjustments.
Definition: usb.h:35
UsbDsInterface
Definition: usbds.h:16
usbDsSetVidPidBcd
Result usbDsSetVidPidBcd(const UsbDsDeviceInfo *deviceinfo)
Removed in [5.0.0+].
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
usbDsInterface_GetDsEndpoint
Result usbDsInterface_GetDsEndpoint(UsbDsInterface *interface, UsbDsEndpoint **endpoint, struct usb_endpoint_descriptor *descriptor)
Removed in [5.0.0+].
usbDsGetState
Result usbDsGetState(UsbState *out)
Gets the device state. See UsbState.
usb_device_descriptor
Imported from libusb, with some adjustments.
Definition: usb.h:48
usbDsEnable
Result usbDsEnable(void)
Only available on [5.0.0+].
usbDsInitialize
Result usbDsInitialize(void)
Opens a session with usb:ds.
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
UsbDeviceSpeed_Full
@ UsbDeviceSpeed_Full
USB 1.1 Full Speed.
Definition: usbds.h:58
Result
u32 Result
Function error code result type.
Definition: types.h:44
UsbState
UsbState
USB Device States, per USB 2.0 spec.
Definition: usb.h:211
UsbDeviceSpeed
UsbDeviceSpeed
Definition: usbds.h:57
usbDsSetUsbDeviceDescriptor
Result usbDsSetUsbDeviceDescriptor(UsbDeviceSpeed speed, struct usb_device_descriptor *descriptor)
Only available on [5.0.0+].
usbDsDisable
Result usbDsDisable(void)
Only available on [5.0.0+].
usbDsSetBinaryObjectStore
Result usbDsSetBinaryObjectStore(const void *bos, size_t bos_size)
Only available on [5.0.0+].
usbDsDeleteUsbStringDescriptor
Result usbDsDeleteUsbStringDescriptor(u8 index)
Only available on [5.0.0+].
usbDsParseReportData
Result usbDsParseReportData(UsbDsReportData *reportdata, u32 urbId, u32 *requestedSize, u32 *transferredSize)
Helper func.
Service
Service object structure.
Definition: service.h:13
usbDsGetDsInterface
Result usbDsGetDsInterface(UsbDsInterface **out, struct usb_interface_descriptor *descriptor, const char *interface_name)
Removed in [5.0.0+].
UsbDsDeviceInfo
Definition: usbds.h:32
u16
uint16_t u16
16-bit unsigned integer.
Definition: types.h:20
usbDsRegisterInterfaceEx
Result usbDsRegisterInterfaceEx(UsbDsInterface **out, u8 intf_num)
Only available on [5.0.0+].
usbDsGetServiceSession
Service * usbDsGetServiceSession(void)
Gets the Service object for the actual usb:ds service session.