1 //------------------------------------------------------------------------------
2 // <copyright file="htc.h" company="Atheros">
3 // Copyright (c) 2004-2010 Atheros Corporation. All rights reserved.
6 // Permission to use, copy, modify, and/or distribute this software for any
7 // purpose with or without fee is hereby granted, provided that the above
8 // copyright notice and this permission notice appear in all copies.
10 // THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 // WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 // MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 // ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 // WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 // ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 // OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 //------------------------------------------------------------------------------
20 //==============================================================================
21 // Author(s): ="Atheros"
22 //==============================================================================
28 #include "athstartpack.h"
31 #define A_OFFSETOF(type,field) (unsigned long)(&(((type *)NULL)->field))
33 #define ASSEMBLE_UNALIGNED_UINT16(p,highbyte,lowbyte) \
34 (((A_UINT16)(((A_UINT8 *)(p))[(highbyte)])) << 8 | (A_UINT16)(((A_UINT8 *)(p))[(lowbyte)]))
36 /* alignment independent macros (little-endian) to fetch UINT16s or UINT8s from a
37 * structure using only the type and field name.
38 * Use these macros if there is the potential for unaligned buffer accesses. */
39 #define A_GET_UINT16_FIELD(p,type,field) \
40 ASSEMBLE_UNALIGNED_UINT16(p,\
41 A_OFFSETOF(type,field) + 1, \
42 A_OFFSETOF(type,field))
44 #define A_SET_UINT16_FIELD(p,type,field,value) \
46 ((A_UINT8 *)(p))[A_OFFSETOF(type,field)] = (A_UINT8)(value); \
47 ((A_UINT8 *)(p))[A_OFFSETOF(type,field) + 1] = (A_UINT8)((value) >> 8); \
50 #define A_GET_UINT8_FIELD(p,type,field) \
51 ((A_UINT8 *)(p))[A_OFFSETOF(type,field)]
53 #define A_SET_UINT8_FIELD(p,type,field,value) \
54 ((A_UINT8 *)(p))[A_OFFSETOF(type,field)] = (value)
56 /****** DANGER DANGER ***************
58 * The frame header length and message formats defined herein were
59 * selected to accommodate optimal alignment for target processing. This reduces code
60 * size and improves performance.
62 * Any changes to the header length may alter the alignment and cause exceptions
63 * on the target. When adding to the message structures insure that fields are
68 /* HTC frame header */
69 typedef PREPACK struct _HTC_FRAME_HDR{
70 /* do not remove or re-arrange these fields, these are minimally required
71 * to take advantage of 4-byte lookaheads in some hardware implementations */
74 A_UINT16 PayloadLen; /* length of data (including trailer) that follows the header */
76 /***** end of 4-byte lookahead ****/
78 A_UINT8 ControlBytes[2];
80 /* message payload starts after the header */
82 } POSTPACK HTC_FRAME_HDR;
84 /* frame header flags */
87 #define HTC_FLAGS_NEED_CREDIT_UPDATE (1 << 0)
88 #define HTC_FLAGS_SEND_BUNDLE (1 << 1) /* start or part of bundle */
89 /* receive direction */
90 #define HTC_FLAGS_RECV_UNUSED_0 (1 << 0) /* bit 0 unused */
91 #define HTC_FLAGS_RECV_TRAILER (1 << 1) /* bit 1 trailer data present */
92 #define HTC_FLAGS_RECV_UNUSED_2 (1 << 0) /* bit 2 unused */
93 #define HTC_FLAGS_RECV_UNUSED_3 (1 << 0) /* bit 3 unused */
94 #define HTC_FLAGS_RECV_BUNDLE_CNT_MASK (0xF0) /* bits 7..4 */
95 #define HTC_FLAGS_RECV_BUNDLE_CNT_SHIFT 4
97 #define HTC_HDR_LENGTH (sizeof(HTC_FRAME_HDR))
98 #define HTC_MAX_TRAILER_LENGTH 255
99 #define HTC_MAX_PAYLOAD_LENGTH (4096 - sizeof(HTC_FRAME_HDR))
101 /* HTC control message IDs */
103 #define HTC_MSG_READY_ID 1
104 #define HTC_MSG_CONNECT_SERVICE_ID 2
105 #define HTC_MSG_CONNECT_SERVICE_RESPONSE_ID 3
106 #define HTC_MSG_SETUP_COMPLETE_ID 4
107 #define HTC_MSG_SETUP_COMPLETE_EX_ID 5
109 #define HTC_MAX_CONTROL_MESSAGE_LENGTH 256
111 /* base message ID header */
112 typedef PREPACK struct {
114 } POSTPACK HTC_UNKNOWN_MSG;
117 * direction : target-to-host */
118 typedef PREPACK struct {
119 A_UINT16 MessageID; /* ID */
120 A_UINT16 CreditCount; /* number of credits the target can offer */
121 A_UINT16 CreditSize; /* size of each credit */
122 A_UINT8 MaxEndpoints; /* maximum number of endpoints the target has resources for */
124 } POSTPACK HTC_READY_MSG;
126 /* extended HTC ready message */
127 typedef PREPACK struct {
128 HTC_READY_MSG Version2_0_Info; /* legacy version 2.0 information at the front... */
129 /* extended information */
131 A_UINT8 MaxMsgsPerHTCBundle;
132 } POSTPACK HTC_READY_EX_MSG;
134 #define HTC_VERSION_2P0 0x00
135 #define HTC_VERSION_2P1 0x01 /* HTC 2.1 */
137 #define HTC_SERVICE_META_DATA_MAX_LENGTH 128
140 * direction : host-to-target */
141 typedef PREPACK struct {
143 A_UINT16 ServiceID; /* service ID of the service to connect to */
144 A_UINT16 ConnectionFlags; /* connection flags */
146 #define HTC_CONNECT_FLAGS_REDUCE_CREDIT_DRIBBLE (1 << 2) /* reduce credit dribbling when
147 the host needs credits */
148 #define HTC_CONNECT_FLAGS_THRESHOLD_LEVEL_MASK (0x3)
149 #define HTC_CONNECT_FLAGS_THRESHOLD_LEVEL_ONE_FOURTH 0x0
150 #define HTC_CONNECT_FLAGS_THRESHOLD_LEVEL_ONE_HALF 0x1
151 #define HTC_CONNECT_FLAGS_THRESHOLD_LEVEL_THREE_FOURTHS 0x2
152 #define HTC_CONNECT_FLAGS_THRESHOLD_LEVEL_UNITY 0x3
154 A_UINT8 ServiceMetaLength; /* length of meta data that follows */
157 /* service-specific meta data starts after the header */
159 } POSTPACK HTC_CONNECT_SERVICE_MSG;
162 * direction : target-to-host */
163 typedef PREPACK struct {
165 A_UINT16 ServiceID; /* service ID that the connection request was made */
166 A_UINT8 Status; /* service connection status */
167 A_UINT8 EndpointID; /* assigned endpoint ID */
168 A_UINT16 MaxMsgSize; /* maximum expected message size on this endpoint */
169 A_UINT8 ServiceMetaLength; /* length of meta data that follows */
172 /* service-specific meta data starts after the header */
174 } POSTPACK HTC_CONNECT_SERVICE_RESPONSE_MSG;
176 typedef PREPACK struct {
178 /* currently, no other fields */
179 } POSTPACK HTC_SETUP_COMPLETE_MSG;
181 /* extended setup completion message */
182 typedef PREPACK struct {
185 A_UINT8 MaxMsgsPerBundledRecv;
187 } POSTPACK HTC_SETUP_COMPLETE_EX_MSG;
189 #define HTC_SETUP_COMPLETE_FLAGS_ENABLE_BUNDLE_RECV (1 << 0)
191 /* connect response status codes */
192 #define HTC_SERVICE_SUCCESS 0 /* success */
193 #define HTC_SERVICE_NOT_FOUND 1 /* service could not be found */
194 #define HTC_SERVICE_FAILED 2 /* specific service failed the connect */
195 #define HTC_SERVICE_NO_RESOURCES 3 /* no resources (i.e. no more endpoints) */
196 #define HTC_SERVICE_NO_MORE_EP 4 /* specific service is not allowing any more
199 /* report record IDs */
201 #define HTC_RECORD_NULL 0
202 #define HTC_RECORD_CREDITS 1
203 #define HTC_RECORD_LOOKAHEAD 2
204 #define HTC_RECORD_LOOKAHEAD_BUNDLE 3
206 typedef PREPACK struct {
207 A_UINT8 RecordID; /* Record ID */
208 A_UINT8 Length; /* Length of record */
209 } POSTPACK HTC_RECORD_HDR;
211 typedef PREPACK struct {
212 A_UINT8 EndpointID; /* Endpoint that owns these credits */
213 A_UINT8 Credits; /* credits to report since last report */
214 } POSTPACK HTC_CREDIT_REPORT;
216 typedef PREPACK struct {
217 A_UINT8 PreValid; /* pre valid guard */
218 A_UINT8 LookAhead[4]; /* 4 byte lookahead */
219 A_UINT8 PostValid; /* post valid guard */
221 /* NOTE: the LookAhead array is guarded by a PreValid and Post Valid guard bytes.
222 * The PreValid bytes must equal the inverse of the PostValid byte */
224 } POSTPACK HTC_LOOKAHEAD_REPORT;
226 typedef PREPACK struct {
227 A_UINT8 LookAhead[4]; /* 4 byte lookahead */
228 } POSTPACK HTC_BUNDLED_LOOKAHEAD_REPORT;
231 #include "athendpack.h"
235 #endif /* __HTC_H__ */