source: mainline/uspace/lib/c/include/nic/nic.h@ eec201d

Last change on this file since eec201d was 1433ecda, checked in by Jiri Svoboda <jiri@…>, 7 years ago

Fix cstyle: make ccheck-fix and commit only files where all the changes are good.
  • Property mode set to 100644
File size: 13.2 KB
Line 
1/*
2 * Copyright (c) 2009 Lukas Mejdrech
3 * Copyright (c) 2011 Radim Vansa
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 *
10 * - Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * - Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 * - The name of the author may not be used to endorse or promote products
16 * derived from this software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
19 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
20 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
21 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
22 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
23 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
24 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
25 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
26 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
27 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 */
29
30/** @addtogroup libc
31 * @{
32 */
33
34/** @file
35 * NIC interface definitions.
36 */
37
38#ifndef LIBC_NIC_H_
39#define LIBC_NIC_H_
40
41#include <nic/eth_phys.h>
42#include <stdbool.h>
43
44/** Ethernet address length. */
45#define ETH_ADDR 6
46
47/** MAC printing format */
48#define PRIMAC "%02x:%02x:%02x:%02x:%02x:%02x"
49
50/** MAC arguments */
51#define ARGSMAC(__a) \
52 (__a)[0], (__a)[1], (__a)[2], (__a)[3], (__a)[4], (__a)[5]
53
54/* Compare MAC address with specific value */
55#define MAC_EQUALS_VALUE(__a, __a0, __a1, __a2, __a3, __a4, __a5) \
56 ((__a)[0] == (__a0) && (__a)[1] == (__a1) && (__a)[2] == (__a2) \
57 && (__a)[3] == (__a3) && (__a)[4] == (__a4) && (__a)[5] == (__a5))
58
59#define MAC_IS_ZERO(__x) \
60 MAC_EQUALS_VALUE(__x, 0, 0, 0, 0, 0, 0)
61
62/** Max length of any hw nic address (currently only eth) */
63#define NIC_MAX_ADDRESS_LENGTH 16
64
65#define NIC_VENDOR_MAX_LENGTH 64
66#define NIC_MODEL_MAX_LENGTH 64
67#define NIC_PART_NUMBER_MAX_LENGTH 64
68#define NIC_SERIAL_NUMBER_MAX_LENGTH 64
69
70#define NIC_DEFECTIVE_LONG 0x0001
71#define NIC_DEFECTIVE_SHORT 0x0002
72#define NIC_DEFECTIVE_BAD_CRC 0x0010
73#define NIC_DEFECTIVE_BAD_IPV4_CHECKSUM 0x0020
74#define NIC_DEFECTIVE_BAD_IPV6_CHECKSUM 0x0040
75#define NIC_DEFECTIVE_BAD_TCP_CHECKSUM 0x0080
76#define NIC_DEFECTIVE_BAD_UDP_CHECKSUM 0x0100
77
78/**
79 * The bitmap uses single bit for each of the 2^12 = 4096 possible VLAN tags.
80 * This means its size is 4096/8 = 512 bytes.
81 */
82#define NIC_VLAN_BITMAP_SIZE 512
83
84#define NIC_DEVICE_PRINT_FMT "%x"
85
86/**
87 * Structure covering the MAC address.
88 */
89typedef struct nic_address {
90 uint8_t address[ETH_ADDR];
91} nic_address_t;
92
93/** Device state. */
94typedef enum nic_device_state {
95 /**
96 * Device present and stopped. Moving device to this state means to discard
97 * all settings and WOL virtues, rebooting the NIC to state as if the
98 * computer just booted (or the NIC was just inserted in case of removable
99 * NIC).
100 */
101 NIC_STATE_STOPPED,
102 /**
103 * If the NIC is in this state no packets (frames) are transmitted nor
104 * received. However, the settings are not restarted. You can use this state
105 * to temporarily disable transmition/reception or atomically (with respect
106 * to incoming/outcoming packets) change frames acceptance etc.
107 */
108 NIC_STATE_DOWN,
109 /** Device is normally operating. */
110 NIC_STATE_ACTIVE,
111 /** Just a constant to limit the state numbers */
112 NIC_STATE_MAX,
113} nic_device_state_t;
114
115/**
116 * Channel operating mode used on the medium.
117 */
118typedef enum {
119 NIC_CM_UNKNOWN,
120 NIC_CM_FULL_DUPLEX,
121 NIC_CM_HALF_DUPLEX,
122 NIC_CM_SIMPLEX
123} nic_channel_mode_t;
124
125/**
126 * Role for the device (used e.g. for 1000Gb ethernet)
127 */
128typedef enum {
129 NIC_ROLE_UNKNOWN,
130 NIC_ROLE_AUTO,
131 NIC_ROLE_MASTER,
132 NIC_ROLE_SLAVE
133} nic_role_t;
134
135/**
136 * Current state of the cable in the device
137 */
138typedef enum {
139 NIC_CS_UNKNOWN,
140 NIC_CS_PLUGGED,
141 NIC_CS_UNPLUGGED
142} nic_cable_state_t;
143
144/**
145 * Result of the requested operation
146 */
147typedef enum {
148 /** Successfully disabled */
149 NIC_RESULT_DISABLED,
150 /** Successfully enabled */
151 NIC_RESULT_ENABLED,
152 /** Not supported at all */
153 NIC_RESULT_NOT_SUPPORTED,
154 /** Temporarily not available */
155 NIC_RESULT_NOT_AVAILABLE,
156 /** Result extensions */
157 NIC_RESULT_FIRST_EXTENSION
158} nic_result_t;
159
160/** Device usage statistics. */
161typedef struct nic_device_stats {
162 /** Total packets received (accepted). */
163 unsigned long receive_packets;
164 /** Total packets transmitted. */
165 unsigned long send_packets;
166 /** Total bytes received (accepted). */
167 unsigned long receive_bytes;
168 /** Total bytes transmitted. */
169 unsigned long send_bytes;
170 /** Bad packets received counter. */
171 unsigned long receive_errors;
172 /** Packet transmition problems counter. */
173 unsigned long send_errors;
174 /** Number of frames dropped due to insufficient space in RX buffers */
175 unsigned long receive_dropped;
176 /** Number of frames dropped due to insufficient space in TX buffers */
177 unsigned long send_dropped;
178 /** Total multicast packets received (accepted). */
179 unsigned long receive_multicast;
180 /** Total broadcast packets received (accepted). */
181 unsigned long receive_broadcast;
182 /** The number of collisions due to congestion on the medium. */
183 unsigned long collisions;
184 /** Unicast packets received but not accepted (filtered) */
185 unsigned long receive_filtered_unicast;
186 /** Multicast packets received but not accepted (filtered) */
187 unsigned long receive_filtered_multicast;
188 /** Broadcast packets received but not accepted (filtered) */
189 unsigned long receive_filtered_broadcast;
190
191 /* detailed receive_errors */
192
193 /** Received packet length error counter. */
194 unsigned long receive_length_errors;
195 /** Receiver buffer overflow counter. */
196 unsigned long receive_over_errors;
197 /** Received packet with crc error counter. */
198 unsigned long receive_crc_errors;
199 /** Received frame alignment error counter. */
200 unsigned long receive_frame_errors;
201 /** Receiver fifo overrun counter. */
202 unsigned long receive_fifo_errors;
203 /** Receiver missed packet counter. */
204 unsigned long receive_missed_errors;
205
206 /* detailed send_errors */
207
208 /** Transmitter aborted counter. */
209 unsigned long send_aborted_errors;
210 /** Transmitter carrier errors counter. */
211 unsigned long send_carrier_errors;
212 /** Transmitter fifo overrun counter. */
213 unsigned long send_fifo_errors;
214 /** Transmitter carrier errors counter. */
215 unsigned long send_heartbeat_errors;
216 /** Transmitter window errors counter. */
217 unsigned long send_window_errors;
218
219 /* for cslip etc */
220
221 /** Total compressed packets received. */
222 unsigned long receive_compressed;
223 /** Total compressed packet transmitted. */
224 unsigned long send_compressed;
225} nic_device_stats_t;
226
227/** Errors corresponding to those in the nic_device_stats_t */
228typedef enum {
229 NIC_SEC_BUFFER_FULL,
230 NIC_SEC_ABORTED,
231 NIC_SEC_CARRIER_LOST,
232 NIC_SEC_FIFO_OVERRUN,
233 NIC_SEC_HEARTBEAT,
234 NIC_SEC_WINDOW_ERROR,
235 /* Error encountered during TX but with other type of error */
236 NIC_SEC_OTHER
237} nic_send_error_cause_t;
238
239/** Errors corresponding to those in the nic_device_stats_t */
240typedef enum {
241 NIC_REC_BUFFER_FULL,
242 NIC_REC_LENGTH,
243 NIC_REC_BUFFER_OVERFLOW,
244 NIC_REC_CRC,
245 NIC_REC_FRAME_ALIGNMENT,
246 NIC_REC_FIFO_OVERRUN,
247 NIC_REC_MISSED,
248 /* Error encountered during RX but with other type of error */
249 NIC_REC_OTHER
250} nic_receive_error_cause_t;
251
252/**
253 * Information about the NIC that never changes - name, vendor, model,
254 * capabilites and so on.
255 */
256typedef struct nic_device_info {
257 /* Device identification */
258 char vendor_name[NIC_VENDOR_MAX_LENGTH];
259 char model_name[NIC_MODEL_MAX_LENGTH];
260 char part_number[NIC_PART_NUMBER_MAX_LENGTH];
261 char serial_number[NIC_SERIAL_NUMBER_MAX_LENGTH];
262 uint16_t vendor_id;
263 uint16_t device_id;
264 uint16_t subsystem_vendor_id;
265 uint16_t subsystem_id;
266 /* Device capabilities */
267 uint16_t ethernet_support[ETH_PHYS_LAYERS];
268
269 /** The mask of all modes which the device can advertise
270 *
271 * see ETH_AUTONEG_ macros in nic/eth_phys.h of libc
272 */
273 uint32_t autoneg_support;
274} nic_device_info_t;
275
276/**
277 * Type of the ethernet frame
278 */
279typedef enum nic_frame_type {
280 NIC_FRAME_UNICAST,
281 NIC_FRAME_MULTICAST,
282 NIC_FRAME_BROADCAST
283} nic_frame_type_t;
284
285/**
286 * Specifies which unicast frames is the NIC receiving.
287 */
288typedef enum nic_unicast_mode {
289 NIC_UNICAST_UNKNOWN,
290 /** No unicast frames are received */
291 NIC_UNICAST_BLOCKED,
292 /** Only the frames with this NIC's MAC as destination are received */
293 NIC_UNICAST_DEFAULT,
294 /**
295 * Both frames with this NIC's MAC and those specified in the list are
296 * received
297 */
298 NIC_UNICAST_LIST,
299 /** All unicast frames are received */
300 NIC_UNICAST_PROMISC
301} nic_unicast_mode_t;
302
303typedef enum nic_multicast_mode {
304 NIC_MULTICAST_UNKNOWN,
305 /** No multicast frames are received */
306 NIC_MULTICAST_BLOCKED,
307 /** Frames with multicast addresses specified in this list are received */
308 NIC_MULTICAST_LIST,
309 /** All multicast frames are received */
310 NIC_MULTICAST_PROMISC
311} nic_multicast_mode_t;
312
313typedef enum nic_broadcast_mode {
314 NIC_BROADCAST_UNKNOWN,
315 /** Broadcast frames are dropped */
316 NIC_BROADCAST_BLOCKED,
317 /** Broadcast frames are received */
318 NIC_BROADCAST_ACCEPTED
319} nic_broadcast_mode_t;
320
321/**
322 * Structure covering the bitmap with VLAN tags.
323 */
324typedef struct nic_vlan_mask {
325 uint8_t bitmap[NIC_VLAN_BITMAP_SIZE];
326} nic_vlan_mask_t;
327
328/* WOL virtue identifier */
329typedef unsigned int nic_wv_id_t;
330
331/**
332 * Structure passed as argument for virtue NIC_WV_MAGIC_PACKET.
333 */
334typedef struct nic_wv_magic_packet_data {
335 uint8_t password[6];
336} nic_wv_magic_packet_data_t;
337
338/**
339 * Structure passed as argument for virtue NIC_WV_DIRECTED_IPV4
340 */
341typedef struct nic_wv_ipv4_data {
342 uint8_t address[4];
343} nic_wv_ipv4_data_t;
344
345/**
346 * Structure passed as argument for virtue NIC_WV_DIRECTED_IPV6
347 */
348typedef struct nic_wv_ipv6_data {
349 uint8_t address[16];
350} nic_wv_ipv6_data_t;
351
352/**
353 * WOL virtue types defining the interpretation of data passed to the virtue.
354 * Those tagged with S can have only single virtue active at one moment, those
355 * tagged with M can have multiple ones.
356 */
357typedef enum nic_wv_type {
358 /**
359 * Used for deletion of the virtue - in this case the mask, data and length
360 * arguments are ignored.
361 */
362 NIC_WV_NONE,
363 /** S
364 * Enabled <=> wakeup upon link change
365 */
366 NIC_WV_LINK_CHANGE,
367 /** S
368 * If this virtue is set up, wakeup can be issued by a magic packet frame.
369 * If the data argument is not NULL, it must contain
370 * nic_wv_magic_packet_data structure with the SecureOn password.
371 */
372 NIC_WV_MAGIC_PACKET,
373 /** M
374 * If the virtue is set up, wakeup can be issued by a frame targeted to
375 * device with MAC address specified in data. The data must contain
376 * nic_address_t structure.
377 */
378 NIC_WV_DESTINATION,
379 /** S
380 * Enabled <=> wakeup upon receiving broadcast frame
381 */
382 NIC_WV_BROADCAST,
383 /** S
384 * Enabled <=> wakeup upon receiving ARP Request
385 */
386 NIC_WV_ARP_REQUEST,
387 /** M
388 * If enabled, the wakeup is issued upon receiving frame with an IPv4 packet
389 * with IPv4 address specified in data. The data must contain
390 * nic_wv_ipv4_data structure.
391 */
392 NIC_WV_DIRECTED_IPV4,
393 /** M
394 * If enabled, the wakeup is issued upon receiving frame with an IPv4 packet
395 * with IPv6 address specified in data. The data must contain
396 * nic_wv_ipv6_data structure.
397 */
398 NIC_WV_DIRECTED_IPV6,
399 /** M
400 * First length/2 bytes in the argument are interpreted as mask, second
401 * length/2 bytes are interpreted as content.
402 * If enabled, the wakeup is issued upon receiving frame where the bytes
403 * with non-zero value in the mask equal to those in the content.
404 */
405 NIC_WV_FULL_MATCH,
406 /**
407 * Dummy value, do not use.
408 */
409 NIC_WV_MAX
410} nic_wv_type_t;
411
412/**
413 * Specifies the interrupt/polling mode used by the driver and NIC
414 */
415typedef enum nic_poll_mode {
416 /**
417 * NIC issues interrupts upon events.
418 */
419 NIC_POLL_IMMEDIATE,
420 /**
421 * Some uspace app calls nic_poll_now(...) in order to check the NIC state
422 * - no interrupts are received from the NIC.
423 */
424 NIC_POLL_ON_DEMAND,
425 /**
426 * The driver itself issues a poll request in a periodic manner. It is
427 * allowed to use hardware timer if the NIC supports it.
428 */
429 NIC_POLL_PERIODIC,
430 /**
431 * The driver itself issued a poll request in a periodic manner. The driver
432 * must create software timer, internal hardware timer of NIC must not be
433 * used even if the NIC supports it.
434 */
435 NIC_POLL_SOFTWARE_PERIODIC
436} nic_poll_mode_t;
437
438/**
439 * Says if this virtue type is a multi-virtue (there can be multiple virtues of
440 * this type at once).
441 *
442 * @param type
443 *
444 * @return true or false
445 */
446static inline int nic_wv_is_multi(nic_wv_type_t type)
447{
448 switch (type) {
449 case NIC_WV_FULL_MATCH:
450 case NIC_WV_DESTINATION:
451 case NIC_WV_DIRECTED_IPV4:
452 case NIC_WV_DIRECTED_IPV6:
453 return true;
454 default:
455 return false;
456 }
457}
458
459static inline const char *nic_device_state_to_string(nic_device_state_t state)
460{
461 switch (state) {
462 case NIC_STATE_STOPPED:
463 return "stopped";
464 case NIC_STATE_DOWN:
465 return "down";
466 case NIC_STATE_ACTIVE:
467 return "active";
468 default:
469 return "undefined";
470 }
471}
472
473#endif
474
475/** @}
476 */
Note: See TracBrowser for help on using the repository browser.