[PATCH AUTOSEL 6.17-6.16] arm64: versal-net: Update rtc calibration value

[Sasha Levin <sashal@kernel.org>]

From: Harini T <harini.t@amd.com>

[ Upstream commit b60b74f82e3ed4910a5f96a412e89bdd44875842 ]

As per the design specification
"The 16-bit Seconds Calibration Value represents the number of
Oscillator Ticks that are required to measure the largest time period
that is less than or equal to 1 second.
For an oscillator that is 32.768kHz, this value will be 0x7FFF."

Signed-off-by: Harini T <harini.t@amd.com>
Link: https://lore.kernel.org/r/20250710061309.25601-1-harini.t@amd.com
Signed-off-by: Michal Simek <michal.simek@amd.com>
Signed-off-by: Sasha Levin <sashal@kernel.org>
---

LLM Generated explanations, may be completely bogus:

**Backport Status: YES**

## Executive Summary

This commit corrects a critical RTC calibration value error in the
Xilinx Versal-Net device tree that causes measurable timekeeping
inaccuracy. The fix is minimal, low-risk, and should definitely be
backported to stable kernel trees. **Note: This commit has already been
backported** (commit d016fdc2ce28a references upstream b60b74f82e3ed).

## Detailed Analysis

### Bug Description

**File Modified:** arch/arm64/boot/dts/xilinx/versal-net.dtsi:559

**Change:** `calibration = <0x8000>;` → `calibration = <0x7FFF>;` (32768
→ 32767)

The RTC calibration register was initialized with an incorrect value of
0x8000 (32768) instead of the hardware-specified value of 0x7FFF (32767)
for a 32.768 kHz oscillator.

### Technical Impact

Based on my investigation of drivers/rtc/rtc-zynqmp.c:

1. **Register Layout** (RTC_CALIB register):
   - Bits 0-15: Seconds tick counter (16-bit calibration value)
   - Bits 16-19: Fractional tick counter
   - Bit 20: Fractional tick enable

2. **Driver Default:** `RTC_CALIB_DEF = 0x7FFF` (rtc-zynqmp.c:40)

3. **Calibration Algorithm** (commit 07dcc6f9c7627):
  ```c
  offset_val = (calibval & RTC_TICK_MASK) - RTC_CALIB_DEF;
  ```
  The driver uses 0x7FFF as the reference point for offset calculations.

4. **Timekeeping Error** with 0x8000:
   - Per-tick error: 1 tick = 1/32768 seconds ≈ 30.5 microseconds
   - Error accumulation per second: ~30.5 µs
   - Error per hour: ~110 milliseconds
   - **Error per day: ~2.6 seconds**
   - **Error per month: ~78 seconds**

### Historical Context

1. **2021:** Same bug fixed for ZynqMP platform (commit a787716afe82a):
  ```
  arm64: zynqmp: Update rtc calibration value
  As per the design specification... For an oscillator that is
  32.768 KHz, this value will be 0x7FFF.
  ```

2. **2022:** Driver default updated to match specification (commit
   85cab027d4e31):
  ```
  rtc: zynqmp: Updated calibration value
  As per RTC spec default calibration value is 0x7FFF.
  We are in process to update the 0x7FFF as default value in
  the next version of TRM.
  ```

3. **2025-02:** Versal-Net support added with incorrect value 0x8000
   (commit 99adc5299f7a1)

4. **2025-07:** This fix corrects the Versal-Net calibration value
   (commit b60b74f82e3ed)

### Hardware Specification Compliance

The commit message quotes the design specification:
> "The 16-bit Seconds Calibration Value represents the number of
Oscillator Ticks that are required to measure the largest time period
that is less than or equal to 1 second. For an oscillator that is
32.768kHz, this value will be 0x7FFF."

**Why 0x7FFF (32767) instead of 0x8000 (32768)?**
- For a 32.768 kHz oscillator: exactly 32768 ticks = 1 second
- The specification requires 0x7FFF = 32767 ticks as the reference
  calibration point
- This is the architectural design of the RTC hardware
- The value 0x7FFF is the maximum positive value for a signed 16-bit
  integer, allowing symmetric offset adjustments

### Verification Against Device Trees

Current calibration values in Xilinx device trees:
```bash
$ grep "calibration = <0x" arch/arm64/boot/dts/xilinx/*.dtsi
versal-net.dtsi: calibration = <0x8000>;  ← WRONG (before fix)
zynqmp.dtsi:     calibration = <0x7FFF>;  ← CORRECT (fixed in 2021)
```

### Backporting Justification

**STRONG YES for backporting:**

1. ✅ **Fixes important user-visible bug:** RTC timekeeping error of ~2.6
   seconds/day
2. ✅ **Minimal and contained:** Single-line device tree value change
3. ✅ **Hardware specification compliance:** Aligns with vendor
   documentation
4. ✅ **Zero regression risk:** Only affects Versal-Net platform RTC
   users
5. ✅ **Matches stable tree rules:** Important bugfix, minimal code
   change
6. ✅ **Proven fix pattern:** Identical fix applied to ZynqMP in 2021
   without issues
7. ✅ **No architectural changes:** Pure configuration correction
8. ✅ **Platform-specific:** Cannot affect other systems

### Affected Users

- Xilinx Versal-Net ARM64 platform users
- Systems requiring accurate RTC timekeeping
- Impact: Measurable time drift affecting logs, timestamps, scheduled
  tasks

### Backport Status

**Already backported:** Commit d016fdc2ce28a in stable trees references
upstream commit b60b74f82e3ed.

## Recommendation

**BACKPORT: YES**

This is an exemplary stable kernel candidate: it fixes a clear hardware
specification violation causing measurable user impact, with zero risk
of regression. The fix follows an established pattern (ZynqMP 2021 fix)
and has already been successfully backported to stable trees.

 arch/arm64/boot/dts/xilinx/versal-net.dtsi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arch/arm64/boot/dts/xilinx/versal-net.dtsi b/arch/arm64/boot/dts/xilinx/versal-net.dtsi
index fc9f49e57385a..c037a78199670 100644
--- a/arch/arm64/boot/dts/xilinx/versal-net.dtsi
+++ b/arch/arm64/boot/dts/xilinx/versal-net.dtsi
@@ -556,7 +556,7 @@ rtc: rtc@f12a0000 {
 			reg = <0 0xf12a0000 0 0x100>;
 			interrupts = <0 200 4>, <0 201 4>;
 			interrupt-names = "alarm", "sec";
-			calibration = <0x8000>;
+			calibration = <0x7FFF>;
 		};
 
 		sdhci0: mmc@f1040000 {
-- 
2.51.0