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