xref: /titanic_50/usr/src/uts/common/sys/1394/id1394.h (revision 4b22b9337f359bfd063322244f5336cc7c6ffcfa)
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_ID1394_H
28 #define	_SYS_1394_ID1394_H
29 
30 #pragma ident	"%Z%%M%	%I%	%E% SMI"
31 
32 /*
33  * id1394.h
34  *    Contains enums and structures used for managing a local isochronous
35  *    DMA resource.
36  */
37 
38 #include <sys/types.h>
39 #include <sys/dditypes.h>
40 #include <sys/ddi.h>
41 #include <sys/sunddi.h>
42 
43 #include <sys/1394/ixl1394.h>
44 
45 #ifdef	__cplusplus
46 extern "C" {
47 #endif
48 
49 /*
50  * t1394_alloc_isoch_dma() is used to allocate a local isochronous
51  * DMA resource for receiving or for transmitting isochronous data.
52  * Upon successful allocation, the 1394 Framework returns a handle
53  * of the type shown below. The target driver passes this handle back to
54  * the 1394 Framework for all subsequent t1394_*_isoch_dma() calls
55  * used to control the allocated resource.
56  */
57 typedef struct isoch_dma_handle	*t1394_isoch_dma_handle_t;
58 
59 /*
60  * Target drivers use the id1394_isoch_dma_options_t enumerated type to
61  * specify to t1394_alloc_isoch_dma() the desired characteristics of
62  * the requested local isochronous DMA resource.
63  * ID1394_TALK specifies an isochronous transmit DMA resource.
64  * ID1394_LISTEN_PKT_MODE specifies an isochronous receive DMA resource in
65  *    which each packet is received into its own (set of) buffer(s).
66  * ID1394_LISTEN_BUF_MODE specifies an isochronous receive DMA resource in
67  *    which packets may be concatenated into a single buffer.
68  * ID1394_RECV_HEADERS specifies that isochronous packet header data for
69  *    received isochronous packets are stored into the data buffers along
70  *    with the packet data (otherwise the packet header is removed).
71  */
72 typedef enum {
73 	ID1394_TALK			= (1 << 0),
74 	ID1394_LISTEN_PKT_MODE		= (1 << 1),
75 	ID1394_LISTEN_BUF_MODE		= (1 << 2),
76 	ID1394_RECV_HEADERS		= (1 << 3)
77 } id1394_isoch_dma_options_t;
78 
79 /*
80  * Enumerated type id1394_isoch_dma_stopped_t is a return argument to
81  * the target's isoch_dma_stopped() callback.
82  * Under a variety of circumstances, the local DMA resource may stop running.
83  * If this occurs (independently of a target driver`s direct call to
84  * t1394_stop_isoch_dma()), the target driver's isoch_dma_stopped callback is
85  * invoked.  In this callback, the reason for the stop is indicated in the
86  * id1394_isoch_dma_stopped_t enumerated type.  ID1394_DONE indicates the
87  * isochronous DMA resource stopped because it reached the "end."
88  * ID1394_FAIL indicates the isochronous DMA resource encountered an error.
89  */
90 typedef enum {
91 	ID1394_DONE			= 1,
92 	ID1394_FAIL			= 2
93 } id1394_isoch_dma_stopped_t;
94 
95 /*
96  * Targets use id1394_isoch_dmainfo_t with t1394_alloc_isoch_dma() to specify
97  * the desired characteristics of the local isochronous DMA resource.
98  *
99  * ixlp
100  *	is the kernel virtual address of the first IXL program command.
101  *	For IXL program command structures, see ixl1394.h.
102  * channel_num
103  *	is the isochronous channel number (0-63) for the allocated local
104  *	isochronous DMA resource.  For an isochronous receive DMA resource,
105  *	only packets with the specified channel number are received into the
106  *	provided buffers.  For an isochronous transmit DMA resource, the
107  *	1394 Framework constructs isochronous transmit packet headers using the
108  *	specified channel number.
109  * default_tag
110  *	are the tag bits for the local isochronous DMA resource.
111  *	For an isochronous receive DMA resource, only packets with the specified
112  *	tag bits are received into the provided buffers.  For an isochronous
113  *	transmit DMA resource, the 1394 Framework constructs isochronous
114  *	transmit packet headers using the specified tag bits.
115  * default_sync
116  *	are the sync bits for the local isochronous DMA resource.  Usage is
117  *	similar to that of default_tag above.
118  * it_speed
119  *	is used only for an isochronous transmit resource and indicates the
120  *	speed at which the 1394 Framework shall transmit packets.  For valid
121  *	speeds, see ieee1394.h.
122  * global_callback_arg
123  *	is the argument the 1394 Framework provides to the target when invoking
124  *	a callback specified in an ixl1394_callback_t IXL command or an IXL
125  *	program. Target drivers can use this to track state or any other
126  *	information.  See ixl1394.h for IXL command info.
127  * it_default_skip
128  *	is used for isochronous transmit DMA resources only and specifies the
129  *	default skip mode for the resource.  See ixl1394.h for valid skip modes.
130  * it_default_skiplabel
131  *	is used for isochronous transmit DMA resources only, and when
132  *	it_default_skip is IXL1394_SKIP_TO_LABEL.  It contains a pointer to
133  *	the targetted IXL Label command.
134  * idma_options
135  *	is used to specify the overall transmit or receive characteristics
136  *	of the requested local isochronous DMA resource.
137  * isoch_dma_stopped
138  *	is the target driver's callback routine the 1394 Framework is to
139  *	invoke if the local isochronous DMA resource stops.
140  * idma_evt_arg
141  *	is the target driver's callback argument to be handed back to the target
142  *	driver when the 1394 Framework invokes the isoch_dma_stopped() callback.
143  */
144 typedef struct id1394_isoch_dmainfo_s {
145 	ixl1394_command_t		*ixlp;		/* 1st IXL command */
146 	uint_t				channel_num;	/* isoch channel */
147 	uint_t				default_tag;	/* tag */
148 	uint_t				default_sync;	/* sync */
149 	uint_t				it_speed;	/* speed - xmit only */
150 	void				*global_callback_arg;
151 	ixl1394_skip_t			it_default_skip; /* skip - xmit only */
152 	ixl1394_command_t		*it_default_skiplabel;
153 	id1394_isoch_dma_options_t	idma_options;	/* I/O type */
154 
155 	void	(*isoch_dma_stopped)(t1394_isoch_dma_handle_t t1394_idma_hdl,
156 		    opaque_t idma_evt_arg,
157 		    id1394_isoch_dma_stopped_t idma_stop_args);
158 	opaque_t			idma_evt_arg;
159 } id1394_isoch_dmainfo_t;
160 
161 /*
162  * Target drivers supply the id1394_isoch_dma_ctrlinfo_t structure to the
163  * t1394_start_isoch_dma() call to indicate the cycle at which the local
164  * isochronous DMA resource is to start receiving or transmitting packets.
165  */
166 typedef struct id1394_isoch_dma_ctrlinfo_s {
167 	uint_t				start_cycle;
168 } id1394_isoch_dma_ctrlinfo_t;
169 
170 /*
171  * t1394_start_isoch_dma() flags.
172  * ID1394_START_ON_CYCLE - if specified, this flag indicates that the local
173  *    isochronous DMA resource is to start receiving or transmitting packets
174  *    at the cycle time specified in id1394_isoch_dma_ctrlinfo_t.
175  *    If not specified, the isochronous DMA resource starts receiving or
176  *    transmitting packets as soon as possible.
177  */
178 #define	ID1394_START_ON_CYCLE	    0x00000001	/* start on specified cycle */
179 
180 /*
181  * Target drivers use the id1394_isoch_dma_updateinfo_t structure to provide
182  * information to t1394_update_isoch_dma(), which dynamically updates an IXL
183  * program for an allocated local isochronous DMA resource.  See ixl1394.h
184  * for information on IXL program commands.
185  * temp_ixlp
186  *	points to the first new IXL command used to update an existing IXL
187  *	command.
188  * orig_ixlp
189  *	points to the original IXL command to be updated.
190  * ixl_count
191  *	is the number of IXL commands to be updated.
192  */
193 typedef struct id1394_isoch_dma_updateinfo_s {
194 	ixl1394_command_t		*temp_ixlp; /* first new IXL cmd */
195 	ixl1394_command_t		*orig_ixlp; /* first updated IXL cmd */
196 	uint_t				ixl_count;  /* length of update chain */
197 } id1394_isoch_dma_updateinfo_t;
198 
199 
200 #ifdef __cplusplus
201 }
202 #endif
203 
204 #endif	/* _SYS_1394_ID1394_H */
205