Progress on the media layer

doc_source/doxygen-bootstrapped/customdoxygen.css

@@ -108,6 +108,8 @@ font-size: 1.15em !important;
 }
 .navbar{
  border: 0px solid #222 !important;
+ padding-left: 1em;
+ padding-right: 1em;
 }
 table{
     white-space:pre-wrap !important;

doc_source/doxygen.ini

@@ -487,15 +487,15 @@ EXTRACT_ANON_NSPACES   = NO
 # section is generated. This option has no effect if EXTRACT_ALL is enabled.
 # The default value is: NO.
 
-HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_MEMBERS     = YES
 
 # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
 # undocumented classes that are normally visible in the class hierarchy. If set
 # to NO, these classes will be included in the various overviews. This option
 # has no effect if EXTRACT_ALL is enabled.
 # The default value is: NO.
 
-HIDE_UNDOC_CLASSES     = NO
+HIDE_UNDOC_CLASSES     = YES
 
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
 # (class|struct|union) declarations. If set to NO, these declarations will be
@@ -552,7 +552,7 @@ SHOW_INCLUDE_FILES     = YES
 # which file to include in order to use the member.
 # The default value is: NO.
 
-SHOW_GROUPED_MEMB_INC  = NO
+SHOW_GROUPED_MEMB_INC  = YES
 
 # If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include
 # files with double quotes in the documentation rather than with sharp brackets.

doc_source/footer.html

@@ -16,7 +16,12 @@
 </div>
 </div>
 <!--BEGIN !GENERATE_TREEVIEW-->
-<hr class="footer"/>
+<address class="footer-copyright"><small>
+  <a href="https://uavcan.org">UAVCAN</a>
+  – Copyright (C) 2014-1029 Pavel Kirienko <pavel.kirienko@gmail.com>
+  – Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved
+  – This documentation is provided under the MIT licence as part of the <a href="https://github.com/UAVCAN/libuavcan/blob/master/LICENSE">libuavcan project</a>.
+  </small></address>
 <!--END !GENERATE_TREEVIEW-->
 </body>
         <script type="text/javascript" src="$relpath^doxy-boot.js"></script>

libuavcan/include/libuavcan/build_config.hpp

@@ -2,6 +2,10 @@
  * Copyright (C) 2014 Pavel Kirienko <pavel.kirienko@gmail.com>
  * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  */
+/**
+ * @file
+ * Build-time configuration macros, templates, and constant expressions.
+ */
 
 #ifndef LIBUAVCAN_BUILD_CONFIG_HPP_INCLUDED
 #define LIBUAVCAN_BUILD_CONFIG_HPP_INCLUDED
@@ -62,6 +66,14 @@
 #    define LIBUAVCAN_EXPORT
 #endif
 
+/**
+ * Allows selecting the size of the microsecond timestamp type used by libuavcan.
+ * Valid values are 8, 4, and 2.
+ */
+#ifndef LIBUAVCAN_MICROSECOND_SIZE_BYTES
+#    define LIBUAVCAN_MICROSECOND_SIZE_BYTES 8
+#endif
+
 /** @} */  // end of macros_platform
 
 #endif  // LIBUAVCAN_BUILD_CONFIG_HPP_INCLUDED

libuavcan/include/libuavcan/introspection.hpp

@@ -1,11 +1,13 @@
 /*
+ * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ */
+/**
+ * @file
  * Optional utilites to provide introspection into libuavcan
  * objects and to provide metrics for library performance.
  * Facilities defined in this header can be compiled out of
  * production code and should be used for debugging or targeted
  * testing activities.
- *
- * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  */
 
 #ifndef LIBUAVCAN_INTROSPECTION_HPP_INCLUDED

libuavcan/include/libuavcan/libuavcan.hpp

@@ -1,10 +1,11 @@
 /*
  * Copyright (C) 2014 Pavel Kirienko <pavel.kirienko@gmail.com>
  * Copyright 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
- *
+ */
+/**
+ * @file
  * This header should be included by the user application.
  */
-/** @file */
 #include "libuavcan/build_config.hpp"
 
 #include <cstdint>

libuavcan/include/libuavcan/time.hpp

@@ -13,19 +13,42 @@
 #include "libuavcan/libuavcan.hpp"
 #include "libuavcan/util/math.hpp"
 
+/**
+ * @namespace libuavcan
+ * The top-level namespace which contains all  types, definitions, and nested
+ * namespaces for libuavcan.
+ */
 namespace libuavcan
 {
+#if LIBUAVCAN_MICROSECOND_SIZE_BYTES == 8
+using DefaultMicrosecondSignedType   = std::int64_t;
+using DefaultMicrosecondUnsignedType = std::uint64_t;
+#elif LIBUAVCAN_MICROSECOND_SIZE_BYTES == 4
+using DefaultMicrosecondSignedType   = std::int32_t;
+using DefaultMicrosecondUnsignedType = std::uint32_t;
+#elif LIBUAVCAN_MICROSECOND_SIZE_BYTES == 2
+using DefaultMicrosecondSignedType   = std::int16_t;
+using DefaultMicrosecondUnsignedType = std::uint16_t;
+#else
+#    error LIBUAVCAN_MICROSECOND_SIZE_BYTES is not a valid integer size for this library.
+#endif
+
 namespace duration
 {
 /**
- * Protected base class for duration values.
+ * Protected base class for duration values. This provides a common implementation for
+ * various duration datatypes and enforces two concepts:
+ *
+ * -# duration math is saturing – MAX_DURATION + 1 == MAX_DURATION
+ * -# durations are signed integers – By default 8 byte integers but USecT can be redefined by
+ *    a specialization.
  *
  * @tparam Type          The type of the derived class. This must be an empty type.
  *                       All storage will be provided by this base class.
  * @tparam USecT         The datatype returned when retrieving durations from
  *                       realizations of this base class. This type must be signed.
  */
-template <typename Type, typename USecT = std::int64_t>
+template <typename Type, typename USecT = libuavcan::DefaultMicrosecondSignedType>
 class Base
 {
     USecT usec_; /**< Internal storage of the duration value in microseconds. */
@@ -59,31 +82,45 @@ class Base
     }
 
 public:
+    /**
+     * The underlying datatype for microsecond values. This must be signed for duration types.
+     */
     using MicrosecondType = USecT;
-    using DurationType    = Type;
 
-    static Type getInfinite()
+    /**
+     * The specialized type of this base duration type.
+     */
+    using DurationType = Type;
+
+    /**
+     * Get the largest possible number of microseconds this type can store.
+     */
+    static Type getMaximum()
     {
         return fromMicrosecond(std::numeric_limits<USecT>::max());
     }
 
+    /**
+     * Construct an instance of Type from a microsecond value.
+     */
     static Type fromMicrosecond(USecT us)
     {
         Type d;
         d.usec_ = us;
         return d;
     }
 
+    /**
+     * Obtain the underlying microsecond value without conversion.
+     */
     USecT toMicrosecond() const
     {
         return usec_;
     }
 
-    USecT toMillisecond() const
-    {
-        return usec_ / static_cast<USecT>(1000);
-    }
-
+    /**
+     * Get the absolute value of the duration as a duration type.
+     */
     Type getAbs() const
     {
         return Type::fromMicrosecond(std::abs(usec_));
@@ -144,7 +181,14 @@ class Base
 
     Type operator-() const
     {
-        return fromMicrosecond(-usec_);
+        if (usec_ == std::numeric_limits<USecT>::max())
+        {
+            return fromMicrosecond(std::numeric_limits<USecT>::min() + 1);
+        }
+        else
+        {
+            return fromMicrosecond(-usec_);
+        }
     }
 
     Type& operator+=(const Type& r)
@@ -160,6 +204,9 @@ class Base
     }
 };
 
+/**
+ * A monotonic duration used by libuavcan.
+ */
 class LIBUAVCAN_EXPORT Monotonic : public Base<Monotonic>
 {};
 
@@ -177,7 +224,7 @@ namespace time
  * @tparam USecT         The datatype returned when retrieving time from
  *                       realizations of this base class. This type must be unsigned.
  */
-template <typename Type, typename DType, typename USecT = std::uint64_t>
+template <typename Type, typename DType, typename USecT = DefaultMicrosecondUnsignedType>
 class Base
 {
     USecT usec_;
@@ -214,31 +261,42 @@ class Base
     }
 
 public:
+    /**
+     * The underlying datatype for microsecond values. This must be unsigned for time types.
+     */
     using MicrosecondType = USecT;
-    using DurationType    = DType;
 
-    static Type getMax()
+    /**
+     * The specialized type of this base time type.
+     */
+    using DurationType = DType;
+
+    /**
+     * Get the largest possible number of microseconds this type can store.
+     */
+    static Type getMaximum()
     {
         return fromMicrosecond(std::numeric_limits<USecT>::max());
     }
 
+    /**
+     * Construct an instance of Type from a microsecond value.
+     */
     static Type fromMicrosecond(USecT us)
     {
         Type t;
         t.usec_ = us;
         return t;
     }
 
+    /**
+     * Obtain the underlying microsecond value without conversion.
+     */
     USecT toMicrosecond() const
     {
         return usec_;
     }
 
-    USecT toMillisecond() const
-    {
-        return usec_ / static_cast<USecT>(1000);
-    }
-
     Base& operator=(Base&& rhs)
     {
         usec_     = rhs.usec_;
@@ -292,11 +350,6 @@ class Base
         return fromMicrosecond(libuavcan::util::saturating_sub(usec_, r.toMicrosecond()));
     }
 
-    DType operator-(const Type& r) const
-    {
-        return DType::fromMicrosecond(libuavcan::util::saturating_sub(usec_, r.toMicrosecond()));
-    }
-
     Type& operator+=(const DType& r)
     {
         *this = *this + r;
@@ -310,6 +363,9 @@ class Base
     }
 };
 
+/**
+ * A monotonic time value used by libuavcan.
+ */
 class LIBUAVCAN_EXPORT Monotonic : public Base<Monotonic, duration::Monotonic>
 {};
 

libuavcan/include/libuavcan/transport/media/can.hpp

@@ -12,6 +12,7 @@
 
 #include "libuavcan/libuavcan.hpp"
 #include "libuavcan/introspection.hpp"
+#include "libuavcan/time.hpp"
 
 namespace libuavcan
 {
@@ -259,6 +260,12 @@ struct LIBUAVCAN_EXPORT Frame
      */
     std::uint32_t id;
 
+    /**
+     * A monotonic timestamp. Libuavcan operates optimally when this value is a
+     * hardware supplied timestamp recorded at the start-of-frame.
+     */
+    libuavcan::time::Monotonic timestamp;
+
     /**
      * System memory buffer of a CAN frame.
      *
@@ -271,19 +278,23 @@ struct LIBUAVCAN_EXPORT Frame
 public:
     Frame()
         : id(0)
+        , timestamp()
         , data{}
         , dlc_(FrameDLC::CodeForLength0)
     {}
 
     /**
-     * Constructs a new Frame object that copies data into this instance.
+     * Constructs a new Frame object with timestamp that copies data into this instance.
      *
-     * @param can_id    The 29-bit CAN id.
-     * @param can_data  The data to copy into this instance.
-     * @param in_dlc    The data length code for the can_data.
+     * @param can_id        The 29-bit CAN id.
+     * @param can_timestamp A monotonic timestamp that should be as close to the time the start-of-frame was
+     *                      received (for rx frames) or put-on-bus (for tx frames) as possible.
+     * @param can_data      The data to copy into this instance.
+     * @param in_dlc        The data length code for the can_data.
      */
-    Frame(std::uint32_t can_id, const std::uint8_t* can_data, FrameDLC in_dlc)
+    Frame(std::uint32_t can_id, libuavcan::time::Monotonic can_timestamp, const std::uint8_t* can_data, FrameDLC in_dlc)
         : id(can_id)
+        , timestamp(can_timestamp)
         , data{}
         , dlc_(in_dlc)
     {
@@ -298,6 +309,17 @@ struct LIBUAVCAN_EXPORT Frame
         }
     }
 
+    /**
+     * Constructs a new Frame object that copies data into this instance.
+     *
+     * @param can_id        The 29-bit CAN id.
+     * @param can_data      The data to copy into this instance.
+     * @param in_dlc        The data length code for the can_data.
+     */
+    Frame(std::uint32_t can_id, const std::uint8_t* can_data, FrameDLC in_dlc)
+        : Frame(can_id, libuavcan::time::Monotonic::fromMicrosecond(0), can_data, in_dlc)
+    {}
+
     /**
      * Get the Data Length Code set for this instance.
      *