From 609968669979823f0b2fdf08b43eab8e38f8dec6 Mon Sep 17 00:00:00 2001 From: aeb Date: Mon, 11 Jun 2001 11:23:00 +0000 Subject: [PATCH] Added man page describing format of the iso dump file. git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@68 53a565d1-3bb7-0310-b661-cf11e63c67ab --- configure.in | 1 + doc/Makefile.am | 4 ++-- doc/dumpiso.1.in | 32 +++++++++++++++++--------------- doc/isodump.5.in | 35 +++++++++++++++++++++++++++++++++++ doc/sendiso.1.in | 27 ++++++++++++++------------- 5 files changed, 69 insertions(+), 30 deletions(-) create mode 100644 doc/isodump.5.in diff --git a/configure.in b/configure.in index 6eccbf5..8d01a91 100644 --- a/configure.in +++ b/configure.in @@ -31,5 +31,6 @@ doc/Makefile doc/testlibraw.1 doc/sendiso.1 doc/dumpiso.1 +doc/isodump.1 debian/Makefile ]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 9569e2b..d6e10c7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,8 +1,8 @@ -EXTRA_DIST = testlibraw.1.in sendiso.1.in dumpiso.1.in \ +EXTRA_DIST = testlibraw.1.in sendiso.1.in dumpiso.1.in isodump.1.in \ libraw1394.sgml libraw1394 libraw1394.ps # man files for testlibraw -man_MANS = testlibraw.1 sendiso.1 dumpiso.1 +man_MANS = testlibraw.1 sendiso.1 dumpiso.1 isodump.1 # libraw1394 docbook documentation diff --git a/doc/dumpiso.1.in b/doc/dumpiso.1.in index b2ced09..2412dcf 100644 --- a/doc/dumpiso.1.in +++ b/doc/dumpiso.1.in @@ -5,32 +5,34 @@ dumpiso \- dump IEEE 1394 isochronous channel packets .B dumpiso [ \fIoptions\fR ] [ \fIFILE\fR ] .SH DESCRIPTION -dumpiso listens on a selected range of channels and dumps all received packets -into the file \fIFILE\fR or, if not given, to standard output. While dumping, -the current number of received packets is written to standard error and updated -with every packet. +dumpiso listens on a selected range of channels and dumps all received +packets into the file \fIFILE\fR or, if not given, to standard output. +While dumping, the current number of received packets is written to +standard error and updated with every packet. .PP -It uses a simple file format for the dumps, described in another man page yet to -be written. The dumped packets can be sent out again with \fBsendiso\fR(1). +It uses a simple file format for the dumps which is described in +\fBisodump\fR(5). The dumped packets can be sent out again with +\fBsendiso\fR(1). .SH OPTIONS .TP .B -c\fR,\fB --channels=\fICHANNELS -Sets the channels to listen on. \fICHANNELS\fR can be either a single number, -in which case this is the only channel to listen on, or a range of channels in -the form X-Y. Channel numbers can range from 0 to 63. You can give this option -multiple times, new channels are added to the list of already set channels. -Defaults to all channels. +Sets the channels to listen on. \fICHANNELS\fR can be either a single +number, in which case this is the only channel to listen on, or a +range of channels in the form X-Y. Channel numbers can range from 0 +to 63. You can give this option multiple times, new channels are +added to the list of already set channels. Defaults to all channels. .TP .B -p\fR,\fB --port=\fIPORT -Choose port \fIPORT\fR for receiving. A port is a 1394 card or chip and -represents one connected bus, therefore this is only relevant when you have -multiple of these. Defaults to 0. +Choose port \fIPORT\fR for receiving. A port is a 1394 card or chip +and represents one connected bus, therefore this is only relevant when +you have multiple of these. Defaults to 0. .TP .B -h\fR,\fB --help Show help text and exit. .SH BUGS None known. .SH SEE ALSO -.B sendiso\fR(1) +.B sendiso\fR(1), +.B isodump\fR(5) .SH AUTHOR Andreas Bombe diff --git a/doc/isodump.5.in b/doc/isodump.5.in new file mode 100644 index 0000000..7ab20a6 --- /dev/null +++ b/doc/isodump.5.in @@ -0,0 +1,35 @@ +.TH isodump 5 "isodump v1" "libraw1394 @VERSION@" "Linux IEEE 1394" +.SH NAME +isodump \- format of IEEE 1394 isochronous packets dump file +.SH DESCRIPTION +The isodump format stores a series of IEEE 1394 isochronous stream +packets (possibly from multiple channels), including their headers. +Its main use is as the output format of \fBdumpiso\fR(1) and the input +format of \fBsendiso\fR(1). +.PP +The 32 byte header starts at offset 0 with the string "1394 isodump +v1" followed by a zero byte. The next 8 bytes form a 64 bit big +endian integer, which represents a bit mask of the channels that were +dumped. A set bit at position (1 << x) signifies that channel x was +being listened on. The following 8 bytes are set to zero. +.PP +The iso packets follow the header and are appended to the data stream +in the order they were received. The packets consist of the header +quadlet as originally received and the data quadlets following +directly. The CRC quadlets after header and data do not appear and +everything is in big endian, as seen on the bus. +.PP +There is no further framing of the packets in the format, packet +boundaries can be found by looking at the data size field in the +header quadlet of each packet. The data size field appears in the +most significant 16 bits of the header quadlet, contain the size in +bytes (the actual packet is padded to a multiple of four bytes) and do +not include the header packet. +.SH COMPATIBILITY +This format was introduced with the iso send and dump tools +distributed with libraw1394. No one else uses it so far. +.SH SEE ALSO +.B sendiso\fR(1), +.B dumpiso\fR(1) +.SH AUTHOR +Andreas Bombe diff --git a/doc/sendiso.1.in b/doc/sendiso.1.in index 8f316ca..e80cae9 100644 --- a/doc/sendiso.1.in +++ b/doc/sendiso.1.in @@ -5,15 +5,15 @@ sendiso \- send IEEE 1394 isochronous packets from dump file .B sendiso [ \fIoptions\fR ] \fIFILE\fR .SH DESCRIPTION -sendiso takes the dump file \fIFILE\fR as generated by \fBdumpiso\fR(1), -extracts the packets and sends them as they were received (in the same order, -with the same channel numbers) as fast as possible - timing of the original dump -is not preserved. +sendiso takes the dump file \fIFILE\fR as generated by +\fBdumpiso\fR(1), extracts the packets and sends them as they were +received (in the same order, with the same channel numbers) as fast as +possible - timing of the original dump is not preserved. .PP -This program does not allocate any isochronous resources but just starts -sending. It should not be used in live environments where it might interfere -with properly set up isochronous transmissions, it is a debug and performance -benchmarking tool. +This program does not allocate any isochronous resources but just +starts sending. It should not be used in live environments where it +might interfere with properly set up isochronous transmissions, it is +a debug and performance benchmarking tool. .SH OPTIONS .TP .B -l\fR,\fB --loop=\fICOUNT @@ -23,19 +23,20 @@ Send dump file \fICOUNT\fR times. Defaults to 1. Send dump file in an endless loop. .TP .B -s\fR,\fB --speed=\fISPEED -Send packets at speed \fISPEED\fR, which can be given as 100, 200 and 400 (in -Mbit/s) or abbreviated as 1, 2 and 4. Defaults to 100. +Send packets at speed \fISPEED\fR, which can be given as 100, 200 and +400 (in Mbit/s) or abbreviated as 1, 2 and 4. Defaults to 100. .TP .B -p\fR,\fB --port=\fIPORT Choose port \fIPORT\fR for sending. A port is a 1394 card or chip and -represents one connected bus, therefore this is only relevant when you have -multiple of these. Defaults to 0. +represents one connected bus, therefore this is only relevant when you +have multiple of these. Defaults to 0. .TP .B -h\fR,\fB --help Show help text and exit. .SH BUGS None known. .SH SEE ALSO -.B dumpiso\fR(1) +.B dumpiso\fR(1), +.B isodump\fR(5) .SH AUTHOR Andreas Bombe