|
1 /* Cypress West Bridge API header file (cyaslowlevel.h) |
|
2 ## =========================== |
|
3 ## |
|
4 ## Copyright Cypress Semiconductor Corporation, 2006-2009, |
|
5 ## All Rights Reserved |
|
6 ## UNPUBLISHED, LICENSED SOFTWARE. |
|
7 ## |
|
8 ## CONFIDENTIAL AND PROPRIETARY INFORMATION |
|
9 ## WHICH IS THE PROPERTY OF CYPRESS. |
|
10 ## |
|
11 ## Use of this file is governed |
|
12 ## by the license agreement included in the file |
|
13 ## |
|
14 ## <install>/license/license.txt |
|
15 ## |
|
16 ## where <install> is the Cypress software |
|
17 ## installation root directory path. |
|
18 ## |
|
19 ## =========================== |
|
20 */ |
|
21 |
|
22 #ifndef _INCLUDED_CYASLOWLEVEL_H_ |
|
23 #define _INCLUDED_CYASLOWLEVEL_H_ |
|
24 |
|
25 /*@@Low Level Communications |
|
26 |
|
27 Summary |
|
28 The low level communications module is responsible for communications between |
|
29 the West Bridge device and the P port processor. Communications is organized as |
|
30 a series of requests and subsequent responses. For each request there is a |
|
31 one and only one response. Requests may go from the West Bridge device to the P port |
|
32 processor, or from the P Port processor to the West Bridge device. |
|
33 |
|
34 Description |
|
35 Requests are issued across what is called a context. A context is a single |
|
36 channel of communications from one processor to another processor. There can |
|
37 be only a single request outstanding on a context at a given time. Contexts |
|
38 are used to identify subsystems that can only process a single request at a |
|
39 time, but are independent of other contexts in the system. For instance, there |
|
40 is a context for communicating storage commands from the P port processor to the |
|
41 West Bridge device. There is also a context for communicating USB commands from |
|
42 the P port processor to the West Bridge device. |
|
43 |
|
44 Requests and responses are identical with the exception of the type bit in the |
|
45 request/response header. If the type bit is one, the packet is a request. If |
|
46 this bit is zero, the packet is a response. Also encoded within the header of |
|
47 the request/response is the code. The code is a command code for a request, or |
|
48 a response code for a response. For a request, the code is a function of the |
|
49 context. The code 0 has one meaning for the storage context and a different |
|
50 meaning for the USB context. The code is treated differently in the response. |
|
51 If the code in the response is less than 16, then the meaning of the response is |
|
52 global across all contexts. If the response is greater than or equal to 16, |
|
53 then the response is specific to the associated context. |
|
54 |
|
55 Requests and responses are transferred between processors through the mailbox |
|
56 registers. It may take one or more cycles to transmit a complete request or |
|
57 response. The context is encoded into each cycle of the transfer to insure the |
|
58 receiving processor can route the data to the appropriate context for processing. |
|
59 In this way, the traffic from multiple contexts can be multiplexed into a single |
|
60 data stream through the mailbox registers by the sending processor, and |
|
61 demultiplexed from the mailbox registers by the receiving processor. |
|
62 |
|
63 * Firmware Assumptions * |
|
64 The firmware assumes that mailbox contents will be consumed immediately. Therefore |
|
65 for multi-cycle packets, the data is sent in a tight polling loop from the firmware. |
|
66 This implies that the data must be read from the mailbox register on the P port side |
|
67 and processed immediately or performance of the firmware will suffer. In order to |
|
68 insure this is the case, the data from the mailboxes is read and stored immediately |
|
69 in a per context buffer. This occurs until the entire packet is received at which |
|
70 time the request packet is processed. Since the protocol is designed to allow for |
|
71 only one outstanding packet at a time, the firmware can never be in a position of |
|
72 waiting on the mailbox registers while the P port is processing a request. Only after |
|
73 the response to the previous request is sent will another request be sent. |
|
74 */ |
|
75 |
|
76 #include "cyashal.h" |
|
77 #include "cyasdevice.h" |
|
78 |
|
79 #include "cyas_cplus_start.h" |
|
80 |
|
81 /* |
|
82 * Constants |
|
83 */ |
|
84 #define CY_AS_REQUEST_RESPONSE_CODE_MASK (0x00ff) |
|
85 #define CY_AS_REQUEST_RESPONSE_CONTEXT_MASK (0x0F00) |
|
86 #define CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT (8) |
|
87 #define CY_AS_REQUEST_RESPONSE_TYPE_MASK (0x4000) |
|
88 #define CY_AS_REQUEST_RESPONSE_LAST_MASK (0x8000) |
|
89 #define CY_AS_REQUEST_RESPONSE_CLEAR_STR_FLAG (0x1000) |
|
90 |
|
91 /* |
|
92 * These macros extract the data from a 16 bit value |
|
93 */ |
|
94 #define CyAsMboxGetCode(c) ((uint8_t)((c) & CY_AS_REQUEST_RESPONSE_CODE_MASK)) |
|
95 #define CyAsMboxGetContext(c) ((uint8_t)(((c) & CY_AS_REQUEST_RESPONSE_CONTEXT_MASK) >> CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT)) |
|
96 #define CyAsMboxIsLast(c) ((c) & CY_AS_REQUEST_RESPONSE_LAST_MASK) |
|
97 #define CyAsMboxIsRequest(c) (((c) & CY_AS_REQUEST_RESPONSE_TYPE_MASK) != 0) |
|
98 #define CyAsMboxIsResponse(c) (((c) & CY_AS_REQUEST_RESPONSE_TYPE_MASK) == 0) |
|
99 |
|
100 /* |
|
101 * These macros (not yet written) pack data into or extract data |
|
102 * from the m_box0 field of the request or response |
|
103 */ |
|
104 #define CyAsLLRequestResponse_SetCode(req, code) \ |
|
105 ((req)->box0 = ((req)->box0 & ~CY_AS_REQUEST_RESPONSE_CODE_MASK) | \ |
|
106 (code & CY_AS_REQUEST_RESPONSE_CODE_MASK)) |
|
107 |
|
108 #define CyAsLLRequestResponse_GetCode(req) CyAsMboxGetCode((req)->box0) |
|
109 |
|
110 #define CyAsLLRequestResponse_SetContext(req, context) \ |
|
111 ((req)->box0 |= ((context) << CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT)) |
|
112 |
|
113 #define CyAsLLRequestResponse_SetClearStorageFlag(req) \ |
|
114 ((req)->box0 |= CY_AS_REQUEST_RESPONSE_CLEAR_STR_FLAG) |
|
115 |
|
116 #define CyAsLLRequestResponse_GetContext(req) CyAsMboxGetContext((req)->box0) |
|
117 |
|
118 #define CyAsLLRequestResponse_IsLast(req) CyAsMboxIsLast((req)->box0) |
|
119 |
|
120 #define CYAnLLRequestResponse__SetLast(req) \ |
|
121 ((req)->box0 |= CY_AS_REQUEST_RESPONSE_LAST_MASK) |
|
122 |
|
123 #define CyAsLLRequestResponse_IsRequest(req) CyAsMboxIsRequest((req)->box0) |
|
124 |
|
125 #define CyAsLLRequestResponse_SetRequest(req) \ |
|
126 ((req)->box0 |= CY_AS_REQUEST_RESPONSE_TYPE_MASK) |
|
127 |
|
128 #define CyAsLLRequestResponse_SetResponse(req) \ |
|
129 ((req)->box0 &= ~CY_AS_REQUEST_RESPONSE_TYPE_MASK) |
|
130 |
|
131 #define CyAsLLRequestResponse_IsResponse(req) CyAsMboxIsResponse((req)->box0) |
|
132 |
|
133 #define CyAsLLRequestResponse_GetWord(req, offset) ((req)->data[(offset)]) |
|
134 |
|
135 #define CyAsLLRequestResponse_SetWord(req, offset, value) ((req)->data[(offset)] = value) |
|
136 |
|
137 typedef enum CyAsRemoveRequestResult_t |
|
138 { |
|
139 CyAsRemoveRequestSucessful, |
|
140 CyAsRemoveRequestInTransit, |
|
141 CyAsRemoveRequestNotFound |
|
142 } CyAsRemoveRequestResult_t ; |
|
143 |
|
144 /* Summary |
|
145 Start the low level communications module |
|
146 |
|
147 Description |
|
148 */ |
|
149 CyAsReturnStatus_t |
|
150 CyAsLLStart( |
|
151 CyAsDevice *dev_p |
|
152 ) ; |
|
153 |
|
154 CyAsReturnStatus_t |
|
155 CyAsLLStop( |
|
156 CyAsDevice *dev_p |
|
157 ) ; |
|
158 |
|
159 |
|
160 CyAsLLRequestResponse * |
|
161 CyAsLLCreateRequest( |
|
162 CyAsDevice *dev_p, |
|
163 uint16_t code, |
|
164 uint8_t context, |
|
165 uint16_t length /* Length of the request in 16 bit words */ |
|
166 ) ; |
|
167 |
|
168 void |
|
169 CyAsLLInitRequest( |
|
170 CyAsLLRequestResponse *req_p, |
|
171 uint16_t code, |
|
172 uint16_t context, |
|
173 uint16_t length) ; |
|
174 |
|
175 void |
|
176 CyAsLLInitResponse( |
|
177 CyAsLLRequestResponse *req_p, |
|
178 uint16_t length) ; |
|
179 |
|
180 void |
|
181 CyAsLLDestroyRequest( |
|
182 CyAsDevice *dev_p, |
|
183 CyAsLLRequestResponse *) ; |
|
184 |
|
185 CyAsLLRequestResponse * |
|
186 CyAsLLCreateResponse( |
|
187 CyAsDevice *dev_p, |
|
188 uint16_t length /* Length of the request in 16 bit words */ |
|
189 ) ; |
|
190 |
|
191 CyAsRemoveRequestResult_t |
|
192 CyAsLLRemoveRequest( |
|
193 CyAsDevice *dev_p, |
|
194 CyAsContext *ctxt_p, |
|
195 CyAsLLRequestResponse *req_p, |
|
196 CyBool force |
|
197 ) ; |
|
198 void |
|
199 CyAsLLRemoveAllRequests(CyAsDevice *dev_p, |
|
200 CyAsContext *ctxt_p) ; |
|
201 |
|
202 void |
|
203 CyAsLLDestroyResponse( |
|
204 CyAsDevice *dev_p, |
|
205 CyAsLLRequestResponse *) ; |
|
206 |
|
207 CyAsReturnStatus_t |
|
208 CyAsLLSendRequest( |
|
209 CyAsDevice * dev_p, /* The West Bridge device */ |
|
210 CyAsLLRequestResponse * req, /* The request to send */ |
|
211 CyAsLLRequestResponse * resp, /* Storage for a reply, must be sure it is of sufficient size */ |
|
212 CyBool sync, /* If true, this is a sync request */ |
|
213 CyAsResponseCallback cb /* Callback to call when reply is received */ |
|
214 ) ; |
|
215 |
|
216 CyAsReturnStatus_t |
|
217 CyAsLLSendRequestWaitReply( |
|
218 CyAsDevice * dev_p, /* The West Bridge device */ |
|
219 CyAsLLRequestResponse * req, /* The request to send */ |
|
220 CyAsLLRequestResponse * resp /* Storage for a reply, must be sure it is of sufficient size */ |
|
221 ) ; |
|
222 |
|
223 /* Summary |
|
224 This function registers a callback function to be called when a request arrives on a given |
|
225 context. |
|
226 |
|
227 Description |
|
228 |
|
229 Returns |
|
230 * CY_AS_ERROR_SUCCESS |
|
231 */ |
|
232 extern CyAsReturnStatus_t |
|
233 CyAsLLRegisterRequestCallback( |
|
234 CyAsDevice *dev_p, |
|
235 uint8_t context, |
|
236 CyAsResponseCallback cb |
|
237 ) ; |
|
238 |
|
239 /* Summary |
|
240 This function packs a set of bytes given by the data_p pointer into a request, reply |
|
241 structure. |
|
242 */ |
|
243 extern void |
|
244 CyAsLLRequestResponse_Pack( |
|
245 CyAsLLRequestResponse *req, /* The destintation request or response */ |
|
246 uint32_t offset, /* The offset of where to pack the data */ |
|
247 uint32_t length, /* The length of the data to pack in bytes */ |
|
248 void *data_p /* The data to pack */ |
|
249 ) ; |
|
250 |
|
251 /* Summary |
|
252 This function unpacks a set of bytes from a request/reply structure into a segment of memory given |
|
253 by the data_p pointer. |
|
254 */ |
|
255 extern void |
|
256 CyAsLLRequestResponse_Unpack( |
|
257 CyAsLLRequestResponse *req, /* The source of the data to unpack */ |
|
258 uint32_t offset, /* The offset of the data to unpack */ |
|
259 uint32_t length, /* The length of the data to unpack in bytes */ |
|
260 void *data_p /* The destination of the unpack operation */ |
|
261 ) ; |
|
262 |
|
263 /* Summary |
|
264 This function sends a status response back to the West Bridge device in response to a |
|
265 previously send request |
|
266 */ |
|
267 extern CyAsReturnStatus_t |
|
268 CyAsLLSendStatusResponse( |
|
269 CyAsDevice *dev_p, /* The West Bridge device */ |
|
270 uint8_t context, /* The context to send the response on */ |
|
271 uint16_t code, /* The success/failure code to send */ |
|
272 uint8_t clear_storage) ; /* Flag to clear wait on storage context */ |
|
273 |
|
274 /* Summary |
|
275 This function sends a response back to the West Bridge device. |
|
276 |
|
277 Description |
|
278 This function sends a response back to the West Bridge device. The response is sent on the |
|
279 context given by the 'context' variable. The code for the response is given by the 'code' |
|
280 argument. The data for the response is given by the data and length arguments. |
|
281 */ |
|
282 extern CyAsReturnStatus_t |
|
283 CyAsLLSendDataResponse( |
|
284 CyAsDevice *dev_p, /* The West Bridge device */ |
|
285 uint8_t context, /* The context to send the response on */ |
|
286 uint16_t code, /* The response code to use */ |
|
287 uint16_t length, /* The length of the data for the response */ |
|
288 void *data /* The data for the response */ |
|
289 ) ; |
|
290 |
|
291 /* Summary |
|
292 This function removes any requests of the given type from the given context. |
|
293 |
|
294 Description |
|
295 This function removes requests of a given type from the context given via the |
|
296 context number. |
|
297 */ |
|
298 extern CyAsReturnStatus_t |
|
299 CyAsLLRemoveEpDataRequests( |
|
300 CyAsDevice *dev_p, /* The West Bridge device */ |
|
301 CyAsEndPointNumber_t ep |
|
302 ) ; |
|
303 |
|
304 #include "cyas_cplus_end.h" |
|
305 |
|
306 #endif /* _INCLUDED_CYASLOWLEVEL_H_ */ |