firewire-cdev.h 33 KB

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