Mainline:Broadcom Kona/BCM590xx/RTC

Downstream driver: drivers/rtc/rtc-bcmpmu59xxx.c

The BCM590XX PMUs provide a real-time clock.

Time data

The RTC stores the time in the following format:

Offset	Purpose	Mask	Value
0	Second (SC)	0x3F	Current second, from 0 to 59.
1	Minute (MN)	0x3F	Current minute of the hour, from 0 to 59.
2	Hour (HR)	0x1F	Current hour of the day, from 0 to 23.
3	Weekday (WD)	0x0F	Day of week, from 0 to 6. Appears to roll over whenever the day changes; the hardware does not enforce a specific start. Sets itself to 0 on reset. Not used in downstream. The day of month sets itself to 0 on reset, which should be an invalid value, but would suggest that the range is 0 -> Sunday, 6 -> Monday, but there is no downstream code to confirm this.
4	Day of month (DT)	0x1F	Day of month, starting from 1. Sets itself to 0 on reset.
5	Month (MT_WD)	0x0F	Number of the month. 1 to 12 represent January-December.
6	Year (YR)	0xFF	Amount of years since 2000 (0 = 2000, 1 = 2001, etc.)

This exact format is used for both the time and alarm registers. In the time registers, the masks are enforced by hardware - any bit written outside of the mask gets ignored.

TODO: What happens on year overflow? Is there a reason as to why the downstream driver limits the values it gets?

Getting the time

On the BCM59054 and BCM59056, time registers start at 0xE0 and follow the format outlined above.

There are interrupts for updates of each of the time values.

The default reset value is 0 0 0 0 0 1 7 (2007-01-00 00:00:00, weekday 0). Notably, the day of month is invalid (0). In this state, the RTCADJ interrupt will be raised.

Alarm

On the BCM59054 and BCM59056, the alarm registers start at 0xE7.

There is an interrupt that is triggered when the alarm is triggered.

Calibration

Downstream driver: drivers/char/broadcom/rtc_cal/bcm_rtc_cal.c

There are three calibration registers: CALIB1, CALIB2 and CALIB3.

TODO	TODO: Figure out how the calibration process works, this is just my initial idea

Calibration appears to be triggered based on a CP (communications processor) event; it receives a message from the CP and uses a value from it as the "ratio". The ratio value is then compared against RTCCAL_Ratio (taken from rtccal_data.nom_ratio, 8666667); if ratio > RTCCAL_Ratio, then direction is 1, otherwise it's 0.

The clk_val value is then calculated based on the difference between the new and old ratio (diff = abs(ratio - RTCCAL_Ratio)): clk_val = RTCCAL_Ratio / diff.

TODO - what is the ratio value?

CALIB1 (0xF4)

Name	Bit	Description
clk_val (1)	7:0	Lower 8 bits of the calibration offset.

CALIB2 (0xF5)

Name	Bit	Description
clk_val (2)	7:0	Upper 8 bits of the calibration offset.

CALIB3 (0xF6)

Name	Bit	Description
???	7	Set to 1 during calibration.
direction	6
Unknown/reserved	5:0	Unknown/reserved.