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