--- #YAML:1.0
# This is a YAML formatted file with '#'-style comments.  This file
# *must* be parseable by the YAML::Tiny perl module.  So don't use
# the inline list or map forms and don't try to use any really fancy
# features like tagging or anchors.
#
# It is used to generate parameter-handling code for MPICH.
# See the maint/genparams script for more information.
#
# The only tricky bit is that long reflowed text (such as a description)
# should use ">-" to both fold newlines and remove the trailing newline.
#
# Listing "FOO" as a parameter name will cause two environment variables
# to be examined by default: MPIR_PARAM_FOO and MPICH_FOO, with the
# MPIR_PARAM value having priority.
categories:
    - name        : collective
      description : parameters that control collective communication behavior
    - name        : communicator
      description : parameters that control communicator construction and operation
    - name        : pt2pt
      description : parameters that control point-to-point communication behavior
    - name        : rma
      description : parameters that control RMA communicatin behavior
    - name        : intranode
      description : intranode communication parameters
    - name        : developer
      description : useful for developers working on MPICH itself
    - name        : memory
      description : affects memory allocation and usage, including MPI object handles
    - name        : error_handling
      description : parameters that control error handling behavior (stack traces, aborts, etc)
    - name        : debugger
      description : parameters relevant to the "MPIR" debugger interface
    - name        : checkpointing
      description : parameters relevant to checkpointing
    - name        : fault_tolerance
      description : parameters that control fault tolerance behavior
    - name        : threads
      description : multi-threading parameters
    - name        : ch3
      description : parameters that control behavior of ch3
    - name        : nemesis
      description : "parameters that control behavior of the ch3:nemesis channel"
    - name        : sockets
      description : control socket parameters

