Skip to content
Michal Shalev edited this page May 30, 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 must 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>[,<type>]   Show UCP memory allocation info for a given size and type
                       Supported memory types are: host
  -u <features>        UCP context features to use. String of one or more of:
                        'a' : atomic operations
                        'r' : remote memory access
                        't' : tag matching 
                        's' : stream 
                        'm' : active messages 
                        'x' : exported memory handle 
                       Modifiers to use in combination with above features:
                        'w' : wakeup
                        'e' : error handling

Other settings:
  -t <name>            Show devices of the 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
  -P <type>            Set peer process placement for printing UCP endpoint
                       configuration:
                         'self'  : same process (default)
                         'intra' : same node
                         'inter' : different node
  -A <ip>              Local IP device address to use for creating
                       endpoint in client/server mode
  -6                   IPv6 address specified with option -A
  -T                   Print system topology
  -M                   Print memory copy bandwidth
  -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