Skip to content
Snippets Groups Projects
Commit 6e1cad5f authored by Adam Wujek's avatar Adam Wujek
Browse files

doc: sort tools chapter (no other change) 


Signed-off-by: default avatarAdam Wujek <dev_public@wujek.eu>
parent e3dbef1a
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 156 additions and 156 deletions
doc/ppsi-manual.in
+ 156
− 156
View file @ 6e1cad5f
......@@ -1324,111 +1324,58 @@ Most of them live in the @i{tools} subdirectory and must be built
separately with ``@t{make -C tools}''.
@c ==========================================================================
@node ptpdump
@section ptpdump
This is a sniffer for @sc{ptp} frames. It reports all Ethernet frames and
UDP datagrams that talk @sc{ptp}, from a specific network interface. The
output format is line-oriented to help running @i{grep} over log
files. The number of blank lines between frames depends on how much
time elapsed between them; this should help identifying sync/follow-up
pairs at a glimpse of the eye.
The program receives one optional argument on the command line, which is
the name of the interface where it should listen; by default it uses @t{eth0}.
This is, for example, the dump of two UDP frames:
@smallexample
TIMEDELTA: 977 ms
TIME: (1362504223 - 0x51362a1f) 18:23:43.958091
ETH: 0800 (00:22:15:d7:c0:ef -> 01:00:5e:00:01:81)
IP: 17 (192.168.16.1 -> 224.0.1.129) len 72
UDP: (319 -> 319) len 52
VERSION: 2 (type 0, len 44, domain 0)
FLAGS: 0x0002 (correction 0x00000000)
PORT: 00-22-15-ff-fe-d7-c0-ef-00-01
REST: seq 29, ctrl 0, log-interval 0
MESSAGE: (E) SYNC
MSG-SYNC: 1362504223.957872054
DUMP: payload (size 44)
DUMP: 80 02 00 2c 00 00 02 00 00 00 00 00 00 00 00 00
DUMP: 00 00 00 00 00 22 15 ff fe d7 c0 ef 00 01 00 1d
DUMP: 00 00 00 00 51 36 2a 1f 39 17 f7 b6
TIMEDELTA: 0 ms
TIME: (1362504223 - 0x51362a1f) 18:23:43.958259
ETH: 0800 (00:22:15:d7:c0:ef -> 01:00:5e:00:01:81)
IP: 17 (192.168.16.1 -> 224.0.1.129) len 72
UDP: (320 -> 320) len 52
VERSION: 2 (type 8, len 44, domain 0)
FLAGS: 0x0002 (correction 0x00000000)
PORT: 00-22-15-ff-fe-d7-c0-ef-00-01
REST: seq 29, ctrl 2, log-interval 0
MESSAGE: (G) FOLLOW_UP
MSG-FOLLOW_UP: 1362504223.957953221
DUMP: payload (size 44)
DUMP: 88 02 00 2c 00 00 02 00 00 00 00 00 00 00 00 00
DUMP: 00 00 00 00 00 22 15 ff fe d7 c0 ef 00 01 00 1d
DUMP: 02 00 00 00 51 36 2a 1f 39 19 34 c5
@end smallexample
@node adjrate
@section adjrate
@c ==========================================================================
@node pps-out
@section pps-out
The program reads and optionally changes the clock rate of the host
system using the Linux-specific @i{adjtimex} system call (the same
being used in the core PPSi program). It is meant to check adjustment
and get acquainted with the involved values.
The tool outputs a pulse-per-second signal to a parallel port or a
serial port. Most likely it only works on an x86 Linux system because
of direct access to I/O ports -- no such portability problem is
expected for serial ports. For this reason it is not built by
default in the distributed @t{tools/Makefile}
The numerical argument of the system call is parts-per-million scaled
by 16 bits. For example half @i{ppm} is passed as 32768.
The program receives a single argument on the command line, which is
either an hex port number (with or without leading @t{0x}) or an
absolute filename:
The following are example uses of the program on an ntp-driven host:
@example
./tools/pps-out 378
./tools/pps-out /dev/ttyS0
morgana% ./tools/adjrate --help
./tools/adjrate: use "./tools/adjrate [<adj-value> [ppm]]"
morgana% ./tools/adjrate
rate: -407582 (-6.219208 ppm)
morgana% ./tools/adjrate -6
./tools/adjrate: adjtimex(rate=-6): -1 (Operation not permitted)
morgana% sudo ./tools/adjrate -6 ppm
morgana% sudo ./tools/adjrate
rate: -393216 (-6.000000 ppm)
@end example
When passed a port number, the program toggles all bits assuming it
refers to a parallel port. When passed a pathname, the program assumes
it is a serial port and it toggles the DTR and RTS modem control signals
(on pins 4 and 7 of the DB9 male connector).
By setting the @t{VERBOSE} environment variable the program
reports how late it was before and after generating the rising
edge:
@c ==========================================================================
@node adjtime
@section adjtime
@example
morgana$ VERBOSE=1 ./tools/pps-out /dev/ttyS0
gettimeofday takes 0.2 usec
udelay takes 4.0 usec
delayed between 0 and 2 usecs
delayed between 0 and 4 usecs
[...]
@end example
This program works like @i{jmptime}, but it requests a slow adjustment
of the time. It receives the requested adjustment on the command
line, as a floating point number just like @i{jmptime} described
above. Additionally, it reports what was the ongoing adjustment
using @i{adjtime}. See the @t{adjtime(2)} man page for details.
@t{pps-out} can be used to verify on a scope the level of
synchronization of two or more computers, but please note that the
user-space software-only approach shows some jitter; on example systems the
delay is usually a few microseconds, up to around a dozen (in general,
use of the parallel port has less delay and less jitter). In any case
this offers a second source to check what NTP or @sc{ptp} daemons report.
Adjustments requested by this program cannot be reported by
@i{tools/chktime}, even when the overall change integrates to more
than half a millisecond, because the change in clock speed affects
both @t{CLOCK_REALTIME} and @t{CLOCK_MONOTONIC}.
@c ==========================================================================
@node jmptime
@section jmptime
The adjustment can be seen in one host by comparing with the time of another
host, for example using @i{tools/mtp}, described in the next section.
The program uses @i{settimeofday} to make the local time jump forward
or backward by some amount, specified as floating-point seconds:
The following example shows how on an example host the kernel adjusts the time
by 15ms every 30s (i.e. 0.05%):
@example
# date +%H:%M:%S; ./tools/jmptime 1.32; date +%H:%M:%S
12:24:28
Requesting time-jump: 1.320000 seconds
12:24:29
# ./tools/adjtime .15; sleep 30; ./tools/adjtime 0
Requesting adjustment: 0.150000 seconds
Previous adjustment: 0.000000 seconds
Requesting adjustment: 0.000000 seconds
Previous adjustment: 0.135000 seconds
@end example
@c ==========================================================================
......@@ -1457,58 +1404,48 @@ For example, this is what @i{chktime} reports when running
@end example
@c ==========================================================================
@node adjtime
@section adjtime
This program works like @i{jmptime}, but it requests a slow adjustment
of the time. It receives the requested adjustment on the command
line, as a floating point number just like @i{jmptime} described
above. Additionally, it reports what was the ongoing adjustment
using @i{adjtime}. See the @t{adjtime(2)} man page for details.
Adjustments requested by this program cannot be reported by
@i{tools/chktime}, even when the overall change integrates to more
than half a millisecond, because the change in clock speed affects
both @t{CLOCK_REALTIME} and @t{CLOCK_MONOTONIC}.
The adjustment can be seen in one host by comparing with the time of another
host, for example using @i{tools/mtp}, described in the next section.
@node jmptime
@section jmptime
The following example shows how on an example host the kernel adjusts the time
by 15ms every 30s (i.e. 0.05%):
The program uses @i{settimeofday} to make the local time jump forward
or backward by some amount, specified as floating-point seconds:
@example
# ./tools/adjtime .15; sleep 30; ./tools/adjtime 0
Requesting adjustment: 0.150000 seconds
Previous adjustment: 0.000000 seconds
Requesting adjustment: 0.000000 seconds
Previous adjustment: 0.135000 seconds
# date +%H:%M:%S; ./tools/jmptime 1.32; date +%H:%M:%S
12:24:28
Requesting time-jump: 1.320000 seconds
12:24:29
@end example
@c ==========================================================================
@node adjrate
@section adjrate
The program reads and optionally changes the clock rate of the host
system using the Linux-specific @i{adjtimex} system call (the same
being used in the core PPSi program). It is meant to check adjustment
and get acquainted with the involved values.
@node MAKEALL
@section MAKEALL
The numerical argument of the system call is parts-per-million scaled
by 16 bits. For example half @i{ppm} is passed as 32768.
The @i{MAKEALL} script, in the top-level directory of PPSi builds the
program for all known configurations, picking them from @t{configs/}.
Developers are urged to run it
before committing each patch, to ensure they are not breaking the
program for configurations they are not using.
It may happen, however, that some developers experience errors or
warnings that others didn't notice, because of differences in compiler
version or library versions.
The following are example uses of the program on an ntp-driven host:
@t{MAKEALL} builds all configurations by default, but it can also be
forced to build only specific configs by listing them on its command line.
Here's an example showing the build of just a couple configurations:
@example
morgana% ./tools/adjrate --help
./tools/adjrate: use "./tools/adjrate [<adj-value> [ppm]]"
morgana% ./tools/adjrate
rate: -407582 (-6.219208 ppm)
morgana% ./tools/adjrate -6
./tools/adjrate: adjtimex(rate=-6): -1 (Operation not permitted)
morgana% sudo ./tools/adjrate -6 ppm
morgana% sudo ./tools/adjrate
rate: -393216 (-6.000000 ppm)
% ./MAKEALL bare-i386_defconfig sim_defconfig
##### Building with 'bare-i386_defconfig'
text data bss dec hex filename
28057 1356 976 30389 76b5 ppsi.o
27347 1356 976 29679 73ef ppsi
##### Building with 'sim_defconfig'
text data bss dec hex filename
39996 1744 556 42296 a538 ppsi.o
43428 2544 624 46596 b604 ppsi
@end example
@c ==========================================================================
......@@ -1549,36 +1486,99 @@ frames (@t{AF_PACKET}). It needs an interface name as first argument
and superuser privileges.
@c ==========================================================================
@node MAKEALL
@section MAKEALL
@node pps-out
@section pps-out
The @i{MAKEALL} script, in the top-level directory of PPSi builds the
program for all known configurations, picking them from @t{configs/}.
Developers are urged to run it
before committing each patch, to ensure they are not breaking the
program for configurations they are not using.
It may happen, however, that some developers experience errors or
warnings that others didn't notice, because of differences in compiler
version or library versions.
The tool outputs a pulse-per-second signal to a parallel port or a
serial port. Most likely it only works on an x86 Linux system because
of direct access to I/O ports -- no such portability problem is
expected for serial ports. For this reason it is not built by
default in the distributed @t{tools/Makefile}
@t{MAKEALL} builds all configurations by default, but it can also be
forced to build only specific configs by listing them on its command line.
Here's an example showing the build of just a couple configurations:
The program receives a single argument on the command line, which is
either an hex port number (with or without leading @t{0x}) or an
absolute filename:
@example
./tools/pps-out 378
./tools/pps-out /dev/ttyS0
@end example
% ./MAKEALL bare-i386_defconfig sim_defconfig
##### Building with 'bare-i386_defconfig'
text data bss dec hex filename
28057 1356 976 30389 76b5 ppsi.o
27347 1356 976 29679 73ef ppsi
##### Building with 'sim_defconfig'
text data bss dec hex filename
39996 1744 556 42296 a538 ppsi.o
43428 2544 624 46596 b604 ppsi
When passed a port number, the program toggles all bits assuming it
refers to a parallel port. When passed a pathname, the program assumes
it is a serial port and it toggles the DTR and RTS modem control signals
(on pins 4 and 7 of the DB9 male connector).
By setting the @t{VERBOSE} environment variable the program
reports how late it was before and after generating the rising
edge:
@example
morgana$ VERBOSE=1 ./tools/pps-out /dev/ttyS0
gettimeofday takes 0.2 usec
udelay takes 4.0 usec
delayed between 0 and 2 usecs
delayed between 0 and 4 usecs
[...]
@end example
@t{pps-out} can be used to verify on a scope the level of
synchronization of two or more computers, but please note that the
user-space software-only approach shows some jitter; on example systems the
delay is usually a few microseconds, up to around a dozen (in general,
use of the parallel port has less delay and less jitter). In any case
this offers a second source to check what NTP or @sc{ptp} daemons report.
@c ==========================================================================
@node ptpdump
@section ptpdump
This is a sniffer for @sc{ptp} frames. It reports all Ethernet frames and
UDP datagrams that talk @sc{ptp}, from a specific network interface. The
output format is line-oriented to help running @i{grep} over log
files. The number of blank lines between frames depends on how much
time elapsed between them; this should help identifying sync/follow-up
pairs at a glimpse of the eye.
The program receives one optional argument on the command line, which is
the name of the interface where it should listen; by default it uses @t{eth0}.
This is, for example, the dump of two UDP frames:
@smallexample
TIMEDELTA: 977 ms
TIME: (1362504223 - 0x51362a1f) 18:23:43.958091
ETH: 0800 (00:22:15:d7:c0:ef -> 01:00:5e:00:01:81)
IP: 17 (192.168.16.1 -> 224.0.1.129) len 72
UDP: (319 -> 319) len 52
VERSION: 2 (type 0, len 44, domain 0)
FLAGS: 0x0002 (correction 0x00000000)
PORT: 00-22-15-ff-fe-d7-c0-ef-00-01
REST: seq 29, ctrl 0, log-interval 0
MESSAGE: (E) SYNC
MSG-SYNC: 1362504223.957872054
DUMP: payload (size 44)
DUMP: 80 02 00 2c 00 00 02 00 00 00 00 00 00 00 00 00
DUMP: 00 00 00 00 00 22 15 ff fe d7 c0 ef 00 01 00 1d
DUMP: 00 00 00 00 51 36 2a 1f 39 17 f7 b6
TIMEDELTA: 0 ms
TIME: (1362504223 - 0x51362a1f) 18:23:43.958259
ETH: 0800 (00:22:15:d7:c0:ef -> 01:00:5e:00:01:81)
IP: 17 (192.168.16.1 -> 224.0.1.129) len 72
UDP: (320 -> 320) len 52
VERSION: 2 (type 8, len 44, domain 0)
FLAGS: 0x0002 (correction 0x00000000)
PORT: 00-22-15-ff-fe-d7-c0-ef-00-01
REST: seq 29, ctrl 2, log-interval 0
MESSAGE: (G) FOLLOW_UP
MSG-FOLLOW_UP: 1362504223.957953221
DUMP: payload (size 44)
DUMP: 88 02 00 2c 00 00 02 00 00 00 00 00 00 00 00 00
DUMP: 00 00 00 00 00 22 15 ff fe d7 c0 ef 00 01 00 1d
DUMP: 02 00 00 00 51 36 2a 1f 39 19 34 c5
@end smallexample
@c ##########################################################################
@node Build Details
@chapter Build Details
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment