1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 /* 23 * Copyright (c) 1999-2000 by Sun Microsystems, Inc. 24 * All rights reserved. 25 */ 26 27 #ifndef _SYS_1394_ID1394_H 28 #define _SYS_1394_ID1394_H 29 30 /* 31 * id1394.h 32 * Contains enums and structures used for managing a local isochronous 33 * DMA resource. 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/ixl1394.h> 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /* 48 * t1394_alloc_isoch_dma() is used to allocate a local isochronous 49 * DMA resource for receiving or for transmitting isochronous data. 50 * Upon successful allocation, the 1394 Framework returns a handle 51 * of the type shown below. The target driver passes this handle back to 52 * the 1394 Framework for all subsequent t1394_*_isoch_dma() calls 53 * used to control the allocated resource. 54 */ 55 typedef struct isoch_dma_handle *t1394_isoch_dma_handle_t; 56 57 /* 58 * Target drivers use the id1394_isoch_dma_options_t enumerated type to 59 * specify to t1394_alloc_isoch_dma() the desired characteristics of 60 * the requested local isochronous DMA resource. 61 * ID1394_TALK specifies an isochronous transmit DMA resource. 62 * ID1394_LISTEN_PKT_MODE specifies an isochronous receive DMA resource in 63 * which each packet is received into its own (set of) buffer(s). 64 * ID1394_LISTEN_BUF_MODE specifies an isochronous receive DMA resource in 65 * which packets may be concatenated into a single buffer. 66 * ID1394_RECV_HEADERS specifies that isochronous packet header data for 67 * received isochronous packets are stored into the data buffers along 68 * with the packet data (otherwise the packet header is removed). 69 */ 70 typedef enum { 71 ID1394_TALK = (1 << 0), 72 ID1394_LISTEN_PKT_MODE = (1 << 1), 73 ID1394_LISTEN_BUF_MODE = (1 << 2), 74 ID1394_RECV_HEADERS = (1 << 3) 75 } id1394_isoch_dma_options_t; 76 77 /* 78 * Enumerated type id1394_isoch_dma_stopped_t is a return argument to 79 * the target's isoch_dma_stopped() callback. 80 * Under a variety of circumstances, the local DMA resource may stop running. 81 * If this occurs (independently of a target driver`s direct call to 82 * t1394_stop_isoch_dma()), the target driver's isoch_dma_stopped callback is 83 * invoked. In this callback, the reason for the stop is indicated in the 84 * id1394_isoch_dma_stopped_t enumerated type. ID1394_DONE indicates the 85 * isochronous DMA resource stopped because it reached the "end." 86 * ID1394_FAIL indicates the isochronous DMA resource encountered an error. 87 */ 88 typedef enum { 89 ID1394_DONE = 1, 90 ID1394_FAIL = 2 91 } id1394_isoch_dma_stopped_t; 92 93 /* 94 * Targets use id1394_isoch_dmainfo_t with t1394_alloc_isoch_dma() to specify 95 * the desired characteristics of the local isochronous DMA resource. 96 * 97 * ixlp 98 * is the kernel virtual address of the first IXL program command. 99 * For IXL program command structures, see ixl1394.h. 100 * channel_num 101 * is the isochronous channel number (0-63) for the allocated local 102 * isochronous DMA resource. For an isochronous receive DMA resource, 103 * only packets with the specified channel number are received into the 104 * provided buffers. For an isochronous transmit DMA resource, the 105 * 1394 Framework constructs isochronous transmit packet headers using the 106 * specified channel number. 107 * default_tag 108 * are the tag bits for the local isochronous DMA resource. 109 * For an isochronous receive DMA resource, only packets with the specified 110 * tag bits are received into the provided buffers. For an isochronous 111 * transmit DMA resource, the 1394 Framework constructs isochronous 112 * transmit packet headers using the specified tag bits. 113 * default_sync 114 * are the sync bits for the local isochronous DMA resource. Usage is 115 * similar to that of default_tag above. 116 * it_speed 117 * is used only for an isochronous transmit resource and indicates the 118 * speed at which the 1394 Framework shall transmit packets. For valid 119 * speeds, see ieee1394.h. 120 * global_callback_arg 121 * is the argument the 1394 Framework provides to the target when invoking 122 * a callback specified in an ixl1394_callback_t IXL command or an IXL 123 * program. Target drivers can use this to track state or any other 124 * information. See ixl1394.h for IXL command info. 125 * it_default_skip 126 * is used for isochronous transmit DMA resources only and specifies the 127 * default skip mode for the resource. See ixl1394.h for valid skip modes. 128 * it_default_skiplabel 129 * is used for isochronous transmit DMA resources only, and when 130 * it_default_skip is IXL1394_SKIP_TO_LABEL. It contains a pointer to 131 * the targetted IXL Label command. 132 * idma_options 133 * is used to specify the overall transmit or receive characteristics 134 * of the requested local isochronous DMA resource. 135 * isoch_dma_stopped 136 * is the target driver's callback routine the 1394 Framework is to 137 * invoke if the local isochronous DMA resource stops. 138 * idma_evt_arg 139 * is the target driver's callback argument to be handed back to the target 140 * driver when the 1394 Framework invokes the isoch_dma_stopped() callback. 141 */ 142 typedef struct id1394_isoch_dmainfo_s { 143 ixl1394_command_t *ixlp; /* 1st IXL command */ 144 uint_t channel_num; /* isoch channel */ 145 uint_t default_tag; /* tag */ 146 uint_t default_sync; /* sync */ 147 uint_t it_speed; /* speed - xmit only */ 148 void *global_callback_arg; 149 ixl1394_skip_t it_default_skip; /* skip - xmit only */ 150 ixl1394_command_t *it_default_skiplabel; 151 id1394_isoch_dma_options_t idma_options; /* I/O type */ 152 153 void (*isoch_dma_stopped)(t1394_isoch_dma_handle_t t1394_idma_hdl, 154 opaque_t idma_evt_arg, 155 id1394_isoch_dma_stopped_t idma_stop_args); 156 opaque_t idma_evt_arg; 157 } id1394_isoch_dmainfo_t; 158 159 /* 160 * Target drivers supply the id1394_isoch_dma_ctrlinfo_t structure to the 161 * t1394_start_isoch_dma() call to indicate the cycle at which the local 162 * isochronous DMA resource is to start receiving or transmitting packets. 163 */ 164 typedef struct id1394_isoch_dma_ctrlinfo_s { 165 uint_t start_cycle; 166 } id1394_isoch_dma_ctrlinfo_t; 167 168 /* 169 * t1394_start_isoch_dma() flags. 170 * ID1394_START_ON_CYCLE - if specified, this flag indicates that the local 171 * isochronous DMA resource is to start receiving or transmitting packets 172 * at the cycle time specified in id1394_isoch_dma_ctrlinfo_t. 173 * If not specified, the isochronous DMA resource starts receiving or 174 * transmitting packets as soon as possible. 175 */ 176 #define ID1394_START_ON_CYCLE 0x00000001 /* start on specified cycle */ 177 178 /* 179 * Target drivers use the id1394_isoch_dma_updateinfo_t structure to provide 180 * information to t1394_update_isoch_dma(), which dynamically updates an IXL 181 * program for an allocated local isochronous DMA resource. See ixl1394.h 182 * for information on IXL program commands. 183 * temp_ixlp 184 * points to the first new IXL command used to update an existing IXL 185 * command. 186 * orig_ixlp 187 * points to the original IXL command to be updated. 188 * ixl_count 189 * is the number of IXL commands to be updated. 190 */ 191 typedef struct id1394_isoch_dma_updateinfo_s { 192 ixl1394_command_t *temp_ixlp; /* first new IXL cmd */ 193 ixl1394_command_t *orig_ixlp; /* first updated IXL cmd */ 194 uint_t ixl_count; /* length of update chain */ 195 } id1394_isoch_dma_updateinfo_t; 196 197 198 #ifdef __cplusplus 199 } 200 #endif 201 202 #endif /* _SYS_1394_ID1394_H */ 203