1#ifndef __CVMX_USBD_H__
2#define __CVMX_USBD_H__
3/***********************license start***************
4 * Copyright (c) 2003-2010  Cavium Inc. (support@cavium.com). All rights
5 * reserved.
6 *
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions are
10 * met:
11 *
12 *   * Redistributions of source code must retain the above copyright
13 *     notice, this list of conditions and the following disclaimer.
14 *
15 *   * Redistributions in binary form must reproduce the above
16 *     copyright notice, this list of conditions and the following
17 *     disclaimer in the documentation and/or other materials provided
18 *     with the distribution.
19
20 *   * Neither the name of Cavium Inc. nor the names of
21 *     its contributors may be used to endorse or promote products
22 *     derived from this software without specific prior written
23 *     permission.
24
25 * This Software, including technical data, may be subject to U.S. export  control
26 * laws, including the U.S. Export Administration Act and its  associated
27 * regulations, and may be subject to export or import  regulations in other
28 * countries.
29
30 * TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
31 * AND WITH ALL FAULTS AND CAVIUM INC. MAKES NO PROMISES, REPRESENTATIONS OR
32 * WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH RESPECT TO
33 * THE SOFTWARE, INCLUDING ITS CONDITION, ITS CONFORMITY TO ANY REPRESENTATION OR
34 * DESCRIPTION, OR THE EXISTENCE OF ANY LATENT OR PATENT DEFECTS, AND CAVIUM
35 * SPECIFICALLY DISCLAIMS ALL IMPLIED (IF ANY) WARRANTIES OF TITLE,
36 * MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, LACK OF
37 * VIRUSES, ACCURACY OR COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION OR
38 * CORRESPONDENCE TO DESCRIPTION. THE ENTIRE  RISK ARISING OUT OF USE OR
39 * PERFORMANCE OF THE SOFTWARE LIES WITH YOU.
40 ***********************license end**************************************/
41
42
43/**
44 * @file
45 *
46 * "cvmx-usbd.h" defines a set of low level USB functions to help developers
47 * create Octeon USB devices for various operating systems. These functions
48 * provide a generic API to the Octeon USB blocks, hiding the internal hardware
49 * specific operations.
50 *
51 * <hr>$Revision: 32636 $<hr>
52 */
53
54#ifdef	__cplusplus
55extern "C" {
56#endif
57
58typedef enum
59{
60    CVMX_USBD_TRANSFER_CONTROL = 0,
61    CVMX_USBD_TRANSFER_ISOCHRONOUS = 1,
62    CVMX_USBD_TRANSFER_BULK = 2,
63    CVMX_USBD_TRANSFER_INTERRUPT = 3,
64} cvmx_usbd_transfer_t;
65
66typedef enum
67{
68    CVMX_USBD_SPEED_HIGH = 0,
69    CVMX_USBD_SPEED_FULL = 1,
70    CVMX_USBD_SPEED_LOW = 2,
71} cvmx_usbd_speed_t;
72
73typedef enum
74{
75    CVMX_USBD_CALLBACK_SUSPEND,
76    CVMX_USBD_CALLBACK_RESET,
77    CVMX_USBD_CALLBACK_ENUM_COMPLETE,
78    CVMX_USBD_CALLBACK_DEVICE_SETUP,
79    CVMX_USBD_CALLBACK_IN_COMPLETE,
80    CVMX_USBD_CALLBACK_OUT_COMPLETE,
81    __CVMX_USBD_CALLBACK_END
82} cvmx_usbd_callback_t;
83
84typedef enum
85{
86    CVMX_USBD_INITIALIZE_FLAGS_CLOCK_XO_XI = 1<<0,       /**< The USB port uses a 12MHz crystal as clock source
87                                                            at USB_XO and USB_XI. */
88    CVMX_USBD_INITIALIZE_FLAGS_CLOCK_XO_GND = 1<<1,      /**< The USB port uses 12/24/48MHz 2.5V board clock
89                                                            source at USB_XO. USB_XI should be tied to GND.*/
90    CVMX_USBD_INITIALIZE_FLAGS_CLOCK_AUTO = 0,           /**< Automatically determine clock type based on function
91                                                             in cvmx-helper-board.c. */
92    CVMX_USBD_INITIALIZE_FLAGS_CLOCK_MHZ_MASK  = 3<<3,       /**< Mask for clock speed field */
93    CVMX_USBD_INITIALIZE_FLAGS_CLOCK_12MHZ = 1<<3,       /**< Speed of reference clock or crystal */
94    CVMX_USBD_INITIALIZE_FLAGS_CLOCK_24MHZ = 2<<3,       /**< Speed of reference clock */
95    CVMX_USBD_INITIALIZE_FLAGS_CLOCK_48MHZ = 3<<3,       /**< Speed of reference clock */
96    /* Bits 3-4 used to encode the clock frequency */
97    CVMX_USBD_INITIALIZE_FLAGS_DEBUG = 1<<16
98} cvmx_usbd_initialize_flags_t;
99
100typedef void (*cvmx_usbd_callback_func_t)(cvmx_usbd_callback_t reason, int endpoint_num, int bytes_transferred, void *user_data);
101
102typedef struct
103{
104    int init_flags;
105    int index;
106    cvmx_usbd_callback_func_t callback[__CVMX_USBD_CALLBACK_END];
107    void *callback_data[__CVMX_USBD_CALLBACK_END];
108    struct {
109        int buffer_length;
110    } endpoint[16];
111} cvmx_usbd_state_t;
112
113/**
114 * Initialize a USB port for use. This must be called before any
115 * other access to the Octeon USB port is made. The port starts
116 * off in the disabled state.
117 *
118 * @param usb    Pointer to an empty cvmx_usbd_state_t structure
119 *               that will be populated by the initialize call.
120 *               This structure is then passed to all other USB
121 *               functions.
122 * @param usb_port_number
123 *               Which Octeon USB port to initialize.
124 * @param flags  Flags to control hardware initialization. See
125 *               cvmx_usbd_initialize_flags_t for the flag
126 *               definitions. Some flags are mandatory.
127 *
128 * @return Zero or a negative on error.
129 */
130int cvmx_usbd_initialize(cvmx_usbd_state_t *usb, int usb_port_number,
131    cvmx_usbd_initialize_flags_t flags);
132
133/**
134 * Shutdown a USB port after a call to cvmx_usbd_initialize().
135 *
136 * @param usb    USB device state populated by
137 *               cvmx_usbd_initialize().
138 *
139 * @return Zero or a negative on error.
140 */
141int cvmx_usbd_shutdown(cvmx_usbd_state_t *usb);
142
143/**
144 * Enable a USB port. After this call succeeds, the USB port is
145 * online and servicing requests.
146 *
147 * @param usb  USB device state populated by
148 *               cvmx_usb_initialize().
149 *
150 * @return Zero or negative on error.
151 */
152int cvmx_usbd_enable(cvmx_usbd_state_t *usb);
153
154/**
155 * Disable a USB port. After this call the USB port will not
156 * generate data transfers and will not generate events.
157 *
158 * @param usb    USB device state populated by
159 *               cvmx_usb_initialize().
160 *
161 * @return Zero or negative on error.
162 */
163int cvmx_usbd_disable(cvmx_usbd_state_t *usb);
164
165/**
166 * Register a callback function to process USB events
167 *
168 * @param usb       USB device state populated by
169 *                  cvmx_usbd_initialize().
170 * @param reason    The reason this callback should be called
171 * @param func      Function to call
172 * @param user_data User supplied data for the callback
173 *
174 * @return Zero on succes, negative on failure
175 */
176int cvmx_usbd_register(cvmx_usbd_state_t *usb, cvmx_usbd_callback_t reason, cvmx_usbd_callback_func_t func, void *user_data);
177
178/**
179 * Poll the USB block for status and call all needed callback
180 * handlers. This function is meant to be called in the interrupt
181 * handler for the USB controller. It can also be called
182 * periodically in a loop for non-interrupt based operation.
183 *
184 * @param usb    USB device state populated by
185 *               cvmx_usbd_initialize().
186 *
187 * @return Zero or negative on error.
188 */
189int cvmx_usbd_poll(cvmx_usbd_state_t *usb);
190
191/**
192 * Get the current USB address
193 *
194 * @param usb    USB device state populated by
195 *               cvmx_usbd_initialize().
196 *
197 * @return The USB address
198 */
199int cvmx_usbd_get_address(cvmx_usbd_state_t *usb);
200
201/**
202 * Set the current USB address
203 *
204 * @param usb     USB device state populated by
205 *                cvmx_usbd_initialize().
206 * @param address Address to set
207 */
208void cvmx_usbd_set_address(cvmx_usbd_state_t *usb, int address);
209
210/**
211 * Get the current USB speed
212 *
213 * @param usb    USB device state populated by
214 *               cvmx_usbd_initialize().
215 *
216 * @return The USB speed
217 */
218cvmx_usbd_speed_t cvmx_usbd_get_speed(cvmx_usbd_state_t *usb);
219
220/**
221 * Set the current USB speed
222 *
223 * @param usb    USB device state populated by
224 *               cvmx_usbd_initialize().
225 * @param speed  The requested speed
226 */
227void cvmx_usbd_set_speed(cvmx_usbd_state_t *usb, cvmx_usbd_speed_t speed);
228
229/**
230 * Enable an endpoint to respond to an OUT transaction
231 *
232 * @param usb    USB device state populated by
233 *               cvmx_usbd_initialize().
234 * @param endpoint_num
235 *               Endpoint number to enable
236 * @param transfer_type
237 *               Transfer type for the endpoint
238 * @param max_packet_size
239 *               Maximum packet size for the endpoint
240 * @param buffer Buffer to receive the data
241 * @param buffer_length
242 *               Length of the buffer in bytes
243 *
244 * @return Zero on success, negative on failure
245 */
246int cvmx_usbd_out_endpoint_enable(cvmx_usbd_state_t *usb,
247    int endpoint_num, cvmx_usbd_transfer_t transfer_type,
248    int max_packet_size, uint64_t buffer, int buffer_length);
249
250/**
251 * Disable an OUT endpoint
252 *
253 * @param usb    USB device state populated by
254 *               cvmx_usbd_initialize().
255 * @param endpoint_num
256 *               Endpoint number to disable
257 *
258 * @return Zero on success, negative on failure
259 */
260int cvmx_usbd_out_endpoint_disable(cvmx_usbd_state_t *usb, int endpoint_num);
261
262/**
263 * Enable an endpoint to respond to an IN transaction
264 *
265 * @param usb    USB device state populated by
266 *               cvmx_usbd_initialize().
267 * @param endpoint_num
268 *               Endpoint number to enable
269 * @param transfer_type
270 *               Transfer type for the endpoint
271 * @param max_packet_size
272 *               Maximum packet size for the endpoint
273 * @param buffer Buffer to send
274 * @param buffer_length
275 *               Length of the buffer in bytes
276 *
277 * @return Zero on success, negative on failure
278 */
279int cvmx_usbd_in_endpoint_enable(cvmx_usbd_state_t *usb,
280    int endpoint_num, cvmx_usbd_transfer_t transfer_type,
281    int max_packet_size, uint64_t buffer, int buffer_length);
282
283/**
284 * Disable an IN endpoint
285 *
286 * @param usb    USB device state populated by
287 *               cvmx_usbd_initialize().
288 * @param endpoint_num
289 *               Endpoint number to disable
290 *
291 * @return Zero on success, negative on failure
292 */
293int cvmx_usbd_in_endpoint_disable(cvmx_usbd_state_t *usb, int endpoint_num);
294
295#ifdef	__cplusplus
296}
297#endif
298
299#endif /* __CVMX_USBD_H__ */
300
301