Commit ff764963 authored by Kishon Vijay Abraham I's avatar Kishon Vijay Abraham I Committed by Greg Kroah-Hartman

drivers: phy: add generic PHY framework

The PHY framework provides a set of APIs for the PHY drivers to
create/destroy a PHY and APIs for the PHY users to obtain a reference to the
PHY with or without using phandle. For dt-boot, the PHY drivers should
also register *PHY provider* with the framework.

PHY drivers should create the PHY by passing id and ops like init, exit,
power_on and power_off. This framework is also pm runtime enabled.

The documentation for the generic PHY framework is added in
Documentation/phy.txt and the documentation for dt binding can be found at
Documentation/devicetree/bindings/phy/phy-bindings.txt

Cc: Tomasz Figa <t.figa@samsung.com>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: default avatarKishon Vijay Abraham I <kishon@ti.com>
Acked-by: default avatarFelipe Balbi <balbi@ti.com>
Tested-by: default avatarSylwester Nawrocki <s.nawrocki@samsung.com>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 6741448e
This document explains only the device tree data binding. For general
information about PHY subsystem refer to Documentation/phy.txt
PHY device node
===============
Required Properties:
#phy-cells: Number of cells in a PHY specifier; The meaning of all those
cells is defined by the binding for the phy node. The PHY
provider can use the values in cells to find the appropriate
PHY.
For example:
phys: phy {
compatible = "xxx";
reg = <...>;
.
.
#phy-cells = <1>;
.
.
};
That node describes an IP block (PHY provider) that implements 2 different PHYs.
In order to differentiate between these 2 PHYs, an additonal specifier should be
given while trying to get a reference to it.
PHY user node
=============
Required Properties:
phys : the phandle for the PHY device (used by the PHY subsystem)
phy-names : the names of the PHY corresponding to the PHYs present in the
*phys* phandle
Example 1:
usb1: usb_otg_ss@xxx {
compatible = "xxx";
reg = <xxx>;
.
.
phys = <&usb2_phy>, <&usb3_phy>;
phy-names = "usb2phy", "usb3phy";
.
.
};
This node represents a controller that uses two PHYs, one for usb2 and one for
usb3.
Example 2:
usb2: usb_otg_ss@xxx {
compatible = "xxx";
reg = <xxx>;
.
.
phys = <&phys 1>;
phy-names = "usbphy";
.
.
};
This node represents a controller that uses one of the PHYs of the PHY provider
device defined previously. Note that the phy handle has an additional specifier
"1" to differentiate between the two PHYs.
PHY SUBSYSTEM
Kishon Vijay Abraham I <kishon@ti.com>
This document explains the Generic PHY Framework along with the APIs provided,
and how-to-use.
1. Introduction
*PHY* is the abbreviation for physical layer. It is used to connect a device
to the physical medium e.g., the USB controller has a PHY to provide functions
such as serialization, de-serialization, encoding, decoding and is responsible
for obtaining the required data transmission rate. Note that some USB
controllers have PHY functionality embedded into it and others use an external
PHY. Other peripherals that use PHY include Wireless LAN, Ethernet,
SATA etc.
The intention of creating this framework is to bring the PHY drivers spread
all over the Linux kernel to drivers/phy to increase code re-use and for
better code maintainability.
This framework will be of use only to devices that use external PHY (PHY
functionality is not embedded within the controller).
2. Registering/Unregistering the PHY provider
PHY provider refers to an entity that implements one or more PHY instances.
For the simple case where the PHY provider implements only a single instance of
the PHY, the framework provides its own implementation of of_xlate in
of_phy_simple_xlate. If the PHY provider implements multiple instances, it
should provide its own implementation of of_xlate. of_xlate is used only for
dt boot case.
#define of_phy_provider_register(dev, xlate) \
__of_phy_provider_register((dev), THIS_MODULE, (xlate))
#define devm_of_phy_provider_register(dev, xlate) \
__devm_of_phy_provider_register((dev), THIS_MODULE, (xlate))
of_phy_provider_register and devm_of_phy_provider_register macros can be used to
register the phy_provider and it takes device and of_xlate as
arguments. For the dt boot case, all PHY providers should use one of the above
2 macros to register the PHY provider.
void devm_of_phy_provider_unregister(struct device *dev,
struct phy_provider *phy_provider);
void of_phy_provider_unregister(struct phy_provider *phy_provider);
devm_of_phy_provider_unregister and of_phy_provider_unregister can be used to
unregister the PHY.
3. Creating the PHY
The PHY driver should create the PHY in order for other peripheral controllers
to make use of it. The PHY framework provides 2 APIs to create the PHY.
struct phy *phy_create(struct device *dev, const struct phy_ops *ops,
struct phy_init_data *init_data);
struct phy *devm_phy_create(struct device *dev, const struct phy_ops *ops,
struct phy_init_data *init_data);
The PHY drivers can use one of the above 2 APIs to create the PHY by passing
the device pointer, phy ops and init_data.
phy_ops is a set of function pointers for performing PHY operations such as
init, exit, power_on and power_off. *init_data* is mandatory to get a reference
to the PHY in the case of non-dt boot. See section *Board File Initialization*
on how init_data should be used.
Inorder to dereference the private data (in phy_ops), the phy provider driver
can use phy_set_drvdata() after creating the PHY and use phy_get_drvdata() in
phy_ops to get back the private data.
4. Getting a reference to the PHY
Before the controller can make use of the PHY, it has to get a reference to
it. This framework provides the following APIs to get a reference to the PHY.
struct phy *phy_get(struct device *dev, const char *string);
struct phy *devm_phy_get(struct device *dev, const char *string);
phy_get and devm_phy_get can be used to get the PHY. In the case of dt boot,
the string arguments should contain the phy name as given in the dt data and
in the case of non-dt boot, it should contain the label of the PHY.
The only difference between the two APIs is that devm_phy_get associates the
device with the PHY using devres on successful PHY get. On driver detach,
release function is invoked on the the devres data and devres data is freed.
5. Releasing a reference to the PHY
When the controller no longer needs the PHY, it has to release the reference
to the PHY it has obtained using the APIs mentioned in the above section. The
PHY framework provides 2 APIs to release a reference to the PHY.
void phy_put(struct phy *phy);
void devm_phy_put(struct device *dev, struct phy *phy);
Both these APIs are used to release a reference to the PHY and devm_phy_put
destroys the devres associated with this PHY.
6. Destroying the PHY
When the driver that created the PHY is unloaded, it should destroy the PHY it
created using one of the following 2 APIs.
void phy_destroy(struct phy *phy);
void devm_phy_destroy(struct device *dev, struct phy *phy);
Both these APIs destroy the PHY and devm_phy_destroy destroys the devres
associated with this PHY.
7. PM Runtime
This subsystem is pm runtime enabled. So while creating the PHY,
pm_runtime_enable of the phy device created by this subsystem is called and
while destroying the PHY, pm_runtime_disable is called. Note that the phy
device created by this subsystem will be a child of the device that calls
phy_create (PHY provider device).
So pm_runtime_get_sync of the phy_device created by this subsystem will invoke
pm_runtime_get_sync of PHY provider device because of parent-child relationship.
It should also be noted that phy_power_on and phy_power_off performs
phy_pm_runtime_get_sync and phy_pm_runtime_put respectively.
There are exported APIs like phy_pm_runtime_get, phy_pm_runtime_get_sync,
phy_pm_runtime_put, phy_pm_runtime_put_sync, phy_pm_runtime_allow and
phy_pm_runtime_forbid for performing PM operations.
8. Board File Initialization
Certain board file initialization is necessary in order to get a reference
to the PHY in the case of non-dt boot.
Say we have a single device that implements 3 PHYs that of USB, SATA and PCIe,
then in the board file the following initialization should be done.
struct phy_consumer consumers[] = {
PHY_CONSUMER("dwc3.0", "usb"),
PHY_CONSUMER("pcie.0", "pcie"),
PHY_CONSUMER("sata.0", "sata"),
};
PHY_CONSUMER takes 2 parameters, first is the device name of the controller
(PHY consumer) and second is the port name.
struct phy_init_data init_data = {
.consumers = consumers,
.num_consumers = ARRAY_SIZE(consumers),
};
static const struct platform_device pipe3_phy_dev = {
.name = "pipe3-phy",
.id = -1,
.dev = {
.platform_data = {
.init_data = &init_data,
},
},
};
then, while doing phy_create, the PHY driver should pass this init_data
phy_create(dev, ops, pdata->init_data);
and the controller driver (phy consumer) should pass the port name along with
the device to get a reference to the PHY
phy_get(dev, "pcie");
9. DeviceTree Binding
The documentation for PHY dt binding can be found @
Documentation/devicetree/bindings/phy/phy-bindings.txt
......@@ -3654,6 +3654,14 @@ S: Maintained
F: include/asm-generic/
F: include/uapi/asm-generic/
GENERIC PHY FRAMEWORK
M: Kishon Vijay Abraham I <kishon@ti.com>
L: linux-kernel@vger.kernel.org
T: git git://git.kernel.org/pub/scm/linux/kernel/git/kishon/linux-phy.git
S: Supported
F: drivers/phy/
F: include/linux/phy/
GENERIC UIO DRIVER FOR PCI DEVICES
M: "Michael S. Tsirkin" <mst@redhat.com>
L: kvm@vger.kernel.org
......
......@@ -166,4 +166,6 @@ source "drivers/reset/Kconfig"
source "drivers/fmc/Kconfig"
source "drivers/phy/Kconfig"
endmenu
......@@ -8,6 +8,8 @@
obj-y += irqchip/
obj-y += bus/
obj-$(CONFIG_GENERIC_PHY) += phy/
# GPIO must come after pinctrl as gpios may need to mux pins etc
obj-y += pinctrl/
obj-y += gpio/
......
#
# PHY
#
menu "PHY Subsystem"
config GENERIC_PHY
tristate "PHY Core"
help
Generic PHY support.
This framework is designed to provide a generic interface for PHY
devices present in the kernel. This layer will have the generic
API by which phy drivers can create PHY using the phy framework and
phy users can obtain reference to the PHY. All the users of this
framework should select this config.
endmenu
#
# Makefile for the phy drivers.
#
obj-$(CONFIG_GENERIC_PHY) += phy-core.o
This diff is collapsed.
/*
* phy.h -- generic phy header file
*
* Copyright (C) 2013 Texas Instruments Incorporated - http://www.ti.com
*
* Author: Kishon Vijay Abraham I <kishon@ti.com>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*/
#ifndef __DRIVERS_PHY_H
#define __DRIVERS_PHY_H
#include <linux/err.h>
#include <linux/of.h>
#include <linux/device.h>
#include <linux/pm_runtime.h>
struct phy;
/**
* struct phy_ops - set of function pointers for performing phy operations
* @init: operation to be performed for initializing phy
* @exit: operation to be performed while exiting
* @power_on: powering on the phy
* @power_off: powering off the phy
* @owner: the module owner containing the ops
*/
struct phy_ops {
int (*init)(struct phy *phy);
int (*exit)(struct phy *phy);
int (*power_on)(struct phy *phy);
int (*power_off)(struct phy *phy);
struct module *owner;
};
/**
* struct phy - represents the phy device
* @dev: phy device
* @id: id of the phy device
* @ops: function pointers for performing phy operations
* @init_data: list of PHY consumers (non-dt only)
* @mutex: mutex to protect phy_ops
* @init_count: used to protect when the PHY is used by multiple consumers
* @power_count: used to protect when the PHY is used by multiple consumers
*/
struct phy {
struct device dev;
int id;
const struct phy_ops *ops;
struct phy_init_data *init_data;
struct mutex mutex;
int init_count;
int power_count;
};
/**
* struct phy_provider - represents the phy provider
* @dev: phy provider device
* @owner: the module owner having of_xlate
* @of_xlate: function pointer to obtain phy instance from phy pointer
* @list: to maintain a linked list of PHY providers
*/
struct phy_provider {
struct device *dev;
struct module *owner;
struct list_head list;
struct phy * (*of_xlate)(struct device *dev,
struct of_phandle_args *args);
};
/**
* struct phy_consumer - represents the phy consumer
* @dev_name: the device name of the controller that will use this PHY device
* @port: name given to the consumer port
*/
struct phy_consumer {
const char *dev_name;
const char *port;
};
/**
* struct phy_init_data - contains the list of PHY consumers
* @num_consumers: number of consumers for this PHY device
* @consumers: list of PHY consumers
*/
struct phy_init_data {
unsigned int num_consumers;
struct phy_consumer *consumers;
};
#define PHY_CONSUMER(_dev_name, _port) \
{ \
.dev_name = _dev_name, \
.port = _port, \
}
#define to_phy(dev) (container_of((dev), struct phy, dev))
#define of_phy_provider_register(dev, xlate) \
__of_phy_provider_register((dev), THIS_MODULE, (xlate))
#define devm_of_phy_provider_register(dev, xlate) \
__devm_of_phy_provider_register((dev), THIS_MODULE, (xlate))
static inline void phy_set_drvdata(struct phy *phy, void *data)
{
dev_set_drvdata(&phy->dev, data);
}
static inline void *phy_get_drvdata(struct phy *phy)
{
return dev_get_drvdata(&phy->dev);
}
#if IS_ENABLED(CONFIG_GENERIC_PHY)
int phy_pm_runtime_get(struct phy *phy);
int phy_pm_runtime_get_sync(struct phy *phy);
int phy_pm_runtime_put(struct phy *phy);
int phy_pm_runtime_put_sync(struct phy *phy);
void phy_pm_runtime_allow(struct phy *phy);
void phy_pm_runtime_forbid(struct phy *phy);
int phy_init(struct phy *phy);
int phy_exit(struct phy *phy);
int phy_power_on(struct phy *phy);
int phy_power_off(struct phy *phy);
struct phy *phy_get(struct device *dev, const char *string);
struct phy *devm_phy_get(struct device *dev, const char *string);
void phy_put(struct phy *phy);
void devm_phy_put(struct device *dev, struct phy *phy);
struct phy *of_phy_simple_xlate(struct device *dev,
struct of_phandle_args *args);
struct phy *phy_create(struct device *dev, const struct phy_ops *ops,
struct phy_init_data *init_data);
struct phy *devm_phy_create(struct device *dev,
const struct phy_ops *ops, struct phy_init_data *init_data);
void phy_destroy(struct phy *phy);
void devm_phy_destroy(struct device *dev, struct phy *phy);
struct phy_provider *__of_phy_provider_register(struct device *dev,
struct module *owner, struct phy * (*of_xlate)(struct device *dev,
struct of_phandle_args *args));
struct phy_provider *__devm_of_phy_provider_register(struct device *dev,
struct module *owner, struct phy * (*of_xlate)(struct device *dev,
struct of_phandle_args *args));
void of_phy_provider_unregister(struct phy_provider *phy_provider);
void devm_of_phy_provider_unregister(struct device *dev,
struct phy_provider *phy_provider);
#else
static inline int phy_pm_runtime_get(struct phy *phy)
{
return -ENOSYS;
}
static inline int phy_pm_runtime_get_sync(struct phy *phy)
{
return -ENOSYS;
}
static inline int phy_pm_runtime_put(struct phy *phy)
{
return -ENOSYS;
}
static inline int phy_pm_runtime_put_sync(struct phy *phy)
{
return -ENOSYS;
}
static inline void phy_pm_runtime_allow(struct phy *phy)
{
return;
}
static inline void phy_pm_runtime_forbid(struct phy *phy)
{
return;
}
static inline int phy_init(struct phy *phy)
{
return -ENOSYS;
}
static inline int phy_exit(struct phy *phy)
{
return -ENOSYS;
}
static inline int phy_power_on(struct phy *phy)
{
return -ENOSYS;
}
static inline int phy_power_off(struct phy *phy)
{
return -ENOSYS;
}
static inline struct phy *phy_get(struct device *dev, const char *string)
{
return ERR_PTR(-ENOSYS);
}
static inline struct phy *devm_phy_get(struct device *dev, const char *string)
{
return ERR_PTR(-ENOSYS);
}
static inline void phy_put(struct phy *phy)
{
}
static inline void devm_phy_put(struct device *dev, struct phy *phy)
{
}
static inline struct phy *of_phy_simple_xlate(struct device *dev,
struct of_phandle_args *args)
{
return ERR_PTR(-ENOSYS);
}
static inline struct phy *phy_create(struct device *dev,
const struct phy_ops *ops, struct phy_init_data *init_data)
{
return ERR_PTR(-ENOSYS);
}
static inline struct phy *devm_phy_create(struct device *dev,
const struct phy_ops *ops, struct phy_init_data *init_data)
{
return ERR_PTR(-ENOSYS);
}
static inline void phy_destroy(struct phy *phy)
{
}
static inline void devm_phy_destroy(struct device *dev, struct phy *phy)
{
}
static inline struct phy_provider *__of_phy_provider_register(
struct device *dev, struct module *owner, struct phy * (*of_xlate)(
struct device *dev, struct of_phandle_args *args))
{
return ERR_PTR(-ENOSYS);
}
static inline struct phy_provider *__devm_of_phy_provider_register(struct device
*dev, struct module *owner, struct phy * (*of_xlate)(struct device *dev,
struct of_phandle_args *args))
{
return ERR_PTR(-ENOSYS);
}
static inline void of_phy_provider_unregister(struct phy_provider *phy_provider)
{
}
static inline void devm_of_phy_provider_unregister(struct device *dev,
struct phy_provider *phy_provider)
{
}
#endif
#endif /* __DRIVERS_PHY_H */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment