From 17167ea970a4ad600615f1dbfe7ea9e89493d735 Mon Sep 17 00:00:00 2001 From: aeb Date: Mon, 9 Jul 2001 00:27:09 +0000 Subject: [PATCH] Reworked some paragraphs. Added chapters on generation numbers and error codes. Added some function reference entries. git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@72 53a565d1-3bb7-0310-b661-cf11e63c67ab --- doc/libraw1394.sgml | 176 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 154 insertions(+), 22 deletions(-) diff --git a/doc/libraw1394.sgml b/doc/libraw1394.sgml index e9f864f..7c7033f 100644 --- a/doc/libraw1394.sgml +++ b/doc/libraw1394.sgml @@ -73,8 +73,9 @@ - If you are familiar with CSR architectures (as defined in --FIXME--), then - you already know most of 1394, which is a CSR implementation. + If you are familiar with CSR architectures (as defined in IEEE 1212 + (FIXME?)), then you already know most of 1394, which is a CSR + implementation. @@ -85,9 +86,9 @@ document are the quadlet (32 bit quantity) and the octlet (64 bit quantity) and blocks (any quantity of bytes). The bus byte ordering is big endian. A transmission can be sent at one of multiple possible - speeds, from the slowest 100 Mbit/s over 200 and 400 Mbit/s up to 3.2 - Gbit/s in the future (these speeds are also referred to as S100, S200, - ...). + speeds, which are 100, 200 and 400 Mbit/s for the currently mostly used + IEEE 1394a spec and up to 3.2 Gbit/s in the recently finalized 1394.b + standard (these speeds are also referred to as S100, S200, ...). @@ -188,16 +189,8 @@ later time from the targetted node to the source node (this is called a split transaction). Only writes can succeed and complete in the ack code, reads and locks require a response. Error and packet pending can - happen for every transaction. - - - - The response packets contain a response code (rcode) which signifies - success or type of error. libraw1394 contains a function to convert - ack/rcode pairs into errno codes which convey roughly the same meaning. - This is done automatically for the synchronous read/write/lock wrapper - functions, i.e. they return a negative value for failure and a standard - error code can be found in the global variable errno. + happen for every transaction. The response packets contain a response + code (rcode) which signifies success or type of error. @@ -411,15 +404,15 @@ - A list of available ports together with some information about it - (name of the hardware, number of connected nodes) is available via + A list of available ports together with some information about it (name + of the hardware, number of connected nodes) is available via raw1394_get_port_info(), which is to be called - right getting a fresh handle. The user should be presented with a + right after getting a fresh handle. The user should be presented with a choice of available ports if there is more than one. It may be good practice to do that even if there is only one port, since that may - result from a normally configured port just not being available, - making it confusing to be dropped right into the application attached - to a port without a choice and notion of anything going wrong. + result from a normally configured port just not being available, making + it confusing to be dropped right into the application attached to a port + without a choice and notion of anything going wrong. @@ -551,6 +544,64 @@ + + Generation Numbers + + + libraw1394 and the kernel code use generation numbers to identify the + current bus configuration and increment those on every configuration + change. The most important generation number is stored per connected + 1394 bus and incremented on every bus reset. There is another number + managed by raw1394 which identifies global changes (like a complete port + being added or removed), which is used for the + raw1394_set_port() function to make sure you don't + use stale port numbers. This is done transparently to you. + + + + The bus generation number is more relevant for your work. Since nodes + can change IDs with every bus reset, it is very likely that you don't + want to send a packet you constructed with the old ID before you noticed + the bus reset. This does not apply to isochronous transmissions, since + they are broadcast and do not depend on bus configuration. Therefore + every packet is automatically tagged with the expected generation + number, and it will fail to send if that does not match the number + managed in the kernel for the port in question. + + + + You get the current generation number through the bus reset handler. If + you don't set a custom bus reset handler, the default handler will + update the generation number automatically. If you set your own + handler, you can update the generation number to be used through + raw1394_update_generation() directly in the handler + or later. + + + + + Error and Success Codes + + + libraw1394 returns the ack/rcode pair in most transaction cases. The + rcode is undefined in cases where the ack code is not equal to + ack_pending. This is stored in a type + raw1394_errcode_t, from which the ack and rcode parts can + be extracted using two macros. + + + + With the function raw1394_errcode_to_errno() it is + possible to convert this to an errno number that conveys roughly the + same meaning. Many developers will find that easier to handle. This is + done automatically for the synchronous read/write/lock wrapper + functions, i.e. they return 0 for success and a negative value for + failure, in which case they also set the errno variable + to the appropriate code. The raw ack/rcode pair can then still be + retrieved using raw1394_get_errcode(). + + + @@ -563,7 +614,7 @@ - raw1394_net_handle + raw1394_new_handle create new handle @@ -644,6 +695,87 @@ + + + raw1394_get_port_info + 3 + + + + raw1394_get_port_info + get information about connected ports + + + + + + int raw1394_get_port_info + raw1394handle_t handle + struct raw1394_port_info *pinf + int maxports + + + + + + Arguments + + + + pinf + + Pointer to an array of structure of type + raw1394_port_info which will be filled in + by the function. + + + + maxports + + Maximum number of pinf structures to + fill in. Zero is valid. + + + + + + + Return Value + + + The number of ports currently existing. + + + + + Description + + + Before you can set which port to use, you use this function to find + out which ports exist. The raw1394_port_info + structure looks like this: + + +struct raw1394_portinfo { + int nodes; + char name[32]; +}; + + + + + The field nodes contains the number of + nodes that are currently connected to that port, the field + name contains the name of the hardware + type. If your program is interactive, you should present the user + with this list to let them decide which port to use. A + non-interactive program (and probably interactive ones, too) should + provide a command line option to choose the port. + + + + + raw1394_get_fd