# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1587934712 -7200
# Node ID e92d1845dc4bfc2f3cda8f7bdb78bfb0b998701a
# Parent  1db570bde795b37f07975c9eba8aa6d94ada01ef
Expanded the clients and servers guides to cover the environment and examples.

diff -r 1db570bde795 -r e92d1845dc4b docs/wiki/Clients
--- a/docs/wiki/Clients	Sun Apr 26 18:25:12 2020 +0200
+++ b/docs/wiki/Clients	Sun Apr 26 22:58:32 2020 +0200
@@ -49,6 +49,13 @@
 #include "calc_client.h"
 }}}
 
+To obtain references to components via the L4Re environment, the following
+include statement is required:
+
+{{{
+#include <l4/re/env.h>
+}}}
+
 == C Language Clients ==
 
 An object representing the component will have the `Calc` type. This
@@ -120,3 +127,31 @@
 
 Since a common base class is used to declare the interface, local and remote
 components are interchangeable.
+
+== Accessing Component Servers ==
+
+In L4Re, components can be made available to programs via capabilities
+provided in the program environment. Given the presence of such a capability,
+registered with the name of `server` and associated with a component server,
+access to the remote component can be obtained as follows:
+
+{{{
+l4_cap_idx_t server = l4re_env_get_cap("server");
+}}}
+
+Thereafter, the techniques described above should be sufficient to communicate
+with and invoke the operations of the component.
+
+== Example Code ==
+
+The `pkg/idl4re-examples` directory contains some example packages for L4Re 
+that feature some of the above code and demonstrate the techniques involved. 
+The `idl4re-examples` directory can be copied into the L4Re distribution's 
+`pkg` directory and built as follows:
+
+{{{
+make O=mybuild S=pkg/idl4re-examples
+}}}
+
+The `mybuild` directory name should be adjusted to match your own choice of 
+build output directory.
diff -r 1db570bde795 -r e92d1845dc4b docs/wiki/Servers
--- a/docs/wiki/Servers	Sun Apr 26 18:25:12 2020 +0200
+++ b/docs/wiki/Servers	Sun Apr 26 22:58:32 2020 +0200
@@ -46,6 +46,12 @@
 #include "calc_server.h"
 }}}
 
+To expose components as servers, a `libipc` header file is also needed:
+
+{{{
+#include <ipc/server.h>
+}}}
+
 == C Language Servers ==
 
 An object representing a server will have the `Calc` type. This encapsulates
@@ -213,7 +219,48 @@
 
 In L4Re, component objects can be made available to other programs by
 associating them with interprocess communication (IPC) "gate" capabilities and
-then waiting for incoming messages. Upon receiving a message, the identity of
-the gate providing the message can be tested, and if it is the gate associated
-with a component, the message can then be interpreted and directed at the
-component as an invocation.
+then waiting for incoming messages.
+
+Given an existing capability accessible via the program environment, a
+component can be exposed to other programs as follows:
+
+{{{
+ipc_server_bind("server", (l4_umword_t) &obj, &server);
+}}}
+
+Here, the `server` variable is of type `l4_cap_idx_t` (indicating a
+capability). The named capability is obtained and assigned to the variable,
+with the object itself presented to label incoming messages, indicating which
+IPC gate was involved in delivering the message.
+
+The details of waiting for messages, testing the label, and directing requests
+to the component are dealt with by another convenience function:
+
+{{{
+ipc_server_loop(Calc_expected_items, &obj, (ipc_server_handler_type) handle_Calc);
+}}}
+
+Here, the following parameters are specified:
+
+ * The predefined number of items expected for the `Calc` interface, generated
+   automatically and provided by `Calc_expected_items`
+
+ * The object address which is used to check message labels
+
+ * A handler function for directing requests to the component, this being
+   provided by the generated `handle_Calc` function which must be cast to an
+   acceptable type as indicated
+
+== Example Code ==
+
+The `pkg/idl4re-examples` directory contains some example packages for L4Re
+that feature some of the above code and demonstrate the techniques involved.
+The `idl4re-examples` directory can be copied into the L4Re distribution's
+`pkg` directory and built as follows:
+
+{{{
+make O=mybuild S=pkg/idl4re-examples
+}}}
+
+The `mybuild` directory name should be adjusted to match your own choice of
+build output directory.