1.1 --- a/docs/wiki/Clients Sun Apr 26 18:25:12 2020 +0200
1.2 +++ b/docs/wiki/Clients Sun Apr 26 22:58:32 2020 +0200
1.3 @@ -49,6 +49,13 @@
1.4 #include "calc_client.h"
1.5 }}}
1.6
1.7 +To obtain references to components via the L4Re environment, the following
1.8 +include statement is required:
1.9 +
1.10 +{{{
1.11 +#include <l4/re/env.h>
1.12 +}}}
1.13 +
1.14 == C Language Clients ==
1.15
1.16 An object representing the component will have the `Calc` type. This
1.17 @@ -120,3 +127,31 @@
1.18
1.19 Since a common base class is used to declare the interface, local and remote
1.20 components are interchangeable.
1.21 +
1.22 +== Accessing Component Servers ==
1.23 +
1.24 +In L4Re, components can be made available to programs via capabilities
1.25 +provided in the program environment. Given the presence of such a capability,
1.26 +registered with the name of `server` and associated with a component server,
1.27 +access to the remote component can be obtained as follows:
1.28 +
1.29 +{{{
1.30 +l4_cap_idx_t server = l4re_env_get_cap("server");
1.31 +}}}
1.32 +
1.33 +Thereafter, the techniques described above should be sufficient to communicate
1.34 +with and invoke the operations of the component.
1.35 +
1.36 +== Example Code ==
1.37 +
1.38 +The `pkg/idl4re-examples` directory contains some example packages for L4Re
1.39 +that feature some of the above code and demonstrate the techniques involved.
1.40 +The `idl4re-examples` directory can be copied into the L4Re distribution's
1.41 +`pkg` directory and built as follows:
1.42 +
1.43 +{{{
1.44 +make O=mybuild S=pkg/idl4re-examples
1.45 +}}}
1.46 +
1.47 +The `mybuild` directory name should be adjusted to match your own choice of
1.48 +build output directory.
2.1 --- a/docs/wiki/Servers Sun Apr 26 18:25:12 2020 +0200
2.2 +++ b/docs/wiki/Servers Sun Apr 26 22:58:32 2020 +0200
2.3 @@ -46,6 +46,12 @@
2.4 #include "calc_server.h"
2.5 }}}
2.6
2.7 +To expose components as servers, a `libipc` header file is also needed:
2.8 +
2.9 +{{{
2.10 +#include <ipc/server.h>
2.11 +}}}
2.12 +
2.13 == C Language Servers ==
2.14
2.15 An object representing a server will have the `Calc` type. This encapsulates
2.16 @@ -213,7 +219,48 @@
2.17
2.18 In L4Re, component objects can be made available to other programs by
2.19 associating them with interprocess communication (IPC) "gate" capabilities and
2.20 -then waiting for incoming messages. Upon receiving a message, the identity of
2.21 -the gate providing the message can be tested, and if it is the gate associated
2.22 -with a component, the message can then be interpreted and directed at the
2.23 -component as an invocation.
2.24 +then waiting for incoming messages.
2.25 +
2.26 +Given an existing capability accessible via the program environment, a
2.27 +component can be exposed to other programs as follows:
2.28 +
2.29 +{{{
2.30 +ipc_server_bind("server", (l4_umword_t) &obj, &server);
2.31 +}}}
2.32 +
2.33 +Here, the `server` variable is of type `l4_cap_idx_t` (indicating a
2.34 +capability). The named capability is obtained and assigned to the variable,
2.35 +with the object itself presented to label incoming messages, indicating which
2.36 +IPC gate was involved in delivering the message.
2.37 +
2.38 +The details of waiting for messages, testing the label, and directing requests
2.39 +to the component are dealt with by another convenience function:
2.40 +
2.41 +{{{
2.42 +ipc_server_loop(Calc_expected_items, &obj, (ipc_server_handler_type) handle_Calc);
2.43 +}}}
2.44 +
2.45 +Here, the following parameters are specified:
2.46 +
2.47 + * The predefined number of items expected for the `Calc` interface, generated
2.48 + automatically and provided by `Calc_expected_items`
2.49 +
2.50 + * The object address which is used to check message labels
2.51 +
2.52 + * A handler function for directing requests to the component, this being
2.53 + provided by the generated `handle_Calc` function which must be cast to an
2.54 + acceptable type as indicated
2.55 +
2.56 +== Example Code ==
2.57 +
2.58 +The `pkg/idl4re-examples` directory contains some example packages for L4Re
2.59 +that feature some of the above code and demonstrate the techniques involved.
2.60 +The `idl4re-examples` directory can be copied into the L4Re distribution's
2.61 +`pkg` directory and built as follows:
2.62 +
2.63 +{{{
2.64 +make O=mybuild S=pkg/idl4re-examples
2.65 +}}}
2.66 +
2.67 +The `mybuild` directory name should be adjusted to match your own choice of
2.68 +build output directory.