ath9k_htc/target_firmware/magpie_fw_dev/target/inc/adf_net.h

   1 /*
   2  * Copyright (c) 2013 Qualcomm Atheros, Inc.
   3  * All rights reserved.
   4  *
   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:
   8  *
   9  *  * Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  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
  15  *    distribution.
  16  *
  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.
  20  *
  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.
  34  */
  35 /**
  36  * @defgroup adf_net_public network abstraction API
  37  */
  38
  39 /**
  40  * @ingroup adf_net_public
  41  * @file adf_net.h
  42  * These APIs abstract the OS networking stack from a driver.
  43  */
  44
  45 /**
  46  * @mainpage
  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.
  53  * @section Modules
  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.
  61  */
  62
  63 #ifndef _ADF_NET_H
  64 #define _ADF_NET_H
  65
  66 #include <adf_os_types.h>
  67 #include <adf_nbuf.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>
  72
  73 /*
  74  * check for a NULL handle
  75  * */
  76 #define ADF_NET_NULL        __ADF_NET_NULL
  77
  78 /**
  79  * @brief this register the driver to the shim, but won't get
  80  *        any handle until create device is called.
  81  *
  82  * @param[in] drv driver info structure
  83  *
  84  * @return status of operation
  85  */
  86 static inline a_status_t
  87 adf_net_register_drv(adf_drv_info_t *drv)
  88 {
  89     return(__adf_net_register_drv(drv));
  90 }
  91
  92
  93 /**
  94  * @brief deregister the driver from the shim
  95  *
  96  * @param[in] name driver name passed in adf_drv_info_t
  97  *
  98  * @see adf_net_register_drv()
  99  */
 100 static inline void
 101 adf_net_unregister_drv(a_uint8_t *drv_name)
 102 {
 103     __adf_net_unregister_drv(drv_name);
 104 }
 105
 106
 107 /**
 108  * @brief register a real device with the kernel
 109  *
 110  * @param[in] hdl driver handle for this device
 111  * @param[in] op per-device switch structure
 112  * @param[in] info basic device information
 113  *
 114  * @return opaque device handle
 115  */
 116 static inline adf_net_handle_t
 117 adf_net_dev_create(adf_drv_handle_t   hdl,
 118                    adf_dev_sw_t      *op,
 119                    adf_net_dev_info_t *info)
 120 {
 121     return (__adf_net_dev_create(hdl, op, info));
 122 }
 123
 124
 125 /**
 126  * @brief unregister a real device with the kernel
 127  *
 128  * @param[in] hdl opaque device handle returned by adf_net_dev_create()
 129  * @see adf_net_dev_create()
 130  */
 131 static inline void
 132 adf_net_dev_delete(adf_net_handle_t hdl)
 133 {
 134     __adf_net_dev_delete(hdl);
 135 }
 136
 137
 138 /**
 139  * @brief register a virtual device with the kernel.
 140  * A virtual device is always backed by a real device.
 141  *
 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
 146  *
 147  * @return opaque device handle
 148  *
 149  * @see adf_net_dev_create()
 150  */
 151 static inline adf_net_handle_t
 152 adf_net_vdev_create(adf_net_handle_t   dev_hdl,
 153                     adf_drv_handle_t   hdl,
 154                     adf_vdev_sw_t     *op,
 155                     adf_net_dev_info_t *info)
 156 {
 157     return (__adf_net_vdev_create(dev_hdl, hdl, op, info));
 158 }
 159
 160
 161 /**
 162  * @brief unregister the virtual device with the kernel.
 163  *
 164  * @param[in] hdl opaque device handle returned by adf_net_vdev_create()
 165  *
 166  * @see adf_net_vdev_create()
 167  */
 168 static inline void
 169 adf_net_vdev_delete(adf_net_handle_t hdl)
 170 {
 171     __adf_net_vdev_delete(hdl);
 172 }
 173
 174
 175 /**
 176  * @brief open the real device
 177  *
 178  * @param[in] hdl opaque device handle
 179  *
 180  * @return status of the operation
 181  *
 182  * @see adf_net_dev_create()
 183  */
 184 static inline a_status_t
 185 adf_net_dev_open(adf_net_handle_t hdl)
 186 {
 187         return (__adf_net_dev_open(hdl));
 188 }
 189
 190
 191 /**
 192  * @brief close the real device
 193  *
 194  * @param[in] hdl opaque device handle
 195  *
 196  * @see adf_net_dev_open()
 197  */
 198 static inline void
 199 adf_net_dev_close(adf_net_handle_t hdl)
 200 {
 201     __adf_net_dev_close(hdl);
 202 }
 203
 204
 205 /**
 206  * @brief transmit a network buffer using a device
 207  *
 208  * @param[in] hdl opaque device handle
 209  * @param[in] pkt network buffer to transmit
 210  *
 211  * @return status of the operation
 212  */
 213 static inline a_status_t
 214 adf_net_dev_tx(adf_net_handle_t hdl, adf_nbuf_t pkt)
 215 {
 216        return (__adf_net_dev_tx(hdl,pkt));
 217 }
 218
 219
 220 /**
 221  * @brief Checks if the interface is running or not
 222  *
 223  * @param[in] hdl opaque device handle
 224  *
 225  * @return true if running, false if not
 226  */
 227 static inline a_bool_t
 228 adf_net_is_running(adf_net_handle_t hdl)
 229 {
 230     return (__adf_net_is_running(hdl));
 231 }
 232
 233 /**
 234  * @brief Checks if the interface is up or not
 235  *
 236  * @param[in] hdl opaque device handle
 237  *
 238  * @return true if up, false if not
 239  */
 240 static inline a_bool_t
 241 adf_net_is_up(adf_net_handle_t hdl)
 242 {
 243     return (__adf_net_is_up(hdl));
 244 }
 245
 246
 247 /**
 248  * @brief check whether the carrier is available or not
 249  *
 250  * @param[in] hdl opaque device handle
 251  *
 252  * @return a_bool_t true if available, false if not
 253  */
 254 static inline a_bool_t
 255 adf_net_carrier_ok(adf_net_handle_t hdl)
 256 {
 257     return(__adf_net_carrier_ok(hdl));
 258 }
 259
 260
 261 /**
 262  * @brief inform the networking stack that the link is down
 263  *
 264  * @param[in] hdl opaque device handle
 265  */
 266 static inline void
 267 adf_net_carrier_off(adf_net_handle_t hdl)
 268 {
 269     __adf_net_carrier_off(hdl);
 270 }
 271
 272
 273 /**
 274  * @brief inform the networking stack that the link is up
 275  *
 276  * @param[in] hdl opaque device handle
 277  *
 278  * @see adf_net_carrier_off()
 279  */
 280 static inline void
 281 adf_net_carrier_on(adf_net_handle_t hdl)
 282 {
 283     __adf_net_carrier_on(hdl);
 284 }
 285
 286
 287 /*
 288  * Queue mgmt.
 289  * driver will use these to keep the native networking stack abreast of its
 290  * resource (descriptor) situation.
 291  */
 292
 293 /**
 294  * @brief inform the networking stack that the device is ready to receive
 295  * transmit packets. Typically called during init.
 296  *
 297  * @param[in] hdl opaque device handle
 298  */
 299 static inline void
 300 adf_net_start_queue(adf_net_handle_t hdl)
 301 {
 302     __adf_net_start_queue(hdl);
 303 }
 304
 305 /**
 306  * @brief inform the networking stack to stop sending transmit packets.
 307  * Typically called if the driver runs out of resources for the device.
 308  *
 309  * @param[in] hdl opaque device handle
 310  */
 311 static inline void
 312 adf_net_stop_queue(adf_net_handle_t hdl)
 313 {
 314     __adf_net_stop_queue(hdl);
 315 }
 316
 317
 318 /**
 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.
 322  *
 323  * @note adf_net_wake_queue() is the counterpart of adf_net_stop_queue()
 324  *
 325  * @param[in] hdl opaque device handle
 326  */
 327 static inline void
 328 adf_net_wake_queue(adf_net_handle_t hdl)
 329 {
 330     __adf_net_wake_queue(hdl);
 331 }
 332
 333
 334 /**
 335  * @brief Check the state of the queue
 336  *
 337  * @param[in] hdl opaque device handle
 338  *
 339  * @return true if stopped, false if not
 340  */
 341 static inline a_bool_t
 342 adf_net_queue_stopped(adf_net_handle_t hdl)
 343 {
 344     return(__adf_net_queue_stopped(hdl));
 345 }
 346
 347
 348 /**
 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.
 358  *
 359  * @param[in] hdl opaque device handle
 360  * @param[in] pkt network buffer to indicate
 361  * @param[in] len length of buffer
 362  */
 363 static inline void
 364 adf_net_indicate_packet(adf_net_handle_t hdl, adf_nbuf_t pkt, a_uint32_t len)
 365 {
 366     __adf_net_indicate_packet(hdl, pkt, len);
 367 }
 368
 369 /**
 370  * @brief use this when indicating a vlan tagged packet on RX
 371  *
 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
 376  *
 377  * @return status of operation
 378  */
 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)
 382 {
 383     return (__adf_net_indicate_vlanpkt(hdl, pkt, len, vid));
 384 }
 385
 386 /**
 387  * @brief get interface name
 388  *
 389  * @param[in] hdl opaque device handle
 390  *
 391  * @return name of interface
 392  */
 393 static inline const a_uint8_t *
 394 adf_net_ifname(adf_net_handle_t  hdl)
 395 {
 396     return (__adf_net_ifname(hdl));
 397 }
 398
 399 /**
 400  * @brief send management packets to apps (listener).
 401  * This is used for wireless applications.
 402  *
 403  * @param[in] hdl opaque device handle
 404  * @param[in] pkt network buffer to send
 405  * @param[in] len length of buffer
 406  */
 407 static inline void
 408 adf_net_fw_mgmt_to_app(adf_net_handle_t hdl, adf_nbuf_t pkt, a_uint32_t len)
 409 {
 410     __adf_net_fw_mgmt_to_app(hdl, pkt, len);
 411 }
 412 /**
 413  * @brief send wireless events to listening applications
 414  *
 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
 419  */
 420 static inline void
 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)
 424 {
 425     __adf_net_send_wireless_event(hdl, what, data, data_len);
 426 }
 427
 428 /**
 429  * @brief schedule the poll controller.
 430  *
 431  * @param[in] hdl opaque device handle
 432  */
 433 static inline void
 434 adf_net_poll_schedule(adf_net_handle_t hdl)
 435 {
 436     __adf_net_poll_schedule(hdl);
 437 }
 438
 439
 440 /**
 441  * @brief per cpu deffered callback (e.g. for RSS)
 442  *
 443  * @param[in] hdl opaque device handle
 444  * @param[in] cpu_msk
 445  * @param[in] arg
 446  */
 447 static inline void
 448 adf_net_poll_schedule_cpu(adf_net_handle_t hdl, a_uint32_t cpu_msk, void *arg)
 449 {
 450     __adf_net_poll_schedule_cpu(hdl, cpu_msk, arg);
 451 }
 452
 453 /**
 454  * @brief Get OS Handle from OS device object.
 455  *
 456  * @param[in] osdev OS device object
 457  *
 458  * @return OS handle
 459  */
 460 static inline adf_os_handle_t
 461 adf_net_dev_to_os(adf_os_device_t osdev)
 462 {
 463     return __adf_net_dev_to_os(osdev);
 464 }
 465
 466 /**
 467  * @brief Get OS Handle from OS net handle.
 468  *
 469  * @param[in] osdev OS net handle
 470  *
 471  * @return OS handle
 472  */
 473 static inline adf_os_handle_t
 474 adf_net_hdl_to_os(adf_net_handle_t hdl)
 475 {
 476     return __adf_net_hdl_to_os(hdl);
 477 }
 478
 479 #endif