2 * Copyright (c) 2013 Qualcomm Atheros, Inc.
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted (subject to the limitations in the
7 * disclaimer below) provided that the following conditions are met:
9 * * Redistributions of source code must retain the above copyright
10 * 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
17 * * Neither the name of Qualcomm Atheros nor the names of its
18 * contributors may be used to endorse or promote products derived
19 * from this software without specific prior written permission.
21 * NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE
22 * GRANTED BY THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT
23 * HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
24 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
25 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
26 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
30 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
31 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
32 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
33 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 * @defgroup adf_net_public network abstraction API
40 * @ingroup adf_net_public
42 * These APIs abstract the OS networking stack from a driver.
47 * @section Introduction
48 * The Atheros Driver Framework provides a mechanism to run the Atheros
49 * WLAN driver on a variety of Operating Systems and Platforms. It achieves
50 * this by abstracting all OS-specific and platform-specific functionality
51 * the driver requires. This ensures the core logic in the driver is OS-
52 * and platform-independent.
54 * The driver framework consists of three main components:
55 * @subsection sec1 Network Stack
56 * This component abstracts the OS network stack. See @ref adf_net_public for details.
57 * @subsection sec2 Network Buffer
58 * This component abstracts the OS network buffer. See @ref adf_nbuf_public for details.
59 * @subsection sec3 OS services
60 * This component abstracts any OS services. See @ref adf_os_public for details.
66 #include <adf_os_types.h>
68 #include "adf_net_types.h"
69 #include "adf_net_wcmd.h"
70 #include <adf_net_sw.h>
71 #include <adf_net_pvt.h>
74 * check for a NULL handle
76 #define ADF_NET_NULL __ADF_NET_NULL
79 * @brief this register the driver to the shim, but won't get
80 * any handle until create device is called.
82 * @param[in] drv driver info structure
84 * @return status of operation
86 static inline a_status_t
87 adf_net_register_drv(adf_drv_info_t *drv)
89 return(__adf_net_register_drv(drv));
94 * @brief deregister the driver from the shim
96 * @param[in] name driver name passed in adf_drv_info_t
98 * @see adf_net_register_drv()
101 adf_net_unregister_drv(a_uint8_t *drv_name)
103 __adf_net_unregister_drv(drv_name);
108 * @brief register a real device with the kernel
110 * @param[in] hdl driver handle for this device
111 * @param[in] op per-device switch structure
112 * @param[in] info basic device information
114 * @return opaque device handle
116 static inline adf_net_handle_t
117 adf_net_dev_create(adf_drv_handle_t hdl,
119 adf_net_dev_info_t *info)
121 return (__adf_net_dev_create(hdl, op, info));
126 * @brief unregister a real device with the kernel
128 * @param[in] hdl opaque device handle returned by adf_net_dev_create()
129 * @see adf_net_dev_create()
132 adf_net_dev_delete(adf_net_handle_t hdl)
134 __adf_net_dev_delete(hdl);
139 * @brief register a virtual device with the kernel.
140 * A virtual device is always backed by a real device.
142 * @param[in] dev_hdl opaque device handle for the real device
143 * @param[in] hdl driver handle for this virtual device
144 * @param[in] op per-virtual-device switch structure
145 * @param[in] info basic virtual device information
147 * @return opaque device handle
149 * @see adf_net_dev_create()
151 static inline adf_net_handle_t
152 adf_net_vdev_create(adf_net_handle_t dev_hdl,
153 adf_drv_handle_t hdl,
155 adf_net_dev_info_t *info)
157 return (__adf_net_vdev_create(dev_hdl, hdl, op, info));
162 * @brief unregister the virtual device with the kernel.
164 * @param[in] hdl opaque device handle returned by adf_net_vdev_create()
166 * @see adf_net_vdev_create()
169 adf_net_vdev_delete(adf_net_handle_t hdl)
171 __adf_net_vdev_delete(hdl);
176 * @brief open the real device
178 * @param[in] hdl opaque device handle
180 * @return status of the operation
182 * @see adf_net_dev_create()
184 static inline a_status_t
185 adf_net_dev_open(adf_net_handle_t hdl)
187 return (__adf_net_dev_open(hdl));
192 * @brief close the real device
194 * @param[in] hdl opaque device handle
196 * @see adf_net_dev_open()
199 adf_net_dev_close(adf_net_handle_t hdl)
201 __adf_net_dev_close(hdl);
206 * @brief transmit a network buffer using a device
208 * @param[in] hdl opaque device handle
209 * @param[in] pkt network buffer to transmit
211 * @return status of the operation
213 static inline a_status_t
214 adf_net_dev_tx(adf_net_handle_t hdl, adf_nbuf_t pkt)
216 return (__adf_net_dev_tx(hdl,pkt));
221 * @brief Checks if the interface is running or not
223 * @param[in] hdl opaque device handle
225 * @return true if running, false if not
227 static inline a_bool_t
228 adf_net_is_running(adf_net_handle_t hdl)
230 return (__adf_net_is_running(hdl));
234 * @brief Checks if the interface is up or not
236 * @param[in] hdl opaque device handle
238 * @return true if up, false if not
240 static inline a_bool_t
241 adf_net_is_up(adf_net_handle_t hdl)
243 return (__adf_net_is_up(hdl));
248 * @brief check whether the carrier is available or not
250 * @param[in] hdl opaque device handle
252 * @return a_bool_t true if available, false if not
254 static inline a_bool_t
255 adf_net_carrier_ok(adf_net_handle_t hdl)
257 return(__adf_net_carrier_ok(hdl));
262 * @brief inform the networking stack that the link is down
264 * @param[in] hdl opaque device handle
267 adf_net_carrier_off(adf_net_handle_t hdl)
269 __adf_net_carrier_off(hdl);
274 * @brief inform the networking stack that the link is up
276 * @param[in] hdl opaque device handle
278 * @see adf_net_carrier_off()
281 adf_net_carrier_on(adf_net_handle_t hdl)
283 __adf_net_carrier_on(hdl);
289 * driver will use these to keep the native networking stack abreast of its
290 * resource (descriptor) situation.
294 * @brief inform the networking stack that the device is ready to receive
295 * transmit packets. Typically called during init.
297 * @param[in] hdl opaque device handle
300 adf_net_start_queue(adf_net_handle_t hdl)
302 __adf_net_start_queue(hdl);
306 * @brief inform the networking stack to stop sending transmit packets.
307 * Typically called if the driver runs out of resources for the device.
309 * @param[in] hdl opaque device handle
312 adf_net_stop_queue(adf_net_handle_t hdl)
314 __adf_net_stop_queue(hdl);
319 * @brief inform the native stack to resume sending packets
320 * to transmit.Typically called when the driver has resources
321 * available again for the device.
323 * @note adf_net_wake_queue() is the counterpart of adf_net_stop_queue()
325 * @param[in] hdl opaque device handle
328 adf_net_wake_queue(adf_net_handle_t hdl)
330 __adf_net_wake_queue(hdl);
335 * @brief Check the state of the queue
337 * @param[in] hdl opaque device handle
339 * @return true if stopped, false if not
341 static inline a_bool_t
342 adf_net_queue_stopped(adf_net_handle_t hdl)
344 return(__adf_net_queue_stopped(hdl));
349 * @brief This indicates a packet to the networking stack
350 * (minus the FCS). The driver should just strip
351 * the FCS and give the packet as a whole. This is
352 * necessary because different native stacks have
353 * different expectation of how they want to recv the
354 * packet. This fucntion will strip off whatever is
355 * required for the OS interface. The routine will also
356 * figure out whether its being called in irq context and
357 * call the appropriate OS API.
359 * @param[in] hdl opaque device handle
360 * @param[in] pkt network buffer to indicate
361 * @param[in] len length of buffer
364 adf_net_indicate_packet(adf_net_handle_t hdl, adf_nbuf_t pkt, a_uint32_t len)
366 __adf_net_indicate_packet(hdl, pkt, len);
370 * @brief use this when indicating a vlan tagged packet on RX
372 * @param[in] hdl opaque device handle
373 * @param[in] pkt network buffer to indicate
374 * @param[in] len length of buffer
375 * @param[in] vid vlan id
377 * @return status of operation
379 static inline a_status_t
380 adf_net_indicate_vlanpkt(adf_net_handle_t hdl, adf_nbuf_t pkt,
381 a_uint32_t len, adf_net_vid_t *vid)
383 return (__adf_net_indicate_vlanpkt(hdl, pkt, len, vid));
387 * @brief get interface name
389 * @param[in] hdl opaque device handle
391 * @return name of interface
393 static inline const a_uint8_t *
394 adf_net_ifname(adf_net_handle_t hdl)
396 return (__adf_net_ifname(hdl));
400 * @brief send management packets to apps (listener).
401 * This is used for wireless applications.
403 * @param[in] hdl opaque device handle
404 * @param[in] pkt network buffer to send
405 * @param[in] len length of buffer
408 adf_net_fw_mgmt_to_app(adf_net_handle_t hdl, adf_nbuf_t pkt, a_uint32_t len)
410 __adf_net_fw_mgmt_to_app(hdl, pkt, len);
413 * @brief send wireless events to listening applications
415 * @param[in] hdl opaque device handle
416 * @param[in] what event to send
417 * @param[in] data information about event
418 * @param[in] data_len length of accompanying information
421 adf_net_send_wireless_event(adf_net_handle_t hdl,
422 adf_net_wireless_event_t what,
423 void *data, adf_os_size_t data_len)
425 __adf_net_send_wireless_event(hdl, what, data, data_len);
429 * @brief schedule the poll controller.
431 * @param[in] hdl opaque device handle
434 adf_net_poll_schedule(adf_net_handle_t hdl)
436 __adf_net_poll_schedule(hdl);
441 * @brief per cpu deffered callback (e.g. for RSS)
443 * @param[in] hdl opaque device handle
448 adf_net_poll_schedule_cpu(adf_net_handle_t hdl, a_uint32_t cpu_msk, void *arg)
450 __adf_net_poll_schedule_cpu(hdl, cpu_msk, arg);
454 * @brief Get OS Handle from OS device object.
456 * @param[in] osdev OS device object
460 static inline adf_os_handle_t
461 adf_net_dev_to_os(adf_os_device_t osdev)
463 return __adf_net_dev_to_os(osdev);
467 * @brief Get OS Handle from OS net handle.
469 * @param[in] osdev OS net handle
473 static inline adf_os_handle_t
474 adf_net_hdl_to_os(adf_net_handle_t hdl)
476 return __adf_net_hdl_to_os(hdl);