UsbDevice.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 USBDEVICE_H
#define USBDEVICE_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/OperationBarrier.h"
#include "pedigree/kernel/processor/types.h"
#include "pedigree/kernel/utilities/String.h"
#include "pedigree/kernel/utilities/Vector.h"
#include "pedigree/kernel/utilities/utility.h"
 
#include <config.h>
 
#include "modules/system/usb/Usb.h"
 
class UsbDeviceContainer;
class UsbHub;
class UsbInterruptInHandle;
class UsbPnP;
struct UsbDeviceDescriptor;
struct UsbEndpointDescriptor;
struct UsbInterfaceDescriptor;
 
class EXPORTED_PUBLIC UsbDevice {
  friend class UsbDeviceContainer;
  friend class UsbPnP;
 
 public:
  struct Setup {
    inline Setup(uint8_t requestType, uint8_t request, uint16_t value, uint16_t index,
                 uint16_t length)
        : nRequestType(requestType),
          nRequest(request),
          nValue(value),
          nIndex(index),
          nLength(length) {}
 
    uint8_t nRequestType;
    uint8_t nRequest;
    uint16_t nValue;
    uint16_t nIndex;
    uint16_t nLength;
  } PACKED;
 
  struct UnknownDescriptor {
    inline UnknownDescriptor(uint8_t* pBuffer, uint8_t type, size_t length)
        : nType(type), nLength(length) {
      pDescriptor = new uint8_t[nLength];
      MemoryCopy(pDescriptor, pBuffer, nLength);
    }
 
    ~UnknownDescriptor() {
      delete[] static_cast<uint8_t*>(pDescriptor);
    }
 
    void* pDescriptor;
    uint8_t nType;
    size_t nLength;
  };
 
  struct Endpoint {
    Endpoint(UsbEndpointDescriptor* pDescriptor, UsbSpeed speed);
 
    enum TransferTypes { Control = 0, Isochronus = 1, Bulk = 2, Interrupt = 3 };
 
    uint8_t nEndpoint;
    bool bIn;
    bool bOut;
    uint8_t nTransferType;
    uint16_t nMaxPacketSize;
    uint8_t nInterval;
    uint8_t nTransactions;
    uint8_t nMaxBurst = 0;
    uint8_t nStreams = 0;
    uint16_t nBytesPerInterval = 0;
    bool hasCompanion = false;
 
    bool bDataToggle;
  };
 
  struct Interface {
    Interface(UsbInterfaceDescriptor* pDescriptor);
    ~Interface();
 
    uint8_t nInterface;
    uint8_t nAlternateSetting;
    uint8_t nClass;
    uint8_t nSubclass;
    uint8_t nProtocol;
    uint8_t nString;
 
    Vector<Endpoint*> endpointList;
    Vector<UnknownDescriptor*> otherDescriptorList;
    String sString;
  };
 
  struct ConfigDescriptor {
    ConfigDescriptor(void* pConfigBuffer, size_t nConfigLength, UsbSpeed speed);
    ~ConfigDescriptor();
 
    uint8_t nConfig;
    uint8_t nString;
    bool valid;
 
    Vector<Interface*> interfaceList;
    Vector<UnknownDescriptor*> otherDescriptorList;
    String sString;
  };
 
  struct DeviceDescriptor {
    DeviceDescriptor(UsbDeviceDescriptor* pDescriptor);
    ~DeviceDescriptor();
 
    void retain();
    void release();
 
    uint16_t nBcdUsbRelease;
    uint8_t nClass;
    uint8_t nSubclass;
    uint8_t nProtocol;
    uint8_t nMaxControlPacketSize;
    uint16_t nVendorId;
    uint16_t nProductId;
    uint16_t nBcdDeviceRelease;
    uint8_t nVendorString;
    uint8_t nProductString;
    uint8_t nSerialString;
    uint8_t nConfigurations;
 
    Vector<ConfigDescriptor*> configList;
    String sVendor;
    String sProduct;
    String sSerial;
 
   private:
    Atomic<size_t> m_References;
  };
 
  struct DeviceQualifier {
    uint16_t nVersion;
    uint8_t nClass;
    uint8_t nSubclass;
    uint8_t nProtocol;
    uint8_t nMaxControlPacketSize;
    uint8_t nConfigurations;
    uint8_t nRsvd;
  } PACKED;
 
  enum UsbState { Connected = 0, Addressed, HasDescriptors, Configured, HasInterface, HasDriver };
 
  UsbDevice(UsbHub* pHub, uint8_t nPort, UsbSpeed speed);
 
  UsbDevice(UsbDevice* pDev);
 
  virtual ~UsbDevice();
 
  void initialise(uint8_t nAddress);
 
  virtual void initialiseDriver() {}
 
  virtual void getUsbDeviceName(String& str) {
    str.assign("Generic USB Device", 19);
  }
 
