[gPTP Doc] Feedback fixes

daemons/gptp/common/avbts_message.hpp

@@ -52,10 +52,7 @@
 
 #define PTP_ETHER 1		/*!< @todo Not used */
 #define PTP_DEFAULT 255	/*!< @todo Not used */
-/**
- * @addtogroup PTP_COMMON_HDR
-* @{
-*/
+
 #define PTP_COMMON_HDR_OFFSET 0		/*!< PTP common header offset */
 #define PTP_COMMON_HDR_LENGTH 34	/*!< PTP common header length in bytes */
 #define PTP_COMMON_HDR_TRANSSPEC_MSGTYPE(x) x	/*!< Gets the message type offset on PTP header */
@@ -69,12 +66,7 @@
 #define PTP_COMMON_HDR_SEQUENCE_ID(x) x+30		/*!< Gets the sequence id offset on PTP header */
 #define PTP_COMMON_HDR_CONTROL(x) x+32			/*!< Gets the control offset on PTP header */
 #define PTP_COMMON_HDR_LOG_MSG_INTRVL(x) x+33	/*!< Gets the log message interval offset on PTP header */
-/**@} */
 
-/**
- * @addtogroup PTP_ANNOUNCE
- * @{
- */
 #define PTP_ANNOUNCE_OFFSET 34							/*!< PTP announce offset */
 #define PTP_ANNOUNCE_LENGTH 30							/*!< PTP announce length in bytes */
 #define PTP_ANNOUNCE_CURRENT_UTC_OFFSET(x) x+10			/*!< Gets PTP announce current UTC offset */
@@ -84,65 +76,40 @@
 #define PTP_ANNOUNCE_GRANDMASTER_IDENTITY(x) x+19		/*!< Gets Grandmaster identity offset on announce fields*/
 #define PTP_ANNOUNCE_STEPS_REMOVED(x) x+27				/*!< Gets steps removed offset on announce fields*/
 #define PTP_ANNOUNCE_TIME_SOURCE(x) x+29				/*!< Gets time source offset on announce fields*/
-/**@}*/
 
-/**
- * @addtogroup PTP_SYNC
- * @{
- */
 #define PTP_SYNC_OFFSET 34		/*!< PTP SYNC base offset */
 #define PTP_SYNC_LENGTH 10		/*!< PTP SYNC length in bytes */
 #define PTP_SYNC_SEC_MS(x) x	/*!< PTP SYNC seconds MSB offset */
 #define PTP_SYNC_SEC_LS(x) x+2	/*!< PTP SYNC seconds LSB offset */
 #define PTP_SYNC_NSEC(x) x+6	/*!< PTP SYNC nanoseconds offset */
-/** @} */
 
-/**
- * @addtogroup PTP_FOLLOWUP
- * @{
- */
 #define PTP_FOLLOWUP_OFFSET 34		/*!< PTP FOLLOWUP base offset */
 #define PTP_FOLLOWUP_LENGTH 10		/*!< PTP FOLLOWUP length in bytes */
 #define PTP_FOLLOWUP_SEC_MS(x) x	/*!< Gets the followup seconds MSB offset */
 #define PTP_FOLLOWUP_SEC_LS(x) x+2	/*!< Gets the followup seconds LSB offset */
 #define PTP_FOLLOWUP_NSEC(x) x+6	/*!< Gets tne followup nanoseconds offset */
-/** @}*/
 
-/**
- * @addtogroup PTP_PDELAY_REQ
- */
 #define PTP_PDELAY_REQ_OFFSET 34		/*!< PTP PDELAY REQUEST base offset */
 #define PTP_PDELAY_REQ_LENGTH 20		/*!< PTP PDELAY REQUEST length in bytes */
 #define PTP_PDELAY_REQ_SEC_MS(x) x		/*!< Gets the pdelay request seconds MSB offset */
 #define PTP_PDELAY_REQ_SEC_LS(x) x+2	/*!< Gets the pdelay request seconds LSB offset */
 #define PTP_PDELAY_REQ_NSEC(x) x+6		/*!< Gets the pdelay request nanoseconds offset */
-/*@}*/
 
