xref: /titanic_44/usr/src/uts/common/sys/1394/t1394.h (revision 56b2bdd1f04d465cfe4a95b88ae5cba5884154e4)
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 1999-2002 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef	_SYS_1394_T1394_H
28 #define	_SYS_1394_T1394_H
29 
30 #pragma ident	"%Z%%M%	%I%	%E% SMI"
31 
32 /*
33  * t1394.h
34  *    Contains all of the prototypes, defines, and structures necessary
35  *    for building drivers using the Solaris 1394 Software Framework.
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/s1394_impl.h>
44 #include <sys/1394/cmd1394.h>
45 #include <sys/1394/id1394.h>
46 #include <sys/1394/ixl1394.h>
47 #include <sys/1394/ieee1394.h>
48 #include <sys/1394/ieee1212.h>
49 
50 #ifdef	__cplusplus
51 extern "C" {
52 #endif
53 
54 /*
55  * Macro to convert a byte stream into a big endian quadlet or octlet or
56  * back the other way.  All data is treated as byte streams over the 1394
57  * bus.  These macros will convert the data to a big endian "integer" on
58  * x86 platforms, and it will do nothing if it is not on x86.
59  */
60 #ifdef _LITTLE_ENDIAN
61 #define	T1394_DATA32(DATA)	ddi_swap32(DATA)
62 #define	T1394_DATA64(DATA)	ddi_swap64(DATA)
63 #else
64 #define	T1394_DATA32(DATA)	(DATA)
65 #define	T1394_DATA64(DATA)	(DATA)
66 #endif
67 
68 /* The various "handles" returned by the 1394 Framework */
69 
70 /* Target handle type */
71 typedef struct target_handle	*t1394_handle_t;
72 /* Address handle type */
73 typedef struct address_handle	*t1394_addr_handle_t;
74 /* Isoch single handle type */
75 typedef struct isoch_handle	*t1394_isoch_single_handle_t;
76 /* Isoch CEC handle type */
77 typedef struct isoch_handle	*t1394_isoch_cec_handle_t;
78 /* Config ROM handle type */
79 typedef struct cfgrom_handle	*t1394_cfgrom_handle_t;
80 
81 
82 /*
83  * t1394_localinfo_t
84  *    is filled in and returned by the 1394 Framework at attach time
85  *    (in the t1394_attachinfo_t structure returned from t1394_attach())
86  *    to provide the local host nodeID and the current bus generation.
87  */
88 typedef struct t1394_localinfo_s {
89 	uint_t			bus_generation;
90 	uint_t			local_nodeID;
91 } t1394_localinfo_t;
92 
93 /*
94  * t1394_attachinfo_t
95  *    is filled in and returned by the 1394 Framework at attach time
96  *    (returned from the call to t1394_attach()).  This structure contains
97  *    the t1394_localinfo_t structure described above, as well as the
98  *    iblock cookie and the attributes necessary for DMA allocations, etc.
99  */
100 typedef struct t1394_attachinfo_s {
101 	ddi_iblock_cookie_t 	iblock_cookie;
102 	ddi_device_acc_attr_t	acc_attr;
103 	ddi_dma_attr_t		dma_attr;
104 	t1394_localinfo_t	localinfo;
105 } t1394_attachinfo_t;
106 
107 
108 /*
109  * t1394_addr_enable_t
110  *    is used in the t1394_alloc_addr_t structure, passed to
111  *    t1394_alloc_addr(), to indicate what types of (incoming)
112  *    asynchronous requests will be allowed in a given address block.
113  *    If, for example, an address block is intended to be read-only,
114  *    then only the T1394_ADDR_RDENBL bit should be enabled at allocation
115  *    time.  Then, when incoming requests of an inappropriate type (write
116  *    or lock requests, in this case) arrive, the 1394 Framework can
117  *    automatically respond to them with TYPE_ERROR in the response
118  *    without having to notify the target driver.
119  */
120 typedef enum {
121 	T1394_ADDR_RDENBL =	(1 << 0),
122 	T1394_ADDR_WRENBL =	(1 << 1),
123 	T1394_ADDR_LKENBL =	(1 << 2)
124 } t1394_addr_enable_t;
125 
126 /*
127  * t1394_addr_type_t
128  *    is used in the t1394_alloc_addr_t structure, passed to
129  *    t1394_alloc_addr(), to indicate what type of address block the
130  *    target driver would like to allocate.
131  *    T1394_ADDR_POSTED_WRITE indicates posted write memory, where
132  *    incoming write requests are automatically acknowledged as complete.
133  *    T1394_ADDR_NORMAL indicates memory, unlike the posted write area,
134  *    where all requests regardless of type are ack_pended upon receipt
135  *    and are subsequently responded to.
136  *    T1394_ADDR_CSR memory range is generally used by target drivers
137  *    that are implementing a well-defined protocol.
138  *    And T1394_ADDR_FIXED is used to indicate to t1394_alloc_addr()
139  *    that a specific set of addresses are needed.  Unlike the other three
140  *    types, this type of request is used to choose a specific address or
141  *    range of addresses in 1394 address space.
142  */
143 typedef enum {
144 	T1394_ADDR_POSTED_WRITE	= 0,
145 	T1394_ADDR_NORMAL	= 1,
146 	T1394_ADDR_CSR		= 2,
147 	T1394_ADDR_FIXED	= 3
148 } t1394_addr_type_t;
149 
150 /*
151  * t1394_addr_evts_t
152  *    is used in the t1394_alloc_addr_t structure, passed to
153  *    t1394_alloc_addr(), to specify callback routines for the
154  *    allocated address block.  When a request of the appropriate type
155  *    (read/write/lock) is received to a target driver's address
156  *    block, the appropriate callback routine is consulted and if it is
157  *    non-NULL it is called and passed a cmd1394_cmd_t structure used to
158  *    describe the incoming asynch request.
159  */
160 typedef struct t1394_addr_evts {
161 	void	(*recv_read_request)(cmd1394_cmd_t *req);
162 	void	(*recv_write_request)(cmd1394_cmd_t *req);
163 	void	(*recv_lock_request)(cmd1394_cmd_t *req);
164 } t1394_addr_evts_t;
165 
166 /*
167  * t1394_alloc_addr_t
168  *    is passed to t1394_alloc_addr(), when 1394 address space is being
169  *    allocated, to describe the type of address space.  The target driver
170  *    is responsible for specifying the aa_enable, aa_type, and aa_evts
171  *    fields described above as well as the size of the allocated block.
172  *    Additionally, the target driver may specify backing store
173  *    (aa_kmem_bufp), a specific address (in aa_address if aa_type is
174  *    T1394_ADDR_FIXED), and a callback argument (in aa_arg) to be
175  *    passed to the target in any of its callback routines.
176  *    When it returns, t1394_alloc_addr() will return in aa_address the
177  *    starting address of the requested block of 1394 address space and
178  *    and address block handle (aa_hdl) used to free the address block
179  *    in a call to t1394_free_addr().
180  */
181 typedef struct t1394_alloc_addr {
182 	t1394_addr_type_t	aa_type;	/* IN: address region */
183 	size_t			aa_length;	/* IN: # bytes requested */
184 	t1394_addr_enable_t	aa_enable;	/* IN: request enables */
185 	t1394_addr_evts_t	aa_evts;	/* IN: event callbacks */
186 	opaque_t		aa_arg;		/* IN: evt callback arg */
187 	caddr_t			aa_kmem_bufp;	/* IN: backing-store buf */
188 	uint64_t		aa_address;	/* IN/OUT: alloced address */
189 	t1394_addr_handle_t	aa_hdl;		/* OUT: returned to target */
190 } t1394_alloc_addr_t;
191 
192 /*
193  * t1394_fcp_evts_t
194  *    is used in t1394_fcp_register_controller(). FCP only allows writes.
195  */
196 typedef struct t1394_fcp_evts {
197 	int		(*fcp_write_request)(cmd1394_cmd_t *req);
198 	opaque_t	fcp_arg;
199 } t1394_fcp_evts_t;
200 
201 /* values returned by the FCP callback */
202 enum {
203 	T1394_REQ_CLAIMED,	/* request is recognized by the target */
204 	T1394_REQ_UNCLAIMED	/* request is not recognized by the target */
205 };
206 
207 /*
208  * t1394_cmp_reg_t
209  *    CMP register types
210  */
211 typedef enum {
212 	T1394_CMP_OMPR,		/* oMPR */
213 	T1394_CMP_IMPR		/* iMPR */
214 } t1394_cmp_reg_t;
215 
216 /*
217  * t1394_cmp_evts_t
218  *    is used in t1394_cmp_register().
219  */
220 typedef struct t1394_cmp_evts {
221 	void		(*cmp_reg_change)(opaque_t, t1394_cmp_reg_t);
222 	opaque_t	cmp_arg;
223 } t1394_cmp_evts_t;
224 
225 /*
226  * t1394_isoch_rsrc_error_t
227  *    is used in the rsrc_fail_target() callback to indicate the reason
228  *    for the resource allocation failure.  T1394_RSRC_BANDWIDTH indicates
229  *    that insufficient bandwidth was available for the requested allocation,
230  *    and T1394_RSRC_CHANNEL indicates that none of the requested channels
231  *    were available.
232  */
233 typedef enum {
234 	T1394_RSRC_BANDWIDTH	= 1,
235 	T1394_RSRC_CHANNEL	= 2
236 } t1394_isoch_rsrc_error_t;
237 
238 /*
239  * t1394_isoch_singleinfo_t
240  *    is passed to the t1394_alloc_isoch_single() routine.  A target
241  *    driver will use this structure to indicate the channels it supports,
242  *    the maximum speed for the isochronous channel, the amount of
243  *    bandwidth required, and the callback (and callback arg) to be used
244  *    when notifying the target of resource reallocation failures.
245  */
246 typedef struct t1394_isoch_singleinfo_s {
247 	uint64_t	si_channel_mask;	/* channels supported */
248 	uint_t		si_speed;		/* 1394 speed for the channel */
249 	uint_t		si_bandwidth;		/* max bytes per cycle */
250 	void		(*rsrc_fail_target)(
251 			    t1394_isoch_single_handle_t	t1394_single_hdl,
252 			    opaque_t			single_evt_arg,
253 			    t1394_isoch_rsrc_error_t	fail_args);
254 	opaque_t	single_evt_arg;
255 } t1394_isoch_singleinfo_t;
256 
257 /*
258  * t1394_isoch_single_out_t
259  *    is filled in and returned to the target by the
260  *    t1394_alloc_isoch_single() routine.  It indicates the number of the
261  *    channel that was actually allocated for the target driver.  This
262  *    channel number will typically be used by a target driver to setup
263  *    isochronous DMA or other resources.
264  */
265 typedef struct t1394_isoch_single_out_s {
266 	uint_t		channel_num;	/* number for the allocated channel */
267 } t1394_isoch_single_out_t;
268 
269 /*
270  * t1394_setup_target_args_t
271  *    is used in the setup_target() callback to indicate the channel number
272  *    and channel speed for the isochronous channel coordinated by the
273  *    Isoch CEC routines.
274  */
275 typedef struct t1394_setup_target_args_s {
276 	uint_t		channel_num;	/* number for the allocated channel */
277 	uint_t		channel_speed;	/* 1394 speed for the channel */
278 } t1394_setup_target_args_t;
279 
280 /*
281  * t1394_cec_options_t
282  *    is used in the t1394_isoch_cec_props_t structure, passed to
283  *    t1394_alloc_isoch_cec().  As the cec_options field in that
284  *    structure, it can be used to request that the 1394 Framework
285  *    NOT automatically reallocate the same isochronous channel and
286  *    bandwidth, if a bus reset happens.  The default behavior is to
287  *    let the 1394 Framework attempt to reallocate the same channel and
288  *    bandwidth the target had after a bus reset, but some target drivers
289  *    may not require this functionality and they therefore have the option
290  *    to decline this service.
291  */
292 typedef enum {
293 	T1394_NO_IRM_ALLOC	= (1 << 0)
294 } t1394_cec_options_t;
295 
296 /*
297  * t1394_isoch_cec_props_t
298  *    is used in calls to the t1394_alloc_isoch_cec() routine.  The
299  *    minimum and maximum speeds, channels supported, and the amount
300  *    of bandwidth necessary for the channel are specified.  These
301  *    characteristics of the Isoch CEC are specified at allocation time
302  *    and are used to pass or fail targets that try to join the Isoch
303  *    CEC later.
304  */
305 typedef struct t1394_isoch_cec_props_s {
306 	uint_t			cec_min_speed;	  /* min speed supported */
307 	uint_t			cec_max_speed;	  /* max speed supported */
308 	uint64_t		cec_channel_mask; /* channels supported  */
309 	uint_t			cec_bandwidth;	  /* max bytes per cycle */
310 	t1394_cec_options_t	cec_options;
311 } t1394_isoch_cec_props_t;
312 
313 /*
314  * t1394_isoch_cec_evts_t
315  *    is used in the t1394_join_isochinfo_t structure, passed to
316  *    t1394_join_isoch_cec().  This structure is a list of callbacks
317  *    for each of the various events the Isoch CEC is responsible for
318  *    coordinating.
319  *    The setup_target() callback is called after the isochronous
320  *    channel and bandwidth for the Isoch CEC have been allocated
321  *    (as a result of a call to t1394_setup_isoch_cec()) to inform the
322  *    member targets of the channel number and speed.
323  *    The start_target() callback is called for all member targets
324  *    as a result of a call to t1394_start_isoch_cec().
325  *    The stop_target() callback is called for all member targets
326  *    as a result of a call to t1394_stop_isoch_cec().
327  *    The rsrc_fail_target() callback (as mentioned above) is called
328  *    to indicate that the 1394 Framework was unable to reallocate
329  *    isochronous resources and the reason for the failure.
330  *    And the teardown_target() callback is called as a result of
331  *    a call to t1394_teardown_isoch_cec() to indicate that the
332  *    isochronous channel and bandwidth are being freed up.
333  */
334 typedef struct t1394_isoch_cec_evts_s {
335 	int	(*setup_target)(
336 		    t1394_isoch_cec_handle_t		t1394_isoch_cec_hdl,
337 		    opaque_t				isoch_cec_evts_arg,
338 		    t1394_setup_target_args_t		*setup_args);
339 	int	(*start_target)(
340 		    t1394_isoch_cec_handle_t		t1394_isoch_cec_hdl,
341 		    opaque_t				isoch_cec_evts_arg);
342 	void	(*stop_target)(
343 		    t1394_isoch_cec_handle_t		t1394_isoch_cec_hdl,
344 		    opaque_t				isoch_cec_evts_arg);
345 	void	(*rsrc_fail_target)(
346 		    t1394_isoch_cec_handle_t		t1394_isoch_cec_hdl,
347 		    opaque_t				isoch_cec_evts_arg,
348 		    t1394_isoch_rsrc_error_t		fail_args);
349 	void	(*teardown_target)(
350 		    t1394_isoch_cec_handle_t		t1394_isoch_cec_hdl,
351 		    opaque_t				isoch_cec_evts_arg);
352 } t1394_isoch_cec_evts_t;
353 
354 /*
355  * t1394_jii_options_t
356  *    is used in the t1394_join_isochinfo_t structure, passed to
357  *    t1394_join_isoch_cec().  As the jii_options field in that
358  *    structure, it is used to indicate to the 1394 Framework
359  *    that the member target is the talker on the channel.  There can
360  *    be no more than one talker per Isoch CEC, and a member target
361  *    may fail in t1394_join_isoch_cec() because there is already a
362  *    talker on the Isoch CEC.
363  */
364 typedef enum {
365 	T1394_TALKER		= (1 << 0)
366 } t1394_jii_options_t;
367 
368 /*
369  * t1394_join_isochinfo_t
370  *    is used in calls to the t1394_join_isoch_cec() routine.  The
371  *    req_channel_mask field indicate the channels that a member
372  *    target can support.  If these channels are inconsistent with
373  *    the characteristics passed in at allocation or with the current
374  *    characteristics of the other members of the Isoch CEC, then the
375  *    t1394_join_isoch_cec() call will fail.
376  *    The req_max_speed field is used similarly.  If the member target's
377  *    maximum speed is inconsistent with the other members of the
378  *    Isoch CEC, then the t1394_join_isoch_cec() will fail.
379  *    In addition to the above fields, a joining member target will pass
380  *    the jii_options (indicate talker or listener), the callbacks and
381  *    the callback arg (see above).
382  */
383 typedef struct t1394_join_isochinfo_s {
384 	uint64_t		req_channel_mask; /* target chnls supported */
385 	uint_t			req_max_speed;	  /* target max_speed */
386 	t1394_jii_options_t	jii_options;
387 	opaque_t		isoch_cec_evts_arg;
388 	t1394_isoch_cec_evts_t	isoch_cec_evts;
389 } t1394_join_isochinfo_t;
390 
391 
392 /*
393  * t1394_targetinfo_t
394  *    is used in calls to the t1394_get_targetinfo() routine.  The
395  *    structure returned to the target contains current_max_payload,
396  *    the default maximum block size that the host device will use in
397  *    asynchronous block reads and writes to the target's device.
398  *    It also contains current_max_speed,  the default maximum speed at
399  *    which the host device will communicate with the target's device.
400  *    The structure also contains the target driver's target nodeID,
401  *    the number assigned to the device for the current bus
402  *    generation.  It will contain T1394_INVALID_NODEID if the target
403  *    device is no longer connected to the 1394 Serial Bus.
404  */
405 typedef struct t1394_targetinfo_s {
406 	uint_t			current_max_payload;
407 	uint_t			current_max_speed;
408 	uint_t			target_nodeID;
409 } t1394_targetinfo_t;
410 #define	T1394_INVALID_NODEID	0xFFFF
411 
412 /*
413  * t1394_cfgrom_entryinfo_t
414  *    is used in calls to the t1394_add_cfgrom_entry() routine.  The
415  *    t1394_cfgrom_entryinfo_t structure contains the information necessary
416  *    to add the Config ROM entry.  The ce_buffer and ce_size are used to
417  *    describe the data to be added, and the ce_key is used to indicate
418  *    what type of entry in the Config ROM buffer the data represents
419  *    (see ieee1212.h fro key types).
420  */
421 typedef struct t1394_cfgrom_entryinfo_s {
422 	uint_t			ce_key;		/* key for Root Dir. entry */
423 	size_t			ce_size;	/* size of the buffer */
424 	uint32_t		*ce_buffer;	/* buffer for Config ROM data */
425 } t1394_cfgrom_entryinfo_t;
426 
427 
428 
429 /*
430  * ATTACH and DETACH:
431  *    These are the calls into 1394 Framework used during target driver
432  *    attach() and detach().  The t1394_attach() routine takes a dip and
433  *    a version (T1394_VERSION_V1) as its input arguments, and it fills
434  *    in and returns a t1394_attachinfo_t structure (described above) and
435  *    the t1394_handle_t.  This target handle is used in all subsequent
436  *    calls into the 1394 Framework.
437  *    The t1394_detach() routine is called from a target driver's detach()
438  *    routine to unregister itself from the 1394 Framework.
439  */
440 int t1394_attach(dev_info_t *dip, int version, uint_t flags,
441     t1394_attachinfo_t *attachinfo, t1394_handle_t *t1394_hdl);
442 /* Version value */
443 #define	T1394_VERSION_V1	1
444 
445 int t1394_detach(t1394_handle_t *t1394_hdl, uint_t flags);
446 
447 
448 /*
449  * OUTGOING ASYNCHRONOUS COMMANDS:
450  *    These are the calls into 1394 Framework used for allocating/freeing
451  *    and sending (outgoing) asynchronous requests.  The t1394_alloc_cmd()
452  *    routine takes a target driver's handle as an input argument and
453  *    returns the cmd1394_cmd_t structure necessary for sending asynch
454  *    requests.  The flags parameter is used to indicate whether or not the
455  *    1394 Framework may sleep while allocating memory for the command.
456  *    The t1394_free_cmd() routine is used to free up commands allocated
457  *    by t1394_alloc_cmd().  Commands should not be in use at the time
458  *    t1394_free_cmd() is called or the call may fail (return DDI_FAILURE).
459  *    After an asynch command has been allocated and filled in (see
460  *    the cmd1394.h file for more details) to indicate the type of request,
461  *    what types of options are necessary, callback functions and/or data
462  *    (if necessary), the command is passed to either t1394_read(),
463  *    t1394_write(), or t1394_lock().  These routines will return DDI_SUCCESS
464  *    or DDI_FAILURE depending on whether the command has been successfully
465  *    accepted by the 1394 Framework.  If the command is a "blocking"
466  *    command, the function will not return until the command has completed.
467  *    If, however, a callback has been specified in the command, that
468  *    function will be called when the command completes.
469  */
470 int t1394_alloc_cmd(t1394_handle_t t1394_hdl, uint_t flags,
471     cmd1394_cmd_t **cmdp);
472 /* Flags passed to t1394_alloc_cmd() */
473 #define	T1394_ALLOC_CMD_NOSLEEP		0x00000001 /* don't sleep in alloc */
474 #define	T1394_ALLOC_CMD_FCP_COMMAND	0x00010000 /* FCP command */
475 #define	T1394_ALLOC_CMD_FCP_RESPONSE	0x00020000 /* FCP response */
476 
477 int t1394_free_cmd(t1394_handle_t t1394_hdl, uint_t flags,
478     cmd1394_cmd_t **cmdp);
479 
480 int t1394_read(t1394_handle_t t1394_hdl, cmd1394_cmd_t *cmd);
481 
482 int t1394_write(t1394_handle_t t1394_hdl, cmd1394_cmd_t *cmd);
483 
484 int t1394_lock(t1394_handle_t t1394_hdl, cmd1394_cmd_t *cmd);
485 
486 
487 /*
488  * 1394 ADDRESS SPACE AND INCOMING ASYNCHRONOUS COMMANDS:
489  *    These are the calls into the 1394 Framework used for allocating/freeing
490  *    1394 address space and handling incoming asynchronous requests.  The
491  *    t1394_alloc_addr() routine is used to allocate 1394 address space.  It
492  *    is passed the target handle and a t1394_alloc_addr_t structure
493  *    (described above).
494  *    The t1394_free_addr() routine is used to free any allocated address
495  *    space that the target may have.  Typically, this will be done in a
496  *    target driver's detach() routine (before calling t1394_detach()).
497  *    The t1394_recv_request_done() routine is used after a target has
498  *    received and handled an incoming asynch request.  It is used to send
499  *    a response to the request.  After the command is sent to
500  *    t1394_recv_request_done(), it should not be modified or used because
501  *    the 1394 Framework may free it up without notifying the target driver.
502  */
503 int t1394_alloc_addr(t1394_handle_t t1394_hdl, t1394_alloc_addr_t *addr_allocp,
504     uint_t flags, int *result);
505 /* Results codes returned by t1394_alloc_addr() */
506 #define	T1394_EALLOC_ADDR		(-400)
507 #define	T1394_EADDR_FIRST		T1394_EALLOC_ADDR
508 #define	T1394_EADDR_LAST		T1394_EALLOC_ADDR
509 /*
510  * NOTE: Make sure T1394_EADDR_LAST is updated if a new error code is
511  * added. t1394_errmsg.c uses *FIRST and *LAST as bounds checks.
512  */
513 
514 int t1394_free_addr(t1394_handle_t t1394_hdl, t1394_addr_handle_t *addr_hdl,
515     uint_t flags);
516 
517 int t1394_recv_request_done(t1394_handle_t t1394_hdl, cmd1394_cmd_t *resp,
518     uint_t flags);
519 
520 
521 /*
522  * FCP SERVICES:
523  *    Function Control Protocol (FCP) is defined in IEC 61883-1 and supported
524  *    by the 1394 Framework. While target drivers could use t1394_alloc_addr()
525  *    and standard asynchronous services, only one driver could use FCP at a
526  *    time, because the FCP addresses have fixed values. To allow sharing of
527  *    FCP address space, the following Framework services should be used.
528  *
529  *    t1394_fcp_register_controller() registers the target as an FCP controller,
530  *    which allows it to write into target's FCP command register and receive
531  *    write requests into host's FCP response register. It takes a valid
532  *    t1394_handle_t argument, hence it should be called after t1394_attach().
533  *    t1394_fcp_unregister_controller() unregisters the target.
534  *
535  *    t1394_fcp_register_target() and t1394_fcp_unregister_target() are
536  *    target counterparts of the above controller functions.
537  */
538 
539 int t1394_fcp_register_controller(t1394_handle_t t1394_hdl,
540     t1394_fcp_evts_t *evts, uint_t flags);
541 
542 int t1394_fcp_unregister_controller(t1394_handle_t t1394_hdl);
543 
544 int t1394_fcp_register_target(t1394_handle_t t1394_hdl,
545     t1394_fcp_evts_t *evts, uint_t flags);
546 
547 int t1394_fcp_unregister_target(t1394_handle_t t1394_hdl);
548 
549 
550 /*
551  * CMP services:
552  *    Connection Management Procedures (CMP) is defined in IEC 61883-1 and
553  *    supported by the 1394 Framework by providing the drivers with shared
554  *    access to iMPR and oMPR registers, which are created by the Framework
555  *    when t1394_cmp_register() is called and destroyed when
556  *    t1394_cmp_unregister() is called. These registers can be read using
557  *    t1394_cmp_read() function and compare-swapped using t1394_cmp_cas().
558  *
559  *    oPCR and iPCR registers can be allocated by the drivers using
560  *    t1394_alloc_addr() function.
561  */
562 int t1394_cmp_register(t1394_handle_t t1394_hdl, t1394_cmp_evts_t *evts,
563     uint_t flags);
564 
565 int t1394_cmp_unregister(t1394_handle_t t1394_hdl);
566 
567 int t1394_cmp_read(t1394_handle_t t1394_hdl, t1394_cmp_reg_t reg,
568     uint32_t *valp);
569 
570 int t1394_cmp_cas(t1394_handle_t t1394_hdl, t1394_cmp_reg_t reg,
571     uint32_t arg_val, uint32_t new_val, uint32_t *old_valp);
572 
573 
574 /*
575  * ISOCHRONOUS SERVICES:
576  *    These are the calls into the 1394 Framework used for isochronous
577  *    services. The t1394_alloc_isoch_single() routine takes a target
578  *    handle and a t1394_isoch_singleinfo_t structure (see above).  It will
579  *    attempt to setup an isochronous channel (which will be automatically
580  *    reallocated after bus resets), and it will return the channel number
581  *    of the allocated channel in the t1394_isoch_single_out_t structure.
582  *    Additionally, it returns a t1394_isoch_single_handle_t structure
583  *    which is passed to t1394_free_isoch_single() when the isochronous
584  *    channel is no longer required.
585  *    The t1394_alloc_isoch_cec() and t1394_free_isoch_cec() are used to
586  *    allocate and free an Isoch Channel Event Coordinator (CEC).  Target
587  *    drivers pass a t1394_isoch_cec_props_t structure (described above)
588  *    to specify the initial characteristics of the Isoch CEC.
589  *    Targets will subsequently join the Isoch CEC with t1394_join_isoch_cec()
590  *    before setting up the channel with t1394_setup_isoch_cec().
591  *    Calls to t1394_join_isoch_cec() are used by targets who wish to join
592  *    the Isoch CEC and receive all of the channel event notifications.
593  *    When they want to leave target drivers call t1394_leave_isoch_cec().
594  *    The t1394_setup_isoch_cec(), as described above, is used to setup the
595  *    the isochronous channel and bandwidth and to notify all member targets
596  *    of the allocated channel number and speed.  After targets have finished
597  *    using the isoch channel, the resources can be torn down with a call to
598  *    t1394_teardown_isoch_cec().
599  *    Additionally, the t1394_start_isoch_cec() and t1394_stop_isoch_cec()
600  *    routines can be used by member targets to coordinate additional events,
601  *    such as the starting and stopping of isochronous DMA or other resources.
602  */
603 int t1394_alloc_isoch_single(t1394_handle_t t1394_hdl,
604     t1394_isoch_singleinfo_t *sii, uint_t flags,
605     t1394_isoch_single_out_t *output_args,
606     t1394_isoch_single_handle_t *t1394_single_hdl, int *result);
607 
608 void t1394_free_isoch_single(t1394_handle_t t1394_hdl,
609     t1394_isoch_single_handle_t *t1394_single_hdl, uint_t flags);
610 
611 int t1394_alloc_isoch_cec(t1394_handle_t t1394_hdl,
612     t1394_isoch_cec_props_t *props, uint_t flags,
613     t1394_isoch_cec_handle_t *t1394_isoch_cec_hdl);
614 
615 int t1394_free_isoch_cec(t1394_handle_t t1394_hdl, uint_t flags,
616     t1394_isoch_cec_handle_t *t1394_isoch_cec_hdl);
617 
618 int t1394_join_isoch_cec(t1394_handle_t t1394_hdl,
619     t1394_isoch_cec_handle_t t1394_isoch_cec_hdl, uint_t flags,
620     t1394_join_isochinfo_t *join_isoch_info);
621 
622 int t1394_leave_isoch_cec(t1394_handle_t t1394_hdl,
623     t1394_isoch_cec_handle_t t1394_isoch_cec_hdl, uint_t flags);
624 
625 int t1394_setup_isoch_cec(t1394_handle_t t1394_hdl,
626     t1394_isoch_cec_handle_t t1394_isoch_cec_hdl, uint_t flags, int *result);
627 
628 /* Results codes returned by t1394_setup_isoch_cec() */
629 #define	T1394_ENO_BANDWIDTH	(-500)
630 #define	T1394_ENO_CHANNEL	(-501)
631 #define	T1394_ETARGET		(-502)
632 #define	T1394_CEC_ERR_FIRST	T1394_ENO_BANDWIDTH
633 #define	T1394_CEC_ERR_LAST	T1394_ETARGET
634 /*
635  * NOTE: Make sure T1394_ERR_LAST is updated if a new error code is
636  * added. t1394_errmsg.c uses *FIRST and *LAST as bounds checks.
637  */
638 
639 int t1394_start_isoch_cec(t1394_handle_t t1394_hdl,
640     t1394_isoch_cec_handle_t t1394_isoch_cec_hdl, uint_t flags);
641 
642 int t1394_stop_isoch_cec(t1394_handle_t t1394_hdl,
643     t1394_isoch_cec_handle_t t1394_isoch_cec_hdl, uint_t flags);
644 
645 int t1394_teardown_isoch_cec(t1394_handle_t t1394_hdl,
646     t1394_isoch_cec_handle_t t1394_isoch_cec_hdl, uint_t flags);
647 
648 
649 /*
650  * ISOCHRONOUS DMA (LOCAL ISOCH DMA) SERVICES:
651  *    These are the calls into the 1394 Framework used for local
652  *    isochronous DMA services. The t1394_alloc_isoch_dma() routine
653  *    takes a target handle and an id1394_isoch_dmainfo_t structure
654  *    (see id1394.h for details) as its input arguments and returns a
655  *    t1394_isoch_dma_handle_t that the target driver will use with all
656  *    other local host DMA calls.  After allocating a local host DMA
657  *    resource, a target driver may start and stop it as often as desired
658  *    using the t1394_start_isoch_dma() and t1394_stop_isoch_dma() calls.
659  *    The t1394_start_isoch_dma() takes an id1394_isoch_dma_ctrlinfo_t
660  *    structure (also discussed in more detail in id1394.h) as an
661  *    additional argument to indicate among other things the conditions
662  *    under which the host DMA will be started.
663  *    The t1394_free_isoch_dma() is used, not surprisingly, to free up
664  *    allocate isoch DMA resources.
665  *    And the t1394_update_isoch_dma() routine is used to update a running
666  *    isochronous stream.  By creating and passing a temporary IXL command
667  *    or set of commands and both the kernel virtual addresses of the
668  *    temporary and original commands, a target driver can request that the
669  *    1394 Framework replace the original field contents with those in the
670  *    temporary command and update the corresponding hardware DMA elements.
671  */
672 int t1394_alloc_isoch_dma(t1394_handle_t t1394_hdl,
673     id1394_isoch_dmainfo_t *idi, uint_t flags,
674     t1394_isoch_dma_handle_t *t1394_idma_hdl, int *result);
675 
676 /*
677  * Results codes returned by t1394_alloc_isoch_dma(). See ixl1394.h for possible
678  * IXL1394 compilation errors.
679  * NOTE: Make sure T1394_IDMA_ERR_LAST is updated if a new error code is
680  * added.
681  */
682 #define	T1394_EIDMA_NO_RESRCS	(-600)
683 #define	T1394_EIDMA_CONFLICT	(-601)
684 #define	T1394_IDMA_ERR_FIRST	T1394_EIDMA_NO_RESRCS
685 #define	T1394_IDMA_ERR_LAST	T1394_EIDMA_CONFLICT
686 
687 void t1394_free_isoch_dma(t1394_handle_t t1394_hdl, uint_t flags,
688     t1394_isoch_dma_handle_t *t1394_idma_hdl);
689 
690 int t1394_start_isoch_dma(t1394_handle_t t1394_hdl,
691     t1394_isoch_dma_handle_t t1394_idma_hdl,
692     id1394_isoch_dma_ctrlinfo_t *idma_ctrlinfo, uint_t flags, int *result);
693 
694 void t1394_stop_isoch_dma(t1394_handle_t t1394_hdl,
695     t1394_isoch_dma_handle_t t1394_idma_hdl, uint_t flags);
696 
697 /* See ixl1394.h for possible IXL1394 t1394_update_isoch_dma() errors. */
698 int t1394_update_isoch_dma(t1394_handle_t t1394_hdl,
699     t1394_isoch_dma_handle_t t1394_idma_hdl,
700     id1394_isoch_dma_updateinfo_t *idma_updateinfo, uint_t flags, int *result);
701 
702 
703 /*
704  * MISCELLANEOUS SERVICES:
705  *    These are the calls into the 1394 Framework used for miscellaneous
706  *    services, including getting target information and topology map,
707  *    adding to and removing from local Config ROM, initiating bus resets,
708  *    etc.  The t1394_get_targetinfo() routine is used to get information
709  *    about the target driver's device and about current bus conditions
710  *    that might be useful to a target.  By passing the target handle and
711  *    current bus generation, a target driver can expect to receive a filled
712  *    in t1394_targetinfo_t structure (see above) that contains the
713  *    current_max_payload, current_max_speed, and device's nodeID.
714  *    The t1394_initiate_bus_reset() routine can be used by target drivers
715  *    to initiate a bus reset.  This call should be used only when it is
716  *    absolutely imperative, however, as bus resets affect all devices on
717  *    the 1394 Serial Bus and excessive use of bus resets can have an
718  *    adverse effect on overall bus performance.
719  *    The t1394_get_topology_map() will return the TOPOLOGY_MAP (see
720  *    IEEE 1394-1995, Section 8.3.2.4.1) which is a list of SelfID packets
721  *    from the current bus generation.
722  *    The t1394_CRC16() call is used to calculate cyclic redundancy checks
723  *    (CRCs) necessary for use in Config ROM buffers.
724  *    The t1394_add_cfgrom_entry() and t1394_rem_cfgrom_entry() calls are
725  *    used, respectively, to add and remove entries from the local host
726  *    Config ROM buffer.  (See above for a description of the
727  *    t1394_cfgrom_entryinfo_t structure.)
728  *    And the t1394_errmsg() routine is used to convert result codes which
729  *    have been returned by the 1394 Framework into character strings for
730  *    use in error messages.
731  */
732 int t1394_get_targetinfo(t1394_handle_t t1394_hdl, uint_t bus_generation,
733     uint_t flags, t1394_targetinfo_t *targetinfo);
734 
735 void t1394_initiate_bus_reset(t1394_handle_t t1394_hdl, uint_t flags);
736 
737 int t1394_get_topology_map(t1394_handle_t t1394_hdl, uint_t bus_generation,
738     size_t tm_length, uint_t flags, uint32_t *tm_buffer);
739 
740 uint_t t1394_CRC16(uint32_t *d, size_t crc_length, uint_t flags);
741 
742 int t1394_add_cfgrom_entry(t1394_handle_t t1394_hdl,
743     t1394_cfgrom_entryinfo_t *cfgrom_entryinfo, uint_t flags,
744     t1394_cfgrom_handle_t *t1394_cfgrom_hdl, int *result);
745 /* Results codes returned by t1394_add_cfgrom_entry() */
746 #define	T1394_ECFGROM_FULL		(-700)
747 #define	T1394_EINVALID_PARAM		(-701)
748 #define	T1394_EINVALID_CONTEXT		(-702)
749 #define	T1394_NOERROR			(-703)
750 #define	T1394_ECFG_FIRST		T1394_ECFGROM_FULL
751 #define	T1394_ECFG_LAST			T1394_NOERROR
752 /*
753  * NOTE: Make sure T1394_ECFG_LAST is updated if a new error code is
754  * added. t1394_errmsg.c uses *FIRST and *LAST as bounds checks.
755  */
756 
757 int t1394_rem_cfgrom_entry(t1394_handle_t t1394_hdl, uint_t flags,
758     t1394_cfgrom_handle_t *t1394_cfgrom_hdl, int *result);
759 
760 const char *t1394_errmsg(int result, uint_t flags);
761 
762 #ifdef __cplusplus
763 }
764 #endif
765 
766 #endif	/* _SYS_1394_T1394_H */
767