doc: describe time- split and general review/udate

Signed-off-by: Alessandro Rubini <rubini@gnudd.com>

doc: describe time- split and general review/udate
Signed-off-by: Alessandro Rubini <rubini@gnudd.com>
e64e6194 · Alessandro Rubini · 97c0c129 · e64e6194
Commit e64e6194 authored May 29, 2013 by Alessandro Rubini
Hide whitespace changes
Inline Side-by-side

Showing with 86 additions and 69 deletions

ppsi-manual.in doc/ppsi-manual.in +86 -69

No files found.
--- a/doc/ppsi-manual.in
+++ b/doc/ppsi-manual.in
@@ -35,7 +35,7 @@
 @setchapternewpage off
-@set update-month March 2013
+@set update-month May 2013
 @finalout
@@ -110,13 +110,13 @@ The home page of the PPSi project and the source repository are:
 @node Status Features and Bugs
 @chapter Status, Features, Bugs
-This document, written in March 2013, tries to summarize the status of
+This document tries to summarize the status of
-the project, but this month we are working a lot on the package,
+the project, but we are working a lot on the package,
 so information here may be slightly out of date with respect to code.
-The software package is designed to be modular: both architectures
+The software package is designed to be modular: each of architectures,
-and protocols can be replaced by providing a proper subdirectory. This
+protocols and timing engine
-will soon apply to time-related functionality as well.
+ can be replaced by providing a proper subdirectory.
 @c ==========================================================================
 @node Architectures
@@ -141,20 +141,36 @@ The package currently supports the following architectures:
        likely works on @sc{bsd} and other variants as well. We may
        change naming accordingly, after identifying the weak
        (i.e. unportable) points.  This architecture supports the standard
-        protocol on both @sc{udp} and raw Ethernet (but currently not both
+        protocol on both @sc{udp} and raw Ethernet, also both at the
-        at the same time).
+        same time thanks to the per-link split of I/O methods.
+        The architecture relies on @i{time-unix}, but it supports
+        building with different time engines.
+@item wrs
+	The White Rabbit switch build of PPSi is designed to be a
+        separate architecture, even if the switch itself is a Linux
+        system running on an ARM processor.  The switch is a complex
+        system, with several daemons cooperating through an IPC
+        mechanism: the standard main loop for a standalone Unix daemon
+        doesn't apply to the WR switch, and modelling it as a
+        separate architecture is the simplest and cleanest approach,
+        in our opinion (even if it leads to some code duplication).
+        The architectures relies on @i{time-wrs}.   
 @item wrpc
 	The @i{White Rabbit PTP Core} architecture is a port of PPSi to
        run on our I/O devices. The @i{wrpc} is a ``@i{core}'', i.e. a
-        logic block, that runs in WR-capable I/O cards; most such cards
+        logic block, that runs in WR-capable I/O cards. Most such cards
-        are developed as open hardware on @i{ohwr.org}.
+        are developed as open hardware on @i{ohwr.org}; examples are
-        @i{wrpc} includes a soft-core
+        the @sc{spec} (a PCIe carrier for FMC devices) and the @sc{svec}
+        (a VME carrier, with two FMC slots driver by the same WR core).
+        The @i{wrpc} includes a soft-core
        @sc{cpu} that runs the @sc{wr-ptp} daemon.  PPSi is designed to
        be able to be linked from @i{wrpc-sw} as its own @i{wr-ptp}
        engine. PPSi in this environment currently supports only raw
-        Ethernet, not @sc{udp}.
+        Ethernet, not @sc{udp}.  The architecture uses @i{time-wrpc}.
 @item bare-i386
@@ -172,7 +188,8 @@ The package currently supports the following architectures:
 	Like @i{bare-i386}, this architectures makes direct system calls
        without relying on external libraries. The host in this case is
-        the a 64-bit PC instead of a 32-bit one.
+        the a 64-bit PC instead of a 32-bit one. Both bare ports use
+        @i{time-bare} for their timing operations.
 @end table
@@ -190,12 +207,13 @@ selected by setting @t{PROTO_EXT=whiterabbit}, but there's nothing that
 prevents our fellow developers to support their own @i{ptp} extension
 using PPSi.
-Each directory lives in a subdirectory called @t{proto-ext-}@i{name}.
+Each extension lives in a subdirectory called @t{proto-ext-}@i{name}.
 Source files in that directory may override the implementation for the
 standard protocol (which lives in @t{proto-standard}) to provide their
-own functionalities.  To simplify extensions, the @i{proto-standard}
+own functionalities.  To simplify writing extensions, the @i{proto-standard}
-functions already provide @i{hooks} for extensions to provide
+functions already provide @i{hooks} so the extension itself can provide
-callbacks.  The set of callbacks is currently based on the needs of
+callbacks while still using the basic PTP engine.
+The set of callbacks is currently based on the needs of
 WR, but we are willing to accept patches to provide more hooks as
 needed.
@@ -206,15 +224,31 @@ refer to how @i{proto-ext-whiterabbit} is implemented.
 @node Time Functions and Network Operations
 @section Time Functions and Network Operations
