UsbHub.h

/*
 * Copyright (c) 2008-2014, Pedigree Developers
 *
 * Please see the CONTRIB file in the root of the source tree for a full
 * list of contributors.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
 
#ifndef USBHUB_H
#define USBHUB_H
#include "pedigree/kernel/Atomic.h"
#include "pedigree/kernel/compiler.h"
#include "pedigree/kernel/machine/Device.h"
#include "pedigree/kernel/process/Mutex.h"
#include "pedigree/kernel/process/Semaphore.h"
#include "pedigree/kernel/processor/types.h"
#include "pedigree/kernel/utilities/ExtensibleBitmap.h"
#include "pedigree/kernel/utilities/List.h"
 
#include <config.h>
 
#include "modules/system/usb/Usb.h"
#include "modules/system/usb/UsbStartup.h"
 
class UsbHub;
class UsbDeviceContainer;
 
struct UsbInterruptInToken {
  uintptr_t transaction;
  size_t generation;
};
 
class EXPORTED_PUBLIC UsbInterruptInHandle {
 public:
  UsbInterruptInHandle();
  UsbInterruptInHandle(UsbInterruptInHandle&& other);
  ~UsbInterruptInHandle();
 
  UsbInterruptInHandle& operator=(UsbInterruptInHandle&& other);
 
  MUST_USE_RESULT bool reset();
 
  explicit operator bool() const {
    return static_cast<UsbHub*>(m_Owner) != nullptr;
  }
 
 private:
  friend class UsbHub;
 
  void adopt(UsbHub* owner, const UsbInterruptInToken& token, void (*callback)(uintptr_t, ssize_t),
             uintptr_t parameter);
 
  UsbInterruptInHandle(const UsbInterruptInHandle&) = delete;
  UsbInterruptInHandle& operator=(const UsbInterruptInHandle&) = delete;
 
  Atomic<UsbHub*> m_Owner;
  Atomic<bool> m_Resetting;
  UsbInterruptInToken m_Token;
  void (*m_Callback)(uintptr_t, ssize_t);
  uintptr_t m_Parameter;
  bool m_CancellationStarted;
};
 
class EXPORTED_PUBLIC UsbHub : public Device {
 public:
  class EXPORTED_PUBLIC StartupActivity {
   public:
    explicit StartupActivity(UsbHub* hub);
    ~StartupActivity();
    explicit operator bool() const {
      return m_Admitted;
    }
    void failed() {
      m_Outcome = UsbStartup::Outcome::Failed;
    }
    void deviceReady() {
      m_Outcome = UsbStartup::Outcome::DeviceReady;
    }
 
   private:
    StartupActivity(const StartupActivity&) = delete;
    StartupActivity& operator=(const StartupActivity&) = delete;
    UsbHub* m_Root;
    bool m_Admitted;
    UsbStartup::Outcome m_Outcome = UsbStartup::Outcome::Neutral;
  };
 
  class EXPORTED_PUBLIC ConnectionChangeSuppression {
   public:
    ConnectionChangeSuppression();
    ConnectionChangeSuppression(ConnectionChangeSuppression&& other);
    ~ConnectionChangeSuppression();
 
    ConnectionChangeSuppression& operator=(ConnectionChangeSuppression&& other);
 
    explicit operator bool() const {
      return m_Hub != nullptr;
    }
 
    void reset();
 
   private:
    friend class UsbHub;
 
    ConnectionChangeSuppression(UsbHub* hub, size_t port);
 
    ConnectionChangeSuppression(const ConnectionChangeSuppression&) = delete;
    ConnectionChangeSuppression& operator=(const ConnectionChangeSuppression&) = delete;
 
    UsbHub* m_Hub;
    size_t m_Port;
  };
 
  UsbHub();
  UsbHub(Device* p);
 
  virtual ~UsbHub();
 
  struct RootConnection {
    uint8_t port;
    size_t generation;
  };
 
  RootConnection rootConnectionForChild(uint8_t childPort) const;
  virtual bool controllerAssignsAddresses() const {
    return false;
  }
  virtual bool supportsHubDevices() const {
    return true;
  }
  virtual bool prepareDevice(uint8_t, const UsbEndpoint&) {
    return true;
  }
  virtual bool addressDevice(uint8_t, const UsbEndpoint&) {
    return false;
  }
  virtual bool resetEndpoint(const UsbEndpoint&) {
    return true;
  }
 
  virtual Type getType();
 
  virtual void addTransferToTransaction(uintptr_t pTransaction, bool bToggle, UsbPid pid,
                                        uintptr_t pBuffer, size_t nBytes) = 0;
 
  virtual uintptr_t createTransaction(UsbEndpoint endpointInfo) = 0;
 
  MUST_USE_RESULT virtual bool doAsync(uintptr_t pTransaction,
                                       void (*pCallback)(uintptr_t, ssize_t) = 0,
                                       uintptr_t pParam = 0) = 0;
 
  virtual void cancelAsyncAndDrain(uintptr_t pTransaction, void (*pCallback)(uintptr_t, ssize_t),
                                   uintptr_t pParam) = 0;
 
  MUST_USE_RESULT virtual bool addInterruptInHandler(UsbEndpoint endpointInfo, uintptr_t pBuffer,
                                                     uint16_t nBytes,
                                                     void (*pCallback)(uintptr_t, ssize_t),
                                                     UsbInterruptInHandle& handle,
                                                     uintptr_t pParam = 0) = 0;
 
  bool deviceConnected(uint8_t nPort, UsbSpeed speed);
 
  void deviceDisconnected(uint8_t nPort);
 
  ssize_t doSync(uintptr_t nTransaction, uint32_t timeout = 5000);
 
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
  static bool runHostedSyncOwnershipRegression();
 
  static bool runHostedInterruptOwnershipRegression();
 
  using ConnectionChangePendingHook = void (*)(UsbHub* hub, size_t port, size_t observedState);
  using ConnectionChangeReplayWaitHook = void (*)(UsbHub* hub, size_t port);
  static void setConnectionChangePendingHookForTest(ConnectionChangePendingHook hook);
  static void setConnectionChangeReplayWaitHookForTest(ConnectionChangeReplayWaitHook hook);
#endif
 
#if PEDIGREE_CONCURRENCY_SMOKE_TESTS
  static bool runQemuInterruptOwnershipRegression();
#endif
 
  // void getDeviceByIds(size_t vendor, size_t product, void
  // (*pCallback)(class UsbDevice *));
 
  virtual bool portReset(uint8_t nPort, bool bErrorResponse = false) = 0;
 
 private:
  bool deviceConnectedAdmitted(uint8_t nPort, UsbSpeed speed);
#if (HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS) || PEDIGREE_CONCURRENCY_SMOKE_TESTS
  static bool runInterruptOwnershipRegression();
  static int retireProbeSubtreeForTest(void* parameter);
#endif
 
  struct SyncParam {
    inline SyncParam() : semaphore(0), nResult(-1), owners(2) {}
 
    ~SyncParam();
    void releaseOwner();
 
    Semaphore semaphore;
    ssize_t nResult;
    Atomic<size_t> owners;
  };
 
  static void syncCallback(uintptr_t pParam, ssize_t ret);
 
  void deviceDisconnectedLocked(uint8_t nPort);
  void retirePortContainersLocked(uint8_t nPort, bool* retiredAddresses,
                                  bool* pinnedSubtreeAddresses = nullptr);
  void releaseRetiredAddressesLocked(uint8_t nPort, const bool* retiredAddresses);
  void retainAddressLocked(size_t address);
  void releaseAddressLocked(size_t address);
  void retainAddressesLocked(const bool* addresses);
  void releaseAddressesLocked(const bool* addresses);
  static void collectUsbAddresses(Device* device, bool* addresses);
  static void collectImmediateUsbContainers(Device* device, List<UsbDeviceContainer*>& containers);
  static void drainSubtreeProbeAdmissions(UsbDeviceContainer* container);
  static void prepareSubtreeForDisconnection(UsbDeviceContainer* container);
  void releaseConnectionChangeSuppression(size_t port);
 
  ExtensibleBitmap m_UsedAddresses;
 
  size_t m_AddressReferences[128] = {};
 
  Mutex m_EnumerationLock;
 
  Mutex m_TopologyLock;
 
  static constexpr size_t ConnectionChangePortCount = 32;
  static constexpr size_t ConnectionChangePending =
      static_cast<size_t>(1) << ((sizeof(size_t) * 8) - static_cast<size_t>(1));
  static constexpr size_t ConnectionChangeCountMask = ~ConnectionChangePending;
 
  Atomic<size_t> m_ConnectionChangeStates[ConnectionChangePortCount];
 
  UsbHub* m_RootHub;
 
  bool m_IsRootHub;
 
  uint8_t m_RootPort;
 
  size_t m_RootPortGeneration;
 
  bool m_RetainDisconnectedAddresses = false;
 
 protected:
  virtual bool portSpeed(uint8_t, UsbSpeed&) {
    return true;
  }
 
  virtual bool beginStartupActivity() {
    return true;
  }
  virtual void endStartupActivity(UsbStartup::Outcome) {}
 
  friend class UsbInterruptInHandle;
  virtual void releaseDeviceAddress(uint8_t) {}
 
  MUST_USE_RESULT bool publishInterruptInHandle(UsbInterruptInHandle& handle,
                                                const UsbInterruptInToken& token,
                                                void (*callback)(uintptr_t, ssize_t),
                                                uintptr_t parameter);
 
  MUST_USE_RESULT virtual bool cancelInterruptInAndDrain(const UsbInterruptInToken& token,
                                                         void (*callback)(uintptr_t, ssize_t),
                                                         uintptr_t parameter,
                                                         bool producerAlreadyStopped) = 0;
 
  virtual bool inInterruptCallbackContext() const {
    return false;
  }
 
  void disconnectAllDevices();
 
  void retainDisconnectedAddressesUntilControllerTeardown();
 
  void attachToUpstreamHub(UsbHub* upstream, const RootConnection& connection);
 
  UsbHub* rootHub() const {
    return m_RootHub;
  }
 
  MUST_USE_RESULT bool suppressConnectionChanges(size_t port,
                                                 ConnectionChangeSuppression& suppression);
 
  MUST_USE_RESULT bool deferConnectionChangeIfSuppressed(size_t port);
 
  virtual void replaySuppressedConnectionChange(size_t port);
 
  virtual size_t currentRootPortGeneration(size_t port) const {
    (void)port;
    return 0;
  }
};
 
#endif