source: mainline/uspace/lib/nic/include/nic.h@ c6ae4c2

lfn serial ticket/834-toolchain-update topic/msim-upgrade topic/simplify-dev-export
Last change on this file since c6ae4c2 was c6ae4c2, checked in by Martin Decky <martin@…>, 14 years ago

implement basic DMA memory mapping routines
no persistent locking (pinning) of the DMA memory is currently implemented (this can be dangerous)
no unmapping is implemented
special allocations (< 16 MB, < 4 GB) are not supported yet
  • Property mode set to 100644
File size: 10.4 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 <ddf/driver.h>
43#include <device/hw_res_parsed.h>
44#include <net/packet.h>
45#include <ops/nic.h>
46
47struct nic;
48typedef struct nic nic_t;
49
50/**
51 * Single WOL virtue descriptor.
52 */
53typedef struct nic_wol_virtue {
54 link_t item;
55 nic_wv_id_t id;
56 nic_wv_type_t type;
57 const void *data;
58 size_t length;
59 struct nic_wol_virtue *next;
60} nic_wol_virtue_t;
61
62/**
63 * Simple structure for sending the allocated frames (packets) in a list.
64 */
65typedef struct {
66 link_t link;
67 packet_t *packet;
68} nic_frame_t;
69
70typedef list_t nic_frame_list_t;
71
72/**
73 * Handler for writing packet data to the NIC device.
74 * The function is responsible for releasing the packet.
75 * It does not return anything, if some error is detected the function just
76 * silently fails (logging on debug level is suggested).
77 *
78 * @param nic_data
79 * @param packet Pointer to the packet to be sent
80 */
81typedef void (*write_packet_handler)(nic_t *, packet_t *);
82/**
83 * The handler for transitions between driver states.
84 * If the handler returns negative error code, the transition between
85 * states is canceled (the state is not changed).
86 *
87 * @param nic_data NICF main structure
88 *
89 * @return EOK If everything is all right.
90 * @return negative error code on error.
91 */
92typedef int (*state_change_handler)(nic_t *);
93/**
94 * Handler for unicast filtering mode change.
95 *
96 * @param nic_data NICF main structure
97 * @param new_mode The mode that should be set up
98 * @param address_list Addresses as argument to the mode
99 * @param address_count Number of addresses in the list
100 *
101 * @return EOK If the mode is set up
102 * @return ENOTSUP If this mode is not supported
103 */
104typedef int (*unicast_mode_change_handler)(nic_t *,
105 nic_unicast_mode_t, const nic_address_t *, size_t);
106/**
107 * Handler for multicast filtering mode change.
108 *
109 * @param nic_data NICF main structure
110 * @param new_mode The mode that should be set up
111 * @param address_list Addresses as argument to the mode
112 * @param address_count Number of addresses in the list
113 *
114 * @return EOK If the mode is set up
115 * @return ENOTSUP If this mode is not supported
116 */
117typedef int (*multicast_mode_change_handler)(nic_t *,
118 nic_multicast_mode_t, const nic_address_t *, size_t);
119/**
120 * Handler for broadcast filtering mode change.
121 *
122 * @param nic_data NICF main structure
123 * @param new_mode The mode that should be set up
124 *
125 * @return EOK If the mode is set up
126 * @return ENOTSUP If this mode is not supported
127 */
128typedef int (*broadcast_mode_change_handler)(nic_t *, nic_broadcast_mode_t);
129/**
130 * Handler for blocked sources list change.
131 *
132 * @param nic_data NICF main structure
133 * @param address_list Addresses as argument to the mode
134 * @param address_count Number of addresses in the list
135 */
136typedef void (*blocked_sources_change_handler)(nic_t *,
137 const nic_address_t *, size_t);
138/**
139 * Handler for VLAN filtering mask change.
140 * @param nic_data NICF main structure
141 * @param vlan_mask The new mask | NULL for disabling vlan filter
142 */
143typedef void (*vlan_mask_change_handler)(nic_t *, const nic_vlan_mask_t *);
144/**
145 * Handler called when a WOL virtue is added.
146 * If the maximum of accepted WOL virtues changes due to adding this virtue
147 * you should update the vector wol_virtues.caps_max.
148 * The driver is allowed to store pointer to the virtue data until
149 * on_wol_virtue_remove on these data is called (although probably this is
150 * not a good practice).
151 *
152 * @param nic_data NICF main structure
153 * @param virtue Structure with virtue description
154 *
155 * @return EOK If the filter can be used. Software emulation of the
156 * filter is activated unless the emulate is set to 0.
157 * @return ENOTSUP If this filter cannot work on this NIC (e.g. the NIC
158 * cannot run in promiscuous node or the limit of WOL
159 * packets' specifications was reached).
160 * @return ELIMIT If this filter must implemented in HW but currently the
161 * limit of these HW filters was reached.
162 */
163typedef int (*wol_virtue_add_handler)(nic_t *, const nic_wol_virtue_t *);
164/**
165 * Handler called when a WOL virtue is removed.
166 * If the maximum of accepted WOL virtues changes due to removing this
167 * virtue you should update the vector wol_virtues.caps_max.
168 *
169 * @param nic_data NICF main structure
170 * @param virtue Structure with virtue description
171 */
172typedef void (*wol_virtue_remove_handler)(nic_t *, const nic_wol_virtue_t *);
173/**
174 * Handler for poll mode change.
175 *
176 * @param nic_data NICF main structure
177 * @param mode Mode to be set up
178 * @param period New period of polling (with NIC_POLL_PERIODIC)
179 *
180 * @return EOK If the mode was fully setup
181 * @return ENOTSUP If NICF should do the periodic polling
182 * @return EINVAL If this mode cannot be set up under no circumstances
183 */
184typedef int (*poll_mode_change_handler)(nic_t *,
185 nic_poll_mode_t, const struct timeval *);
186/**
187 * Event handler called when the NIC should poll its buffers for a new frame
188 * (in NIC_POLL_PERIODIC or NIC_POLL_ON_DEMAND) modes.
189 *
190 * @param nic_data NICF main structure
191 */
192typedef void (*poll_request_handler)(nic_t *);
193
194/* nic_t allocation and deallocation */
195extern nic_t *nic_create_and_bind(ddf_dev_t *);
196extern void nic_unbind_and_destroy(ddf_dev_t *);
197
198/* Functions called in the main function */
199extern int nic_driver_init(const char *);
200extern void nic_driver_implement(driver_ops_t *, ddf_dev_ops_t *,
201 nic_iface_t *);
202
203/* Functions called in add_device */
204extern int nic_connect_to_services(nic_t *);
205extern int nic_register_as_ddf_fun(nic_t *, ddf_dev_ops_t *);
206extern int nic_get_resources(nic_t *, hw_res_list_parsed_t *);
207extern void nic_set_specific(nic_t *, void *);
208extern void nic_set_write_packet_handler(nic_t *, write_packet_handler);
209extern void nic_set_state_change_handlers(nic_t *,
210 state_change_handler, state_change_handler, state_change_handler);
211extern void nic_set_filtering_change_handlers(nic_t *,
212 unicast_mode_change_handler, multicast_mode_change_handler,
213 broadcast_mode_change_handler, blocked_sources_change_handler,
214 vlan_mask_change_handler);
215extern void nic_set_wol_virtue_change_handlers(nic_t *,
216 wol_virtue_add_handler, wol_virtue_remove_handler);
217extern void nic_set_poll_handlers(nic_t *,
218 poll_mode_change_handler, poll_request_handler);
219
220/* Functions called in device_added */
221extern int nic_ready(nic_t *);
222
223/* General driver functions */
224extern ddf_dev_t *nic_get_ddf_dev(nic_t *);
225extern ddf_fun_t *nic_get_ddf_fun(nic_t *);
226extern nic_t *nic_get_from_ddf_dev(ddf_dev_t *);
227extern nic_t *nic_get_from_ddf_fun(ddf_fun_t *);
228extern void *nic_get_specific(nic_t *);
229extern nic_device_state_t nic_query_state(nic_t *);
230extern void nic_set_tx_busy(nic_t *, int);
231extern int nic_report_address(nic_t *, const nic_address_t *);
232extern int nic_report_poll_mode(nic_t *, nic_poll_mode_t, struct timeval *);
233extern void nic_query_address(nic_t *, nic_address_t *);
234extern void nic_received_packet(nic_t *, packet_t *);
235extern void nic_received_noneth_packet(nic_t *, packet_t *);
236extern void nic_received_frame(nic_t *, nic_frame_t *);
237extern void nic_received_frame_list(nic_t *, nic_frame_list_t *);
238extern void nic_disable_interrupt(nic_t *, int);
239extern void nic_enable_interrupt(nic_t *, int);
240extern nic_poll_mode_t nic_query_poll_mode(nic_t *, struct timeval *);
241
242/* Statistics updates */
243extern void nic_report_send_ok(nic_t *, size_t, size_t);
244extern void nic_report_send_error(nic_t *, nic_send_error_cause_t, unsigned);
245extern void nic_report_receive_error(nic_t *, nic_receive_error_cause_t,
246 unsigned);
247extern void nic_report_collisions(nic_t *, unsigned);
248
249/* Packet / frame / frame list allocation and deallocation */
250extern packet_t *nic_alloc_packet(nic_t *, size_t);
251extern void nic_release_packet(nic_t *, packet_t *);
252extern nic_frame_t *nic_alloc_frame(nic_t *, size_t);
253extern nic_frame_list_t *nic_alloc_frame_list(void);
254extern void nic_frame_list_append(nic_frame_list_t *, nic_frame_t *);
255extern void nic_release_frame(nic_t *, nic_frame_t *);
256
257/* RXC query and report functions */
258extern void nic_report_hw_filtering(nic_t *, int, int, int);
259extern void nic_query_unicast(const nic_t *,
260 nic_unicast_mode_t *, size_t, nic_address_t *, size_t *);
261extern void nic_query_multicast(const nic_t *,
262 nic_multicast_mode_t *, size_t, nic_address_t *, size_t *);
263extern void nic_query_broadcast(const nic_t *, nic_broadcast_mode_t *);
264extern void nic_query_blocked_sources(const nic_t *,
265 size_t, nic_address_t *, size_t *);
266extern int nic_query_vlan_mask(const nic_t *, nic_vlan_mask_t *);
267extern int nic_query_wol_max_caps(const nic_t *, nic_wv_type_t);
268extern void nic_set_wol_max_caps(nic_t *, nic_wv_type_t, int);
269extern uint64_t nic_mcast_hash(const nic_address_t *, size_t);
270extern uint64_t nic_query_mcast_hash(nic_t *);
271
272/* Software period functions */
273extern void nic_sw_period_start(nic_t *);
274extern void nic_sw_period_stop(nic_t *);
275
276/* Packet DMA lock */
277extern int nic_dma_lock_packet(packet_t *, size_t, void **);
278extern int nic_dma_unlock_packet(packet_t *, size_t);
279
280#endif // __NIC_H__
281
282/** @}
283 */
Note: See TracBrowser for help on using the repository browser.