begriffs open source - cmsis/blob - CMSIS/DoxyGen/Driver/src/Driver_ETH.c

   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="http://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="http://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 */