From 28aedd7ee214eb63a2e6924b5ec2b081aa7b3953 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 12 Jun 2019 14:52:56 -0300 Subject: docs: pps.txt: convert to ReST and rename to pps.rst This file is already in a good shape: just its title and adding some literal block markups is needed for it to be part of the document. While it has a small chapter with sysfs stuff, most of the document is focused on driver development. As it describes a kernel API, move it to the driver-api directory. In order to avoid conflicts, let's add an :orphan: tag to it, to be removed when added to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Rodolfo Giometti Signed-off-by: Jonathan Corbet --- Documentation/driver-api/pps.rst | 242 +++++++++++++++++++++++++++++++++++++++ Documentation/pps/pps.txt | 239 -------------------------------------- MAINTAINERS | 2 +- 3 files changed, 243 insertions(+), 240 deletions(-) create mode 100644 Documentation/driver-api/pps.rst delete mode 100644 Documentation/pps/pps.txt diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst new file mode 100644 index 000000000000..1456d2c32ebd --- /dev/null +++ b/Documentation/driver-api/pps.rst @@ -0,0 +1,242 @@ +:orphan: + +====================== +PPS - Pulse Per Second +====================== + +Copyright (C) 2007 Rodolfo Giometti + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + + + +Overview +-------- + +LinuxPPS provides a programming interface (API) to define in the +system several PPS sources. + +PPS means "pulse per second" and a PPS source is just a device which +provides a high precision signal each second so that an application +can use it to adjust system clock time. + +A PPS source can be connected to a serial port (usually to the Data +Carrier Detect pin) or to a parallel port (ACK-pin) or to a special +CPU's GPIOs (this is the common case in embedded systems) but in each +case when a new pulse arrives the system must apply to it a timestamp +and record it for userland. + +Common use is the combination of the NTPD as userland program, with a +GPS receiver as PPS source, to obtain a wallclock-time with +sub-millisecond synchronisation to UTC. + + +RFC considerations +------------------ + +While implementing a PPS API as RFC 2783 defines and using an embedded +CPU GPIO-Pin as physical link to the signal, I encountered a deeper +problem: + + At startup it needs a file descriptor as argument for the function + time_pps_create(). + +This implies that the source has a /dev/... entry. This assumption is +OK for the serial and parallel port, where you can do something +useful besides(!) the gathering of timestamps as it is the central +task for a PPS API. But this assumption does not work for a single +purpose GPIO line. In this case even basic file-related functionality +(like read() and write()) makes no sense at all and should not be a +precondition for the use of a PPS API. + +The problem can be simply solved if you consider that a PPS source is +not always connected with a GPS data source. + +So your programs should check if the GPS data source (the serial port +for instance) is a PPS source too, and if not they should provide the +possibility to open another device as PPS source. + +In LinuxPPS the PPS sources are simply char devices usually mapped +into files /dev/pps0, /dev/pps1, etc. + + +PPS with USB to serial devices +------------------------------ + +It is possible to grab the PPS from an USB to serial device. However, +you should take into account the latencies and jitter introduced by +the USB stack. Users have reported clock instability around +-1ms when +synchronized with PPS through USB. With USB 2.0, jitter may decrease +down to the order of 125 microseconds. + +This may be suitable for time server synchronization with NTP because +of its undersampling and algorithms. + +If your device doesn't report PPS, you can check that the feature is +supported by its driver. Most of the time, you only need to add a call +to usb_serial_handle_dcd_change after checking the DCD status (see +ch341 and pl2303 examples). + + +Coding example +-------------- + +To register a PPS source into the kernel you should define a struct +pps_source_info as follows:: + + static struct pps_source_info pps_ktimer_info = { + .name = "ktimer", + .path = "", + .mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT | + PPS_ECHOASSERT | + PPS_CANWAIT | PPS_TSFMT_TSPEC, + .echo = pps_ktimer_echo, + .owner = THIS_MODULE, + }; + +and then calling the function pps_register_source() in your +initialization routine as follows:: + + source = pps_register_source(&pps_ktimer_info, + PPS_CAPTUREASSERT | PPS_OFFSETASSERT); + +The pps_register_source() prototype is:: + + int pps_register_source(struct pps_source_info *info, int default_params) + +where "info" is a pointer to a structure that describes a particular +PPS source, "default_params" tells the system what the initial default +parameters for the device should be (it is obvious that these parameters +must be a subset of ones defined in the struct +pps_source_info which describe the capabilities of the driver). + +Once you have registered a new PPS source into the system you can +signal an assert event (for example in the interrupt handler routine) +just using:: + + pps_event(source, &ts, PPS_CAPTUREASSERT, ptr) + +where "ts" is the event's timestamp. + +The same function may also run the defined echo function +(pps_ktimer_echo(), passing to it the "ptr" pointer) if the user +asked for that... etc.. + +Please see the file drivers/pps/clients/pps-ktimer.c for example code. + + +SYSFS support +------------- + +If the SYSFS filesystem is enabled in the kernel it provides a new class:: + + $ ls /sys/class/pps/ + pps0/ pps1/ pps2/ + +Every directory is the ID of a PPS sources defined in the system and +inside you find several files:: + + $ ls -F /sys/class/pps/pps0/ + assert dev mode path subsystem@ + clear echo name power/ uevent + + +Inside each "assert" and "clear" file you can find the timestamp and a +sequence number:: + + $ cat /sys/class/pps/pps0/assert + 1170026870.983207967#8 + +Where before the "#" is the timestamp in seconds; after it is the +sequence number. Other files are: + + * echo: reports if the PPS source has an echo function or not; + + * mode: reports available PPS functioning modes; + + * name: reports the PPS source's name; + + * path: reports the PPS source's device path, that is the device the + PPS source is connected to (if it exists). + + +Testing the PPS support +----------------------- + +In order to test the PPS support even without specific hardware you can use +the pps-ktimer driver (see the client subsection in the PPS configuration menu) +and the userland tools available in your distribution's pps-tools package, +http://linuxpps.org , or https://github.com/redlab-i/pps-tools. + +Once you have enabled the compilation of pps-ktimer just modprobe it (if +not statically compiled):: + + # modprobe pps-ktimer + +and the run ppstest as follow:: + + $ ./ppstest /dev/pps1 + trying PPS source "/dev/pps1" + found PPS source "/dev/pps1" + ok, found 1 source(s), now start fetching data... + source 0 - assert 1186592699.388832443, sequence: 364 - clear 0.000000000, sequence: 0 + source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0 + source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0 + +Please note that to compile userland programs, you need the file timepps.h. +This is available in the pps-tools repository mentioned above. + + +Generators +---------- + +Sometimes one needs to be able not only to catch PPS signals but to produce +them also. For example, running a distributed simulation, which requires +computers' clock to be synchronized very tightly. One way to do this is to +invent some complicated hardware solutions but it may be neither necessary +nor affordable. The cheap way is to load a PPS generator on one of the +computers (master) and PPS clients on others (slaves), and use very simple +cables to deliver signals using parallel ports, for example. + +Parallel port cable pinout:: + + pin name master slave + 1 STROBE *------ * + 2 D0 * | * + 3 D1 * | * + 4 D2 * | * + 5 D3 * | * + 6 D4 * | * + 7 D5 * | * + 8 D6 * | * + 9 D7 * | * + 10 ACK * ------* + 11 BUSY * * + 12 PE * * + 13 SEL * * + 14 AUTOFD * * + 15 ERROR * * + 16 INIT * * + 17 SELIN * * + 18-25 GND *-----------* + +Please note that parallel port interrupt occurs only on high->low transition, +so it is used for PPS assert edge. PPS clear edge can be determined only +using polling in the interrupt handler which actually can be done way more +precisely because interrupt handling delays can be quite big and random. So +current parport PPS generator implementation (pps_gen_parport module) is +geared towards using the clear edge for time synchronization. + +Clear edge polling is done with disabled interrupts so it's better to select +delay between assert and clear edge as small as possible to reduce system +latencies. But if it is too small slave won't be able to capture clear edge +transition. The default of 30us should be good enough in most situations. +The delay can be selected using 'delay' pps_gen_parport module parameter. diff --git a/Documentation/pps/pps.txt b/Documentation/pps/pps.txt deleted file mode 100644 index 99f5d8c4c652..000000000000 --- a/Documentation/pps/pps.txt +++ /dev/null @@ -1,239 +0,0 @@ - - PPS - Pulse Per Second - ---------------------- - -(C) Copyright 2007 Rodolfo Giometti - -This program is free software; you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - - - -Overview --------- - -LinuxPPS provides a programming interface (API) to define in the -system several PPS sources. - -PPS means "pulse per second" and a PPS source is just a device which -provides a high precision signal each second so that an application -can use it to adjust system clock time. - -A PPS source can be connected to a serial port (usually to the Data -Carrier Detect pin) or to a parallel port (ACK-pin) or to a special -CPU's GPIOs (this is the common case in embedded systems) but in each -case when a new pulse arrives the system must apply to it a timestamp -and record it for userland. - -Common use is the combination of the NTPD as userland program, with a -GPS receiver as PPS source, to obtain a wallclock-time with -sub-millisecond synchronisation to UTC. - - -RFC considerations ------------------- - -While implementing a PPS API as RFC 2783 defines and using an embedded -CPU GPIO-Pin as physical link to the signal, I encountered a deeper -problem: - - At startup it needs a file descriptor as argument for the function - time_pps_create(). - -This implies that the source has a /dev/... entry. This assumption is -OK for the serial and parallel port, where you can do something -useful besides(!) the gathering of timestamps as it is the central -task for a PPS API. But this assumption does not work for a single -purpose GPIO line. In this case even basic file-related functionality -(like read() and write()) makes no sense at all and should not be a -precondition for the use of a PPS API. - -The problem can be simply solved if you consider that a PPS source is -not always connected with a GPS data source. - -So your programs should check if the GPS data source (the serial port -for instance) is a PPS source too, and if not they should provide the -possibility to open another device as PPS source. - -In LinuxPPS the PPS sources are simply char devices usually mapped -into files /dev/pps0, /dev/pps1, etc. - - -PPS with USB to serial devices ------------------------------- - -It is possible to grab the PPS from an USB to serial device. However, -you should take into account the latencies and jitter introduced by -the USB stack. Users have reported clock instability around +-1ms when -synchronized with PPS through USB. With USB 2.0, jitter may decrease -down to the order of 125 microseconds. - -This may be suitable for time server synchronization with NTP because -of its undersampling and algorithms. - -If your device doesn't report PPS, you can check that the feature is -supported by its driver. Most of the time, you only need to add a call -to usb_serial_handle_dcd_change after checking the DCD status (see -ch341 and pl2303 examples). - - -Coding example --------------- - -To register a PPS source into the kernel you should define a struct -pps_source_info as follows: - - static struct pps_source_info pps_ktimer_info = { - .name = "ktimer", - .path = "", - .mode = PPS_CAPTUREASSERT | PPS_OFFSETASSERT | - PPS_ECHOASSERT | - PPS_CANWAIT | PPS_TSFMT_TSPEC, - .echo = pps_ktimer_echo, - .owner = THIS_MODULE, - }; - -and then calling the function pps_register_source() in your -initialization routine as follows: - - source = pps_register_source(&pps_ktimer_info, - PPS_CAPTUREASSERT | PPS_OFFSETASSERT); - -The pps_register_source() prototype is: - - int pps_register_source(struct pps_source_info *info, int default_params) - -where "info" is a pointer to a structure that describes a particular -PPS source, "default_params" tells the system what the initial default -parameters for the device should be (it is obvious that these parameters -must be a subset of ones defined in the struct -pps_source_info which describe the capabilities of the driver). - -Once you have registered a new PPS source into the system you can -signal an assert event (for example in the interrupt handler routine) -just using: - - pps_event(source, &ts, PPS_CAPTUREASSERT, ptr) - -where "ts" is the event's timestamp. - -The same function may also run the defined echo function -(pps_ktimer_echo(), passing to it the "ptr" pointer) if the user -asked for that... etc.. - -Please see the file drivers/pps/clients/pps-ktimer.c for example code. - - -SYSFS support -------------- - -If the SYSFS filesystem is enabled in the kernel it provides a new class: - - $ ls /sys/class/pps/ - pps0/ pps1/ pps2/ - -Every directory is the ID of a PPS sources defined in the system and -inside you find several files: - - $ ls -F /sys/class/pps/pps0/ - assert dev mode path subsystem@ - clear echo name power/ uevent - - -Inside each "assert" and "clear" file you can find the timestamp and a -sequence number: - - $ cat /sys/class/pps/pps0/assert - 1170026870.983207967#8 - -Where before the "#" is the timestamp in seconds; after it is the -sequence number. Other files are: - - * echo: reports if the PPS source has an echo function or not; - - * mode: reports available PPS functioning modes; - - * name: reports the PPS source's name; - - * path: reports the PPS source's device path, that is the device the - PPS source is connected to (if it exists). - - -Testing the PPS support ------------------------ - -In order to test the PPS support even without specific hardware you can use -the pps-ktimer driver (see the client subsection in the PPS configuration menu) -and the userland tools available in your distribution's pps-tools package, -http://linuxpps.org , or https://github.com/redlab-i/pps-tools. - -Once you have enabled the compilation of pps-ktimer just modprobe it (if -not statically compiled): - - # modprobe pps-ktimer - -and the run ppstest as follow: - - $ ./ppstest /dev/pps1 - trying PPS source "/dev/pps1" - found PPS source "/dev/pps1" - ok, found 1 source(s), now start fetching data... - source 0 - assert 1186592699.388832443, sequence: 364 - clear 0.000000000, sequence: 0 - source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0 - source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0 - -Please note that to compile userland programs, you need the file timepps.h. -This is available in the pps-tools repository mentioned above. - - -Generators ----------- - -Sometimes one needs to be able not only to catch PPS signals but to produce -them also. For example, running a distributed simulation, which requires -computers' clock to be synchronized very tightly. One way to do this is to -invent some complicated hardware solutions but it may be neither necessary -nor affordable. The cheap way is to load a PPS generator on one of the -computers (master) and PPS clients on others (slaves), and use very simple -cables to deliver signals using parallel ports, for example. - -Parallel port cable pinout: -pin name master slave -1 STROBE *------ * -2 D0 * | * -3 D1 * | * -4 D2 * | * -5 D3 * | * -6 D4 * | * -7 D5 * | * -8 D6 * | * -9 D7 * | * -10 ACK * ------* -11 BUSY * * -12 PE * * -13 SEL * * -14 AUTOFD * * -15 ERROR * * -16 INIT * * -17 SELIN * * -18-25 GND *-----------* - -Please note that parallel port interrupt occurs only on high->low transition, -so it is used for PPS assert edge. PPS clear edge can be determined only -using polling in the interrupt handler which actually can be done way more -precisely because interrupt handling delays can be quite big and random. So -current parport PPS generator implementation (pps_gen_parport module) is -geared towards using the clear edge for time synchronization. - -Clear edge polling is done with disabled interrupts so it's better to select -delay between assert and clear edge as small as possible to reduce system -latencies. But if it is too small slave won't be able to capture clear edge -transition. The default of 30us should be good enough in most situations. -The delay can be selected using 'delay' pps_gen_parport module parameter. diff --git a/MAINTAINERS b/MAINTAINERS index ac88ed99fca5..aae3bd8a19f4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12659,7 +12659,7 @@ M: Rodolfo Giometti W: http://wiki.enneenne.com/index.php/LinuxPPS_support L: linuxpps@ml.enneenne.com (subscribers-only) S: Maintained -F: Documentation/pps/ +F: Documentation/driver-api/pps.rst F: Documentation/devicetree/bindings/pps/pps-gpio.txt F: Documentation/ABI/testing/sysfs-pps F: drivers/pps/ -- cgit v1.2.1