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 /** USBX Component */
14 /** */
15 /** Device HID Class */
16 /** */
17 /**************************************************************************/
18 /**************************************************************************/
19
20 #define UX_SOURCE_CODE
21
22
23 /* Include necessary system files. */
24
25 #include "ux_api.h"
26 #include "ux_device_class_hid.h"
27 #include "ux_device_stack.h"
28
29
30 /**************************************************************************/
31 /* */
32 /* FUNCTION RELEASE */
33 /* */
34 /* _ux_device_class_hid_activate PORTABLE C */
35 /* 6.3.0 */
36 /* AUTHOR */
37 /* */
38 /* Chaoqiong Xiao, Microsoft Corporation */
39 /* */
40 /* DESCRIPTION */
41 /* */
42 /* This function activates an instance of a HID device. */
43 /* */
44 /* INPUT */
45 /* */
46 /* command Pointer to hid command */
47 /* */
48 /* OUTPUT */
49 /* */
50 /* Completion Status */
51 /* */
52 /* CALLS */
53 /* */
54 /* _ux_device_thread_resume Resume thread */
55 /* */
56 /* CALLED BY */
57 /* */
58 /* USBX Source Code */
59 /* */
60 /* RELEASE HISTORY */
61 /* */
62 /* DATE NAME DESCRIPTION */
63 /* */
64 /* 05-19-2020 Chaoqiong Xiao Initial Version 6.0 */
65 /* 09-30-2020 Chaoqiong Xiao Modified comment(s), */
66 /* resulting in version 6.1 */
67 /* 12-31-2020 Chaoqiong Xiao Modified comment(s), */
68 /* added Get/Set Protocol */
69 /* request support, */
70 /* resulting in version 6.1.3 */
71 /* 10-15-2021 Chaoqiong Xiao Modified comment(s), */
72 /* added packet size assert, */
73 /* resulting in version 6.1.9 */
74 /* 01-31-2022 Chaoqiong Xiao Modified comment(s), */
75 /* added standalone support, */
76 /* added interrupt OUT support,*/
77 /* added packet size assert, */
78 /* resulting in version 6.1.10 */
79 /* 07-29-2022 Chaoqiong Xiao Modified comment(s), */
80 /* added standalone receiver, */
81 /* fixed standalone tx length, */
82 /* fixed standalone EP IN init,*/
83 /* fixed parameter/variable */
84 /* names conflict C++ keyword, */
85 /* resulting in version 6.1.12 */
86 /* 10-31-2023 Chaoqiong Xiao Modified comment(s), */
87 /* added zero copy support, */
88 /* added a new mode to manage */
89 /* endpoint buffer in classes, */
90 /* resulting in version 6.3.0 */
91 /* */
92 /**************************************************************************/
_ux_device_class_hid_activate(UX_SLAVE_CLASS_COMMAND * command)93 UINT _ux_device_class_hid_activate(UX_SLAVE_CLASS_COMMAND *command)
94 {
95
96 UX_SLAVE_INTERFACE *interface_ptr;
97 UX_SLAVE_CLASS *class_ptr;
98 UX_SLAVE_CLASS_HID *hid;
99 UX_SLAVE_ENDPOINT *endpoint_interrupt;
100 UX_SLAVE_ENDPOINT *endpoint_in = UX_NULL;
101 #if defined(UX_DEVICE_CLASS_HID_INTERRUPT_OUT_SUPPORT)
102 UX_SLAVE_ENDPOINT *endpoint_out = UX_NULL;
103 UCHAR *pos;
104 #endif
105
106 /* Get the class container. */
107 class_ptr = command -> ux_slave_class_command_class_ptr;
108
109 /* Get the class instance in the container. */
110 hid = (UX_SLAVE_CLASS_HID *) class_ptr -> ux_slave_class_instance;
111
112 /* Get the interface that owns this instance. */
113 interface_ptr = (UX_SLAVE_INTERFACE *) command -> ux_slave_class_command_interface;
114
115 /* Store the class instance into the interface. */
116 interface_ptr -> ux_slave_interface_class_instance = (VOID *)hid;
117
118 /* Now the opposite, store the interface in the class instance. */
119 hid -> ux_slave_class_hid_interface = interface_ptr;
120
121 /* Locate the endpoints. */
122 endpoint_interrupt = interface_ptr -> ux_slave_interface_first_endpoint;
123
124 /* Check if interrupt IN endpoint exists. */
125 while (endpoint_interrupt != UX_NULL)
126 {
127 if ((endpoint_interrupt -> ux_slave_endpoint_descriptor.bmAttributes &
128 UX_MASK_ENDPOINT_TYPE) == UX_INTERRUPT_ENDPOINT)
129 {
130 if ((endpoint_interrupt -> ux_slave_endpoint_descriptor.bEndpointAddress &
131 UX_ENDPOINT_DIRECTION) == UX_ENDPOINT_IN)
132 {
133
134 /* It's interrupt IN endpoint we need. */
135 endpoint_in = endpoint_interrupt;
136
137 #if defined(UX_DEVICE_CLASS_HID_OWN_ENDPOINT_BUFFER)
138
139 /* Set endpoint buffer owner to class instance. */
140 endpoint_in -> ux_slave_endpoint_transfer_request.
141 ux_slave_transfer_request_data_pointer =
142 UX_DEVICE_CLASS_HID_INTERRUPTIN_BUFFER(hid);
143 #endif
144
145 #if defined(UX_DEVICE_CLASS_HID_INTERRUPT_OUT_SUPPORT)
146 if (endpoint_out != UX_NULL)
147 #endif
148 break;
149 }
150 #if defined(UX_DEVICE_CLASS_HID_INTERRUPT_OUT_SUPPORT)
151 else
152 {
153
154 /* It's optional interrupt OUT endpoint. */
155 endpoint_out = endpoint_interrupt;
156
157 #if defined(UX_DEVICE_CLASS_HID_OWN_ENDPOINT_BUFFER)
158
159 /* Set endpoint buffer owner to class instance. */
160 endpoint_out -> ux_slave_endpoint_transfer_request.
161 ux_slave_transfer_request_data_pointer =
162 UX_DEVICE_CLASS_HID_INTERRUPTOUT_BUFFER(hid);
163 #endif
164
165 if (endpoint_in != UX_NULL)
166 break;
167 }
168 #endif
169 }
170
171 /* Try next endpoint. */
172 endpoint_interrupt = endpoint_interrupt -> ux_slave_endpoint_next_endpoint;
173 }
174
175 /* Check if we found right endpoint. */
176 if (endpoint_in == UX_NULL)
177 return (UX_ERROR);
178
179 /* Validate event buffer size (fits largest transfer payload size). */
180 UX_ASSERT(UX_DEVICE_CLASS_HID_EVENT_BUFFER_LENGTH >=
181 endpoint_in -> ux_slave_endpoint_transfer_request.
182 ux_slave_transfer_request_transfer_length);
183
184 /* Default HID protocol is report protocol. */
185 hid -> ux_device_class_hid_protocol = UX_DEVICE_CLASS_HID_PROTOCOL_REPORT;
186
187 /* Save the endpoints in the hid instance. */
188 hid -> ux_device_class_hid_interrupt_endpoint = endpoint_in;
189
190 #if defined(UX_DEVICE_CLASS_HID_INTERRUPT_OUT_SUPPORT)
191
192 /* Save endpoint OUT. */
193 hid -> ux_device_class_hid_read_endpoint = endpoint_out;
194
195 /* Resume receiver thread/task (if present). */
196 if (hid -> ux_device_class_hid_receiver && endpoint_out)
197 {
198
199 /* Reset events. */
200 hid -> ux_device_class_hid_receiver -> ux_device_class_hid_receiver_event_save_pos =
201 hid -> ux_device_class_hid_receiver -> ux_device_class_hid_receiver_events;
202 hid -> ux_device_class_hid_receiver -> ux_device_class_hid_receiver_event_read_pos =
203 hid -> ux_device_class_hid_receiver -> ux_device_class_hid_receiver_events;
204 for (pos = (UCHAR*)hid -> ux_device_class_hid_receiver -> ux_device_class_hid_receiver_events;
205 pos < (UCHAR*)hid -> ux_device_class_hid_receiver -> ux_device_class_hid_receiver_events_end;
206 pos += UX_DEVICE_CLASS_HID_RECEIVED_QUEUE_ITEM_SIZE(hid -> ux_device_class_hid_receiver))
207 {
208 ((UX_DEVICE_CLASS_HID_RECEIVED_EVENT*)pos) -> ux_device_class_hid_received_event_length = 0;
209 }
210
211 #if !defined(UX_DEVICE_STANDALONE)
212
213 /* Resume thread. */
214 _ux_utility_thread_resume(&hid -> ux_device_class_hid_receiver -> ux_device_class_hid_receiver_thread);
215 #else
216
217 /* Setup read state for receiver. */
218 hid -> ux_device_class_hid_read_state = UX_DEVICE_CLASS_HID_RECEIVER_START;
219 #endif
220 }
221 #endif
222
223 #if !defined(UX_DEVICE_STANDALONE)
224
225 /* Resume thread. */
226 _ux_device_thread_resume(&class_ptr -> ux_slave_class_thread);
227 #else
228
229 /* Reset event buffered for background transfer. */
230 _ux_utility_memory_set((VOID *)&hid -> ux_device_class_hid_event, 0,
231 sizeof(UX_DEVICE_CLASS_HID_EVENT)); /* Use case of memset is verified. */
232 hid -> ux_device_class_hid_event.ux_device_class_hid_event_length =
233 endpoint_in -> ux_slave_endpoint_transfer_request.
234 ux_slave_transfer_request_transfer_length;
235
236 /* Reset event sending state. */
237 hid -> ux_device_class_hid_event_state = UX_STATE_RESET;
238 #endif
239
240
241 /* If there is a activate function call it. */
242 if (hid -> ux_slave_class_hid_instance_activate != UX_NULL)
243 {
244
245 /* Invoke the application. */
246 hid -> ux_slave_class_hid_instance_activate(hid);
247 }
248
249 /* If trace is enabled, insert this event into the trace buffer. */
250 UX_TRACE_IN_LINE_INSERT(UX_TRACE_DEVICE_CLASS_HID_ACTIVATE, hid, 0, 0, 0, UX_TRACE_DEVICE_CLASS_EVENTS, 0, 0)
251
252 /* If trace is enabled, register this object. */
253 UX_TRACE_OBJECT_REGISTER(UX_TRACE_DEVICE_OBJECT_TYPE_INTERFACE, hid, 0, 0, 0)
254
255 /* Return completion status. */
256 return(UX_SUCCESS);
257 }
258