-The current code base uses data structures to collect in a single
+PPSi supports custom implementations of time functions, so you can
-entry point all functions related to the time and all functions
+easily port the daemon to your own timing primitives.
-related to the network.
+The subdirectories named @i{time-sth} are used to implement timing
-While we still miss @t{time-} and @t{net-} directories to split off
+functions; timing includes the methods that are part of two data
-specific implementations, the code is designed to allow such a split
+structures: @i{pp_time_operations} and @i{pp_network_operations}.  The
-at a later time.  For example, the Linux-specific way to interface
+former structure deals with getting and setting system time, while the
-with hardware-timestamping in network cards can be implemented as a
+latter deals with frame tx and rx. Network operations are concerned
-separate @i{time} module.
+with timestamping the actual I/O, and that's why they are considered
+part of the ``timing'' of PPSi.
+Each architecture defines its own @t{TIME=} choice in the specific
+@t{Makefile}.  The user can override the default by either setting the
+variable on the command line of PPSi, or by setting an environment
+variable if the architecture supports it.  For example, the @i{bare}
+architectures force @t{TIME=bare}, while the @i{unix} architecture
+suggests Unix timing code (@t{TIME?=unix}).
+If you want to support a different timing engine within the Unix build
+system, you can use ``@t{make TIME=xyz}'' to request building
+the@u{time-xyz} subdirectory.  Please note that the Unix time
+structures are built anyways, so you can piggy-back on those
+functions, either within your own methods or by replacing the
+@t{ppi->t_ops} and @t{ppi->n_ops} for the communications links that do
+not include your own hardware support.
 @c ==========================================================================
 @node Features
@@ -243,13 +277,15 @@ unfair to hide them.
 @item Support both hosted and freestanding environments.
 	This is already supported, though we still lack a microcontroller
-        implementation.
+        implementation, and our only freestanding environment is @i{wrpc},
+        running on an LM32 processor.
 @item Support multi-link operation.
-	This is being worked on during March 2013. We currently only
+	The daemon manages several links at the same time, being master
-        run a single link as either master or slave (using the Best Master
+        slave or auto-detect independently on each link.
-        Clock protocol to select the master).
+        The @i{best master clock} algorithm is run globally,
+        but communication and timeouts are managed per-link.
 @item Support both @sc{udp} and raw Ethernet.
@@ -261,16 +297,15 @@ unfair to hide them.
 @item Support fall-back master links.
-	This is needed for WR, but it depends on multi-link operation.
+	This is needed for WR, and is being worked on.
        We need to track more than one master in order to switch over
        from one to the other within a few milliseconds and with no
        time glitches.
-@item Support hardware timestamping when available.
+@item Support hardware timestamping where available.
-	This is not yet implemented for the generic protocol.
+	This is not yet implemented for the generic protocol, but we
-        @i{arch-wrpc} supports hardware timestamping but that's
+        plan to add at least @i{time-linux-tstamp} soon.
-        a special case because WR requires its own special hardware.
 @item Support @sc{bsd} specifics.
@@ -304,15 +339,11 @@ unfair to hide them.
 @node Bugs
 @section Bugs
-As of 2013-03-11 the following known bugs are being worked on:
+As of 2013-05 the project suffers from these known bugs:
 @itemize
-@item @i{adjtimex} is not invoked properly on the host. The daemon
-      fixes the slave time when it is off by more than one second by
-      jumping to the proper value, but the smooth adjustment for errors
-      smaller than one second is not currently working.
 @item All frames must be sent according to a pseudo-random distribution;
-      this is not completely verified.
+      this is mostly in place but mut be audited project-wide.
 @item We removed @i{peer-delay} support. Maybe this is a feature, we
      are still shaping our mind about that, but for the time being we
      don't plan to support peer-delay because it would be academic and
@@ -396,26 +427,9 @@ commented.
 We introduced the diagnostic macros described above at the beginning
 of March 2013.  Earlier code used a less-structured approach, which is
 still used in parts of the code and is being slowly phased away.
+As of May 2013 we still have a pair of uses of @t{PP_PRINTF},
-The older conventions are implemented in the initial par of
+but we'll kill them soon.  To help our users not add such calls,
-@t{<ppsi/diag-macros.h>}.  Here we have a global @t{pp_diag_verbosity}
+we are not documenting it any more.
-flag, which is incremented by each ``@t{-V}'' flag on the command line,
-and two macros: @t{PP_PRINTF} and @t{PP_VPRINTF}.  The former becomes
-a @i{pp_printf} call if the global verbosity is greater than zero
-and the latter is turned into a message if the global verbosity
-is bigger than 1.
-Moreover, you can build the code without all such diagnostic code by
-setting @t{CONFIG_PPSI_VERBOSITY} to zero.  Again, this was meant to
-shrink the resulting binary file, and we really had size issues with
-@i{arch-wrpc}, before a code cleanup that finally solved the problem
-for us.
-Finally, PPSi up to 2013-01 had no diagnostics by default and used the
-environment variables @t{HAS_DIAG} and @t{HAS_FULL_DIAG}. They are not
-used any more and the Makefile warns about them, to ease previous
-users.
 @c ==========================================================================
 @node Printf
@@ -714,21 +728,24 @@ without the complete source code and associated rights. You may avoid
 the GPL requirements by using different printf implementations; if so
 we'd love to have them contributed back in the package.
-For binaries without diagnostic code, the LGPL applies, as detailed
+The same issue about the GPL license applies to the @i{div64_32}
-below.
+function.  We need this implementation in our @i{wrpc} code base
+because the default @i{libgcc} division is very big, and we are always
+tight with our in-FPGA memory space.
+For binaries without diagnostic code and the size-optimized division,
+the LGPL applies, as detailed below.
 For licensing purposes, any `arch-name' or `time-name' subdirectory
 "can be reasonably considered independent and separate works in
-themselves". While code in the directories provided here is all LGPL,
+themselves" (quoting the LPGL text).
+Code in the directories provided here is all LGPL, and
 you may add your own drop-in subdirectories. The LGPL requirements for
 source distribution and associated permissions won't apply to any such
-subdirectory that you may add, even if technically such code si not
+subdirectory that you may add, even if technically such code is not
 linked as a library.
-Currently, there is no `time-' support, it will be added in a way
-similar to what you already see for `arch-'.
 @c ##########################################################################
 @node Coding Style and Conventions
 @chapter Coding Style and Conventions