periph_drivers: Proposal for a minimal RTC interface

[thomaseichinger]

This is a proposal for a low-level RTC driver. (now for real)
It tries to follow the principles of @haukepetersen's low-level driver interfaces and is open for discussion.

[Kijewski]

I'd like an explicit typedef void (rtc_alarm_callback_t *)(int irq_type); better.

[Kijewski]

IMO all functions should return an error if the access was successful.

[Kijewski]

Use the plural in the name, too.

[haukepetersen]

I seem to have some trouble to understand the specific usage of this interface. I would imagine and interface for the RTC maybe as this:

int rtc_init()
time_t rtc_get_time()
int rtc_set_time(time_t time)
int rtc_set_alarm(time_t time, void (*some_callback)(void)) 
int rtc_clear_alarm(int id)

I am not quite sure that the IRQ masks and types are i) portable enough and ii) needed for a clean and easy interface?!

[thomaseichinger]

@haukepetersen Well most platforms I checked provide alarm/time registers in their RTC module someone can write seconds minutes and hours to. So someone could say "alarm in 2 months" or "alarm in 87840 seconds". Using time_t would need a conversion in the driver implementation. Because of this I decided to use tm.

[haukepetersen]

oh, actually the time_t in my pseudo-code was rather meant as placeholder for 'some-struct-that-defines-time'... tm is fine with me...

[thomaseichinger]

updated addressing @Kijewski's and @haukepetersen's comments

[OlegHahm]

2014

[OlegHahm]

ACK

[haukepetersen]

Now that i look at this again, I have some remarks which I didn't think of before:

• would it make sense to include a function like rtc_remove_alarm(struct tm *time)?
• for power management, rtc_poweron() and rtc_poweroff() functions as in proposed drivers: Initial import of SPI low-level driver IF #1311 would be useful?!
• we should synchronize on the usage of specific vs. general types (int vs int32_t) in low-level drivers -> should we open an issue for this?
• the existing drivers register callbacks in their init functions. We should also try to synchronize this design decision for all low-level drivers...

[LudwigKnuepfer]

I'd say use int instead of int8_t for the return values.

[LudwigKnuepfer]

I'm not sure registering an alarm callback on init makes sense.

Edit: yes it does (these devices tend not to have several alarm registers, so that functionality would need to be implemented in a high-level driver anyway).

[LudwigKnuepfer]

Can RTC's be turned on and off at all? If so, I'm in favor of functions like @haukepetersen proposed.

Edit: yes they can

[LudwigKnuepfer]

Other than that I'd rather like to see this merged asap, the current interface is not so great.

[LudwigKnuepfer]

-> ACK when types changed, anything else can come later.

[LudwigKnuepfer]

One last remark: it might make sense to explicitly specify the format expected in the struct tm *time parameters.
The old interface apparently expects offsets to the year 1900 and 0 as the first month. In my opinion this should be handled by the driver implementation even if this is a common characteristic of RTCs.
In any case - specify what the driver expects to avoid confusion.

Edit: aha, the old driver actually complied with the specification.. http://pubs.opengroup.org/onlinepubs/7908799/xsh/time.h.html

[thomaseichinger]

updated addressing @LudwigOrtmann's comments and rebased

[LudwigKnuepfer]

 * The values in `tm` are expected to conform to the `struct tm` specification.
 * Compare: http://pubs.opengroup.org/onlinepubs/7908799/xsh/time.h.html

?

[thomaseichinger]

Updated addressing @haukepetersen's offline comments.

[haukepetersen]

Looking nice! ACK when squashed, merge at will

[thomaseichinger]

squashed and go