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_class_get PORTABLE C */
36 /* 6.3.0 */
37 /* AUTHOR */
38 /* */
39 /* Chaoqiong Xiao, Microsoft Corporation */
40 /* */
41 /* DESCRIPTION */
42 /* */
43 /* This function returns a pointer to the class container. A class */
44 /* needs to obtain its container from the USBX stack to search for */
45 /* instances when a driver or an application wants to open a device. */
46 /* */
47 /* Note: The C string of class_name must be NULL-terminated and the */
48 /* length of it (without the NULL-terminator itself) must be no larger */
49 /* than UX_MAX_CLASS_NAME_LENGTH. */
50 /* */
51 /* INPUT */
52 /* */
53 /* class_name Name of class */
54 /* host_class Class pointer */
55 /* */
56 /* OUTPUT */
57 /* */
58 /* Completion Status */
59 /* */
60 /* CALLS */
61 /* */
62 /* _ux_utility_string_length_check Check C string and return its */
63 /* length if null-terminated */
64 /* _ux_utility_memory_compare Compare memory blocks */
65 /* */
66 /* CALLED BY */
67 /* */
68 /* Application */
69 /* USBX Components */
70 /* */
71 /* RELEASE HISTORY */
72 /* */
73 /* DATE NAME DESCRIPTION */
74 /* */
75 /* 05-19-2020 Chaoqiong Xiao Initial Version 6.0 */
76 /* 09-30-2020 Chaoqiong Xiao Modified comment(s), */
77 /* optimized based on compile */
78 /* definitions, */
79 /* resulting in version 6.1 */
80 /* 10-31-2023 Chaoqiong Xiao Modified comment(s), */
81 /* resulting in version 6.3.0 */
82 /* */
83 /**************************************************************************/
_ux_host_stack_class_get(UCHAR * class_name,UX_HOST_CLASS ** host_class)84 UINT _ux_host_stack_class_get(UCHAR *class_name, UX_HOST_CLASS **host_class)
85 {
86
87 UX_HOST_CLASS *class_ptr;
88 #if !defined(UX_NAME_REFERENCED_BY_POINTER)
89 UINT status;
90 UINT class_name_length = 0;
91 #endif
92 #if UX_MAX_CLASS_DRIVER > 1
93 ULONG class_index;
94 #endif
95
96 #if !defined(UX_NAME_REFERENCED_BY_POINTER)
97 /* Get the length of the class name (exclude null-terminator). */
98 status = _ux_utility_string_length_check(class_name, &class_name_length, UX_MAX_CLASS_NAME_LENGTH);
99 if (status)
100 return(status);
101 #endif
102
103 /* Get first class. */
104 class_ptr = _ux_system_host -> ux_system_host_class_array;
105
106 #if UX_MAX_CLASS_DRIVER > 1
107 /* We need to parse the class driver table. */
108 for (class_index = 0; class_index < _ux_system_host -> ux_system_host_max_class; class_index++)
109 {
110 #endif
111
112 /* Check if this class is already being used. */
113 if (class_ptr -> ux_host_class_status == UX_USED)
114 {
115
116 /* We have found a container. Check if this is the one we need (compare including null-terminator). */
117 if (ux_utility_name_match(class_ptr -> ux_host_class_name, class_name, class_name_length + 1))
118 {
119
120 /* The class container was found. Update the pointer to the class container for the caller. */
121 *host_class = class_ptr;
122
123 /* Return success. */
124 return(UX_SUCCESS);
125 }
126 }
127
128 #if UX_MAX_CLASS_DRIVER > 1
129 /* Move to the next class. */
130 class_ptr++;
131 }
132 #endif
133
134 /* If trace is enabled, insert this event into the trace buffer. */
135 UX_TRACE_IN_LINE_INSERT(UX_TRACE_ERROR, UX_HOST_CLASS_UNKNOWN, class_name, 0, 0, UX_TRACE_ERRORS, 0, 0)
136
137 /* This class does not exist, return an error. */
138 return(UX_HOST_CLASS_UNKNOWN);
139 }
140
141
142 /**************************************************************************/
143 /* */
144 /* FUNCTION RELEASE */
145 /* */
146 /* _uxe_host_stack_class_get PORTABLE C */
147 /* 6.3.0 */
148 /* AUTHOR */
149 /* */
150 /* Chaoqiong Xiao, Microsoft Corporation */
151 /* */
152 /* DESCRIPTION */
153 /* */
154 /* This function checks errors in host stack class get function call. */
155 /* */
156 /* INPUT */
157 /* */
158 /* class_name Name of class */
159 /* host_class Class pointer */
160 /* */
161 /* OUTPUT */
162 /* */
163 /* None */
164 /* */
165 /* CALLS */
166 /* */
167 /* _ux_host_stack_class_get Host stack class get */
168 /* */
169 /* CALLED BY */
170 /* */
171 /* Application */
172 /* */
173 /* RELEASE HISTORY */
174 /* */
175 /* DATE NAME DESCRIPTION */
176 /* */
177 /* 10-31-2023 Chaoqiong Xiao Initial Version 6.3.0 */
178 /* */
179 /**************************************************************************/
_uxe_host_stack_class_get(UCHAR * class_name,UX_HOST_CLASS ** host_class)180 UINT _uxe_host_stack_class_get(UCHAR *class_name, UX_HOST_CLASS **host_class)
181 {
182
183 /* Sanity checks. */
184 if ((class_name == UX_NULL) || (host_class == UX_NULL))
185 return(UX_INVALID_PARAMETER);
186
187 /* Invoke class get function. */
188 return(_ux_host_stack_class_get(class_name, host_class));
189 }
190
