ChibiOS/HAL 9.0.0
hal_mac.h
Go to the documentation of this file.
1/*
2 ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15*/
16
17/**
18 * @file hal_mac.h
19 * @brief MAC Driver macros and structures.
20 * @addtogroup MAC
21 * @{
22 */
23
24#ifndef HAL_MAC_H
25#define HAL_MAC_H
26
27#if (HAL_USE_MAC == TRUE) || defined(__DOXYGEN__)
28
29/*===========================================================================*/
30/* Driver constants. */
31/*===========================================================================*/
32
33/**
34 * @name MAC event flags
35 * @{
36 */
37#define MAC_FLAGS_TX (1U << 0)
38#define MAC_FLAGS_RX (1U << 1)
39/** @} */
40
41/*===========================================================================*/
42/* Driver pre-compile time settings. */
43/*===========================================================================*/
44
45/**
46 * @name MAC configuration options
47 * @{
48 */
49/**
50 * @brief Enables an event sources for incoming packets.
51 */
52#if !defined(MAC_USE_ZERO_COPY) || defined(__DOXYGEN__)
53#define MAC_USE_ZERO_COPY FALSE
54#endif
55
56/**
57 * @brief Enables an event sources for incoming packets.
58 */
59#if !defined(MAC_USE_EVENTS) || defined(__DOXYGEN__)
60#define MAC_USE_EVENTS TRUE
61#endif
62/** @} */
63
64/*===========================================================================*/
65/* Derived constants and error checks. */
66/*===========================================================================*/
67
68/*===========================================================================*/
69/* Driver data structures and types. */
70/*===========================================================================*/
71
72/**
73 * @brief Type of a structure representing a MAC driver.
74 */
76
77/**
78 * @brief Type of structure representing a MAC configuration.
79 */
81
82/**
83 * @brief Type of structure representing a MAC transmit descriptor.
84 */
86
87/**
88 * @brief Type of structure representing a MAC receive descriptor.
89 */
91
92/**
93 * @brief Generic ETH notification callback type.
94 *
95 * @param[in] macp pointer to the @p MACDriver object
96 */
97typedef void (*maccb_t)(MACDriver *macp);
98
99/**
100 * @brief Driver state machine possible states.
101 */
102typedef enum {
103 MAC_UNINIT = 0, /**< Not initialized. */
104 MAC_STOP = 1, /**< Stopped. */
105 MAC_ACTIVE = 2 /**< Active. */
106} macstate_t;
107
108#include "hal_mac_lld.h"
109
110/**
111 * @brief Driver configuration structure.
112 * @note Implementations may extend this structure to contain more,
113 * architecture dependent, fields.
114 */
117#if defined(MAC_CONFIG_EXT_FIELDS)
118 MAC_CONFIG_EXT_FIELDS
119#endif
120};
121
122/**
123 * @brief Structure representing a MAC driver.
124 * @note Implementations may extend this structure to contain more,
125 * architecture dependent, fields.
126 */
128 /**
129 * @brief Driver state.
130 */
132 /**
133 * @brief Current configuration data.
134 */
136 /**
137 * @brief Transmit threads queue.
138 */
140 /**
141 * @brief Receive threads queue.
142 */
144#if MAC_USE_EVENTS || defined(__DOXYGEN__)
145 /**
146 * @brief MAC events source.
147 */
149#endif
150 /**
151 * @brief Locally held event flags for callback use.
152 */
154 /**
155 * @brief Events callback.
156 * @note Can be @p NULL.
157 */
159 /**
160 * @brief User argument.
161 * @note Can be retrieved through the @p ethp argument of the callback.
162 */
163 void *arg;
164 /* End of the mandatory fields.*/
166#if defined(MAC_DRIVER_EXT_FIELS)
167 MAC_DRIVER_EXT_FIELS
168#endif
169};
170
171/**
172 * @brief Structure representing a MAC transmit descriptor.
173 */
175 /**
176 * @brief Current write offset.
177 */
178 size_t offset;
179 /**
180 * @brief Available space size.
181 */
182 size_t size;
183 /* End of the mandatory fields.*/
185};
186
187/**
188 * @brief Structure representing a MAC receive descriptor.
189 */
191 /**
192 * @brief Current read offset.
193 */
194 size_t offset;
195 /**
196 * @brief Available data size.
197 */
198 size_t size;
199 /* End of the mandatory fields.*/
201};
202
203/*===========================================================================*/
204/* Driver macros. */
205/*===========================================================================*/
206
207/**
208 * @name Low level driver helper macros
209 * @{
210 */
211/**
212 * @brief MAC callback.
213 *
214 * @param[in] macp pointer to the @p MACDriver object
215 *
216 * @notapi
217 */
218#define __mac_callback(macp) do { \
219 if ((macp)->cb != NULL) { \
220 (macp)->cb(macp); \
221 } \
222} while (false)
223
224/**
225 * @brief MAC TX wakeup and event.
226 *
227 * @param[in] macp pointer to the @p MACDriver object
228 *
229 * @notapi
230 */
231#if (MAC_USE_EVENTS == TRUE) || defined(__DOXYGEN__)
232#define __mac_tx_wakeup(macp) do { \
233 osalSysLockFromISR(); \
234 osalThreadDequeueAllI(&(macp)->tdqueue, MSG_OK); \
235 (macp)->flags |= MAC_FLAGS_TX; \
236 osalEventBroadcastFlagsI(&(macp)->es, MAC_FLAGS_TX); \
237 osalSysUnlockFromISR(); \
238} while (false)
239#else
240#define __mac_tx_event(macp) do { \
241 osalSysLockFromISR(); \
242 osalThreadDequeueAllI(&(macp)->tdqueue, MSG_OK); \
243 (macp)->flags |= MAC_FLAGS_TX; \
244 osalSysUnlockFromISR(); \
245} while (false)
246#endif
247
248/**
249 * @brief MAC RX wakeup and event.
250 *
251 * @param[in] macp pointer to the @p MACDriver object
252 *
253 * @notapi
254 */
255#if (MAC_USE_EVENTS == TRUE) || defined(__DOXYGEN__)
256#define __mac_rx_wakeup(macp) do { \
257 osalSysLockFromISR(); \
258 osalThreadDequeueAllI(&(macp)->rdqueue, MSG_OK); \
259 (macp)->flags |= MAC_FLAGS_RX; \
260 osalEventBroadcastFlagsI(&(macp)->es, MAC_FLAGS_RX); \
261 osalSysUnlockFromISR(); \
262} while (false)
263#else
264#define __mac_rx_event(macp) do { \
265 osalSysLockFromISR(); \
266 osalThreadDequeueAllI(&(macp)->rdqueue, MSG_OK); \
267 (macp)->flags |= MAC_FLAGS_RX; \
268 osalSysUnlockFromISR(); \
269} while (false)
270#endif
271/** @} */
272
273/**
274 * @name Macro Functions
275 * @{
276 */
277/**
278 * @brief Associates a callback to the MAC instance.
279 *
280 * @param[in] macp pointer to the @p MACDriver object
281 * @param[in] f callback to be associated
282 */
283#define macSetCallbackX(macp, f) (siop)->cb = (f)
284
285/**
286 * @brief Returns the driver events source.
287 *
288 * @param[in] macp pointer to the @p MACDriver object
289 * @return The pointer to the @p EventSource structure.
290 *
291 * @api
292 */
293#if (MAC_USE_EVENTS == TRUE) || defined(__DOXYGEN__)
294#define macGetEventSource(macp) (&(macp)->es)
295#endif
296
297/**
298 * @brief Returns a transmission descriptor.
299 * @details One of the available transmission descriptors is locked and
300 * returned.
301 *
302 * @param[in] macp pointer to the @p MACDriver object
303 * @param[out] tdp pointer to a @p MACTransmitDescriptor structure
304 * @return The operation status.
305 * @retval MSG_OK the descriptor has been obtained.
306 * @retval MSG_TIMEOUT descriptor not available.
307 *
308 * @xclass
309 */
310#define macGetTransmitDescriptorX(macp, tdp) \
311 mac_lld_get_transmit_descriptor(macp, tdp)
312
313/**
314 * @brief Releases a transmit descriptor and starts the transmission of the
315 * enqueued data as a single frame.
316 *
317 * @param[in] tdp the pointer to the @p MACTransmitDescriptor structure
318 *
319 * @notapi
320 */
321#define macReleaseTransmitDescriptorX(tdp) \
322 mac_lld_release_transmit_descriptor(tdp)
323
324/**
325 * @brief Returns a receive descriptor.
326 *
327 * @param[in] macp pointer to the @p MACDriver object
328 * @param[out] rdp pointer to a @p MACReceiveDescriptor structure
329 * @return The operation status.
330 * @retval MSG_OK the descriptor has been obtained.
331 * @retval MSG_TIMEOUT descriptor not available.
332 *
333 * @xclass
334 */
335#define macGetReceiveDescriptorX(macp, rdp) \
336 mac_lld_get_receive_descriptor(macp, rdp)
337
338/**
339 * @brief Releases a receive descriptor.
340 * @details The descriptor and its buffer are made available for more incoming
341 * frames.
342 *
343 * @param[in] rdp the pointer to the @p MACReceiveDescriptor structure
344 *
345 * @xclass
346 */
347#define macReleaseReceiveDescriptorX(rdp) \
348 mac_lld_release_receive_descriptor(rdp)
349
350/**
351 * @brief Writes to a transmit descriptor's stream.
352 *
353 * @param[in] tdp pointer to a @p MACTransmitDescriptor structure
354 * @param[in] buf pointer to the buffer containing the data to be written
355 * @param[in] size number of bytes to be written
356 * @return The number of bytes written into the descriptor's
357 * stream, this value can be less than the amount
358 * specified in the parameter @p size if the maximum frame
359 * size is reached.
360 *
361 * @api
362 */
363#define macWriteTransmitDescriptor(tdp, buf, size) \
364 mac_lld_write_transmit_descriptor(tdp, buf, size)
365
366/**
367 * @brief Reads from a receive descriptor's stream.
368 *
369 * @param[in] rdp pointer to a @p MACReceiveDescriptor structure
370 * @param[in] buf pointer to the buffer that will receive the read data
371 * @param[in] size number of bytes to be read
372 * @return The number of bytes read from the descriptor's stream,
373 * this value can be less than the amount specified in the
374 * parameter @p size if there are no more bytes to read.
375 *
376 * @api
377 */
378#define macReadReceiveDescriptor(rdp, buf, size) \
379 mac_lld_read_receive_descriptor(rdp, buf, size)
380
381#if (MAC_USE_ZERO_COPY == TRUE) || defined(__DOXYGEN__)
382/**
383 * @brief Returns a pointer to the next transmit buffer in the descriptor
384 * chain.
385 * @note The API guarantees that enough buffers can be requested to fill
386 * a whole frame.
387 *
388 * @param[in] tdp pointer to a @p MACTransmitDescriptor structure
389 * @param[in] size size of the requested buffer. Specify the frame size
390 * on the first call then scale the value down subtracting
391 * the amount of data already copied into the previous
392 * buffers.
393 * @param[out] sizep pointer to variable receiving the real buffer size.
394 * The returned value can be less than the amount
395 * requested, this means that more buffers must be
396 * requested in order to fill the frame data entirely.
397 * @return Pointer to the returned buffer.
398 *
399 * @api
400 */
401#define macGetNextTransmitBuffer(tdp, size, sizep) \
402 mac_lld_get_next_transmit_buffer(tdp, size, sizep)
403
404/**
405 * @brief Returns a pointer to the next receive buffer in the descriptor
406 * chain.
407 * @note The API guarantees that the descriptor chain contains a whole
408 * frame.
409 *
410 * @param[in] rdp pointer to a @p MACReceiveDescriptor structure
411 * @param[out] sizep pointer to variable receiving the buffer size, it is
412 * zero when the last buffer has already been returned.
413 * @return Pointer to the returned buffer.
414 * @retval NULL if the buffer chain has been entirely scanned.
415 *
416 * @api
417 */
418#define macGetNextReceiveBuffer(rdp, sizep) \
419 mac_lld_get_next_receive_buffer(rdp, sizep)
420#endif /* MAC_USE_ZERO_COPY */
421/** @} */
422
423/*===========================================================================*/
424/* External declarations. */
425/*===========================================================================*/
426
427#ifdef __cplusplus
428extern "C" {
429#endif
430 void macInit(void);
431 void macObjectInit(MACDriver *macp);
432 msg_t macStart(MACDriver *macp, const MACConfig *config);
433 void macStop(MACDriver *macp);
437 sysinterval_t timeout);
441 sysinterval_t timeout);
443 bool macPollLinkStatus(MACDriver *macp);
444#ifdef __cplusplus
445}
446#endif
447
448#endif /* HAL_USE_MAC == TRUE */
449
450#endif /* HAL_MAC_H */
451
452/** @} */
#define mac_lld_transmit_descriptor_fields
Low level fields of the MAC transmit descriptor structure.
Definition hal_mac_lld.h:82
void macReleaseTransmitDescriptor(MACTransmitDescriptor *tdp)
void macStop(MACDriver *macp)
Deactivates the MAC peripheral.
Definition hal_mac.c:136
macstate_t
Driver state machine possible states.
Definition hal_mac.h:102
void macInit(void)
MAC Driver initialization.
Definition hal_mac.c:64
struct hal_mac_driver MACDriver
Type of a structure representing a MAC driver.
Definition hal_mac.h:75
void macObjectInit(MACDriver *macp)
Initialize the standard part of a MACDriver structure.
Definition hal_mac.c:76
struct hal_mac_receive_descriptor MACReceiveDescriptor
Type of structure representing a MAC receive descriptor.
Definition hal_mac.h:90
struct hal_mac_transmit_descriptor MACTransmitDescriptor
Type of structure representing a MAC transmit descriptor.
Definition hal_mac.h:85
#define mac_lld_receive_descriptor_fields
Low level fields of the MAC receive descriptor structure.
Definition hal_mac_lld.h:87
void macReleaseReceiveDescriptor(MACReceiveDescriptor *rdp)
#define mac_lld_driver_fields
Low level fields of the MAC driver structure.
Definition hal_mac_lld.h:72
msg_t macWaitTransmitDescriptor(MACDriver *macp, MACTransmitDescriptor *tdp, sysinterval_t timeout)
Allocates a transmission descriptor.
Definition hal_mac.c:187
msg_t macStart(MACDriver *macp, const MACConfig *config)
Configures and activates the MAC peripheral.
Definition hal_mac.c:99
#define mac_lld_config_fields
Low level fields of the MAC configuration structure.
Definition hal_mac_lld.h:77
eventflags_t macGetAndClearEventsI(MACDriver *macp)
Get and clears MAC event flags.
Definition hal_mac.c:160
void(* maccb_t)(MACDriver *macp)
Generic ETH notification callback type.
Definition hal_mac.h:97
msg_t macWaitReceiveDescriptor(MACDriver *macp, MACReceiveDescriptor *rdp, sysinterval_t timeout)
Waits for a received frame.
Definition hal_mac.c:227
bool macPollLinkStatus(MACDriver *macp)
Updates and returns the link status.
Definition hal_mac.c:259
struct hal_mac_config MACConfig
Type of structure representing a MAC configuration.
Definition hal_mac.h:80
@ MAC_ACTIVE
Definition hal_mac.h:105
@ MAC_UNINIT
Definition hal_mac.h:103
@ MAC_STOP
Definition hal_mac.h:104
uint32_t eventflags_t
Type of an event flags mask.
Definition osal.h:191
struct event_source event_source_t
Type of an event flags object.
Definition osal.h:201
int32_t msg_t
Type of a message.
Definition osal.h:159
uint32_t sysinterval_t
Type of system time interval.
Definition osal.h:169
PLATFORM MAC subsystem low level driver header.
Driver configuration structure.
Definition hal_mac.h:115
Structure representing a MAC driver.
Definition hal_mac.h:127
const MACConfig * config
Current configuration data.
Definition hal_mac.h:135
macstate_t state
Driver state.
Definition hal_mac.h:131
threads_queue_t rdqueue
Receive threads queue.
Definition hal_mac.h:143
event_source_t es
MAC events source.
Definition hal_mac.h:148
eventflags_t flags
Locally held event flags for callback use.
Definition hal_mac.h:153
maccb_t cb
Events callback.
Definition hal_mac.h:158
void * arg
User argument.
Definition hal_mac.h:163
threads_queue_t tdqueue
Transmit threads queue.
Definition hal_mac.h:139
Structure representing a MAC receive descriptor.
Definition hal_mac.h:190
size_t offset
Current read offset.
Definition hal_mac.h:194
size_t size
Available data size.
Definition hal_mac.h:198
Structure representing a MAC transmit descriptor.
Definition hal_mac.h:174
size_t offset
Current write offset.
Definition hal_mac.h:178
size_t size
Available space size.
Definition hal_mac.h:182
Type of a thread queue.
Definition osal.h:238