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