1 /**
2 \defgroup eth_interface_gr Ethernet Interface
3 \brief    Ethernet common definitions (%Driver_ETH.h)
4 
5 \details
6 <b>Ethernet</b> is a networking technology for exchanging data packages between computer systems. Several microcontrollers integrate
7 an Ethernet MAC (Media Access Control) data-link layer that interfaces to an Ethernet PHY (Physical Interface Transceiver).
8 
9 Wikipedia offers more information about
10 the <a href="https://en.wikipedia.org/wiki/Ethernet" target="_blank"><b>Ethernet</b></a>.
11 
12 
13 <b>Block Diagram</b>
14 
15 The Ethernet PHY connects typically to the Ethernet MAC using an MII (Media Independent Interface) or RMII (Reduced Media Independent Interface).
16 
17 \n
18 \image html EthernetSchematic.png  "Block Diagram of a typical Ethernet Interface"
19 
20 
21 <b>Ethernet API</b>
22 
23 The following header files define the Application Programming Interface (API) for the <b>Ethernet</b> interface:
24  - \b %Driver_ETH.h : Common definitions of the Ethernet PHY and MAC part
25  - \b %Driver_ETH_MAC.h : API for the Ethernet MAC
26  - \b %Driver_ETH_PHY.h : API for the Ethernet PHY
27 
28 The driver implementation of the Ethernet MAC is a typical part of a Device Family Pack (DFP) that supports the peripherals of the microcontroller family.
29 The driver implementation of the Ethernet PHY is a typical part of a \b Network Software Pack, since PHY is typically not integrated into the microcontroller.
30 
31 \note
32 For parameters, the value marked with (default) is the setting after the driver initialization.
33 
34 
35 <b>Driver Functions</b>
36 
37 The driver functions are published in the access struct as explained in \ref DriverFunctions
38  - \ref ARM_DRIVER_ETH_MAC : access struct for <b>Ethernet MAC</b> driver functions.
39  - \ref ARM_DRIVER_ETH_PHY : access struct for <b>Ethernet PHY</b> driver functions.
40 
41 Both drivers are used in combination and usually the Ethernet MAC provides a media interface to the Ethernet PHY.
42 A typical setup sequence for the drivers is shown below:
43 
44 <b>Example Code</b>
45 
46 The following example code shows the usage of the Ethernet interface.
47 
48 \code
49 extern ARM_DRIVER_ETH_MAC Driver_ETH_MAC0;
50 extern ARM_DRIVER_ETH_PHY Driver_ETH_PHY0;
51 
52 static ARM_DRIVER_ETH_MAC *mac;
53 static ARM_DRIVER_ETH_PHY *phy;
54 static ARM_ETH_MAC_ADDR          own_mac_address;
55 static ARM_ETH_MAC_CAPABILITIES  capabilities;
56 
57 void ethernet_mac_notify (uint32_t event)  {
58   switch (event)  {
59      :
60   }
61 }
62 
63 
64 void initialize_ethernet_interface (void) {
65   mac = &Driver_ETH_MAC0;
66   phy = &Driver_ETH_PHY0;
67 
68   // Initialize Media Access Controller
69   capabilities = mac->GetCapabilities ();
70 
71   mac->Initialize (ethernet_mac_notify);
72   mac->PowerControl (ARM_POWER_FULL);
73 
74   if (capabilities.mac_address == 0)  {
75     // populate own_mac_address with the address to use
76     mac->SetMacAddress(&own_mac_address);
77   }
78   else {
79     mac->GetMacAddress(&own_mac_address);
80   }
81 
82   // Initialize Physical Media Interface
83   if (phy->Initialize (mac->PHY_Read, mac->PHY_Write) == ARM_DRIVER_OK) {
84     phy->PowerControl (ARM_POWER_FULL);
85     phy->SetInterface (capabilities.media_interface);
86     phy->SetMode (ARM_ETH_PHY_AUTO_NEGOTIATE);
87   }
88     :
89     :
90 }
91 
92 
93 static ARM_ETH_LINK_STATE ethernet_link;   // current link status
94 
95 void ethernet_check_link_status (void) {
96   ARM_ETH_LINK_STATE link;
97 
98   link = phy->GetLinkState ();
99   if (link == ethernet_link) {
100     return;                                // link state unchanged
101   }
102                                            // link state changed
103   ethernet_link = link;
104   if (link == ARM_ETH_LINK_UP) {      // start transfer
105     ARM_ETH_LINK_INFO info = phy->GetLinkInfo ();
106     mac->Control(ARM_ETH_MAC_CONFIGURE,
107                  info.speed  << ARM_ETH_MAC_SPEED_Pos  |
108                  info.duplex << ARM_ETH_MAC_DUPLEX_Pos |
109                  ARM_ETH_MAC_ADDRESS_BROADCAST);
110     mac->Control(ARM_ETH_MAC_CONTROL_TX, 1);
111     mac->Control(ARM_ETH_MAC_CONTROL_RX, 1);
112   }
113   else {                                   // stop transfer
114     mac->Control(ARM_ETH_MAC_FLUSH, ARM_ETH_MAC_FLUSH_TX | ARM_ETH_MAC_FLUSH_RX);
115     mac->Control(ARM_ETH_MAC_CONTROL_TX, 0);
116     mac->Control(ARM_ETH_MAC_CONTROL_RX, 0);
117   }
118 }
119 
120 \endcode
121 */
122 
123 /**
124 \defgroup eth_interface_gr Ethernet Interface
125 @{
126 */
127 
128 /**
129 \cond
130 */
131 
132 /**
133 \enum ARM_ETH_INTERFACE
134 \details
135 Encodes the supported media interface between Ethernet MAC and Ethernet PHY.
136 
137 The function \ref ARM_ETH_MAC_GetCapabilities retrieves the media interface type encoded in the data field \b media_interface of the struct
138  \ref ARM_ETH_MAC_CAPABILITIES.
139 
140 <b>Parameter for:</b>
141 - \ref ARM_ETH_PHY_SetInterface
142 */
143 
144 /**
145 \enum ARM_ETH_DUPLEX
146 \details
147 Lists the supported duplex operating types for MAC.
148 
149 <b>Parameter for:</b>
150   - \ref ARM_ETH_MAC_SetMode
151 */
152 
153 
154 /**
155 \typedef ARM_ETH_SPEED
156 \details
157 Lists the supported operating speeds for MAC.
158 
159 <b>Parameter for:</b>
160   - \ref ARM_ETH_MAC_SetMode
161 */
162 
163 /**
164 \endcond
165 */
166 
167 
168 /**
169 \typedef ARM_ETH_LINK_STATE
170 \details
171 The Ethernet Link status shows if the communication is currently established (up) or interrupted (down).
172 
173 <b>Returned by:</b>
174   - \ref ARM_ETH_PHY_GetLinkState
175 */
176 
177 
178 /**
179 \struct ARM_ETH_LINK_INFO
180 \details
181 The Ethernet Link information provides parameters about the current established communication.
182 
183 <b>Returned by:</b>
184   - \ref ARM_ETH_PHY_GetLinkInfo
185 */
186 
187 
188 /**
189 \struct ARM_ETH_MAC_ADDR
190 \details
191 Stores the MAC Address of the Ethernet interface as defined by IEEE 802. Wikipedia offers more information about
192 the <a href="https://en.wikipedia.org/wiki/MAC_address" target="_blank"><b>MAC Address</b></a>.
193 
194 <b>Parameter for:</b>
195   - \ref ARM_ETH_MAC_GetMacAddress, \ref ARM_ETH_MAC_SetMacAddress, \ref ARM_ETH_MAC_SetAddressFilter
196 */
197 
198 /**
199 @}
200 */
201 // End ETH Interface
202 
203 
204 /**
205 \defgroup eth_interface_types1 Media Interface Types
206 \ingroup eth_interface_gr
207 \brief Ethernet Media Interface type
208 \details
209 Encodes the supported media interface between Ethernet MAC and Ethernet PHY.
210 The function \ref ARM_ETH_MAC_GetCapabilities retrieves the media interface type encoded in the data field \b media_interface of the struct
211  \ref ARM_ETH_MAC_CAPABILITIES.
212 
213 <b>Parameter for:</b>
214 - \ref ARM_ETH_PHY_SetInterface
215 
216 @{
217 \def ARM_ETH_INTERFACE_MII
218 \sa ARM_ETH_PHY_SetInterface
219 \def ARM_ETH_INTERFACE_RMII
220 \sa ARM_ETH_PHY_SetInterface
221 \def ARM_ETH_INTERFACE_SMII
222 \sa ARM_ETH_PHY_SetInterface
223 @}
224 */
225