Skip to content
Michal Shalev edited this page May 29, 2024 · 4 revisions

This tool prints various information about UCX library:

  • Version and build configuration
  • Configuration settings and help for every variable.
  • Sizes of various data structures
  • Transport information: devices and capabilities. The tool resides in src/tools/info.

Full options list:

$ ucx_info -h
Usage: ucx_info [options]
At least one of the following options has to be set:
  -v              Show version information
  -d              Show devices and transports
  -b              Show build configuration
  -y              Show type and structures information
  -s              Show system information
  -c              Show UCX configuration
  -C              Comment-out default configuration values
  -a              Show also hidden configuration
  -f              Display fully decorated output

UCP information (-u is required):
  -p              Show UCP context information
  -w              Show UCP worker information
  -e              Show UCP endpoint configuration
  -m <size>       Show UCP memory allocation method for a given size
  -u <features>   UCP context features to use. String of one or more of:
                    'a' : atomic operations
                    'r' : remote memory access
                    't' : tag matching 
                    'm' : active messages 
                    'w' : wakeup
                  Modifiers to use in combination with above features:
                    'e' : error handling

Other settings:
  -t <name>       Filter devices information using specified transport (requires -d)
  -n <count>      Estimated UCP endpoint count (for ucp_init)
  -N <count>      Estimated UCP endpoint count per node (for ucp_init)
  -D <type>       Set which device types to use when creating UCP context:
                    'all'  : all possible devices (default)
                    'shm'  : shared memory devices only
                    'net'  : network devices only
                    'self' : self transport only
  -A <ipv4>       Local IPv4 device address to use for creating
                  endpoint in client/server mode  -h              Show this help message

[mshalev@hpchead ucx]$ ucx_info -h
Usage: ucx_info [options]
At least one of the following options has to be set:
  -v              Show version information
  -d              Show devices and transports
  -b              Show build configuration
  -y              Show type and structures information
  -s              Show system information
  -c              Show UCX configuration
  -C              Comment-out default configuration values
  -a              Show also hidden configuration
  -f              Display fully decorated output

UCP information (-u is required):
  -p              Show UCP context information
  -w              Show UCP worker information
  -e              Show UCP endpoint configuration
  -m <size>       Show UCP memory allocation method for a given size
  -u <features>   UCP context features to use. String of one or more of:
                    'a' : atomic operations
                    'r' : remote memory access
                    't' : tag matching 
                    'm' : active messages 
                    'w' : wakeup
                  Modifiers to use in combination with above features:
                    'e' : error handling

Other settings:
  -t <name>       Filter devices information using specified transport (requires -d)
  -n <count>      Estimated UCP endpoint count (for ucp_init)
  -N <count>      Estimated UCP endpoint count per node (for ucp_init)
  -D <type>       Set which device types to use when creating UCP context:
                    'all'  : all possible devices (default)
                    'shm'  : shared memory devices only
                    'net'  : network devices only
                    'self' : self transport only
  -A <ipv4>       Local IPv4 device address to use for creating
                  endpoint in client/server mode
  -h              Show this help message

Sample output:

$ ucx_info -d
# Memory domain: mlx5_bond_0
#     Component: ib
#             register: unlimited, cost: 180 nsec
#           remote key: 8 bytes
#           local memory handle is required for zcopy
#
#      Transport: dc_mlx5
#         Device: mlx5_bond_0:1
#           Type: network
#  System device: mlx5_bond_0 (0)
#
#      capabilities:
#            bandwidth: 10957.84/ppn + 0.00 MB/sec
#              latency: 860 nsec
#             overhead: 40 nsec
#            put_short: <= 2K
#            put_bcopy: <= 8256
#            put_zcopy: <= 1G, up to 11 iov
#  put_opt_zcopy_align: <= 512
#        put_align_mtu: <= 1K
#            get_bcopy: <= 8256
#            get_zcopy: 65..1G, up to 11 iov
#  get_opt_zcopy_align: <= 512
#        get_align_mtu: <= 1K
#             am_short: <= 2046
#             am_bcopy: <= 8254
#             am_zcopy: <= 8254, up to 3 iov
#   am_opt_zcopy_align: <= 512
#         am_align_mtu: <= 1K
#            am header: <= 138
#               domain: device
#           atomic_add: 32, 64 bit
#           atomic_and: 32, 64 bit
#            atomic_or: 32, 64 bit
#           atomic_xor: 32, 64 bit
#          atomic_fadd: 32, 64 bit
#          atomic_fand: 32, 64 bit
#           atomic_for: 32, 64 bit
#          atomic_fxor: 32, 64 bit
#          atomic_swap: 32, 64 bit
#         atomic_cswap: 32, 64 bit
#           connection: to iface
#      device priority: 40
#     device num paths: 2
#              max eps: inf
#       device address: 18 bytes
#        iface address: 5 bytes
#       error handling: buffer (zcopy), remote access, peer failure, ep_check
$ UCX_TLS=rc_x UCX_NET_DEVICES=mlx5_bond_0:1 ucx_info -ep -u t
#
# UCP context
#
#     component 0  :  self
#     component 1  :  tcp
#     component 2  :  sysv
#     component 3  :  posix
#     component 4  :  ib
#     component 5  :  rdmacm
#     component 6  :  cma
#
#            md 0  :  component 4  mlx5_bond_0 
#
#      resource 0  :  md 0  dev 0  flags -- rc_mlx5/mlx5_bond_0:1
#      resource 1  :  md 0  dev 0  flags a- ud_mlx5/mlx5_bond_0:1
#
# memory: 0.24MB, file descriptors: 7
# create time: 19.528 ms
#
#
# UCP endpoint 
#
#               peer: <no debug data>
#                 lane[0]:  0:rc_mlx5/mlx5_bond_0:1.0 md[0]  -> md[0]/ib/sysdev[255] rma_bw#0 am am_bw#0
#                 lane[1]:  0:rc_mlx5/mlx5_bond_0:1.1 md[0]  -> md[0]/ib/sysdev[255] rma_bw#1 wireup
#
#                tag_send: 0..<egr/short>..2039..<egr/bcopy>..2325..<egr/zcopy>..28242..<rndv>..(inf)
#            tag_send_nbr: 0..<egr/short>..2039..<egr/bcopy>..262144..<rndv>..(inf)
#           tag_send_sync: 0..<egr/short>..2039..<egr/bcopy>..2325..<egr/zcopy>..28242..<rndv>..(inf)
#
#                  rma_bw: mds [0] rndv_rkey_size 18
#
Clone this wiki locally