From 1945a035540e2cef0362a2e7e828f8cf547e86b8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 15 Apr 2019 19:27:55 -0300 Subject: [PATCH] docs: phy: convert samsung-usb2.txt to ReST format In order to merge it into a Sphinx book, we need first to convert to ReST. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- .../{samsung-usb2.txt => samsung-usb2.rst} | 62 ++++++++++--------- MAINTAINERS | 2 +- 2 files changed, 34 insertions(+), 30 deletions(-) rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%) diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.rst similarity index 77% rename from Documentation/phy/samsung-usb2.txt rename to Documentation/phy/samsung-usb2.rst index ed12d437189d..98b5952fcb97 100644 --- a/Documentation/phy/samsung-usb2.txt +++ b/Documentation/phy/samsung-usb2.rst @@ -1,9 +1,11 @@ -.------------------------------------------------------------------------------+ -| 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 @@ -14,8 +16,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 +34,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 +98,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 +132,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. diff --git a/MAINTAINERS b/MAINTAINERS index 96c85695b3d4..2a2d74e5d670 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -14083,7 +14083,7 @@ M: Sylwester Nawrocki 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 -- 2.34.1