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

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