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