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