ehci.h

Go to the documentation of this file.

/*
 * The MIT License (MIT)
 *
 * Copyright (c) 2019 Ha Thach (tinyusb.org)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 *
 * This file is part of the TinyUSB stack.
 */
 
#ifndef _TUSB_EHCI_H_
#define _TUSB_EHCI_H_
 
 
/* Abbreviation
 * HC: Host Controller
 * HCD: Host Controller Driver
 * QHD: Queue Head for non-ISO transfer
 * QTD: Queue Transfer Descriptor for non-ISO transfer
 * ITD: Iso Transfer Descriptor for highspeed
 * SITD: Split ISO Transfer Descriptor for full-speed
 * SMASK: Start Split mask for Slipt Transaction
 * CMASK: Complete Split mask for Slipt Transaction
*/
 
#ifdef __cplusplus
 extern "C" {
#endif
 
//--------------------------------------------------------------------+
// EHCI CONFIGURATION & CONSTANTS
//--------------------------------------------------------------------+
 
// TODO merge OHCI with EHCI
enum {
  EHCI_MAX_ITD  = 4,
  EHCI_MAX_SITD = 16
};
 
//--------------------------------------------------------------------+
// EHCI Data Structure
//--------------------------------------------------------------------+
enum
{
  EHCI_QTYPE_ITD = 0 ,
  EHCI_QTYPE_QHD     ,
  EHCI_QTYPE_SITD    ,
  EHCI_QTYPE_FSTN
};
 
enum
{
  EHCI_PID_OUT = 0 ,
  EHCI_PID_IN      ,
  EHCI_PID_SETUP
};
 
typedef union {
    uint32_t address;
    struct  {
        uint32_t terminate : 1;
        uint32_t type      : 2;
    };
}ehci_link_t;
 
TU_VERIFY_STATIC( sizeof(ehci_link_t) == 4, "size is not correct" );
 
typedef struct
{
    // Word 0: Next QTD Pointer
    ehci_link_t next;
 
    // Word 1: Alternate Next QTD Pointer (not used)
    union{
      ehci_link_t alternate;
      struct {
        uint32_t                : 5;
        uint32_t used           : 1;
        uint32_t                : 10;
        uint32_t expected_bytes : 16;
      };
    };
 
    // Word 2: qTQ Token
    volatile uint32_t ping_err             : 1  ; 
    volatile uint32_t non_hs_split_state   : 1  ; 
    volatile uint32_t non_hs_missed_uframe : 1  ; 
    volatile uint32_t xact_err             : 1  ; 
    volatile uint32_t babble_err           : 1  ; 
    volatile uint32_t buffer_err           : 1  ; 
    volatile uint32_t halted               : 1  ; 
    volatile uint32_t active               : 1  ; 
 
    uint32_t pid                           : 2  ; 
    volatile uint32_t err_count            : 2  ; 
    volatile uint32_t current_page         : 3  ; 
    uint32_t int_on_complete               : 1  ; 
    volatile uint32_t total_bytes          : 15 ; 
    volatile uint32_t data_toggle          : 1  ; 
 
 
    uint32_t buffer[5];
} ehci_qtd_t;
 
TU_VERIFY_STATIC( sizeof(ehci_qtd_t) == 32, "size is not correct" );
 
typedef struct TU_ATTR_ALIGNED(32)
{
  // Word 0: Next QHD
    ehci_link_t next;
 
    // Word 1: Endpoint Characteristics
    uint32_t dev_addr              : 7  ; 
    uint32_t fl_inactive_next_xact : 1  ; 
    uint32_t ep_number             : 4  ; 
    uint32_t ep_speed              : 2  ; 
    uint32_t data_toggle_control   : 1  ; 
    uint32_t head_list_flag        : 1  ; 
    uint32_t max_packet_size       : 11 ; 
    uint32_t fl_ctrl_ep_flag       : 1  ; 
    uint32_t nak_reload            : 4  ; 
 
    // Word 2: Endpoint Capabilities
    uint32_t int_smask             : 8  ; 
    uint32_t fl_int_cmask          : 8  ; 
    uint32_t fl_hub_addr           : 7  ; 
    uint32_t fl_hub_port           : 7  ; 
    uint32_t mult                  : 2  ; 
 
    // Word 3: Current qTD Pointer
    volatile uint32_t qtd_addr;
 
    // Word 4-11: Transfer Overlay
    volatile ehci_qtd_t qtd_overlay;
 
    //--------------------------------------------------------------------+
  //--------------------------------------------------------------------+
    uint8_t used;
    uint8_t removing; // removed from asyn list, waiting for async advance
    uint8_t pid;
    uint8_t interval_ms; // polling interval in frames (or millisecond)
 
    uint8_t TU_RESERVED[4];
 
  // Attached TD management, note usbh will only queue 1 TD per QHD.
  // buffer for dcache invalidate since td's buffer is modified by HC and finding initial buffer address is not trivial
  uint32_t attached_buffer;
    ehci_qtd_t * volatile attached_qtd;
} ehci_qhd_t;
 
TU_VERIFY_STATIC( sizeof(ehci_qhd_t) == 64, "size is not correct" );
 
typedef struct TU_ATTR_ALIGNED(32) {
    // Word 0: Next Link Pointer
    ehci_link_t next;
 
    // Word 1-8: iTD Transaction Status and Control List
    struct  {
      // iTD Control
        volatile uint32_t offset          : 12 ; 
        volatile uint32_t page_select     : 3  ; 
             uint32_t int_on_complete : 1  ; 
        volatile uint32_t length          : 12 ; 
        // iTD Status
        volatile uint32_t error           : 1  ; 
        volatile uint32_t babble_err      : 1  ; 
        volatile uint32_t buffer_err      : 1  ; 
        volatile uint32_t active          : 1  ; 
    } xact[8];
 
    // Word 9-15  Buffer Page Pointer List (Plus)
    uint32_t BufferPointer[7];
 
//  // FIXME: Store meta data into buffer pointer reserved for saving memory
//  /*---------- HCD Area ----------*/
//  uint32_t used;
//  uint32_t IhdIdx;
//  uint32_t reserved[6];
} ehci_itd_t;
 
TU_VERIFY_STATIC( sizeof(ehci_itd_t) == 64, "size is not correct" );
 
typedef struct TU_ATTR_ALIGNED(32)
{
  // Word 0: Next Link Pointer
    ehci_link_t next;
 
    // Word 1: siTD Endpoint Characteristics
    uint32_t dev_addr    : 7; 
    uint32_t             : 1; 
    uint32_t ep_number   : 4; 
    uint32_t             : 4; 
    uint32_t hub_addr    : 7; 
    uint32_t             : 1; 
    uint32_t port_number : 7; 
    uint32_t direction   : 1; 
 
    // Word 2: Micro-frame Schedule Control
    uint8_t int_smask   ; 
    uint8_t fl_int_cmask; 
    uint16_t reserved ; 
 
    // Word 3: siTD Transfer Status and Control
    // Status [7:0] TODO identical to qTD Token'status --> refactor later
    volatile uint32_t                 : 1  ; // reserved
    volatile uint32_t split_state     : 1  ;
    volatile uint32_t missed_uframe   : 1  ;
    volatile uint32_t xact_err        : 1  ;
    volatile uint32_t babble_err      : 1  ;
    volatile uint32_t buffer_err      : 1  ;
    volatile uint32_t error           : 1  ;
    volatile uint32_t active          : 1  ;
    // Micro-frame Schedule Control
    volatile uint32_t cmask_progress  : 8  ; 
    volatile uint32_t total_bytes     : 10 ; 
    volatile uint32_t                 : 4  ; 
    volatile uint32_t page_select     : 1  ; 
                     uint32_t int_on_complete : 1  ; 
                     uint32_t                 : 0  ; // padding to the end of current storage unit
 
    uint32_t buffer[2];     // buffer[1] TP: Transaction Position - T-Count: Transaction Count
 
    /*---------- Word 6 ----------*/
    ehci_link_t back;
 
    uint8_t used;
    uint8_t ihd_idx;
    uint8_t reserved2[2];
} ehci_sitd_t;
 
TU_VERIFY_STATIC( sizeof(ehci_sitd_t) == 32, "size is not correct" );
 
//--------------------------------------------------------------------+
// EHCI Operational Register
//--------------------------------------------------------------------+
enum {
  // Bit 0-5 has maskable in interrupt enabled register
  EHCI_INT_MASK_USB                   = TU_BIT(0),
  EHCI_INT_MASK_ERROR                 = TU_BIT(1),
  EHCI_INT_MASK_PORT_CHANGE           = TU_BIT(2),
  EHCI_INT_MASK_FRAMELIST_ROLLOVER    = TU_BIT(3),
  EHCI_INT_MASK_PCI_HOST_SYSTEM_ERROR = TU_BIT(4),
  EHCI_INT_MASK_ASYNC_ADVANCE         = TU_BIT(5),
 
  EHCI_INT_MASK_NXP_SOF               = TU_BIT(7),
 
  EHCI_INT_MASK_HC_HALTED             = TU_BIT(12),
  EHCI_INT_MASK_RECLAIMATION          = TU_BIT(13),
  EHCI_INT_MASK_PERIODIC_SCHED_STATUS = TU_BIT(14),
  EHCI_INT_MASK_ASYNC_SCHED_STATUS    = TU_BIT(15),
 
  EHCI_INT_MASK_ALL                   =
      EHCI_INT_MASK_USB | EHCI_INT_MASK_ERROR | EHCI_INT_MASK_PORT_CHANGE |
      EHCI_INT_MASK_FRAMELIST_ROLLOVER | EHCI_INT_MASK_PCI_HOST_SYSTEM_ERROR |
      EHCI_INT_MASK_ASYNC_ADVANCE | EHCI_INT_MASK_NXP_SOF
};
 
enum {
  EHCI_USBCMD_FRAMELIST_SIZE_SHIFT              = 2, // [2..3]
  EHCI_USBCMD_CHIPIDEA_FRAMELIST_SIZE_MSB_SHIFT = 15,
  EHCI_USBCMD_INTERRUPT_THRESHOLD_SHIFT         = 16
};
 
enum {
  EHCI_USBCMD_RUN_STOP                       = TU_BIT(0), // [0..0] 1 = Run, 0 = Stop
  EHCI_USBCMD_HCRESET                        = TU_BIT(1), // [1..1] SW write 1 to reset HC, clear by HC when complete
  EHCI_USBCMD_PERIOD_SCHEDULE_ENABLE         = TU_BIT(4), // [4..4] Enable periodic schedule
  EHCI_USBCMD_ASYNC_SCHEDULE_ENABLE          = TU_BIT(5), // [5..5] Enable async schedule
  EHCI_USBCMD_INTR_ON_ASYNC_ADVANCE_DOORBELL = TU_BIT(6), // [6..6] Tell HC to interrupt next time it advances async list. Clear by HC
};
 
enum {
  EHCI_PORTSC_MASK_CURRENT_CONNECT_STATUS = TU_BIT(0),
  EHCI_PORTSC_MASK_CONNECT_STATUS_CHANGE  = TU_BIT(1),
  EHCI_PORTSC_MASK_PORT_EANBLED           = TU_BIT(2),
  EHCI_PORTSC_MASK_PORT_ENABLE_CHANGE     = TU_BIT(3),
  EHCI_PORTSC_MASK_OVER_CURRENT_CHANGE    = TU_BIT(5),
  EHCI_PORTSC_MASK_FORCE_RESUME           = TU_BIT(6),
  EHCI_PORTSC_MASK_PORT_SUSPEND           = TU_BIT(7),
  EHCI_PORTSC_MASK_PORT_RESET             = TU_BIT(8),
  EHCI_PORTSC_MASK_PORT_POWER             = TU_BIT(12),
 
  EHCI_PORTSC_MASK_W1C =
    EHCI_PORTSC_MASK_CONNECT_STATUS_CHANGE |
    EHCI_PORTSC_MASK_PORT_ENABLE_CHANGE |
    EHCI_PORTSC_MASK_OVER_CURRENT_CHANGE
};
 
typedef volatile struct
{
  union {
    uint32_t command; // 0x00
 
    struct {
      uint32_t run_stop               : 1 ; 
      uint32_t reset                  : 1 ; 
      uint32_t framelist_size         : 2 ; 
      uint32_t periodic_enable        : 1 ; 
      uint32_t async_enable           : 1 ; 
      uint32_t async_adv_doorbell     : 1 ; 
      uint32_t light_reset            : 1 ; 
      uint32_t async_park_count       : 2 ; 
      uint32_t                        : 1 ;
      uint32_t async_park_enable      : 1 ; 
      uint32_t                        : 3 ;
      uint32_t nxp_framelist_size_msb : 1 ; 
      uint32_t int_threshold          : 8 ; 
    }command_bm;
  };
 
  union {
    uint32_t status; // 0x04
 
    struct {
      uint32_t usb                   : 1  ; 
      uint32_t usb_error             : 1  ; 
      uint32_t port_change_detect    : 1  ; 
      uint32_t framelist_rollover    : 1  ; 
      uint32_t pci_host_system_error : 1  ; 
      uint32_t async_adv             : 1  ; 
      uint32_t                       : 1  ;
      uint32_t nxp_int_sof           : 1  ; 
      uint32_t                       : 4  ;
      uint32_t hc_halted             : 1  ; 
      uint32_t reclamation           : 1  ; 
      uint32_t periodic_status       : 1  ; 
      uint32_t async_status          : 1  ; 
      uint32_t                       : 2  ;
      uint32_t nxp_int_async         : 1  ; 
      uint32_t nxp_int_period        : 1  ; 
      uint32_t                       : 12 ;
    }status_bm;
  };
 
  union{
    uint32_t inten; // 0x08
 
    struct {
      uint32_t usb                   : 1  ;
      uint32_t usb_error             : 1  ;
      uint32_t port_change_detect    : 1  ;
      uint32_t framelist_rollover    : 1  ;
      uint32_t pci_host_system_error : 1  ;
      uint32_t async_adv             : 1  ;
      uint32_t                       : 1  ;
      uint32_t nxp_int_sof           : 1  ;
      uint32_t                       : 10 ;
      uint32_t nxp_int_async         : 1  ;
      uint32_t nxp_int_period        : 1  ;
      uint32_t                       : 12 ;
    }inten_bm;
  };
 
  uint32_t frame_index        ; 
  uint32_t ctrl_ds_seg        ; 
  uint32_t periodic_list_base ; 
  uint32_t async_list_addr    ; 
  uint32_t nxp_tt_control     ; 
  uint32_t reserved[8]        ;
  uint32_t config_flag        ; 
 
  union {
    // mixed with RW and R/WC bits, care should be taken when writing to this register
    uint32_t portsc           ; 
    const struct {
      uint32_t current_connect_status      : 1; 
      uint32_t connect_status_change       : 1; 
      uint32_t port_enabled                : 1; 
      uint32_t port_enable_change          : 1; 
      uint32_t over_current_active         : 1; 
      uint32_t over_current_change         : 1; 
      uint32_t force_port_resume           : 1; 
      uint32_t suspend                     : 1; 
      uint32_t port_reset                  : 1; 
      uint32_t nxp_highspeed_status        : 1; 
      uint32_t line_status                 : 2; 
      uint32_t port_power                  : 1; 
      uint32_t port_owner                  : 1; 
      uint32_t port_indicator_control      : 2; 
      uint32_t port_test_control           : 4; 
      uint32_t wake_on_connect_enable      : 1; 
      uint32_t wake_on_disconnect_enable   : 1; 
      uint32_t wake_on_over_current_enable : 1; 
      uint32_t nxp_phy_clock_disable       : 1; 
      uint32_t nxp_port_force_fullspeed    : 1; 
      uint32_t TU_RESERVED                 : 1; 
      uint32_t nxp_port_speed              : 2; 
      uint32_t TU_RESERVED                 : 4;
    }portsc_bm;
  };
} ehci_registers_t;
 
//--------------------------------------------------------------------+
// Capability Registers
//--------------------------------------------------------------------+
typedef volatile struct {
  uint8_t caplength;   // 0x00
  uint8_t TU_RESERVED; // 0x01
  uint16_t hciversion; // 0x02
 
  union {
    uint32_t hcsparams; // 0x04
    struct {
      uint32_t num_ports          : 4; // [00:03]
      uint32_t port_power_control : 1; // [04]
      uint32_t TU_RESERVED        : 2; // [05:06]
      uint32_t port_route_rule    : 1; // [07]
      uint32_t n_pcc              : 4; // [08:11] Number of Ports per Companion Controller
      uint32_t n_cc               : 4; // [12:15] Number of Companion Controllers
      uint32_t port_ind           : 1; // [16] Port Indicators
      uint32_t TU_RESERVED        : 3; // [17:19]
      uint32_t n_ptt              : 4; // [20:23] ChipIdea: Number of Ports per Transaction Translator
      uint32_t n_tt               : 4; // [24:27] ChipIdea: Number of Transaction Translators
      uint32_t TU_RESERVED        : 4; // [28:31]
    } hcsparams_bm;
  };
 
  union {
    uint32_t hccparams; // 0x08
    struct {
      uint32_t addr_64bit                   : 1; // [00] 64-bit Addressing Capability
      uint32_t programmable_frame_list_flag : 1; // [01] Programmable Frame List Flag
      uint32_t async_park_cap               : 1; // [02] Asynchronous Schedule Park Capability
      uint32_t TU_RESERVED                  : 1; // [03]
      uint32_t iso_schedule_threshold       : 4; // [4:7] Isochronous Scheduling Threshold
      uint32_t eecp                         : 8; // [8:15] EHCI Extended Capabilities Pointer
      uint32_t TU_RESERVED                  : 16;// [16:31]
    } hccparams_bm;
  };
 
  uint32_t hcsp_portroute; // 0x0C HCSP Port Route Register
} ehci_cap_registers_t;
 
TU_VERIFY_STATIC(sizeof(ehci_cap_registers_t) == 16, "size is not correct");
 
#ifdef __cplusplus
 }
#endif
 
#endif /* _TUSB_EHCI_H_ */