Aquatic-Robotic-Courier/software/ARC-FW/hal/include/hpl_usb_host.h

/**
 * \file
 *
 * \brief SAM USB host HPL
 *
 * Copyright (c) 2016-2018 Microchip Technology Inc. and its subsidiaries.
 *
 * \asf_license_start
 *
 * \page License
 *
 * Subject to your compliance with these terms, you may use Microchip
 * software and any derivatives exclusively with Microchip products.
 * It is your responsibility to comply with third party license terms applicable
 * to your use of third party software (including open source software) that
 * may accompany Microchip software.
 *
 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES,
 * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE,
 * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY,
 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE
 * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL
 * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE
 * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE
 * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE.  TO THE FULLEST EXTENT
 * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY
 * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY,
 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE.
 *
 * \asf_license_stop
 *
 */

#ifndef _HPL_USB_HOST_H_INCLUDED
#define _HPL_USB_HOST_H_INCLUDED

#include <hpl_usb.h>
#include <hpl_irq.h>
#include "hpl_usb_config.h"

#ifdef __cplusplus
extern "C" {
#endif

/** Driver version */
#define USB_H_VERSION 0x00000001

/**
 * @brief      USB HCD callback types
 */
enum usb_h_cb_type {
	/** SOF generated */
	USB_H_CB_SOF,
	/** Root Hub change detected */
	USB_H_CB_ROOTHUB_CHANGE,
	/** Number of USB HCD callback types */
	USB_H_CB_N
};

/**
 * @brief      USB HCD resource strategy
 */
enum usb_h_rsc_strategy {
	/** Normal resource allocation, e.g.,
	 *  1 bank for interrupt endpoint,
	 *  2 bank for bulk endpoint and normal iso endpoint,
	 *  3 bank for iso high bandwidth endpoint.
	 */
	USB_H_RSC_NORMAL = false,
	/** Minimal resource allocation, e.g., only 1 bank for bulk endpoints */
	USB_H_RSC_MINIMAL = true
};

/**
 * @brief      USB HCD pipe states
 */
enum usb_h_pipe_state {
	/** Pipe is free to allocate */
	USB_H_PIPE_S_FREE = 0x00,
	/** Pipe is in configuration */
	USB_H_PIPE_S_CFG = 0x01,
	/** Pipe is allocated and idle */
	USB_H_PIPE_S_IDLE = 0x02,
	/** Pipe in control setup stage */
	USB_H_PIPE_S_SETUP = 0x03,
	/** Pipe in data IN stage */
	USB_H_PIPE_S_DATI = 0x05,
	/** Pipe in data OUT stage */
	USB_H_PIPE_S_DATO = 0x06,
	/** Pipe in data IN ZLP stage */
	USB_H_PIPE_S_ZLPI = 0x07,
	/** Pipe in data OUT ZLP stage */
	USB_H_PIPE_S_ZLPO = 0x08,
	/** Pipe in control status IN stage */
	USB_H_PIPE_S_STATI = 0x09,
	/** Pipe in control status OUT stage */
	USB_H_PIPE_S_STATO = 0x0A,
	/** Taken by physical pipe (in process) */
	USB_H_PIPE_S_TAKEN = 0x10
};

/**
 * @brief      USB HCD status code
 */
enum usb_h_status {
	/** OK */
	USB_H_OK = ERR_NONE,
	/** Busy */
	USB_H_BUSY = ERR_BUSY,
	/** Denied */
	USB_H_DENIED = ERR_DENIED,
	/** Timeout */
	USB_H_TIMEOUT = ERR_TIMEOUT,
	/** Abort */
	USB_H_ABORT = ERR_ABORTED,
	/** Stall protocol */
	USB_H_STALL = ERR_PROTOCOL,
	/** Transfer reset by pipe re-configure */
	USB_H_RESET = ERR_REQ_FLUSHED,
	/** Argument error */
	USB_H_ERR_ARG = ERR_INVALID_ARG,
	/** Operation not supported */
	USB_H_ERR_UNSP_OP = ERR_UNSUPPORTED_OP,
	/** No resource */
	USB_H_ERR_NO_RSC = ERR_NO_RESOURCE,
	/** Not initialized */
	USB_H_ERR_NOT_INIT = ERR_NOT_INITIALIZED,
	/** Some general error */
	USB_H_ERR = ERR_IO
};

/** Forward declare for pipe structure */
struct usb_h_pipe;

/** Forward declare for driver descriptor structure */
struct usb_h_desc;

/**
 * \brief Prototyping USB HCD callback of SOF
 */
typedef void (*usb_h_cb_sof_t)(struct usb_h_desc *drv);

/**
 * \brief Prototyping USB HCD callback of root hub changing.
 * According to the bitmap size, max port number is 31.
 */
typedef void (*usb_h_cb_roothub_t)(struct usb_h_desc *drv, uint8_t port, uint8_t ftr);

/**
 * Prototyping USB HCD callback of pipe transfer done.
 * For control pipe, it's forced to call even if there is no transfer
 * in progress, since the pipe size could be changed at run time.
 */
typedef void (*usb_h_pipe_cb_xfer_t)(struct usb_h_pipe *pipe);

/** Access to max packet size of a pipe */
#define usb_h_pipe_max_pkt_size(p) (p->max_pkt_size)

/** Access to device address of a pipe */
#define usb_h_pipe_dev_addr(p) (p->dev)

/** Access to endpoint address of a pipe */
#define usb_h_pipe_ep_addr(p) (p->ep)

/** Access to state of a pipe */
#define usb_h_pipe_state(p) (p->x.general.state)

/** Access to status of a pipe */
#define usb_h_pipe_status(p) (p->x.general.status)

/**
 * @brief      USB Host Controller device structure
 */
struct usb_h_desc {
	/** Pointer to hardware base */
	void *hw;
	/** Pointer to private data for Host Controller driver */
	void *prvt;
	/** Interrupt handling descriptor */
	struct _irq_descriptor irq;
	/** Callback of SOF */
	usb_h_cb_sof_t sof_cb;
	/** Callback of root hub change */
	usb_h_cb_roothub_t rh_cb;
#if CONF_USB_H_INST_OWNER_SP
	/** Extension for the driver owner (upper layer user) */
	void *owner;
#endif
};

/**
 * @brief      Transfer descriptor for control transfer
 *
 * Timing in USB 2.0 spec.:
 * - 9.2.6.1 : USB sets an upper limit of 5 seconds as the upper limit for any
 *             command to be processed.
 * - 9.2.6.3 : if a device receives a SetAddress() request, the device must be
 *             able to complete processing of the request and be able to
 *             successfully complete the Status stage of the request within
 *             50 ms.
 *             After successful completion of the Status stage, the device is
 *             allowed a SetAddress() recovery interval of 2 ms. At the end of
 *             this interval, the device must be able to accept Setup packets
 *             addressed to the new address.
 * - 9.2.6.4 : For standard device requests that require no Data stage, a device
 *             must be able to complete the request and be able to successfully
 *             complete the Status stage of the request within 50 ms of receipt
 *             of the request. This limitation applies to requests to the
 *             device, interface, or endpoint.
 *             For standard device requests that require data stage transfer to
 *             the host, the device must be able to return the first data packet
 *             to the host within 500 ms of receipt of the request. For
 *             subsequent data packets, if any, the device must be able to
 *             return them within 500 ms of successful completion of the
 *             transmission of the previous packet. The device must then be
 *             able to successfully complete the status stage within 50 ms after
 *             returning the last data packet.
 *             For standard device requests that require a data stage transfer
 *             to the device, the 5-second limit applies.
 * - 9.2.6.5 : Unless specifically exempted in the class document, all
 *             class-specific requests must meet the timing limitations for
 *             standard device requests.
 *
 * Conclusion:
 * 1. Whole request with data: 5 seconds
 * 2. Whole request without data: 50 ms
 * 3. Data packets: 500 ms
 */
struct usb_h_ctrl_xfer {
	/** Pointer to transfer data */
	uint8_t *data;
	/** Pointer to setup packet */
	uint8_t *setup;
	/** Expected transfer size */
	uint16_t size;
	/** Transfer count */
	uint16_t count;
	/** Timeout for request, -1 if disable timeout */
	int16_t req_timeout;
	/** Timeout between packets
	 *  (500ms for data and 50ms for status), -1 if disabled */
	int16_t pkt_timeout;
	/** Packet size during transfer (<= allocate max packet size) */
	uint16_t pkt_size;

	/** Transfer state */
	uint8_t state;
	/** Last transfer status */
	int8_t status;
};

/**
 * @brief      Transfer descriptor for bulk / interrupt / iso transfer
 */
struct usb_h_bulk_int_iso_xfer {
	/** Expected transfer size */
	uint32_t size;
	/** Transfer count */
	uint32_t count;
	/** Pointer to transfer data */
	uint8_t *data;
	/** Reserved */
	uint16_t reserved[3];

	/** Transfer state */
	uint8_t state;
	/** Last transfer status */
	int8_t status;
};

/**
 * @brief      Transfer descriptor for periodic high bandwidth transfer
 */
struct usb_h_high_bw_xfer {
	/** Expected transfer size */
	uint32_t size;
	/** Transfer count */
	uint32_t count;
	/** Pointer to transfer data */
	uint8_t *data;
	/** Micro frame packet sizes */
	uint16_t pkt_size[3];

	/** Transfer state */
	uint8_t state;
	/** Last transfer status */
	int8_t status;
};

/**
 * @brief General transfer descriptor
 */
struct usb_h_xfer {
	/** Reserved for different transfer */
	union {
		uint16_t u16[9];
		uint8_t  u8[18];
	} reserved;
	/** Transfer state */
	uint8_t state;
	/** Last transfer status */
	int8_t status;
};

/**
 * @brief      USB Host Controller Driver Pipe structure
 */
struct usb_h_pipe {
	/** Pointer to the USB Host Controller Driver */
	struct usb_h_desc *hcd;
	/** Pointer to the callback for transfer done */
	usb_h_pipe_cb_xfer_t done;
#if CONF_USB_H_INST_OWNER_SP
	/** Pointer to the pipe owner */
	void *owner;
#endif

	/** Endpoint max packet size (bits 10..0) */
	uint16_t max_pkt_size;
	/** Device address */
	uint8_t dev;
	/** Endpoint address */
	uint8_t ep;

	/** Endpoint interval */
	uint8_t interval;
	/** Endpoint type: Control, Isochronous, Bulk or Interrupt */
	uint8_t type;
	/** Current toggle (driver dependent) */
	uint8_t toggle;
	/** Endpoint number of banks (HW dependent) */
	uint8_t bank : 2;
	/** Transfer speed (HW dependent) */
	uint8_t speed : 2;
	/** High bandwidth periodic out */
	uint8_t high_bw_out : 1;
	/** Uses DMA (on transfer) */
	uint8_t dma : 1;
	/** Transfer ZLP support */
	uint8_t zlp : 1;
	/** Transfer periodic */
	uint8_t periodic_start : 1;

	/** Transfer status */
	union {
		/** General transfer info */
		struct usb_h_xfer general;
		/** Control transfer status */
		struct usb_h_ctrl_xfer ctrl;
		/** Bulk interrupt iso transfer status */
		struct usb_h_bulk_int_iso_xfer bii;
		/** Periodic high bandwidth transfer status */
		struct usb_h_high_bw_xfer hbw;
	} x;
};

/**
 * @brief      USB HCD Initialization
 *
 * @param      drv     Pointer to the HCD driver instance
 * @param[in]  hw      Pointer to hardware base
 * @param[in]  prvt    The private driver data (implement specific)
 *
 * @return     Operation result status
 * @retval     ERR_DENIED Hardware has been enabled
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_init(struct usb_h_desc *drv, void *hw, void *prvt);

/**
 * @brief      USB HCD de-initialization
 *
 * @param      drv   The driver
 */
void _usb_h_deinit(struct usb_h_desc *drv);

/**
 * @brief      USB HCD enable
 *
 * @param      drv   The driver
 */
void _usb_h_enable(struct usb_h_desc *drv);

/**
 * @brief      USB HCD disable
 *
 * @param      drv   The driver
 */
void _usb_h_disable(struct usb_h_desc *drv);

/**
 * @brief      Register callbacks for USB HCD
 *
 * @param      drv   The driver
 * @param[in]  type  The callback type
 * @param[in]  cb    The callback function entry
 *
 * @return     Operation result status
 * @retval     ERR_INVALID_ARG Argument error
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_register_callback(struct usb_h_desc *drv, enum usb_h_cb_type type, FUNC_PTR cb);

/**
 * @brief      Return current frame number
 *
 * @param      drv   The driver
 *
 * @return     current frame number
 */
uint16_t _usb_h_get_frame_n(struct usb_h_desc *drv);

/**
 * @brief      Return current micro frame number
 *
 * @param      drv   The driver
 *
 * @return     current micro frame number
 */
uint8_t _usb_h_get_microframe_n(struct usb_h_desc *drv);

/**
 * @brief Suspend the USB bus
 *
 * @param drv The driver
 */
void _usb_h_suspend(struct usb_h_desc *drv);

/**
 * @brief Resume the USB bus
 *
 * @param drv The driver
 */
void _usb_h_resume(struct usb_h_desc *drv);

/* Root hub related APIs */

/**
 * \brief Reset the root hub port
 *
 * \param[in,out] drv  Pointer to the USB HCD driver
 * \param[in]     port Root hub port, ignored if there is only one port
 */
void _usb_h_rh_reset(struct usb_h_desc *drv, uint8_t port);

/**
 * \brief Suspend the root hub port
 *
 * \param[in,out] drv  Pointer to the USB HCD driver
 * \param[in]     port Root hub port, ignored if there is only one port
 */
void _usb_h_rh_suspend(struct usb_h_desc *drv, uint8_t port);

/**
 * \brief Resume the root hub port
 *
 * \param[in,out] drv  Pointer to the USB HCD driver
 * \param[in]     port Root hub port, ignored if there is only one port
 */
void _usb_h_rh_resume(struct usb_h_desc *drv, uint8_t port);

/**
 * \brief Root hub or port feature status check
 *
 * Check USB Spec. for hub status and feature selectors.
 *
 * \param[in] drv  Pointer to the USB HCD driver
 * \param[in] port Set to 0 to get hub status, otherwise to get port status
 * \param[in] ftr  Hub feature/status selector
 *                 (0: connection, 2: suspend, 4: reset, 9: LS, 10: HS)
 *
 * \return     \c true if the status bit is 1
 */
bool _usb_h_rh_check_status(struct usb_h_desc *drv, uint8_t port, uint8_t ftr);

/* Pipe transfer functions */

/**
 * @brief      Allocate a pipe for USB host communication
 *
 * @param      drv           The USB HCD driver
 * @param[in]  dev           The device address
 * @param[in]  ep            The endpoint address
 * @param[in]  max_pkt_size  The endpoint maximum packet size
 * @param[in]  attr          The endpoint attribute
 * @param[in]  interval      The endpoint interval
 *                           (bInterval of USB Endpoint Descriptor)
 * @param[in]  speed         The transfer speed of the endpoint
 * @param[in]  minimum_rsc   Minimum the resource usage, \sa usb_h_rsc_strategy
 *
 * @return     Pointer to allocated pipe structure instance
 * @retval     NULL allocation fail
 */
struct usb_h_pipe *_usb_h_pipe_allocate(struct usb_h_desc *drv, uint8_t dev, uint8_t ep, uint16_t max_pkt_size,
                                        uint8_t attr, uint8_t interval, uint8_t speed, bool minimum_rsc);

/**
 * @brief      Free an allocated pipe
 *
 * @param      pipe  The pipe
 *
 * @return     Operation result status
 * @retval     ERR_BUSY Pipe is busy, use \ref _usb_h_pipe_abort to abort
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_pipe_free(struct usb_h_pipe *pipe);

/**
 * @brief      Modify parameters of an allocated control pipe
 *
 * @param      pipe          The pipe
 * @param[in]  dev           The device address
 * @param[in]  ep            The endpoint address
 * @param[in]  max_pkt_size  The maximum packet size, must be equal or
 *                           less than allocated size
 * @param[in]  speed         The working speed
 *
 * @return     Operation result status
 * @retval     ERR_NOT_INITIALIZED Pipe is not allocated
 * @retval     ERR_BUSY Pipe is busy transferring
 * @retval     ERR_INVALID_ARG Argument error
 * @retval     ERR_UNSUPPORTED_OP Pipe is not control pipe
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_pipe_set_control_param(struct usb_h_pipe *pipe, uint8_t dev, uint8_t ep, uint16_t max_pkt_size,
                                      uint8_t speed);

/**
 * @brief      Register transfer callback on a pipe
 *
 * @param      pipe  The pipe
 * @param[in]  cb    Transfer callback function
 *
 * @return     Operation result status
 * @retval     ERR_INVALID_ARG Argument error
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_pipe_register_callback(struct usb_h_pipe *pipe, usb_h_pipe_cb_xfer_t cb);

/**
 * @brief      Issue a control transfer (request) on a pipe
 *
 * \note When there is data stage, timeout between data packets is 500ms, the
 *       timeout between last data packet and the status packet is 50ms.
 *
 * @param         pipe    The pipe
 * @param[in]     setup   Pointer to the setup packet
 * @param[in,out] data    Pointer to the data buffer
 * @param[in]     length  The data length
 * @param[in]     timeout Timeout for whole request in ms
 *
 * @return     Operation result status
 * @retval     ERR_NOT_INITIALIZED Pipe is not allocated
 * @retval     ERR_BUSY Pipe is busy transferring
 * @retval     ERR_INVALID_ARG Argument error
 * @retval     ERR_UNSUPPORTED_OP Pipe is not control pipe
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_control_xfer(struct usb_h_pipe *pipe, uint8_t *setup, uint8_t *data, uint16_t length, int16_t timeout);

/**
 * @brief      Issue a bulk / interrupt / iso transfer on a pipe
 *
 * @param         pipe     The pipe
 * @param[in,out] data     Pointer to the data buffer
 * @param[in]     length   The data length
 * @param[in]     auto_zlp Auto append ZLP for OUT
 *
 * @return     Operation result status
 * @retval     ERR_NOT_INITIALIZED Pipe is not allocated
 * @retval     ERR_BUSY Pipe is busy transferring
 * @retval     ERR_INVALID_ARG Argument error
 * @retval     ERR_UNSUPPORTED_OP Pipe is control pipe
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_bulk_int_iso_xfer(struct usb_h_pipe *pipe, uint8_t *data, uint32_t length, bool auto_zlp);

/**
 * @brief      Issue a periodic high bandwidth output on a pipe
 *
 * @param         pipe             The pipe
 * @param[in,out] data             Pointer to the data buffer
 * @param[in]     length           The data length
 * @param[in]     trans_pkt_size   The transaction packet sizes in a micro frame,
 *                                 0 to use endpoint max packet size
 *
 * @return     Operation result status
 * @retval     ERR_NOT_INITIALIZED Pipe is not allocated
 * @retval     ERR_BUSY Pipe is busy transferring
 * @retval     ERR_INVALID_ARG Argument error
 * @retval     ERR_UNSUPPORTED_OP Pipe is not high bandwidth periodic pipe, or
 *                                DMA feature not enabled, or
 *                                high bandwidth not enabled
 * @retval     ERR_NONE Operation done successfully
 */
int32_t _usb_h_high_bw_out(struct usb_h_pipe *pipe, uint8_t *data, uint32_t length, uint16_t trans_pkt_size[3]);

/**
 * @brief      Check if pipe is busy transferring
 *
 * @param      pipe  The pipe
 *
 * @return     \c true if pipe is busy
 */
bool _usb_h_pipe_is_busy(struct usb_h_pipe *pipe);

/**
 * @brief      Abort pending transfer on a pipe
 *
 * @param      pipe  The pipe
 */
void _usb_h_pipe_abort(struct usb_h_pipe *pipe);

#ifdef __cplusplus
}
#endif

#endif /* _HPL_USB_HOST_H_INCLUDED */