[aravis] documentation: begin a documentation of the GV protocol.

From: Emmanuel Pacaud <emmanuel src gnome org>
To: commits-list gnome org
Cc:
Subject: [aravis] documentation: begin a documentation of the GV protocol.
Date: Sat, 23 Jul 2011 17:59:47 +0000 (UTC)
commit 93b7b81dc9a91edc2eacf5e9cc3d650063675a05
Author: Emmanuel Pacaud <emmanuel gnome org>
Date:   Sat Jul 23 19:59:11 2011 +0200

    documentation: begin a documentation of the GV protocol.

 docs/reference/aravis/Makefile.am         |    6 ++-
 docs/reference/aravis/aravis-docs.xml     |   25 ++++++++------
 docs/reference/aravis/aravis-gv.xml       |   38 +++++++++++++++++++++
 docs/reference/aravis/aravis-sections.txt |    8 +++--
 src/arvgvcp.h                             |   52 +++++++++++++++++++++++++++-
 5 files changed, 111 insertions(+), 18 deletions(-)
---
diff --git a/docs/reference/aravis/Makefile.am b/docs/reference/aravis/Makefile.am
index 00b6d42..cccdb16 100644
--- a/docs/reference/aravis/Makefile.am
+++ b/docs/reference/aravis/Makefile.am
@@ -72,13 +72,15 @@ HTML_IMAGES=
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files= \
-	       aravis-overview.xml
+	       aravis-overview.xml 	\
+	       aravis-gv.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
 # e.g. expand_content_files=running.sgml
 expand_content_files= \
-	       aravis-overview.xml
+	       aravis-overview.xml	\
+	       aravis-gv.xml
 
 # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget
diff --git a/docs/reference/aravis/aravis-docs.xml b/docs/reference/aravis/aravis-docs.xml
index 6fcfb52..c5734b0 100644
--- a/docs/reference/aravis/aravis-docs.xml
+++ b/docs/reference/aravis/aravis-docs.xml
@@ -34,7 +34,7 @@
 	<xi:include href="xml/aravis-overview.xml"/>
 
 	<part id="aravis-reference">
-		<title>Aravis reference</title>
+		<title>Aravis API reference</title>
 
 		<chapter>
 			<title>Base</title>
@@ -91,17 +91,20 @@
 			<xi:include href="xml/arvvalue.xml"/>
 			<xi:include href="xml/arvzip.xml"/>
 		</chapter>
-	</part>
 
-	<chapter id="object-tree">
-		<title>Object Hierarchy</title>
-		<xi:include href="xml/tree_index.sgml"/>
-	</chapter>
+		<chapter id="object-tree">
+			<title>Object Hierarchy</title>
+			<xi:include href="xml/tree_index.sgml"/>
+		</chapter>
+
+		<index id="api-index-full">
+			<title>API Index</title>
+			<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+		</index>
+
+		<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+	</part>
 
-	<index id="api-index-full">
-		<title>API Index</title>
-		<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
-	</index>
+	<xi:include href="xml/aravis-gv.xml"/>
 
-	<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
 </book>
diff --git a/docs/reference/aravis/aravis-gv.xml b/docs/reference/aravis/aravis-gv.xml
new file mode 100644
index 0000000..e8fbf5c
--- /dev/null
+++ b/docs/reference/aravis/aravis-gv.xml
@@ -0,0 +1,38 @@
+<part id="aravis-gv">
+	<title>Ethernet protocol (GV)</title>
+
+	<chapter id="aravis-gv-introduction">
+		<title>Introduction</title>
+
+		<para>
+			This part contains a description of the protocol implemented by Aravis for the control of the gigabit ethenet cameras. This protocol is a standard used by many video cameras manufacturers for their products. It is a closed standard which should not be confused by what is used on 'IP cameras'. In the case of 'IP cameras' the video stream is a compressed stream (jpeg, h264...) send over HTTP or RTSP, whereas in Aravis, the video stream is a raw stream, mainly targeted to industrial applications.
+		</para>
+
+		<para>
+			The protocol implemented by Aravis library is based on UDP packets transmited over an ethernet link. Two different types of packets are used: GVCP packets and GVSP packets. GVCP packets are used for the control of the devices, and GVSP for the transmission of the data stream.		</para>
+	</chapter>
+
+	<chapter id="aravis-gvcp">
+		<title>GVCP packets</title>
+		<para>
+			Devices are waiting for GVCP packets listening to the GVCP port (3946). When the client sends a command GVCP packet to the device, the device sends back an acknowledge packets in return. Each command/acknowledge pair is identified by a 16 bit value, which allows to check if an acknowledge packet corresponds to the previsoulsy sent command. 0 is an error value for this identifier. If an acknowledge is not received after a given timeout period, another command packet is sent, until a maximum number of retries is reached.
+		</para>
+
+		<para>
+			A GVCP packet is composed by a 64 bit headers, followed by a data byte array.
+		</para>
+
+	</chapter>
+
+	<chapter id="aravis-gvsp">
+		<title>GVSP packets</title>
+	</chapter>
+
+	<chapter id="aravis-gvcp-discovery">
+		<title>Device discovery mechanism</title>
+
+		<para>
+			A device discovery mechanism is implemented using a discovery GVCP packet, broadcasted by the client to the GVCP port. Each available device responds to this discovery packet with an acknowledge packet, containing a description of the device (device name, model name, manufacturer name, MAC Address...).
+		</para>
+	</chapter>
+</part>
diff --git a/docs/reference/aravis/aravis-sections.txt b/docs/reference/aravis/aravis-sections.txt
index 22ffcae..7531ff8 100644
--- a/docs/reference/aravis/aravis-sections.txt
+++ b/docs/reference/aravis/aravis-sections.txt
@@ -779,6 +779,10 @@ arv_pixel_format_from_gst_caps
 <SECTION>
 <FILE>arvgvcp</FILE>
 <TITLE>ArvGvcp</TITLE>
