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 /**   Generic Serial Host module class                                    */
18 /**                                                                       */
19 /**************************************************************************/
20 /**************************************************************************/
21 
22 
23 /**************************************************************************/
24 /*                                                                        */
25 /*  COMPONENT DEFINITION                                   RELEASE        */
26 /*                                                                        */
27 /*    ux_host_class_gser.h                                PORTABLE C      */
28 /*                                                           6.1.8        */
29 /*  AUTHOR                                                                */
30 /*                                                                        */
31 /*    Chaoqiong Xiao, Microsoft Corporation                               */
32 /*                                                                        */
33 /*  DESCRIPTION                                                           */
34 /*                                                                        */
35 /*    This file contains all the header and extern functions used by the  */
36 /*    USBX Generic Serial Class.                                          */
37 /*                                                                        */
38 /*  RELEASE HISTORY                                                       */
39 /*                                                                        */
40 /*    DATE              NAME                      DESCRIPTION             */
41 /*                                                                        */
42 /*  05-19-2020     Chaoqiong Xiao           Initial Version 6.0           */
43 /*  09-30-2020     Chaoqiong Xiao           Modified comment(s),          */
44 /*                                            used UX prefix to refer to  */
45 /*                                            TX symbols instead of using */
46 /*                                            them directly,              */
47 /*                                            resulting in version 6.1    */
48 /*  08-02-2021     Wen Wang                 Modified comment(s),          */
49 /*                                            added extern "C" keyword    */
50 /*                                            for compatibility with C++, */
51 /*                                            resulting in version 6.1.8  */
52 /*                                                                        */
53 /**************************************************************************/
54 
55 #ifndef UX_HOST_CLASS_GSER_H
56 #define UX_HOST_CLASS_GSER_H
57 
58 /* Determine if a C++ compiler is being used.  If so, ensure that standard
59    C is used to process the API information.  */
60 
61 #ifdef   __cplusplus
62 
63 /* Yes, C++ compiler is present.  Use standard C.  */
64 extern   "C" {
65 
66 #endif
67 
68 
69 /* Internal option: enable the basic USBX error checking. This define is typically used
70    while debugging application.  */
71 #if defined(UX_ENABLE_ERROR_CHECKING) && !defined(UX_HOST_CLASS_GSER_ENABLE_ERROR_CHECKING)
72 #define UX_HOST_CLASS_GSER_ENABLE_ERROR_CHECKING
73 #endif
74 
75 
76 /* Define Sierra Wireless AR Class constants.  */
77 
78 #define UX_HOST_CLASS_GSER_CLASS_TRANSFER_TIMEOUT               300000
79 #ifndef UX_HOST_CLASS_GSER_VENDOR_ID
80 #define UX_HOST_CLASS_GSER_VENDOR_ID                            0X05C6
81 #define UX_HOST_CLASS_GSER_PRODUCT_ID                           0X9002
82 #endif
83 
84 /* Define  serial interfaces equivalences.  */
85 #define UX_HOST_CLASS_GSER_INTERFACE_NUMBER                     3
86 
87 /* Define  packet equivalences.  */
88 #define UX_HOST_CLASS_GSER_PACKET_SIZE                          128
89 
90 /* Define Generic AR IOCTL functions.  */
91 
92 #define UX_HOST_CLASS_GSER_REQ_SEND_ENCAPSULATED_COMMAND        0x00
93 #define UX_HOST_CLASS_GSER_REQ_GET_ENCAPSULATED_COMMAND         0x01
94 #define UX_HOST_CLASS_GSER_REQ_SET_COMM_FEATURE                 0x02
95 #define UX_HOST_CLASS_GSER_REQ_GET_COMM_FEATURE                 0x03
96 #define UX_HOST_CLASS_GSER_REQ_CLEAR_COMM_FEATURE               0x04
97 #define UX_HOST_CLASS_GSER_REQ_SET_AUX_LINE_STATE               0x10
98 #define UX_HOST_CLASS_GSER_REQ_SET_HOOK_STATE                   0x11
99 #define UX_HOST_CLASS_GSER_REQ_PULSE_SETUP                      0x12
100 #define UX_HOST_CLASS_GSER_REQ_SEND_PULSE                       0x13
101 #define UX_HOST_CLASS_GSER_REQ_SET_PUSLE_TIME                   0x14
102 #define UX_HOST_CLASS_GSER_REQ_RING_AUX_JACK                    0x15
103 #define UX_HOST_CLASS_GSER_REQ_SET_LINE_CODING                  0x20
104 #define UX_HOST_CLASS_GSER_REQ_GET_LINE_CODING                  0x21
105 #define UX_HOST_CLASS_GSER_REQ_SET_LINE_STATE                   0x22
106 #define UX_HOST_CLASS_GSER_REQ_SEND_BREAK                       0x23
107 #define UX_HOST_CLASS_GSER_REQ_SET_RINGER_PARMS                 0x30
108 #define UX_HOST_CLASS_GSER_REQ_GET_RINGER_PARMS                 0x31
109 #define UX_HOST_CLASS_GSER_REQ_SET_OPERATION_PARMS              0x32
110 #define UX_HOST_CLASS_GSER_REQ_GET_OPERATION_PARMS              0x33
111 #define UX_HOST_CLASS_GSER_REQ_SET_LINE_PARMS                   0x34
112 #define UX_HOST_CLASS_GSER_REQ_GET_LINE_PARMS                   0x35
113 
114 /* Define CDC ACM line output control values.  */
115 
116 #define UX_HOST_CLASS_GSER_CTRL_DTR                             0x01
117 #define UX_HOST_CLASS_GSER_CTRL_RTS                             0x02
118 
119 /* Define CDC ACM line input control values.  */
120 
121 #define UX_HOST_CLASS_GSER_CTRL_DCD                             0x01
122 #define UX_HOST_CLASS_GSER_CTRL_DSR                             0x02
123 #define UX_HOST_CLASS_GSER_CTRL_BRK                             0x04
124 #define UX_HOST_CLASS_GSER_CTRL_RI                              0x08
125 
126 #define UX_HOST_CLASS_GSER_CTRL_FRAMING                         0x10
127 #define UX_HOST_CLASS_GSER_CTRL_PARITY                          0x20
128 #define UX_HOST_CLASS_GSER_CTRL_OVERRUN                         0x40
129 
130 /* Define CDC ACM default values.  */
131 
132 #define UX_HOST_CLASS_GSER_LINE_CODING_DEFAULT_RATE             9600
133 #define UX_HOST_CLASS_GSER_LINE_CODING_DEFAULT_DATA_BIT         8
134 
135 /* Define CDC ACM line coding definitions.  */
136 
137 #define UX_HOST_CLASS_GSER_LINE_CODING_STOP_BIT_0               0
138 #define UX_HOST_CLASS_GSER_LINE_CODING_STOP_BIT_15              1
139 #define UX_HOST_CLASS_GSER_LINE_CODING_STOP_BIT_2               2
140 
141 #define UX_HOST_CLASS_GSER_LINE_CODING_PARITY_NONE              0
142 #define UX_HOST_CLASS_GSER_LINE_CODING_PARITY_ODD               1
143 #define UX_HOST_CLASS_GSER_LINE_CODING_PARITY_EVEN              2
144 #define UX_HOST_CLASS_GSER_LINE_CODING_PARITY_MARK              3
145 #define UX_HOST_CLASS_GSER_LINE_CODING_PARITY_SPACE             4
146 
147 #define UX_HOST_CLASS_GSER_LINE_CODING_LENGTH                   7
148 #define UX_HOST_CLASS_GSER_LINE_CODING_RATE                     0
149 #define UX_HOST_CLASS_GSER_LINE_CODING_STOP_BIT                 4
150 #define UX_HOST_CLASS_GSER_LINE_CODING_PARITY                   5
151 #define UX_HOST_CLASS_GSER_LINE_CODING_DATA_BIT                 6
152 
153 /* Define CDC ACM line state definitions.  */
154 
155 #define UX_HOST_CLASS_GSER_LINE_STATE_STOP_BIT_0                0
156 #define UX_HOST_CLASS_GSER_LINE_CODING_STOP_BIT_15              1
157 
158 /* Define CDC ACM IOCTL Functions. */
159 
160 #define UX_HOST_CLASS_GSER_IOCTL_SET_LINE_CODING                0
161 #define UX_HOST_CLASS_GSER_IOCTL_GET_LINE_CODING                1
162 #define UX_HOST_CLASS_GSER_IOCTL_SET_LINE_STATE                 2
163 #define UX_HOST_CLASS_GSER_IOCTL_SEND_BREAK                     3
164 #define UX_HOST_CLASS_GSER_IOCTL_ABORT_IN_PIPE                  5
165 #define UX_HOST_CLASS_GSER_IOCTL_ABORT_OUT_PIPE                 6
166 #define UX_HOST_CLASS_GSER_IOCTL_NOTIFICATION_CALLBACK          7
167 #define UX_HOST_CLASS_GSER_IOCTL_GET_DEVICE_STATUS              8
168 
169 /* Define Reception States. */
170 
171 #define UX_HOST_CLASS_GSER_RECEPTION_STATE_STOPPED              0
172 #define UX_HOST_CLASS_GSER_RECEPTION_STATE_STARTED              1
173 #define UX_HOST_CLASS_GSER_RECEPTION_STATE_IN_TRANSFER          2
174 
175 /* Define the interface structures.  */
176 
177 typedef struct UX_HOST_CLASS_GSER_INTERFACE_STRUCT
178 {
179 
180     UX_INTERFACE                                *ux_host_class_gser_interface;
181     UX_ENDPOINT                                 *ux_host_class_gser_bulk_out_endpoint;
182     UX_ENDPOINT                                 *ux_host_class_gser_bulk_in_endpoint;
183     UX_SEMAPHORE                                ux_host_class_gser_semaphore;
184     struct UX_HOST_CLASS_GSER_RECEPTION_STRUCT  *ux_host_class_gser_reception;
185     ULONG                                       ux_host_class_gser_notification_count;
186 } UX_HOST_CLASS_GSER_INTERFACE;
187 
188 /* Define Generic Serial Class instance structure.  */
189 
190 typedef struct UX_HOST_CLASS_GSER_STRUCT
191 {
192 
193     struct UX_HOST_CLASS_GSER_STRUCT            *ux_host_class_gser_next_instance;
194     UX_HOST_CLASS                               *ux_host_class_gser_class;
195     UX_DEVICE                                   *ux_host_class_gser_device;
196     UINT                                        ux_host_class_gser_state;
197     struct UX_HOST_CLASS_GSER_INTERFACE_STRUCT  ux_host_class_gser_interface_array[UX_HOST_CLASS_GSER_INTERFACE_NUMBER];
198     ULONG                                       ux_host_class_gser_device_state;
199     VOID                                        (*ux_host_class_gser_device_status_change_callback)(struct UX_HOST_CLASS_GSER_STRUCT *gser,
200                                                                     ULONG  notification_type, ULONG notification_value);
201 } UX_HOST_CLASS_GSER;
202 
203 /* Define generic serial class reception structure. */
204 
205 
206 typedef struct UX_HOST_CLASS_GSER_RECEPTION_STRUCT
207 {
208 
209     ULONG           ux_host_class_gser_reception_interface_index;
210     ULONG           ux_host_class_gser_reception_state;
211     ULONG           ux_host_class_gser_reception_block_size;
212     UCHAR           *ux_host_class_gser_reception_data_buffer;
213     ULONG           ux_host_class_gser_reception_data_buffer_size;
214     UCHAR           *ux_host_class_gser_reception_data_head;
215     UCHAR           *ux_host_class_gser_reception_data_tail;
216     VOID            (*ux_host_class_gser_reception_callback)(struct UX_HOST_CLASS_GSER_STRUCT *gser,
217                                                                 UINT  status,
218                                                                 UCHAR *reception_buffer,
219                                                                 ULONG reception_size);
220 
221 } UX_HOST_CLASS_GSER_RECEPTION;
222 
223 
224 /* Define GSER Line Coding IOCTL structure.  */
225 
226 typedef struct UX_HOST_CLASS_GSER_LINE_CODING_STRUCT
227 {
228 
229     ULONG           ux_host_class_gser_line_coding_dter;
230     ULONG           ux_host_class_gser_line_coding_stop_bit;
231     ULONG           ux_host_class_gser_line_coding_parity;
232     ULONG           ux_host_class_gser_line_coding_data_bits;
233 
234 } UX_HOST_CLASS_GSER_LINE_CODING;
235 
236 /* Define GSER Line State IOCTL structure.  */
237 
238 typedef struct UX_HOST_CLASS_GSER_LINE_STATE_STRUCT
239 {
240 
241     ULONG           ux_host_class_gser_line_state_rts;
242     ULONG           ux_host_class_gser_line_state_dtr;
243 
244 } UX_HOST_CLASS_GSER_LINE_STATE;
245 
246 /* Define GSER Line break IOCTL structure.  */
247 
248 typedef struct UX_HOST_CLASS_GSER_LINE_BREAK_STRUCT
249 {
250 
251     ULONG           ux_host_class_gser_line_break;
252 
253 } UX_HOST_CLASS_GSER_LINE_BREAK;
254 
255 
256 /* Define  GSER Class function prototypes.  */
257 
258 UINT    _ux_host_class_gser_activate(UX_HOST_CLASS_COMMAND *command);
259 UINT    _ux_host_class_gser_configure(UX_HOST_CLASS_GSER *gser);
260 UINT    _ux_host_class_gser_deactivate(UX_HOST_CLASS_COMMAND *command);
261 UINT    _ux_host_class_gser_endpoints_get(UX_HOST_CLASS_GSER *gser);
262 UINT    _ux_host_class_gser_entry(UX_HOST_CLASS_COMMAND *command);
263 UINT    _ux_host_class_gser_read (UX_HOST_CLASS_GSER *gser, ULONG interface_index,UCHAR *data_pointer,
264                                     ULONG requested_length, ULONG *actual_length);
265 UINT    _ux_host_class_gser_write(UX_HOST_CLASS_GSER *gser, ULONG interface_index,UCHAR *data_pointer,
266                                     ULONG requested_length, ULONG *actual_length);
267 UINT    _ux_host_class_gser_command(UX_HOST_CLASS_GSER *gser, ULONG interface_index, ULONG command,
268                                     ULONG value, UCHAR *data_buffer, ULONG data_length);
269 UINT    _ux_host_class_gser_ioctl(UX_HOST_CLASS_GSER *gser, ULONG interface_index, ULONG ioctl_function,
270                                     VOID *parameter);
271 VOID    _ux_host_class_gser_reception_callback (UX_TRANSFER *transfer_request);
272 UINT    _ux_host_class_gser_reception_stop (UX_HOST_CLASS_GSER *gser,
273                                     UX_HOST_CLASS_GSER_RECEPTION *gser_reception);
274 UINT    _ux_host_class_gser_reception_start (UX_HOST_CLASS_GSER *gser,
275                                     UX_HOST_CLASS_GSER_RECEPTION *gser_reception);
276 
277 
278 UINT    _uxe_host_class_gser_read (UX_HOST_CLASS_GSER *gser, ULONG interface_index,UCHAR *data_pointer,
279                                     ULONG requested_length, ULONG *actual_length);
280 UINT    _uxe_host_class_gser_write(UX_HOST_CLASS_GSER *gser, ULONG interface_index,UCHAR *data_pointer,
281                                     ULONG requested_length, ULONG *actual_length);
282 UINT    _uxe_host_class_gser_command(UX_HOST_CLASS_GSER *gser, ULONG interface_index, ULONG command,
283                                     ULONG value, UCHAR *data_buffer, ULONG data_length);
284 UINT    _uxe_host_class_gser_ioctl(UX_HOST_CLASS_GSER *gser, ULONG interface_index, ULONG ioctl_function,
285                                     VOID *parameter);
286 UINT    _uxe_host_class_gser_reception_stop (UX_HOST_CLASS_GSER *gser,
287                                     UX_HOST_CLASS_GSER_RECEPTION *gser_reception);
288 UINT    _uxe_host_class_gser_reception_start (UX_HOST_CLASS_GSER *gser,
289                                     UX_HOST_CLASS_GSER_RECEPTION *gser_reception);
290 
291 
292 /* Define GSER Class API prototypes.  */
293 
294 #define ux_host_class_gser_entry                     _ux_host_class_gser_entry
295 
296 #if defined(UX_HOST_CLASS_GSER_ENABLE_ERROR_CHECKING)
297 
298 #define ux_host_class_gser_read                      _uxe_host_class_gser_read
299 #define ux_host_class_gser_write                     _uxe_host_class_gser_write
300 #define ux_host_class_gser_ioctl                     _uxe_host_class_gser_ioctl
301 #define ux_host_class_gser_reception_start           _uxe_host_class_gser_reception_start
302 #define ux_host_class_gser_reception_stop            _uxe_host_class_gser_reception_stop
303 
304 #else
305 
306 #define ux_host_class_gser_read                      _ux_host_class_gser_read
307 #define ux_host_class_gser_write                     _ux_host_class_gser_write
308 #define ux_host_class_gser_ioctl                     _ux_host_class_gser_ioctl
309 #define ux_host_class_gser_reception_start           _ux_host_class_gser_reception_start
310 #define ux_host_class_gser_reception_stop            _ux_host_class_gser_reception_stop
311 
312 #endif
313 
314 /* Determine if a C++ compiler is being used.  If so, complete the standard
315    C conditional started above.  */
316 #ifdef __cplusplus
317 }
318 #endif
319 
320 #endif
321