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