1/*
2 * Copyright (c) 2023 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15#ifndef USB_DDK_API_H
16#define USB_DDK_API_H
17
18/**
19 * @addtogroup UsbDdk
20 * @{
21 *
22 * @brief Provides USB DDK APIs to open and close USB interfaces, perform non-isochronous and isochronous\n
23 * data transfer over USB pipes, and implement control transfer and interrupt transfer, etc.
24 *
25 * @syscap SystemCapability.Driver.USB.Extension
26 * @since 10
27 * @version 1.0
28 */
29
30/**
31 * @file usb_ddk_api.h
32 *
33 * @brief Declares the USB DDK APIs used by the USB host to access USB devices.
34 *
35 * @since 10
36 * @version 1.0
37 */
38
39#include <stdint.h>
40
41#include "ddk_types.h"
42#include "usb_ddk_types.h"
43
44#ifdef __cplusplus
45extern "C" {
46#endif /* __cplusplus */
47
48/**
49 * @brief Initializes the DDK.
50 *
51 * @permission ohos.permission.ACCESS_DDK_USB
52 * @return <b>0</b> if the operation is successful; a negative value otherwise.
53 * @since 10
54 * @version 1.0
55 */
56int32_t OH_Usb_Init(void);
57
58/**
59 * @brief Releases the DDK.
60 *
61 * @permission ohos.permission.ACCESS_DDK_USB
62 * @since 10
63 * @version 1.0
64 */
65void OH_Usb_Release(void);
66
67/**
68 * @brief Obtains the USB device descriptor.
69 *
70 * @permission ohos.permission.ACCESS_DDK_USB
71 * @param deviceId ID of the device whose descriptor is to be obtained.
72 * @param desc Standard device descriptor defined in the USB protocol.
73 * @return <b>0</b> if the operation is successful; a negative value otherwise.
74 * @since 10
75 * @version 1.0
76 */
77int32_t OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc);
78
79/**
80 * @brief Obtains the configuration descriptor. To avoid memory leakage, use <b>OH_Usb_FreeConfigDescriptor</b>\n
81 * to release a descriptor after use.
82 *
83 * @permission ohos.permission.ACCESS_DDK_USB
84 * @param deviceId ID of the device whose configuration descriptor is to be obtained.
85 * @param configIndex Configuration index, which corresponds to <b>bConfigurationValue</b> in the USB protocol.
86 * @param config Configuration descriptor, which includes the standard configuration descriptor defined in the\n
87 * USB protocol and the associated interface descriptor and endpoint descriptor.
88 * @return <b>0</b> if the operation is successful; a negative value otherwise.
89 * @since 10
90 * @version 1.0
91 */
92int32_t OH_Usb_GetConfigDescriptor(
93    uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor ** const config);
94
95/**
96 * @brief Releases the configuration descriptor. To avoid memory leakage, use <b>OH_Usb_FreeConfigDescriptor</b>\n
97 * to release a descriptor after use.
98 *
99 * @permission ohos.permission.ACCESS_DDK_USB
100 * @param config Configuration descriptor obtained by calling <b>OH_Usb_GetConfigDescriptor</b>.
101 * @since 10
102 * @version 1.0
103 */
104void OH_Usb_FreeConfigDescriptor(struct UsbDdkConfigDescriptor * const config);
105
106/**
107 * @brief Claims a USB interface.
108 *
109 * @permission ohos.permission.ACCESS_DDK_USB
110 * @param deviceId ID of the device to be operated.
111 * @param interfaceIndex Interface index, which corresponds to <b>bInterfaceNumber</b> in the USB protocol.
112 * @param interfaceHandle Interface operation handle. After the interface is claimed successfully, a value will be\n
113 * assigned to this parameter.
114 * @return <b>0</b> if the operation is successful; a negative value otherwise.
115 * @since 10
116 * @version 1.0
117 */
118int32_t OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle);
119
120/**
121 * @brief Releases a USB interface.
122 *
123 * @permission ohos.permission.ACCESS_DDK_USB
124 * @param interfaceHandle Interface operation handle.
125 * @return <b>0</b> if the operation is successful; a negative value otherwise.
126 * @since 10
127 * @version 1.0
128 */
129int32_t OH_Usb_ReleaseInterface(uint64_t interfaceHandle);
130
131/**
132 * @brief Activates the alternate setting of the USB interface.
133 *
134 * @permission ohos.permission.ACCESS_DDK_USB
135 * @param interfaceHandle Interface operation handle.
136 * @param settingIndex Index of the alternate setting, which corresponds to <b>bAlternateSetting</b>\n
137 * in the USB protocol.
138 * @return <b>0</b> if the operation is successful; a negative value otherwise.
139 * @since 10
140 * @version 1.0
141 */
142int32_t OH_Usb_SelectInterfaceSetting(uint64_t interfaceHandle, uint8_t settingIndex);
143
144/**
145 * @brief Obtains the activated alternate setting of the USB interface.
146 *
147 * @permission ohos.permission.ACCESS_DDK_USB
148 * @param interfaceHandle Interface operation handle.
149 * @param settingIndex Index of the alternate setting, which corresponds to <b>bAlternateSetting</b>\n
150 * in the USB protocol.
151 * @return <b>0</b> if the operation is successful; a negative value otherwise.
152 * @since 10
153 * @version 1.0
154 */
155int32_t OH_Usb_GetCurrentInterfaceSetting(uint64_t interfaceHandle, uint8_t *settingIndex);
156
157/**
158 * @brief Sends a control read transfer request. This API works in a synchronous manner.
159 *
160 * @permission ohos.permission.ACCESS_DDK_USB
161 * @param interfaceHandle Interface operation handle.
162 * @param setup Request data, which corresponds to <b>Setup Data</b> in the USB protocol.
163 * @param timeout Timeout duration, in milliseconds.
164 * @param data Data to be transferred.
165 * @param dataLen Data length. The return value indicates the length of the actually read data.
166 * @return <b>0</b> if the operation is successful; a negative value otherwise.
167 * @since 10
168 * @version 1.0
169 */
170int32_t OH_Usb_SendControlReadRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup,
171    uint32_t timeout, uint8_t *data, uint32_t *dataLen);
172
173/**
174 * @brief Sends a control write transfer request. This API works in a synchronous manner.
175 *
176 * @permission ohos.permission.ACCESS_DDK_USB
177 * @param interfaceHandle Interface operation handle.
178 * @param setup Request data, which corresponds to <b>Setup Data</b> in the USB protocol.
179 * @param timeout Timeout duration, in milliseconds.
180 * @param data Data to be transferred.
181 * @param dataLen Data length.
182 * @return <b>0</b> if the operation is successful; a negative value otherwise.
183 * @since 10
184 * @version 1.0
185 */
186int32_t OH_Usb_SendControlWriteRequest(uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup,
187    uint32_t timeout, const uint8_t *data, uint32_t dataLen);
188
189/**
190 * @brief Sends a pipe request. This API works in a synchronous manner. This API applies to interrupt transfer\n
191 * and bulk transfer.
192 *
193 * @permission ohos.permission.ACCESS_DDK_USB
194 * @param pipe Pipe used to transfer data.
195 * @param devMmap Device memory map, which can be obtained by calling <b>OH_Usb_CreateDeviceMemMap</b>.
196 * @return <b>0</b> if the operation is successful; a negative value otherwise.
197 * @since 10
198 * @version 1.0
199 */
200int32_t OH_Usb_SendPipeRequest(const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap);
201
202/**
203 * @brief Sends a pipe request. This API works in a synchronous manner. This API applies to interrupt transfer\n
204 * and bulk transfer.
205 *
206 * @permission ohos.permission.ACCESS_DDK_USB
207 * @param pipe Pipe used to transfer data.
208 * @param ashmem Shared memory, which can be obtained by calling <b>OH_DDK_CreateAshmem</b>.
209 * @return <b>0</b> if the operation is successful; a negative value otherwise.
210 * @since 12
211 */
212int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem);
213
214/**
215 * @brief Creates a buffer. To avoid resource leakage, destroy a buffer by calling\n
216 * <b>OH_Usb_DestroyDeviceMemMap</b> after use.
217 *
218 * @permission ohos.permission.ACCESS_DDK_USB
219 * @param deviceId ID of the device for which the buffer is to be created.
220 * @param size Buffer size.
221 * @param devMmap Data memory map, through which the created buffer is returned to the caller.
222 * @return <b>0</b> if the operation is successful; a negative value otherwise.
223 * @since 10
224 * @version 1.0
225 */
226int32_t OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap);
227
228/**
229 * @brief Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.
230 *
231 * @permission ohos.permission.ACCESS_DDK_USB
232 * @param devMmap Device memory map created by calling <b>OH_Usb_CreateDeviceMemMap</b>.
233 * @since 10
234 * @version 1.0
235 */
236void OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap);
237/** @} */
238#ifdef __cplusplus
239}
240#endif /* __cplusplus */
241
242#endif // USB_DDK_API_H