  inline uint8_t getAddress() {
    return m_nAddress;
  }
 
  inline uint8_t getPort() {
    return m_nPort;
  }
 
  UsbHub* getHub() const {
    return m_pHub;
  }
 
  inline UsbSpeed getSpeed() {
    return m_Speed;
  }
 
  inline UsbState getUsbState() {
    return m_UsbState;
  }
 
  inline DeviceDescriptor* getDescriptor() {
    return m_pDescriptor;
  }
 
  inline ConfigDescriptor* getConfiguration() {
    return m_pConfiguration;
  }
 
  inline Interface* getInterface() {
    return m_pInterface;
  }
 
  void useConfiguration(uint8_t nConfig);
 
  void useInterface(uint8_t nInterface);
 
  UsbDeviceContainer* getContainer() const {
    return m_pContainer;
  }
 
  virtual bool hasSubtree() const {
    return false;
  }
 
  virtual Device* getDevice() {
    return 0;
  }
 
  virtual void prepareForDriverRetirement() {}
 
  virtual void quiesceForRetirement() {}
 
  virtual void prepareForDisconnection() {}
 
 protected:
  // Sync transfer methods
  ssize_t doSync(Endpoint* pEndpoint, UsbPid pid, uintptr_t pBuffer, size_t nBytes, size_t timeout);
  ssize_t syncIn(Endpoint* pEndpoint, uintptr_t pBuffer, size_t nBytes, size_t timeout = 5000);
  ssize_t syncOut(Endpoint* pEndpoint, uintptr_t pBuffer, size_t nBytes, size_t timeout = 5000);
 
  MUST_USE_RESULT bool addInterruptInHandler(Endpoint* pEndpoint, uintptr_t pBuffer,
                                             uint16_t nBytes, void (*pCallback)(uintptr_t, ssize_t),
                                             UsbInterruptInHandle& handle, uintptr_t pParam = 0);
 
  bool controlRequest(uint8_t nRequestType, uint8_t nRequest, uint16_t nValue, uint16_t nIndex,
                      uint16_t nLength = 0, uintptr_t pBuffer = 0, uint32_t timeout = 5000);
  ssize_t controlRequestResult(uint8_t nRequestType, uint8_t nRequest, uint16_t nValue,
                               uint16_t nIndex, uint16_t nLength = 0, uintptr_t pBuffer = 0,
                               uint32_t timeout = 5000);
 
  uint16_t getStatus();
 
  bool clearEndpointHalt(Endpoint* pEndpoint);
 
  void* getDescriptor(uint8_t nDescriptorType, uint8_t nDescriptorIndex, uint16_t nBytes,
                      uint8_t requestType = 0);
 
  uint8_t getDescriptorLength(uint8_t nDescriptorType, uint8_t nDescriptorIndex,
                              uint8_t requestType = 0);
 
  String getString(uint8_t nString);
 
  uint8_t m_nAddress;
  uint16_t m_ControlPacketSize;
 
  uint8_t m_nPort;
 
  uint8_t m_nRootPort;
  size_t m_nRootPortGeneration;
 
  UsbSpeed m_Speed;
 
  UsbState m_UsbState;
 
  DeviceDescriptor* m_pDescriptor;
 
  ConfigDescriptor* m_pConfiguration;
 
  Interface* m_pInterface;
 
  UsbHub* m_pHub;
 
  UsbDeviceContainer* m_pContainer;
 
 private:
  UsbDevice(const UsbDevice& d);
  const UsbDevice& operator=(const UsbDevice& d);
};
 
class UsbDeviceContainer : public Device {
 public:
  UsbDeviceContainer(UsbDevice* pDev);
  virtual ~UsbDeviceContainer();
 
  EXPORTED_PUBLIC UsbDevice* getUsbDevice() const;
 
  MUST_USE_RESULT bool replaceUsbDevice(UsbDevice* pDev);
 
  virtual void getName(String& str);
 
  virtual Type getType();
 
  virtual void dump(String& str);
 
 private:
  friend class UsbHub;
  friend class UsbPnP;
 
  bool tryAcquireProbe(OperationBarrier::Lease& lease);
  void closeProbeAdmission();
  void waitForProbes();
 
  void attachSubtree(UsbDevice* pDev);
  void destroyUsbDevice(UsbDevice* pDev);
 
  UsbDevice* m_pUsbDevice;
  OperationBarrier m_ProbeOperations;
  Mutex m_ProbeLock;
  Atomic<UsbPnP*> m_BindingRegistry;
  void* m_BindingOwner;
  OperationBarrier::Lease m_BindingLease;
  UsbDeviceContainer* m_PreviousBinding;
  UsbDeviceContainer* m_NextBinding;
};
 
#if HOSTED && PEDIGREE_HOSTED_SMOKE_TESTS
EXPORTED_PUBLIC bool runHostedUsbContainerOwnershipRegression();
#endif
 
#endif