/*
* Copyright (c) 2018-2019, Arm Limited and affiliates.
* SPDX-License-Identifier: Apache-2.0
*
* 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.
*/
#ifndef USBPHY_H
#define USBPHY_H
#include "USBPhyTypes.h"
#include "USBPhyEvents.h"
/** Abstract interface to physical USB hardware
*
* # Defined behavior
* * You can use any endpoint configurations that fit in the parameters
* of the table returned by USBPhy::endpoint_table.
* * You can use all endpoints in any valid endpoint configuration concurrently.
* * The device supports use of at least one control, bulk, interrupt and
* isochronous in each direction at the same time - at least 8 endpoints.
* * USBPhy supports all standard endpoint sizes (wMaxPacketSize).
* * USBPhy can handle an interrupt latency of at least 100ms if the host PC
* is not performing a reset or setting the device's address.
* * USBPhy only sends USBPhyEvents when it is in the initialized state.
* * When unpowered, USBPhy only sends the USBPhyEvents::power event.
* * On USB reset, all endpoints are removed except for endpoint 0.
* * A call to USBPhy::ep0_write results in the call of USBPhyEvents::in when
* the PC reads the data unless a power loss, reset, or a call to
* USBPhy::disconnect occurs first.
* * A call to USBPhy::endpoint_write results in the call of USBPhyEvents::in
* when the pc reads the data unless a power loss, reset, or a call to
* USBPhy::endpoint_abort occurs first.
* * A call to USBPhy::endpoint_read results in the call of USBPhyEvents::out
* when the pc sends data unless a power loss, reset, or a call to
* USBPhy::endpoint_abort occurs first.
* * Endpoint 0 naks all transactions aside from setup packets until
* higher-level code calls one of USBPhy::ep0_read, USBPhy::ep0_write or
* USBPhy::ep0_stall.
* * Endpoint 0 stall automatically clears on reception of a setup packet.
*
* # Undefined behavior
* * Calling USBPhy::endpoint_add or USBPhy::endpoint_remove outside of the
* control requests SetInterface or SetConfiguration.
* * Calling USBPhy::endpoint_remove on an endpoint that has an ongoing read
* or write operation. To avoid undefined behavior, you must abort ongoing
* operations with USBPhy::endpoint_abort.
* * Devices behavior is undefined if latency is greater than 2ms when address
* is being set - see USB spec 9.2.6.3.
* * Devices behavior is undefined if latency is greater than 10ms when a
* reset occurs - see USB spec 7.1.7.5.
* * Calling any of the USBPhy::endpoint_* functions on endpoint 0.
*
* # Notes
* * Make sure USBPhy sends USBPhyEvents in the correct order when multiple
* packets are present. USBPhy must send IN endpoint events before OUT
* endpoint events if both are pending.
* * A host PC may resend setup packets to a USB device if there is noise on
* the USB line. The USBPhy should be able to handle this scenario and
* respond to the setup packet with an ACK.
* * Bidirectional protocols making use of alternating IN and OUT phases
* should not rely on the last ACK an IN transfer to indicate that the
* OUT phase should start. Instead, the OUT phase should be started at
* the same time the last IN transfer is started. This is because the ACK
* to the last in transfer may be dropped if there is noise on the USB
* line. If dropped, it will only be resent on the next IN phase. You can
* find more information on this in section 8.5.3.3 of the USB
* specification.
*
* @ingroup usb_device_core
*/
class USBPhy {
public:
USBPhy() {};
virtual ~USBPhy() {};
/**
* Initialize this USBPhy instance
*
* This function must be called before calling
* any other functions of this class, unless specifically
* noted.
*
* @param events Callback class to handle USB events
*/
virtual void init(USBPhyEvents *events) = 0;
/**
* Power down this USBPhy instance
*
* Disable interrupts and stop sending events.
*/
virtual void deinit() = 0;
/**
* Check if USB power is present
*
* Devices which don't support checking the USB power state
* must always return true.
*
* @return true if USB power is present, false otherwise
*/
virtual bool powered() = 0;
/**
* Make the USB phy visible to the USB host
*
* Enable either the D+ or D- pullup so the host can detect
* the presence of this device.
*/
virtual void connect() = 0;
/**
* Detach the USB phy
*
* Disable the D+ and D- pullup and stop responding to
* USB traffic.
*/
virtual void disconnect() = 0;
/**
* Set this device to the configured state
*
* Enable added endpoints if they are not enabled
* already.
*/
virtual void configure() = 0;
/**
* Leave the configured state
*
* This is a notification to the USBPhy indicating that the device
* is leaving the configured state. The USBPhy can disable all
* endpoints other than endpoint 0.
*
*/
virtual void unconfigure() = 0;
/**
* Enable the start of frame interrupt
*
* Call USBPhyEvents::sof on every frame.
*/
virtual void sof_enable() = 0;
/**
* Disable the start of frame interrupt
*
* Stop calling USBPhyEvents::sof.
*/
virtual void sof_disable() = 0;
/**
* Set the USBPhy's address
*
* @param address This device's USB address
*/
virtual void set_address(uint8_t address) = 0;
/**
* Wake upstream devices
*/
virtual void remote_wakeup() = 0;
/**
* Get the endpoint table
*
* This function returns a table which describes the endpoints
* can be used, the functionality of those endpoints and the
* resource cost.
*/
virtual const usb_ep_table_t *endpoint_table() = 0;
/**
* Set wMaxPacketSize of endpoint 0
*
* @param max_packet The wMaxPacketSize value for endpoint 0
* @return The actual size of endpoint 0
*/
virtual uint32_t ep0_set_max_packet(uint32_t max_packet) = 0;
/**
* Read the contents of the SETUP packet
*
* @param buffer Buffer to fill with data
* @param size Size of buffer passed in
*/
virtual void ep0_setup_read_result(uint8_t *buffer, uint32_t size) = 0;
/**
* Start receiving a packet of up to wMaxPacketSize on endpoint 0
*
* @param data Buffer to fill with the data read
* @param size Size of buffer
*/
virtual void ep0_read(uint8_t *data, uint32_t size) = 0;
/**
* Read the contents of a received packet
*
* @return Size of data read
*/
virtual uint32_t ep0_read_result() = 0;
/**
* Write a packet on endpoint 0
*
* @param buffer Buffer fill with data to send
* @param size Size of data to send
*/
virtual void ep0_write(uint8_t *buffer, uint32_t size) = 0;
/**
* Protocol stall on endpoint 0
*
* Stall all IN and OUT packets on endpoint 0 until a setup packet
* is received.
* @note The stall is cleared automatically when a setup packet is received
*/
virtual void ep0_stall() = 0;
/**
* Configure and enable an endpoint
*
* @param endpoint Endpoint to configure and enable
* @param max_packet The maximum packet size that can be sent or received
* @param type The type of endpoint this should be configured as -
* USB_EP_TYPE_BULK, USB_EP_TYPE_INT or USB_EP_TYPE_ISO
* @note This function cannot be used to configure endpoint 0. That must be done
* with ep0_set_max_packet
*/
virtual bool endpoint_add(usb_ep_t endpoint, uint32_t max_packet, usb_ep_type_t type) = 0;
/**
* Disable an endpoint
*
* @param endpoint Endpoint to disable
*/
virtual void endpoint_remove(usb_ep_t endpoint) = 0;
/**
* Perform a functional stall on the given endpoint
*
* Set the HALT feature for this endpoint so that all further
* communication is aborted.
*
* @param endpoint Endpoint to stall
*/
virtual void endpoint_stall(usb_ep_t endpoint) = 0;
/**
* Un-stall the endpoint
*
* Clear the HALT feature on this endpoint so communication can
* resume.
*
* @param endpoint Endpoint to stall
*/
virtual void endpoint_unstall(usb_ep_t endpoint) = 0;
/**
* Start a read on the given endpoint
*
* @param endpoint Endpoint to start the read on
* @param data Buffer to fill with data
* @param size Size of the read buffer. This must be at least
* the max packet size for this endpoint.
* @return true if the read was successfully started, false otherwise
*/
virtual bool endpoint_read(usb_ep_t endpoint, uint8_t *data, uint32_t size) = 0;
/**
* Finish a read on the given endpoint
*
* @param endpoint Endpoint to check
* @return The number of bytes received
*/
virtual uint32_t endpoint_read_result(usb_ep_t endpoint) = 0;
/**
* Start a write on the given endpoint
*
* @param endpoint Endpoint to write to
* @param data Buffer to write
* @param size Size of data to write
* @return true if the data was prepared for transmit, false otherwise
*/
virtual bool endpoint_write(usb_ep_t endpoint, uint8_t *data, uint32_t size) = 0;
/**
* Abort the current transfer if it has not yet been sent
*
* @param endpoint Endpoint to abort the transfer on. It is implementation defined
* if this function has an effect on receive endpoints.
*/
virtual void endpoint_abort(usb_ep_t endpoint) = 0;
/**
* Callback used for performing USB processing
*
* USBPhy processing should be triggered by calling USBPhyEvents::start_process
* and done inside process. All USBPhyEvents callbacks aside from
* USBPhyEvents::start_process must be called in the context of process
*/
virtual void process() = 0;
};
#endif
