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

target-arm queue:
 * docs/devel/docs: Document .hx file syntax
 * arm_pamax() no longer needs to do feature propagation
 * docs/system/arm/virt.rst: Improve 'highmem' option docs
 * STM32L4x5 Implement SYSCFG and EXTI devices
 * hw/timer: fix systick trace message
 * hw/arm/virt: Consolidate valid CPU types
 * load_elf: fix iterator's type for elf file processing

# -----BEGIN PGP SIGNATURE-----
#
# iQJNBAABCAA3FiEE4aXFk81BneKOgxXPPCUl7RQ2DN4FAmWpHM4ZHHBldGVyLm1h
# eWRlbGxAbGluYXJvLm9yZwAKCRA8JSXtFDYM3pZxD/sGIXvTeoOCsum7OFpArKoQ
# J+wcy74pO526IDzjudgtwP8kFW09oVblMPgrt/68F9LY4Oa7sDNAZX/Xqlhs/hdJ
# SVbOXArRmyLvgLpn8KVii9xk9iI/olMGt0S6KcXAErdgFud+JcCevbS0D5fAF4Ua
# /G/4ldnwr+WcYUA5IIoi02ymSBm5VNeH2bKu0MPS3xpizjzgOFxWTBYwq3zkZYWD
# w5GjH9+F+IC67CiAlCLvuQBqpGLdRwFBttU05hLtGXuSlnvS+FtJTooI7gGD17CR
# 2wTa7qF716qDN1lNSIvxA6t8/dWNMIYCZYdlxJml476WzP3jECpth2WFWqE0G3yg
# Orr7sFVB8X6JmtlR34srW6e3CZA3t+4FIWqcdELFLi5IQtJeer90jqQ9xwx4SttJ
# nsHdy5M8txWSa61yAaDTXMID/smVlC7sWTKJrR9kV7v5+b9OPQ/R8k0mCODl5Aer
# mzAVuCvUQVYK3j7fzprGrlldla57s3v78OAhqACLgKflK0+aJSJjglulPrSMK1z5
# bRPS5jLZjFwEi2VaLVg3LPJiBMDj1s/wAl0ycfCQSv2oEzvmpkw+Ar1HDc2NFe+d
# 9dunbdhAZJMwh+ABIg7iMj+l0ncOXDa4DS+6BnjRxfECCa172u3viq1HATkLLAFI
# GTkcJ5hIQzNEeg9ob0MDIg==
# =Rfpe
# -----END PGP SIGNATURE-----
# gpg: Signature made Thu 18 Jan 2024 12:42:54 GMT
# gpg:                using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg:                issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# gpg:                 aka "Peter Maydell <peter@archaic.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83  15CF 3C25 25ED 1436 0CDE

* tag 'pull-target-arm-20240118' of https://git.linaro.org/people/pmaydell/qemu-arm:
  load_elf: fix iterator's type for elf file processing
  hw/arm/virt: Consolidate valid CPU types
  hw/timer: fix systick trace message
  tests/qtest: Add STM32L4x5 SYSCFG QTest testcase
  hw/arm: Connect STM32L4x5 SYSCFG to STM32L4x5 SoC
  hw/misc: Implement STM32L4x5 SYSCFG
  tests/qtest: Add STM32L4x5 EXTI QTest testcase
  hw/arm: Connect STM32L4x5 EXTI to STM32L4x5 SoC
  hw/misc: Implement STM32L4x5 EXTI
  docs/system/arm/virt.rst: Improve 'highmem' option docs
  target/arm: arm_pamax() no longer needs to do feature propagation
  docs/devel/docs: Document .hx file syntax

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 60 insertions, 0 deletions

diff --git a/docs/devel/docs.rst b/docs/devel/docs.rst
new file mode 100644
index 0000000000..7da067905b
--- /dev/null
+++ b/docs/devel/docs.rst
@@ -0,0 +1,60 @@
+
+==================
+QEMU Documentation
+==================
+
+QEMU's documentation is written in reStructuredText format and
+built using the Sphinx documentation generator. We generate both
+the HTML manual and the manpages from the some documentation sources.
+
+hxtool and .hx files
+--------------------
+
+The documentation for QEMU command line options and Human Monitor Protocol
+(HMP) commands is written in files with the ``.hx`` suffix. These
+are processed in two ways:
+
+ * ``scripts/hxtool`` creates C header files from them, which are included
+   in QEMU to do things like handle the ``--help`` option output
+ * a Sphinx extension in ``docs/sphinx/hxtool.py`` generates rST output
+   to be included in the HTML or manpage documentation
+
+The syntax of these ``.hx`` files is simple. It is broadly an
+alternation of C code put into the C output and rST format text
+put into the documention. A few special directives are recognised;
+these are all-caps and must be at the beginning of the line.
+
+``HXCOMM`` is the comment marker. The line, including any arbitrary
+text after the marker, is discarded and appears neither in the C output
+nor the documentation output.
+
+``SRST`` starts a reStructuredText section. Following lines
+are put into the documentation verbatim, and discarded from the C output.
+
+``ERST`` ends the documentation section started with ``SRST``,
+and switches back to a C code section.
+
+``DEFHEADING()`` defines a heading that should appear in both the
+``--help`` output and in the documentation. This directive should
+be in the C code block. If there is a string inside the brackets,
+this is the heading to use. If this string is empty, it produces
+a blank line in the ``--help`` output and is ignored for the rST
+output.
+
+``ARCHHEADING()`` is a variant of ``DEFHEADING()`` which produces
+the heading only if the specified guest architecture was compiled
+into QEMU. This should be avoided in new documentation.
+
+Within C code sections, you should check the comments at the top
+of the file to see what the expected usage is, because this
+varies between files. For instance in ``qemu-options.hx`` we use
+the ``DEF()`` macro to define each option and specify its ``--help``
+text, but in ``hmp-commands.hx`` the C code sections are elements
+of an array of structs of type ``HMPCommand`` which define the
+name, behaviour and help text for each monitor command.
+
+In the file ``qemu-options.hx``, do not try to define a
+reStructuredText label within a documentation section. This file
+is included into two separate Sphinx documents, and some
+versions of Sphinx will complain about the duplicate label
+that results.