Merge tag 'pull-target-arm-20220519' of https://git.linaro.org/people/pmaydell/qemu-arm into staging

target-arm queue:
 * Implement FEAT_S2FWB
 * Implement FEAT_IDST
 * Drop unsupported_encoding() macro
 * hw/intc/arm_gicv3: Use correct number of priority bits for the CPU
 * Fix aarch64 debug register names
 * hw/adc/zynq-xadc: Use qemu_irq typedef
 * target/arm/helper.c: Delete stray obsolete comment
 * Make number of counters in PMCR follow the CPU
 * hw/arm/virt: Fix dtb nits
 * ptimer: Rename PTIMER_POLICY_DEFAULT to PTIMER_POLICY_LEGACY
 * target/arm: Fix PAuth keys access checks for disabled SEL2
 * Enable FEAT_HCX for -cpu max
 * Use FIELD definitions for CPACR, CPTR_ELx

# -----BEGIN PGP SIGNATURE-----
#
# iQJNBAABCAA3FiEE4aXFk81BneKOgxXPPCUl7RQ2DN4FAmKGf/kZHHBldGVyLm1h
# eWRlbGxAbGluYXJvLm9yZwAKCRA8JSXtFDYM3h5fD/9+2ymBkwX9jIaaOooejZrJ
# CUVCPL2w206eZbPihgE4snZcZdkGjteDhS30kipyJxFNaCE0d2qQLTMrPXQMKyGz
# aqCcvSSdb+VraVOP7RpfqYrkzFsj/+K/F5NHn3Vf/T7ULLQJFk0JZ4UWnt7/rkhL
# oaXGDm79JrFfMTWUu2AKtCGj132YXyH2YP7GmvYyIty3l+hR9a8mwx3EcFTewuEn
# U7AZGZL2GfixGLZU/nNRcTu/BOlkdU6PM1BZoprs7HwbMXR1+pBCX6bwIXK35Q6/
# vCu8e/4+Hi4cd7nxRXqQ7+KuIdcEB+LwupN61othVUl2lnfQgNcvj2hhiWJkxdRI
# gpRktnnf6QNWsQ7HWShB5o8HhDN9v82wMf8VSiN1XncN6oYWZSEAMa4NbV/1ditY
# yolJww/onnre8A07xTzBqIXqKRViwUMltXSamUpuWx4UsSMOql/ktJYsXqSnJWP+
# cpTqQ+VQKj8cTotvDTnxKsOiI/RraSAzW1amle0x2Ff8I6AN45j1S3GuT9EyJJ3w
# CabegyYloJChI2Gnqf5Pc+B108E/GwHlcsmgaN5FEjlGzluKa7Ii0D2f1Cey1tAl
# iTqJ3dRFjhkll6a88TN47QRtDJadXp+PjQzzQxtEM1wXhJLWXTxocvBn0cGg2OnY
# 4eMY1YLtD9neCnKvdZdw9g==
# =F3ow
# -----END PGP SIGNATURE-----
# gpg: Signature made Thu 19 May 2022 10:35:53 AM PDT
# gpg:                using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg:                issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [full]
# gpg:                 aka "Peter Maydell <pmaydell@gmail.com>" [full]
# gpg:                 aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [full]

* tag 'pull-target-arm-20220519' of https://git.linaro.org/people/pmaydell/qemu-arm: (22 commits)
  target/arm: Use FIELD definitions for CPACR, CPTR_ELx
  target/arm: Enable FEAT_HCX for -cpu max
  target/arm: Fix PAuth keys access checks for disabled SEL2
  ptimer: Rename PTIMER_POLICY_DEFAULT to PTIMER_POLICY_LEGACY
  hw/arm/virt: Drop #size-cells and #address-cells from gpio-keys dtb node
  hw/arm/virt: Fix incorrect non-secure flash dtb node name
  target/arm: Make number of counters in PMCR follow the CPU
  target/arm/helper.c: Delete stray obsolete comment
  hw/adc/zynq-xadc: Use qemu_irq typedef
  Fix aarch64 debug register names.
  hw/intc/arm_gicv3: Provide ich_num_aprs()
  hw/intc/arm_gicv3: Use correct number of priority bits for the CPU
  hw/intc/arm_gicv3: Support configurable number of physical priority bits
  hw/intc/arm_gicv3_kvm.c: Stop using GIC_MIN_BPR constant
  hw/intc/arm_gicv3: report correct PRIbits field in ICV_CTLR_EL1
  hw/intc/arm_gicv3_cpuif: Handle CPUs that don't specify GICv3 parameters
  target/arm: Drop unsupported_encoding() macro
  target/arm: Implement FEAT_IDST
  target/arm: Enable FEAT_S2FWB for -cpu max
  target/arm: Implement FEAT_S2FWB
  ...

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

1 files changed, 12 insertions, 4 deletions

diff --git a/include/hw/ptimer.h b/include/hw/ptimer.h
index c443218475..4dc02b0de4 100644
--- a/include/hw/ptimer.h
+++ b/include/hw/ptimer.h
@@ -33,9 +33,17 @@
  * to stderr when the guest attempts to enable the timer.
  */
 
-/* The default ptimer policy retains backward compatibility with the legacy
- * timers. Custom policies are adjusting the default one. Consider providing
- * a correct policy for your timer.
+/*
+ * The 'legacy' ptimer policy retains backward compatibility with the
+ * traditional ptimer behaviour from before policy flags were introduced.
+ * It has several weird behaviours which don't match typical hardware
+ * timer behaviour. For a new device using ptimers, you should not
+ * use PTIMER_POLICY_LEGACY, but instead check the actual behaviour
+ * that you need and specify the right set of policy flags to get that.
+ *
+ * If you are overhauling an existing device that uses PTIMER_POLICY_LEGACY
+ * and are in a position to check or test the real hardware behaviour,
+ * consider updating it to specify the right policy flags.
  *
  * The rough edges of the default policy:
  *  - Starting to run with a period = 0 emits error message and stops the
@@ -54,7 +62,7 @@
  *    since the last period, effectively restarting the timer with a
  *    counter = counter value at the moment of change (.i.e. one less).
  */
-#define PTIMER_POLICY_DEFAULT               0
+#define PTIMER_POLICY_LEGACY                0
 
 /* Periodic timer counter stays with "0" for a one period before wrapping
  * around.  */