xref: /illumos-gate/usr/src/uts/common/sys/1394/adapters/hci1394_q.h (revision 2d6eb4a5e0a47d30189497241345dc5466bb68ab)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright (c) 1999-2000 by Sun Microsystems, Inc.
24  * All rights reserved.
25  */
26 
27 #ifndef _SYS_1394_ADAPTERS_HCI1394_Q_H
28 #define	_SYS_1394_ADAPTERS_HCI1394_Q_H
29 
30 /*
31  * hci1394_q.h
32  *    This code decouples some of the OpenHCI async descriptor logic/structures
33  *    from the async processing.  The goal was to combine as much of the
34  *    duplicate code as possible for the different type of async transfers
35  *    without going too overboard.
36  *
37  *    There are two parts to the Q, the descriptor buffer and the data buffer.
38  *    for the most part, data to be transmitted and data which is received go
39  *    in the data buffers.  The information of where to get the data and put
40  *    the data reside in the descriptor buffers. There are exceptions to this.
41  */
42 
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46 
47 #include <sys/ddi.h>
48 #include <sys/modctl.h>
49 #include <sys/sunddi.h>
50 #include <sys/types.h>
51 #include <sys/note.h>
52 
53 #include <sys/1394/adapters/hci1394_def.h>
54 #include <sys/1394/adapters/hci1394_tlist.h>
55 #include <sys/1394/adapters/hci1394_buf.h>
56 #include <sys/1394/adapters/hci1394_descriptors.h>
57 
58 
59 /*
60  * Part of q_info passed in during q_init(). This tells us if this is an async
61  * transmit or async receive Q. This makes a big difference inside of q. For
62  * the transmit Q we will just setup an empty Q ready for TX calls into us. For
63  * receive Q's we have to make sure we get multiple data buffers and then setup
64  * the buffers so they are ready to receive data (by adding in the IM
65  * descriptors).
66  */
67 typedef enum {
68 	HCI1394_ARQ,
69 	HCI1394_ATQ
70 } hci1394_q_mode_t;
71 
72 /*
73  * Part of q_info passed in during q_init().  These are the callbacks for
74  * starting and waking up the async Q's.  When the first descriptor is placed
75  * on the Q, the async DMA engine is started with an address of where to find
76  * the descriptor on the Q.  That descriptor will be changed to point to the
77  * next descriptor when the next descriptor is added (i.e. a chained dma).
78  * Whenever an additional descriptor is added, wake is called.
79  */
80 typedef void (*hci1394_q_start_t)(void *arg, uint32_t io_addr);
81 typedef void (*hci1394_q_wake_t)(void *arg);
82 
83 /*
84  * Passed in during q_init().  This contains the size of the descriptor Q, the
85  * size of the data Q, what kind of Q it is (AT or AR), the callbacks for start
86  * and wake, and the argument to pass during start and wake.
87  */
88 typedef struct hci1394_q_info_s {
89 	uint_t			qi_desc_size;
90 	uint_t			qi_data_size;
91 	hci1394_q_mode_t	qi_mode;
92 	hci1394_q_start_t	qi_start;
93 	hci1394_q_wake_t	qi_wake;
94 	void			*qi_callback_arg;
95 } hci1394_q_info_t;
96 
97 /*
98  * Per command tracking information for the AT Q's.  This is not used on the AR
99  * side.  This structure has two parts to it, the public data and the private
100  * data.  The public data is shared between async.c and q.c.  The private data
101  * is for internal q.c access only.  It is only put in this structure so that
102  * we do not have to dynamically alloc space for each transfer.
103  */
104 typedef struct hci1394_q_cmd_s {
105 
106 	/* PUBLIC DATA STRUCTURES */
107 	/*
108 	 * qc_arg is an input paramter to hci1394_q_at() (along with the data
109 	 * versions). It is an opaque address pointer which is used by async.c
110 	 * to determine the commands address after a call to
111 	 * hci1394_q_at_next().
112 	 */
113 	void			*qc_arg;
114 
115 	/*
116 	 * qc_generation is an input parameter to hci1394_q_at() (along with the
117 	 * data versions). It is the generation count for which this command is
118 	 * valid. If qc_generation does not match the current bus generation,
119 	 * hci1394_q_at*() will return failure.
120 	 */
121 	uint_t			qc_generation;
122 
123 	/*
124 	 * qc_timestamp is used when sending an atresp to set the time when the
125 	 * response is to have timed out.  It is also use on at_next to tell
126 	 * when the AT command completed.
127 	 */
128 	uint_t			qc_timestamp;
129 
130 	/*
131 	 * qc_status is an output of hci1394_q_at_next().  It contains the
132 	 * command status after completion.
133 	 */
134 	uint32_t		qc_status;
135 
136 
137 	/* PRIVATE DATA STRUCTURES */
138 	/*
139 	 * This is the memory address of where the status of this command
140 	 * resides.
141 	 */
142 	uint32_t		*qc_status_addr;
143 
144 	/*
145 	 * qc_descriptor_end and qc_descriptor_buf are used to track where the
146 	 * descriptor q pointers should be set to when this command has
147 	 * completed (i.e. free up the space used by this command)
148 	 */
149 	caddr_t			qc_descriptor_end;
150 	uint_t			qc_descriptor_buf;
151 
152 	/*
153 	 * qc_data_end and qc_data_buf are used to track where the data q
154 	 * pointers should be set to when this command has completed (i.e. free
155 	 * up the space used by this command).  Not all commands use the data
156 	 * q so qc_data_used give us state on if this command uses the data q.
157 	 */
158 	boolean_t		qc_data_used;
159 	caddr_t			qc_data_end;
160 	uint_t			qc_data_buf;
161 
162 	/*
163 	 * This is the node for the queued list.  Since AT requests finish in
164 	 * the order that they were submitted, we queue these up in a linked
165 	 * list so that it is easy to figure out which command has finished.
166 	 * Just look at the head of the list.
167 	 */
168 	hci1394_tlist_node_t	qc_node;
169 } hci1394_q_cmd_t;
170 
171 _NOTE(SCHEME_PROTECTS_DATA("Single thread modifies", \
172 	hci1394_q_cmd_s::qc_status \
173 	hci1394_q_cmd_s::qc_timestamp))
174 
175 typedef struct hci1394_q_bufptr_s {
176 	/*
177 	 * kernel virtual addresses.  The q may be broken down into multiple
178 	 * cookies.  The q is contiguous relative to the driver, but segmented
179 	 * relative to the 1394 HW DMA engines.
180 	 *
181 	 * qp_top is the top the q. qp_bottom is the bottom of the q. These
182 	 * never change after initial setup. qp_bottom is inclusive (i.e. for a
183 	 * q size of 16 bytes where top was = to 0, qp_bottom would be = to 15).
184 	 *
185 	 * qp_current and qp_free are pointers within top and bottom. qp_current
186 	 * refers to the next free space to write and free refers to the end of
187 	 * free space (i.e. used memory within q). qp_free is inclusive (see
188 	 * qp_bottom).
189 	 */
190 	caddr_t		qp_top;
191 	caddr_t		qp_bottom;
192 	caddr_t		qp_current;
193 	caddr_t		qp_free;
194 
195 	/*
196 	 * qp_begin and qp_end are also kernel virtual addresses.  They are the
197 	 * beginning and ending address of the current_buf (cookie) within the
198 	 * q.  qp_offset is (qp_current - qp_begin). This is used to determine
199 	 * the 32 bit PCI address to put into the OpenHCI descriptor. We know
200 	 * the base PCI address from the cookie structure, we add offset to that
201 	 * to determine the correct PCI address.
202 	 */
203 	caddr_t		qp_begin;
204 	caddr_t		qp_end;
205 	uint32_t	qp_offset;
206 
207 	/*
208 	 * As stated above, the q may be broken into multiple cookies.
209 	 * qp_current_buf is the cookie qp_current is in and qp_free_buf is the
210 	 * cookie qp_free is in.  NOTE: The cookie's are numbered 0, 1, 2, ...,
211 	 * (i.e. if we have 4 cookies, qp_current_buf can be 0, 1, 2, or 3)
212 	 */
213 	uint_t		qp_current_buf;
214 	uint_t		qp_free_buf;
215 
216 	/*
217 	 * qp_resv_size is only used for the AT Q's.
218 	 * How much space has been reserved.  This value is set on the call to
219 	 * hci1394_q_reserve() and decremented each time a data is written.  It
220 	 * is used to check for overrun conditions. This extra check is in there
221 	 * as an added sanity check due to the complexity of this code.
222 	 */
223 	uint_t		qp_resv_size;
224 } hci1394_q_bufptr_t;
225 
226 
227 typedef struct hci1394_q_buf_s {
228 	/* pointers to track used/free space/cookies in the buffer */
229 	hci1394_q_bufptr_t	qb_ptrs;
230 
231 	/*
232 	 * a backup of qb_ptrs. If we fail while setting up an AT Q, we need to
233 	 * cleanup by putting things back the way that they were.
234 	 */
235 	hci1394_q_bufptr_t	qb_backup_ptrs;
236 
237 	/* copy of all of the cookie's structures for this buffer */
238 	ddi_dma_cookie_t	qb_cookie[OHCI_MAX_COOKIE];
239 
240 	/* Buffer handle used for calls into hci1394_buf_* routines */
241 	hci1394_buf_handle_t	qb_buf_handle;
242 
243 	/* Buffer info (i.e. cookie count, kaddr, ddi handles, etc.) */
244 	hci1394_buf_info_t	qb_buf;
245 } hci1394_q_buf_t;
246 
247 _NOTE(SCHEME_PROTECTS_DATA("Single thread modifies", \
248 	hci1394_q_buf_s::qb_ptrs.qp_begin \
249 	hci1394_q_buf_s::qb_ptrs.qp_bottom \
250 	hci1394_q_buf_s::qb_ptrs.qp_current \
251 	hci1394_q_buf_s::qb_ptrs.qp_current_buf \
252 	hci1394_q_buf_s::qb_ptrs.qp_end \
253 	hci1394_q_buf_s::qb_ptrs.qp_offset \
254 	hci1394_q_buf_s::qb_ptrs.qp_top))
255 
256 typedef struct hci1394_q_s {
257 	/*
258 	 * q_queued_list is only used in the AT descriptor Qs. AT commands
259 	 * complete in the order they were issued. We Q these commands up with
260 	 * each new command being added to the end of the list.  When a command
261 	 * completes, we look at the top of this list to determine which command
262 	 * completed.
263 	 */
264 	hci1394_tlist_handle_t	q_queued_list;
265 
266 	/*
267 	 * pointer to general driver information (dip, instance, etc) and to
268 	 * handle for access to openHCI routines.
269 	 */
270 	hci1394_drvinfo_t	*q_drvinfo;
271 	hci1394_ohci_handle_t 	q_ohci;
272 
273 	/*
274 	 * The OpenHCI DMA engines are basically just chained DMA engines. Each
275 	 * "link" in the chain is called a descriptor in OpenHCI.  When you want
276 	 * to add a new descriptor, you init the descriptor, setup its "next"
277 	 * pointer to "NULL", update the previous descriptor to point to the
278 	 * new descriptor, and tell the HW you added a new descriptor by setting
279 	 * its wake bit. q_previous is a pointer to the previous descriptor.
280 	 * When adding a new descriptor, we just de-reference q_previous to
281 	 * update its "next" pointer.
282 	 */
283 	hci1394_desc_t		*q_previous;
284 
285 	/*
286 	 * When updating the "next" pointer in the previous descriptor block
287 	 * (as described above in q_previous), one of the things you need to
288 	 * tell the HW is how many 16 byte blocks the next descriptor block
289 	 * uses. This is what q_block_cnt is used for.  This is only used in the
290 	 * AT descriptor Q's.  Since the IM's used in the AR Q's are the only
291 	 * descriptor types used in AR, the block count is always the same for
292 	 * an AR descriptor Q.
293 	 */
294 	uint_t			q_block_cnt;
295 
296 	/*
297 	 * q_head is only used in the AR descriptor Qs. It contains the location
298 	 * of the first descriptor on the Q.  This is used to look at the
299 	 * residual count in the AR data Q.  The residual count tells us if we
300 	 * have received any new packets to process. When a descriptor's data
301 	 * buffer is empty (q_space_left = 0), we move q_head to the next
302 	 * descriptor in the descriptor buffer.
303 	 */
304 	caddr_t			q_head;
305 
306 	/*
307 	 * q_space_left is only used in the AR descriptor Qs. Each AR
308 	 * descriptor has residual count embedded in the descriptor which says
309 	 * how much free space is left in the descriptors associated data
310 	 * buffer. q_space_left is how much SW thinks is left in the data
311 	 * buffer.  When they do not match, we have a new packet(s) in the data
312 	 * buffer to process.  Since the residual count is not updated by the
313 	 * HW until the entire packet has been written to memory, we don't have
314 	 * to worry about any partial packet RX problems.
315 	 */
316 	uint_t			q_space_left;
317 
318 	/*
319 	 * status of the dma controller.  This tells us if we should do a start
320 	 * or a wake.  If the dma engine is not running, we should start it. If
321 	 * it is running, we should wake it. When the DMA engine is started, it
322 	 * expects to have a valid descriptor to process.  Since we don't have
323 	 * anything to send in the beginning (AT), we have to wait until the
324 	 * first AT packet comes down before we can start the DMA engine.
325 	 */
326 	boolean_t		q_dma_running;
327 
328 	/* The descriptor buffer for this Q */
329 	hci1394_q_buf_t		q_desc;
330 
331 	/* The data buffer for this Q */
332 	hci1394_q_buf_t		q_data;
333 
334 	/* copy of qinfo passed in during hci1394_q_init() */
335 	hci1394_q_info_t	q_info;
336 
337 	kmutex_t		q_mutex;
338 } hci1394_q_t;
339 
340 _NOTE(SCHEME_PROTECTS_DATA("Single thread modifies", \
341         hci1394_q_s::q_dma_running \
342 	hci1394_q_s::q_head \
343 	hci1394_q_s::q_previous \
344 	hci1394_q_s::q_space_left))
345 
346 /* handle passed back from init() and used for rest of functions */
347 typedef struct hci1394_q_s	*hci1394_q_handle_t;
348 
349 
350 int hci1394_q_init(hci1394_drvinfo_t *drvinfo,
351     hci1394_ohci_handle_t ohci_handle, hci1394_q_info_t *qinfo,
352     hci1394_q_handle_t *q_handle);
353 void hci1394_q_fini(hci1394_q_handle_t *q_handle);
354 void hci1394_q_resume(hci1394_q_handle_t q_handle);
355 void hci1394_q_stop(hci1394_q_handle_t q_handle);
356 
357 int hci1394_q_at(hci1394_q_handle_t q_handle, hci1394_q_cmd_t *cmd,
358     hci1394_basic_pkt_t *hdr, uint_t hdrsize, int *result);
359 int hci1394_q_at_with_data(hci1394_q_handle_t q_handle, hci1394_q_cmd_t *cmd,
360     hci1394_basic_pkt_t *hdr, uint_t hdrsize, uint8_t *data, uint_t datasize,
361     int *result);
362 int hci1394_q_at_with_mblk(hci1394_q_handle_t q_handle, hci1394_q_cmd_t *cmd,
363     hci1394_basic_pkt_t *hdr, uint_t hdrsize, h1394_mblk_t *mblk, int *result);
364 void hci1394_q_at_next(hci1394_q_handle_t q_handle, boolean_t flush_q,
365     hci1394_q_cmd_t **cmd);
366 
367 void hci1394_q_ar_next(hci1394_q_handle_t q_handle, uint32_t **q_addr);
368 void hci1394_q_ar_free(hci1394_q_handle_t q_handle, uint_t size);
369 uint32_t hci1394_q_ar_get32(hci1394_q_handle_t q_handle, uint32_t *addr);
370 void hci1394_q_ar_rep_get8(hci1394_q_handle_t q_handle, uint8_t *dest,
371     uint8_t *q_addr, uint_t size);
372 void hci1394_q_ar_copy_to_mblk(hci1394_q_handle_t q_handle, uint8_t *addr,
373     h1394_mblk_t *mblk);
374 
375 
376 #ifdef __cplusplus
377 }
378 #endif
379 
380 #endif	/* _SYS_1394_ADAPTERS_HCI1394_Q_H */
381