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 /** Pima Class */
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_class_pima.h"
29 #include "ux_host_stack.h"
30
31
32 #if UX_SLAVE_REQUEST_DATA_MAX_LENGTH < UX_HOST_CLASS_PIMA_CONTAINER_SIZE
33 #error UX_SLAVE_REQUEST_DATA_MAX_LENGTH too small, please check
34 #endif
35
36 /**************************************************************************/
37 /* */
38 /* FUNCTION RELEASE */
39 /* */
40 /* _ux_host_class_pima_read PORTABLE C */
41 /* 6.1.12 */
42 /* AUTHOR */
43 /* */
44 /* Chaoqiong Xiao, Microsoft Corporation */
45 /* */
46 /* DESCRIPTION */
47 /* */
48 /* This function reads a data payload from the Pima device. This */
49 /* function first read a header followed by some data. */
50 /* */
51 /* Note header only transfer and partial transfer is not accepted. */
52 /* */
53 /* INPUT */
54 /* */
55 /* pima Pointer to pima class */
56 /* data_pointer Pointer to data to read */
57 /* data_length Length of data to read */
58 /* callback_function Application function to call */
59 /* to get the rest of the data */
60 /* max_payload_data Maximum data received in one */
61 /* data payload. */
62 /* */
63 /* OUTPUT */
64 /* */
65 /* Completion Status */
66 /* */
67 /* CALLS */
68 /* */
69 /* _ux_host_stack_transfer_request Process transfer request */
70 /* _ux_host_stack_transfer_request_abort Abort transfer request */
71 /* _ux_host_stack_endpoint_reset Reset endpoint */
72 /* _ux_host_semaphore_get Get protection semaphore */
73 /* _ux_utility_long_get Get a long 32 bit value */
74 /* _ux_utility_short_get Get a short 16 bit value */
75 /* _ux_utility_memory_copy Copy memory */
76 /* */
77 /* CALLED BY */
78 /* */
79 /* Application */
80 /* */
81 /* RELEASE HISTORY */
82 /* */
83 /* DATE NAME DESCRIPTION */
84 /* */
85 /* 05-19-2020 Chaoqiong Xiao Initial Version 6.0 */
86 /* 09-30-2020 Chaoqiong Xiao Modified comment(s), */
87 /* prefixed UX to MS_TO_TICK, */
88 /* verified memset and memcpy */
89 /* cases, */
90 /* resulting in version 6.1 */
91 /* 01-31-2022 Chaoqiong Xiao Modified comment(s), */
92 /* refined macros names, */
93 /* resulting in version 6.1.10 */
94 /* 07-29-2022 Chaoqiong Xiao Modified comment(s), */
95 /* improved length checks, */
96 /* resulting in version 6.1.12 */
97 /* */
98 /**************************************************************************/
_ux_host_class_pima_read(UX_HOST_CLASS_PIMA * pima,UCHAR * data_pointer,ULONG data_length,ULONG max_payload_length)99 UINT _ux_host_class_pima_read(UX_HOST_CLASS_PIMA *pima, UCHAR *data_pointer,
100 ULONG data_length,
101 ULONG max_payload_length)
102
103 {
104
105 UX_TRANSFER *transfer_request;
106 UINT status;
107 ULONG header_length;
108 UCHAR *ptp_payload;
109 ULONG requested_length;
110 ULONG payload_length;
111
112 /* If trace is enabled, insert this event into the trace buffer. */
113 UX_TRACE_IN_LINE_INSERT(UX_TRACE_HOST_CLASS_PIMA_READ, pima, data_pointer, data_length, 0, UX_TRACE_HOST_CLASS_EVENTS, 0, 0)
114
115 /* We use the Bulk In pipe for receiving data .. */
116 transfer_request = &pima -> ux_host_class_pima_bulk_in_endpoint -> ux_endpoint_transfer_request;
117
118 /* Get the pointer to the ptp payload. */
119 ptp_payload = pima -> ux_host_class_pima_container ;
120
121 /* Calculate the requested length for this payload. */
122 requested_length = UX_HOST_CLASS_PIMA_CONTAINER_SIZE;
123
124 /* Initialize the transfer_request. */
125 transfer_request -> ux_transfer_request_data_pointer = ptp_payload;
126 transfer_request -> ux_transfer_request_requested_length = requested_length;
127
128 /* Send request to HCD layer. */
129 status = _ux_host_stack_transfer_request(transfer_request);
130
131 /* If the transfer is successful, we need to wait for the transfer request to be completed. */
132 if (status == UX_SUCCESS)
133 {
134
135 /* Wait for the completion of the transfer request. */
136 status = _ux_host_semaphore_get(&transfer_request -> ux_transfer_request_semaphore, UX_MS_TO_TICK(UX_HOST_CLASS_PIMA_CLASS_TRANSFER_TIMEOUT));
137
138 /* If the semaphore did not succeed we probably have a time out. */
139 if (status != UX_SUCCESS)
140 {
141
142 /* All transfers pending need to abort. There may have been a partial transfer. */
143 _ux_host_stack_transfer_request_abort(transfer_request);
144
145 /* The endpoint was halted by a transfer error and needs to be reset. */
146 _ux_host_stack_endpoint_reset(pima -> ux_host_class_pima_bulk_in_endpoint);
147
148 /* The endpoint was halted by a transfer error and needs to be reset. */
149 _ux_host_stack_endpoint_reset(pima -> ux_host_class_pima_bulk_out_endpoint);
150
151 /* There was an error, return to the caller. */
152 return(status);
153 }
154 }
155 else
156 {
157
158 /* There was a non transfer error, no partial transfer to be checked */
159 return(status);
160 }
161
162 /* Ensure the transfer is greater than the size of a PIMA header. */
163 if (transfer_request -> ux_transfer_request_actual_length <= UX_HOST_CLASS_PIMA_DATA_HEADER_SIZE)
164
165 /* We have a malformed packet. Return error. */
166 return(UX_CLASS_MALFORMED_PACKET_RECEIVED_ERROR);
167
168 /* Get the expected length from the header. */
169 header_length = _ux_utility_long_get(ptp_payload + UX_HOST_CLASS_PIMA_DATA_HEADER_LENGTH);
170
171 /* Device reported data length should be equal or more than this packet
172 * (and UX_HOST_CLASS_PIMA_DATA_HEADER_LENGTH). */
173 if (header_length < transfer_request -> ux_transfer_request_actual_length)
174 return(UX_CLASS_MALFORMED_PACKET_RECEIVED_ERROR);
175
176 /* Check for remainder in last packet. */
177 if ((header_length % pima -> ux_host_class_pima_bulk_in_endpoint -> ux_endpoint_descriptor.wMaxPacketSize) == 0)
178
179 /* We have a ZLP condition on a IN. */
180 pima -> ux_host_class_pima_zlp_flag = UX_HOST_CLASS_PIMA_ZLP_IN;
181 else
182
183 /* Do not expect a ZLP. */
184 pima -> ux_host_class_pima_zlp_flag = UX_HOST_CLASS_PIMA_ZLP_NONE;
185
186 /* The length returned should be smaller than the length requested. */
187 if ((header_length - UX_HOST_CLASS_PIMA_DATA_HEADER_SIZE) > data_length)
188 return(UX_ERROR);
189
190 /* We may have had data in the first packet, if so adjust the data_length. */
191 data_length = header_length - transfer_request -> ux_transfer_request_actual_length;
192
193 /* Copying the necessary partial memory. */
194 _ux_utility_memory_copy(data_pointer, ptp_payload + UX_HOST_CLASS_PIMA_DATA_HEADER_SIZE,
195 transfer_request -> ux_transfer_request_actual_length - UX_HOST_CLASS_PIMA_DATA_HEADER_SIZE); /* Use case of memcpy is verified. */
196
197 /* Adjust the data payload pointer. */
198 data_pointer += (transfer_request -> ux_transfer_request_actual_length - UX_HOST_CLASS_PIMA_DATA_HEADER_SIZE);
199
200 /* Now we can read the data from the device. */
201 while(data_length)
202 {
203
204 /* Check if need to split the data payload into smaller packets. */
205 if (data_length > max_payload_length)
206
207 /* We cannot send everything in this payload. */
208 payload_length = max_payload_length;
209 else
210
211 /* Either this is the last packet or we we have a small packet to send. */
212 payload_length = data_length;
213
214 /* Initialize the transfer_request. */
215 transfer_request -> ux_transfer_request_data_pointer = data_pointer;
216 transfer_request -> ux_transfer_request_requested_length = payload_length;
217
218 /* Send request to HCD layer. */
219 status = _ux_host_stack_transfer_request(transfer_request);
220
221 /* If the transfer is successful, we need to wait for the transfer request to be completed. */
222 if (status == UX_SUCCESS)
223 {
224
225 /* Wait for the completion of the transfer request. */
226 status = _ux_host_semaphore_get(&transfer_request -> ux_transfer_request_semaphore, UX_MS_TO_TICK(UX_HOST_CLASS_PIMA_CLASS_TRANSFER_TIMEOUT));
227
228 /* If the semaphore did not succeed we probably have a time out. */
229 if (status != UX_SUCCESS)
230 {
231
232 /* All transfers pending need to abort. There may have been a partial transfer. */
233 _ux_host_stack_transfer_request_abort(transfer_request);
234
235 /* The endpoint was halted by a transfer error and needs to be reset. */
236 _ux_host_stack_endpoint_reset(pima -> ux_host_class_pima_bulk_in_endpoint);
237
238 /* The endpoint was halted by a transfer error and needs to be reset. */
239 _ux_host_stack_endpoint_reset(pima -> ux_host_class_pima_bulk_out_endpoint);
240
241 /* There was an error, return to the caller. */
242 return(status);
243 }
244 }
245 else
246 {
247
248 /* There was a non transfer error, no partial transfer to be checked */
249 return(status);
250 }
251
252 /* Check for completion of transfer. If the transfer is partial, return to caller.
253 Partial transfer is not OK. */
254 if (payload_length != transfer_request -> ux_transfer_request_actual_length)
255 return(UX_TRANSFER_ERROR);
256
257 /* Adjust the total length to transfer. */
258 data_length -= payload_length;
259
260 /* Adjust the data pointer. */
261 data_pointer += payload_length;
262
263 }
264
265 /* If we have a ZLP condition, read from the device one more time with a zero packet. */
266 if (pima -> ux_host_class_pima_zlp_flag == UX_HOST_CLASS_PIMA_ZLP_IN)
267 {
268
269 /* Initialize the transfer_request. */
270 transfer_request -> ux_transfer_request_data_pointer = UX_NULL;
271 transfer_request -> ux_transfer_request_requested_length = 0;
272
273 /* Send request to HCD layer. */
274 status = _ux_host_stack_transfer_request(transfer_request);
275
276 /* If the transfer is successful, we need to wait for the transfer request to be completed. */
277 if (status == UX_SUCCESS)
278 {
279
280 /* Wait for the completion of the transfer request. */
281 status = _ux_host_semaphore_get(&transfer_request -> ux_transfer_request_semaphore, UX_MS_TO_TICK(UX_HOST_CLASS_PIMA_CLASS_TRANSFER_TIMEOUT));
282
283 /* If the semaphore did not succeed we probably have a time out. */
284 if (status != UX_SUCCESS)
285 {
286
287 /* All transfers pending need to abort. There may have been a partial transfer. */
288 _ux_host_stack_transfer_request_abort(transfer_request);
289
290 /* The endpoint was halted by a transfer error and needs to be reset. */
291 _ux_host_stack_endpoint_reset(pima -> ux_host_class_pima_bulk_in_endpoint);
292
293 /* The endpoint was halted by a transfer error and needs to be reset. */
294 _ux_host_stack_endpoint_reset(pima -> ux_host_class_pima_bulk_out_endpoint);
295
296 /* There was an error, return to the caller. */
297 return(status);
298 }
299
300 /* Reset the ZLP. */
301 pima -> ux_host_class_pima_zlp_flag = UX_HOST_CLASS_PIMA_ZLP_NONE;
302 }
303 }
304
305 /* We have finished receiving the data. */
306 return(UX_SUCCESS);
307 }
308
309
