1 /* Cypress West Bridge API header file (cyaslowlevel.h)
2 ## ===========================
3 ## Copyright (C) 2010 Cypress Semiconductor
5 ## This program is free software; you can redistribute it and/or
6 ## modify it under the terms of the GNU General Public License
7 ## as published by the Free Software Foundation; either version 2
8 ## of the License, or (at your option) any later version.
10 ## This program is distributed in the hope that it will be useful,
11 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 ## GNU General Public License for more details.
15 ## You should have received a copy of the GNU General Public License
16 ## along with this program; if not, write to the Free Software
17 ## Foundation, Inc., 51 Franklin Street
18 ## Fifth Floor, Boston, MA 02110-1301, USA.
19 ## ===========================
22 #ifndef _INCLUDED_CYASLOWLEVEL_H_
23 #define _INCLUDED_CYASLOWLEVEL_H_
25 /*@@Low Level Communications
28 The low level communications module is responsible for
29 communications between the West Bridge device and the P
30 port processor. Communications is organized as a series
31 of requests and subsequent responses. For each request
32 there is a one and only one response. Requests may go
33 from the West Bridge device to the P port processor, or
34 from the P Port processor to the West Bridge device.
37 Requests are issued across what is called a context. A
38 context is a single channel of communications from one
39 processor to another processor. There can be only a single
40 request outstanding on a context at a given time. Contexts
41 are used to identify subsystems that can only process a
42 single request at a time, but are independent of other
43 contexts in the system. For instance, there is a context
44 for communicating storage commands from the P port processor
45 to the West Bridge device. There is also a context for
46 communicating USB commands from the P port processor to the
49 Requests and responses are identical with the exception of
50 the type bit in the request/response header. If the type
51 bit is one, the packet is a request. If this bit is zero,
52 the packet is a response. Also encoded within the header of
53 the request/response is the code. The code is a command
54 code for a request, or a response code for a response. For
55 a request, the code is a function of the context. The code
56 0 has one meaning for the storage context and a different
57 meaning for the USB context. The code is treated differently
58 in the response. If the code in the response is less than 16,
59 then the meaning of the response is global across all
60 contexts. If the response is greater than or equal to 16,
61 then the response is specific to the associated context.
63 Requests and responses are transferred between processors
64 through the mailbox registers. It may take one or more cycles
65 to transmit a complete request or response. The context is
66 encoded into each cycle of the transfer to insure the
67 receiving processor can route the data to the appropriate
68 context for processing. In this way, the traffic from multiple
69 contexts can be multiplexed into a single data stream through
70 the mailbox registers by the sending processor, and
71 demultiplexed from the mailbox registers by the receiving
74 * Firmware Assumptions *
75 The firmware assumes that mailbox contents will be consumed
76 immediately. Therefore for multi-cycle packets, the data is
77 sent in a tight polling loop from the firmware. This implies
78 that the data must be read from the mailbox register on the P
79 port side and processed immediately or performance of the
80 firmware will suffer. In order to insure this is the case,
81 the data from the mailboxes is read and stored immediately
82 in a per context buffer. This occurs until the entire packet
83 is received at which time the request packet is processed.
84 Since the protocol is designed to allow for only one
85 outstanding packet at a time, the firmware can never be in a
86 position of waiting on the mailbox registers while the P port
87 is processing a request. Only after the response to the
88 previous request is sent will another request be sent.
92 #include "cyasdevice.h"
94 #include "cyas_cplus_start.h"
99 #define CY_AS_REQUEST_RESPONSE_CODE_MASK (0x00ff)
100 #define CY_AS_REQUEST_RESPONSE_CONTEXT_MASK (0x0F00)
101 #define CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT (8)
102 #define CY_AS_REQUEST_RESPONSE_TYPE_MASK (0x4000)
103 #define CY_AS_REQUEST_RESPONSE_LAST_MASK (0x8000)
104 #define CY_AS_REQUEST_RESPONSE_CLEAR_STR_FLAG (0x1000)
107 * These macros extract the data from a 16 bit value
109 #define cy_as_mbox_get_code(c) \
110 ((uint8_t)((c) & CY_AS_REQUEST_RESPONSE_CODE_MASK))
111 #define cy_as_mbox_get_context(c) \
112 ((uint8_t)(((c) & CY_AS_REQUEST_RESPONSE_CONTEXT_MASK) \
113 >> CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT))
114 #define cy_as_mbox_is_last(c) \
115 ((c) & CY_AS_REQUEST_RESPONSE_LAST_MASK)
116 #define cy_as_mbox_is_request(c) \
117 (((c) & CY_AS_REQUEST_RESPONSE_TYPE_MASK) != 0)
118 #define cy_as_mbox_is_response(c) \
119 (((c) & CY_AS_REQUEST_RESPONSE_TYPE_MASK) == 0)
122 * These macros (not yet written) pack data into or extract data
123 * from the m_box0 field of the request or response
125 #define cy_as_ll_request_response__set_code(req, code) \
127 ((req)->box0 & ~CY_AS_REQUEST_RESPONSE_CODE_MASK) | \
128 (code & CY_AS_REQUEST_RESPONSE_CODE_MASK))
130 #define cy_as_ll_request_response__get_code(req) \
131 cy_as_mbox_get_code((req)->box0)
133 #define cy_as_ll_request_response__set_context(req, context) \
134 ((req)->box0 |= ((context) << \
135 CY_AS_REQUEST_RESPONSE_CONTEXT_SHIFT))
137 #define cy_as_ll_request_response__set_clear_storage_flag(req) \
138 ((req)->box0 |= CY_AS_REQUEST_RESPONSE_CLEAR_STR_FLAG)
140 #define cy_as_ll_request_response__get_context(req) \
141 cy_as_mbox_get_context((req)->box0)
143 #define cy_as_ll_request_response__is_last(req) \
144 cy_as_mbox_is_last((req)->box0)
146 #define CY_an_ll_request_response___set_last(req) \
147 ((req)->box0 |= CY_AS_REQUEST_RESPONSE_LAST_MASK)
149 #define cy_as_ll_request_response__is_request(req) \
150 cy_as_mbox_is_request((req)->box0)
152 #define cy_as_ll_request_response__set_request(req) \
153 ((req)->box0 |= CY_AS_REQUEST_RESPONSE_TYPE_MASK)
155 #define cy_as_ll_request_response__set_response(req) \
156 ((req)->box0 &= ~CY_AS_REQUEST_RESPONSE_TYPE_MASK)
158 #define cy_as_ll_request_response__is_response(req) \
159 cy_as_mbox_is_response((req)->box0)
161 #define cy_as_ll_request_response__get_word(req, offset) \
162 ((req)->data[(offset)])
164 #define cy_as_ll_request_response__set_word(req, offset, \
165 value) ((req)->data[(offset)] = value)
167 typedef enum cy_as_remove_request_result_t {
168 cy_as_remove_request_sucessful,
169 cy_as_remove_request_in_transit,
170 cy_as_remove_request_not_found
171 } cy_as_remove_request_result_t;
174 Start the low level communications module
178 cy_as_return_status_t
183 cy_as_return_status_t
189 cy_as_ll_request_response *
190 cy_as_ll_create_request(
194 /* Length of the request in 16 bit words */
199 cy_as_ll_init_request(
200 cy_as_ll_request_response *req_p,
206 cy_as_ll_init_response(
207 cy_as_ll_request_response *req_p,
211 cy_as_ll_destroy_request(
213 cy_as_ll_request_response *);
215 cy_as_ll_request_response *
216 cy_as_ll_create_response(
218 /* Length of the request in 16 bit words */
222 cy_as_remove_request_result_t
223 cy_as_ll_remove_request(
225 cy_as_context *ctxt_p,
226 cy_as_ll_request_response *req_p,
230 cy_as_ll_remove_all_requests(cy_as_device *dev_p,
231 cy_as_context *ctxt_p);
234 cy_as_ll_destroy_response(
236 cy_as_ll_request_response *);
238 cy_as_return_status_t
239 cy_as_ll_send_request(
240 /* The West Bridge device */
242 /* The request to send */
243 cy_as_ll_request_response *req,
244 /* Storage for a reply, must be sure it is of sufficient size */
245 cy_as_ll_request_response *resp,
246 /* If true, this is a sync request */
248 /* Callback to call when reply is received */
249 cy_as_response_callback cb
252 cy_as_return_status_t
253 cy_as_ll_send_request_wait_reply(
254 /* The West Bridge device */
256 /* The request to send */
257 cy_as_ll_request_response *req,
258 /* Storage for a reply, must be sure it is of sufficient size */
259 cy_as_ll_request_response *resp
263 This function registers a callback function to be called when a
264 request arrives on a given context.
269 * CY_AS_ERROR_SUCCESS
271 extern cy_as_return_status_t
272 cy_as_ll_register_request_callback(
275 cy_as_response_callback cb
279 This function packs a set of bytes given by the data_p pointer
280 into a request, reply structure.
283 cy_as_ll_request_response__pack(
284 /* The destintation request or response */
285 cy_as_ll_request_response *req,
286 /* The offset of where to pack the data */
288 /* The length of the data to pack in bytes */
290 /* The data to pack */
295 This function unpacks a set of bytes from a request/reply
296 structure into a segment of memory given by the data_p pointer.
299 cy_as_ll_request_response__unpack(
300 /* The source of the data to unpack */
301 cy_as_ll_request_response *req,
302 /* The offset of the data to unpack */
304 /* The length of the data to unpack in bytes */
306 /* The destination of the unpack operation */
311 This function sends a status response back to the West Bridge
312 device in response to a previously send request
314 extern cy_as_return_status_t
315 cy_as_ll_send_status_response(
316 /* The West Bridge device */
318 /* The context to send the response on */
320 /* The success/failure code to send */
322 /* Flag to clear wait on storage context */
323 uint8_t clear_storage);
326 This function sends a response back to the West Bridge device.
329 This function sends a response back to the West Bridge device.
330 The response is sent on the context given by the 'context'
331 variable. The code for the response is given by the 'code'
332 argument. The data for the response is given by the data and
335 extern cy_as_return_status_t
336 cy_as_ll_send_data_response(
337 /* The West Bridge device */
339 /* The context to send the response on */
341 /* The response code to use */
343 /* The length of the data for the response */
345 /* The data for the response */
350 This function removes any requests of the given type
351 from the given context.
354 This function removes requests of a given type from the
355 context given via the context number.
357 extern cy_as_return_status_t
358 cy_as_ll_remove_ep_data_requests(
359 /* The West Bridge device */
361 cy_as_end_point_number_t ep
364 #include "cyas_cplus_end.h"
366 #endif /* _INCLUDED_CYASLOWLEVEL_H_ */