Modify description of set_time() function.

[mprse]

Description

Add note about setting RTC time value to 0.

This PR is a result of discussion from PR#5087:

set_time() function on some platforms does not set RTC time to 0. In such case specific driver function - rtc_write() sets time to 1 instead of 0. This is caused because on some platforms 0 is an invalid time. Unfortunately there is no information about this behaviour. Maybe a warning should be added to the set_time() function description?

Just a note in the doxygen should be enough.

Status

READY

Migrations

NO

[0xc0170]

cc @c1728p9

[0xc0170]

what platforms have this behaviour ?

[mprse]

For example K64F board have this issue. But it looks like it is valid for the following freescale platforms:
/m-bed/targets/TARGET_Freescale/TARGET_K20XX/rtc_api.c
/m-bed/targets/TARGET_Freescale/TARGET_KLXX/rtc_api.c
/m-bed/targets/TARGET_Freescale/TARGET_MCUXpresso_MCUS/api/rtc_api.c

Code example:

void rtc_write(time_t t)
{
    if (t == 0) {    <---- issue
        t = 1;
    }
    RTC_StopTimer(RTC);
    RTC->TSR = t;
    RTC_StartTimer(RTC);
}

Note: When I remove code which modify 'time to set' to 1 in case when 0 is given, then RTC time can be successfully set to 0 and RTC counts time (checked on K64F board). Maybe drivers should be modified?

[0xc0170]

That makes it more clear now. I had a look at KL27Z reference manual

Writing to TSR with zero is supported, but not
recommended because TSR will read as zero when SR[TIF] or SR[TOF] are set (indicating the time is
invalid).

This is target specific. I've checked other targets, they support writing 0. There are often anomalies in the API like this, not certain if we create notes for each target (we might end up with lot of notes in some cases).
We could change this to set to 0 in those Freescale targets, and make a note from the statement above in their targets, that setting 0 makes those 2 flags set, be aware.

One thing I have noticed, lot of our targets use time_base variable that is set in rtc_write()? An example: https://github.com/ARMmbed/mbed-os/blob/master/targets/TARGET_Silicon_Labs/TARGET_EFM32/rtc_api.c#L268

@mmahadevan108

@bulislaw @c1728p9 @deepikabhavnani Suggestions?

[c1728p9]

I would consider this a bug with the vendor implementation. If 0 is unsupported by hardware then they should have a software translation.

I would argue code like this should be updated to have an offset instead:

#define RTC_OFFSET 1
time_t rtc_read(void)
{
    return (time_t)(RTC->TSR - RTC_OFFSET);
}

void rtc_write(time_t t)
{
    RTC_StopTimer(RTC);
    RTC->TSR = t + RTC_OFFSET;
    RTC_StartTimer(RTC);
}

[mmahadevan108]

I have created a PR to allow writing 0 to the TSR register. There is no hardware limitation in writing this value.

It is suggested in the manual to avoid this value as 0 when read from the TSR also indicates that a overflow or invalid flag is set. However we do not use this way inside mbed and probe the status register directly for overflow and invalid time information.

[0xc0170]

We can close this PR. @mprse Thanks for finding this bug