usr/src/uts/common/sys/1394/id1394.h

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