^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) PHY subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) :Author: Kishon Vijay Abraham I <kishon@ti.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) This document explains the Generic PHY Framework along with the APIs provided,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) and how-to-use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) *PHY* is the abbreviation for physical layer. It is used to connect a device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) to the physical medium e.g., the USB controller has a PHY to provide functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) such as serialization, de-serialization, encoding, decoding and is responsible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) for obtaining the required data transmission rate. Note that some USB
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) controllers have PHY functionality embedded into it and others use an external
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) PHY. Other peripherals that use PHY include Wireless LAN, Ethernet,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) SATA etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) The intention of creating this framework is to bring the PHY drivers spread
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) all over the Linux kernel to drivers/phy to increase code re-use and for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) better code maintainability.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) This framework will be of use only to devices that use external PHY (PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) functionality is not embedded within the controller).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Registering/Unregistering the PHY provider
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ==========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) PHY provider refers to an entity that implements one or more PHY instances.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) For the simple case where the PHY provider implements only a single instance of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) the PHY, the framework provides its own implementation of of_xlate in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) of_phy_simple_xlate. If the PHY provider implements multiple instances, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) should provide its own implementation of of_xlate. of_xlate is used only for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) dt boot case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) #define of_phy_provider_register(dev, xlate) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) __of_phy_provider_register((dev), NULL, THIS_MODULE, (xlate))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) #define devm_of_phy_provider_register(dev, xlate) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) __devm_of_phy_provider_register((dev), NULL, THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) (xlate))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) of_phy_provider_register and devm_of_phy_provider_register macros can be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) register the phy_provider and it takes device and of_xlate as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) arguments. For the dt boot case, all PHY providers should use one of the above
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 2 macros to register the PHY provider.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Often the device tree nodes associated with a PHY provider will contain a set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) of children that each represent a single PHY. Some bindings may nest the child
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) nodes within extra levels for context and extensibility, in which case the low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) level of_phy_provider_register_full() and devm_of_phy_provider_register_full()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) macros can be used to override the node containing the children.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) #define of_phy_provider_register_full(dev, children, xlate) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) __of_phy_provider_register(dev, children, THIS_MODULE, xlate)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) #define devm_of_phy_provider_register_full(dev, children, xlate) \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) __devm_of_phy_provider_register_full(dev, children,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) THIS_MODULE, xlate)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) void devm_of_phy_provider_unregister(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) struct phy_provider *phy_provider);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) void of_phy_provider_unregister(struct phy_provider *phy_provider);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) devm_of_phy_provider_unregister and of_phy_provider_unregister can be used to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) unregister the PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) Creating the PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) The PHY driver should create the PHY in order for other peripheral controllers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) to make use of it. The PHY framework provides 2 APIs to create the PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) struct phy *phy_create(struct device *dev, struct device_node *node,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) const struct phy_ops *ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) struct phy *devm_phy_create(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) struct device_node *node,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) const struct phy_ops *ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) The PHY drivers can use one of the above 2 APIs to create the PHY by passing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) the device pointer and phy ops.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) phy_ops is a set of function pointers for performing PHY operations such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) init, exit, power_on and power_off.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Inorder to dereference the private data (in phy_ops), the phy provider driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) phy_ops to get back the private data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) 4. Getting a reference to the PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) Before the controller can make use of the PHY, it has to get a reference to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) it. This framework provides the following APIs to get a reference to the PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) struct phy *phy_get(struct device *dev, const char *string);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) struct phy *phy_optional_get(struct device *dev, const char *string);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) struct phy *devm_phy_get(struct device *dev, const char *string);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) struct phy *devm_phy_optional_get(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) const char *string);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) struct phy *devm_of_phy_get_by_index(struct device *dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) struct device_node *np,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) int index);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) phy_get, phy_optional_get, devm_phy_get and devm_phy_optional_get can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) be used to get the PHY. In the case of dt boot, the string arguments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) should contain the phy name as given in the dt data and in the case of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) non-dt boot, it should contain the label of the PHY. The two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) devm_phy_get associates the device with the PHY using devres on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) successful PHY get. On driver detach, release function is invoked on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) the devres data and devres data is freed. phy_optional_get and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) devm_phy_optional_get should be used when the phy is optional. These
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) two functions will never return -ENODEV, but instead returns NULL when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) the phy cannot be found.Some generic drivers, such as ehci, may use multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) phys and for such drivers referencing phy(s) by name(s) does not make sense. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) this case, devm_of_phy_get_by_index can be used to get a phy reference based on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) the index.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) It should be noted that NULL is a valid phy reference. All phy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) consumer calls on the NULL phy become NOPs. That is the release calls,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) the phy_init() and phy_exit() calls, and phy_power_on() and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) phy_power_off() calls are all NOP when applied to a NULL phy. The NULL
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) phy is useful in devices for handling optional phy devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) Releasing a reference to the PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) When the controller no longer needs the PHY, it has to release the reference
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) to the PHY it has obtained using the APIs mentioned in the above section. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) PHY framework provides 2 APIs to release a reference to the PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) void phy_put(struct phy *phy);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) void devm_phy_put(struct device *dev, struct phy *phy);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) Both these APIs are used to release a reference to the PHY and devm_phy_put
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) destroys the devres associated with this PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) Destroying the PHY
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) When the driver that created the PHY is unloaded, it should destroy the PHY it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) created using one of the following 2 APIs::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) void phy_destroy(struct phy *phy);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) void devm_phy_destroy(struct device *dev, struct phy *phy);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) Both these APIs destroy the PHY and devm_phy_destroy destroys the devres
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) associated with this PHY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) PM Runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) This subsystem is pm runtime enabled. So while creating the PHY,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) pm_runtime_enable of the phy device created by this subsystem is called and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) while destroying the PHY, pm_runtime_disable is called. Note that the phy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) device created by this subsystem will be a child of the device that calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) phy_create (PHY provider device).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) So pm_runtime_get_sync of the phy_device created by this subsystem will invoke
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) pm_runtime_get_sync of PHY provider device because of parent-child relationship.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) It should also be noted that phy_power_on and phy_power_off performs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) phy_pm_runtime_get_sync and phy_pm_runtime_put respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) There are exported APIs like phy_pm_runtime_get, phy_pm_runtime_get_sync,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) phy_pm_runtime_put, phy_pm_runtime_put_sync, phy_pm_runtime_allow and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) phy_pm_runtime_forbid for performing PM operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) PHY Mappings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) In order to get reference to a PHY without help from DeviceTree, the framework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) offers lookups which can be compared to clkdev that allow clk structures to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) bound to devices. A lookup can be made during runtime when a handle to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) struct phy already exists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) The framework offers the following API for registering and unregistering the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) lookups::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) int phy_create_lookup(struct phy *phy, const char *con_id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) const char *dev_id);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) void phy_remove_lookup(struct phy *phy, const char *con_id,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) const char *dev_id);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) DeviceTree Binding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) The documentation for PHY dt binding can be found @
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) Documentation/devicetree/bindings/phy/phy-bindings.txt
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags