ath9k_htc/target_firmware/magpie_fw_dev/target/htc/htc_api.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  * @File: htc_api.h
  37  *
  38  * @Abstract: host-target communications API
  39  *
  40  * @Notes:
  41  */
  42
  43 #ifndef __HTC_API_H__
  44 #define __HTC_API_H__
  45
  46 #include <osapi.h>
  47 #include <htc.h>
  48 #include <adf_nbuf.h>
  49 #include <buf_pool_api.h>
  50
  51 #define HTC_HDR_SZ          HTC_HDR_LENGTH
  52 #define HTC_BUFSZ_MAX_SEND  2048
  53
  54 typedef void (* HTC_SERVICE_ProcessRecvMsg)(HTC_ENDPOINT_ID EndpointID, adf_nbuf_t, adf_nbuf_t, void *ServiceCtx);
  55 typedef void (* HTC_SERVICE_ProcessSendBufferComplete)(HTC_ENDPOINT_ID EndpointID, adf_nbuf_t, void *ServiceCtx);
  56
  57 /* HTC service structure :
  58  * the caller is required to allocate storage for the service structure and register the
  59  * structure using HTC_RegisterService()  The service must set the following fields:
  60  *    ProcessRecvMsg
  61  *    ProcessSendBufferComplete
  62  *    ProcessConnect
  63  *    ServiceID
  64  *    MaxSvcMsgSize (for message validation)
  65  * */
  66 typedef struct _HTC_SERVICE {
  67         struct _HTC_SERVICE *pNext;
  68         /* Callback for processing receive messages.  HTC calls this callback whenever a
  69          * message arrives on the endpoint assigned to this service.
  70          * HTC_BUFFER is a chain of buffers containing a full application message.
  71          * HTC_BUFFER->buffer points to the start of the msg buffer (past the HTC header) */
  72         void (* ProcessRecvMsg)(HTC_ENDPOINT_ID EndpointID, adf_nbuf_t, adf_nbuf_t, void *ServiceCtx);
  73         /* callback to process completed send buffers */
  74         void (* ProcessSendBufferComplete)(HTC_ENDPOINT_ID EndpointID, adf_nbuf_t, void *ServiceCtx);
  75         /* optional callback when a connection request occurs.
  76          * The EndpointID is the assigned endpoint, the callback returns a connect
  77          * response status code to allow or disallow the connection.
  78          * pDataIn points to the optional meta data supplied in the connection request
  79          * pDataOut points to a buffer to send back meta data
  80          * If no callback is supplied, HTC assumes the connect is allowed  */
  81         A_UINT8 (* ProcessConnect)(struct _HTC_SERVICE *pService,
  82                                    HTC_ENDPOINT_ID EndpointID,
  83                                    A_UINT8 *pDataIn,
  84                                    int LengthIn,
  85                                    A_UINT8 *pDataOut,
  86                                    int *pLengthOut);
  87
  88         A_UINT16  ServiceID;        /* service ID to match connection requests */
  89         A_UINT16  ServiceFlags;     /* service flags */
  90         A_UINT16  MaxSvcMsgSize;    /* maximum length of service-specific messages exchanged on the endpoint */
  91         A_UINT16  TrailerSpcCheckLimit;  /* amount of space in each send buffer that HTC can check for trailer
  92                                             data. This should be set to the smallest HTC buffer that can be sent
  93                                             through the service. The service can disable trailer data insertion
  94                                             by setting this value to 0. */
  95         void      *ServiceCtx;
  96 } HTC_SERVICE;
  97
  98 #define HTC_SERVICE_FLAGS_CONNECTED         (1 << 0)  /* service has at least 1 connection */
  99
 100 #define IS_SERVICE_CONNECTED(s) ((s)->ServiceFlags & HTC_SERVICE_FLAGS_CONNECTED)
 101
 102 /* configuration settings for the WMI service */
 103 typedef struct _HTC_CONFIG {
 104         int         CreditSize;    /*  */
 105         int         CreditNumber;
 106         adf_os_handle_t   OSHandle;
 107         hif_handle_t      HIFHandle;
 108         pool_handle_t     PoolHandle;
 109 } HTC_CONFIG;
 110
 111 typedef struct _HTC_BUF_CONTEXT {
 112         A_UINT8         end_point;
 113         A_UINT8         htc_flags;      /* htc flags (used by HTC layer only) */
 114 } HTC_BUF_CONTEXT;
 115
 116 typedef void* htc_handle_t;
 117
 118 /*
 119  * setup complete function, supplied by HTC caller at HTC_init time.
 120  * HTC calls this function after the host has indicated that the service connection
 121  * phase is complete.
 122  *
 123  */
 124 typedef void (* HTC_SETUP_COMPLETE_CB)(void);
 125
 126 struct htc_apis {
 127         htc_handle_t (* _HTC_Init)(HTC_SETUP_COMPLETE_CB, HTC_CONFIG *pConfig);
 128         void (* _HTC_Shutdown)(htc_handle_t);
 129         void (* _HTC_RegisterService)(htc_handle_t, HTC_SERVICE *);
 130         void (* _HTC_Ready)(htc_handle_t);
 131         void (* _HTC_ReturnBuffers)(htc_handle_t handle, HTC_ENDPOINT_ID EndpointID, adf_nbuf_t);
 132         void (* _HTC_ReturnBuffersList)(htc_handle_t handle, HTC_ENDPOINT_ID EndpointID, adf_nbuf_queue_t);
 133         void (* _HTC_SendMsg)(htc_handle_t handle, HTC_ENDPOINT_ID EndpointID, adf_nbuf_t);
 134         int  (* _HTC_GetReservedHeadroom)(htc_handle_t handle);
 135
 136         /* These APIs below are for patch purpose only */
 137         void (*_HTC_MsgRecvHandler)(adf_nbuf_t hdr_buf, adf_nbuf_t buf, void *context);
 138         void (*_HTC_SendDoneHandler)(adf_nbuf_t buf, void *context);
 139         void (*_HTC_ControlSvcProcessMsg)(HTC_ENDPOINT_ID EndpointID, adf_nbuf_t hdr_buf, adf_nbuf_t buf, void *arg);
 140         void (*_HTC_ControlSvcProcessSendComplete)(HTC_ENDPOINT_ID EndpointID, adf_nbuf_t pBuffers, void *arg);
 141
 142         void *pReserved;  /* for expansion if need be */
 143 };
 144
 145 extern void htc_module_install(struct htc_apis *pAPIs);
 146
 147 #endif /* _HTC_API_H__ */