[000/110] Big documentation cleanup/expansion

This giant patchset goes through and ensures that at the very least we
have a bit of skeleton documentation for each OPAL API call.

It also makes each API call documentation a bit prettier, and uses the
proper C code formatting stuff that Sphinx gives us.

I also had a good amount of diving into ancient history to work out what
calls actually existed and when, and along the way found several ones
that have never been implemented, or were implemented and *mostly*
removed but no longer have any need to be around.

I've tried to keep each patch pretty self contained to the one thing
it's touching, which is kind of why this patch series is so long.

Stewart Smith (110):
  doc: flesh out OPAL return codes documentation
  doc/opal-spec: update email address
  doc/overview: flesh out overview
  doc: Giant OPAL API table
  doc: Make OPAL_CONSOLE_* docs pretty
  doc: Make OPAL_RTC_READ docs pretty
  doc: make OPAL_RTC_WRITE docs pretty
  doc: prettify OPAL_REINIT_CPUS
  doc: prettify FSP Code update docs
  doc: prettify and expand OPAL_HANDLE_HMI2 docs
  doc: prettify OPAL powercap docs
  doc: prettify opal IMC counters calls
  doc: prettify OPAL_SENSOR_GROUP_ENABLE and OPAL_SENSOR_GROUP_CLEAR
  doc: prettify OPAL_QUIESCE
  doc: prettify OPAL_PCI_SET_P2P
  doc: prettify OPAL_[GET|SET]_PBCQ_TUNNEL_BAR
  doc: prettify and RSTify OPAL_NMMU_SET_PTCR
  doc: prettify OPAL_PCI_TCE_KILL
  doc: prettify OPAL_INT_* calls
  doc: prettify OPAL_PCI_[GET|SET]_POWER_STATE
  doc: prettify OPAL_GET_DEVICE_TREE
  doc: prettify OPAL_PCI_GET_PRESENCE_STATE
  doc: prettify OPAL_PRD_MSG
  doc: prettify OPAL_IPMI_(SEND|RECV)
  doc: prettify OPAL_SLW_SET_REG
  doc: prettify OPAL_CHECK_TOKEN
  doc: prettify OPAL_PCI_SET_PHB_CAPI_MODE
  doc: make OPAL_TEST docs pretty
  doc: Add anchors to 5.1.13 and 5.3.0 release notes
  doc: combine OPAL_RTC_READ and OPAL_RTC_WRITE pages
  doc: Make OPAL_CEC_POWER_DOWN docs pretty
  doc: Add example to OPAL_CEC_POWER_DOWN
  doc: flesh out OPAL_CEC_REBOOT docs
  doc: Flesh out NVRAM docs
  doc: Fix up OPAL_HANDLE_INTERRUPT links
  doc: Add details on removed calls
  Remove remnants of OPAL_PCI_SET_PHB_TCE_MEMORY
  Remove last remnants of OPAL_PCI_SET_PHB_TCE_MEMORY and
    OPAL_PCI_SET_HUB_TCE_MEMORY
  doc: Add PCI Config Space OPAL call docs
  doc: Make OPAL_ELOG_* pretty, mark OPAL_ELOG_WRITE unimplemented
  Document the long removed OPAL_REGISTER_OPAL_EXCEPTION_HANDLER call
  doc: fix OPAL_CONSOLE_* links
  doc: OPAL_START_CPU and OPAL_RETURN_CPU
  doc: Add links to XIVE calls
  doc: Combine and extend OPAL_SENSOR_READ[_U64] docs
  doc: Clean up OPAL power shift ratio docs
  doc: combine OPAL_SENSOR_GROUP_ENABLE and OPAL_SENSOR_GROUP_CLEAR
  doc: Extend OPAL_LEDS_[GET|SET]_INDICATOR
  doc: prettify and flesh out OPAL_FLASH_* call documentation
  doc: Add OPAL_I2C_REQUEST documentation
  doc: Flesh out OPAL_(READ|WRITE)_TPO and OPAL_GET_DPO_STATUS docs
  doc: Flesh out OPAL_(UN)REGISTER_DUMP_REGION docs
  doc: prettify and flesh out OPAL_XSCOM_READ and OPAL_XSCOM_WRITE
  doc: flesh out and prettify OPAL_LPC_(READ|WRITE)
  doc: misc formatting fixes
  doc: Document OPAL_DUMP_* calls
  Add missing 5.4.9 release notes
  skiboot 6.0.3 release notes
  skiboot v6.0.12 release notes
  skiboot 6.0.9 release notes
  doc: Add missing skiboot 5.9.8 release notes
  doc: Add missing skiboot-4.0 release notes
  doc: Add missing skiboot-5.0 release notes
  doc: Add missing skiboot-4.1 release notes
  doc: Add missing skiboot-4.1.1 release notes
  doc: Add skeleton OPAL_PCI_EEH_FREEZE_STATUS docs
  doc: OPAL_PCI_SHPC was never implemented
  doc: Add skeleton OPAL_PCI_EEH_FREEZE_CLEAR docs
  Remove unused OPAL_PCI_EEH_FREEZE_STATUS2
  doc: prettify OPAL_PCI_PHB_MMIO_ENABLE
  doc: prettify OPAL_PCI_SET_PHB_MEM_WINDOW
  doc: prettify OPAL_PCI_MAP_PE_MMIO_WINDOW
  Remove never implemented OPAL_PCI_SET_PHB_TABLE_MEMORY and document
    why
  doc: prettify OPAL_PCI_SET_PE
  doc: prettify OPAL_PCI_SET_PELTV
  doc: prettify OPAL_PCI_SET_MVE
  doc: prettify OPAL_PCI_SET_MVE_ENABLE
  Remove unused OPAL_PCI_GET_XIVE_REISSUE and OPAL_PCI_SET_XIVE_REISSUE
  doc: prettify OPAL_PCI_SET_XIVE_PE
  Remove unused OPAL_GET_XIVE_SOURCE
  doc: prettify OPAL_GET_MSI_[32|64]
  doc: Document OPAL_QUERY_CPU_STATUS
  doc: prettify OPAL_PCI_MAP_PE_DMA_WINDOW[_REAL]
  doc: Add skeleton OPAL_PCI_RESET docs
  doc: Skeleton OPAL_PCI_GET_HUB_DIAG_DATA docs
  doc: Flesh out OPAL_PCI_GET_PHB_DIAG_DATA2 docs
  Remove remnants of OPAL_PCI_GET_PHB_DIAG_DATA
  doc: OPAL_PCI_FENCE_PHB was never implemented
  doc: Add skeleton for OPAL_PCI_REINIT
  doc: OPAL_PCI_MASK_PE_ERROR was never implemented
  doc: Mark OPAL_SET_SLOT_LED_STATUS as never implemented
  doc: Add OPAL_GET_EPOW_STATUS docs
  doc: OPAL_SET_SYSTEM_ATTENTION_LED was never implemented
  doc: OPAL_RESERVED[12], reserved but never used
  doc: Add skeleton for OPAL_PCI_NEXT_ERROR
  doc: Skeleton OPAL_PCI_POLL docs
  doc: Add OPAL_PCI_MSI_EOI skeleton docs
  doc: Add OPAL_ELOG_WRITE to a list of future calls
  doc: Add skeleton OPAL_RESYNC_TIMEBASE docs
  doc: prettify OPAL_GET_MSG
  doc: prettify OPAL_CHECK_ASYNC_COMPLETION
  doc: prettify OPAL_SYNC_HOST_REBOOT
  doc: Document OPAL_GET_PARAM and OPAL_SET_PARAM
  doc: Document OPAL_ELOG_SEND as not ever used
  doc: Document OPAL_WRITE_OPPANEL_ASYNC
  doc: Skeleton OPAL_PCI_ERR_INJECT docs
  doc: skeleton OPAL_PCI_EEH_FREEZE_SET docs
  doc: Document OPAL_CONFIG_CPU_IDLE_STATE
  doc: prettify OPAL_GET_XIVE and OPAL_SET_XIVE
  doc: fixup misc broken links

 core/pci-opal.c                               | 125 ----
 doc/device-tree/ibm,opal/nvram.rst            |  13 +
 doc/device-tree/ibm,opal/oppanel.rst          |   2 +
 .../ibm,opal/power-mgt/powercap.rst           |   4 +-
 doc/device-tree/ibm,opal/sensor-groups.rst    |   2 +
 doc/device-tree/ibm,opal/sysparams.rst        |  38 ++
 doc/opal-api/index.rst                        | 646 ++++++++++++++++++
 doc/opal-api/opal-cec-power-down-5.rst        |  55 +-
 doc/opal-api/opal-cec-reboot-6-116.rst        |  88 ++-
 .../opal-check-async-completion-86.rst        |  17 +-
 doc/opal-api/opal-check-token-80.rst          |   8 +
 doc/opal-api/opal-code-update-76-77-78.rst    |  33 +-
 .../opal-config-cpu-idle-state-99.rst         |  32 +
 doc/opal-api/opal-console-read-write-1-2.rst  |  66 +-
 .../opal-dump-81-82-83-84-94-101-102.rst      | 293 ++++++++
 doc/opal-api/opal-elog-71-72-73-74-75.rst     |  52 +-
 doc/opal-api/opal-flash-110-111-112.rst       |  65 +-
 doc/opal-api/opal-get-device-tree-118.rst     |  37 +-
 doc/opal-api/opal-get-epow-status-56.rst      |  66 ++
 doc/opal-api/opal-get-msg-85.rst              |  22 +-
 doc/opal-api/opal-get-msi-39-40.rst           |  45 +-
 doc/opal-api/opal-get-xive-20.rst             |   9 +-
 doc/opal-api/opal-get-xive-source-38.rst      |  32 -
 doc/opal-api/opal-handle-hmi-98-166.rst       | 187 ++---
 doc/opal-api/opal-handle-interrupt.rst        |   2 +-
 doc/opal-api/opal-i2c-request-109.rst         |  64 ++
 doc/opal-api/opal-imc-counters.rst            |  32 +-
 doc/opal-api/opal-int-eoi-124.rst             |  13 +-
 doc/opal-api/opal-int-get-xirr-122.rst        |  13 +-
 doc/opal-api/opal-int-set-cppr-123.rst        |  12 +-
 doc/opal-api/opal-int-set-mfrr-125.rst        |  14 +-
 doc/opal-api/opal-ipmi-send-recv-107-108.rst  | 111 ++-
 doc/opal-api/opal-led-get-set-114-115.rst     |  74 +-
 doc/opal-api/opal-lpc-read-write-67-68.rst    |  92 ++-
 doc/opal-api/opal-messages.rst                |  11 +-
 ...tcr-127.txt => opal-nmmu-set-ptcr-127.rst} |  25 +-
 doc/opal-api/opal-nvram-read-write-7-8.rst    |  72 +-
 doc/opal-api/opal-param-89-90.rst             |  84 +++
 ...ci-config-read-write-13-14-15-16-17-18.rst | 132 ++++
 doc/opal-api/opal-pci-eeh-freeze-clear-26.rst |  33 +
 doc/opal-api/opal-pci-eeh-freeze-set-97.rst   |  29 +
 .../opal-pci-eeh-freeze-status-23.rst         |  71 ++
 doc/opal-api/opal-pci-err-inject-96.rst       |  54 ++
 .../opal-pci-get-hub-diag-data-50.rst         |  81 +++
 .../opal-pci-get-phb-diag-data2-64.rst        | 251 ++++++-
 doc/opal-api/opal-pci-get-power-state-120.rst |  17 +-
 .../opal-pci-get-presence-state-119.rst       |  16 +-
 ...al-pci-get-set-pbcq-tunnel-bar-164-165.rst |  42 +-
 .../opal-pci-get-set-xive-reissue-35-36.rst   |  18 -
 .../opal-pci-map-pe-dma-window-44.rst         |  11 +-
 .../opal-pci-map-pe-dma-window-real-45.rst    |  14 +-
 .../opal-pci-map-pe-mmio-window-29.rst        |  21 +-
 doc/opal-api/opal-pci-msi-eoi-63.rst          |  24 +
 doc/opal-api/opal-pci-next-error-60.rst       |  41 ++
 doc/opal-api/opal-pci-phb-mmio-enable-27.rst  |  15 +-
 doc/opal-api/opal-pci-poll-62.rst             |  18 +
 doc/opal-api/opal-pci-reinit-53.rst           |  31 +
 doc/opal-api/opal-pci-reset-49.rst            |  42 ++
 doc/opal-api/opal-pci-set-mve-33.rst          |  12 +-
 doc/opal-api/opal-pci-set-mve-enable-34.rst   |  13 +-
 doc/opal-api/opal-pci-set-p2p-157.rst         |  22 +-
 doc/opal-api/opal-pci-set-pe-31.rst           |  36 +-
 doc/opal-api/opal-pci-set-peltv-32.rst        |  18 +-
 .../opal-pci-set-phb-capi-mode-93.rst         |  60 +-
 .../opal-pci-set-phb-mem-window-28.rst        |  23 +-
 doc/opal-api/opal-pci-set-power-state-121.rst |  23 +-
 doc/opal-api/opal-pci-set-xive-pe-37.rst      |  14 +-
 doc/opal-api/opal-pci-tce-kill-126.rst        |  27 +-
 doc/opal-api/opal-poll-events.rst             |  10 +-
 doc/opal-api/opal-power-shift-ratio.rst       |  60 +-
 doc/opal-api/opal-powercap.rst                |  60 +-
 doc/opal-api/opal-prd-msg-113.rst             |  10 +-
 doc/opal-api/opal-query-cpu-status-42.rst     |  35 +
 doc/opal-api/opal-quiesce-158.rst             |  87 ++-
 doc/opal-api/opal-read-write-tpo-103-104.rst  |  15 -
 .../opal-read-write-tpo-dpo-103-104-105.rst   |  82 +++
 .../opal-register-dump-region-101.rst         |  45 --
 doc/opal-api/opal-reinit-cpus-70.rst          |  18 +-
 doc/opal-api/opal-resync-timebase-79.rst      |  21 +
 doc/opal-api/opal-return-cpu-69.rst           |  19 -
 ...read-3.rst => opal-rtc-read-write-3-4.rst} |  48 +-
 doc/opal-api/opal-rtc-write-4.rst             |   9 -
 doc/opal-api/opal-sensor-group-clear-156.rst  |  42 --
 doc/opal-api/opal-sensor-group-enable-163.rst |  46 --
 ...opal-sensor-group-enable-clear-163-156.rst |  88 +++
 doc/opal-api/opal-sensor-read-88.rst          |  71 +-
 doc/opal-api/opal-sensor-read-u64-162.rst     |  16 -
 doc/opal-api/opal-set-xive-19.rst             |   7 +-
 doc/opal-api/opal-slw-set-reg-100.rst         |  40 +-
 doc/opal-api/opal-start-return-cpu-41-69.rst  |  57 ++
 doc/opal-api/opal-sync-host-reboot-87.rst     |  19 +-
 doc/opal-api/opal-test-0.rst                  |  14 +-
 .../opal-unregister-dump-region-102.rst       |  19 -
 doc/opal-api/opal-write-oppanel-async-95.rst  |  49 ++
 doc/opal-api/opal-xscom-read-write-65-66.rst  |  91 ++-
 doc/opal-api/return-codes.rst                 | 314 ++++++++-
 doc/opal-spec.rst                             |   2 +-
 doc/overview.rst                              |   8 +-
 doc/process/stable-skiboot-rules.rst          |   1 +
 doc/release-notes/skiboot-4.0.rst             |  16 +
 doc/release-notes/skiboot-4.1.1.rst           |  40 ++
 doc/release-notes/skiboot-4.1.rst             |  43 ++
 doc/release-notes/skiboot-5.0.rst             | 145 ++++
 doc/release-notes/skiboot-5.1.0.rst           |   2 +
 doc/release-notes/skiboot-5.1.13.rst          |   2 +
 doc/release-notes/skiboot-5.10-rc1.rst        |   2 +-
 doc/release-notes/skiboot-5.10.rst            |   2 +-
 doc/release-notes/skiboot-5.3.0.rst           |   4 +-
 doc/release-notes/skiboot-5.4.9.rst           |  16 +
 doc/release-notes/skiboot-5.9-rc5.rst         |   3 +-
 doc/release-notes/skiboot-5.9.8.rst           |  16 +
 doc/release-notes/skiboot-6.0.12.rst          |  24 +
 doc/release-notes/skiboot-6.0.18.rst          |   1 +
 doc/release-notes/skiboot-6.0.20.rst          |  97 +--
 doc/release-notes/skiboot-6.0.3.rst           |  53 ++
 doc/release-notes/skiboot-6.0.9.rst           | 139 ++++
 doc/release-notes/skiboot-6.0.rst             |   1 +
 doc/release-notes/skiboot-6.2.2.rst           |   7 +-
 doc/release-notes/skiboot-6.2.4.rst           | 163 ++---
 doc/xive.rst                                  |  35 +
 hw/cec.c                                      |  14 -
 hw/npu.c                                      |   1 -
 hw/npu2-opencapi.c                            |   1 -
 hw/npu2.c                                     |   1 -
 hw/p7ioc-phb.c                                |  15 -
 hw/phb3.c                                     |   1 -
 hw/phb4.c                                     |   1 -
 include/opal-api.h                            |  10 +-
 include/pci.h                                 |  11 -
 129 files changed, 4718 insertions(+), 1316 deletions(-)
 create mode 100644 doc/device-tree/ibm,opal/nvram.rst
 create mode 100644 doc/device-tree/ibm,opal/sysparams.rst
 create mode 100644 doc/opal-api/opal-config-cpu-idle-state-99.rst
 create mode 100644 doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst
 create mode 100644 doc/opal-api/opal-get-epow-status-56.rst
 delete mode 100644 doc/opal-api/opal-get-xive-source-38.rst
 create mode 100644 doc/opal-api/opal-i2c-request-109.rst
 rename doc/opal-api/{opal-nmmu-set-ptcr-127.txt => opal-nmmu-set-ptcr-127.rst} (53%)
 create mode 100644 doc/opal-api/opal-param-89-90.rst
 create mode 100644 doc/opal-api/opal-pci-config-read-write-13-14-15-16-17-18.rst
 create mode 100644 doc/opal-api/opal-pci-eeh-freeze-clear-26.rst
 create mode 100644 doc/opal-api/opal-pci-eeh-freeze-set-97.rst
 create mode 100644 doc/opal-api/opal-pci-eeh-freeze-status-23.rst
 create mode 100644 doc/opal-api/opal-pci-err-inject-96.rst
 create mode 100644 doc/opal-api/opal-pci-get-hub-diag-data-50.rst
 delete mode 100644 doc/opal-api/opal-pci-get-set-xive-reissue-35-36.rst
 create mode 100644 doc/opal-api/opal-pci-msi-eoi-63.rst
 create mode 100644 doc/opal-api/opal-pci-next-error-60.rst
 create mode 100644 doc/opal-api/opal-pci-poll-62.rst
 create mode 100644 doc/opal-api/opal-pci-reinit-53.rst
 create mode 100644 doc/opal-api/opal-pci-reset-49.rst
 create mode 100644 doc/opal-api/opal-query-cpu-status-42.rst
 delete mode 100644 doc/opal-api/opal-read-write-tpo-103-104.rst
 create mode 100644 doc/opal-api/opal-read-write-tpo-dpo-103-104-105.rst
 delete mode 100644 doc/opal-api/opal-register-dump-region-101.rst
 create mode 100644 doc/opal-api/opal-resync-timebase-79.rst
 delete mode 100644 doc/opal-api/opal-return-cpu-69.rst
 rename doc/opal-api/{opal-rtc-read-3.rst => opal-rtc-read-write-3-4.rst} (55%)
 delete mode 100644 doc/opal-api/opal-rtc-write-4.rst
 delete mode 100644 doc/opal-api/opal-sensor-group-clear-156.rst
 delete mode 100644 doc/opal-api/opal-sensor-group-enable-163.rst
 create mode 100644 doc/opal-api/opal-sensor-group-enable-clear-163-156.rst
 delete mode 100644 doc/opal-api/opal-sensor-read-u64-162.rst
 create mode 100644 doc/opal-api/opal-start-return-cpu-41-69.rst
 delete mode 100644 doc/opal-api/opal-unregister-dump-region-102.rst
 create mode 100644 doc/opal-api/opal-write-oppanel-async-95.rst
 create mode 100644 doc/release-notes/skiboot-4.0.rst
 create mode 100644 doc/release-notes/skiboot-4.1.1.rst
 create mode 100644 doc/release-notes/skiboot-4.1.rst
 create mode 100644 doc/release-notes/skiboot-5.0.rst
 create mode 100644 doc/release-notes/skiboot-5.4.9.rst
 create mode 100644 doc/release-notes/skiboot-5.9.8.rst
 create mode 100644 doc/release-notes/skiboot-6.0.12.rst
 create mode 100644 doc/release-notes/skiboot-6.0.3.rst
 create mode 100644 doc/release-notes/skiboot-6.0.9.rst

Stewart Smith <stewart@linux.ibm.com> writes:
> This giant patchset goes through and ensures that at the very least we
> have a bit of skeleton documentation for each OPAL API call.
>
> It also makes each API call documentation a bit prettier, and uses the
> proper C code formatting stuff that Sphinx gives us.
>
> I also had a good amount of diving into ancient history to work out what
> calls actually existed and when, and along the way found several ones
> that have never been implemented, or were implemented and *mostly*
> removed but no longer have any need to be around.
>
> I've tried to keep each patch pretty self contained to the one thing
> it's touching, which is kind of why this patch series is so long.

Series merged to master as of 63dd1315f5acd633c849a0d7ad057c7bc761a948.