1 /***************************************************************************
2 * Copyright (c) 2024 Microsoft Corporation
3 *
4 * This program and the accompanying materials are made available under the
5 * terms of the MIT License which is available at
6 * https://opensource.org/licenses/MIT.
7 *
8 * SPDX-License-Identifier: MIT
9 **************************************************************************/
10
11
12 /**************************************************************************/
13 /**************************************************************************/
14 /** */
15 /** USBX Component */
16 /** */
17 /** Host Stack */
18 /** */
19 /**************************************************************************/
20 /**************************************************************************/
21
22
23 /* Include necessary system files. */
24
25 #define UX_SOURCE_CODE
26
27 #include "ux_api.h"
28 #include "ux_host_stack.h"
29
30
31 /**************************************************************************/
32 /* */
33 /* FUNCTION RELEASE */
34 /* */
35 /* _ux_host_stack_device_string_get PORTABLE C */
36 /* 6.1.10 */
37 /* AUTHOR */
38 /* */
39 /* Chaoqiong Xiao, Microsoft Corporation */
40 /* */
41 /* DESCRIPTION */
42 /* */
43 /* This function obtains the device string descriptor. */
44 /* */
45 /* INPUT */
46 /* */
47 /* device Pointer to device instance */
48 /* descriptor_buffer Pointer to a buffer to fill */
49 /* LANGID or STRING descriptor */
50 /* length Length of buffer */
51 /* language_id 0 to obtain LANGID descriptor */
52 /* valid language ID to obtain */
53 /* string descriptor */
54 /* string_index Index of the string */
55 /* */
56 /* OUTPUT */
57 /* */
58 /* Completion Status */
59 /* */
60 /* CALLS */
61 /* */
62 /* _ux_host_stack_transfer_request Process transfer request */
63 /* _ux_utility_semaphore_get Get Semaphore */
64 /* */
65 /* CALLED BY */
66 /* */
67 /* Application */
68 /* */
69 /* RELEASE HISTORY */
70 /* */
71 /* DATE NAME DESCRIPTION */
72 /* */
73 /* 02-02-2021 Chaoqiong Xiao Initial Version 6.1.4 */
74 /* 06-02-2021 Chaoqiong Xiao Modified comment(s), and */
75 /* removed unnecessary header, */
76 /* resulting in version 6.1.7 */
77 /* 01-31-2022 Chaoqiong Xiao Modified comment(s), */
78 /* added standalone support, */
79 /* resulting in version 6.1.10 */
80 /* */
81 /**************************************************************************/
_ux_host_stack_device_string_get(UX_DEVICE * device,UCHAR * descriptor_buffer,ULONG length,ULONG language_id,ULONG string_index)82 UINT _ux_host_stack_device_string_get(UX_DEVICE *device, UCHAR *descriptor_buffer, ULONG length, ULONG language_id, ULONG string_index)
83 {
84 #if defined(UX_HOST_STANDALONE)
85 UX_INTERRUPT_SAVE_AREA
86 #endif
87 UX_ENDPOINT *control_endpoint;
88 UX_TRANSFER *transfer_request;
89 UINT status;
90
91
92 /* Do a sanity check on the device handle. */
93 if (device -> ux_device_handle != (ULONG) (ALIGN_TYPE) device)
94 {
95
96 /* Error trap. */
97 _ux_system_error_handler(UX_SYSTEM_LEVEL_THREAD, UX_SYSTEM_CONTEXT_ENUMERATOR, UX_DEVICE_HANDLE_UNKNOWN);
98
99 /* If trace is enabled, insert this event into the trace buffer. */
100 UX_TRACE_IN_LINE_INSERT(UX_TRACE_ERROR, UX_DEVICE_HANDLE_UNKNOWN, device, 0, 0, UX_TRACE_ERRORS, 0, 0)
101
102 return(UX_DEVICE_HANDLE_UNKNOWN);
103 }
104
105 /* If trace is enabled, insert this event into the trace buffer. */
106 UX_TRACE_IN_LINE_INSERT(UX_TRACE_HOST_STACK_DEVICE_STRING_GET, device, descriptor_buffer, length, (language_id << 16) | string_index, UX_TRACE_HOST_CLASS_EVENTS, 0, 0)
107
108 /* We need to get the default control endpoint transfer request pointer. */
109 control_endpoint = &device -> ux_device_control_endpoint;
110 transfer_request = &control_endpoint -> ux_endpoint_transfer_request;
111
112 #if defined(UX_HOST_STANDALONE)
113 UX_DISABLE
114 if ((device -> ux_device_flags & UX_DEVICE_FLAG_LOCK) ||
115 (transfer_request -> ux_transfer_request_flags & UX_TRANSFER_FLAG_LOCK))
116 {
117 UX_RESTORE
118 return(UX_BUSY);
119 }
120 device -> ux_device_flags |= UX_DEVICE_FLAG_LOCK;
121 transfer_request -> ux_transfer_request_flags |=
122 (UX_TRANSFER_FLAG_LOCK | UX_TRANSFER_FLAG_AUTO_DEVICE_UNLOCK);
123 UX_RESTORE
124 #else
125
126 /* Protect the control endpoint semaphore here. It will be unprotected in the
127 transfer request function. */
128 status = _ux_host_semaphore_get(&device -> ux_device_protection_semaphore, UX_WAIT_FOREVER);
129
130 /* Check for status. */
131 if (status != UX_SUCCESS)
132 return(UX_SEMAPHORE_ERROR);
133 #endif
134
135 /* Create a transfer request for the GET_DEVICE_ID request. */
136 transfer_request -> ux_transfer_request_data_pointer = descriptor_buffer;
137 transfer_request -> ux_transfer_request_requested_length = length;
138 transfer_request -> ux_transfer_request_function = UX_GET_DESCRIPTOR;
139 transfer_request -> ux_transfer_request_type = UX_REQUEST_IN | UX_REQUEST_TYPE_STANDARD | UX_REQUEST_TARGET_DEVICE;
140 transfer_request -> ux_transfer_request_value = (UX_STRING_DESCRIPTOR_ITEM << 8) | string_index;
141 transfer_request -> ux_transfer_request_index = (language_id);
142
143 /* Send request to HCD layer. */
144 status = _ux_host_stack_transfer_request(transfer_request);
145
146 /* Return completion status. */
147 return(status);
148 }
149
150
151 /**************************************************************************/
152 /* */
153 /* FUNCTION RELEASE */
154 /* */
155 /* _uxe_host_stack_device_string_get PORTABLE C */
156 /* 6.3.0 */
157 /* AUTHOR */
158 /* */
159 /* Chaoqiong Xiao, Microsoft Corporation */
160 /* */
161 /* DESCRIPTION */
162 /* */
163 /* This function checks errors in host stack device get function call. */
164 /* */
165 /* INPUT */
166 /* */
167 /* device Pointer to device instance */
168 /* descriptor_buffer Pointer to a buffer to fill */
169 /* LANGID or STRING descriptor */
170 /* length Length of buffer */
171 /* language_id 0 to obtain LANGID descriptor */
172 /* valid language ID to obtain */
173 /* string descriptor */
174 /* string_index Index of the string */
175 /* */
176 /* OUTPUT */
177 /* */
178 /* None */
179 /* */
180 /* CALLS */
181 /* */
182 /* _ux_host_stack_device_string_get String descriptor get */
183 /* */
184 /* CALLED BY */
185 /* */
186 /* Application */
187 /* */
188 /* RELEASE HISTORY */
189 /* */
190 /* DATE NAME DESCRIPTION */
191 /* */
192 /* 10-31-2023 Chaoqiong Xiao Initial Version 6.3.0 */
193 /* */
194 /**************************************************************************/
_uxe_host_stack_device_string_get(UX_DEVICE * device,UCHAR * descriptor_buffer,ULONG length,ULONG language_id,ULONG string_index)195 UINT _uxe_host_stack_device_string_get(UX_DEVICE *device, UCHAR *descriptor_buffer, ULONG length, ULONG language_id, ULONG string_index)
196 {
197
198 /* Sanity check. */
199 if ((device == UX_NULL) || (descriptor_buffer == UX_NULL) || (length == 0))
200 return(UX_INVALID_PARAMETER);
201
202 /* Invoke string descriptor get function. */
203 return(_ux_host_stack_device_string_get(device, descriptor_buffer, length, language_id, string_index));
204 }
205
