target_firmware/magpie_fw_dev/target/inc/adf_net.h

   1 /**
   2  * @defgroup adf_net_public network abstraction API
   3  */
   4
   5 /**
   6  * @ingroup adf_net_public
   7  * @file adf_net.h
   8  * These APIs abstract the OS networking stack from a driver.
   9  */
  10
  11 /**
  12  * @mainpage
  13  * @section Introduction
  14  * The Atheros Driver Framework provides a mechanism to run the Atheros
  15  * WLAN driver on a variety of Operating Systems and Platforms. It achieves
  16  * this by abstracting all OS-specific and platform-specific functionality
  17  * the driver requires. This ensures the core logic in the driver is OS-
  18  * and platform-independent.
  19  * @section Modules
  20  * The driver framework consists of three main components:
  21  * @subsection sec1 Network Stack
  22  * This component abstracts the OS network stack. See @ref adf_net_public for details.
  23  * @subsection sec2 Network Buffer
  24  * This component abstracts the OS network buffer. See @ref adf_nbuf_public for details.
  25  * @subsection sec3 OS services
  26  * This component abstracts any OS services. See @ref adf_os_public for details.
  27  */
  28
  29 #ifndef _ADF_NET_H
  30 #define _ADF_NET_H
  31
  32 #include <adf_os_types.h>
  33 #include <adf_nbuf.h>
  34 #include "adf_net_types.h"
  35 #include "adf_net_wcmd.h"
  36 #include <adf_net_sw.h>
  37 #include <adf_net_pvt.h>
  38
  39 /*
  40  * check for a NULL handle
  41  * */
  42 #define ADF_NET_NULL        __ADF_NET_NULL
  43
  44 /**
  45  * @brief this register the driver to the shim, but won't get
  46  *        any handle until create device is called.
  47  *
  48  * @param[in] drv driver info structure
  49  *
  50  * @return status of operation
  51  */
  52 static inline a_status_t
  53 adf_net_register_drv(adf_drv_info_t *drv)
  54 {
  55     return(__adf_net_register_drv(drv));
  56 }
  57
  58
  59 /**
  60  * @brief deregister the driver from the shim
  61  *
  62  * @param[in] name driver name passed in adf_drv_info_t
  63  *
  64  * @see adf_net_register_drv()
  65  */
  66 static inline void
  67 adf_net_unregister_drv(a_uint8_t *drv_name)
  68 {
  69     __adf_net_unregister_drv(drv_name);
  70 }
  71
  72
  73 /**
  74  * @brief register a real device with the kernel
  75  *
  76  * @param[in] hdl driver handle for this device
  77  * @param[in] op per-device switch structure
  78  * @param[in] info basic device information
  79  *
  80  * @return opaque device handle
  81  */
  82 static inline adf_net_handle_t
  83 adf_net_dev_create(adf_drv_handle_t   hdl,
  84                    adf_dev_sw_t      *op,
  85                    adf_net_dev_info_t *info)
  86 {
  87     return (__adf_net_dev_create(hdl, op, info));
  88 }
  89
  90
  91 /**
  92  * @brief unregister a real device with the kernel
  93  *
  94  * @param[in] hdl opaque device handle returned by adf_net_dev_create()
  95  * @see adf_net_dev_create()
  96  */
  97 static inline void
  98 adf_net_dev_delete(adf_net_handle_t hdl)
  99 {
 100     __adf_net_dev_delete(hdl);
 101 }
 102
 103
 104 /**
 105  * @brief register a virtual device with the kernel.
 106  * A virtual device is always backed by a real device.
 107  *
 108  * @param[in] dev_hdl opaque device handle for the real device
 109  * @param[in] hdl driver handle for this virtual device
 110  * @param[in] op per-virtual-device switch structure
 111  * @param[in] info basic virtual device information
 112  *
 113  * @return opaque device handle
 114  *
 115  * @see adf_net_dev_create()
 116  */
 117 static inline adf_net_handle_t
 118 adf_net_vdev_create(adf_net_handle_t   dev_hdl,
 119                     adf_drv_handle_t   hdl,
 120                     adf_vdev_sw_t     *op,
 121                     adf_net_dev_info_t *info)
 122 {
 123     return (__adf_net_vdev_create(dev_hdl, hdl, op, info));
 124 }
 125
 126
 127 /**
 128  * @brief unregister the virtual device with the kernel.
 129  *
 130  * @param[in] hdl opaque device handle returned by adf_net_vdev_create()
 131  *
 132  * @see adf_net_vdev_create()
 133  */
 134 static inline void
 135 adf_net_vdev_delete(adf_net_handle_t hdl)
 136 {
 137     __adf_net_vdev_delete(hdl);
 138 }
 139
 140
 141 /**
 142  * @brief open the real device
 143  *
 144  * @param[in] hdl opaque device handle
 145  *
 146  * @return status of the operation
 147  *
 148  * @see adf_net_dev_create()
 149  */
 150 static inline a_status_t
 151 adf_net_dev_open(adf_net_handle_t hdl)
 152 {
 153         return (__adf_net_dev_open(hdl));
 154 }
 155
 156
 157 /**
 158  * @brief close the real device
 159  *
 160  * @param[in] hdl opaque device handle
 161  *
 162  * @see adf_net_dev_open()
 163  */
 164 static inline void
 165 adf_net_dev_close(adf_net_handle_t hdl)
 166 {
 167     __adf_net_dev_close(hdl);
 168 }
 169
 170
 171 /**
 172  * @brief transmit a network buffer using a device
 173  *
 174  * @param[in] hdl opaque device handle
 175  * @param[in] pkt network buffer to transmit
 176  *
 177  * @return status of the operation
 178  */
 179 static inline a_status_t
 180 adf_net_dev_tx(adf_net_handle_t hdl, adf_nbuf_t pkt)
 181 {
 182        return (__adf_net_dev_tx(hdl,pkt));
 183 }
 184
 185
 186 /**
 187  * @brief Checks if the interface is running or not
 188  *
 189  * @param[in] hdl opaque device handle
 190  *
 191  * @return true if running, false if not
 192  */
 193 static inline a_bool_t
 194 adf_net_is_running(adf_net_handle_t hdl)
 195 {
 196     return (__adf_net_is_running(hdl));
 197 }
 198
 199 /**
 200  * @brief Checks if the interface is up or not
 201  *
 202  * @param[in] hdl opaque device handle
 203  *
 204  * @return true if up, false if not
 205  */
 206 static inline a_bool_t
 207 adf_net_is_up(adf_net_handle_t hdl)
 208 {
 209     return (__adf_net_is_up(hdl));
 210 }
 211
 212
 213 /**
 214  * @brief check whether the carrier is available or not
 215  *
 216  * @param[in] hdl opaque device handle
 217  *
 218  * @return a_bool_t true if available, false if not
 219  */
 220 static inline a_bool_t
 221 adf_net_carrier_ok(adf_net_handle_t hdl)
 222 {
 223     return(__adf_net_carrier_ok(hdl));
 224 }
 225
 226
 227 /**
 228  * @brief inform the networking stack that the link is down
 229  *
 230  * @param[in] hdl opaque device handle
 231  */
 232 static inline void
 233 adf_net_carrier_off(adf_net_handle_t hdl)
 234 {
 235     __adf_net_carrier_off(hdl);
 236 }
 237
 238
 239 /**
 240  * @brief inform the networking stack that the link is up
 241  *
 242  * @param[in] hdl opaque device handle
 243  *
 244  * @see adf_net_carrier_off()
 245  */
 246 static inline void
 247 adf_net_carrier_on(adf_net_handle_t hdl)
 248 {
 249     __adf_net_carrier_on(hdl);
 250 }
 251
 252
 253 /*
 254  * Queue mgmt.
 255  * driver will use these to keep the native networking stack abreast of its
 256  * resource (descriptor) situation.
 257  */
 258
 259 /**
 260  * @brief inform the networking stack that the device is ready to receive
 261  * transmit packets. Typically called during init.
 262  *
 263  * @param[in] hdl opaque device handle
 264  */
 265 static inline void
 266 adf_net_start_queue(adf_net_handle_t hdl)
 267 {
 268     __adf_net_start_queue(hdl);
 269 }
 270
 271 /**
 272  * @brief inform the networking stack to stop sending transmit packets.
 273  * Typically called if the driver runs out of resources for the device.
 274  *
 275  * @param[in] hdl opaque device handle
 276  */
 277 static inline void
 278 adf_net_stop_queue(adf_net_handle_t hdl)
 279 {
 280     __adf_net_stop_queue(hdl);
 281 }
 282
 283
 284 /**
 285  * @brief inform the native stack to resume sending packets
 286  * to transmit.Typically called when the driver has resources
 287  * available again for the device.
 288  *
 289  * @note adf_net_wake_queue() is the counterpart of adf_net_stop_queue()
 290  *
 291  * @param[in] hdl opaque device handle
 292  */
 293 static inline void
 294 adf_net_wake_queue(adf_net_handle_t hdl)
 295 {
 296     __adf_net_wake_queue(hdl);
 297 }
 298
 299
 300 /**
 301  * @brief Check the state of the queue
 302  *
 303  * @param[in] hdl opaque device handle
 304  *
 305  * @return true if stopped, false if not
 306  */
 307 static inline a_bool_t
 308 adf_net_queue_stopped(adf_net_handle_t hdl)
 309 {
 310     return(__adf_net_queue_stopped(hdl));
 311 }
 312
 313
 314 /**
 315  * @brief This indicates a packet to the networking stack
 316  * (minus the FCS). The driver should just strip
 317  * the FCS and give the packet as a whole. This is
 318  * necessary because different native stacks have
 319  * different expectation of how they want to recv the
 320  * packet. This fucntion will strip off whatever is
 321  * required for the OS interface. The routine will also
 322  * figure out whether its being called in irq context and
 323  * call the appropriate OS API.
 324  *
 325  * @param[in] hdl opaque device handle
 326  * @param[in] pkt network buffer to indicate
 327  * @param[in] len length of buffer
 328  */
 329 static inline void
 330 adf_net_indicate_packet(adf_net_handle_t hdl, adf_nbuf_t pkt, a_uint32_t len)
 331 {
 332     __adf_net_indicate_packet(hdl, pkt, len);
 333 }
 334
 335 /**
 336  * @brief use this when indicating a vlan tagged packet on RX
 337  *
 338  * @param[in] hdl opaque device handle
 339  * @param[in] pkt network buffer to indicate
 340  * @param[in] len length of buffer
 341  * @param[in] vid vlan id
 342  *
 343  * @return status of operation
 344  */
 345 static inline a_status_t
 346 adf_net_indicate_vlanpkt(adf_net_handle_t hdl, adf_nbuf_t pkt,
 347                          a_uint32_t len, adf_net_vid_t *vid)
 348 {
 349     return (__adf_net_indicate_vlanpkt(hdl, pkt, len, vid));
 350 }
 351
 352 /**
 353  * @brief get interface name
 354  *
 355  * @param[in] hdl opaque device handle
 356  *
 357  * @return name of interface
 358  */
 359 static inline const a_uint8_t *
 360 adf_net_ifname(adf_net_handle_t  hdl)
 361 {
 362     return (__adf_net_ifname(hdl));
 363 }
 364
 365 /**
 366  * @brief send management packets to apps (listener).
 367  * This is used for wireless applications.
 368  *
 369  * @param[in] hdl opaque device handle
 370  * @param[in] pkt network buffer to send
 371  * @param[in] len length of buffer
 372  */
 373 static inline void
 374 adf_net_fw_mgmt_to_app(adf_net_handle_t hdl, adf_nbuf_t pkt, a_uint32_t len)
 375 {
 376     __adf_net_fw_mgmt_to_app(hdl, pkt, len);
 377 }
 378 /**
 379  * @brief send wireless events to listening applications
 380  *
 381  * @param[in] hdl opaque device handle
 382  * @param[in] what event to send
 383  * @param[in] data information about event
 384  * @param[in] data_len length of accompanying information
 385  */
 386 static inline void
 387 adf_net_send_wireless_event(adf_net_handle_t hdl,
 388                             adf_net_wireless_event_t what,
 389                             void *data, adf_os_size_t data_len)
 390 {
 391     __adf_net_send_wireless_event(hdl, what, data, data_len);
 392 }
 393
 394 /**
 395  * @brief schedule the poll controller.
 396  *
 397  * @param[in] hdl opaque device handle
 398  */
 399 static inline void
 400 adf_net_poll_schedule(adf_net_handle_t hdl)
 401 {
 402     __adf_net_poll_schedule(hdl);
 403 }
 404
 405
 406 /**
 407  * @brief per cpu deffered callback (e.g. for RSS)
 408  *
 409  * @param[in] hdl opaque device handle
 410  * @param[in] cpu_msk
 411  * @param[in] arg
 412  */
 413 static inline void
 414 adf_net_poll_schedule_cpu(adf_net_handle_t hdl, a_uint32_t cpu_msk, void *arg)
 415 {
 416     __adf_net_poll_schedule_cpu(hdl, cpu_msk, arg);
 417 }
 418
 419 /**
 420  * @brief Get OS Handle from OS device object.
 421  *
 422  * @param[in] osdev OS device object
 423  *
 424  * @return OS handle
 425  */
 426 static inline adf_os_handle_t
 427 adf_net_dev_to_os(adf_os_device_t osdev)
 428 {
 429     return __adf_net_dev_to_os(osdev);
 430 }
 431
 432 /**
 433  * @brief Get OS Handle from OS net handle.
 434  *
 435  * @param[in] osdev OS net handle
 436  *
 437  * @return OS handle
 438  */
 439 static inline adf_os_handle_t
 440 adf_net_hdl_to_os(adf_net_handle_t hdl)
 441 {
 442     return __adf_net_hdl_to_os(hdl);
 443 }
 444
 445 #endif