parameters:
    ##############################################################
    # collective parameters
    - category    : collective
      name        : ALLTOALL_SHORT_MSG_SIZE
      type        : int
      default     : 256
      description : >-
        the short message algorithm will be used if the per-destination
        message size (sendcount*size(sendtype)) is <= this value

    - category    : collective
      name        : ALLTOALL_MEDIUM_MSG_SIZE
      type        : int
      default     : 32768
      description : >-
        the medium message algorithm will be used if the per-destination
        message size (sendcount*size(sendtype)) is <= this value and
        larger than ALLTOALL_SHORT_MSG_SIZE

    - category    : collective
      name        : ALLTOALL_THROTTLE
      type        : int
      default     : 4
      description : >-
        max no. of irecvs/isends posted at a time in some alltoall
        algorithms. Setting it to 0 causes all irecvs/isends to be
        posted at once.

    - category    : collective
      name        : REDSCAT_COMMUTATIVE_LONG_MSG_SIZE
      type        : int
      default     : 524288
      description : >-
        the long message algorithm will be used if the operation is commutative
        and the send buffer size is >= this value (in bytes)

    - category    : collective
      name        : BCAST_MIN_PROCS
      type        : int
      default     : 8
      description : >-
        the minimum number of processes in a communicator to use a non-binomial
        broadcast algorithm

    - category    : collective
      name        : BCAST_SHORT_MSG_SIZE
      type        : int
      default     : 12288
      description : >-
        the short message algorithm will be used if the send buffer size is <
        this value (in bytes)

    - category    : collective
      name        : BCAST_LONG_MSG_SIZE
      type        : int
      default     : 524288
      description : >-
        the long message algorithm will be used if the send buffer size is >=
        this value (in bytes)

    - category    : collective
      name        : ALLGATHER_SHORT_MSG_SIZE
      type        : int
      default     : 81920
      description : >-
        For MPI_Allgather and MPI_Allgatherv, the short message algorithm will
        be used if the send buffer size is < this value (in bytes).

    - category    : collective
      name        : ALLGATHER_LONG_MSG_SIZE
      type        : int
      default     : 524288
      description : >-
        For MPI_Allgather and MPI_Allgatherv, the long message algorithm will be
        used if the send buffer size is >= this value (in bytes)

    - category    : collective
      name        : REDUCE_SHORT_MSG_SIZE
      type        : int
      default     : 2048
      description : >-
        the short message algorithm will be used if the send buffer size is <=
        this value (in bytes)

    - category    : collective
      name        : ALLREDUCE_SHORT_MSG_SIZE
      type        : int
      default     : 2048
      description : >-
        the short message algorithm will be used if the send buffer size is <=
        this value (in bytes)

    - category    : collective
      name        : GATHER_VSMALL_MSG_SIZE
      type        : int
      default     : 1024
      description : >-
        use a temporary buffer for intracommunicator MPI_Gather if the send
        buffer size is < this value (in bytes)

    - category    : collective
      name        : GATHER_INTER_SHORT_MSG_SIZE
      type        : int
      default     : 2048
      description : >-
        use the short message algorithm for intercommunicator MPI_Gather if the
        send buffer size is < this value (in bytes)

    - category    : collective
      name        : GATHERV_INTER_SSEND_MIN_PROCS
      # backwards compatibility
      abs-alt-env :
                    - MPICH_GATHERV_MIN_PROCS
      type        : int
      default     : 32
      description : >-
        Use Ssend (synchronous send) for intercommunicator MPI_Gatherv if the
        "group B" size is >= this value.  Specifying "-1" always avoids using
        Ssend.  For backwards compatibility, specifying "0" uses the default
        value.

    - category    : collective
      name        : SCATTER_INTER_SHORT_MSG_SIZE
      type        : int
      default     : 2048
      description : >-
        use the short message algorithm for intercommunicator MPI_Scatter if the
        send buffer size is < this value (in bytes)

    - category    : collective
      name        : ALLGATHERV_PIPELINE_MSG_SIZE
      type        : int
      default     : 32768
      description : >-
        The smallest message size that will be used for the pipelined, large-message,
        ring algorithm in the MPI_Allgatherv implementation.

    ##############################################################
    # communicator parameters
    - category    : communicator
      name        : COMM_SPLIT_USE_QSORT
      type        : boolean
      default     : true
      description : >-
        Use qsort(3) in the implementation of MPI_Comm_split instead of bubble sort.
    ##############################################################
    # RMA parameters
    - category    : rma
      name        : RMA_ACC_IMMED
      type        : boolean
      default     : true
      description : >-
        Use the immediate accumulate optimization

    - category    : rma
      name        : RMA_NREQUEST_THRESHOLD
      type        : int
      default     : 4000
      description : >-
        Threshold at which the RMA implementation attempts to complete requests
        while completing RMA operations and while using the lazy synchonization
        approach.  Change this value if programs fail because they run out of 
        requests or other internal resources

    - category    : rma
      name        : RMA_NREQUEST_NEW_THRESHOLD
      type        : int
      default     : 128
      description : >-
        Threshold for the number of new requests since the last attempt to
        complete pending requests.  Higher values can increase performance, 
        but may run the risk of exceeding the available number of requests
        or other internal resources.

    - category    : rma
      name        : RMA_LOCK_IMMED
      type        : boolean
      default     : false
      description : >-
        Issue a request for the passive target RMA lock immediately.  Default
        behavior is to defer the lock request until the call to MPI_Win_unlock.

    - category    : rma
      name        : RMA_MERGE_LOCK_OP_UNLOCK
      type        : boolean
      default     : true
      description : >-
        Enable/disable an optimization that merges lock, op, and unlock
        messages, for single-operation passive target epochs.

    ##############################################################
    # intranode communication parameters
    - category    : intranode
      name        : NOLOCAL
      alt-env     :
                    - NO_LOCAL
      type        : boolean
      default     : false
      description : >-
        If true, force all processes to operate as though all processes
        are located on another node.  For example, this disables shared
        memory communication hierarchical collectives.

    - category    : intranode
      name        : ODD_EVEN_CLIQUES
      alt-env     :
                    - EVEN_ODD_CLIQUES
      type        : boolean
      default     : false
      description : >-
        If true, odd procs on a node are seen as local to each other, and even
        procs on a node are seen as local to each other.  Used for debugging on
        a single machine.

    - category    : intranode
      name        : POLLS_BEFORE_YIELD
      type        : int
      default     : 1000
      description : >-
        When MPICH is in a busy waiting loop, it will periodically
        call a function to yield the processor.  This parameter sets
        the number of loops before the yield function is called.  A 
        value of 0 disables yielding.

    - category    : developer
      name        : MEMDUMP
      type        : boolean
      default     : true
      description : >-
        If true, list any memory that was allocated by MPICH and that
        remains allocated when MPI_Finalize completes.

    - category    : debugger
      name        : PROCTABLE_SIZE
      type        : int
      default     : 64
      description : >-
        Size of the "MPIR" debugger interface proctable (process table).

    - category    : debugger
      name        : PROCTABLE_PRINT
      type        : boolean
      default     : true
      description : >-
        If true, dump the proctable entries at MPIR_WaitForDebugger-time.
        (currently compile-time disabled by "#if 0")

    - category    : error_handling
      name        : ERROR_CHECKING
      type        : boolean
      default     : true
      description : >-
        If true, perform checks for errors, typically to verify valid inputs
        to MPI routines.  Only effective when MPICH is configured with
        --enable-error-checking=runtime .

    - category    : error_handling
      name        : PRINT_ERROR_STACK
      type        : boolean
      default     : true
      description : >-
        If true, print an error stack trace at error handling time.

    - category    : error_handling
      name        : CHOP_ERROR_STACK
      type        : int
      default     : 0
      description : >-
        If >0, truncate error stack output lines this many characters
        wide.  If 0, do not truncate, and if <0 use a sensible default.

    - category    : intranode
      name        : NEM_LMT_DMA_THRESHOLD
      type        : int
      # 2048*1024 == 2MiB
      default     : 2097152
      description : >-
        Messages larger than this size will use the "dma" (knem)
        intranode LMT implementation, if it is enabled and available.

    - category    : nemesis
      name        : NEMESIS_NETMOD
      type        : string
      default     : ""
      description : >-
        If non-empty, this parameter specifies which network module
        should be used for communication.

    - category    : nemesis
      name        : INTERFACE_HOSTNAME
      type        : string
      defaultliteral : NULL
      description : >-
        If non-NULL, this parameter specifies the IP address that
        other processes should use when connecting to this process.
        This parameter is mutually exclusive with the
        MPICH_NETWORK_IFACE parameter and it is an error to set them
        both.

    - category    : nemesis
      name        : NETWORK_IFACE
      type        : string
      defaultliteral : NULL
      description : >-
        If non-NULL, this parameter specifies which pseudo-ethernet
        interface the tcp netmod should use (e.g., "eth1", "ib0"). 
        Note, this is a Linux-specific parameter.
        This parameter is mutually exclusive with the
        MPICH_INTERFACE_HOSTNAME parameter and it is an error to set
        them both.

    - category    : nemesis
      name        : HOST_LOOKUP_RETRIES
      type        : int
      default     : 10
      description : >-
        This parameter controls the number of times to retry the 
        gethostbyname() function before giving up.

    - category    : nemesis
      name        : SHM_EAGER_MAX_SZ
      type        : int
      default     : -1
      description : >-
        This parameter controls the message size at which Nemesis 
        switches from eager to rendezvous mode for shared memory.
        If this parameter is set to -1, then Nemesis will choose
        an appropriate value.

    - category    : nemesis
      name        : SHM_READY_EAGER_MAX_SZ
      type        : int
      default     : -2
      description : >-
        This parameter controls the message size at which Nemesis
        switches from eager to rendezvous mode for ready-send
        messages.  If this parameter is set to -1, then ready messages
        will always be sent eagerly.  If this parameter is set to -2,
        then Nemesis will choose an appropriate value.

    - category    : nemesis
      name        : COMM_OVERRIDES
      type        : boolean
      default     : true
      description : >-
        If set to false, communication override functionality will be
        disabled for netmods that provide the override feature.  Some
        netmods may not honor this flag.
        # Note the netmod must implement this functionality by not
        # setting the comm_ops table in any VC.

    - category    : ch3
      name        : CH3_EAGER_MAX_MSG_SIZE
      type        : int
      default     : 131072
      description : >-
        This parameter controls the message size at which CH3 switches
        from eager to rendezvous mode.


  ##############################################################
    # debugging parameters
    - category    : debugger
      name        : DEBUG_HOLD
      type        : boolean
      default     : false
      description : >-
        If true, causes processes to wait in MPI_Init and
        MPI_Initthread for a debugger to be attached.  Once the
        debugger has attached, the variable 'hold' should be set to 0
        in order to allow the process to continue (e.g., in gdb, "set
        hold=0").

  ##############################################################
    # checkpointing parameters
    - category    : checkpointing
      name        : ENABLE_CKPOINT
      type        : boolean
      default     : false
      description : >-
        If true, enables checkpointing support and returns an error if
        checkpointing library cannot be initialized.

  ##############################################################
    # fault-tolerance parameters
    - category    : fault_tolerance
      name        : ENABLE_COLL_FT_RET
      type        : boolean
      default     : false
      description : >-
        NOT COMPATIBLE WITH NONBLOCKING COLLECTIVES (see tt#1601)!!!
        Collectives called on a communicator with a failed process
        should not hang, however the result of the operation may be
        invalid even though the function returns MPI_SUCCESS.  This
        option enables an experimental feature that will return an error
        if the result of the collective is invalid.

  ##############################################################
    # memory parameters
    - category    : memory
      name        : ABORT_ON_LEAKED_HANDLES
      type        : boolean
      default     : false
      description : >-
        If true, MPI will call MPI_Abort at MPI_Finalize if any MPI object
        handles have been leaked.  For example, if MPI_Comm_dup is called
        without calling a corresponding MPI_Comm_free.  For uninteresting
        reasons, enabling this option may prevent all known object leaks from
        being reported.  MPICH must have been configure with
        "--enable-g=handlealloc" or better in order for this functionality to
        work.

  ############################
    # sockets parameters
    - category    : sockets
      name        : PORT_RANGE
      alt-env     : 
                    - PORTRANGE
      type        : range
      default     : "0:0"
      description : >-
        The MPICH_PORT_RANGE environment variable allows you to
        specify the range of TCP ports to be used by the process
        manager and the MPICH library. The format of this variable is
        <low>:<high>.

  ############################
    # threads parameters
    - category    : threads
      name        : CTXID_EAGER_SIZE
      type        : int
      default     : 2
      description : >-
        The MPICH_CTXID_EAGER_SIZE environment variable allows you to
        specify how many words in the context ID mask will be set aside
        for the eager allocation protocol.  If the application is running
        out of context IDs, reducing this value may help.

...

# Local Variables:
# mode: conf-colon
# indent-tabs-mode: nil
# End:
