[PATCH 56/57] docs: phy: convert samsung-usb2.txt to ReST format

Mauro Carvalho Chehab
2019-04-16T02:59:16Z

In order to merge it into a Sphinx book, we need first to
convert to ReST.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
Documentation/phy/samsung-usb2.txt | 60 +++++++++++++++---------------
1 file changed, 31 insertions(+), 29 deletions(-)

diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.txt
index ed12d437189d..c48c8b9797b9 100644
--- a/Documentation/phy/samsung-usb2.txt
+++ b/Documentation/phy/samsung-usb2.txt
@@ -1,9 +1,9 @@
-.------------------------------------------------------------------------------+
-| Samsung USB 2.0 PHY adaptation layer |
-+-----------------------------------------------------------------------------+'
+====================================
+Samsung USB 2.0 PHY adaptation layer
+====================================

-| 1. Description
-+----------------
+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
@@ -14,8 +14,8 @@ the PHY powering up process had to be altered. This adaptation layer is
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
@@ -32,44 +32,45 @@ with added support for many special cases.
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 {
+ struct samsung_usb2_phy_config {
const struct samsung_usb2_common_phy *phys;
int (*rate_to_clk)(unsigned long, u32 *);
unsigned int num_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 = {
+ const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
.has_mode_switch = 0,
.num_phys = EXYNOS4210_NUM_PHYS,
.phys = exynos4210_phys,
.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[] = {
+ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
{
.label = "device",
.id = EXYNOS4210_DEVICE,
@@ -95,29 +96,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
.power_off = exynos4210_power_off,
},
{},
-};
+ };
+
+- `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
+ #ifdef CONFIG_PHY_EXYNOS4210_USB2
{
.compatible = "samsung,exynos4210-usb2-phy",
.data = &exynos4210_usb2_phy_config,
},
-#endif
+ #endif

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
+ config PHY_EXYNOS4210_USB2
bool "Support for Exynos 4210"
depends on PHY_SAMSUNG_USB2
depends on CPU_EXYNOS4210
@@ -128,8 +130,8 @@ config PHY_EXYNOS4210_USB2
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
+ obj-$(CONFIG_PHY_EXYNOS4210_USB2) += phy-exynos4210-usb2.o

After completing these steps the support for the new SoC should be ready.
--
2.20.1