1 /**
2 \defgroup eth_phy_interface_gr Ethernet PHY Interface
3 \ingroup eth_interface_gr
4 \brief Driver API for Ethernet PHY Peripheral (%Driver_ETH_PHY.h)
5 \details The following section describes the Ethernet PHY Interface as defined in the %Driver_ETH_PHY.h header file.
6
7 The %Driver_ETH_PHY.h contains two \#defines that are used to configure the connection between the PHY and the
8 microcontroller device:
9 - \c ETH_PHY_NUM and
10 - \c ETH_PHY_ADDR
11
12 Usually, the Serial Management Interface (\b SMI) (using MDC and MDIO) is used to access the PHY’s internal registers to read
13 the state of the link (up/down), duplex mode, speed, and to restart auto-negotiation etc. SMI is a serial bus, which allows
14 to connect up to 32 devices. Devices on the bus are accessed using a 5-bit device address. A default device address is
15 hardware configurable by pin-strapping on the device (some pins are sampled when a reset is asserted or at power-up).
16
17 The device’s internal weak pull-up or pull-down resistors define a default device address. This address can be changed by
18 connecting strong pull-up or pull-down resistors externally. In this case, the \c ETH_PHY_ADDR needs to be defined by the
19 user.
20
21 If a microcontroller device offers more than one Ethernet PHY driver, the user needs to set the correct \c ETH_PHY_NUM in his
22 application.
23 @{
24 */
25
26 /**
27 \struct ARM_DRIVER_ETH_PHY
28 \details
29 The functions of the Ethernet PHY are accessed by function pointers exposed by this structure. Refer to \ref DriverFunctions for
30 overview information.
31
32 Each instance of an Ethernet PHY provides such an access struct. The instance is identified by
33 a postfix number in the symbol name of the access struct, for example:
34 - \b Driver_ETH_PHY0 is the name of the access struct of the first instance (no. 0).
35 - \b Driver_ETH_PHY1 is the name of the access struct of the second instance (no. 1).
36
37
38 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_ETH_PHY<i>n</i></b>.
39 The default is \token{0}, which connects a middleware to the first instance of a driver.
40 *****************************************************************************************************************/
41
42
43 /**
44 \typedef ARM_ETH_PHY_Read_t
45 \details
46 Provides the typedef for the register read function \ref ARM_ETH_MAC_PHY_Read.
47
48 <b>Parameter for:</b>
49 - \ref ARM_ETH_PHY_Initialize
50 *******************************************************************************************************************/
51
52 /**
53 \typedef ARM_ETH_PHY_Write_t
54 \details
55 Provides the typedef for the register write function \ref ARM_ETH_MAC_PHY_Write.
56
57 <b>Parameter for:</b>
58 - \ref ARM_ETH_PHY_Initialize
59 *******************************************************************************************************************/
60
61
62 //
63 // Functions
64 //
65
ARM_ETH_PHY_GetVersion(void)66 ARM_DRIVER_VERSION ARM_ETH_PHY_GetVersion (void) {
67 return { 0, 0 };
68 }
69 /**
70 \fn ARM_DRIVER_VERSION ARM_ETH_PHY_GetVersion (void)
71 \details
72 The function \b ARM_ETH_PHY_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
73 - API version is the version of the CMSIS-Driver specification used to implement this driver.
74 - Driver version is source code version of the actual driver implementation.
75
76 Example:
77 \code
78 extern ARM_DRIVER_ETH_PHY Driver_ETH_PHY0;
79 ARM_DRIVER_ETH_PHY *drv_info;
80
81 void setup_ethernet_phy (void) {
82 ARM_DRIVER_VERSION version;
83
84 drv_info = &Driver_ETH_PHY0;
85 version = drv_info->GetVersion ();
86 if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
87 // error handling
88 return;
89 }
90 }
91 \endcode
92 *****************************************************************************************************************/
93
ARM_ETH_PHY_Initialize(ARM_ETH_PHY_Read_t fn_read,ARM_ETH_PHY_Write_t fn_write)94 int32_t ARM_ETH_PHY_Initialize (ARM_ETH_PHY_Read_t fn_read, ARM_ETH_PHY_Write_t fn_write) {
95 return 0;
96 }
97 /**
98 \fn int32_t ARM_ETH_PHY_Initialize (ARM_ETH_PHY_Read_t fn_read, ARM_ETH_PHY_Write_t fn_write)
99 \details
100 The function \b ARM_ETH_PHY_Initialize initializes the Ethernet PHY interface.
101 It is called when the middleware component starts operation.
102
103 The \ref ARM_ETH_PHY_Initialize function performs the following operations:
104 - Initializes the resources needed for Ethernet PHY peripheral.
105 - Registers the \ref ARM_ETH_MAC_PHY_Read register read access function.
106 - Registers the \ref ARM_ETH_MAC_PHY_Write register write access function.
107
108 \b Example:
109 - see \ref eth_interface_gr - Driver Functions
110
111 *****************************************************************************************************************/
112
ARM_ETH_PHY_Uninitialize(void)113 int32_t ARM_ETH_PHY_Uninitialize (void) {
114 return 0;
115 }
116 /**
117 \fn int32_t ARM_ETH_PHY_Uninitialize (void)
118 \details
119 The function \b ARM_ETH_PHY_Uninitialize de-initializes the resources of Ethernet PHY interface.
120
121 It is called when the middleware component stops operation and releases the software resources used by the interface.
122 *****************************************************************************************************************/
123
ARM_ETH_PHY_PowerControl(ARM_POWER_STATE state)124 int32_t ARM_ETH_PHY_PowerControl (ARM_POWER_STATE state) {
125 return 0;
126 }
127 /**
128 \fn int32_t ARM_ETH_PHY_PowerControl (ARM_POWER_STATE state)
129 \details
130 The function \b ARM_ETH_PHY_PowerControl operates the power modes of the Ethernet PHY interface.
131
132 The parameter \em state sets the operation and can have the following values:
133 - \ref ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA.
134 Can be called multiple times. If the peripheral is already in this mode the function performs
135 no operation and returns with \ref ARM_DRIVER_OK.
136 - \ref ARM_POWER_LOW : may use power saving. Returns \ref ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
137 - \ref ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.
138
139 Refer to \ref CallSequence for more information.
140
141 \b Example:
142 - see \ref eth_interface_gr - Driver Functions
143 *****************************************************************************************************************/
144
ARM_ETH_PHY_SetInterface(uint32_t interface)145 int32_t ARM_ETH_PHY_SetInterface (uint32_t interface) {
146 return 0;
147 }
148 /**
149 \fn int32_t ARM_ETH_PHY_SetInterface (uint32_t interface)
150
151 \details
152 The function \b ARM_ETH_PHY_SetInterface specifies the \ref eth_interface_types1 that links the Ethernet MAC and Ethernet PHY.
153 After initialization of the PHY interface, you can set the media type.
154 The function \ref ARM_ETH_MAC_GetCapabilities retrieves the media interface type encoded in the data field \b media_interface of the structure
155 \ref ARM_ETH_MAC_CAPABILITIES.
156
157 The parameter \em interface can have the following values:
158
159 Parameter \em interface | Media Type
160 :-----------------------------|:-------------------------
161 \ref ARM_ETH_INTERFACE_MII | Media Independent Interface (MII)
162 \ref ARM_ETH_INTERFACE_RMII | Reduced Media Independent Interface (RMII)
163 \ref ARM_ETH_INTERFACE_SMII | Serial Media Independent Interface (SMII);
164
165 \note
166 Some \em interface values may be unsupported by a driver implementation. For example \ref ARM_ETH_INTERFACE_SMII may return \b ARM_DRIVER_ERROR_UNSUPPORTED.
167
168 \b Example:
169 \code
170 static ARM_ETH_MAC_CAPABILITIES capabilities;
171 static ARM_DRIVER_ETH_MAC *mac;
172 static ARM_DRIVER_ETH_PHY *phy;
173
174 mac = &Driver_ETH_MAC0;
175 phy = &Driver_ETH_PHY0;
176
177 // Initialize Media Access Controller
178 capabilities = mac->GetCapabilities ();
179 ...
180 status = phy->SetInterface (capabilities.media_interface);
181 if (status != ARM_DRIVER_OK) ... // error handling
182 status = phy->SetMode (ARM_ETH_PHY_AUTO_NEGOTIATE);
183 if (status != ARM_DRIVER_OK) ... // error handling
184 ...
185 \endcode
186 *****************************************************************************************************************/
187
ARM_ETH_PHY_SetMode(uint32_t mode)188 int32_t ARM_ETH_PHY_SetMode (uint32_t mode) {
189 return 0;
190 }
191 /**
192 \fn int32_t ARM_ETH_PHY_SetMode (uint32_t mode)
193 \details
194 The function \b ARM_ETH_PHY_SetMode sets the operation mode parameters for the Ethernet PHY.
195
196
197 The table below lists the possible values for the parameter \em mode. Values from different categories can be ORed as shown in this example code:
198
199 \code
200 phy->SetMode (ARM_ETH_PHY_SPEED_100M | ARM_ETH_PHY_LOOPBACK | ARM_ETH_PHY_DUPLEX_HALF );
201 \endcode
202 \n
203
204 <table class="cmtable" summary="">
205 <tr><th>Parameter \em mode </th><th> bit </th><th> Category </th> <th>Description</th></tr>
206 <tr><td>\ref ARM_ETH_PHY_SPEED_10M </td><td rowspan="3"> 0..1 </td><td rowspan="3">Link Speed </td> <td>Set the link speed to \token{10 [Mbps]} </td></tr>
207 <tr><td>\ref ARM_ETH_PHY_SPEED_100M </td> <td>Set the link speed to \token{100 [Mbps]} </td></tr>
208 <tr><td>\ref ARM_ETH_PHY_SPEED_1G </td> <td>Set the link speed to \token{1 [Gbps]} </td></tr>
209 <tr><td>\ref ARM_ETH_PHY_DUPLEX_HALF </td><td rowspan="2"> 2 </td><td rowspan="2">Link Mode </td> <td>Set the link mode to half duplex </td></tr>
210 <tr><td>\ref ARM_ETH_PHY_DUPLEX_FULL </td> <td>Set the link mode to full duplex </td></tr>
211 <tr><td>\ref ARM_ETH_PHY_AUTO_NEGOTIATE </td><td> 3 </td><td>Autonegotiation </td> <td>Set the interface to Auto Negotiation mode of transmission parameters</td></tr>
212 <tr><td>\ref ARM_ETH_PHY_LOOPBACK </td><td> 4 </td><td>Loopback </td> <td>Set the interface into a Loop-back test mode </td></tr>
213 <tr><td>\ref ARM_ETH_PHY_ISOLATE </td><td> 5 </td><td>Isolation </td> <td>Set to indicate electrical isolation of PHY interface from MII/RMII interface</td></tr>
214 </table>
215
216 \note
217 Some settings may be also taken from configuration pins (example \ref ARM_ETH_PHY_ISOLATE). Check the effect of mode settings in the actual driver implementation.
218 \note
219 Some \em mode values may be unsupported by a driver implementation. For example \ref ARM_ETH_PHY_SPEED_1G may return \b ARM_DRIVER_ERROR_UNSUPPORTED.
220
221
222 \b Example:
223 \code
224 static ARM_ETH_MAC_CAPABILITIES capabilities;
225 static ARM_DRIVER_ETH_MAC *mac;
226 static ARM_DRIVER_ETH_PHY *phy;
227
228 mac = &Driver_ETH_MAC0;
229 phy = &Driver_ETH_PHY0;
230
231 // Initialize Media Access Controller
232 capabilities = mac->GetCapabilities ();
233 ...
234 status = phy->SetInterface (capabilities.media_interface);
235 if (status != ARM_DRIVER_OK) ... // error handling
236 status = phy->SetMode (ARM_ETH_PHY_SPEED_100M | ARM_ETH_PHY_DUPLEX_FULL | ARM_ETH_PHY_ISOLATE);
237 if (status != ARM_DRIVER_OK) ... // error handling
238 ...
239 \endcode
240
241
242
243 *****************************************************************************************************************/
244
ARM_ETH_PHY_GetLinkState(void)245 ARM_ETH_LINK_STATE ARM_ETH_PHY_GetLinkState (void) {
246 return 0;
247 }
248 /**
249 \fn ARM_ETH_LINK_STATE ARM_ETH_PHY_GetLinkState (void)
250 \details
251 The function \b ARM_ETH_PHY_GetLinkState retrieves the connection status of the physical Ethernet link.
252
253 \b Example:
254 - see \ref eth_interface_gr - Driver Functions
255 *****************************************************************************************************************/
256
ARM_ETH_PHY_GetLinkInfo(void)257 ARM_ETH_LINK_INFO ARM_ETH_PHY_GetLinkInfo (void) {
258 return 0;
259 }
260 /**
261 \fn ARM_ETH_LINK_INFO ARM_ETH_PHY_GetLinkInfo (void)
262 \details
263 The function \b ARM_ETH_PHY_GetLinkInfo retrieves information about the current established communication
264 mode (half/full duplex) and communication speed. Information is only valid when link is up (see \ref ARM_ETH_PHY_GetLinkState).
265
266 \b Example:
267 - see \ref eth_interface_gr - Driver Functions
268 *****************************************************************************************************************/
269
270
271 /**
272 @}
273 */
274 // End ETH PHY Interface group; below the groups are included with \ingroup
275
276
277 /**
278 \defgroup eth_phy_mode_ctrls Ethernet PHY Mode
279 \ingroup eth_phy_interface_gr
280 \brief Specify operation modes of the Ethernet PHY interface
281 \details
282 @{
283 \def ARM_ETH_PHY_SPEED_10M
284 \sa ARM_ETH_PHY_SetMode
285 \def ARM_ETH_PHY_SPEED_100M
286 \sa ARM_ETH_PHY_SetMode
287 \def ARM_ETH_PHY_SPEED_1G
288 \sa ARM_ETH_PHY_SetMode
289 \def ARM_ETH_PHY_DUPLEX_HALF
290 \sa ARM_ETH_PHY_SetMode
291 \def ARM_ETH_PHY_DUPLEX_FULL
292 \sa ARM_ETH_PHY_SetMode
293 \def ARM_ETH_PHY_AUTO_NEGOTIATE
294 \sa ARM_ETH_PHY_SetMode
295 \def ARM_ETH_PHY_LOOPBACK
296 \sa ARM_ETH_PHY_SetMode
297 \def ARM_ETH_PHY_ISOLATE
298 \sa ARM_ETH_PHY_SetMode
299 @}
300 */
301
302
303
304
