docs: phy: convert samsung-usb2.txt to ReST format

.------------------------------------------------------------------------------+

|			Samsung USB 2.0 PHY adaptation layer		       |

+-----------------------------------------------------------------------------+'

:orphan:

| 1. Description

+----------------

====================================

Samsung USB 2.0 PHY adaptation layer

====================================

1. Description

--------------

The architecture of the USB 2.0 PHY module in Samsung SoCs is similar

among many SoCs. In spite of the similarities it proved difficult to

a compromise between having separate drivers and having a single driver

with added support for many special cases.

| 2. Files description

+----------------------

2. Files description

--------------------

- phy-samsung-usb2.c

   This is the main file of the adaptation layer. This file contains

   driver. In addition it should contain extern declarations for

   structures that describe particular SoCs.

| 3. Supporting SoCs

+--------------------

3. Supporting SoCs

------------------

To support a new SoC a new file should be added to the drivers/phy

directory. Each SoC's configuration is stored in an instance of the

struct samsung_usb2_phy_config.

struct samsung_usb2_phy_config::

  struct samsung_usb2_phy_config {

	const struct samsung_usb2_common_phy *phys;

	bool has_mode_switch;

  };

The num_phys is the number of phys handled by the driver. *phys is an

The num_phys is the number of phys handled by the driver. `*phys` is an

array that contains the configuration for each phy. The has_mode_switch

property is a boolean flag that determines whether the SoC has USB host

and device on a single pair of pins. If so, a special register has to

be modified to change the internal routing of these pins between a USB

device or host module.

For example the configuration for Exynos 4210 is following:

For example the configuration for Exynos 4210 is following::

  const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {

	.has_mode_switch        = 0,

	.rate_to_clk		= exynos4210_rate_to_clk,

  }

- int (*rate_to_clk)(unsigned long, u32 *)

- `int (*rate_to_clk)(unsigned long, u32 *)`

	The rate_to_clk callback is to convert the rate of the clock

	used as the reference clock for the PHY module to the value

	that should be written in the hardware register.

The exynos4210_phys configuration array is as follows:

The exynos4210_phys configuration array is as follows::

  static const struct samsung_usb2_common_phy exynos4210_phys[] = {

	{

	{},

  };

- int (*power_on)(struct samsung_usb2_phy_instance *);

- int (*power_off)(struct samsung_usb2_phy_instance *);

- `int (*power_on)(struct samsung_usb2_phy_instance *);`

  `int (*power_off)(struct samsung_usb2_phy_instance *);`

	These two callbacks are used to power on and power off the phy

	by modifying appropriate registers.

Final change to the driver is adding appropriate compatible value to the

phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were

added to the struct of_device_id samsung_usb2_phy_of_match[] array:

added to the struct of_device_id samsung_usb2_phy_of_match[] array::

  #ifdef CONFIG_PHY_EXYNOS4210_USB2

	{

To add further flexibility to the driver the Kconfig file enables to

include support for selected SoCs in the compiled driver. The Kconfig

entry for Exynos 4210 is following:

entry for Exynos 4210 is following::

  config PHY_EXYNOS4210_USB2

	bool "Support for Exynos 4210"

	  phys are available - device, host, HSCI0 and HSCI1.

The newly created file that supports the new SoC has to be also added to the

Makefile. In case of Exynos 4210 the added line is following:

Makefile. In case of Exynos 4210 the added line is following::

  obj-$(CONFIG_PHY_EXYNOS4210_USB2)       += phy-exynos4210-usb2.o

L:	linux-kernel@vger.kernel.org

S:	Supported

F:	Documentation/devicetree/bindings/phy/samsung-phy.txt

F:	Documentation/phy/samsung-usb2.txt

F:	Documentation/phy/samsung-usb2.rst

F:	drivers/phy/samsung/phy-exynos4210-usb2.c

F:	drivers/phy/samsung/phy-exynos4x12-usb2.c

F:	drivers/phy/samsung/phy-exynos5250-usb2.c