Document on : Time Manager in OpenBMC --> Need your review.

[vishwa]

Team,

Please help look into this document that describes what I think the 
TimeManager on openBMC systems should look like.

Please weigh in your thoughts.

Thanks.

Vishwanath.
-------------- next part --------------
BMC Settings  in /org/openbmc/settings/Host/host0
--------------------------------------------------

1/. New property "TimeMode" and the default would be set to "NTP"

--> This means, BMC will use timesyncd to sync the time with NTP servers. Any attempt to set the time manually is rejected by the time daemon.

1.1) The only other valid value for that would be "Manual".

--> This means, BMC will disable 'ntp' so that only manually setting the time would be allowed.

-------------------------------------------------------

2/. New property called "TimeOwner" and the default would be set to "BMC"

2.1) The other possible values would be "Host" / "Split" / "Both".

Owner *BMC*: BMC can have NTP / Non-NTP as BMC's source of time.
 --> This also means that, when host sends SET_SEL, BMC just responds with success and when host asks GET_SEL, BMC's time is returned.

**

Owner *Host*: BMC can *not* set the time on its own and need to wait for host's IPMI message to set and this is why this is not default.

**

Owner *Split*: BMC is free to choose either Manual -or- NTP to set BMC time, however, when host sends the time down, the difference between host's time and BMC's time is calculated and is stored in a persistent area. This offset is kept up-to-date whenever the time changes on the BMC ( Using timerfd_settime with TFD_TIMER_CANCEL_ON_SET ).

--> When host asks time, the BMC's time is read and then factors in the offset and returns it.

**

Owner *Both* : Same as BMC owns the clock but just that when Host sends SET_SEL time, the time on BMC is set to value given by host.

==========================================================

API's defined that is exported by BMC and accessible by REST ( Modified only if policy allows it ).
---------------------------------------------------------------------------------------------------

1/. /org/openbmc/TimeManager/SetTime (time_string_in_%Y-%m-%d %H:%M:%S ). --> Set BMC Time per the user input.

    --> This format is then used by strptime and uses mktime to convert it to num_seconds and calls /org/freedesktop/timedate1/SetTime converted to usec

    --> Although strptime support whole lot of other formats, I think this one way is enough.

**

2/. /org/openbmc/TimeManager/GetTime (returns ctime ) -> Get BMC Time.

    --> If caller is IPMI_GET_SEL and the mode is "split", then the host-offset is added to this and returned, else return what is read on BMC.

**

3/. /org/openbmc/TimeManager/SetNTP (string 'yes_or_no') --> Enable / Disable NTP @ BMC.

    --> Calls /org/freedesktop/timedate1/SetNTP with '1' or '0' and that would handle pausing timesyncd.

**

NOTE :: The easiet thing would be to do a "systemd(timedatectl <user request>)" so mostly all is handled by systemd but the only draw back I see is the new fork and I believe this may not be a correct approach.

**

4/. TimeManager watches for PropertyChanged events from /org/openbmc/settings/Host/host0 and would read the changed settings and take appropriate actions :

Actions could be :
-----------------

4.1/. If the TimeMode is changed between BMC<-->Manual, then whatever asked for is enabled / disabled is honored at anytime.

4.2/.  If the TimerMode asked is to change to "host owns the clock" -OR- "split clock", then the value of [pgood] is read. If that is [on], then the request is  

       ignored since it would not be safe to change to these modes when things are running.

       --> On a successful policy change, the host_offset is nullified.

4.3/  if the TimerMode asked is to change to "BMC owns the clock" -OR- "Both", then the "host_offset" would be invalidated and the request is honored.

**

5/. TimeManager watches for time changes in BMC due to any source by watching for TFD_TIMER_CANCEL_ON_SET and then updates the host_offset if the Owner is set to split.

===========================================================

Changes to Existing /org/openbmc/NetworkManager/
------------------------------------------------

1/. SetAddress4 now takes in another field called "NTP" and user need to give "" if they do not want to supply NTP at the time of netconf.
2/. SetDHCP now takes in another field called "UseNTP" and the user needs to give "yes"/"no"/"" and the "" the same would be put as UseNTP= under DHCP section.
3/. A new API that will take in "interface name" and "list of NTP" and would go ahead update the static .network file or in DHCP section.

=====================

Notes:

1/. sd_event loop is used so that the requests are serialized by SD_BUS.
2/. timerfd_settime is used with TFD_TIMER_CANCEL_ON_SET so that we get woken up only when there is a time is set.