rcu: remove all rcu head initializations, except on_stack initializations
[linux-2.6.git] / 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 */