[chrony-dev] [PATCH] rtc (linux): Help the user diagnose a problem with RTC UIE ioctl requests

[Michael Witten <mfwitten@xxxxxxxxx>]

This commit updates the FAQ to point the user towards a solution; it
also updates the RTC driver code (rtc_linux.c:RTC_Linux_Initialise())
to provide useful diagnostic messages:

  * Always: "The RTC driver could not be initialised."
  * --enable-debug: A longer message explaining the situation and
                    suggesting the possible solution of enabling
                    emulation in the Linux kernel.

chrony's Linux RTC driver (rtc_linux.c) requires the following ioctl
requests to be functional:

  RTC_UIE_ON
  RTC_UIE_OFF

However, a Linux system's RTC driver does not necessarily implement them,
as noted in these previous commits:

  d66b2f2b2423bfbd3de4d69895024dac7eefb306
  rtc: handle RTCs that don't support interrupts
  Tue Dec 10 17:45:28 2019 +0100

  bff3f51d13c3f41e2ead2cfff5bfe0b8c22ef44a
  rtc: extend check for RTCs that don't support interrupts
  Thu Dec 12 12:50:19 2019 +0100

Fortunately, the Linux kernel can be built with software emulation of
these hardware requests, by enabling the following config variable:

  CONFIG_RTC_INTF_DEV_UIE_EMUL
    Provides an emulation for RTC_UIE if the underlying rtc chip
    driver does not expose RTC_UIE ioctls. Those requests generate
    once-per-second update interrupts, used for synchronization.

    The emulation code will read the time from the hardware
    clock several times per second, please enable this option
    only if you know that you really need it.

This commit records these facts for the benefit of the user.
---
 doc/faq.adoc | 7 ++++++-
 rtc_linux.c  | 8 ++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/doc/faq.adoc b/doc/faq.adoc
index 9d2c109..bcb7512 100644
--- a/doc/faq.adoc
+++ b/doc/faq.adoc
@@ -587,12 +587,17 @@ is started after it has run.
 === I just keep getting the `513 RTC driver not running` message
 
 For the real-time clock support to work, you need the following three
-things
+things:
 
 * an RTC in your computer
 * a Linux kernel with enabled RTC support
 * an `rtcfile` directive in your _chrony.conf_ file
 
+Your real-time clock hardware might not support the required ioctl requests;
+it might be necessary to build the Linux kernel with support for software
+emulation instead (try enabling the following build-time option:
+`CONFIG_RTC_INTF_DEV_UIE_EMUL`).
+
 === I get `Could not open /dev/rtc, Device or resource busy` in my syslog file
 
 Some other program running on the system might be using the device.
diff --git a/rtc_linux.c b/rtc_linux.c
index 08c2a19..9f58857 100644
--- a/rtc_linux.c
+++ b/rtc_linux.c
@@ -518,6 +518,14 @@ RTC_Linux_Initialise(void)
   /* Make sure the RTC supports interrupts */
   if (!switch_interrupts(1) || !switch_interrupts(0)) {
     close(fd);
+    LOG(LOGS_WARN, "The RTC driver could not be initialised.");
+#if DEBUG > 0
+    LOG(LOGS_INFO,
+        "Your real-time clock hardware might not support the required "
+        "ioctl requests; it might be necessary to build the Linux kernel "
+        "with support for software emulation instead: When configuring the "
+        "kernel, enable this option: CONFIG_RTC_INTF_DEV_UIE_EMUL");
+#endif
     return 0;
   }
 
-- 
2.22.0


-- 
To unsubscribe email chrony-dev-request@xxxxxxxxxxxxxxxxxxxx with "unsubscribe" in the subject.
For help email chrony-dev-request@xxxxxxxxxxxxxxxxxxxx with "help" in the subject.
Trouble?  Email listmaster@xxxxxxxxxxxxxxxxxxxx.