usb: Add USB device controller header file
Add USB device controller header file containing the USB device controller APIs. All device controller drivers should implement the APIs described in this file. Change-Id: I14443a5286bbc2faddbd6420ce1668acb183cd2e Signed-off-by: Adrian Bradianu <adrian.bradianu@windriver.com> Signed-off-by: Daniel Leung <daniel.leung@intel.com> Signed-off-by: Jesus Sanchez-Palencia <jesus.sanchez-palencia@intel.com>
This commit is contained in:
Adrian Bradianu
Inaky Perez-Gonzalez
parent
bcca0dcbbd
commit
fca8eb8608
1 changed files with 299 additions and 0 deletions
299
include/drivers/usb/usb_dc.h
Normal file
299
include/drivers/usb/usb_dc.h
Normal file
|
|
@ -0,0 +1,299 @@
|
|||
/* usb_dc.h - USB device controller driver interface */
|
||||
|
||||
/*
|
||||
* Copyright (c) 2016 Intel Corporation.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @file
|
||||
* @brief USB device controller APIs
|
||||
*
|
||||
* This file contains the USB device controller APIs. All device controller
|
||||
* drivers should implement the APIs described in this file.
|
||||
*/
|
||||
|
||||
#ifndef __USB_DC_H__
|
||||
#define __USB_DC_H__
|
||||
|
||||
#include <device.h>
|
||||
|
||||
/**
|
||||
* USB endpoint direction and number.
|
||||
*/
|
||||
|
||||
#define USB_EP_DIR_MASK 0x80
|
||||
#define USB_EP_DIR_IN 0x80
|
||||
#define USB_EP_DIR_OUT 0x00
|
||||
|
||||
/**
|
||||
* USB Driver Status Codes
|
||||
*/
|
||||
enum usb_dc_status_code {
|
||||
USB_DC_ERROR, /* USB error reported by the controller */
|
||||
USB_DC_RESET, /* USB reset */
|
||||
/* USB connection established, hardware enumeration is completed */
|
||||
USB_DC_CONNECTED,
|
||||
USB_DC_CONFIGURED, /* USB configuration done */
|
||||
USB_DC_DISCONNECTED, /* USB connection lost */
|
||||
USB_DC_SUSPEND, /* USB connection suspended by the HOST */
|
||||
USB_DC_RESUME, /* USB connection resumed by the HOST */
|
||||
USB_DC_UNKNOWN /* Initial USB connection status */
|
||||
};
|
||||
|
||||
/**
|
||||
* USB Endpoint Callback Status Codes
|
||||
*/
|
||||
enum usb_dc_ep_cb_status_code {
|
||||
USB_DC_EP_SETUP, /* SETUP received */
|
||||
/* Out transaction on this EP, data is available for read */
|
||||
USB_DC_EP_DATA_OUT,
|
||||
USB_DC_EP_DATA_IN, /* In transaction done on this EP */
|
||||
};
|
||||
|
||||
/**
|
||||
* USB Endpoint type
|
||||
*/
|
||||
enum usb_dc_ep_type {
|
||||
USB_DC_EP_CONTROL = 0, /* Control type endpoint */
|
||||
USB_DC_EP_ISOCHRONOUS, /* Isochronous type endpoint */
|
||||
USB_DC_EP_BULK, /* Bulk type endpoint */
|
||||
USB_DC_EP_INTERRUPT /* Interrupt type endpoint */
|
||||
};
|
||||
|
||||
/**
|
||||
* USB Endpoint Configuration.
|
||||
*/
|
||||
struct usb_dc_ep_cfg_data {
|
||||
/** The number associated with the EP in the device
|
||||
* configuration structure
|
||||
* IN EP = 0x80 | \<endpoint number\>
|
||||
* OUT EP = 0x00 | \<endpoint number\>
|
||||
*/
|
||||
uint8_t ep_addr;
|
||||
uint16_t ep_mps; /** Endpoint max packet size */
|
||||
enum usb_dc_ep_type ep_type; /** Endpoint type */
|
||||
};
|
||||
|
||||
/**
|
||||
* Callback function signature for the USB Endpoint status
|
||||
*/
|
||||
typedef void (*usb_dc_ep_callback)(uint8_t ep,
|
||||
enum usb_dc_ep_cb_status_code cb_status);
|
||||
|
||||
/**
|
||||
* Callback function signature for the device
|
||||
*/
|
||||
typedef void (*usb_dc_status_callback)(enum usb_dc_status_code cb_status);
|
||||
|
||||
/**
|
||||
* @brief attach USB for device connection
|
||||
*
|
||||
* Function to attach USB for device connection. Upon success, the USB PLL
|
||||
* is enabled, and the USB device is now capable of transmitting and receiving
|
||||
* on the USB bus and of generating interrupts.
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_attach(void);
|
||||
|
||||
/**
|
||||
* @brief detach the USB device
|
||||
*
|
||||
* Function to detach the USB device. Upon success, the USB hardware PLL
|
||||
* is powered down and USB communication is disabled.
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_detach(void);
|
||||
|
||||
/**
|
||||
* @brief reset the USB device
|
||||
*
|
||||
* This function returns the USB device and firmware back to it's initial state.
|
||||
* N.B. the USB PLL is handled by the usb_detach function
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_reset(void);
|
||||
|
||||
/**
|
||||
* @brief set USB device address
|
||||
*
|
||||
* @param[in] addr device address
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_set_address(const uint8_t addr);
|
||||
|
||||
/**
|
||||
* @brief set USB device controller status callback
|
||||
*
|
||||
* Function to set USB device controller status callback. The registered
|
||||
* callback is used to report changes in the status of the device controller.
|
||||
*
|
||||
* @param[in] cb callback function
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_set_status_callback(const usb_dc_status_callback cb);
|
||||
|
||||
/**
|
||||
* @brief configure endpoint
|
||||
*
|
||||
* Function to configure an endpoint. usb_dc_ep_cfg_data structure provides
|
||||
* the endpoint configuration parameters: endpoint address, endpoint maximum
|
||||
* packet size and endpoint type.
|
||||
*
|
||||
* @param[in] cfg Endpoint config
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_configure(const struct usb_dc_ep_cfg_data * const cfg);
|
||||
|
||||
/**
|
||||
* @brief set stall condition for the selected endpoint
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_set_stall(const uint8_t ep);
|
||||
|
||||
/**
|
||||
* @brief clear stall condition for the selected endpoint
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_clear_stall(const uint8_t ep);
|
||||
|
||||
/**
|
||||
* @brief check if selected endpoint is stalled
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
* @param[out] stalled Endpoint stall status
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_is_stalled(const uint8_t ep, uint8_t *const stalled);
|
||||
|
||||
/**
|
||||
* @brief halt the selected endpoint
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_halt(const uint8_t ep);
|
||||
|
||||
/**
|
||||
* @brief enable the selected endpoint
|
||||
*
|
||||
* Function to enable the selected endpoint. Upon success interrupts are
|
||||
* enabled for the corresponding endpoint and the endpoint is ready for
|
||||
* transmitting/receiving data.
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_enable(const uint8_t ep);
|
||||
|
||||
/**
|
||||
* @brief disable the selected endpoint
|
||||
*
|
||||
* Function to disable the selected endpoint. Upon success interrupts are
|
||||
* disabled for the corresponding endpoint and the endpoint is no longer able
|
||||
* for transmitting/receiving data.
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_disable(const uint8_t ep);
|
||||
|
||||
/**
|
||||
* @brief flush the selected endpoint
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_flush(const uint8_t ep);
|
||||
|
||||
/**
|
||||
* @brief write data to the specified endpoint
|
||||
*
|
||||
* This function is called to write data to the specified endpoint. The supplied
|
||||
* usb_ep_callback function will be called when data is transmitted out.
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
* @param[in] data pointer to data to write
|
||||
* @param[in] data_len length of data requested to write. This may
|
||||
* be zero for a zero length status packet.
|
||||
* @param[out] ret_bytes bytes scheduled for transmission. This value
|
||||
* may be NULL if the application expects all
|
||||
* bytes to be written
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_write(const uint8_t ep, const uint8_t *const data,
|
||||
const uint32_t data_len, uint32_t * const ret_bytes);
|
||||
|
||||
/**
|
||||
* @brief read data from the specified endpoint
|
||||
*
|
||||
* This function is called by the Endpoint handler function, after an OUT
|
||||
* interrupt has been received for that EP. The application must only call this
|
||||
* function through the supplied usb_ep_callback function.
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
* @param[in] data pointer to data buffer to write to
|
||||
* @param[in] max_data_len max length of data to read
|
||||
* @param[out] read_bytes Number of bytes read. If data is NULL and
|
||||
* max_data_len is 0 the number of bytes
|
||||
* available for read should be returned.
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_read(const uint8_t ep, uint8_t *const data,
|
||||
const uint32_t max_data_len, uint32_t *const read_bytes);
|
||||
|
||||
/**
|
||||
* @brief set callback function for the specified endpoint
|
||||
*
|
||||
* Function to set callback function for notification of data received and
|
||||
* available to application or trasmit done on the selected endpoint,
|
||||
* NULL if callback not required by application code.
|
||||
*
|
||||
* @param[in] ep Endpoint address corresponding to the one
|
||||
* listed in the device configuration table
|
||||
* @param[in] cb callback function
|
||||
*
|
||||
* @return 0 on success, negative errno code on fail.
|
||||
*/
|
||||
int usb_dc_ep_set_callback(const uint8_t ep, const usb_dc_ep_callback cb);
|
||||
|
||||
#endif /* __USB_DC_H__ */
|
||||
Loading…
Add table
Add a link
Reference in a new issue