ethernet.h
Go to the documentation of this file.
1 /**
2  * @file ethernet.h
3  * @brief Ethernet
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2022 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.1.6
29  **/
30 
31 #ifndef _ETHERNET_H
32 #define _ETHERNET_H
33 
34 //Dependencies
35 #include "core/net.h"
36 
37 //Ethernet support
38 #ifndef ETH_SUPPORT
39  #define ETH_SUPPORT ENABLED
40 #elif (ETH_SUPPORT != ENABLED && ETH_SUPPORT != DISABLED)
41  #error ETH_SUPPORT parameter is not valid
42 #endif
43 
44 //Virtual interface support
45 #ifndef ETH_VIRTUAL_IF_SUPPORT
46  #define ETH_VIRTUAL_IF_SUPPORT DISABLED
47 #elif (ETH_VIRTUAL_IF_SUPPORT != ENABLED && ETH_VIRTUAL_IF_SUPPORT != DISABLED)
48  #error ETH_VIRTUAL_IF_SUPPORT parameter is not valid
49 #endif
50 
51 //VLAN support (IEEE 802.1Q)
52 #ifndef ETH_VLAN_SUPPORT
53  #define ETH_VLAN_SUPPORT DISABLED
54 #elif (ETH_VLAN_SUPPORT != ENABLED && ETH_VLAN_SUPPORT != DISABLED)
55  #error ETH_VLAN_SUPPORT parameter is not valid
56 #endif
57 
58 //VMAN support (IEEE 802.1ad)
59 #ifndef ETH_VMAN_SUPPORT
60  #define ETH_VMAN_SUPPORT DISABLED
61 #elif (ETH_VMAN_SUPPORT != ENABLED && ETH_VMAN_SUPPORT != DISABLED)
62  #error ETH_VMAN_SUPPORT parameter is not valid
63 #endif
64 
65 //LLC support (IEEE 802.2)
66 #ifndef ETH_LLC_SUPPORT
67  #define ETH_LLC_SUPPORT DISABLED
68 #elif (ETH_LLC_SUPPORT != ENABLED && ETH_LLC_SUPPORT != DISABLED)
69  #error ETH_LLC_SUPPORT parameter is not valid
70 #endif
71 
72 //Switch port tagging
73 #ifndef ETH_PORT_TAGGING_SUPPORT
74  #define ETH_PORT_TAGGING_SUPPORT DISABLED
75 #elif (ETH_PORT_TAGGING_SUPPORT != ENABLED && ETH_PORT_TAGGING_SUPPORT != DISABLED)
76  #error ETH_PORT_TAGGING_SUPPORT parameter is not valid
77 #endif
78 
79 //Size of tags used for switch port tagging
80 #ifndef ETH_PORT_TAG_SIZE
81  #define ETH_PORT_TAG_SIZE 4
82 #elif (ETH_PORT_TAG_SIZE < 0)
83  #error ETH_PORT_TAG_SIZE parameter is not valid
84 #endif
85 
86 //Hardware time stamping support
87 #ifndef ETH_TIMESTAMP_SUPPORT
88  #define ETH_TIMESTAMP_SUPPORT DISABLED
89 #elif (ETH_TIMESTAMP_SUPPORT != ENABLED && ETH_TIMESTAMP_SUPPORT != DISABLED)
90  #error ETH_TIMESTAMP_SUPPORT parameter is not valid
91 #endif
92 
93 //Size of the MAC address filter
94 #ifndef MAC_ADDR_FILTER_SIZE
95  #define MAC_ADDR_FILTER_SIZE 12
96 #elif (MAC_ADDR_FILTER_SIZE < 1)
97  #error MAC_ADDR_FILTER_SIZE parameter is not valid
98 #endif
99 
100 //CRC32 calculation using a pre-calculated lookup table
101 #ifndef ETH_FAST_CRC_SUPPORT
102  #define ETH_FAST_CRC_SUPPORT DISABLED
103 #elif (ETH_FAST_CRC_SUPPORT != ENABLED && ETH_FAST_CRC_SUPPORT != DISABLED)
104  #error ETH_FAST_CRC_SUPPORT parameter is not valid
105 #endif
106 
107 //Minimum Ethernet frame size
108 #define ETH_MIN_FRAME_SIZE 64
109 //Maximum Ethernet frame size
110 #define ETH_MAX_FRAME_SIZE 1518
111 //Ethernet header size
112 #define ETH_HEADER_SIZE 14
113 //Ethernet CRC field size
114 #define ETH_CRC_SIZE 4
115 //Ethernet maximum transmission unit
116 #define ETH_MTU 1500
117 
118 //VLAN tag control information
119 #define VLAN_PCP_POS 13
120 #define VLAN_DEI_POS 12
121 #define VLAN_VID_POS 0
122 #define VLAN_PCP_MASK 0xE000
123 #define VLAN_DEI_MASK 0x1000
124 #define VLAN_VID_MASK 0x0FFF
125 
126 //Copy MAC address
127 #define macCopyAddr(destMacAddr, srcMacAddr) osMemcpy(destMacAddr, srcMacAddr, sizeof(MacAddr))
128 
129 //Compare MAC addresses
130 #define macCompAddr(macAddr1, macAddr2) (!osMemcmp(macAddr1, macAddr2, sizeof(MacAddr)))
131 
132 //Determine whether a MAC address is a group address
133 #define macIsMulticastAddr(macAddr) (((macAddr)->b[0] & 0x01) != 0)
134 
135 //Copy EUI-64 address
136 #define eui64CopyAddr(destEui64Addr, srcEui64Addr) osMemcpy(destEui64Addr, srcEui64Addr, sizeof(Eui64))
137 
138 //Compare EUI-64 addresses
139 #define eui64CompAddr(eui64Addr1, eui64Addr2) (!osMemcmp(eui64Addr1, eui64Addr2, sizeof(Eui64)))
140 
141 //C++ guard
142 #ifdef __cplusplus
143 extern "C" {
144 #endif
145 
146 
147 /**
148  * @brief MAC address flags
149  **/
150 
151 typedef enum
152 {
154  MAC_ADDR_FLAG_LOCAL = 0x02
156 
157 
158 /**
159  * @brief Ethernet Type field
160  **/
161 
162 typedef enum
163 {
164  ETH_TYPE_IPV4 = 0x0800,
165  ETH_TYPE_ARP = 0x0806,
166  ETH_TYPE_RARP = 0x8035,
167  ETH_TYPE_VLAN = 0x8100,
168  ETH_TYPE_IPV6 = 0x86DD,
169  ETH_TYPE_EAPOL = 0x888E,
170  ETH_TYPE_VMAN = 0x88A8,
171  ETH_TYPE_LLDP = 0x88CC,
172  ETH_TYPE_PTP = 0x88F7
174 
175 
176 //CodeWarrior or Win32 compiler?
177 #if defined(__CWCC__) || defined(_WIN32)
178  #pragma pack(push, 1)
179 #endif
180 
181 
182 /**
183  * @brief MAC address
184  **/
185 
186 typedef __start_packed struct
187 {
188  __start_packed union
189  {
190  uint8_t b[6];
191  uint16_t w[3];
192  };
194 
195 
196 /**
197  * @brief EUI-64 identifier
198  **/
199 
200 typedef __start_packed struct
201 {
202  __start_packed union
203  {
204  uint8_t b[8];
205  uint16_t w[4];
206  uint32_t dw[2];
207  };
209 
210 
211 /**
212  * @brief Ethernet frame header
213  **/
214 
215 typedef __start_packed struct
216 {
218  MacAddr srcAddr; //6-11
219  uint16_t type; //12-13
220  uint8_t data[]; //14
222 
223 
224 /**
225  * @brief LLC header
226  **/
227 
228 typedef __start_packed struct
229 {
230  uint8_t dsap; //0
231  uint8_t ssap; //1
232  uint8_t control; //2
234 
235 
236 /**
237  * @brief VLAN tag
238  **/
239 
240 typedef __start_packed struct
241 {
242  uint16_t tci; //0-1
243  uint16_t type; //2-3
245 
246 
247 //CodeWarrior or Win32 compiler?
248 #if defined(__CWCC__) || defined(_WIN32)
249  #pragma pack(pop)
250 #endif
251 
252 
253 /**
254  * @brief MAC filter table entry
255  **/
256 
257 typedef struct
258 {
259  MacAddr addr; ///<MAC address
260  uint_t refCount; ///<Reference count for the current entry
264 
265 
266 /**
267  * @brief LLC frame received callback
268  **/
269 
270 typedef void (*LlcRxCallback)(NetInterface *interface, EthHeader *header,
271  const uint8_t *data, size_t length, NetRxAncillary *ancillary, void *param);
272 
273 
274 //Ethernet related constants
275 extern const MacAddr MAC_UNSPECIFIED_ADDR;
276 extern const MacAddr MAC_BROADCAST_ADDR;
277 extern const Eui64 EUI64_UNSPECIFIED_ADDR;
278 
279 //Ethernet related functions
280 error_t ethInit(NetInterface *interface);
281 
282 void ethProcessFrame(NetInterface *interface, uint8_t *frame, size_t length,
283  NetRxAncillary *ancillary);
284 
286  uint16_t type, NetBuffer *buffer, size_t offset, NetTxAncillary *ancillary);
287 
288 error_t ethAcceptMacAddr(NetInterface *interface, const MacAddr *macAddr);
289 error_t ethDropMacAddr(NetInterface *interface, const MacAddr *macAddr);
290 
292  void *param);
293 
295 
296 NetBuffer *ethAllocBuffer(size_t length, size_t *offset);
297 
298 error_t macStringToAddr(const char_t *str, MacAddr *macAddr);
299 char_t *macAddrToString(const MacAddr *macAddr, char_t *str);
300 void macAddrToEui64(const MacAddr *macAddr, Eui64 *interfaceId);
301 
302 void ethDumpHeader(const EthHeader *ethHeader);
303 
304 error_t eui64StringToAddr(const char_t *str, Eui64 *eui64);
305 char_t *eui64AddrToString(const Eui64 *eui64, char_t *str);
306 
307 //C++ guard
308 #ifdef __cplusplus
309 }
310 #endif
311 
312 #endif
__start_packed struct @4 VlanTag
VLAN tag.
__start_packed struct @1 Eui64
EUI-64 identifier.
uint8_t length
Definition: coap_common.h:191
@ ETH_TYPE_RARP
Definition: ethernet.h:166
int bool_t
Definition: compiler_port.h:48
__start_packed struct @2 EthHeader
Ethernet frame header.
MacAddr srcAddr
Definition: ethernet.h:218
uint8_t data[]
Definition: ethernet.h:220
uint8_t dsap
Definition: ethernet.h:230
uint16_t type
Definition: ethernet.h:219
error_t ethInit(NetInterface *interface)
Ethernet related initialization.
Definition: ethernet.c:66
uint8_t control
Definition: ethernet.h:232
error_t ethSendFrame(NetInterface *interface, const MacAddr *destAddr, uint16_t type, NetBuffer *buffer, size_t offset, NetTxAncillary *ancillary)
Send an Ethernet frame.
Definition: ethernet.c:402
Structure describing a buffer that spans multiple chunks.
Definition: net_mem.h:89
@ ETH_TYPE_PTP
Definition: ethernet.h:172
void macAddrToEui64(const MacAddr *macAddr, Eui64 *interfaceId)
Map a MAC address to the IPv6 modified EUI-64 identifier.
Definition: ethernet.c:943
@ MAC_ADDR_FLAG_LOCAL
Definition: ethernet.h:154
bool_t addFlag
Definition: ethernet.h:261
@ MAC_ADDR_FLAG_MULTICAST
Definition: ethernet.h:153
uint_t refCount
Reference count for the current entry.
Definition: ethernet.h:260
@ ETH_TYPE_IPV4
Definition: ethernet.h:164
error_t ethAttachLlcRxCalback(NetInterface *interface, LlcRxCallback callback, void *param)
Register LLC frame received callback.
Definition: ethernet.c:722
uint16_t w[3]
Definition: ethernet.h:191
MacAddr destAddr
Definition: ethernet.h:217
@ ETH_TYPE_LLDP
Definition: ethernet.h:171
__start_packed struct @0 MacAddr
MAC address.
void(* LlcRxCallback)(NetInterface *interface, EthHeader *header, const uint8_t *data, size_t length, NetRxAncillary *ancillary, void *param)
LLC frame received callback.
Definition: ethernet.h:270
error_t
Error codes.
Definition: error.h:43
const Eui64 EUI64_UNSPECIFIED_ADDR
Definition: ethernet.c:982
error_t ethDropMacAddr(NetInterface *interface, const MacAddr *macAddr)
Remove a unicast/multicast address from the MAC filter table.
Definition: ethernet.c:667
const MacAddr MAC_UNSPECIFIED_ADDR
Definition: ethernet.c:55
#define NetRxAncillary
Definition: net_misc.h:40
#define NetInterface
Definition: net.h:36
MacAddr addr
MAC address.
Definition: ethernet.h:259
char_t * macAddrToString(const MacAddr *macAddr, char_t *str)
Convert a MAC address to a dash delimited string.
Definition: ethernet.c:920
__start_packed struct _Ipv4Header __end_packed
@ ETH_TYPE_ARP
Definition: ethernet.h:165
char_t * eui64AddrToString(const Eui64 *eui64, char_t *str)
Convert an EUI-64 address to a dash delimited string.
Definition: ethernet.c:1090
#define NetTxAncillary
Definition: net_misc.h:36
Eui64 interfaceId
Definition: ipv6cp.h:69
@ ETH_TYPE_EAPOL
Definition: ethernet.h:169
error_t macStringToAddr(const char_t *str, MacAddr *macAddr)
Convert a string representation of a MAC address to a binary MAC address.
Definition: ethernet.c:822
EthType
Ethernet Type field.
Definition: ethernet.h:163
uint8_t b[6]
Definition: ethernet.h:190
@ ETH_TYPE_VLAN
Definition: ethernet.h:167
char char_t
Definition: compiler_port.h:43
MacAddrFlags
MAC address flags.
Definition: ethernet.h:152
MAC filter table entry.
Definition: ethernet.h:258
@ ETH_TYPE_IPV6
Definition: ethernet.h:168
error_t ethDetachLlcRxCalback(NetInterface *interface)
Unregister LLC frame received callback.
Definition: ethernet.c:750
uint16_t tci
Definition: ethernet.h:242
@ ETH_TYPE_VMAN
Definition: ethernet.h:170
NetBuffer * ethAllocBuffer(size_t length, size_t *offset)
Allocate a buffer to hold an Ethernet frame.
Definition: ethernet.c:778
const MacAddr MAC_BROADCAST_ADDR
Definition: ethernet.c:57
bool_t deleteFlag
Definition: ethernet.h:262
error_t ethAcceptMacAddr(NetInterface *interface, const MacAddr *macAddr)
Add a unicast/multicast address to the MAC filter table.
Definition: ethernet.c:597
void ethProcessFrame(NetInterface *interface, uint8_t *frame, size_t length, NetRxAncillary *ancillary)
Process an incoming Ethernet frame.
Definition: ethernet.c:86
uint8_t ssap
Definition: ethernet.h:231
unsigned int uint_t
Definition: compiler_port.h:45
__start_packed struct @3 LlcHeader
LLC header.
TCP/IP stack core.
void ethDumpHeader(const EthHeader *ethHeader)
Dump Ethernet header for debugging purpose.
Definition: ethernet.c:970
uint32_t dw[2]
Definition: ethernet.h:206
error_t eui64StringToAddr(const char_t *str, Eui64 *eui64)
Convert a string representation of an EUI-64 address to a binary EUI-64 address.
Definition: ethernet.c:992