Document MCA parameter changes from move from ORTE to PRRTE.

Addresses Github issue open-mpi#7668

Co-authored-by: [email protected]

Signed-off-by: Quincey Koziol <[email protected]>

docs/mca.rst

@@ -655,3 +655,269 @@ presented here so that they can easily be found via internet searches:
      ``^accelerator,btl/uct``, then Open MPI will only warn about the
      failure to load DSOs that are neither in the accelerator
      framework nor are the UCT BTL.
+
+.. _label-mca-backward-compat:
+
+MCA Parameter Changes Between Open MPI 4.x and 5.x
+--------------------------------------------------
+
+When Open MPI :ref:`switched from using ORTE to PRRTE as its run-time
+environment, <label-running-role-of-pmix-and-prte>` some MCA
+parameters were renamed to be more consistent and/or allow more
+flexible behavior.  The deprecated Open MPI MCA parameters listed
+below are currently replaced by a corresponding new PRRTE parameter,
+but may be removed in future releases.
+
+.. note:: In all cases listed below, the deprecated MCA parameter is
+          an Open MPI MCA parameter, meaning that its corresponding
+          environment variable was prefixed with ``OMPI_MCA_`` (e.g.,
+          ``OMPI_MCA_orte_xml_output``).  However, the corresponding
+          new MCA parameter is a PRRTE MCA parameter, meaning that its
+          corresponding environment variable is prefixed with
+          ``PRTE_MCA_`` (e.g., ``PRTE_MCA_output``).
+
+          .. important:: Yes, that's a single ``R`` in the
+                         ``PRTE_MCA_`` environment variable prefix.
+                         `See this explanation
+                         <https://docs.prrte.org/>`_ for the when one
+                         R or two R's are used in the PRRTE name.
+
+
+.. list-table::
+    :header-rows: 1
+
+    * - Behavior
+      - Deprecated MCA parameter
+      - Replaced with
+
+    * - Control buffering of stream output
+      - ``orte_ess_base_stream_buffering``
+
+        Values:  0 | 1 | 2
+
+      - ``ompi_stream_buffering``
+
+        Values: same
+
+    * - Output a brief periodic report on launch progress
+      - ``orte_report_launch_progress``
+
+        Values: boolean
+      - ``state_base_show_launch_progress``
+
+        Values: same
+
+    * - Provide all output in XML format
+      - ``orte_xml_output``
+
+        Values: boolean
+      - ``output``
+
+        Value: ``xml``
+
+    * - Tag all output with [job,rank]
+      - ``orte_tag_output``
+
+        Values: boolean
+      - ``output``
+
+        Value: ``tag``
+
+    * - Timestamp all application process output
+      - ``orte_timestamp_output``
+
+        Values: boolean
+      - ``output``
+
+        Value: ``timestamp``
+
+    * - Redirect output from application processes into filename / job
+        / rank / stdout / stderr / stdddiag.
+      - ``orte_output_filename``
+
+        Value: ``<filenname>``
+      - ``output``
+
+        Value: ``file=<filename>``
+
+    * - Display a detailed process map just before launch
+      - ``rmaps_base_display_devel_map``
+
+        Values: boolean
+      - ``display``
+
+        Value: ``map-devel``
+
+    * - Display the topology as part of the process map just before
+        launch
+      - ``rmaps_base_display_topo_with_map``
+
+        Values: ``<value>``
+      - ``display``
+
+        Value: ``topo=<value>``
+
+    * - Whether to report process bindings to stderr
+      - ``hwloc_base_report_bindings``
+
+        Values: boolean
+      - ``display``
+
+        Value: ``bind``
+
+    * - Display the process map just before launch
+      - ``rmaps_base_display_map``
+
+        Values: boolean
+      - ``display``
+
+        Value: ``map``
+
+    * - Display the allocation being used by this job
+      - ``orte_display_alloc``
+
+        Values: boolean
+      - ``display``
+
+        Value: ``allocation``
+
+    * - Do not run any MPI applications on the local node
+      - ``rmaps_base_no_schedule_local``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``[<value>]:nolocal``
+
+    * - Nodes are allowed to be oversubscribed, even on a managed
+        system, and overloading of processing elements
+      - ``rmaps_base_oversubscribe``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``[<value>]:oversubscribe``
+
+    * - Nodes are not to be oversubscribed, even if the system
+        supports such operation
+      - ``rmaps_base_no_oversubscribe``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``[<value>]:nooversubscribe``
+
+    * - Use hardware threads as independent CPUs
+      - ``hwloc_base_use_hwthreads_as_cpus``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``[<value>]:hwtcpus``
+
+    * - Comma-separated list of ranges specifying logical cpus
+        allocated to this job
+      - ``hwloc_base_cpu_set``
+
+        Value: ``<value>``
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``pe-list=<value>``
+
+    * - List of processor IDs to bind processes to
+      - ``hwloc_base_cpu_list``
+
+        Value: ``<value>``
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``pe-list=<value>```
+
+    * - Bind processes to cores
+      - ``hwloc_base_bind_to_core``
+
+        Values: boolean
+      - ``hwloc_default_binding_policy``
+
+        Value: ``core``
+
+    * - Bind processes to sockets
+      - ``hwloc_base_bind_to_socket``
+
+        Values: boolean
+      - ``hwloc_default_binding_policy``
+
+        Value: ``package``
+
+    * - Whether to map and rank processes round-robin by node
+      - ``rmaps_base_bynode``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``node``
+
+    * - Whether to map and rank processes round-robin by core
+      - ``rmaps_base_bycore``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``core``
+
+    * - Whether to map and rank processes round-robin by slot
+      - ``rmaps_base_byslot``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``slot``
+
+    * - Number of cpus to use for each process
+      - ``rmaps_base_cpus_per_rank``
+
+        Value: ``<X>``
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``[<value>]:pe=<X>``
+
+    * - Launch n processes per node on all allocated nodes
+      - ``rmaps_ppr_n_pernode``
+
+        Value: ``<X>``
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``ppr:<X>:node``
+
+    * - Launch one process per available node
+      - ``rmaps_ppr_pernode``
+
+        Values: boolean
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``ppr:1:node``
+
+    * - Launch n processes per socket on all allocated nodes
+      - ``rmaps_ppr_n_persocket``
+
+        Value: integer ``<X>``
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``ppr:<X>:package``
+
+    * - Comma-separated list of number of processes on a given
+        resource type
+      - ``rmaps_ppr_pattern``
+
+        Value: ``<value>``
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``ppr:<value>``
+
+    * - Provide a rankfile file
+      - ``orte_rankfile``
+
+        Value: ``<filename>``
+      - ``rmaps_default_mapping_policy``
+
+        Value: ``rankfile:file=<filename>``
+

docs/version-numbering.rst

@@ -50,6 +50,12 @@ Similarly, if using a container technology that internally bundles all
 the libraries from Open MPI vX, attempting to launch that container
 with ``mpirun`` / ``oshrun`` from Open MPI vY is not guaranteed to work.
 
+Open MPI |ompi_series| MCA parameter compatibility
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Several MCA parameters have been deprecated in Open MPI |ompi_series|, please
+see this :ref:`table <label-mca-backward-compat>` for the full list.
+
 Software Version Number
 -----------------------