-/**
- * @addtogroup PTP_PDELAY_RESP
- * @{
- */
 #define PTP_PDELAY_RESP_OFFSET 34				/*!< PDELAY RESPONSE base offset */
 #define PTP_PDELAY_RESP_LENGTH 20				/*!< PDELAY RESPONSE length in bytes */
 #define PTP_PDELAY_RESP_SEC_MS(x) x				/*!< Gets the pdelay response seconds MSB offset */
 #define PTP_PDELAY_RESP_SEC_LS(x) x+2			/*!< Gets the pdelay response seconds LSB offset */
 #define PTP_PDELAY_RESP_NSEC(x) x+6				/*!< Gets the pdelay nanoseconds offset */
 #define PTP_PDELAY_RESP_REQ_CLOCK_ID(x) x+10	/*!< Gets the pdelay response request clock id offset */
 #define PTP_PDELAY_RESP_REQ_PORT_ID(x) x+18		/*!< Gets the pdelay response request port id offset */
-/*@}*/
 
-
-/**
- * @addtogroup PTP_PDELAY_FOLLOWUP
- */
 #define PTP_PDELAY_FOLLOWUP_OFFSET 34				/*!< PTP PDELAY FOLLOWUP base offset*/
 #define PTP_PDELAY_FOLLOWUP_LENGTH 20				/*!< PTP PDELAY FOLLOWUP length in bytes */
 #define PTP_PDELAY_FOLLOWUP_SEC_MS(x) x				/*!< Gets the pdelay followup seconds MSB offset*/
 #define PTP_PDELAY_FOLLOWUP_SEC_LS(x) x+2			/*!< Gets the pdelay followup seconds LSB offset*/
 #define PTP_PDELAY_FOLLOWUP_NSEC(x) x+6				/*!< Gets the pdelay followup nanoseconds offset*/
 #define PTP_PDELAY_FOLLOWUP_REQ_CLOCK_ID(x) x+10	/*!< Gets the pdelay followup request clock id offset*/
 #define PTP_PDELAY_FOLLOWUP_REQ_PORT_ID(x) x+18		/*!< Gets the pdelay followup request port id offset*/
-/**@}*/
 
 #define PTP_LI_61_BYTE 1		/*!< PTP_LI_61(leap61) byte offset on flags field */
 #define PTP_LI_61_BIT 0			/*!< PTP_LI_61(leap61) bit offset on PTP_LI_61 byte*/

daemons/gptp/common/avbts_osnet.hpp

