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

   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
  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
  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
 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
 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
 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
 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
 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
 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