1 /**
2 * @file
3 *
4 * @brief Public APIs for Ethernet PHY drivers.
5 */
6
7 /*
8 * Copyright (c) 2021 IP-Logix Inc.
9 * Copyright 2022 NXP
10 *
11 * SPDX-License-Identifier: Apache-2.0
12 */
13 #ifndef ZEPHYR_INCLUDE_DRIVERS_PHY_H_
14 #define ZEPHYR_INCLUDE_DRIVERS_PHY_H_
15
16 /**
17 * @brief Ethernet PHY Interface
18 * @defgroup ethernet_phy Ethernet PHY Interface
19 * @ingroup networking
20 * @{
21 */
22 #include <zephyr/types.h>
23 #include <zephyr/device.h>
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29 /** @brief Ethernet link speeds. */
30 enum phy_link_speed {
31 /** 10Base-T Half-Duplex */
32 LINK_HALF_10BASE_T = BIT(0),
33 /** 10Base-T Full-Duplex */
34 LINK_FULL_10BASE_T = BIT(1),
35 /** 100Base-T Half-Duplex */
36 LINK_HALF_100BASE_T = BIT(2),
37 /** 100Base-T Full-Duplex */
38 LINK_FULL_100BASE_T = BIT(3),
39 /** 1000Base-T Half-Duplex */
40 LINK_HALF_1000BASE_T = BIT(4),
41 /** 1000Base-T Full-Duplex */
42 LINK_FULL_1000BASE_T = BIT(5),
43 };
44
45 #define PHY_LINK_IS_FULL_DUPLEX(x) (x & (BIT(1) | BIT(3) | BIT(5)))
46 #define PHY_LINK_IS_SPEED_1000M(x) (x & (BIT(4) | BIT(5)))
47 #define PHY_LINK_IS_SPEED_100M(x) (x & (BIT(2) | BIT(3)))
48
49 /** @brief Link state */
50 struct phy_link_state {
51 /** Link speed */
52 enum phy_link_speed speed;
53 /** When true the link is active and connected */
54 bool is_up;
55 };
56
57 /**
58 * @typedef phy_callback_t
59 * @brief Define the callback function signature for
60 * `phy_link_callback_set()` function.
61 *
62 * @param dev PHY device structure
63 * @param state Pointer to link_state structure.
64 * @param user_data Pointer to data specified by user
65 */
66 typedef void (*phy_callback_t)(const struct device *dev,
67 struct phy_link_state *state,
68 void *user_data);
69
70 /**
71 * @cond INTERNAL_HIDDEN
72 *
73 * These are for internal use only, so skip these in
74 * public documentation.
75 */
76 __subsystem struct ethphy_driver_api {
77 /** Get link state */
78 int (*get_link)(const struct device *dev,
79 struct phy_link_state *state);
80
81 /** Configure link */
82 int (*cfg_link)(const struct device *dev,
83 enum phy_link_speed adv_speeds);
84
85 /** Set callback to be invoked when link state changes. */
86 int (*link_cb_set)(const struct device *dev, phy_callback_t cb,
87 void *user_data);
88
89 /** Read PHY register */
90 int (*read)(const struct device *dev, uint16_t reg_addr,
91 uint32_t *data);
92
93 /** Write PHY register */
94 int (*write)(const struct device *dev, uint16_t reg_addr,
95 uint32_t data);
96 };
97 /**
98 * @endcond
99 */
100
101 /**
102 * @brief Configure PHY link
103 *
104 * This route configures the advertised link speeds.
105 *
106 * @param[in] dev PHY device structure
107 * @param speeds OR'd link speeds to be advertised by the PHY
108 *
109 * @retval 0 If successful.
110 * @retval -EIO If communication with PHY failed.
111 * @retval -ENOTSUP If not supported.
112 */
phy_configure_link(const struct device * dev,enum phy_link_speed speeds)113 static inline int phy_configure_link(const struct device *dev,
114 enum phy_link_speed speeds)
115 {
116 const struct ethphy_driver_api *api =
117 (const struct ethphy_driver_api *)dev->api;
118
119 return api->cfg_link(dev, speeds);
120 }
121
122 /**
123 * @brief Get PHY link state
124 *
125 * Returns the current state of the PHY link. This can be used by
126 * to determine when a link is up and the negotiated link speed.
127 *
128 *
129 * @param[in] dev PHY device structure
130 * @param state Pointer to receive PHY state
131 *
132 * @retval 0 If successful.
133 * @retval -EIO If communication with PHY failed.
134 */
phy_get_link_state(const struct device * dev,struct phy_link_state * state)135 static inline int phy_get_link_state(const struct device *dev,
136 struct phy_link_state *state)
137 {
138 const struct ethphy_driver_api *api =
139 (const struct ethphy_driver_api *)dev->api;
140
141 return api->get_link(dev, state);
142 }
143
144 /**
145 * @brief Set link state change callback
146 *
147 * Sets a callback that is invoked when link state changes. This is the
148 * preferred method for ethernet drivers to be notified of the PHY link
149 * state change.
150 *
151 * @param[in] dev PHY device structure
152 * @param callback Callback handler
153 * @param user_data Pointer to data specified by user.
154 *
155 * @retval 0 If successful.
156 * @retval -ENOTSUP If not supported.
157 */
phy_link_callback_set(const struct device * dev,phy_callback_t callback,void * user_data)158 static inline int phy_link_callback_set(const struct device *dev,
159 phy_callback_t callback,
160 void *user_data)
161 {
162 const struct ethphy_driver_api *api =
163 (const struct ethphy_driver_api *)dev->api;
164
165 return api->link_cb_set(dev, callback, user_data);
166 }
167
168 /**
169 * @brief Read PHY registers
170 *
171 * This routine provides a generic interface to read from a PHY register.
172 *
173 * @param[in] dev PHY device structure
174 * @param[in] reg_addr Register address
175 * @param value Pointer to receive read value
176 *
177 * @retval 0 If successful.
178 * @retval -EIO If communication with PHY failed.
179 */
phy_read(const struct device * dev,uint16_t reg_addr,uint32_t * value)180 static inline int phy_read(const struct device *dev, uint16_t reg_addr,
181 uint32_t *value)
182 {
183 const struct ethphy_driver_api *api =
184 (const struct ethphy_driver_api *)dev->api;
185
186 return api->read(dev, reg_addr, value);
187 }
188
189 /**
190 * @brief Write PHY register
191 *
192 * This routine provides a generic interface to write to a PHY register.
193 *
194 * @param[in] dev PHY device structure
195 * @param[in] reg_addr Register address
196 * @param[in] value Value to write
197 *
198 * @retval 0 If successful.
199 * @retval -EIO If communication with PHY failed.
200 */
phy_write(const struct device * dev,uint16_t reg_addr,uint32_t value)201 static inline int phy_write(const struct device *dev, uint16_t reg_addr,
202 uint32_t value)
203 {
204 const struct ethphy_driver_api *api =
205 (const struct ethphy_driver_api *)dev->api;
206
207 return api->write(dev, reg_addr, value);
208 }
209
210
211 #ifdef __cplusplus
212 }
213 #endif
214
215 /**
216 * @}
217 */
218
219 #endif /* ZEPHYR_INCLUDE_DRIVERS_PHY_H_ */
220