@@ -216,7 +216,7 @@ class InterfaceName: public InterfaceLabel {
 
 /**
  * factory_name_t class
- * Provides a gereric class to be used as a key to create factory maps.
+ * Provides a generic class to be used as a key to create factory maps.
  */
 class factory_name_t {
  private:

daemons/gptp/common/ieee1588.hpp

@@ -51,7 +51,7 @@
 
 #define MAX_PORTS 32	/*!< Maximum number of IEEE1588Port instances */
 
-#define PTP_CLOCK_IDENTITY_LENGTH 8		/*!< Size of ClockIdentity instance*/
+#define PTP_CLOCK_IDENTITY_LENGTH 8		/*!< Size of a clock identifier stored in the ClockIndentity class, described at IEEE 802.1AS Clause 8.5.2.4*/
 
 class LinkLayerAddress;
 struct ClockQuality;
@@ -71,19 +71,19 @@ class OSNetworkInterface;
  * Defined at: IEEE 1588-2008 Clause 9.2.6
  */
 typedef enum {
-	NULL_EVENT = 0,
-	POWERUP = 5,
-	INITIALIZE,
-	STATE_CHANGE_EVENT,
-	SYNC_INTERVAL_TIMEOUT_EXPIRES,
-	PDELAY_INTERVAL_TIMEOUT_EXPIRES,
-	SYNC_RECEIPT_TIMEOUT_EXPIRES,
-	QUALIFICATION_TIMEOUT_EXPIRES,
-	ANNOUNCE_RECEIPT_TIMEOUT_EXPIRES,
-	ANNOUNCE_INTERVAL_TIMEOUT_EXPIRES,
-	FAULT_DETECTED,
-	PDELAY_DEFERRED_PROCESSING,
-	PDELAY_RESP_RECEIPT_TIMEOUT_EXPIRES,
+	NULL_EVENT = 0,						//!< Null Event. Used to initialize events.
+	POWERUP = 5,						//!< Power Up. Initialize state machines.
+	INITIALIZE,							//!< Same as POWERUP.
+	STATE_CHANGE_EVENT,					//!< Signalizes that something has changed. Recalculates best master.
+	SYNC_INTERVAL_TIMEOUT_EXPIRES,		//!< Sync interval expired. Its time to send a sync message.
+	PDELAY_INTERVAL_TIMEOUT_EXPIRES,	//!< PDELAY interval expired. Its time to send pdelay_req message
+	SYNC_RECEIPT_TIMEOUT_EXPIRES,		//!< Sync receipt timeout. Restart timers and take actions based on port's state.
+	QUALIFICATION_TIMEOUT_EXPIRES,		//!< Qualification timeout. Event not currently used
+	ANNOUNCE_RECEIPT_TIMEOUT_EXPIRES,	//!< Announce receipt timeout. Same as SYNC_RECEIPT_TIMEOUT_EXPIRES
+	ANNOUNCE_INTERVAL_TIMEOUT_EXPIRES,	//!< Announce interval timout. Its time to send an announce message if asCapable is true
+	FAULT_DETECTED,						//!< A fault was detected.
+	PDELAY_DEFERRED_PROCESSING,			//!< Defers pdelay processing
+	PDELAY_RESP_RECEIPT_TIMEOUT_EXPIRES,	//!< Pdelay response message timeout
 } Event;
 
 /**
@@ -122,17 +122,17 @@ class ClockIdentity {
 	 * @brief  Constructs the object and sets its ID
 	 * @param  id [in] clock id as an octet array
 	 */
-	ClockIdentity( uint8_t *id ) {
-		set(id);
-	}
-
-	/**
-	 * @brief  Implements the operator '==' overloading method.
-	 * @param  cmp Reference to the ClockIdentity comparing value
-	 * @return TRUE if cmp equals to the object's clock identity. FALSE otherwise
-	 */
-	bool operator==(const ClockIdentity & cmp) const {
-		return memcmp(this->id, cmp.id,
+		ClockIdentity( uint8_t *id ) {
+			set(id);
+		}
+
+		/**
+		 * @brief  Implements the operator '==' overloading method.
+		 * @param  cmp Reference to the ClockIdentity comparing value
+		 * @return TRUE if cmp equals to the object's clock identity. FALSE otherwise
+		 */
+		bool operator==(const ClockIdentity & cmp) const {
+			return memcmp(this->id, cmp.id,
 			      PTP_CLOCK_IDENTITY_LENGTH) == 0 ? true : false;
 	}
 
@@ -173,7 +173,7 @@ class ClockIdentity {
 
 	/**
 	 * @brief  Gets the identity string from the ClockIdentity object
-	 * @param  id [out] Value copied from the object ClockIdentity
+	 * @param  id [out] Value copied from the object ClockIdentity. Needs to be PTP_CLOCK_IDENTITY_LENGTH long.
 	 * @return void
 	 */
 	void getIdentityString(uint8_t *id) {
@@ -191,8 +191,8 @@ class ClockIdentity {
 
 	/**
 	 * @brief  Set clock id based on the link layer address. Clock id is 8 octets
-	 * long whereas link layer address is 6 octets long. This method pads 0xFEFF after the 3
-	 * first octets
+	 * long whereas link layer address is 6 octets long and it is turned into a
+	 * clock identity as per the 802.1AS standard described in clause 8.5.2.2
 	 * @param  address Link layer address
 	 * @return void
 	 */

daemons/gptp/doc/Doxyfile.in

@@ -743,7 +743,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = common linux/src windows/daemon_cl
+INPUT                  = common linux/src windows/daemon_cl doc/mainpage.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -763,7 +763,7 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          = *.hpp
+FILE_PATTERNS          = *.hpp 
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -1352,7 +1352,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.
@@ -1999,7 +1999,7 @@ EXTERNAL_GROUPS        = YES
 # be listed.
 # The default value is: YES.
 
-EXTERNAL_PAGES         = YES
+EXTERNAL_PAGES         = NO
 
 # The PERL_PATH should be the absolute path and name of the perl script
 # interpreter (i.e. the result of 'which perl').

daemons/gptp/doc/mainpage.dox

@@ -0,0 +1,111 @@
+/**
+ * \mainpage gPTP Documentation
+ *
+ * Introduction
+ * ------------
+ * This is an example Intel provided gptp daemon which can be used on Linux
+ * and Windows platforms. There are a number of other ptp daemons available
+ * for Linux which can be used to establish clock synchronization, although
+ * not all may export the required APIs needed for an AVB system.
+ * 
+ * The daemon communicates with other processes through a named pipe.
+ * The pipe name and message format is defined in ipcdef.hpp.  The pipe name 
+ * is "gptp-update". A Windows example is in the project named_pipe_test.
+ * 
+ * The message format is:
+ * 
+ * 	Integer64	<master-local phase offset>
+ * 
+ * 	Integer64	<local-system phase offset>
+ * 
+ * 	Float	<master-local frequency offset>
+ * 
+ * 	Float	<local-system frequency offset>
+ * 
+ * 	UInteger64	< local time of last update>
+ * 
+ * Meaning of IPC provided values
+ * - master  ~= local  - <master-local phase offset>
+ * - local   ~= system - <local-system phase offset>
+ * - Dmaster ~= Dlocal * (1-<master-local phase offset>/1e12) (where D denotes a delta rather than a specific value)
+ * - Dlocal ~= Dsystem * (1-<local-system freq offset>/1e12) (where D denotes a delta rather than a specific value)
+ * 
+ * Linux Specific
+ * -------------
+ * 
+ * Requirements for documentation on a ubuntu based system:
+ *     - cmake: sudo apt-get install cmake
+ *     - doxygen: sudo apt-get install doxygen
+ *     - graphviz: sudo apt-get install graphviz
+ * 
+ * To build, execute the linux/build makefile.
+ * 
+ * To build for I210:
+ * 
+ * ARCH=I210 make clean all
+ * 
+ * To build for 'generic' Linux:
+ * 
+ * make clean all
+ * 
+ * To build for Intel CE 5100 Platforms:
+ * 
+ * ARCH=IntelCE make clean all
+ * 
+ * To execute, run 
+ * 	./daemon_cl <interface-name>
+ * such as
+ * 	./daemon_cl eth0
+ * 
+ * The daemon creates a shared memory segment with the 'ptp' group. Some distributions may not have this group installed.  The IPC interface will not available unless the 'ptp' group is available.
+ * 
+ * 
+ * Windows Version
+ * ---------------
+ * 
+ * Build Dependencies
+ * 
+ * * WinPCAP Developer's Pack (WpdPack) is required for linking - downloadable from http://www.winpcap.org/devel.htm.
+ * 
+ * Extract WpdPack so the Include folder is in one of the below locations
+ * 
+* 1- ProgramData
+* 	\\WpdPack
+* 		\\Include
+* 		\\Lib
+* 		\\Lib\\x64
+* 
+* 2- USERPROFILE
+* 	\\src\\pcap
+* 		\\Include
+* 		\\Lib
+* 		\\Lib\\x64
+* 
+* * WinPCAP must also be installed on any machine where the daemon runs.
+* 
+* To run from the command line:
+* 
+* 	daemon_cl.exe xx-xx-xx-xx-xx-xx
+* 
+* where xx-xx-xx-xx-xx-xx is the mac address of the local interface
+* 
+* Other Available PTP Daemons
+* ---------------------------
+* There are a number of existing ptp daemon projects. Some of the other known 
+* ptp daemons are listed below. Intel has not tested Open AVB with the following 
+* ptp daemons.
+* 
+* * Richard Cochran's ptp4l daemon - https://sourceforge.net/p/linuxptp/
+* 
+*   Note with this version to use gPTP specific settings, which differ 
+*   slightly from IEEE 1588.
+* 
+* * http://ptpd.sourceforge.net/
+* 
+* * http://ptpd2.sourceforge.net/
+* 
+* * http://code.google.com/p/ptpv2d
+* 
+* * http://home.mit.bme.hu/~khazy/ptpd/
+*/
+