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 Simulator Controller Driver                                    */
18 /**                                                                       */
19 /**************************************************************************/
20 /**************************************************************************/
21 
22 
23 /**************************************************************************/
24 /*                                                                        */
25 /*  COMPONENT DEFINITION                                   RELEASE        */
26 /*                                                                        */
27 /*    ux_hcd_sim_host.h                                   PORTABLE C      */
28 /*                                                           6.1.10       */
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 host simulator. It is designed to work ONLY with the USBX      */
37 /*    device (slave) simulator.                                           */
38 /*                                                                        */
39 /*  RELEASE HISTORY                                                       */
40 /*                                                                        */
41 /*    DATE              NAME                      DESCRIPTION             */
42 /*                                                                        */
43 /*  05-19-2020     Chaoqiong Xiao           Initial Version 6.0           */
44 /*  09-30-2020     Chaoqiong Xiao           Modified comment(s),          */
45 /*                                            added controller disable,   */
46 /*                                            used UX prefix to refer to  */
47 /*                                            TX symbols instead of using */
48 /*                                            them directly,              */
49 /*                                            resulting in version 6.1    */
50 /*  11-09-2020     Chaoqiong Xiao           Modified comment(s),          */
51 /*                                            added HCD uninitialize,     */
52 /*                                            resulting in version 6.1.2  */
53 /*  04-02-2021     Chaoqiong Xiao           Modified comment(s),          */
54 /*                                            added port status variable, */
55 /*                                            resulting in version 6.1.6  */
56 /*  08-02-2021     Chaoqiong Xiao           Modified comment(s),          */
57 /*                                            added extern "C" keyword    */
58 /*                                            for compatibility with C++, */
59 /*                                            resulting in version 6.1.8  */
60 /*  01-31-2022     Chaoqiong Xiao           Modified comment(s),          */
61 /*                                            added standalone support,   */
62 /*                                            resulting in version 6.1.10 */
63 /*                                                                        */
64 /**************************************************************************/
65 
66 #ifndef UX_HCD_SIM_HOST_H
67 #define UX_HCD_SIM_HOST_H
68 
69 /* Determine if a C++ compiler is being used.  If so, ensure that standard
70    C is used to process the API information.  */
71 
72 #ifdef   __cplusplus
73 
74 /* Yes, C++ compiler is present.  Use standard C.  */
75 extern   "C" {
76 
77 #endif
78 
79 
80 /* Define simulator host generic definitions.  */
81 
82 #define UX_HCD_SIM_HOST_CONTROLLER                              99
83 #define UX_HCD_SIM_HOST_MAX_PAYLOAD                             4096
84 #define UX_HCD_SIM_HOST_FRAME_DELAY                             4
85 #define UX_HCD_SIM_HOST_PERIODIC_ENTRY_NB                       32
86 #define UX_HCD_SIM_HOST_PERIODIC_ENTRY_MASK                     0x1f
87 #define UX_HCD_SIM_HOST_AVAILABLE_BANDWIDTH                     6000
88 
89 
90 
91 /* Define simulator host completion code errors.  */
92 
93 #define UX_HCD_SIM_HOST_NO_ERROR                                0x00
94 #define UX_HCD_SIM_HOST_ERROR_CRC                               0x01
95 #define UX_HCD_SIM_HOST_ERROR_BIT_STUFFING                      0x02
96 #define UX_HCD_SIM_HOST_ERROR_DATA_TOGGLE                       0x03
97 #define UX_HCD_SIM_HOST_ERROR_STALL                             0x04
98 #define UX_HCD_SIM_HOST_ERROR_DEVICE_NOT_RESPONDING             0x05
99 #define UX_HCD_SIM_HOST_ERROR_PID_FAILURE                       0x06
100 #define UX_HCD_SIM_HOST_ERROR_PID_UNEXPECTED                    0x07
101 #define UX_HCD_SIM_HOST_ERROR_DATA_OVERRRUN                     0x08
102 #define UX_HCD_SIM_HOST_ERROR_DATA_UNDERRUN                     0x09
103 #define UX_HCD_SIM_HOST_ERROR_BUFFER_OVERRRUN                   0x0c
104 #define UX_HCD_SIM_HOST_ERROR_BUFFER_UNDERRUN                   0x0d
105 #define UX_HCD_SIM_HOST_NOT_ACCESSED                            0x0e
106 #define UX_HCD_SIM_HOST_NAK                                     0x0f
107 
108 
109 /* Define simulator host structure.  */
110 
111 typedef struct UX_HCD_SIM_HOST_STRUCT
112 {
113 
114     struct UX_HCD_STRUCT
115                     *ux_hcd_sim_host_hcd_owner;
116     ULONG           ux_hcd_sim_host_hcor;
117     UINT            ux_hcd_sim_host_nb_root_hubs;
118     ULONG           ux_hcd_sim_host_port_status[1];
119     struct UX_HCD_SIM_HOST_ED_STRUCT
120                     *ux_hcd_sim_host_ed_list;
121     struct UX_HCD_SIM_HOST_TD_STRUCT
122                     *ux_hcd_sim_host_td_list;
123     struct UX_HCD_SIM_HOST_ISO_TD_STRUCT
124                     *ux_hcd_sim_host_iso_td_list;
125     struct UX_HCD_SIM_HOST_ED_STRUCT
126                     *ux_hcd_sim_host_asynch_head_ed;
127     struct UX_HCD_SIM_HOST_ED_STRUCT
128                     *ux_hcd_sim_host_asynch_current_ed;
129     struct UX_HCD_SIM_HOST_ED_STRUCT
130                     *ux_hcd_sim_host_iso_head_ed;
131     struct UX_HCD_SIM_HOST_ED_STRUCT
132                     *ux_hcd_sim_host_interrupt_ed_list[32];
133     UINT            ux_hcd_sim_host_queue_empty;
134     UINT            ux_hcd_sim_host_periodic_scheduler_active;
135     UINT            ux_hcd_sim_host_interruptible;
136     ULONG           ux_hcd_sim_host_interrupt_count;
137 #if !defined(UX_HOST_STANDALONE)
138     UX_TIMER        ux_hcd_sim_host_timer;
139 #endif
140 } UX_HCD_SIM_HOST;
141 
142 
143 /* Define simulator host ED structure.  */
144 
145 typedef struct UX_HCD_SIM_HOST_ED_STRUCT
146 {
147 
148     struct UX_HCD_SIM_HOST_TD_STRUCT
149                     *ux_sim_host_ed_tail_td;
150     struct UX_HCD_SIM_HOST_TD_STRUCT
151                     *ux_sim_host_ed_head_td;
152     struct UX_HCD_SIM_HOST_ED_STRUCT
153                     *ux_sim_host_ed_next_ed;
154     struct UX_HCD_SIM_HOST_ED_STRUCT
155                     *ux_sim_host_ed_previous_ed;
156     ULONG           ux_sim_host_ed_status;
157     struct UX_ENDPOINT_STRUCT
158                     *ux_sim_host_ed_endpoint;
159     ULONG           ux_sim_host_ed_toggle;
160     ULONG           ux_sim_host_ed_frame;
161 } UX_HCD_SIM_HOST_ED;
162 
163 
164 /* Define simulator host ED bitmap.  */
165 
166 #define UX_HCD_SIM_HOST_ED_STATIC                               0x80000000u
167 #define UX_HCD_SIM_HOST_ED_SKIP                                 0x40000000u
168 #define UX_HCD_SIM_HOST_ED_TRANSFER                             0x00100000u
169 
170 
171 /* Define simulator host TD structure.  */
172 
173 typedef struct UX_HCD_SIM_HOST_TD_STRUCT
174 {
175 
176     UCHAR *         ux_sim_host_td_buffer;
177     ULONG           ux_sim_host_td_length;
178     struct UX_HCD_SIM_HOST_TD_STRUCT
179                     *ux_sim_host_td_next_td;
180     struct UX_TRANSFER_STRUCT
181                     *ux_sim_host_td_transfer_request;
182     struct UX_HCD_SIM_HOST_TD_STRUCT
183                     *ux_sim_host_td_next_td_transfer_request;
184     struct UX_HCD_SIM_HOST_ED_STRUCT
185                     *ux_sim_host_td_ed;
186     ULONG           ux_sim_host_td_actual_length;
187     ULONG           ux_sim_host_td_status;
188     ULONG           ux_sim_host_td_direction;
189     ULONG           ux_sim_host_td_toggle;
190 } UX_HCD_SIM_HOST_TD;
191 
192 
193 /* Define simulator host TD bitmap.  */
194 
195 #define UX_HCD_SIM_HOST_TD_SETUP_PHASE                          0x00010000
196 #define UX_HCD_SIM_HOST_TD_DATA_PHASE                           0x00020000
197 #define UX_HCD_SIM_HOST_TD_STATUS_PHASE                         0x00040000
198 #define UX_HCD_SIM_HOST_TD_OUT                                  0x00000800
199 #define UX_HCD_SIM_HOST_TD_IN                                   0x00001000
200 #define UX_HCD_SIM_HOST_TD_ACK_PENDING                          0x00002000
201 #define UX_HCD_SIM_HOST_TD_TOGGLE_FROM_ED                       0x80000000
202 
203 
204 /* Define simulator host ISOCHRONOUS TD structure.  */
205 
206 typedef struct UX_HCD_SIM_HOST_ISO_TD_STRUCT
207 {
208 
209     UCHAR *         ux_sim_host_iso_td_buffer;
210     ULONG           ux_sim_host_iso_td_length;
211     struct UX_HCD_SIM_HOST_ISO_TD_STRUCT
212                     *ux_sim_host_iso_td_next_td;
213     struct UX_TRANSFER_STRUCT
214                     *ux_sim_host_iso_td_transfer_request;
215     struct UX_HCD_SIM_HOST_ISO_TD_STRUCT
216                     *ux_sim_host_iso_td_next_td_transfer_request;
217     struct UX_HCD_SIM_HOST_ED_STRUCT
218                     *ux_sim_host_iso_td_ed;
219     ULONG           ux_sim_host_iso_td_actual_length;
220     ULONG           ux_sim_host_iso_td_status;
221     ULONG           ux_sim_host_iso_td_direction;
222 } UX_HCD_SIM_HOST_ISO_TD;
223 
224 
225 /* Define simulator host function prototypes.  */
226 
227 VOID    _ux_hcd_sim_host_asynch_queue_process(UX_HCD_SIM_HOST *hcd_sim_host);
228 VOID    _ux_hcd_sim_host_asynch_schedule(UX_HCD_SIM_HOST *hcd_sim_host);
229 UINT    _ux_hcd_sim_host_asynchronous_endpoint_create(UX_HCD_SIM_HOST *hcd_sim_host, UX_ENDPOINT *endpoint);
230 UINT    _ux_hcd_sim_host_asynchronous_endpoint_destroy(UX_HCD_SIM_HOST *hcd_sim_host, UX_ENDPOINT *endpoint);
231 UX_HCD_SIM_HOST_ED
232         *_ux_hcd_sim_host_ed_obtain(UX_HCD_SIM_HOST *hcd_sim_host);
233 VOID    _ux_hcd_sim_host_ed_td_clean(UX_HCD_SIM_HOST_ED *ed);
234 UINT    _ux_hcd_sim_host_endpoint_reset(UX_HCD_SIM_HOST *hcd_sim_host, UX_ENDPOINT *endpoint);
235 UINT    _ux_hcd_sim_host_entry(UX_HCD *hcd, UINT function, VOID *parameter);
236 UINT    _ux_hcd_sim_host_frame_number_get(UX_HCD_SIM_HOST *hcd_sim_host, ULONG *frame_number);
237 VOID    _ux_hcd_sim_host_frame_number_set(UX_HCD_SIM_HOST *hcd_sim_host, ULONG frame_number);
238 UINT    _ux_hcd_sim_host_initialize(UX_HCD *hcd);
239 UINT    _ux_hcd_sim_host_uninitialize(UX_HCD_SIM_HOST *hcd);
240 UINT    _ux_hcd_sim_host_controller_disable(UX_HCD_SIM_HOST *hcd);
241 UINT    _ux_hcd_sim_host_interrupt_endpoint_create(UX_HCD_SIM_HOST *hcd_sim_host, UX_ENDPOINT *endpoint);
242 VOID    _ux_hcd_sim_host_iso_queue_process(UX_HCD_SIM_HOST *hcd_sim_host);
243 VOID    _ux_hcd_sim_host_iso_schedule(UX_HCD_SIM_HOST *hcd_sim_host);
244 UINT    _ux_hcd_sim_host_isochronous_endpoint_create(UX_HCD_SIM_HOST *hcd_sim_host, UX_ENDPOINT *endpoint);
245 UX_HCD_SIM_HOST_ISO_TD
246         *_ux_hcd_sim_host_isochronous_td_obtain(UX_HCD_SIM_HOST *hcd_sim_host);
247 UX_HCD_SIM_HOST_ED
248         *_ux_hcd_sim_host_least_traffic_list_get(UX_HCD_SIM_HOST *hcd_sim_host);
249 UINT    _ux_hcd_sim_host_periodic_endpoint_destroy(UX_HCD_SIM_HOST *hcd_sim_host, UX_ENDPOINT *endpoint);
250 VOID    _ux_hcd_sim_host_periodic_schedule(UX_HCD_SIM_HOST *hcd_sim_host);
251 UINT    _ux_hcd_sim_host_periodic_tree_create(UX_HCD_SIM_HOST *hcd_sim_host);
252 ULONG   _ux_hcd_sim_host_port_status_get(UX_HCD_SIM_HOST *hcd_sim_host, ULONG port_index);
253 UX_HCD_SIM_HOST_TD
254         *_ux_hcd_sim_host_regular_td_obtain(UX_HCD_SIM_HOST *hcd_sim_host);
255 UINT    _ux_hcd_sim_host_request_bulk_transfer(UX_HCD_SIM_HOST *hcd_sim_host, UX_TRANSFER *transfer_request);
256 UINT    _ux_hcd_sim_host_request_control_transfer(UX_HCD_SIM_HOST *hcd_sim_host, UX_TRANSFER *transfer_request);
257 UINT    _ux_hcd_sim_host_request_interrupt_transfer(UX_HCD_SIM_HOST *hcd_sim_host, UX_TRANSFER *transfer_request);
258 UINT    _ux_hcd_sim_host_request_isochronous_transfer(UX_HCD_SIM_HOST *hcd_sim_host, UX_TRANSFER *transfer_request);
259 UINT    _ux_hcd_sim_host_request_transfer(UX_HCD_SIM_HOST *hcd_sim_host, UX_TRANSFER *transfer_request);
260 VOID    _ux_hcd_sim_host_timer_function(ULONG hcd_sim_host_addr);
261 UINT    _ux_hcd_sim_host_transaction_schedule(UX_HCD_SIM_HOST *hcd_sim_host, UX_HCD_SIM_HOST_ED *ed);
262 UINT    _ux_hcd_sim_host_transfer_abort(UX_HCD_SIM_HOST *hcd_sim_host, UX_TRANSFER *transfer_request);
263 UINT    _ux_hcd_sim_host_port_reset(UX_HCD_SIM_HOST *hcd_sim_host, ULONG port_index);
264 
265 UINT    _ux_hcd_sim_host_transfer_run(UX_HCD_SIM_HOST *hcd_sim_host, UX_TRANSFER *transfer_request);
266 
267 /* Define Device Simulator Class API prototypes.  */
268 
269 #define ux_hcd_sim_host_initialize                 _ux_hcd_sim_host_initialize
270 /* Determine if a C++ compiler is being used.  If so, complete the standard
271    C conditional started above.  */
272 #ifdef __cplusplus
273 }
274 #endif
275 
276 #endif
277 
278