include/linux/firewire-cdev.h

   1 /*
   2  * Char device interface.
   3  *
   4  * Copyright (C) 2005-2007  Kristian Hoegsberg <krh@bitplanet.net>
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a
   7  * copy of this software and associated documentation files (the "Software"),
   8  * to deal in the Software without restriction, including without limitation
   9  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  10  * and/or sell copies of the Software, and to permit persons to whom the
  11  * Software is furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice (including the next
  14  * paragraph) shall be included in all copies or substantial portions of the
  15  * Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  20  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
  21  * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  22  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  23  * DEALINGS IN THE SOFTWARE.
  24  */
  25
  26 #ifndef _LINUX_FIREWIRE_CDEV_H
  27 #define _LINUX_FIREWIRE_CDEV_H
  28
  29 #include <linux/ioctl.h>
  30 #include <linux/types.h>
  31 #include <linux/firewire-constants.h>
  32
  33 #define FW_CDEV_EVENT_BUS_RESET                 0x00
  34 #define FW_CDEV_EVENT_RESPONSE                  0x01
  35 #define FW_CDEV_EVENT_REQUEST                   0x02
  36 #define FW_CDEV_EVENT_ISO_INTERRUPT             0x03
  37 #define FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED    0x04
  38 #define FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED  0x05
  39
  40 /**
  41  * struct fw_cdev_event_common - Common part of all fw_cdev_event_ types
  42  * @closure:    For arbitrary use by userspace
  43  * @type:       Discriminates the fw_cdev_event_ types
  44  *
  45  * This struct may be used to access generic members of all fw_cdev_event_
  46  * types regardless of the specific type.
  47  *
  48  * Data passed in the @closure field for a request will be returned in the
  49  * corresponding event.  It is big enough to hold a pointer on all platforms.
  50  * The ioctl used to set @closure depends on the @type of event.
  51  */
  52 struct fw_cdev_event_common {
  53         __u64 closure;
  54         __u32 type;
  55 };
  56
  57 /**
  58  * struct fw_cdev_event_bus_reset - Sent when a bus reset occurred
  59  * @closure:    See &fw_cdev_event_common; set by %FW_CDEV_IOC_GET_INFO ioctl
  60  * @type:       See &fw_cdev_event_common; always %FW_CDEV_EVENT_BUS_RESET
  61  * @node_id:       New node ID of this node
  62  * @local_node_id: Node ID of the local node, i.e. of the controller
  63  * @bm_node_id:    Node ID of the bus manager
  64  * @irm_node_id:   Node ID of the iso resource manager
  65  * @root_node_id:  Node ID of the root node
  66  * @generation:    New bus generation
  67  *
  68  * This event is sent when the bus the device belongs to goes through a bus
  69  * reset.  It provides information about the new bus configuration, such as
  70  * new node ID for this device, new root ID, and others.
  71  */
  72 struct fw_cdev_event_bus_reset {
  73         __u64 closure;
  74         __u32 type;
  75         __u32 node_id;
  76         __u32 local_node_id;
  77         __u32 bm_node_id;
  78         __u32 irm_node_id;
  79         __u32 root_node_id;
  80         __u32 generation;
  81 };
  82
  83 /**
  84  * struct fw_cdev_event_response - Sent when a response packet was received
  85  * @closure:    See &fw_cdev_event_common;
  86  *              set by %FW_CDEV_IOC_SEND_REQUEST ioctl
  87  * @type:       See &fw_cdev_event_common; always %FW_CDEV_EVENT_RESPONSE
  88  * @rcode:      Response code returned by the remote node
  89  * @length:     Data length, i.e. the response's payload size in bytes
  90  * @data:       Payload data, if any
  91  *
  92  * This event is sent when the stack receives a response to an outgoing request
  93  * sent by %FW_CDEV_IOC_SEND_REQUEST ioctl.  The payload data for responses
  94  * carrying data (read and lock responses) follows immediately and can be
  95  * accessed through the @data field.
  96  */
  97 struct fw_cdev_event_response {
  98         __u64 closure;
  99         __u32 type;
 100         __u32 rcode;
 101         __u32 length;
 102         __u32 data[0];
 103 };
 104
 105 /**
 106  * struct fw_cdev_event_request - Sent on incoming request to an address region
 107  * @closure:    See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl
 108  * @type:       See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST
 109  * @tcode:      Transaction code of the incoming request
 110  * @offset:     The offset into the 48-bit per-node address space
 111  * @handle:     Reference to the kernel-side pending request
 112  * @length:     Data length, i.e. the request's payload size in bytes
 113  * @data:       Incoming data, if any
 114  *
 115  * This event is sent when the stack receives an incoming request to an address
 116  * region registered using the %FW_CDEV_IOC_ALLOCATE ioctl.  The request is
 117  * guaranteed to be completely contained in the specified region.  Userspace is
 118  * responsible for sending the response by %FW_CDEV_IOC_SEND_RESPONSE ioctl,
 119  * using the same @handle.
 120  *
 121  * The payload data for requests carrying data (write and lock requests)
 122  * follows immediately and can be accessed through the @data field.
 123  */
 124 struct fw_cdev_event_request {
 125         __u64 closure;
 126         __u32 type;
 127         __u32 tcode;
 128         __u64 offset;
 129         __u32 handle;
 130         __u32 length;
 131         __u32 data[0];
 132 };
 133
 134 /**
 135  * struct fw_cdev_event_iso_interrupt - Sent when an iso packet was completed
 136  * @closure:    See &fw_cdev_event_common;
 137  *              set by %FW_CDEV_CREATE_ISO_CONTEXT ioctl
 138  * @type:       See &fw_cdev_event_common; always %FW_CDEV_EVENT_ISO_INTERRUPT
 139  * @cycle:      Cycle counter of the interrupt packet
 140  * @header_length: Total length of following headers, in bytes
 141  * @header:     Stripped headers, if any
 142  *
 143  * This event is sent when the controller has completed an &fw_cdev_iso_packet
 144  * with the %FW_CDEV_ISO_INTERRUPT bit set.  In the receive case, the headers
 145  * stripped of all packets up until and including the interrupt packet are
 146  * returned in the @header field.  The amount of header data per packet is as
 147  * specified at iso context creation by &fw_cdev_create_iso_context.header_size.
 148  *
 149  * In version 1 of this ABI, header data consisted of the 1394 isochronous
 150  * packet header, followed by quadlets from the packet payload if
 151  * &fw_cdev_create_iso_context.header_size > 4.
 152  *
 153  * In version 2 of this ABI, header data consist of the 1394 isochronous
 154  * packet header, followed by a timestamp quadlet if
 155  * &fw_cdev_create_iso_context.header_size > 4, followed by quadlets from the
 156  * packet payload if &fw_cdev_create_iso_context.header_size > 8.
 157  *
 158  * Behaviour of ver. 1 of this ABI is no longer available since ABI ver. 2.
 159  *
 160  * Format of 1394 iso packet header: 16 bits len, 2 bits tag, 6 bits channel,
 161  * 4 bits tcode, 4 bits sy, in big endian byte order.  Format of timestamp:
 162  * 16 bits invalid, 3 bits cycleSeconds, 13 bits cycleCount, in big endian byte
 163  * order.
 164  */
 165 struct fw_cdev_event_iso_interrupt {
 166         __u64 closure;
 167         __u32 type;
 168         __u32 cycle;
 169         __u32 header_length;
 170         __u32 header[0];
 171 };
 172
 173 /**
 174  * struct fw_cdev_event_iso_resource - Iso resources were allocated or freed
 175  * @closure:    See &fw_cdev_event_common;
 176  *              set by %FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE) ioctl
 177  * @type:       %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or
 178  *              %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED
 179  * @handle:     Reference by which an allocated resource can be deallocated
 180  * @channel:    Isochronous channel which was (de)allocated, if any
 181  * @bandwidth:  Bandwidth allocation units which were (de)allocated, if any
 182  *
 183  * An %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED event is sent after an isochronous
 184  * resource was allocated at the IRM.  The client has to check @channel and
 185  * @bandwidth for whether the allocation actually succeeded.
 186  *
 187  * An %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event is sent after an isochronous
 188  * resource was deallocated at the IRM.  It is also sent when automatic
 189  * reallocation after a bus reset failed.
 190  *
 191  * @channel is <0 if no channel was (de)allocated or if reallocation failed.
 192  * @bandwidth is 0 if no bandwidth was (de)allocated or if reallocation failed.
 193  */
 194 struct fw_cdev_event_iso_resource {
 195         __u64 closure;
 196         __u32 type;
 197         __u32 handle;
 198         __s32 channel;
 199         __s32 bandwidth;
 200 };
 201
 202 /**
 203  * union fw_cdev_event - Convenience union of fw_cdev_event_ types
 204  * @common:        Valid for all types
 205  * @bus_reset:     Valid if @common.type == %FW_CDEV_EVENT_BUS_RESET
 206  * @response:      Valid if @common.type == %FW_CDEV_EVENT_RESPONSE
 207  * @request:       Valid if @common.type == %FW_CDEV_EVENT_REQUEST
 208  * @iso_interrupt: Valid if @common.type == %FW_CDEV_EVENT_ISO_INTERRUPT
 209  * @iso_resource:  Valid if @common.type ==
 210  *                              %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or
 211  *                              %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED
 212  *
 213  * Convenience union for userspace use.  Events could be read(2) into an
 214  * appropriately aligned char buffer and then cast to this union for further
 215  * processing.  Note that for a request, response or iso_interrupt event,
 216  * the data[] or header[] may make the size of the full event larger than
 217  * sizeof(union fw_cdev_event).  Also note that if you attempt to read(2)
 218  * an event into a buffer that is not large enough for it, the data that does
 219  * not fit will be discarded so that the next read(2) will return a new event.
 220  */
 221 union fw_cdev_event {
 222         struct fw_cdev_event_common             common;
 223         struct fw_cdev_event_bus_reset          bus_reset;
 224         struct fw_cdev_event_response           response;
 225         struct fw_cdev_event_request            request;
 226         struct fw_cdev_event_iso_interrupt      iso_interrupt;
 227         struct fw_cdev_event_iso_resource       iso_resource;
 228 };
 229
 230 /* available since kernel version 2.6.22 */
 231 #define FW_CDEV_IOC_GET_INFO           _IOWR('#', 0x00, struct fw_cdev_get_info)
 232 #define FW_CDEV_IOC_SEND_REQUEST        _IOW('#', 0x01, struct fw_cdev_send_request)
 233 #define FW_CDEV_IOC_ALLOCATE           _IOWR('#', 0x02, struct fw_cdev_allocate)
 234 #define FW_CDEV_IOC_DEALLOCATE          _IOW('#', 0x03, struct fw_cdev_deallocate)
 235 #define FW_CDEV_IOC_SEND_RESPONSE       _IOW('#', 0x04, struct fw_cdev_send_response)
 236 #define FW_CDEV_IOC_INITIATE_BUS_RESET  _IOW('#', 0x05, struct fw_cdev_initiate_bus_reset)
 237 #define FW_CDEV_IOC_ADD_DESCRIPTOR     _IOWR('#', 0x06, struct fw_cdev_add_descriptor)
 238 #define FW_CDEV_IOC_REMOVE_DESCRIPTOR   _IOW('#', 0x07, struct fw_cdev_remove_descriptor)
 239 #define FW_CDEV_IOC_CREATE_ISO_CONTEXT _IOWR('#', 0x08, struct fw_cdev_create_iso_context)
 240 #define FW_CDEV_IOC_QUEUE_ISO          _IOWR('#', 0x09, struct fw_cdev_queue_iso)
 241 #define FW_CDEV_IOC_START_ISO           _IOW('#', 0x0a, struct fw_cdev_start_iso)
 242 #define FW_CDEV_IOC_STOP_ISO            _IOW('#', 0x0b, struct fw_cdev_stop_iso)
 243
 244 /* available since kernel version 2.6.24 */
 245 #define FW_CDEV_IOC_GET_CYCLE_TIMER     _IOR('#', 0x0c, struct fw_cdev_get_cycle_timer)
 246
 247 /* available since kernel version 2.6.30 */
 248 #define FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE       _IOWR('#', 0x0d, struct fw_cdev_allocate_iso_resource)
 249 #define FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE      _IOW('#', 0x0e, struct fw_cdev_deallocate)
 250 #define FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE   _IOW('#', 0x0f, struct fw_cdev_allocate_iso_resource)
 251 #define FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE_ONCE _IOW('#', 0x10, struct fw_cdev_allocate_iso_resource)
 252 #define FW_CDEV_IOC_GET_SPEED                     _IO('#', 0x11) /* returns speed code */
 253 #define FW_CDEV_IOC_SEND_BROADCAST_REQUEST       _IOW('#', 0x12, struct fw_cdev_send_request)
 254 #define FW_CDEV_IOC_SEND_STREAM_PACKET           _IOW('#', 0x13, struct fw_cdev_send_stream_packet)
 255
 256 /* available since kernel version 2.6.34 */
 257 #define FW_CDEV_IOC_GET_CYCLE_TIMER2   _IOWR('#', 0x14, struct fw_cdev_get_cycle_timer2)
 258
 259 /*
 260  * FW_CDEV_VERSION History
 261  *  1  (2.6.22)  - initial version
 262  *  2  (2.6.30)  - changed &fw_cdev_event_iso_interrupt.header if
 263  *                 &fw_cdev_create_iso_context.header_size is 8 or more
 264  *     (2.6.32)  - added time stamp to xmit &fw_cdev_event_iso_interrupt
 265  *     (2.6.33)  - IR has always packet-per-buffer semantics now, not one of
 266  *                 dual-buffer or packet-per-buffer depending on hardware
 267  *  3  (2.6.34)  - made &fw_cdev_get_cycle_timer reliable
 268  */
 269 #define FW_CDEV_VERSION 3
 270
 271 /**
 272  * struct fw_cdev_get_info - General purpose information ioctl
 273  * @version:    The version field is just a running serial number.
 274  *              We never break backwards compatibility, but may add more
 275  *              structs and ioctls in later revisions.
 276  * @rom_length: If @rom is non-zero, at most rom_length bytes of configuration
 277  *              ROM will be copied into that user space address.  In either
 278  *              case, @rom_length is updated with the actual length of the
 279  *              configuration ROM.
 280  * @rom:        If non-zero, address of a buffer to be filled by a copy of the
 281  *              device's configuration ROM
 282  * @bus_reset:  If non-zero, address of a buffer to be filled by a
 283  *              &struct fw_cdev_event_bus_reset with the current state
 284  *              of the bus.  This does not cause a bus reset to happen.
 285  * @bus_reset_closure: Value of &closure in this and subsequent bus reset events
 286  * @card:       The index of the card this device belongs to
 287  */
 288 struct fw_cdev_get_info {
 289         __u32 version;
 290         __u32 rom_length;
 291         __u64 rom;
 292         __u64 bus_reset;
 293         __u64 bus_reset_closure;
 294         __u32 card;
 295 };
 296
 297 /**
 298  * struct fw_cdev_send_request - Send an asynchronous request packet
 299  * @tcode:      Transaction code of the request
 300  * @length:     Length of outgoing payload, in bytes
 301  * @offset:     48-bit offset at destination node
 302  * @closure:    Passed back to userspace in the response event
 303  * @data:       Userspace pointer to payload
 304  * @generation: The bus generation where packet is valid
 305  *
 306  * Send a request to the device.  This ioctl implements all outgoing requests.
 307  * Both quadlet and block request specify the payload as a pointer to the data
 308  * in the @data field.  Once the transaction completes, the kernel writes an
 309  * &fw_cdev_event_response event back.  The @closure field is passed back to
 310  * user space in the response event.
 311  */
 312 struct fw_cdev_send_request {
 313         __u32 tcode;
 314         __u32 length;
 315         __u64 offset;
 316         __u64 closure;
 317         __u64 data;
 318         __u32 generation;
 319 };
 320
 321 /**
 322  * struct fw_cdev_send_response - Send an asynchronous response packet
 323  * @rcode:      Response code as determined by the userspace handler
 324  * @length:     Length of outgoing payload, in bytes
 325  * @data:       Userspace pointer to payload
 326  * @handle:     The handle from the &fw_cdev_event_request
 327  *
 328  * Send a response to an incoming request.  By setting up an address range using
 329  * the %FW_CDEV_IOC_ALLOCATE ioctl, userspace can listen for incoming requests.  An
 330  * incoming request will generate an %FW_CDEV_EVENT_REQUEST, and userspace must
 331  * send a reply using this ioctl.  The event has a handle to the kernel-side
 332  * pending transaction, which should be used with this ioctl.
 333  */
 334 struct fw_cdev_send_response {
 335         __u32 rcode;
 336         __u32 length;
 337         __u64 data;
 338         __u32 handle;
 339 };
 340
 341 /**
 342  * struct fw_cdev_allocate - Allocate a CSR address range
 343  * @offset:     Start offset of the address range
 344  * @closure:    To be passed back to userspace in request events
 345  * @length:     Length of the address range, in bytes
 346  * @handle:     Handle to the allocation, written by the kernel
 347  *
 348  * Allocate an address range in the 48-bit address space on the local node
 349  * (the controller).  This allows userspace to listen for requests with an
 350  * offset within that address range.  When the kernel receives a request
 351  * within the range, an &fw_cdev_event_request event will be written back.
 352  * The @closure field is passed back to userspace in the response event.
 353  * The @handle field is an out parameter, returning a handle to the allocated
 354  * range to be used for later deallocation of the range.
 355  *
 356  * The address range is allocated on all local nodes.  The address allocation
 357  * is exclusive except for the FCP command and response registers.
 358  */
 359 struct fw_cdev_allocate {
 360         __u64 offset;
 361         __u64 closure;
 362         __u32 length;
 363         __u32 handle;
 364 };
 365
 366 /**
 367  * struct fw_cdev_deallocate - Free a CSR address range or isochronous resource
 368  * @handle:     Handle to the address range or iso resource, as returned by the
 369  *              kernel when the range or resource was allocated
 370  */
 371 struct fw_cdev_deallocate {
 372         __u32 handle;
 373 };
 374
 375 #define FW_CDEV_LONG_RESET      0
 376 #define FW_CDEV_SHORT_RESET     1
 377
 378 /**
 379  * struct fw_cdev_initiate_bus_reset - Initiate a bus reset
 380  * @type:       %FW_CDEV_SHORT_RESET or %FW_CDEV_LONG_RESET
 381  *
 382  * Initiate a bus reset for the bus this device is on.  The bus reset can be
 383  * either the original (long) bus reset or the arbitrated (short) bus reset
 384  * introduced in 1394a-2000.
 385  */
 386 struct fw_cdev_initiate_bus_reset {
 387         __u32 type;     /* FW_CDEV_SHORT_RESET or FW_CDEV_LONG_RESET */
 388 };
 389
 390 /**
 391  * struct fw_cdev_add_descriptor - Add contents to the local node's config ROM
 392  * @immediate:  If non-zero, immediate key to insert before pointer
 393  * @key:        Upper 8 bits of root directory pointer
 394  * @data:       Userspace pointer to contents of descriptor block
 395  * @length:     Length of descriptor block data, in quadlets
 396  * @handle:     Handle to the descriptor, written by the kernel
 397  *
 398  * Add a descriptor block and optionally a preceding immediate key to the local
 399  * node's configuration ROM.
 400  *
 401  * The @key field specifies the upper 8 bits of the descriptor root directory
 402  * pointer and the @data and @length fields specify the contents. The @key
 403  * should be of the form 0xXX000000. The offset part of the root directory entry
 404  * will be filled in by the kernel.
 405  *
 406  * If not 0, the @immediate field specifies an immediate key which will be
 407  * inserted before the root directory pointer.
 408  *
 409  * @immediate, @key, and @data array elements are CPU-endian quadlets.
 410  *
 411  * If successful, the kernel adds the descriptor and writes back a handle to the
 412  * kernel-side object to be used for later removal of the descriptor block and
 413  * immediate key.
 414  *
 415  * This ioctl affects the configuration ROMs of all local nodes.
 416  * The ioctl only succeeds on device files which represent a local node.
 417  */
 418 struct fw_cdev_add_descriptor {
 419         __u32 immediate;
 420         __u32 key;
 421         __u64 data;
 422         __u32 length;
 423         __u32 handle;
 424 };
 425
 426 /**
 427  * struct fw_cdev_remove_descriptor - Remove contents from the configuration ROM
 428  * @handle:     Handle to the descriptor, as returned by the kernel when the
 429  *              descriptor was added
 430  *
 431  * Remove a descriptor block and accompanying immediate key from the local
 432  * nodes' configuration ROMs.
 433  */
 434 struct fw_cdev_remove_descriptor {
 435         __u32 handle;
 436 };
 437
 438 #define FW_CDEV_ISO_CONTEXT_TRANSMIT    0
 439 #define FW_CDEV_ISO_CONTEXT_RECEIVE     1
 440
 441 /**
 442  * struct fw_cdev_create_iso_context - Create a context for isochronous IO
 443  * @type:       %FW_CDEV_ISO_CONTEXT_TRANSMIT or %FW_CDEV_ISO_CONTEXT_RECEIVE
 444  * @header_size: Header size to strip for receive contexts
 445  * @channel:    Channel to bind to
 446  * @speed:      Speed for transmit contexts
 447  * @closure:    To be returned in &fw_cdev_event_iso_interrupt
 448  * @handle:     Handle to context, written back by kernel
 449  *
 450  * Prior to sending or receiving isochronous I/O, a context must be created.
 451  * The context records information about the transmit or receive configuration
 452  * and typically maps to an underlying hardware resource.  A context is set up
 453  * for either sending or receiving.  It is bound to a specific isochronous
 454  * channel.
 455  *
 456  * If a context was successfully created, the kernel writes back a handle to the
 457  * context, which must be passed in for subsequent operations on that context.
 458  *
 459  * For receive contexts, @header_size must be at least 4 and must be a multiple
 460  * of 4.
 461  *
 462  * Note that the effect of a @header_size > 4 depends on
 463  * &fw_cdev_get_info.version, as documented at &fw_cdev_event_iso_interrupt.
 464  */
 465 struct fw_cdev_create_iso_context {
 466         __u32 type;
 467         __u32 header_size;
 468         __u32 channel;
 469         __u32 speed;
 470         __u64 closure;
 471         __u32 handle;
 472 };
 473
 474 #define FW_CDEV_ISO_PAYLOAD_LENGTH(v)   (v)
 475 #define FW_CDEV_ISO_INTERRUPT           (1 << 16)
 476 #define FW_CDEV_ISO_SKIP                (1 << 17)
 477 #define FW_CDEV_ISO_SYNC                (1 << 17)
 478 #define FW_CDEV_ISO_TAG(v)              ((v) << 18)
 479 #define FW_CDEV_ISO_SY(v)               ((v) << 20)
 480 #define FW_CDEV_ISO_HEADER_LENGTH(v)    ((v) << 24)
 481
 482 /**
 483  * struct fw_cdev_iso_packet - Isochronous packet
 484  * @control:    Contains the header length (8 uppermost bits), the sy field
 485  *              (4 bits), the tag field (2 bits), a sync flag (1 bit),
 486  *              a skip flag (1 bit), an interrupt flag (1 bit), and the
 487  *              payload length (16 lowermost bits)
 488  * @header:     Header and payload
 489  *
 490  * &struct fw_cdev_iso_packet is used to describe isochronous packet queues.
 491  *
 492  * Use the FW_CDEV_ISO_ macros to fill in @control.
 493  *
 494  * For transmit packets, the header length must be a multiple of 4 and specifies
 495  * the numbers of bytes in @header that will be prepended to the packet's
 496  * payload; these bytes are copied into the kernel and will not be accessed
 497  * after the ioctl has returned.  The sy and tag fields are copied to the iso
 498  * packet header (these fields are specified by IEEE 1394a and IEC 61883-1).
 499  * The skip flag specifies that no packet is to be sent in a frame; when using
 500  * this, all other fields except the interrupt flag must be zero.
 501  *
 502  * For receive packets, the header length must be a multiple of the context's
 503  * header size; if the header length is larger than the context's header size,
 504  * multiple packets are queued for this entry.  The sy and tag fields are
 505  * ignored.  If the sync flag is set, the context drops all packets until
 506  * a packet with a matching sy field is received (the sync value to wait for is
 507  * specified in the &fw_cdev_start_iso structure).  The payload length defines
 508  * how many payload bytes can be received for one packet (in addition to payload
 509  * quadlets that have been defined as headers and are stripped and returned in
 510  * the &fw_cdev_event_iso_interrupt structure).  If more bytes are received, the
 511  * additional bytes are dropped.  If less bytes are received, the remaining
 512  * bytes in this part of the payload buffer will not be written to, not even by
 513  * the next packet, i.e., packets received in consecutive frames will not
 514  * necessarily be consecutive in memory.  If an entry has queued multiple
 515  * packets, the payload length is divided equally among them.
 516  *
 517  * When a packet with the interrupt flag set has been completed, the
 518  * &fw_cdev_event_iso_interrupt event will be sent.  An entry that has queued
 519  * multiple receive packets is completed when its last packet is completed.
 520  */
 521 struct fw_cdev_iso_packet {
 522         __u32 control;
 523         __u32 header[0];
 524 };
 525
 526 /**
 527  * struct fw_cdev_queue_iso - Queue isochronous packets for I/O
 528  * @packets:    Userspace pointer to packet data
 529  * @data:       Pointer into mmap()'ed payload buffer
 530  * @size:       Size of packet data in bytes
 531  * @handle:     Isochronous context handle
 532  *
 533  * Queue a number of isochronous packets for reception or transmission.
 534  * This ioctl takes a pointer to an array of &fw_cdev_iso_packet structs,
 535  * which describe how to transmit from or receive into a contiguous region
 536  * of a mmap()'ed payload buffer.  As part of transmit packet descriptors,
 537  * a series of headers can be supplied, which will be prepended to the
 538  * payload during DMA.
 539  *
 540  * The kernel may or may not queue all packets, but will write back updated
 541  * values of the @packets, @data and @size fields, so the ioctl can be
 542  * resubmitted easily.
 543  */
 544 struct fw_cdev_queue_iso {
 545         __u64 packets;
 546         __u64 data;
 547         __u32 size;
 548         __u32 handle;
 549 };
 550
 551 #define FW_CDEV_ISO_CONTEXT_MATCH_TAG0           1
 552 #define FW_CDEV_ISO_CONTEXT_MATCH_TAG1           2
 553 #define FW_CDEV_ISO_CONTEXT_MATCH_TAG2           4
 554 #define FW_CDEV_ISO_CONTEXT_MATCH_TAG3           8
 555 #define FW_CDEV_ISO_CONTEXT_MATCH_ALL_TAGS      15
 556
 557 /**
 558  * struct fw_cdev_start_iso - Start an isochronous transmission or reception
 559  * @cycle:      Cycle in which to start I/O.  If @cycle is greater than or
 560  *              equal to 0, the I/O will start on that cycle.
 561  * @sync:       Determines the value to wait for for receive packets that have
 562  *              the %FW_CDEV_ISO_SYNC bit set
 563  * @tags:       Tag filter bit mask.  Only valid for isochronous reception.
 564  *              Determines the tag values for which packets will be accepted.
 565  *              Use FW_CDEV_ISO_CONTEXT_MATCH_ macros to set @tags.
 566  * @handle:     Isochronous context handle within which to transmit or receive
 567  */
 568 struct fw_cdev_start_iso {
 569         __s32 cycle;
 570         __u32 sync;
 571         __u32 tags;
 572         __u32 handle;
 573 };
 574
 575 /**
 576  * struct fw_cdev_stop_iso - Stop an isochronous transmission or reception
 577  * @handle:     Handle of isochronous context to stop
 578  */
 579 struct fw_cdev_stop_iso {
 580         __u32 handle;
 581 };
 582
 583 /**
 584  * struct fw_cdev_get_cycle_timer - read cycle timer register
 585  * @local_time:   system time, in microseconds since the Epoch
 586  * @cycle_timer:  Cycle Time register contents
 587  *
 588  * The %FW_CDEV_IOC_GET_CYCLE_TIMER ioctl reads the isochronous cycle timer
 589  * and also the system clock (%CLOCK_REALTIME).  This allows to express the
 590  * receive time of an isochronous packet as a system time.
 591  *
 592  * @cycle_timer consists of 7 bits cycleSeconds, 13 bits cycleCount, and
 593  * 12 bits cycleOffset, in host byte order.  Cf. the Cycle Time register
 594  * per IEEE 1394 or Isochronous Cycle Timer register per OHCI-1394.
 595  *
 596  * In version 1 and 2 of the ABI, this ioctl returned unreliable (non-
 597  * monotonic) @cycle_timer values on certain controllers.
 598  */
 599 struct fw_cdev_get_cycle_timer {
 600         __u64 local_time;
 601         __u32 cycle_timer;
 602 };
 603
 604 /**
 605  * struct fw_cdev_get_cycle_timer2 - read cycle timer register
 606  * @tv_sec:       system time, seconds
 607  * @tv_nsec:      system time, sub-seconds part in nanoseconds
 608  * @clk_id:       input parameter, clock from which to get the system time
 609  * @cycle_timer:  Cycle Time register contents
 610  *
 611  * The %FW_CDEV_IOC_GET_CYCLE_TIMER2 works like
 612  * %FW_CDEV_IOC_GET_CYCLE_TIMER but lets you choose a clock like with POSIX'
 613  * clock_gettime function.  Supported @clk_id values are POSIX' %CLOCK_REALTIME
 614  * and %CLOCK_MONOTONIC and Linux' %CLOCK_MONOTONIC_RAW.
 615  */
 616 struct fw_cdev_get_cycle_timer2 {
 617         __s64 tv_sec;
 618         __s32 tv_nsec;
 619         __s32 clk_id;
 620         __u32 cycle_timer;
 621 };
 622
 623 /**
 624  * struct fw_cdev_allocate_iso_resource - (De)allocate a channel or bandwidth
 625  * @closure:    Passed back to userspace in correponding iso resource events
 626  * @channels:   Isochronous channels of which one is to be (de)allocated
 627  * @bandwidth:  Isochronous bandwidth units to be (de)allocated
 628  * @handle:     Handle to the allocation, written by the kernel (only valid in
 629  *              case of %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE ioctls)
 630  *
 631  * The %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE ioctl initiates allocation of an
 632  * isochronous channel and/or of isochronous bandwidth at the isochronous
 633  * resource manager (IRM).  Only one of the channels specified in @channels is
 634  * allocated.  An %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED is sent after
 635  * communication with the IRM, indicating success or failure in the event data.
 636  * The kernel will automatically reallocate the resources after bus resets.
 637  * Should a reallocation fail, an %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event
 638  * will be sent.  The kernel will also automatically deallocate the resources
 639  * when the file descriptor is closed.
 640  *
 641  * The %FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE ioctl can be used to initiate
 642  * deallocation of resources which were allocated as described above.
 643  * An %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event concludes this operation.
 644  *
 645  * The %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE ioctl is a variant of allocation
 646  * without automatic re- or deallocation.
 647  * An %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED event concludes this operation,
 648  * indicating success or failure in its data.
 649  *
 650  * The %FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE_ONCE ioctl works like
 651  * %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE except that resources are freed
 652  * instead of allocated.
 653  * An %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event concludes this operation.
 654  *
 655  * To summarize, %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE allocates iso resources
 656  * for the lifetime of the fd or @handle.
 657  * In contrast, %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE allocates iso resources
 658  * for the duration of a bus generation.
 659  *
 660  * @channels is a host-endian bitfield with the least significant bit
 661  * representing channel 0 and the most significant bit representing channel 63:
 662  * 1ULL << c for each channel c that is a candidate for (de)allocation.
 663  *
 664  * @bandwidth is expressed in bandwidth allocation units, i.e. the time to send
 665  * one quadlet of data (payload or header data) at speed S1600.
 666  */
 667 struct fw_cdev_allocate_iso_resource {
 668         __u64 closure;
 669         __u64 channels;
 670         __u32 bandwidth;
 671         __u32 handle;
 672 };
 673
 674 /**
 675  * struct fw_cdev_send_stream_packet - send an asynchronous stream packet
 676  * @length:     Length of outgoing payload, in bytes
 677  * @tag:        Data format tag
 678  * @channel:    Isochronous channel to transmit to
 679  * @sy:         Synchronization code
 680  * @closure:    Passed back to userspace in the response event
 681  * @data:       Userspace pointer to payload
 682  * @generation: The bus generation where packet is valid
 683  * @speed:      Speed to transmit at
 684  *
 685  * The %FW_CDEV_IOC_SEND_STREAM_PACKET ioctl sends an asynchronous stream packet
 686  * to every device which is listening to the specified channel.  The kernel
 687  * writes an &fw_cdev_event_response event which indicates success or failure of
 688  * the transmission.
 689  */
 690 struct fw_cdev_send_stream_packet {
 691         __u32 length;
 692         __u32 tag;
 693         __u32 channel;
 694         __u32 sy;
 695         __u64 closure;
 696         __u64 data;
 697         __u32 generation;
 698         __u32 speed;
 699 };
 700
 701 #endif /* _LINUX_FIREWIRE_CDEV_H */