Documentation/phy/samsung-usb2.rst

   1 :orphan:
   2
   3 ====================================
   4 Samsung USB 2.0 PHY adaptation layer
   5 ====================================
   6
   7 1. Description
   8 --------------
   9
  10 The architecture of the USB 2.0 PHY module in Samsung SoCs is similar
  11 among many SoCs. In spite of the similarities it proved difficult to
  12 create a one driver that would fit all these PHY controllers. Often
  13 the differences were minor and were found in particular bits of the
  14 registers of the PHY. In some rare cases the order of register writes or
  15 the PHY powering up process had to be altered. This adaptation layer is
  16 a compromise between having separate drivers and having a single driver
  17 with added support for many special cases.
  18
  19 2. Files description
  20 --------------------
  21
  22 - phy-samsung-usb2.c
  23    This is the main file of the adaptation layer. This file contains
  24    the probe function and provides two callbacks to the Generic PHY
  25    Framework. This two callbacks are used to power on and power off the
  26    phy. They carry out the common work that has to be done on all version
  27    of the PHY module. Depending on which SoC was chosen they execute SoC
  28    specific callbacks. The specific SoC version is selected by choosing
  29    the appropriate compatible string. In addition, this file contains
  30    struct of_device_id definitions for particular SoCs.
  31
  32 - phy-samsung-usb2.h
  33    This is the include file. It declares the structures used by this
  34    driver. In addition it should contain extern declarations for
  35    structures that describe particular SoCs.
  36
  37 3. Supporting SoCs
  38 ------------------
  39
  40 To support a new SoC a new file should be added to the drivers/phy
  41 directory. Each SoC's configuration is stored in an instance of the
  42 struct samsung_usb2_phy_config::
  43
  44   struct samsung_usb2_phy_config {
  45         const struct samsung_usb2_common_phy *phys;
  46         int (*rate_to_clk)(unsigned long, u32 *);
  47         unsigned int num_phys;
  48         bool has_mode_switch;
  49   };
  50
  51 The num_phys is the number of phys handled by the driver. `*phys` is an
  52 array that contains the configuration for each phy. The has_mode_switch
  53 property is a boolean flag that determines whether the SoC has USB host
  54 and device on a single pair of pins. If so, a special register has to
  55 be modified to change the internal routing of these pins between a USB
  56 device or host module.
  57
  58 For example the configuration for Exynos 4210 is following::
  59
  60   const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
  61         .has_mode_switch        = 0,
  62         .num_phys               = EXYNOS4210_NUM_PHYS,
  63         .phys                   = exynos4210_phys,
  64         .rate_to_clk            = exynos4210_rate_to_clk,
  65   }
  66
  67 - `int (*rate_to_clk)(unsigned long, u32 *)`
  68
  69         The rate_to_clk callback is to convert the rate of the clock
  70         used as the reference clock for the PHY module to the value
  71         that should be written in the hardware register.
  72
  73 The exynos4210_phys configuration array is as follows::
  74
  75   static const struct samsung_usb2_common_phy exynos4210_phys[] = {
  76         {
  77                 .label          = "device",
  78                 .id             = EXYNOS4210_DEVICE,
  79                 .power_on       = exynos4210_power_on,
  80                 .power_off      = exynos4210_power_off,
  81         },
  82         {
  83                 .label          = "host",
  84                 .id             = EXYNOS4210_HOST,
  85                 .power_on       = exynos4210_power_on,
  86                 .power_off      = exynos4210_power_off,
  87         },
  88         {
  89                 .label          = "hsic0",
  90                 .id             = EXYNOS4210_HSIC0,
  91                 .power_on       = exynos4210_power_on,
  92                 .power_off      = exynos4210_power_off,
  93         },
  94         {
  95                 .label          = "hsic1",
  96                 .id             = EXYNOS4210_HSIC1,
  97                 .power_on       = exynos4210_power_on,
  98                 .power_off      = exynos4210_power_off,
  99         },
 100         {},
 101   };
 102
 103 - `int (*power_on)(struct samsung_usb2_phy_instance *);`
 104   `int (*power_off)(struct samsung_usb2_phy_instance *);`
 105
 106         These two callbacks are used to power on and power off the phy
 107         by modifying appropriate registers.
 108
 109 Final change to the driver is adding appropriate compatible value to the
 110 phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were
 111 added to the struct of_device_id samsung_usb2_phy_of_match[] array::
 112
 113   #ifdef CONFIG_PHY_EXYNOS4210_USB2
 114         {
 115                 .compatible = "samsung,exynos4210-usb2-phy",
 116                 .data = &exynos4210_usb2_phy_config,
 117         },
 118   #endif
 119
 120 To add further flexibility to the driver the Kconfig file enables to
 121 include support for selected SoCs in the compiled driver. The Kconfig
 122 entry for Exynos 4210 is following::
 123
 124   config PHY_EXYNOS4210_USB2
 125         bool "Support for Exynos 4210"
 126         depends on PHY_SAMSUNG_USB2
 127         depends on CPU_EXYNOS4210
 128         help
 129           Enable USB PHY support for Exynos 4210. This option requires that
 130           Samsung USB 2.0 PHY driver is enabled and means that support for this
 131           particular SoC is compiled in the driver. In case of Exynos 4210 four
 132           phys are available - device, host, HSCI0 and HSCI1.
 133
 134 The newly created file that supports the new SoC has to be also added to the
 135 Makefile. In case of Exynos 4210 the added line is following::
 136
 137   obj-$(CONFIG_PHY_EXYNOS4210_USB2)       += phy-exynos4210-usb2.o
 138
 139 After completing these steps the support for the new SoC should be ready.