source: mainline/uspace/lib/nic/include/nic.h@ 02246b8

lfn serial ticket/834-toolchain-update topic/msim-upgrade topic/simplify-dev-export
Last change on this file since 02246b8 was 33b8d024, checked in by Jiří Zárevúcky <zarevucky.jiri@…>, 8 years ago

Remove const qualifier from the argument of free() and realloc(),
as well as in numerous other variables that hold ownership of memory.

By convention, a pointer that holds ownership is _never_ qualified by const.
This is reflected in the standard type signature of free() and realloc().
Allowing const pointers to hold ownership may seem superficially convenient,
but is actually quite confusing to experienced C programmers.
  • Property mode set to 100644
File size: 9.9 KB
Line 
1/*
2 * Copyright (c) 2011 Radim Vansa
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * - Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * - Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 * - The name of the author may not be used to endorse or promote products
15 * derived from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/**
30 * @addtogroup libnic
31 * @{
32 */
33/**
34 * @file
35 * @brief Public header exposing NICF to drivers
36 */
37
38#ifndef __NIC_H__
39#define __NIC_H__
40
41#include <adt/list.h>
42#include <adt/hash_table.h>
43#include <ddf/driver.h>
44#include <device/hw_res_parsed.h>
45#include <ops/nic.h>
46
47#define DEVICE_CATEGORY_NIC "nic"
48
49struct nic;
50typedef struct nic nic_t;
51
52/**
53 * Single WOL virtue descriptor.
54 */
55typedef struct nic_wol_virtue {
56 ht_link_t item;
57 nic_wv_id_t id;
58 nic_wv_type_t type;
59 void *data;
60 size_t length;
61 struct nic_wol_virtue *next;
62} nic_wol_virtue_t;
63
64/**
65 * Simple structure for sending lists of frames.
66 */
67typedef struct {
68 link_t link;
69 void *data;
70 size_t size;
71} nic_frame_t;
72
73typedef list_t nic_frame_list_t;
74
75/**
76 * Handler for writing frame data to the NIC device.
77 * The function is responsible for releasing the frame.
78 * It does not return anything, if some error is detected the function just
79 * silently fails (logging on debug level is suggested).
80 *
81 * @param nic_data
82 * @param data Pointer to frame data
83 * @param size Size of frame data in bytes
84 */
85typedef void (*send_frame_handler)(nic_t *, void *, size_t);
86
87/**
88 * The handler for transitions between driver states.
89 * If the handler returns error code, the transition between
90 * states is canceled (the state is not changed).
91 *
92 * @param nic_data NICF main structure
93 *
94 * @return EOK If everything is all right.
95 * @return error code on error.
96 */
97typedef errno_t (*state_change_handler)(nic_t *);
98
99/**
100 * Handler for unicast filtering mode change.
101 *
102 * @param nic_data NICF main structure
103 * @param new_mode The mode that should be set up
104 * @param address_list Addresses as argument to the mode
105 * @param address_count Number of addresses in the list
106 *
107 * @return EOK If the mode is set up
108 * @return ENOTSUP If this mode is not supported
109 */
110typedef errno_t (*unicast_mode_change_handler)(nic_t *,
111 nic_unicast_mode_t, const nic_address_t *, size_t);
112
113/**
114 * Handler for multicast filtering mode change.
115 *
116 * @param nic_data NICF main structure
117 * @param new_mode The mode that should be set up
118 * @param address_list Addresses as argument to the mode
119 * @param address_count Number of addresses in the list
120 *
121 * @return EOK If the mode is set up
122 * @return ENOTSUP If this mode is not supported
123 */
124typedef errno_t (*multicast_mode_change_handler)(nic_t *,
125 nic_multicast_mode_t, const nic_address_t *, size_t);
126
127/**
128 * Handler for broadcast filtering mode change.
129 *
130 * @param nic_data NICF main structure
131 * @param new_mode The mode that should be set up
132 *
133 * @return EOK If the mode is set up
134 * @return ENOTSUP If this mode is not supported
135 */
136typedef errno_t (*broadcast_mode_change_handler)(nic_t *, nic_broadcast_mode_t);
137
138/**
139 * Handler for blocked sources list change.
140 *
141 * @param nic_data NICF main structure
142 * @param address_list Addresses as argument to the mode
143 * @param address_count Number of addresses in the list
144 */
145typedef void (*blocked_sources_change_handler)(nic_t *,
146 const nic_address_t *, size_t);
147
148/**
149 * Handler for VLAN filtering mask change.
150 * @param nic_data NICF main structure
151 * @param vlan_mask The new mask | NULL for disabling vlan filter
152 */
153typedef void (*vlan_mask_change_handler)(nic_t *, const nic_vlan_mask_t *);
154
155/**
156 * Handler called when a WOL virtue is added.
157 * If the maximum of accepted WOL virtues changes due to adding this virtue
158 * you should update the vector wol_virtues.caps_max.
159 * The driver is allowed to store pointer to the virtue data until
160 * on_wol_virtue_remove on these data is called (although probably this is
161 * not a good practice).
162 *
163 * @param nic_data NICF main structure
164 * @param virtue Structure with virtue description
165 *
166 * @return EOK If the filter can be used. Software emulation of the
167 * filter is activated unless the emulate is set to 0.
168 * @return ENOTSUP If this filter cannot work on this NIC (e.g. the NIC
169 * cannot run in promiscuous node or the limit of WOL
170 * frames' specifications was reached).
171 * @return ELIMIT If this filter must implemented in HW but currently the
172 * limit of these HW filters was reached.
173 */
174typedef errno_t (*wol_virtue_add_handler)(nic_t *, const nic_wol_virtue_t *);
175
176/**
177 * Handler called when a WOL virtue is removed.
178 * If the maximum of accepted WOL virtues changes due to removing this
179 * virtue you should update the vector wol_virtues.caps_max.
180 *
181 * @param nic_data NICF main structure
182 * @param virtue Structure with virtue description
183 */
184typedef void (*wol_virtue_remove_handler)(nic_t *, const nic_wol_virtue_t *);
185
186/**
187 * Handler for poll mode change.
188 *
189 * @param nic_data NICF main structure
190 * @param mode Mode to be set up
191 * @param period New period of polling (with NIC_POLL_PERIODIC)
192 *
193 * @return EOK If the mode was fully setup
194 * @return ENOTSUP If NICF should do the periodic polling
195 * @return EINVAL If this mode cannot be set up under no circumstances
196 */
197typedef errno_t (*poll_mode_change_handler)(nic_t *,
198 nic_poll_mode_t, const struct timeval *);
199
200/**
201 * Event handler called when the NIC should poll its buffers for a new frame
202 * (in NIC_POLL_PERIODIC or NIC_POLL_ON_DEMAND) modes.
203 *
204 * @param nic_data NICF main structure
205 */
206typedef void (*poll_request_handler)(nic_t *);
207
208/* nic_t allocation and deallocation */
209extern nic_t *nic_create_and_bind(ddf_dev_t *);
210extern void nic_unbind_and_destroy(ddf_dev_t *);
211
212/* Functions called in the main function */
213extern errno_t nic_driver_init(const char *);
214extern void nic_driver_implement(driver_ops_t *, ddf_dev_ops_t *,
215 nic_iface_t *);
216
217/* Functions called in add_device */
218extern errno_t nic_get_resources(nic_t *, hw_res_list_parsed_t *);
219extern void nic_set_specific(nic_t *, void *);
220extern void nic_set_send_frame_handler(nic_t *, send_frame_handler);
221extern void nic_set_state_change_handlers(nic_t *,
222 state_change_handler, state_change_handler, state_change_handler);
223extern void nic_set_filtering_change_handlers(nic_t *,
224 unicast_mode_change_handler, multicast_mode_change_handler,
225 broadcast_mode_change_handler, blocked_sources_change_handler,
226 vlan_mask_change_handler);
227extern void nic_set_wol_virtue_change_handlers(nic_t *,
228 wol_virtue_add_handler, wol_virtue_remove_handler);
229extern void nic_set_poll_handlers(nic_t *,
230 poll_mode_change_handler, poll_request_handler);
231
232/* General driver functions */
233extern ddf_dev_t *nic_get_ddf_dev(nic_t *);
234extern ddf_fun_t *nic_get_ddf_fun(nic_t *);
235extern void nic_set_ddf_fun(nic_t *, ddf_fun_t *);
236extern nic_t *nic_get_from_ddf_dev(ddf_dev_t *);
237extern nic_t *nic_get_from_ddf_fun(ddf_fun_t *);
238extern void *nic_get_specific(nic_t *);
239extern nic_device_state_t nic_query_state(nic_t *);
240extern void nic_set_tx_busy(nic_t *, int);
241extern errno_t nic_report_address(nic_t *, const nic_address_t *);
242extern errno_t nic_report_poll_mode(nic_t *, nic_poll_mode_t, struct timeval *);
243extern void nic_query_address(nic_t *, nic_address_t *);
244extern void nic_received_frame(nic_t *, nic_frame_t *);
245extern void nic_received_frame_list(nic_t *, nic_frame_list_t *);
246extern nic_poll_mode_t nic_query_poll_mode(nic_t *, struct timeval *);
247
248/* Statistics updates */
249extern void nic_report_send_ok(nic_t *, size_t, size_t);
250extern void nic_report_send_error(nic_t *, nic_send_error_cause_t, unsigned);
251extern void nic_report_receive_error(nic_t *, nic_receive_error_cause_t,
252 unsigned);
253extern void nic_report_collisions(nic_t *, unsigned);
254
255/* Frame / frame list allocation and deallocation */
256extern nic_frame_t *nic_alloc_frame(nic_t *, size_t);
257extern nic_frame_list_t *nic_alloc_frame_list(void);
258extern void nic_frame_list_append(nic_frame_list_t *, nic_frame_t *);
259extern void nic_release_frame(nic_t *, nic_frame_t *);
260
261/* RXC query and report functions */
262extern void nic_report_hw_filtering(nic_t *, int, int, int);
263extern void nic_query_unicast(const nic_t *,
264 nic_unicast_mode_t *, size_t, nic_address_t *, size_t *);
265extern void nic_query_multicast(const nic_t *,
266 nic_multicast_mode_t *, size_t, nic_address_t *, size_t *);
267extern void nic_query_broadcast(const nic_t *, nic_broadcast_mode_t *);
268extern void nic_query_blocked_sources(const nic_t *,
269 size_t, nic_address_t *, size_t *);
270extern errno_t nic_query_vlan_mask(const nic_t *, nic_vlan_mask_t *);
271extern int nic_query_wol_max_caps(const nic_t *, nic_wv_type_t);
272extern void nic_set_wol_max_caps(nic_t *, nic_wv_type_t, int);
273extern uint64_t nic_mcast_hash(const nic_address_t *, size_t);
274extern uint64_t nic_query_mcast_hash(nic_t *);
275
276/* Software period functions */
277extern void nic_sw_period_start(nic_t *);
278extern void nic_sw_period_stop(nic_t *);
279
280#endif // __NIC_H__
281
282/** @}
283 */
Note: See TracBrowser for help on using the repository browser.