From ab290966c9424f65c9b41947d117bd4015c53eb5 Mon Sep 17 00:00:00 2001 From: Kaike Wan Date: Mon, 16 Jun 2014 09:29:18 -0700 Subject: [PATCH] ibacm: update man page This patch updates the ibacm man page after the introduction of the provider interface. Signed-off-by: Kaike Wan --- man/ibacm.1 | 63 +++++++++++++++++++++++++++++------------------------ man/ibacm.7 | 4 ++-- 2 files changed, 36 insertions(+), 31 deletions(-) diff --git a/man/ibacm.1 b/man/ibacm.1 index fb15752..29ecd86 100644 --- a/man/ibacm.1 +++ b/man/ibacm.1 @@ -1,4 +1,4 @@ -.TH "ibacm" 1 "2013-07-18" "ibacm" "ibacm" ibacm +.TH "ibacm" 1 "2014-06-16" "ibacm" "ibacm" ibacm .SH NAME ibacm \- address and route resolution services for InfiniBand. .SH SYNOPSIS @@ -25,14 +25,17 @@ however existing applications should still see significant connection scaling benefits using the calls available in librdmacm 1.0.11 and previous releases. .P -The IB ACM is focused on being scalable and efficient. The current -implementation limits network traffic, SA interactions, and centralized -services. ACM supports multiple resolution protocols in order to handle +The IB ACM is focused on being scalable, efficient, and extensible. It implements +a plugin architecture that allows a vendor to supply its proprietary provider in +addition to the default provider. The current default provider implementation +ibacmp limits network traffic, SA interactions, and centralized +services. Ibacmp supports multiple resolution protocols in order to handle different fabric topologies. .P -The IB ACM package is comprised of two components: the ibacm service -and a test/configuration utility - ib_acme. Both are userspace components -and are available for Linux and Windows. Additional details are given below. +The IB ACM package is comprised of three components: the ibacm core service, +the default provider ibacmp shared library, and a test/configuration utility +- ib_acme. All three are userspace components and are available for Linux. +Additional details are given below. .SH "OPTIONS" .TP \-D @@ -51,7 +54,7 @@ option configuration file The IB stack should be running with IPoIB configured. These steps assume that the user has administrative privileges. .P -2. Install the IB ACM package. This installs ibacm, ib_acme, and init.d scripts. +2. Install the IB ACM package. This installs ibacm, ibacmp, ib_acme, and init.d scripts. .P 3. Run 'ibacm' as administrator to start the ibacm daemon. .P @@ -64,7 +67,9 @@ The librdmacm will automatically use the ibacm service. On failures, the librdmacm will fall back to normal resolution. .P 6. You can use ib_acme -P to gather performance statistics from the local ibacm -daemon to see if the service is working correctly. +daemon to see if the service is working correctly. Similarly, the command +ib_acme -e could be used to enumerate all endpoints created by the local ibacm +service. .SH "NOTES" ib_acme: .P @@ -80,14 +85,15 @@ The ibacm service relies on two configuration files. .P The ibacm_addr.cfg file contains name and address mappings for each IB endpoint. Although the names in the ibacm_addr.cfg -file can be anything, ib_acme maps the host name and IP addresses to -the IB endpoints. If the address file cannot be found, the ibacm -service will attempt to create one using default values. +file can be anything, ib_acme maps the host name to the IB endpoints. IP +addresses, on the other hand, are assigned dynamically. If the address file +cannot be found, the ibacm service will attempt to create one using default +values. .P The ibacm_opts.cfg file provides a set of configurable options for the -ibacm service, such as timeout, number of retries, logging level, etc. -ib_acme generates the ibacm_opts.cfg file using static information. If -an option file cannot be found, ibacm will use default values. +ibacm core service and default provider, such as timeout, number of retries, +logging level, etc. ib_acme generates the ibacm_opts.cfg file using static +information. If an option file cannot be found, ibacm will use default values. .P ibacm: .P @@ -96,34 +102,33 @@ InfiniBand path information and caching such data. It should execute with administrative privileges. .P The ibacm implements a client interface over TCP sockets, which is -abstracted by the librdmacm library. One or more back-end protocols are -used by the ibacm service to satisfy user requests. Although the -ibacm supports standard SA path record queries on the back-end, it +abstracted by the librdmacm library. One or more providers can be loaded +by the core service, depending on the configuration. In the default provider +ibacmp, one or more back-end protocols are used to satisfy user requests. +Although ibacmp supports standard SA path record queries on the back-end, it also supports a resolution protocol based on multicast traffic. The latter is not usable on all fabric topologies, specifically ones that may not have reversible paths or fabrics using torus routing. Users should use the ib_acme utility to verify that multicast protocol is usable before running other applications. .P -Conceptually, the ibacm service implements an ARP like protocol and either +Conceptually, the default provider ibacmp implements an ARP like protocol and either uses IB multicast records to construct path record data or queries the SA directly, depending on the selected route protocol. By default, the -ibacm services uses and caches SA path record queries. +ibacmp provider uses and caches SA path record queries. .P Specifically, all IB endpoints join a number of multicast groups. Multicast groups differ based on rates, mtu, sl, etc., and are prioritized. All participating endpoints must be able to communicate on the lowest -priority multicast group. The ibacm assigns one or more names/addresses +priority multicast group. The ibacmp assigns one or more names/addresses to each IB endpoint using the ibacm_addr.cfg file. Clients provide source and destination names or addresses as input to the service, and receive as output path record data. .P The service maps a client's source name/address to a local IB endpoint. -If a client does not provide a source address, then the ibacm service -will select one based on the destination and local routing tables. If the -destination name/address is not cached locally, it sends a multicast -request out on the lowest priority multicast group on the local endpoint. -The request carries a list of multicast groups that the sender can use. +If the destination name/address is not cached locally in the default provider, +it sends a multicast request out on the lowest priority multicast group on the +local endpoint. The request carries a list of multicast groups that the sender can use. The recipient of the request selects the highest priority multicast group that it can use as well and returns that information directly to the sender. The request data is cached by all endpoints that receive the multicast @@ -131,9 +136,9 @@ request message. The source endpoint also caches the response and uses the multicast group that was selected to construct or obtain path record data, which is returned to the client. .P -The current implementation of the IB ACM has several additional restrictions: +The current implementation of the provider ibacmp has several additional restrictions: .P -- The ibacm is limited in its handling of dynamic changes. +- The ibacmp is limited in its handling of dynamic changes. ibacm must be stopped and restarted if a cluster is reconfigured. .P - Cached data does not timed out and is only updated if a new resolution @@ -146,7 +151,7 @@ limited to 4. .P - The number of multicast groups that an endpoint can support is limited to 2. .P -The ibacm contains several internal caches. These include caches for GID +The ibacmp contains several internal caches. These include caches for GID and LID destination addresses. These caches can be optionally preloaded. ibacm supports the OpenSM dump_pr plugin "full" PathRecord format which is used to preload these caches. diff --git a/man/ibacm.7 b/man/ibacm.7 index 06acf5b..ad502cd 100644 --- a/man/ibacm.7 +++ b/man/ibacm.7 @@ -1,8 +1,8 @@ -.TH "IBACM" 7 "2012-03-01" "IBACM" "IB ACM User Guide" IBACM +.TH "IBACM" 7 "2014-06-16" "IBACM" "IB ACM User Guide" IBACM .SH NAME ibacm \- InfiniBand communication management assistant .SH SYNOPSIS -.B "#include " +.B "#include " .SH "DESCRIPTION" Used to resolve remote endpoint information before establishing communications over InfiniBand. -- 2.41.0