+ArvGvcpPacketType
+ArvGvcpCommand
+ArvGvcpHeader
+ArvGvcpPacket
 arv_gvcp_packet_free
 arv_gvcp_packet_get_packet_type
 arv_gvcp_packet_get_command
@@ -895,12 +899,10 @@ ARV_GVBS_USER_DEFINED_NAME_SIZE
 ARV_GVBS_XML_URL_SIZE
 ARV_GVCP_PORT
 ARV_GVCP_DATA_SIZE_MAX
-ArvGvcpPacket
-ArvGvcpPacketType
-ArvGvcpCommand
 g_ntohl
 g_ntohs
 sizeof
+ARAVIS_PACKED_STRUCTURE
 </SECTION>
 
 <SECTION>
diff --git a/src/arvgvcp.h b/src/arvgvcp.h
index 54a3127..623a183 100644
--- a/src/arvgvcp.h
+++ b/src/arvgvcp.h
@@ -142,6 +142,14 @@ G_BEGIN_DECLS
 
 #define ARV_GVCP_DATA_SIZE_MAX				512
 
+/**
+ * ArvGvcpPacketType:
+ * @ARV_GVCP_PACKET_TYPE_ACK: acknowledge packet
+ * @ARV_GVCP_PACKET_TYPE_RESEND: resend request packet
+ * @ARV_GVCP_PACKET_TYPE_CMD: command packet
+ * @ARV_GVCP_PACKET_TYPE_ERROR: error packet
+ */
+
 typedef enum {
 	ARV_GVCP_PACKET_TYPE_ACK =		0x0000,
 	ARV_GVCP_PACKET_TYPE_RESEND =		0x4200,
@@ -149,6 +157,24 @@ typedef enum {
 	ARV_GVCP_PACKET_TYPE_ERROR =		0x8006
 } ArvGvcpPacketType;
 
+/**
+ * ArvGvcpCommand:
+ * @ARV_GVCP_COMMAND_DISCOVERY_CMD: discovery command
+ * @ARV_GVCP_COMMAND_DISCOVERY_ACK: discovery acknowledge
+ * @ARV_GVCP_COMMAND_BYE_CMD: goodbye command, for connection termination
+ * @ARV_GVCP_COMMAND_BYE_ACK: goodbye acknowledge
+ * @ARV_GVCP_COMMAND_PACKET_RESEND_CMD: packet resend request
+ * @ARV_GVCP_COMMAND_PACKET_RESEND_ACK: packet resend acknowledge (not used ?)
+ * @ARV_GVCP_COMMAND_READ_REGISTER_CMD: read register command
+ * @ARV_GVCP_COMMAND_READ_REGISTER_ACK: read register acknowledge
+ * @ARV_GVCP_COMMAND_WRITE_REGISTER_CMD: write register command
+ * @ARV_GVCP_COMMAND_WRITE_REGISTER_ACK: write register acknowledge
+ * @ARV_GVCP_COMMAND_READ_MEMORY_CMD: read memory command
+ * @ARV_GVCP_COMMAND_READ_MEMORY_ACK: read memory acknowledge
+ * @ARV_GVCP_COMMAND_WRITE_MEMORY_CMD: write memory command
+ * @ARV_GVCP_COMMAND_WRITE_MEMORY_ACK: write memory acknowledge
+ */
+
 typedef enum {
 	ARV_GVCP_COMMAND_DISCOVERY_CMD =	0x0002,
 	ARV_GVCP_COMMAND_DISCOVERY_ACK =	0x0003,
@@ -166,12 +192,34 @@ typedef enum {
 	ARV_GVCP_COMMAND_WRITE_MEMORY_ACK =	0x0087
 } ArvGvcpCommand;
 
-typedef struct {
+/**
+ * ArvGvcpHeader:
+ * @packet_type: a #ArvGvcpPacketType identifier
+ * @command: a #ArvGvcpCommand identifier
+ * @size: data size
+ * @count: packet identifier
+ *
+ * GVCP packet header structure.
+ */
+
+#define ARAVIS_PACKED_STRUCTURE __attribute__((__packed__))
+
+typedef struct ARAVIS_PACKED_STRUCTURE {
 	guint16 packet_type;
 	guint16 command;
 	guint16 size;
 	guint16 count;
-}  __attribute__((__packed__)) ArvGvcpHeader;
+} ArvGvcpHeader;
+
+#undef ARAVIS_PACKED_STRUCTURE
+
+/**
+ * ArvGvcpPacket:
+ * @header: packet header
+ * @data: variable size byte array
+ *
+ * GVCP packet structure.
+ */
 
 typedef struct {
 	ArvGvcpHeader header;
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]