Commit aa6fec3cdeb14ecc916eb78c4cd9ed79e4f7fe8d
Committed by
Stefan Richter
1 parent
9cac00b8f0
Exists in
master
and in
7 other branches
firewire: cdev: iso packet documentation
Add the missing documentation for iso packets. Signed-off-by: Clemens Ladisch <clemens@ladisch.de> Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
Showing 1 changed file with 33 additions and 6 deletions Side-by-side Diff
include/linux/firewire-cdev.h
... | ... | @@ -438,7 +438,7 @@ |
438 | 438 | * @type: %FW_CDEV_ISO_CONTEXT_TRANSMIT or %FW_CDEV_ISO_CONTEXT_RECEIVE |
439 | 439 | * @header_size: Header size to strip for receive contexts |
440 | 440 | * @channel: Channel to bind to |
441 | - * @speed: Speed to transmit at | |
441 | + * @speed: Speed for transmit contexts | |
442 | 442 | * @closure: To be returned in &fw_cdev_event_iso_interrupt |
443 | 443 | * @handle: Handle to context, written back by kernel |
444 | 444 | * |
... | ... | @@ -451,6 +451,9 @@ |
451 | 451 | * If a context was successfully created, the kernel writes back a handle to the |
452 | 452 | * context, which must be passed in for subsequent operations on that context. |
453 | 453 | * |
454 | + * For receive contexts, @header_size must be at least 4 and must be a multiple | |
455 | + * of 4. | |
456 | + * | |
454 | 457 | * Note that the effect of a @header_size > 4 depends on |
455 | 458 | * &fw_cdev_get_info.version, as documented at &fw_cdev_event_iso_interrupt. |
456 | 459 | */ |
457 | 460 | |
... | ... | @@ -481,10 +484,34 @@ |
481 | 484 | * |
482 | 485 | * &struct fw_cdev_iso_packet is used to describe isochronous packet queues. |
483 | 486 | * |
484 | - * Use the FW_CDEV_ISO_ macros to fill in @control. The sy and tag fields are | |
485 | - * specified by IEEE 1394a and IEC 61883. | |
487 | + * Use the FW_CDEV_ISO_ macros to fill in @control. | |
486 | 488 | * |
487 | - * FIXME - finish this documentation | |
489 | + * For transmit packets, the header length must be a multiple of 4 and specifies | |
490 | + * the numbers of bytes in @header that will be prepended to the packet's | |
491 | + * payload; these bytes are copied into the kernel and will not be accessed | |
492 | + * after the ioctl has returned. The sy and tag fields are copied to the iso | |
493 | + * packet header (these fields are specified by IEEE 1394a and IEC 61883-1). | |
494 | + * The skip flag specifies that no packet is to be sent in a frame; when using | |
495 | + * this, all other fields except the interrupt flag must be zero. | |
496 | + * | |
497 | + * For receive packets, the header length must be a multiple of the context's | |
498 | + * header size; if the header length is larger than the context's header size, | |
499 | + * multiple packets are queued for this entry. The sy and tag fields are | |
500 | + * ignored. If the sync flag is set, the context drops all packets until | |
501 | + * a packet with a matching sy field is received (the sync value to wait for is | |
502 | + * specified in the &fw_cdev_start_iso structure). The payload length defines | |
503 | + * how many payload bytes can be received for one packet (in addition to payload | |
504 | + * quadlets that have been defined as headers and are stripped and returned in | |
505 | + * the &fw_cdev_event_iso_interrupt structure). If more bytes are received, the | |
506 | + * additional bytes are dropped. If less bytes are received, the remaining | |
507 | + * bytes in this part of the payload buffer will not be written to, not even by | |
508 | + * the next packet, i.e., packets received in consecutive frames will not | |
509 | + * necessarily be consecutive in memory. If an entry has queued multiple | |
510 | + * packets, the payload length is divided equally among them. | |
511 | + * | |
512 | + * When a packet with the interrupt flag set has been completed, the | |
513 | + * &fw_cdev_event_iso_interrupt event will be sent. An entry that has queued | |
514 | + * multiple receive packets is completed when its last packet is completed. | |
488 | 515 | */ |
489 | 516 | struct fw_cdev_iso_packet { |
490 | 517 | __u32 control; |
... | ... | @@ -501,7 +528,7 @@ |
501 | 528 | * Queue a number of isochronous packets for reception or transmission. |
502 | 529 | * This ioctl takes a pointer to an array of &fw_cdev_iso_packet structs, |
503 | 530 | * which describe how to transmit from or receive into a contiguous region |
504 | - * of a mmap()'ed payload buffer. As part of the packet descriptors, | |
531 | + * of a mmap()'ed payload buffer. As part of transmit packet descriptors, | |
505 | 532 | * a series of headers can be supplied, which will be prepended to the |
506 | 533 | * payload during DMA. |
507 | 534 | * |