xref: /openbmc/linux/include/uapi/linux/firewire-cdev.h (revision 2612e3bbc0386368a850140a6c9b990cd496a5ec)
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  /* available since kernel version 2.6.22 */
34  #define FW_CDEV_EVENT_BUS_RESET				0x00
35  #define FW_CDEV_EVENT_RESPONSE				0x01
36  #define FW_CDEV_EVENT_REQUEST				0x02
37  #define FW_CDEV_EVENT_ISO_INTERRUPT			0x03
38  
39  /* available since kernel version 2.6.30 */
40  #define FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED		0x04
41  #define FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED		0x05
42  
43  /* available since kernel version 2.6.36 */
44  #define FW_CDEV_EVENT_REQUEST2				0x06
45  #define FW_CDEV_EVENT_PHY_PACKET_SENT			0x07
46  #define FW_CDEV_EVENT_PHY_PACKET_RECEIVED		0x08
47  #define FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL	0x09
48  
49  /* available since kernel version 6.5 */
50  #define FW_CDEV_EVENT_REQUEST3				0x0a
51  #define FW_CDEV_EVENT_RESPONSE2				0x0b
52  #define FW_CDEV_EVENT_PHY_PACKET_SENT2			0x0c
53  #define FW_CDEV_EVENT_PHY_PACKET_RECEIVED2		0x0d
54  
55  /**
56   * struct fw_cdev_event_common - Common part of all fw_cdev_event_* types
57   * @closure:	For arbitrary use by userspace
58   * @type:	Discriminates the fw_cdev_event_* types
59   *
60   * This struct may be used to access generic members of all fw_cdev_event_*
61   * types regardless of the specific type.
62   *
63   * Data passed in the @closure field for a request will be returned in the
64   * corresponding event.  It is big enough to hold a pointer on all platforms.
65   * The ioctl used to set @closure depends on the @type of event.
66   */
67  struct fw_cdev_event_common {
68  	__u64 closure;
69  	__u32 type;
70  };
71  
72  /**
73   * struct fw_cdev_event_bus_reset - Sent when a bus reset occurred
74   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_GET_INFO ioctl
75   * @type:	See &fw_cdev_event_common; always %FW_CDEV_EVENT_BUS_RESET
76   * @node_id:       New node ID of this node
77   * @local_node_id: Node ID of the local node, i.e. of the controller
78   * @bm_node_id:    Node ID of the bus manager
79   * @irm_node_id:   Node ID of the iso resource manager
80   * @root_node_id:  Node ID of the root node
81   * @generation:    New bus generation
82   *
83   * This event is sent when the bus the device belongs to goes through a bus
84   * reset.  It provides information about the new bus configuration, such as
85   * new node ID for this device, new root ID, and others.
86   *
87   * If @bm_node_id is 0xffff right after bus reset it can be reread by an
88   * %FW_CDEV_IOC_GET_INFO ioctl after bus manager selection was finished.
89   * Kernels with ABI version < 4 do not set @bm_node_id.
90   */
91  struct fw_cdev_event_bus_reset {
92  	__u64 closure;
93  	__u32 type;
94  	__u32 node_id;
95  	__u32 local_node_id;
96  	__u32 bm_node_id;
97  	__u32 irm_node_id;
98  	__u32 root_node_id;
99  	__u32 generation;
100  };
101  
102  /**
103   * struct fw_cdev_event_response - Sent when a response packet was received
104   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_SEND_REQUEST
105   *		or %FW_CDEV_IOC_SEND_BROADCAST_REQUEST
106   *		or %FW_CDEV_IOC_SEND_STREAM_PACKET ioctl
107   * @type:	See &fw_cdev_event_common; always %FW_CDEV_EVENT_RESPONSE
108   * @rcode:	Response code returned by the remote node
109   * @length:	Data length, i.e. the response's payload size in bytes
110   * @data:	Payload data, if any
111   *
112   * This event is sent instead of &fw_cdev_event_response if the kernel or the client implements
113   * ABI version <= 5. It has the lack of time stamp field comparing to &fw_cdev_event_response2.
114   */
115  struct fw_cdev_event_response {
116  	__u64 closure;
117  	__u32 type;
118  	__u32 rcode;
119  	__u32 length;
120  	__u32 data[];
121  };
122  
123  /**
124   * struct fw_cdev_event_response2 - Sent when a response packet was received
125   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_SEND_REQUEST
126   *		or %FW_CDEV_IOC_SEND_BROADCAST_REQUEST
127   *		or %FW_CDEV_IOC_SEND_STREAM_PACKET ioctl
128   * @type:	See &fw_cdev_event_common; always %FW_CDEV_EVENT_RESPONSE
129   * @rcode:	Response code returned by the remote node
130   * @length:	Data length, i.e. the response's payload size in bytes
131   * @request_tstamp:	The time stamp of isochronous cycle at which the request was sent.
132   * @response_tstamp:	The time stamp of isochronous cycle at which the response was sent.
133   * @padding:	Padding to keep the size of structure as multiples of 8 in various architectures
134   *		since 4 byte alignment is used for 8 byte of object type in System V ABI for i386
135   *		architecture.
136   * @data:	Payload data, if any
137   *
138   * This event is sent when the stack receives a response to an outgoing request
139   * sent by %FW_CDEV_IOC_SEND_REQUEST ioctl.  The payload data for responses
140   * carrying data (read and lock responses) follows immediately and can be
141   * accessed through the @data field.
142   *
143   * The event is also generated after conclusions of transactions that do not
144   * involve response packets.  This includes unified write transactions,
145   * broadcast write transactions, and transmission of asynchronous stream
146   * packets.  @rcode indicates success or failure of such transmissions.
147   *
148   * The value of @request_tstamp expresses the isochronous cycle at which the request was sent to
149   * initiate the transaction. The value of @response_tstamp expresses the isochronous cycle at which
150   * the response arrived to complete the transaction. Each value is unsigned 16 bit integer
151   * containing three low order bits of second field and all 13 bits of cycle field in format of
152   * CYCLE_TIMER register.
153   */
154  struct fw_cdev_event_response2 {
155  	__u64 closure;
156  	__u32 type;
157  	__u32 rcode;
158  	__u32 length;
159  	__u32 request_tstamp;
160  	__u32 response_tstamp;
161  	__u32 padding;
162  	__u32 data[];
163  };
164  
165  /**
166   * struct fw_cdev_event_request - Old version of &fw_cdev_event_request2
167   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl
168   * @type:	See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST
169   * @tcode:	Transaction code of the incoming request
170   * @offset:	The offset into the 48-bit per-node address space
171   * @handle:	Reference to the kernel-side pending request
172   * @length:	Data length, i.e. the request's payload size in bytes
173   * @data:	Incoming data, if any
174   *
175   * This event is sent instead of &fw_cdev_event_request2 if the kernel or
176   * the client implements ABI version <= 3.  &fw_cdev_event_request lacks
177   * essential information; use &fw_cdev_event_request2 instead.
178   */
179  struct fw_cdev_event_request {
180  	__u64 closure;
181  	__u32 type;
182  	__u32 tcode;
183  	__u64 offset;
184  	__u32 handle;
185  	__u32 length;
186  	__u32 data[];
187  };
188  
189  /**
190   * struct fw_cdev_event_request2 - Sent on incoming request to an address region
191   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl
192   * @type:	See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST2
193   * @tcode:	Transaction code of the incoming request
194   * @offset:	The offset into the 48-bit per-node address space
195   * @source_node_id: Sender node ID
196   * @destination_node_id: Destination node ID
197   * @card:	The index of the card from which the request came
198   * @generation:	Bus generation in which the request is valid
199   * @handle:	Reference to the kernel-side pending request
200   * @length:	Data length, i.e. the request's payload size in bytes
201   * @data:	Incoming data, if any
202   *
203   * This event is sent instead of &fw_cdev_event_request3 if the kernel or the client implements
204   * ABI version <= 5. It has the lack of time stamp field comparing to &fw_cdev_event_request3.
205   */
206  struct fw_cdev_event_request2 {
207  	__u64 closure;
208  	__u32 type;
209  	__u32 tcode;
210  	__u64 offset;
211  	__u32 source_node_id;
212  	__u32 destination_node_id;
213  	__u32 card;
214  	__u32 generation;
215  	__u32 handle;
216  	__u32 length;
217  	__u32 data[];
218  };
219  
220  /**
221   * struct fw_cdev_event_request3 - Sent on incoming request to an address region
222   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl
223   * @type:	See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST2
224   * @tcode:	Transaction code of the incoming request
225   * @offset:	The offset into the 48-bit per-node address space
226   * @source_node_id: Sender node ID
227   * @destination_node_id: Destination node ID
228   * @card:	The index of the card from which the request came
229   * @generation:	Bus generation in which the request is valid
230   * @handle:	Reference to the kernel-side pending request
231   * @length:	Data length, i.e. the request's payload size in bytes
232   * @tstamp:	The time stamp of isochronous cycle at which the request arrived.
233   * @padding:	Padding to keep the size of structure as multiples of 8 in various architectures
234   *		since 4 byte alignment is used for 8 byte of object type in System V ABI for i386
235   *		architecture.
236   * @data:	Incoming data, if any
237   *
238   * This event is sent when the stack receives an incoming request to an address
239   * region registered using the %FW_CDEV_IOC_ALLOCATE ioctl.  The request is
240   * guaranteed to be completely contained in the specified region.  Userspace is
241   * responsible for sending the response by %FW_CDEV_IOC_SEND_RESPONSE ioctl,
242   * using the same @handle.
243   *
244   * The payload data for requests carrying data (write and lock requests)
245   * follows immediately and can be accessed through the @data field.
246   *
247   * Unlike &fw_cdev_event_request, @tcode of lock requests is one of the
248   * firewire-core specific %TCODE_LOCK_MASK_SWAP...%TCODE_LOCK_VENDOR_DEPENDENT,
249   * i.e. encodes the extended transaction code.
250   *
251   * @card may differ from &fw_cdev_get_info.card because requests are received
252   * from all cards of the Linux host.  @source_node_id, @destination_node_id, and
253   * @generation pertain to that card.  Destination node ID and bus generation may
254   * therefore differ from the corresponding fields of the last
255   * &fw_cdev_event_bus_reset.
256   *
257   * @destination_node_id may also differ from the current node ID because of a
258   * non-local bus ID part or in case of a broadcast write request.  Note, a
259   * client must call an %FW_CDEV_IOC_SEND_RESPONSE ioctl even in case of a
260   * broadcast write request; the kernel will then release the kernel-side pending
261   * request but will not actually send a response packet.
262   *
263   * In case of a write request to FCP_REQUEST or FCP_RESPONSE, the kernel already
264   * sent a write response immediately after the request was received; in this
265   * case the client must still call an %FW_CDEV_IOC_SEND_RESPONSE ioctl to
266   * release the kernel-side pending request, though another response won't be
267   * sent.
268   *
269   * If the client subsequently needs to initiate requests to the sender node of
270   * an &fw_cdev_event_request3, it needs to use a device file with matching
271   * card index, node ID, and generation for outbound requests.
272   *
273   * @tstamp is isochronous cycle at which the request arrived. It is 16 bit integer value and the
274   * higher 3 bits expresses three low order bits of second field in the format of CYCLE_TIME
275   * register and the rest 13 bits expresses cycle field.
276   */
277  struct fw_cdev_event_request3 {
278  	__u64 closure;
279  	__u32 type;
280  	__u32 tcode;
281  	__u64 offset;
282  	__u32 source_node_id;
283  	__u32 destination_node_id;
284  	__u32 card;
285  	__u32 generation;
286  	__u32 handle;
287  	__u32 length;
288  	__u32 tstamp;
289  	__u32 padding;
290  	__u32 data[];
291  };
292  
293  /**
294   * struct fw_cdev_event_iso_interrupt - Sent when an iso packet was completed
295   * @closure:	See &fw_cdev_event_common;
296   *		set by %FW_CDEV_CREATE_ISO_CONTEXT ioctl
297   * @type:	See &fw_cdev_event_common; always %FW_CDEV_EVENT_ISO_INTERRUPT
298   * @cycle:	Cycle counter of the last completed packet
299   * @header_length: Total length of following headers, in bytes
300   * @header:	Stripped headers, if any
301   *
302   * This event is sent when the controller has completed an &fw_cdev_iso_packet
303   * with the %FW_CDEV_ISO_INTERRUPT bit set, when explicitly requested with
304   * %FW_CDEV_IOC_FLUSH_ISO, or when there have been so many completed packets
305   * without the interrupt bit set that the kernel's internal buffer for @header
306   * is about to overflow.  (In the last case, ABI versions < 5 drop header data
307   * up to the next interrupt packet.)
308   *
309   * Isochronous transmit events (context type %FW_CDEV_ISO_CONTEXT_TRANSMIT):
310   *
311   * In version 3 and some implementations of version 2 of the ABI, &header_length
312   * is a multiple of 4 and &header contains timestamps of all packets up until
313   * the interrupt packet.  The format of the timestamps is as described below for
314   * isochronous reception.  In version 1 of the ABI, &header_length was 0.
315   *
316   * Isochronous receive events (context type %FW_CDEV_ISO_CONTEXT_RECEIVE):
317   *
318   * The headers stripped of all packets up until and including the interrupt
319   * packet are returned in the @header field.  The amount of header data per
320   * packet is as specified at iso context creation by
321   * &fw_cdev_create_iso_context.header_size.
322   *
323   * Hence, _interrupt.header_length / _context.header_size is the number of
324   * packets received in this interrupt event.  The client can now iterate
325   * through the mmap()'ed DMA buffer according to this number of packets and
326   * to the buffer sizes as the client specified in &fw_cdev_queue_iso.
327   *
328   * Since version 2 of this ABI, the portion for each packet in _interrupt.header
329   * consists of the 1394 isochronous packet header, followed by a timestamp
330   * quadlet if &fw_cdev_create_iso_context.header_size > 4, followed by quadlets
331   * from the packet payload if &fw_cdev_create_iso_context.header_size > 8.
332   *
333   * Format of 1394 iso packet header:  16 bits data_length, 2 bits tag, 6 bits
334   * channel, 4 bits tcode, 4 bits sy, in big endian byte order.
335   * data_length is the actual received size of the packet without the four
336   * 1394 iso packet header bytes.
337   *
338   * Format of timestamp:  16 bits invalid, 3 bits cycleSeconds, 13 bits
339   * cycleCount, in big endian byte order.
340   *
341   * In version 1 of the ABI, no timestamp quadlet was inserted; instead, payload
342   * data followed directly after the 1394 is header if header_size > 4.
343   * Behaviour of ver. 1 of this ABI is no longer available since ABI ver. 2.
344   */
345  struct fw_cdev_event_iso_interrupt {
346  	__u64 closure;
347  	__u32 type;
348  	__u32 cycle;
349  	__u32 header_length;
350  	__u32 header[];
351  };
352  
353  /**
354   * struct fw_cdev_event_iso_interrupt_mc - An iso buffer chunk was completed
355   * @closure:	See &fw_cdev_event_common;
356   *		set by %FW_CDEV_CREATE_ISO_CONTEXT ioctl
357   * @type:	%FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL
358   * @completed:	Offset into the receive buffer; data before this offset is valid
359   *
360   * This event is sent in multichannel contexts (context type
361   * %FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL) for &fw_cdev_iso_packet buffer
362   * chunks that have been completely filled and that have the
363   * %FW_CDEV_ISO_INTERRUPT bit set, or when explicitly requested with
364   * %FW_CDEV_IOC_FLUSH_ISO.
365   *
366   * The buffer is continuously filled with the following data, per packet:
367   *  - the 1394 iso packet header as described at &fw_cdev_event_iso_interrupt,
368   *    but in little endian byte order,
369   *  - packet payload (as many bytes as specified in the data_length field of
370   *    the 1394 iso packet header) in big endian byte order,
371   *  - 0...3 padding bytes as needed to align the following trailer quadlet,
372   *  - trailer quadlet, containing the reception timestamp as described at
373   *    &fw_cdev_event_iso_interrupt, but in little endian byte order.
374   *
375   * Hence the per-packet size is data_length (rounded up to a multiple of 4) + 8.
376   * When processing the data, stop before a packet that would cross the
377   * @completed offset.
378   *
379   * A packet near the end of a buffer chunk will typically spill over into the
380   * next queued buffer chunk.  It is the responsibility of the client to check
381   * for this condition, assemble a broken-up packet from its parts, and not to
382   * re-queue any buffer chunks in which as yet unread packet parts reside.
383   */
384  struct fw_cdev_event_iso_interrupt_mc {
385  	__u64 closure;
386  	__u32 type;
387  	__u32 completed;
388  };
389  
390  /**
391   * struct fw_cdev_event_iso_resource - Iso resources were allocated or freed
392   * @closure:	See &fw_cdev_event_common;
393   *		set by``FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE)`` ioctl
394   * @type:	%FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or
395   *		%FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED
396   * @handle:	Reference by which an allocated resource can be deallocated
397   * @channel:	Isochronous channel which was (de)allocated, if any
398   * @bandwidth:	Bandwidth allocation units which were (de)allocated, if any
399   *
400   * An %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED event is sent after an isochronous
401   * resource was allocated at the IRM.  The client has to check @channel and
402   * @bandwidth for whether the allocation actually succeeded.
403   *
404   * An %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event is sent after an isochronous
405   * resource was deallocated at the IRM.  It is also sent when automatic
406   * reallocation after a bus reset failed.
407   *
408   * @channel is <0 if no channel was (de)allocated or if reallocation failed.
409   * @bandwidth is 0 if no bandwidth was (de)allocated or if reallocation failed.
410   */
411  struct fw_cdev_event_iso_resource {
412  	__u64 closure;
413  	__u32 type;
414  	__u32 handle;
415  	__s32 channel;
416  	__s32 bandwidth;
417  };
418  
419  /**
420   * struct fw_cdev_event_phy_packet - A PHY packet was transmitted or received
421   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_SEND_PHY_PACKET
422   *		or %FW_CDEV_IOC_RECEIVE_PHY_PACKETS ioctl
423   * @type:	%FW_CDEV_EVENT_PHY_PACKET_SENT or %..._RECEIVED
424   * @rcode:	%RCODE_..., indicates success or failure of transmission
425   * @length:	Data length in bytes
426   * @data:	Incoming data for %FW_CDEV_IOC_RECEIVE_PHY_PACKETS. For %FW_CDEV_IOC_SEND_PHY_PACKET
427   *		the field has the same data in the request, thus the length of 8 bytes.
428   *
429   * This event is sent instead of &fw_cdev_event_phy_packet2 if the kernel or
430   * the client implements ABI version <= 5. It has the lack of time stamp field comparing to
431   * &fw_cdev_event_phy_packet2.
432   */
433  struct fw_cdev_event_phy_packet {
434  	__u64 closure;
435  	__u32 type;
436  	__u32 rcode;
437  	__u32 length;
438  	__u32 data[];
439  };
440  
441  /**
442   * struct fw_cdev_event_phy_packet2 - A PHY packet was transmitted or received with time stamp.
443   * @closure:	See &fw_cdev_event_common; set by %FW_CDEV_IOC_SEND_PHY_PACKET
444   *		or %FW_CDEV_IOC_RECEIVE_PHY_PACKETS ioctl
445   * @type:	%FW_CDEV_EVENT_PHY_PACKET_SENT2 or %FW_CDEV_EVENT_PHY_PACKET_RECEIVED2
446   * @rcode:	%RCODE_..., indicates success or failure of transmission
447   * @length:	Data length in bytes
448   * @tstamp:	For %FW_CDEV_EVENT_PHY_PACKET_RECEIVED2, the time stamp of isochronous cycle at
449   *		which the packet arrived. For %FW_CDEV_EVENT_PHY_PACKET_SENT2 and non-ping packet,
450   *		the time stamp of isochronous cycle at which the packet was sent. For ping packet,
451   *		the tick count for round-trip time measured by 1394 OHCI controller.
452   * The time stamp of isochronous cycle at which either the response was sent for
453   *		%FW_CDEV_EVENT_PHY_PACKET_SENT2 or the request arrived for
454   *		%FW_CDEV_EVENT_PHY_PACKET_RECEIVED2.
455   * @data:	Incoming data
456   *
457   * If @type is %FW_CDEV_EVENT_PHY_PACKET_SENT2, @length is 8 and @data consists of the two PHY
458   * packet quadlets to be sent, in host byte order,
459   *
460   * If @type is %FW_CDEV_EVENT_PHY_PACKET_RECEIVED2, @length is 8 and @data consists of the two PHY
461   * packet quadlets, in host byte order.
462   *
463   * For %FW_CDEV_EVENT_PHY_PACKET_RECEIVED2, the @tstamp is the isochronous cycle at which the
464   * packet arrived. It is 16 bit integer value and the higher 3 bits expresses three low order bits
465   * of second field and the rest 13 bits expresses cycle field in the format of CYCLE_TIME register.
466   *
467   * For %FW_CDEV_EVENT_PHY_PACKET_SENT2, the @tstamp has different meanings whether to sent the
468   * packet for ping or not. If it's not for ping, the @tstamp is the isochronous cycle at which the
469   * packet was sent, and use the same format as the case of %FW_CDEV_EVENT_PHY_PACKET_SENT2. If it's
470   * for ping, the @tstamp is for round-trip time measured by 1394 OHCI controller with 42.195 MHz
471   * resolution.
472   */
473  struct fw_cdev_event_phy_packet2 {
474  	__u64 closure;
475  	__u32 type;
476  	__u32 rcode;
477  	__u32 length;
478  	__u32 tstamp;
479  	__u32 data[];
480  };
481  
482  /**
483   * union fw_cdev_event - Convenience union of fw_cdev_event_* types
484   * @common:		Valid for all types
485   * @bus_reset:		Valid if @common.type == %FW_CDEV_EVENT_BUS_RESET
486   * @response:		Valid if @common.type == %FW_CDEV_EVENT_RESPONSE
487   * @request:		Valid if @common.type == %FW_CDEV_EVENT_REQUEST
488   * @request2:		Valid if @common.type == %FW_CDEV_EVENT_REQUEST2
489   * @iso_interrupt:	Valid if @common.type == %FW_CDEV_EVENT_ISO_INTERRUPT
490   * @iso_interrupt_mc:	Valid if @common.type ==
491   *				%FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL
492   * @iso_resource:	Valid if @common.type ==
493   *				%FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED or
494   *				%FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED
495   * @phy_packet:		Valid if @common.type ==
496   *				%FW_CDEV_EVENT_PHY_PACKET_SENT or
497   *				%FW_CDEV_EVENT_PHY_PACKET_RECEIVED
498   *
499   * @request3:		Valid if @common.type == %FW_CDEV_EVENT_REQUEST3
500   * @response2:		Valid if @common.type == %FW_CDEV_EVENT_RESPONSE2
501   * @phy_packet2:	Valid if @common.type == %FW_CDEV_EVENT_PHY_PACKET_SENT2 or
502   *				%FW_CDEV_EVENT_PHY_PACKET_RECEIVED2
503   *
504   * Convenience union for userspace use.  Events could be read(2) into an
505   * appropriately aligned char buffer and then cast to this union for further
506   * processing.  Note that for a request, response or iso_interrupt event,
507   * the data[] or header[] may make the size of the full event larger than
508   * sizeof(union fw_cdev_event).  Also note that if you attempt to read(2)
509   * an event into a buffer that is not large enough for it, the data that does
510   * not fit will be discarded so that the next read(2) will return a new event.
511   */
512  union fw_cdev_event {
513  	struct fw_cdev_event_common		common;
514  	struct fw_cdev_event_bus_reset		bus_reset;
515  	struct fw_cdev_event_response		response;
516  	struct fw_cdev_event_request		request;
517  	struct fw_cdev_event_request2		request2;		/* added in 2.6.36 */
518  	struct fw_cdev_event_iso_interrupt	iso_interrupt;
519  	struct fw_cdev_event_iso_interrupt_mc	iso_interrupt_mc;	/* added in 2.6.36 */
520  	struct fw_cdev_event_iso_resource	iso_resource;		/* added in 2.6.30 */
521  	struct fw_cdev_event_phy_packet		phy_packet;		/* added in 2.6.36 */
522  	struct fw_cdev_event_request3		request3;		/* added in 6.5 */
523  	struct fw_cdev_event_response2		response2;		/* added in 6.5 */
524  	struct fw_cdev_event_phy_packet2	phy_packet2;		/* added in 6.5 */
525  };
526  
527  /* available since kernel version 2.6.22 */
528  #define FW_CDEV_IOC_GET_INFO           _IOWR('#', 0x00, struct fw_cdev_get_info)
529  #define FW_CDEV_IOC_SEND_REQUEST        _IOW('#', 0x01, struct fw_cdev_send_request)
530  #define FW_CDEV_IOC_ALLOCATE           _IOWR('#', 0x02, struct fw_cdev_allocate)
531  #define FW_CDEV_IOC_DEALLOCATE          _IOW('#', 0x03, struct fw_cdev_deallocate)
532  #define FW_CDEV_IOC_SEND_RESPONSE       _IOW('#', 0x04, struct fw_cdev_send_response)
533  #define FW_CDEV_IOC_INITIATE_BUS_RESET  _IOW('#', 0x05, struct fw_cdev_initiate_bus_reset)
534  #define FW_CDEV_IOC_ADD_DESCRIPTOR     _IOWR('#', 0x06, struct fw_cdev_add_descriptor)
535  #define FW_CDEV_IOC_REMOVE_DESCRIPTOR   _IOW('#', 0x07, struct fw_cdev_remove_descriptor)
536  #define FW_CDEV_IOC_CREATE_ISO_CONTEXT _IOWR('#', 0x08, struct fw_cdev_create_iso_context)
537  #define FW_CDEV_IOC_QUEUE_ISO          _IOWR('#', 0x09, struct fw_cdev_queue_iso)
538  #define FW_CDEV_IOC_START_ISO           _IOW('#', 0x0a, struct fw_cdev_start_iso)
539  #define FW_CDEV_IOC_STOP_ISO            _IOW('#', 0x0b, struct fw_cdev_stop_iso)
540  
541  /* available since kernel version 2.6.24 */
542  #define FW_CDEV_IOC_GET_CYCLE_TIMER     _IOR('#', 0x0c, struct fw_cdev_get_cycle_timer)
543  
544  /* available since kernel version 2.6.30 */
545  #define FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE       _IOWR('#', 0x0d, struct fw_cdev_allocate_iso_resource)
546  #define FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE      _IOW('#', 0x0e, struct fw_cdev_deallocate)
547  #define FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE   _IOW('#', 0x0f, struct fw_cdev_allocate_iso_resource)
548  #define FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE_ONCE _IOW('#', 0x10, struct fw_cdev_allocate_iso_resource)
549  #define FW_CDEV_IOC_GET_SPEED                     _IO('#', 0x11) /* returns speed code */
550  #define FW_CDEV_IOC_SEND_BROADCAST_REQUEST       _IOW('#', 0x12, struct fw_cdev_send_request)
551  #define FW_CDEV_IOC_SEND_STREAM_PACKET           _IOW('#', 0x13, struct fw_cdev_send_stream_packet)
552  
553  /* available since kernel version 2.6.34 */
554  #define FW_CDEV_IOC_GET_CYCLE_TIMER2   _IOWR('#', 0x14, struct fw_cdev_get_cycle_timer2)
555  
556  /* available since kernel version 2.6.36 */
557  #define FW_CDEV_IOC_SEND_PHY_PACKET    _IOWR('#', 0x15, struct fw_cdev_send_phy_packet)
558  #define FW_CDEV_IOC_RECEIVE_PHY_PACKETS _IOW('#', 0x16, struct fw_cdev_receive_phy_packets)
559  #define FW_CDEV_IOC_SET_ISO_CHANNELS    _IOW('#', 0x17, struct fw_cdev_set_iso_channels)
560  
561  /* available since kernel version 3.4 */
562  #define FW_CDEV_IOC_FLUSH_ISO           _IOW('#', 0x18, struct fw_cdev_flush_iso)
563  
564  /*
565   * ABI version history
566   *  1  (2.6.22)  - initial version
567   *     (2.6.24)  - added %FW_CDEV_IOC_GET_CYCLE_TIMER
568   *  2  (2.6.30)  - changed &fw_cdev_event_iso_interrupt.header if
569   *                 &fw_cdev_create_iso_context.header_size is 8 or more
570   *               - added %FW_CDEV_IOC_*_ISO_RESOURCE*,
571   *                 %FW_CDEV_IOC_GET_SPEED, %FW_CDEV_IOC_SEND_BROADCAST_REQUEST,
572   *                 %FW_CDEV_IOC_SEND_STREAM_PACKET
573   *     (2.6.32)  - added time stamp to xmit &fw_cdev_event_iso_interrupt
574   *     (2.6.33)  - IR has always packet-per-buffer semantics now, not one of
575   *                 dual-buffer or packet-per-buffer depending on hardware
576   *               - shared use and auto-response for FCP registers
577   *  3  (2.6.34)  - made &fw_cdev_get_cycle_timer reliable
578   *               - added %FW_CDEV_IOC_GET_CYCLE_TIMER2
579   *  4  (2.6.36)  - added %FW_CDEV_EVENT_REQUEST2, %FW_CDEV_EVENT_PHY_PACKET_*,
580   *                 and &fw_cdev_allocate.region_end
581   *               - implemented &fw_cdev_event_bus_reset.bm_node_id
582   *               - added %FW_CDEV_IOC_SEND_PHY_PACKET, _RECEIVE_PHY_PACKETS
583   *               - added %FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL,
584   *                 %FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL, and
585   *                 %FW_CDEV_IOC_SET_ISO_CHANNELS
586   *  5  (3.4)     - send %FW_CDEV_EVENT_ISO_INTERRUPT events when needed to
587   *                 avoid dropping data
588   *               - added %FW_CDEV_IOC_FLUSH_ISO
589   *  6  (6.5)     - added some event for subactions of asynchronous transaction with time stamp
590   *                   - %FW_CDEV_EVENT_REQUEST3
591   *                   - %FW_CDEV_EVENT_RESPONSE2
592   *                   - %FW_CDEV_EVENT_PHY_PACKET_SENT2
593   *                   - %FW_CDEV_EVENT_PHY_PACKET_RECEIVED2
594   */
595  
596  /**
597   * struct fw_cdev_get_info - General purpose information ioctl
598   * @version:	The version field is just a running serial number.  Both an
599   *		input parameter (ABI version implemented by the client) and
600   *		output parameter (ABI version implemented by the kernel).
601   *		A client shall fill in the ABI @version for which the client
602   *		was implemented.  This is necessary for forward compatibility.
603   * @rom_length:	If @rom is non-zero, up to @rom_length bytes of Configuration
604   *		ROM will be copied into that user space address.  In either
605   *		case, @rom_length is updated with the actual length of the
606   *		Configuration ROM.
607   * @rom:	If non-zero, address of a buffer to be filled by a copy of the
608   *		device's Configuration ROM
609   * @bus_reset:	If non-zero, address of a buffer to be filled by a
610   *		&struct fw_cdev_event_bus_reset with the current state
611   *		of the bus.  This does not cause a bus reset to happen.
612   * @bus_reset_closure: Value of &closure in this and subsequent bus reset events
613   * @card:	The index of the card this device belongs to
614   *
615   * The %FW_CDEV_IOC_GET_INFO ioctl is usually the very first one which a client
616   * performs right after it opened a /dev/fw* file.
617   *
618   * As a side effect, reception of %FW_CDEV_EVENT_BUS_RESET events to be read(2)
619   * is started by this ioctl.
620   */
621  struct fw_cdev_get_info {
622  	__u32 version;
623  	__u32 rom_length;
624  	__u64 rom;
625  	__u64 bus_reset;
626  	__u64 bus_reset_closure;
627  	__u32 card;
628  };
629  
630  /**
631   * struct fw_cdev_send_request - Send an asynchronous request packet
632   * @tcode:	Transaction code of the request
633   * @length:	Length of outgoing payload, in bytes
634   * @offset:	48-bit offset at destination node
635   * @closure:	Passed back to userspace in the response event
636   * @data:	Userspace pointer to payload
637   * @generation:	The bus generation where packet is valid
638   *
639   * Send a request to the device.  This ioctl implements all outgoing requests. Both quadlet and
640   * block request specify the payload as a pointer to the data in the @data field. Once the
641   * transaction completes, the kernel writes either &fw_cdev_event_response event or
642   * &fw_cdev_event_response event back. The @closure field is passed back to user space in the
643   * response event.
644   */
645  struct fw_cdev_send_request {
646  	__u32 tcode;
647  	__u32 length;
648  	__u64 offset;
649  	__u64 closure;
650  	__u64 data;
651  	__u32 generation;
652  };
653  
654  /**
655   * struct fw_cdev_send_response - Send an asynchronous response packet
656   * @rcode:	Response code as determined by the userspace handler
657   * @length:	Length of outgoing payload, in bytes
658   * @data:	Userspace pointer to payload
659   * @handle:	The handle from the &fw_cdev_event_request
660   *
661   * Send a response to an incoming request.  By setting up an address range using
662   * the %FW_CDEV_IOC_ALLOCATE ioctl, userspace can listen for incoming requests.  An
663   * incoming request will generate an %FW_CDEV_EVENT_REQUEST, and userspace must
664   * send a reply using this ioctl.  The event has a handle to the kernel-side
665   * pending transaction, which should be used with this ioctl.
666   */
667  struct fw_cdev_send_response {
668  	__u32 rcode;
669  	__u32 length;
670  	__u64 data;
671  	__u32 handle;
672  };
673  
674  /**
675   * struct fw_cdev_allocate - Allocate a CSR in an address range
676   * @offset:	Start offset of the address range
677   * @closure:	To be passed back to userspace in request events
678   * @length:	Length of the CSR, in bytes
679   * @handle:	Handle to the allocation, written by the kernel
680   * @region_end:	First address above the address range (added in ABI v4, 2.6.36)
681   *
682   * Allocate an address range in the 48-bit address space on the local node
683   * (the controller).  This allows userspace to listen for requests with an
684   * offset within that address range.  Every time when the kernel receives a
685   * request within the range, an &fw_cdev_event_request2 event will be emitted.
686   * (If the kernel or the client implements ABI version <= 3, an
687   * &fw_cdev_event_request will be generated instead.)
688   *
689   * The @closure field is passed back to userspace in these request events.
690   * The @handle field is an out parameter, returning a handle to the allocated
691   * range to be used for later deallocation of the range.
692   *
693   * The address range is allocated on all local nodes.  The address allocation
694   * is exclusive except for the FCP command and response registers.  If an
695   * exclusive address region is already in use, the ioctl fails with errno set
696   * to %EBUSY.
697   *
698   * If kernel and client implement ABI version >= 4, the kernel looks up a free
699   * spot of size @length inside [@offset..@region_end) and, if found, writes
700   * the start address of the new CSR back in @offset.  I.e. @offset is an
701   * in and out parameter.  If this automatic placement of a CSR in a bigger
702   * address range is not desired, the client simply needs to set @region_end
703   * = @offset + @length.
704   *
705   * If the kernel or the client implements ABI version <= 3, @region_end is
706   * ignored and effectively assumed to be @offset + @length.
707   *
708   * @region_end is only present in a kernel header >= 2.6.36.  If necessary,
709   * this can for example be tested by #ifdef FW_CDEV_EVENT_REQUEST2.
710   */
711  struct fw_cdev_allocate {
712  	__u64 offset;
713  	__u64 closure;
714  	__u32 length;
715  	__u32 handle;
716  	__u64 region_end;	/* available since kernel version 2.6.36 */
717  };
718  
719  /**
720   * struct fw_cdev_deallocate - Free a CSR address range or isochronous resource
721   * @handle:	Handle to the address range or iso resource, as returned by the
722   *		kernel when the range or resource was allocated
723   */
724  struct fw_cdev_deallocate {
725  	__u32 handle;
726  };
727  
728  #define FW_CDEV_LONG_RESET	0
729  #define FW_CDEV_SHORT_RESET	1
730  
731  /**
732   * struct fw_cdev_initiate_bus_reset - Initiate a bus reset
733   * @type:	%FW_CDEV_SHORT_RESET or %FW_CDEV_LONG_RESET
734   *
735   * Initiate a bus reset for the bus this device is on.  The bus reset can be
736   * either the original (long) bus reset or the arbitrated (short) bus reset
737   * introduced in 1394a-2000.
738   *
739   * The ioctl returns immediately.  A subsequent &fw_cdev_event_bus_reset
740   * indicates when the reset actually happened.  Since ABI v4, this may be
741   * considerably later than the ioctl because the kernel ensures a grace period
742   * between subsequent bus resets as per IEEE 1394 bus management specification.
743   */
744  struct fw_cdev_initiate_bus_reset {
745  	__u32 type;
746  };
747  
748  /**
749   * struct fw_cdev_add_descriptor - Add contents to the local node's config ROM
750   * @immediate:	If non-zero, immediate key to insert before pointer
751   * @key:	Upper 8 bits of root directory pointer
752   * @data:	Userspace pointer to contents of descriptor block
753   * @length:	Length of descriptor block data, in quadlets
754   * @handle:	Handle to the descriptor, written by the kernel
755   *
756   * Add a descriptor block and optionally a preceding immediate key to the local
757   * node's Configuration ROM.
758   *
759   * The @key field specifies the upper 8 bits of the descriptor root directory
760   * pointer and the @data and @length fields specify the contents. The @key
761   * should be of the form 0xXX000000. The offset part of the root directory entry
762   * will be filled in by the kernel.
763   *
764   * If not 0, the @immediate field specifies an immediate key which will be
765   * inserted before the root directory pointer.
766   *
767   * @immediate, @key, and @data array elements are CPU-endian quadlets.
768   *
769   * If successful, the kernel adds the descriptor and writes back a @handle to
770   * the kernel-side object to be used for later removal of the descriptor block
771   * and immediate key.  The kernel will also generate a bus reset to signal the
772   * change of the Configuration ROM to other nodes.
773   *
774   * This ioctl affects the Configuration ROMs of all local nodes.
775   * The ioctl only succeeds on device files which represent a local node.
776   */
777  struct fw_cdev_add_descriptor {
778  	__u32 immediate;
779  	__u32 key;
780  	__u64 data;
781  	__u32 length;
782  	__u32 handle;
783  };
784  
785  /**
786   * struct fw_cdev_remove_descriptor - Remove contents from the Configuration ROM
787   * @handle:	Handle to the descriptor, as returned by the kernel when the
788   *		descriptor was added
789   *
790   * Remove a descriptor block and accompanying immediate key from the local
791   * nodes' Configuration ROMs.  The kernel will also generate a bus reset to
792   * signal the change of the Configuration ROM to other nodes.
793   */
794  struct fw_cdev_remove_descriptor {
795  	__u32 handle;
796  };
797  
798  #define FW_CDEV_ISO_CONTEXT_TRANSMIT			0
799  #define FW_CDEV_ISO_CONTEXT_RECEIVE			1
800  #define FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL	2 /* added in 2.6.36 */
801  
802  /**
803   * struct fw_cdev_create_iso_context - Create a context for isochronous I/O
804   * @type:	%FW_CDEV_ISO_CONTEXT_TRANSMIT or %FW_CDEV_ISO_CONTEXT_RECEIVE or
805   *		%FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL
806   * @header_size: Header size to strip in single-channel reception
807   * @channel:	Channel to bind to in single-channel reception or transmission
808   * @speed:	Transmission speed
809   * @closure:	To be returned in &fw_cdev_event_iso_interrupt or
810   *		&fw_cdev_event_iso_interrupt_multichannel
811   * @handle:	Handle to context, written back by kernel
812   *
813   * Prior to sending or receiving isochronous I/O, a context must be created.
814   * The context records information about the transmit or receive configuration
815   * and typically maps to an underlying hardware resource.  A context is set up
816   * for either sending or receiving.  It is bound to a specific isochronous
817   * @channel.
818   *
819   * In case of multichannel reception, @header_size and @channel are ignored
820   * and the channels are selected by %FW_CDEV_IOC_SET_ISO_CHANNELS.
821   *
822   * For %FW_CDEV_ISO_CONTEXT_RECEIVE contexts, @header_size must be at least 4
823   * and must be a multiple of 4.  It is ignored in other context types.
824   *
825   * @speed is ignored in receive context types.
826   *
827   * If a context was successfully created, the kernel writes back a handle to the
828   * context, which must be passed in for subsequent operations on that context.
829   *
830   * Limitations:
831   * No more than one iso context can be created per fd.
832   * The total number of contexts that all userspace and kernelspace drivers can
833   * create on a card at a time is a hardware limit, typically 4 or 8 contexts per
834   * direction, and of them at most one multichannel receive context.
835   */
836  struct fw_cdev_create_iso_context {
837  	__u32 type;
838  	__u32 header_size;
839  	__u32 channel;
840  	__u32 speed;
841  	__u64 closure;
842  	__u32 handle;
843  };
844  
845  /**
846   * struct fw_cdev_set_iso_channels - Select channels in multichannel reception
847   * @channels:	Bitmask of channels to listen to
848   * @handle:	Handle of the mutichannel receive context
849   *
850   * @channels is the bitwise or of 1ULL << n for each channel n to listen to.
851   *
852   * The ioctl fails with errno %EBUSY if there is already another receive context
853   * on a channel in @channels.  In that case, the bitmask of all unoccupied
854   * channels is returned in @channels.
855   */
856  struct fw_cdev_set_iso_channels {
857  	__u64 channels;
858  	__u32 handle;
859  };
860  
861  #define FW_CDEV_ISO_PAYLOAD_LENGTH(v)	(v)
862  #define FW_CDEV_ISO_INTERRUPT		(1 << 16)
863  #define FW_CDEV_ISO_SKIP		(1 << 17)
864  #define FW_CDEV_ISO_SYNC		(1 << 17)
865  #define FW_CDEV_ISO_TAG(v)		((v) << 18)
866  #define FW_CDEV_ISO_SY(v)		((v) << 20)
867  #define FW_CDEV_ISO_HEADER_LENGTH(v)	((v) << 24)
868  
869  /**
870   * struct fw_cdev_iso_packet - Isochronous packet
871   * @control:	Contains the header length (8 uppermost bits),
872   *		the sy field (4 bits), the tag field (2 bits), a sync flag
873   *		or a skip flag (1 bit), an interrupt flag (1 bit), and the
874   *		payload length (16 lowermost bits)
875   * @header:	Header and payload in case of a transmit context.
876   *
877   * &struct fw_cdev_iso_packet is used to describe isochronous packet queues.
878   * Use the FW_CDEV_ISO_* macros to fill in @control.
879   * The @header array is empty in case of receive contexts.
880   *
881   * Context type %FW_CDEV_ISO_CONTEXT_TRANSMIT:
882   *
883   * @control.HEADER_LENGTH must be a multiple of 4.  It specifies the numbers of
884   * bytes in @header that will be prepended to the packet's payload.  These bytes
885   * are copied into the kernel and will not be accessed after the ioctl has
886   * returned.
887   *
888   * The @control.SY and TAG fields are copied to the iso packet header.  These
889   * fields are specified by IEEE 1394a and IEC 61883-1.
890   *
891   * The @control.SKIP flag specifies that no packet is to be sent in a frame.
892   * When using this, all other fields except @control.INTERRUPT must be zero.
893   *
894   * When a packet with the @control.INTERRUPT flag set has been completed, an
895   * &fw_cdev_event_iso_interrupt event will be sent.
896   *
897   * Context type %FW_CDEV_ISO_CONTEXT_RECEIVE:
898   *
899   * @control.HEADER_LENGTH must be a multiple of the context's header_size.
900   * If the HEADER_LENGTH is larger than the context's header_size, multiple
901   * packets are queued for this entry.
902   *
903   * The @control.SY and TAG fields are ignored.
904   *
905   * If the @control.SYNC flag is set, the context drops all packets until a
906   * packet with a sy field is received which matches &fw_cdev_start_iso.sync.
907   *
908   * @control.PAYLOAD_LENGTH defines how many payload bytes can be received for
909   * one packet (in addition to payload quadlets that have been defined as headers
910   * and are stripped and returned in the &fw_cdev_event_iso_interrupt structure).
911   * If more bytes are received, the additional bytes are dropped.  If less bytes
912   * are received, the remaining bytes in this part of the payload buffer will not
913   * be written to, not even by the next packet.  I.e., packets received in
914   * consecutive frames will not necessarily be consecutive in memory.  If an
915   * entry has queued multiple packets, the PAYLOAD_LENGTH is divided equally
916   * among them.
917   *
918   * When a packet with the @control.INTERRUPT flag set has been completed, an
919   * &fw_cdev_event_iso_interrupt event will be sent.  An entry that has queued
920   * multiple receive packets is completed when its last packet is completed.
921   *
922   * Context type %FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL:
923   *
924   * Here, &fw_cdev_iso_packet would be more aptly named _iso_buffer_chunk since
925   * it specifies a chunk of the mmap()'ed buffer, while the number and alignment
926   * of packets to be placed into the buffer chunk is not known beforehand.
927   *
928   * @control.PAYLOAD_LENGTH is the size of the buffer chunk and specifies room
929   * for header, payload, padding, and trailer bytes of one or more packets.
930   * It must be a multiple of 4.
931   *
932   * @control.HEADER_LENGTH, TAG and SY are ignored.  SYNC is treated as described
933   * for single-channel reception.
934   *
935   * When a buffer chunk with the @control.INTERRUPT flag set has been filled
936   * entirely, an &fw_cdev_event_iso_interrupt_mc event will be sent.
937   */
938  struct fw_cdev_iso_packet {
939  	__u32 control;
940  	__u32 header[];
941  };
942  
943  /**
944   * struct fw_cdev_queue_iso - Queue isochronous packets for I/O
945   * @packets:	Userspace pointer to an array of &fw_cdev_iso_packet
946   * @data:	Pointer into mmap()'ed payload buffer
947   * @size:	Size of the @packets array, in bytes
948   * @handle:	Isochronous context handle
949   *
950   * Queue a number of isochronous packets for reception or transmission.
951   * This ioctl takes a pointer to an array of &fw_cdev_iso_packet structs,
952   * which describe how to transmit from or receive into a contiguous region
953   * of a mmap()'ed payload buffer.  As part of transmit packet descriptors,
954   * a series of headers can be supplied, which will be prepended to the
955   * payload during DMA.
956   *
957   * The kernel may or may not queue all packets, but will write back updated
958   * values of the @packets, @data and @size fields, so the ioctl can be
959   * resubmitted easily.
960   *
961   * In case of a multichannel receive context, @data must be quadlet-aligned
962   * relative to the buffer start.
963   */
964  struct fw_cdev_queue_iso {
965  	__u64 packets;
966  	__u64 data;
967  	__u32 size;
968  	__u32 handle;
969  };
970  
971  #define FW_CDEV_ISO_CONTEXT_MATCH_TAG0		 1
972  #define FW_CDEV_ISO_CONTEXT_MATCH_TAG1		 2
973  #define FW_CDEV_ISO_CONTEXT_MATCH_TAG2		 4
974  #define FW_CDEV_ISO_CONTEXT_MATCH_TAG3		 8
975  #define FW_CDEV_ISO_CONTEXT_MATCH_ALL_TAGS	15
976  
977  /**
978   * struct fw_cdev_start_iso - Start an isochronous transmission or reception
979   * @cycle:	Cycle in which to start I/O.  If @cycle is greater than or
980   *		equal to 0, the I/O will start on that cycle.
981   * @sync:	Determines the value to wait for receive packets that have
982   *		the %FW_CDEV_ISO_SYNC bit set
983   * @tags:	Tag filter bit mask.  Only valid for isochronous reception.
984   *		Determines the tag values for which packets will be accepted.
985   *		Use FW_CDEV_ISO_CONTEXT_MATCH_* macros to set @tags.
986   * @handle:	Isochronous context handle within which to transmit or receive
987   */
988  struct fw_cdev_start_iso {
989  	__s32 cycle;
990  	__u32 sync;
991  	__u32 tags;
992  	__u32 handle;
993  };
994  
995  /**
996   * struct fw_cdev_stop_iso - Stop an isochronous transmission or reception
997   * @handle:	Handle of isochronous context to stop
998   */
999  struct fw_cdev_stop_iso {
1000  	__u32 handle;
1001  };
1002  
1003  /**
1004   * struct fw_cdev_flush_iso - flush completed iso packets
1005   * @handle:	handle of isochronous context to flush
1006   *
1007   * For %FW_CDEV_ISO_CONTEXT_TRANSMIT or %FW_CDEV_ISO_CONTEXT_RECEIVE contexts,
1008   * report any completed packets.
1009   *
1010   * For %FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL contexts, report the current
1011   * offset in the receive buffer, if it has changed; this is typically in the
1012   * middle of some buffer chunk.
1013   *
1014   * Any %FW_CDEV_EVENT_ISO_INTERRUPT or %FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL
1015   * events generated by this ioctl are sent synchronously, i.e., are available
1016   * for reading from the file descriptor when this ioctl returns.
1017   */
1018  struct fw_cdev_flush_iso {
1019  	__u32 handle;
1020  };
1021  
1022  /**
1023   * struct fw_cdev_get_cycle_timer - read cycle timer register
1024   * @local_time:   system time, in microseconds since the Epoch
1025   * @cycle_timer:  Cycle Time register contents
1026   *
1027   * Same as %FW_CDEV_IOC_GET_CYCLE_TIMER2, but fixed to use %CLOCK_REALTIME
1028   * and only with microseconds resolution.
1029   *
1030   * In version 1 and 2 of the ABI, this ioctl returned unreliable (non-
1031   * monotonic) @cycle_timer values on certain controllers.
1032   */
1033  struct fw_cdev_get_cycle_timer {
1034  	__u64 local_time;
1035  	__u32 cycle_timer;
1036  };
1037  
1038  /**
1039   * struct fw_cdev_get_cycle_timer2 - read cycle timer register
1040   * @tv_sec:       system time, seconds
1041   * @tv_nsec:      system time, sub-seconds part in nanoseconds
1042   * @clk_id:       input parameter, clock from which to get the system time
1043   * @cycle_timer:  Cycle Time register contents
1044   *
1045   * The %FW_CDEV_IOC_GET_CYCLE_TIMER2 ioctl reads the isochronous cycle timer
1046   * and also the system clock.  This allows to correlate reception time of
1047   * isochronous packets with system time.
1048   *
1049   * @clk_id lets you choose a clock like with POSIX' clock_gettime function.
1050   * Supported @clk_id values are POSIX' %CLOCK_REALTIME and %CLOCK_MONOTONIC
1051   * and Linux' %CLOCK_MONOTONIC_RAW.
1052   *
1053   * @cycle_timer consists of 7 bits cycleSeconds, 13 bits cycleCount, and
1054   * 12 bits cycleOffset, in host byte order.  Cf. the Cycle Time register
1055   * per IEEE 1394 or Isochronous Cycle Timer register per OHCI-1394.
1056   */
1057  struct fw_cdev_get_cycle_timer2 {
1058  	__s64 tv_sec;
1059  	__s32 tv_nsec;
1060  	__s32 clk_id;
1061  	__u32 cycle_timer;
1062  };
1063  
1064  /**
1065   * struct fw_cdev_allocate_iso_resource - (De)allocate a channel or bandwidth
1066   * @closure:	Passed back to userspace in corresponding iso resource events
1067   * @channels:	Isochronous channels of which one is to be (de)allocated
1068   * @bandwidth:	Isochronous bandwidth units to be (de)allocated
1069   * @handle:	Handle to the allocation, written by the kernel (only valid in
1070   *		case of %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE ioctls)
1071   *
1072   * The %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE ioctl initiates allocation of an
1073   * isochronous channel and/or of isochronous bandwidth at the isochronous
1074   * resource manager (IRM).  Only one of the channels specified in @channels is
1075   * allocated.  An %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED is sent after
1076   * communication with the IRM, indicating success or failure in the event data.
1077   * The kernel will automatically reallocate the resources after bus resets.
1078   * Should a reallocation fail, an %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event
1079   * will be sent.  The kernel will also automatically deallocate the resources
1080   * when the file descriptor is closed.
1081   *
1082   * The %FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE ioctl can be used to initiate
1083   * deallocation of resources which were allocated as described above.
1084   * An %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event concludes this operation.
1085   *
1086   * The %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE ioctl is a variant of allocation
1087   * without automatic re- or deallocation.
1088   * An %FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED event concludes this operation,
1089   * indicating success or failure in its data.
1090   *
1091   * The %FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE_ONCE ioctl works like
1092   * %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE except that resources are freed
1093   * instead of allocated.
1094   * An %FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event concludes this operation.
1095   *
1096   * To summarize, %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE allocates iso resources
1097   * for the lifetime of the fd or @handle.
1098   * In contrast, %FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE allocates iso resources
1099   * for the duration of a bus generation.
1100   *
1101   * @channels is a host-endian bitfield with the least significant bit
1102   * representing channel 0 and the most significant bit representing channel 63:
1103   * 1ULL << c for each channel c that is a candidate for (de)allocation.
1104   *
1105   * @bandwidth is expressed in bandwidth allocation units, i.e. the time to send
1106   * one quadlet of data (payload or header data) at speed S1600.
1107   */
1108  struct fw_cdev_allocate_iso_resource {
1109  	__u64 closure;
1110  	__u64 channels;
1111  	__u32 bandwidth;
1112  	__u32 handle;
1113  };
1114  
1115  /**
1116   * struct fw_cdev_send_stream_packet - send an asynchronous stream packet
1117   * @length:	Length of outgoing payload, in bytes
1118   * @tag:	Data format tag
1119   * @channel:	Isochronous channel to transmit to
1120   * @sy:		Synchronization code
1121   * @closure:	Passed back to userspace in the response event
1122   * @data:	Userspace pointer to payload
1123   * @generation:	The bus generation where packet is valid
1124   * @speed:	Speed to transmit at
1125   *
1126   * The %FW_CDEV_IOC_SEND_STREAM_PACKET ioctl sends an asynchronous stream packet to every device
1127   * which is listening to the specified channel. The kernel writes either &fw_cdev_event_response
1128   * event or &fw_cdev_event_response2 event which indicates success or failure of the transmission.
1129   */
1130  struct fw_cdev_send_stream_packet {
1131  	__u32 length;
1132  	__u32 tag;
1133  	__u32 channel;
1134  	__u32 sy;
1135  	__u64 closure;
1136  	__u64 data;
1137  	__u32 generation;
1138  	__u32 speed;
1139  };
1140  
1141  /**
1142   * struct fw_cdev_send_phy_packet - send a PHY packet
1143   * @closure:	Passed back to userspace in the PHY-packet-sent event
1144   * @data:	First and second quadlet of the PHY packet
1145   * @generation:	The bus generation where packet is valid
1146   *
1147   * The %FW_CDEV_IOC_SEND_PHY_PACKET ioctl sends a PHY packet to all nodes on the same card as this
1148   * device.  After transmission, either %FW_CDEV_EVENT_PHY_PACKET_SENT event or
1149   * %FW_CDEV_EVENT_PHY_PACKET_SENT event is generated.
1150   *
1151   * The payload @data\[\] shall be specified in host byte order.  Usually,
1152   * @data\[1\] needs to be the bitwise inverse of @data\[0\].  VersaPHY packets
1153   * are an exception to this rule.
1154   *
1155   * The ioctl is only permitted on device files which represent a local node.
1156   */
1157  struct fw_cdev_send_phy_packet {
1158  	__u64 closure;
1159  	__u32 data[2];
1160  	__u32 generation;
1161  };
1162  
1163  /**
1164   * struct fw_cdev_receive_phy_packets - start reception of PHY packets
1165   * @closure: Passed back to userspace in phy packet events
1166   *
1167   * This ioctl activates issuing of either %FW_CDEV_EVENT_PHY_PACKET_RECEIVED or
1168   * %FW_CDEV_EVENT_PHY_PACKET_RECEIVED2 due to incoming PHY packets from any node on the same bus
1169   * as the device.
1170   *
1171   * The ioctl is only permitted on device files which represent a local node.
1172   */
1173  struct fw_cdev_receive_phy_packets {
1174  	__u64 closure;
1175  };
1176  
1177  #define FW_CDEV_VERSION 3 /* Meaningless legacy macro; don't use it. */
1178  
1179  #endif /* _LINUX_FIREWIRE_CDEV_H */
1180