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

   1 /* -----------------------------------------------------------------------------
   2  * Copyright (c) 2013-2014 ARM Limited. All rights reserved.
   3  *
   4  * $Date:        2. January 2014
   5  * $Revision:    V2.00
   6  *
   7  * Project:      Ethernet MAC Driver API
   8  * -------------------------------------------------------------------------- */
   9
  10
  11 /**
  12 \defgroup   eth_mac_interface_gr Ethernet MAC Interface
  13 \ingroup    eth_interface_gr
  14 \brief      Driver API for Ethernet MAC Peripheral (%Driver_ETH_MAC.h)
  15 \details
  16 The following section describes the Ethernet MAC Interface as defined in the %Driver_ETH_MAC.h header file.
  17 @{
  18 */
  19
  20 /**
  21 \struct     ARM_ETH_MAC_CAPABILITIES
  22 \details
  23 An Ethernet MAC driver can be implemented with different capabilities.
  24 The data fields of this struct encode the capabilities implemented by this driver.
  25
  26 <b>Returned by:</b>
  27   - \ref ARM_ETH_MAC_GetCapabilities
  28 */
  29
  30 /**
  31 \struct     ARM_DRIVER_ETH_MAC
  32 \details
  33 The functions of the Ethernet MAC are accessed by function pointers. Refer to \ref DriverFunctions for
  34 overview information.
  35
  36 Each instance of an Ethernet MAC provides such an access struct. The instance is indicated by
  37 a postfix in the symbol name of the access struct, for example:
  38  - \b Driver_ETH_MAC0 is the name of the access struct of the first instance (no. 0).
  39  - \b Driver_ETH_MAC1 is the name of the access struct of the second instance (no. 1).
  40
  41 A configuration setting in the middleware allows connecting the middleware to a specific driver instance <b>Driver_ETH_MAC<i>n</i></b>.
  42 The default is \token{0}, which connects a middleware to the first instance of a driver.
  43 */
  44
  45 /**
  46 \struct     ARM_ETH_MAC_TIME
  47 \details
  48 The two members of this struct provide fields to encode time values in the order \token{Nano seconds} and \token{seconds}.
  49
  50 The member \em ns is also used as a correction factor for \ref ARM_ETH_MAC_TIMER_ADJUST_CLOCK.
  51
  52 <b>Used in:</b>
  53   - \ref ARM_ETH_MAC_GetRxFrameTime
  54   - \ref ARM_ETH_MAC_GetTxFrameTime
  55   - \ref ARM_ETH_MAC_ControlTimer
  56
  57 *******************************************************************************************************************/
  58
  59 /**
  60 \typedef    ARM_ETH_MAC_SignalEvent_t
  61 \details
  62 Provides the typedef for the callback function \ref ARM_ETH_MAC_SignalEvent.
  63
  64 <b>Parameter for:</b>
  65   - \ref ARM_ETH_MAC_Initialize
  66 *******************************************************************************************************************/
  67
  68 /**
  69 \defgroup ETH_MAC_events Ethernet MAC Events
  70 \ingroup eth_mac_interface_gr
  71 \brief The Ethernet MAC driver generates call back events that are notified via the function \ref ARM_ETH_MAC_SignalEvent.
  72 \details
  73 This section provides the event values for the \ref ARM_ETH_MAC_SignalEvent callback function.
  74
  75 The following call back notification events are generated:
  76 @{
  77 \def ARM_ETH_MAC_EVENT_RX_FRAME
  78 \def ARM_ETH_MAC_EVENT_TX_FRAME
  79 \def ARM_ETH_MAC_EVENT_WAKEUP
  80 \def ARM_ETH_MAC_EVENT_TIMER_ALARM
  81 @}
  82 */
  83
  84 //
  85 // Function documentation
  86 //
  87
  88 ARM_DRIVER_VERSION ARM_ETH_MAC_GetVersion (void)  {
  89   ;
  90 }
  91 /**
  92 \fn       ARM_DRIVER_VERSION ARM_ETH_MAC_GetVersion (void);
  93 \details
  94 The function \b ARM_ETH_MAC_GetVersion returns version information of the driver implementation in \ref ARM_DRIVER_VERSION
  95  - API version is the version of the CMSIS-Driver specification used to implement this driver.
  96  - Driver version is source code version of the actual driver implementation.
  97
  98 Example:
  99 \code
 100 extern ARM_DRIVER_ETH_MAC Driver_ETH_MAC0;
 101 ARM_DRIVER_ETH_MAC *mac;
 102
 103 void setup_ethernet (void)  {
 104   ARM_DRIVER_VERSION  version;
 105
 106   mac = &Driver_ETH_MAC0;
 107   version = mac->GetVersion ();
 108   if (version.api < 0x10A)   {      // requires at minimum API version 1.10 or higher
 109     // error handling
 110     return;
 111   }
 112 }
 113 \endcode
 114 *******************************************************************************************************************/
 115
 116 ARM_ETH_MAC_CAPABILITIES ARM_ETH_MAC_GetCapabilities (void)  {
 117   ;
 118 }
 119 /**
 120 \fn       ARM_ETH_MAC_CAPABILITIES ARM_ETH_MAC_GetCapabilities (void)
 121 \details
 122 The function \b ARM_ETH_MAC_GetCapabilities retrieves information about capabilities in this driver implementation.
 123 The data fields of the struct \ref ARM_ETH_MAC_CAPABILITIES encode various capabilities, for example
 124 if a hardware is capable to create checksums in hardware or signal events using the \ref ARM_ETH_MAC_SignalEvent
 125 callback function.
 126
 127 Example:
 128 \code
 129 extern ARM_DRIVER_ETH_MAC Driver_ETH_MAC0;
 130 ARM_DRIVER_ETH_MAC *mac;
 131
 132 void read_capabilities (void)  {
 133   ARM_ETH_MAC_CAPABILITIES mac_capabilities;
 134
 135   mac = &Driver_ETH_MAC0;
 136   mac_capabilities = mac->GetCapabilities ();
 137   // interrogate capabilities
 138
 139 }
 140 \endcode
 141 *******************************************************************************************************************/
 142
 143 int32_t ARM_ETH_MAC_Initialize (ARM_ETH_MAC_SignalEvent_t cb_event)  {
 144
 145 }
 146 /**
 147 \fn     int32_t ARM_ETH_MAC_Initialize (ARM_ETH_MAC_SignalEvent_t cb_event)
 148 \details
 149 The function \b ARM_ETH_MAC_Initialize initializes the Ethernet MAC interface.
 150 It is called when the middleware component starts operation.
 151
 152 The \ref ARM_ETH_MAC_Initialize function performs the following operations:
 153   - Initializes the resources needed for the Ethernet MAC peripheral.
 154   - Registers the \ref ARM_ETH_MAC_SignalEvent callback function.
 155
 156 The parameter \em cb_event is a pointer to the \ref ARM_ETH_MAC_SignalEvent callback function; use a NULL pointer
 157 when no callback signals are required.
 158
 159 \b Example:
 160  - see \ref eth_interface_gr - Driver Functions
 161 *******************************************************************************************************************/
 162
 163 int32_t ARM_ETH_MAC_Uninitialize (void)  {
 164
 165 }
 166 /**
 167 \fn       int32_t ARM_ETH_MAC_Uninitialize (void)
 168 \details
 169 The function \b ARM_ETH_MAC_Uninitialize de-initializes the resources of Ethernet MAC interface.
 170
 171 It is called when the middleware component stops operation and releases the software resources
 172 used by the interface.
 173 *******************************************************************************************************************/
 174
 175 int32_t ARM_ETH_MAC_PowerControl (ARM_POWER_STATE state)  {
 176
 177 }
 178 /**
 179 \fn int32_t ARM_ETH_MAC_PowerControl (ARM_POWER_STATE state)
 180 \details
 181 The function \b ARM_ETH_MAC_PowerControl allows you to configure the power modes of the Ethernet MAC interface.
 182
 183 The parameter \em state can be:
 184  - ARM_POWER_OFF: Ethernet MAC peripheral is turned off.
 185  - ARM_POWER_FULL: Ethernet MAC peripheral is turned on and fully operational.
 186
 187 If power \em state specifies an unsupported mode, the function returns \ref ARM_DRIVER_ERROR_UNSUPPORTED as status information
 188 and the previous power state of the peripheral is unchanged. Multiple calls with the same \em state generate no
 189 error.
 190
 191 \b Example:
 192  - see \ref eth_interface_gr - Driver Functions
 193 *******************************************************************************************************************/
 194
 195 int32_t ARM_ETH_MAC_GetMacAddress (ARM_ETH_MAC_ADDR *ptr_addr)  {
 196
 197 }
 198 /**
 199 \fn int32_t ARM_ETH_MAC_GetMacAddress (ARM_ETH_MAC_ADDR *ptr_addr)
 200 \details
 201 The function \b ARM_ETH_MAC_GetMacAddress retrieves the Ethernet MAC own address from the driver.
 202 *******************************************************************************************************************/
 203
 204 int32_t ARM_ETH_MAC_SetMacAddress (const ARM_ETH_MAC_ADDR *ptr_addr)  {
 205
 206 }
 207 /**
 208 \fn int32_t ARM_ETH_MAC_SetMacAddress (const ARM_ETH_MAC_ADDR *ptr_addr)
 209 \details
 210 The function \b ARM_ETH_MAC_SetMacAddress configures Ethernet MAC own address.
 211 The Ethernet MAC accepts packets <a href="http://en.wikipedia.org/wiki/Ethernet_frame" target="_blank"><b>Ethernet frames</b></a> which contains
 212 a MAC destination address that matches the address specified with \em ptr_addr.
 213
 214 The Ethernet MAC receiver will accept also packets with addresses configured by \ref ARM_ETH_MAC_SetAddressFilter function.
 215
 216 MAC receiver can be configured to accept also packets with broadcast address, any multicast address or even all packets regardless of address (Promiscuity Mode).
 217 This is configured by function \ref ARM_ETH_MAC_Control with \ref ARM_ETH_MAC_CONFIGURE as control parameter.
 218 *******************************************************************************************************************/
 219
 220 int32_t ARM_ETH_MAC_SetAddressFilter (const ARM_ETH_MAC_ADDR *ptr_addr, uint32_t num_addr)  {
 221
 222 }
 223 /**
 224 \fn int32_t ARM_ETH_MAC_SetAddressFilter (const ARM_ETH_MAC_ADDR *ptr_addr, uint32_t num_addr)
 225 \details
 226 The function \b ARM_ETH_MAC_SetAddressFilter configures Ethernet MAC receiver address filtering.
 227 The Ethernet MAC accepts packets <a href="http://en.wikipedia.org/wiki/Ethernet_frame" target="_blank"><b>Ethernet frames</b></a> which contains
 228 a MAC destination address of the list supplied with \em ptr_addr.  The parameter \em ptr_addr provides and array of Ethernet MAC addresses.  The number of addresses
 229 is supplied by \em num_addr. Specifying \em num_adr = 0 disables address filtering previously set with this function.
 230
 231 The Ethernet MAC receiver will accept packets addressed to its own address and packets with addresses configured by this function.
 232
 233 MAC receiver can be configured to accept also packets with broadcast address, any multicast address or even all packets regardless of address (Promiscuity Mode).
 234 This is configured by function \ref ARM_ETH_MAC_Control with \ref ARM_ETH_MAC_CONFIGURE as control parameter.
 235 *******************************************************************************************************************/
 236
 237 int32_t ARM_ETH_MAC_SendFrame (const uint8_t *frame, uint32_t len, uint32_t flags)  {
 238
 239 }
 240 /**
 241 \fn int32_t ARM_ETH_MAC_SendFrame (const uint8_t *frame, uint32_t len, uint32_t flags)
 242 \details
 243 The function \b ARM_ETH_MAC_SendFrame writes an <a href="http://en.wikipedia.org/wiki/Ethernet_frame" target="_blank"><b>Ethernet frame</b></a> to the Ethernet MAC transmit buffer.
 244
 245 The Ethernet MAC transmit engine must be enabled by using the function \ref ARM_ETH_MAC_Control (ARM_ETH_MAC_CONTROL_TX, 1) before a call to this function.
 246
 247 The frame data addressed by \em buf starts with MAC destination and ends with the last Payload data byte. The frame data is copied into
 248 the transmit buffer of the Ethernet MAC interface. The function does not wait until the transmission over the Ethernet is complete,
 249 however the memory addressed by \em buf is available for the next Ethernet frame after return.
 250
 251 The maximum value for \em len is implied by the size restrictions of the Ethernet frame but is not verified.
 252 Using an invalid value for \em len may generate unpredicted results.
 253
 254 The parameter \em flags specifies additional attributes for the function as shown in the following table. Multiple flags can be combined, for example:
 255 ARM_ETH_MAC_TX_FRAME_EVENT | ARM_ETH_MAC_TX_FRAME_TIMESTAMP.
 256
 257 Flag bit                               | Description
 258 :--------------------------------------|:-----------------------------------------
 259 \ref ARM_ETH_MAC_TX_FRAME_FRAGMENT     | Indicates that it is a fragment of the frame. allows you to collect multiple fragments before the frame is sent.
 260 \ref ARM_ETH_MAC_TX_FRAME_EVENT        | \ref ARM_ETH_MAC_SignalEvent with \em event bit \ref ARM_ETH_MAC_EVENT_TX_FRAME set will be called when frame send is complete.
 261 \ref ARM_ETH_MAC_TX_FRAME_TIMESTAMP    | Capture the time stamp of the frame. The time stamp can be obtained using the function \ref ARM_ETH_MAC_GetTxFrameTime.
 262
 263
 264 \b Example:
 265 \code
 266   status = mac->SendFrame (&frame->data[0], frame->length, 0);
 267   if (status != ARM_DRIVER_OK)  {
 268     // error handling
 269   }
 270 \endcode
 271
 272 *******************************************************************************************************************/
 273
 274 int32_t ARM_ETH_MAC_ReadFrame (uint8_t *frame, uint32_t len)  {
 275
 276 }
 277 /**
 278 \fn int32_t ARM_ETH_MAC_ReadFrame (uint8_t *frame, uint32_t len)
 279 \details
 280 The function \b ARM_ETH_MAC_ReadFrame reads an <a href="http://en.wikipedia.org/wiki/Ethernet_frame" target="_blank"><b>Ethernet frame</b></a> from the Ethernet MAC receive buffer.
 281
 282 The Ethernet MAC receive engine must be enabled using the function \ref ARM_ETH_MAC_Control (ARM_ETH_MAC_CONTROL_RX , 1) before a call to this function.
 283 The \em len of the Ethernet frame can be checked using the function \ref ARM_ETH_MAC_GetRxFrameSize.
 284
 285 The frame data addressed by \em buf starts with MAC destination and ends with the last Payload data byte. The frame data is read from
 286 the receive buffer of the Ethernet MAC interface and the number of bytes written into the memory addressed by \em buf is returned.
 287 A negative return value indicates an error whereby the status code is defined with driver common return codes.
 288
 289 The function \ref ARM_ETH_MAC_ReadFrame may be called with \em buf = NULL and \em len = 0 to discard or release an frame. This is useful when an incorrect frame has been received or
 290 no memory is available to hold the Ethernet frame.
 291
 292 \b Example:
 293 \code
 294   size = mac->GetRxFrameSize ();
 295   if ((size < 14) || (size > 1514)) {    // frame excludes CRC
 296     mac->ReadFrame (NULL, 0);            // Frame error, release it
 297   }
 298   len = mac->ReadFrame (&frame->data[0], size);
 299   if (len < 0)  {
 300     // error handling
 301   }
 302 \endcode
 303 *******************************************************************************************************************/
 304
 305 uint32_t ARM_ETH_MAC_GetRxFrameSize (void)  {
 306
 307 }
 308 /**
 309 \fn uint32_t ARM_ETH_MAC_GetRxFrameSize (void)
 310 \details
 311 The function \b ARM_ETH_MAC_GetRxFrameSize returns the size of a received
 312 <a href="http://en.wikipedia.org/wiki/Ethernet_frame" target="_blank"><b>Ethernet frame</b></a>.
 313 This function is called before \ref ARM_ETH_MAC_ReadFrame and supplies the value \em len.
 314
 315 The frame size includes MAC destination and ends with the last Payload data byte.
 316 Value \em 0 indicates that no Ethernet frame is available in the receive buffer.
 317 Values smaller than minimum size of Ethernet frame or larger than maximum size of Ethernet frame
 318 indicate an invalid frame which needs to be discarded by calling \ref ARM_ETH_MAC_ReadFrame.
 319
 320 \b Example:
 321   - see \ref ARM_ETH_MAC_ReadFrame
 322
 323 *******************************************************************************************************************/
 324
 325 int32_t ARM_ETH_MAC_GetRxFrameTime (ARM_ETH_MAC_TIME *time)  {
 326
 327 }
 328 /**
 329 \fn int32_t ARM_ETH_MAC_GetRxFrameTime (ARM_ETH_MAC_TIME *time)
 330 \details
 331 Retrieve time stamp of a received <a href="http://en.wikipedia.org/wiki/Ethernet_frame" target="_blank"><b>Ethernet frame</b></a>.
 332 This function must be called before the frame is read using \ref ARM_ETH_MAC_ReadFrame.
 333 *******************************************************************************************************************/
 334
 335 int32_t ARM_ETH_MAC_GetTxFrameTime (ARM_ETH_MAC_TIME *time)  {
 336
 337 }
 338 /**
 339 \fn int32_t ARM_ETH_MAC_GetTxFrameTime (ARM_ETH_MAC_TIME *time)
 340 \details
 341 The function \b returns the time stamp of a transmitted <a href="http://en.wikipedia.org/wiki/Ethernet_frame" target="_blank"><b>Ethernet frame</b></a>.
 342 *******************************************************************************************************************/
 343
 344 int32_t ARM_ETH_MAC_Control (uint32_t control, uint32_t arg)  {
 345
 346 }
 347 /**
 348 \fn int32_t ARM_ETH_MAC_Control (uint32_t control, uint32_t arg)
 349 \details
 350 The function \b ARM_ETH_MAC_Control controls the Ethernet MAC interface and executes various operations.
 351 After initialization, the Ethernet transceiver and receiver are disabled.
 352
 353 The parameter \em control specifies an operation as defined in the table <b>Parameter \em control</b>. \n
 354 The parameter \em arg provides, depending on the operation, additional information or values.
 355
 356 The table lists values for the parameter \em control.
 357
 358 Parameter \em control                                | Operation
 359 :----------------------------------------------------|:--------------------------------------------
 360 \ref ARM_ETH_MAC_CONFIGURE                           | Configure the Ethernet MAC interface; For \em arg values, see table <b>Parameter \em arg for CONFIGURE</b>
 361 \ref ARM_ETH_MAC_CONTROL_TX                          | Enable or disable the transmitter; \em arg :  \token{0=disable; 1=enable}
 362 \ref ARM_ETH_MAC_CONTROL_RX                          | Enable or disable the receiver; \em arg :  \token{0=disable; 1=enable}
 363 \ref ARM_ETH_MAC_FLUSH                               | Flush a buffer; \em arg : see table <b>Parameter \em arg for FLUSH</b>
 364 \ref ARM_ETH_MAC_SLEEP                               | Exit/Enter Sleep mode; \em arg : \token{0=exit; 1=enter and wait for Magic packet}
 365 \ref ARM_ETH_MAC_VLAN_FILTER                         | Configure VLAN Filter for received frames;  \em arg : See table <b>Parameter \em arg for VLAN Filter</b>
 366
 367
 368 The table <b>Parameter \em arg for CONFIGURE</b> lists the \em arg values for the \em control \b ARM_ETH_MAC_CONFIGURE.
 369 The values can be ORed in the following way:
 370 \code
 371     mac->Control(ARM_ETH_MAC_CONFIGURE, ARM_ETH_MAC_SPEED_100M | ARM_ETH_MAC_DUPLEX_FULL | ARM_ETH_MAC_LOOPBACK);
 372 \endcode
 373
 374 <table class="cmtable" summary="">
 375 <tr><th colspan="4">Parameter \em arg CONFIGURE </th></tr>
 376 <tr><th>Parameter \em arg                   </th><th>               Bit    </th><th>            Category     </th><th>Description                             </th></tr>
 377 <tr><td>\ref ARM_ETH_MAC_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>
 378 <tr><td>\ref ARM_ETH_MAC_SPEED_100M         </td>                                                                 <td>Set the link speed to \token{100 [Mbps]}</td></tr>
 379 <tr><td>\ref ARM_ETH_MAC_SPEED_1G           </td>                                                                 <td>Set the link speed to \token{1  [Gbps]} </td></tr>
 380 <tr><td>\ref ARM_ETH_MAC_DUPLEX_HALF        </td><td rowspan="2">   2      </td><td rowspan="2">Link Mode    </td><td>Set the link mode to half duplex        </td></tr>
 381 <tr><td>\ref ARM_ETH_MAC_DUPLEX_FULL        </td>                                                                 <td>Set the link mode to full duplex        </td></tr>
 382 <tr><td>n.a.                                </td><td>               3      </td><td>            n.a.         </td><td>\em reserved                            </td></tr>
 383 <tr><td>\ref ARM_ETH_MAC_LOOPBACK           </td><td>               4      </td><td>    Loopback Test Mode   </td><td>Set the interface into a Loop-back test mode</td></tr>
 384 <tr><td>\ref ARM_ETH_MAC_CHECKSUM_OFFLOAD_RX</td><td>               5      </td><td>Receiver Checksum offload</td><td>Enable Receiver Checksum offload        </td></tr>
 385 <tr><td>\ref ARM_ETH_MAC_CHECKSUM_OFFLOAD_TX</td><td>               6      </td><td>Transmitter Checksum offload</td><td>Enable Transmitter Checksum offload  </td></tr>
 386 <tr><td>\ref ARM_ETH_MAC_ADDRESS_BROADCAST  </td><td>               7      </td><td>Broadcast Frame address  </td><td>Accept frames with Broadcast address    </td></tr>
 387 <tr><td>\ref ARM_ETH_MAC_ADDRESS_MULTICAST  </td><td>               8      </td><td>Multicast Frame address  </td><td>Accept frames with any Multicast address</td></tr>
 388 <tr><td>\ref ARM_ETH_MAC_ADDRESS_ALL        </td><td>               9      </td><td>Any Frame address        </td><td>Accept frames with any address (Promiscuous Mode)</td></tr>
 389 </table>
 390
 391 The table <b>Parameter \em arg for FLUSH</b> lists the \em arg values for the \em control \b ARM_ETH_MAC_FLUSH.
 392 The \em arg values can be ORed.
 393
 394 <table class="cmtable" summary="">
 395 <tr><th colspan="4">Parameter \em arg for FLUSH </th></tr>
 396 <tr><th>Parameter \em arg          </th><th>    Bit    </th><th>     Category     </th><th> Description                  </th></tr>
 397 <tr><td>\ref ARM_ETH_MAC_FLUSH_RX  </td><td>    1      </td><td>  Receive buffer  </td><td> Flush the Receive buffer     </td></tr>
 398 <tr><td>\ref ARM_ETH_MAC_FLUSH_TX  </td><td>    2      </td><td>  Transmit buffer </td><td> Flush the Transmit buffer    </td></tr>
 399 </table>
 400
 401 The table <b>Parameter \em arg for VLAN Filter</b> lists the \em arg values for the \em control \b ARM_ETH_MAC_VLAN_FILTER.
 402 The \em arg values can be ORed.
 403
 404 <table class="cmtable" summary="">
 405 <tr><th colspan="4">Parameter \em arg for VLAN Filter</th></tr>
 406 <tr><th>Parameter \em arg                     </th><th>              Bit    </th><th>             Category    </th><th> Description                                </th></tr>
 407 <tr><td>\em value                             </td><td>              0..15  </td><td>             VLAN Tag    </td><td> Set VLAN Tag value                         </td></tr>
 408 <tr><td>\token{0}                             </td><td rowspan="2">  16     </td><td rowspan="2"> Use of VLAN </td><td> Compare the complete 16-bit VLAN Tag value </td></tr>
 409 <tr><td>\ref ARM_ETH_MAC_VLAN_FILTER_ID_ONLY  </td>                                                                <td>Compare only the 12-bit VLAN Identifier     </td></tr>
 410 <tr><td>\token{0}                             </td><td>              0..16  </td><td>             Disable     </td><td> Disable the VLAN Filter                    </td></tr>
 411 </table>
 412
 413
 414 \b Example:
 415
 416 \code
 417 ...
 418                                          // start transfer
 419     mac->Control(ARM_ETH_MAC_CONFIGURE, ARM_ETH_MAC_SPEED_100M | ARM_ETH_MAC_DUPLEX_FULL | ARM_ETH_MAC_ADDRESS_BROADCAST);
 420     mac->Control(ARM_ETH_MAC_CONTROL_TX, 1);
 421     mac->Control(ARM_ETH_MAC_CONTROL_RX, 1);
 422
 423 ...                                      // stop transfer
 424     mac->Control(ARM_ETH_MAC_FLUSH, ARM_ETH_MAC_FLUSH_TX | ARM_ETH_MAC_FLUSH_RX);
 425     mac->Control(ARM_ETH_MAC_CONTROL_TX, 0);
 426     mac->Control(ARM_ETH_MAC_CONTROL_RX, 0);
 427   }
 428 }
 429 \endcode
 430
 431 For a complete example, refer to  \ref eth_interface_gr - Driver Functions.
 432
 433 *******************************************************************************************************************/
 434
 435 int32_t ARM_ETH_MAC_ControlTimer (uint32_t control, ARM_ETH_MAC_TIME *time)  {
 436
 437 }
 438 /**
 439 \fn int32_t ARM_ETH_MAC_ControlTimer (uint32_t control, ARM_ETH_MAC_TIME *time)
 440 \details
 441 The function \b ARM_ETH_MAC_ControlTimer controls the timer required for PTP (Precision Time Protocol).
 442
 443 The parameter \em control receives \b ARM_ETH_MAC_TIMER_xxx codes to manage the timer for a PTP enabled Ethernet MAC interface. \n
 444 The parameter \em time is pointer to a structure that holds time information.
 445
 446 Mode Parameters: Timer Controls         | Description
 447 :---------------------------------------|:--------------------------------------------
 448 \ref ARM_ETH_MAC_TIMER_GET_TIME         | Retrieve the current time and update the content \ref ARM_ETH_MAC_TIME *time.
 449 \ref ARM_ETH_MAC_TIMER_SET_TIME         | Set the new time using the values provided with \ref ARM_ETH_MAC_TIME *time.
 450 \ref ARM_ETH_MAC_TIMER_INC_TIME         | Increment the current time by using the values provided with \ref ARM_ETH_MAC_TIME *time.
 451 \ref ARM_ETH_MAC_TIMER_DEC_TIME         | Decrement the current time by using the values provided with \ref ARM_ETH_MAC_TIME *time.
 452 \ref ARM_ETH_MAC_TIMER_SET_ALARM        | Set the alarm time to the values provided with \ref ARM_ETH_MAC_TIME *time.
 453 \ref ARM_ETH_MAC_TIMER_ADJUST_CLOCK     | Set the clock frequency; the value in time->ns is the <b>correction factor</b> in fractional format q31.
 454
 455 *******************************************************************************************************************/
 456
 457 int32_t ARM_ETH_MAC_PHY_Read (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)  {
 458
 459 }
 460 /**
 461 \fn int32_t ARM_ETH_MAC_PHY_Read (uint8_t phy_addr, uint8_t reg_addr, uint16_t *data)
 462 \details
 463
 464 Read Ethernet PHY Register through the Management Interface. The function is passed to \ref ARM_ETH_PHY_Initialize.
 465 The Ethernet PHY driver uses this function to read the value of PHY registers.
 466
 467 \b Example:
 468  - see \ref eth_interface_gr - Driver Functions
 469 *******************************************************************************************************************/
 470
 471 int32_t ARM_ETH_MAC_PHY_Write (uint8_t phy_addr, uint8_t reg_addr, uint16_t data)  {
 472
 473 }
 474 /**
 475 \fn int32_t ARM_ETH_MAC_PHY_Write (uint8_t phy_addr, uint8_t reg_addr, uint16_t data)
 476 \details
 477 The function \b ARM_ETH_MAC_PHY_Write writes to a Ethernet PHY register through the Management Interface.  The function is passed to \ref ARM_ETH_PHY_Initialize.
 478 The Ethernet PHY driver uses this function to write data to PHY registers.
 479
 480 \b Example:
 481  - see \ref eth_interface_gr - Driver Functions
 482
 483 *******************************************************************************************************************/
 484
 485 void ARM_ETH_MAC_SignalEvent (uint32_t event)  {
 486   ;
 487 }
 488 /**
 489 \fn void ARM_ETH_MAC_SignalEvent (uint32_t event)
 490 \details
 491
 492 The function \b ARM_ETH_MAC_SignalEvent is a callback function registered by the function
 493 \ref ARM_ETH_MAC_Initialize. This function is typically called from interrupt service routines (ISR) to indicate that
 494 a frame is processed or a special event occurred.
 495
 496 The parameter \a event indicates one or more events that occurred during driver operation.
 497 Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.
 498
 499 Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the
 500 data fields of the structure \ref ARM_ETH_MAC_CAPABILITIES, which can be retrieved with the function \ref ARM_ETH_MAC_GetCapabilities.
 501
 502 The following events can be generated:
 503
 504 Parameter \em event                      | Bit | Description
 505 :----------------------------------------|:---:|:----------------------------------------
 506 \ref ARM_ETH_MAC_EVENT_RX_FRAME          |  0  | Occurs after a frame is received. Frame can be read by calling \ref ARM_ETH_MAC_ReadFrame.
 507 \ref ARM_ETH_MAC_EVENT_TX_FRAME          |  1  | Occurs after call to \ref ARM_ETH_MAC_SendFrame to indicate that the frame is transmitted.
 508 \ref ARM_ETH_MAC_EVENT_WAKEUP            |  2  | Indicates that a Magic Packet is received while the driver is in Sleep mode (set by \ref ARM_ETH_MAC_SLEEP using \ref ARM_ETH_MAC_Control).
 509 \ref ARM_ETH_MAC_EVENT_TIMER_ALARM       |  3  | Indicates that a Timer Alarm occurred that was set with \ref ARM_ETH_MAC_TIMER_SET_ALARM using ARM_ETH_MAC_ControlTimer.
 510
 511 *******************************************************************************************************************/
 512
 513
 514 /**
 515 \defgroup eth_mac_control Ethernet MAC Control Codes
 516 \ingroup eth_mac_interface_gr
 517 \brief Configure and control the Ethernet MAC using the \ref ARM_ETH_MAC_Control.
 518 \details
 519 @{
 520 Many parameters of the Ethernet MAC driver are configured using the \ref ARM_ETH_MAC_Control function.
 521
 522 The various Ethernet MAC control codes define:
 523
 524   - \ref eth_mac_ctrls                configures and controls the Ethernet MAC interface
 525   - \ref eth_mac_configuration_ctrls  specifies speed mode, link mode, checksum, and frame filtering modes
 526   - \ref eth_mac_flush_flag_ctrls     specify controls to flush a buffer
 527   - \ref eth_mac_vlan_filter_ctrls    specifies whether to compare only the VLAN Identifier
 528
 529 Refer to the \ref ARM_ETH_MAC_Control function for further details.
 530 */
 531
 532 /**
 533 \defgroup eth_mac_ctrls Ethernet MAC Controls
 534 \brief Configure and control the Ethernet MAC interface.
 535 \details
 536 @{
 537 \def ARM_ETH_MAC_CONFIGURE
 538 \sa ARM_ETH_MAC_Control
 539 \def ARM_ETH_MAC_CONTROL_TX
 540 \sa ARM_ETH_MAC_Control
 541 \def ARM_ETH_MAC_CONTROL_RX
 542 \sa ARM_ETH_MAC_Control
 543 \def ARM_ETH_MAC_FLUSH
 544 \sa ARM_ETH_MAC_Control
 545 \def ARM_ETH_MAC_SLEEP
 546 \sa ARM_ETH_MAC_Control
 547 \def ARM_ETH_MAC_VLAN_FILTER
 548 \sa ARM_ETH_MAC_Control
 549 @}
 550 */
 551
 552
 553 /**
 554 \defgroup eth_mac_configuration_ctrls Ethernet MAC Configuration
 555 \brief Specifies speed mode, link mode, checksum, and frame filtering modes.
 556 \details
 557 @{
 558 The function \ref ARM_ETH_MAC_Control with \em control = \ref ARM_ETH_MAC_CONFIGURE configures the Ethernet MAC interface
 559 as specified with \em arg listed bellow.
 560
 561 \def ARM_ETH_MAC_SPEED_10M
 562 \def ARM_ETH_MAC_SPEED_100M
 563 \def ARM_ETH_MAC_SPEED_1G
 564 \def ARM_ETH_MAC_DUPLEX_HALF
 565 \def ARM_ETH_MAC_DUPLEX_FULL
 566 \def ARM_ETH_MAC_LOOPBACK
 567 \def ARM_ETH_MAC_CHECKSUM_OFFLOAD_RX
 568 \def ARM_ETH_MAC_CHECKSUM_OFFLOAD_TX
 569 \def ARM_ETH_MAC_ADDRESS_BROADCAST
 570 \def ARM_ETH_MAC_ADDRESS_MULTICAST
 571 \def ARM_ETH_MAC_ADDRESS_ALL
 572 @}
 573 */
 574
 575 /**
 576 \defgroup eth_mac_flush_flag_ctrls  Ethernet MAC Flush Flags
 577 \brief Specify controls to flush a buffer
 578 \details
 579 @{
 580 The function \ref ARM_ETH_MAC_Control with \em control = \ref ARM_ETH_MAC_FLUSH flushes the buffer
 581 which is specified with \em arg listed bellow.
 582
 583 \def ARM_ETH_MAC_FLUSH_RX
 584 \def ARM_ETH_MAC_FLUSH_TX
 585 @}
 586 */
 587
 588
 589 /**
 590 \defgroup eth_mac_vlan_filter_ctrls   Ethernet MAC VLAN Filter Flag
 591 \brief Specify whether to compare only the VLAN Identifier
 592 \details
 593 @{
 594 The function \ref ARM_ETH_MAC_Control with \em control = \ref ARM_ETH_MAC_VLAN_FILTER configures the VLAN Filter for received frames as specified with \em arg.
 595
 596 By default the complete VLAN Tag (16-bit) is compared. When \ref ARM_ETH_MAC_VLAN_FILTER_ID_ONLY is specified then only the VLAN Identifier (12-bit) is compared.
 597
 598 Specifying \em arg=0 disables the VLAN Filter.
 599
 600 \def ARM_ETH_MAC_VLAN_FILTER_ID_ONLY
 601 @}
 602 */
 603
 604
 605 /**
 606 @} */  // end group eth_mac_control
 607
 608
 609 /**
 610 \defgroup eth_mac_time_control Ethernet MAC Timer Control Codes
 611 \ingroup eth_mac_interface_gr
 612 \brief Control codes for \ref ARM_ETH_MAC_ControlTimer function.
 613 \details
 614 The following timer controls are used as parameter \em control for the \ref ARM_ETH_MAC_ControlTimer function:
 615 @{
 616 \def ARM_ETH_MAC_TIMER_GET_TIME
 617 \sa ARM_ETH_MAC_ControlTimer
 618 \def ARM_ETH_MAC_TIMER_SET_TIME
 619 \sa ARM_ETH_MAC_ControlTimer
 620 \def ARM_ETH_MAC_TIMER_INC_TIME
 621 \sa ARM_ETH_MAC_ControlTimer
 622 \def ARM_ETH_MAC_TIMER_DEC_TIME
 623 \sa ARM_ETH_MAC_ControlTimer
 624 \def ARM_ETH_MAC_TIMER_SET_ALARM
 625 \sa ARM_ETH_MAC_ControlTimer
 626 \def ARM_ETH_MAC_TIMER_ADJUST_CLOCK
 627 \sa ARM_ETH_MAC_ControlTimer
 628 @}
 629 */
 630
 631
 632 /**
 633 \defgroup eth_mac_frame_transmit_ctrls Ethernet MAC Frame Transmit Flags
 634 \brief Specify frame transmit flags
 635 \details
 636 @{
 637 \def ARM_ETH_MAC_TX_FRAME_FRAGMENT
 638 \sa ARM_ETH_MAC_SendFrame
 639 \def ARM_ETH_MAC_TX_FRAME_EVENT
 640 \sa ARM_ETH_MAC_SendFrame
 641 \def ARM_ETH_MAC_TX_FRAME_TIMESTAMP
 642 \sa ARM_ETH_MAC_SendFrame
 643 @}
 644 */
 645
 646
 647
 648 /**
 649 @}
 650 */
 651 // End ETH MAC Interface