From: Kaike Wan <kaike.wan@intel.com>
Date: Mon, 16 Jun 2014 16:29:39 +0000 (-0700)
Subject: ibacm: add provider man page
X-Git-Url: https://openfabrics.org/gitweb/?a=commitdiff_plain;h=3cbbe4e84cdd9665f02b6f0bcddf0ff65747bee6;p=~shefty%2Fibacm.git

ibacm: add provider man page

This patch adds the man page for the provider interface.

Signed-off-by: Kaike Wan <kaike.wan@intel.com>
---

diff --git a/man/ibacm_prov.7 b/man/ibacm_prov.7
new file mode 100644
index 0000000..d04617e
--- /dev/null
+++ b/man/ibacm_prov.7
@@ -0,0 +1,80 @@
+.TH "IBACM_PROV" 7 "2014-06-16" "IBACM_PROV" "IB ACM Provider Guide" IBACM_PROV
+.SH NAME
+ibacm_prov \- InfiniBand communication management assistant provider interface
+.SH SYNOPSIS
+.B "#include <infiniband/acm_prov.h>"
+.SH "DESCRIPTION"
+The ibacm provider interface provides a plugin interface that allows a vendor
+to implement proprietary solutions to support scalable address and route 
+resolution services over InfiniBand.
+.P
+To add a provider to the ibacm core service, the provider must 
+.TP
+1. be implemented as a shared library;
+.TP
+2. be installed under a configured directory, eg., /usr/lib64/ibacm/;
+.TP
+3  export a function provider_query() that returns a pointer to its provider info 
+and version info.
+.P
+The prototype of provider_query function is defined below:
+.P
+.nf
+int provider_query(struct acm_provider **info, uint32_t *version);
+.fi
+.P
+This function should return a pointer to its provider structure:
+.P
+.nf
+struct acm_provider {
+	size_t    size; 
+	uint32_t  version;
+	char      *name;
+	int	(*open_device)(const struct acm_device *device, 
+			void **dev_context);
+	void	(*close_device)(void *dev_context);
+	int	(*open_port)(const struct acm_port *port, 
+			void *dev_context, void **port_context);
+	void	(*close_port)(void *port_context);
+	int	(*open_endpoint)(const struct acm_endpoint *endpoint, 
+			void *port_context, void **ep_context);
+	void	(*close_endpoint)(void *ep_context);
+	int	(*add_address)(const struct acm_address *addr, void *ep_context,
+			void **addr_context);
+	void	(*remove_address)(void *addr_context);
+	int	(*resolve)(void *addr_context, struct acm_msg *msg, uint64_t id);
+	int	(*query)(void *addr_context, struct acm_msg *msg, uint64_t id);
+	int	(*handle_event)(void *port_context, enum ibv_event_type type);
+	void	(*query_perf)(void *ep_context, uint64_t *values, uint8_t *cnt);
+};
+.fi
+.P
+The size and version fields provide a way to detect version compatibility.
+When a port is assigned to the provider, the ibacm core will call the
+open/add_address functions;  Similarly, when a port is down or re-assigned to
+another provider, the close/remove_address functions will be invoked to release
+resources.  The ibacm core will centralize the management of events for each device
+and events not handled by the ibacm core will be forwarded to the relevant port
+through the handle_event() function.  The resolve() function will be called to
+resolve a destination name into a path record.  The performance of the provider 
+for each endpoint can be queried by calling perf_query().
+.P
+To share a configuration file, the path for the ibacm configuration file is
+exported through the variable opts_file. Each loaded provider can open this 
+configuration file and parse the contents related to its own operation.  
+Non-related sections should be ignored.
+.P
+Some helper functions are also exported by the ibacm core. For example, the
+acm_log define (or the acm_write() function) can be used to log messages into
+ibacm's log file (default /var/log/ibacm.log).  For details, refer to
+the acm_prov.h file.
+.SH "NOTES"
+A provider should always set the version in its provider info structure as the
+value of the define ACM_PROV_VERSION at the time the provider is implemented.  Never
+set the version to ACM_PROV_VERSION itself as the define may be changed over time 
+when the provider interface is changed, unless the provider itself is placed in 
+ibacm source tree.  This is to avoid the version problem when the old provider 
+implementation is built against a new acm_prov.h file.  The ibacm will always 
+check the version of the provider at loading time.
+.SH "SEE ALSO"
+ib_acme(1), ibacm(1), ibacm(7)