xref: /wlan-driver/fw-api/fw/wmi_tlv_helper.h (revision 5113495b16420b49004c444715d2daae2066e7dc)
1 /*
2  * Copyright (c) 2012-2017 The Linux Foundation. All rights reserved.
3  *
4  * Previously licensed under the ISC license by Qualcomm Atheros, Inc.
5  *
6  *
7  * Permission to use, copy, modify, and/or distribute this software for
8  * any purpose with or without fee is hereby granted, provided that the
9  * above copyright notice and this permission notice appear in all
10  * copies.
11  *
12  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
13  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
14  * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
15  * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
16  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
17  * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
18  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
19  * PERFORMANCE OF THIS SOFTWARE.
20  */
21 
22 /*
23  * This file was originally distributed by Qualcomm Atheros, Inc.
24  * under proprietary terms before Copyright ownership was assigned
25  * to the Linux Foundation.
26  */
27 #ifndef _WMI_TLV_HELPER_H_
28 #define _WMI_TLV_HELPER_H_
29 
30 /*
31  * Every command or event parameter structure will need a TLV definition.
32  * The macro WMITLV_TABLE is used to help build this TLV definition. Inside this macro define, the
33  * individual TLV's are specified. The parameters for WMITLV_ELEM are:
34  * (1) the list of parameters that are passed unchanged from the WMITLV_TABLE. Currently, they are id,op,buf,len
35  * (2) The TLV Tag. You should create a new tag for each cmd/event in WMITLV_TAG_ID. The name of the
36  *     tag is <WMI_TLVTAG_STRUC_><CMD or Event ID name>. There are special tags,
37  *     e.g. WMI_TLVTAG_ARRAY_UINT32 and WMI_TLVTAG_ARRAY_STRUC. WMI_TLVTAG_ARRAY_UINT32 is for a
38  *     variable size array of UINT32 elements. WMI_TLVTAG_ARRAY_STRUC is for a varialbe size array
39  *     of structures.
40  * (3) type of the TLV. For WMI_TLVTAG_ARRAY_* tag, then it is the type of each element.
41  * (4) Name of this TLV. It must be unique in this TLV TABLE.
42  * (5) Either WMITLV_SIZE_FIX or WMITLV_SIZE_VAR to indicate if this TLV is variable size.
43  *
44  * Note: It is important that the last TLV_ELEM does not have the "\" character.
45 */
46 
47 /* Size of the TLV Header which is the Tag and Length fields */
48 #define WMI_TLV_HDR_SIZE   (1 * sizeof(A_UINT32))
49 
50 /** TLV Helper macro to get the TLV Header given the pointer
51  *  to the TLV buffer. */
52 #define WMITLV_GET_HDR(tlv_buf)        (((A_UINT32 *)(tlv_buf))[0])
53 
54 /** TLV Helper macro to set the TLV Header given the pointer
55  *  to the TLV buffer. */
56 #define WMITLV_SET_HDR(tlv_buf, tag, len) (((A_UINT32 *)(tlv_buf))[0]) = ((tag << 16) | (len & 0x0000FFFF))
57 
58 /** TLV Helper macro to get the TLV Tag given the TLV header. */
59 #define WMITLV_GET_TLVTAG(tlv_header)  ((A_UINT32)((tlv_header)>>16))
60 
61 /** TLV Helper macro to get the TLV Buffer Length (minus TLV
62  *  header size) given the TLV header. */
63 #define WMITLV_GET_TLVLEN(tlv_header)  ((A_UINT32)((tlv_header) & 0x0000FFFF))
64 
65 /** TLV Helper macro to get the TLV length from TLV structure size by removing TLV header size */
66 #define WMITLV_GET_STRUCT_TLVLEN(tlv_struct)    ((A_UINT32)(sizeof(tlv_struct)-WMI_TLV_HDR_SIZE))
67 
68 /* Indicates whether the TLV is fixed size or variable length */
69 #define WMITLV_SIZE_FIX     0
70 #define WMITLV_SIZE_VAR     1
71 
72 typedef struct {
73 	A_UINT32 tag_order;
74 	A_UINT32 tag_id;
75 	A_UINT32 tag_struct_size;
76 	A_UINT32 tag_varied_size;
77 	A_UINT32 tag_array_size;
78     A_UINT32 cmd_num_tlv;
79 } wmitlv_attributes_struc;
80 
81 
82 /* Template structure definition for a variable size array of UINT32 */
83 typedef struct {
84     A_UINT32    tlv_header;     /* TLV tag and len; tag equals WMI_TLVTAG_ARRAY_UINT32 */
85     A_UINT32    uint32_array[1]; /* variable length Array of UINT32 */
86 } wmitlv_array_uint32;
87 
88 /* Template structure definition for a variable size array of unknown structure */
89 typedef struct {
90     A_UINT32    tlv_header;     /* TLV tag and len; tag equals WMI_TLVTAG_ARRAY_STRUC */
91     A_UINT32    struc_array[1]; /* variable length Array of structures */
92 } wmitlv_array_struc;
93 
94 /*
95  * Used to fill in the "arr_size" parameter when it is not specified and hence, invalid. Can be used to
96  * indicate if the original TLV definition specify this fixed array size.
97  */
98 #define WMITLV_ARR_SIZE_INVALID  0x1FE
99 
100 #define WMITLV_GET_TAG_NUM_TLV_ATTRIB(wmi_cmd_event_id)      \
101        WMI_TLV_HLPR_NUM_TLVS_FOR_##wmi_cmd_event_id
102 
103 
104 void
105 wmitlv_set_static_param_tlv_buf(void *param_tlv_buf, A_UINT32 max_tlvs_accomodated);
106 
107 void
108 wmitlv_set_static_param_tlv_buf_ext(void *param_tlv_buf, A_UINT32 max_tlvs_accomodated, A_UINT32 indx);
109 
110 void
111 wmitlv_free_allocated_command_tlvs(
112     A_UINT32 cmd_id,
113     void **wmi_cmd_struct_ptr);
114 
115 void
116 wmitlv_free_allocated_event_tlvs(
117     A_UINT32 event_id,
118     void **wmi_cmd_struct_ptr);
119 
120 int
121 wmitlv_check_command_tlv_params(
122     void *os_ctx, void *param_struc_ptr, A_UINT32 param_buf_len, A_UINT32 wmi_cmd_event_id);
123 
124 int
125 wmitlv_check_event_tlv_params(
126     void *os_ctx, void *param_struc_ptr, A_UINT32 param_buf_len, A_UINT32 wmi_cmd_event_id);
127 
128 int
129 wmitlv_check_and_pad_command_tlvs(
130     void *os_ctx, void *param_struc_ptr, A_UINT32 param_buf_len, A_UINT32 wmi_cmd_event_id, void **wmi_cmd_struct_ptr);
131 
132 int
133 wmitlv_check_and_pad_event_tlvs(
134     void *os_ctx, void *param_struc_ptr, A_UINT32 param_buf_len, A_UINT32 wmi_cmd_event_id, void **wmi_cmd_struct_ptr);
135 
136 /** This structure is the element for the Version WhiteList
137  *  table. */
138 typedef struct {
139     A_UINT32      major;
140     A_UINT32      minor;
141     A_UINT32      namespace_0;
142     A_UINT32      namespace_1;
143     A_UINT32      namespace_2;
144     A_UINT32      namespace_3;
145 } wmi_whitelist_version_info;
146 
147 struct _wmi_abi_version;   /* Forward declaration to make the ARM compiler happy */
148 
149 int
150 wmi_cmp_and_set_abi_version(int num_whitelist, wmi_whitelist_version_info *version_whitelist_table,
151                             struct _wmi_abi_version *my_vers,
152                             struct _wmi_abi_version *opp_vers,
153                             struct _wmi_abi_version *out_vers);
154 
155 int
156 wmi_versions_are_compatible(struct _wmi_abi_version *vers1, struct _wmi_abi_version *vers2);
157 
158 #endif /*_WMI_TLV_HELPER_H_*/
159 
160