Add document for libdfi and dynamic ip mechanism

bundles/remote_services/README.md

@@ -87,6 +87,22 @@ Provides a service discovery using Bonjour.
 |--|----------------------------|
 | **Configuration** | See  [Zeroconf Discovery](discovery_zeroconf/README.md) |
 
+## Dynamic IP Mechanism For Remote Service Admin
+
+In order to make remote services work without configuring the IP of the RSA, we have designed the following dynamic IP mechanism.
+
+  - The remote service admin service adds the property "celix.rsa.dynamic.ip.support". If RSA sets this property to true, the RSA will support dynamic IP address.
+  - If the RSA supports dynamic IP addresses, it should bind the network service address to any address(0.0.0.0/::), and set the property "celix.rsa.port" (which indicates the network port number of the remote service) for the exported remote service endpoint.
+  - The endpoint listener service of discovery adds the property "celix.rsa.discovery.interface.specific.endpoints.support". If this property is set to true, it means that the discovery support dynamic IP address filling.
+  - Add the configuration property "CELIX_RSA_INTERFACES_OF_PORT_<port>", which indicates which network interfaces is used to expose the specified port service.
+  - When the topology manager exports remote services, it should detect whether the "celix.rsa.dynamic.ip.support" property of the remote service admin service is true. If so, the topology manager should create multiple endpoints that support dynamic IP address for a single export registration base on CELIX_RSA_INTERFACES_OF_PORT_<port>. These endpoints are then forwarded to the discovery endpoint listener services that support dynamic IP address filling.
+  - The endpoint that supports dynamic IP address adds the property "celix.rsa.ifname", which indicates which network interface is used for exported endpoint exposure. This property is set by the topology manager based on CELIX_RSA_INTERFACES_OF_PORT_<port>.
+  - The endpoint that supports dynamic IP address adds the property "celix.rsa.ip.addresses", which indicates the list of IP addresses corresponding to the endpoint. When the topology manager creates the endpoint description that supports dynamic IP address, the value of this property should be set to null, and the discovery that support dynamic IP address filling will replace the value(Discovery will decide whether to fill in the dynamic IP addresses based on whether the "celix.rsa.ip.addresses" key exists or not).
+
+The sequence diagram of the dynamic IP mechanism is as follows:
+![dynamic_ip_filling](diagrams/dynamic_ip_filling_seq.png)
+
+  The example of dynamic IP mechanism see `remote-services-zeroconf-server` and `remote-services-zeroconf-client`.
 
 ## Usage
 

bundles/remote_services/diagrams/dynamic_ip_filling_seq.puml

@@ -0,0 +1,43 @@
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+@startuml
+'https://plantuml.com/sequence-diagram
+
+Box "Framework A"
+participant "RSA" as RSA_A
+participant "TopologyManager" as TM_A
+participant "Discovery" as Discovery_A
+end Box
+
+Box "Framework B"
+participant "Discovery" as Discovery_B
+participant "TopologyManager" as TM_B
+participant "RSA" as RSA_B
+end Box
+
+TM_A -> RSA_A: exportService()
+note over RSA_A: Exported service endpoint description e.g.:\n{\ncelix.rsa.port: 80"(set by RSA),\n...\n}"
+TM_A -> TM_A: Create endpoint descriptions\n that support dynamic ip
+note over TM_A: Dynamic ip endpoint description e.g.:\n{\ncelix.rsa.ifname: "eth0"(set by TopologyManager),\ncelix.rsa.port: 80",\ncelix.rsa.ip.addresses:""(set by TopologyManager),\n...\n}
+TM_A -> Discovery_A: endpointAdded()
+
+Discovery_A -> Discovery_B: Announce endpoint \nto other frameworks
+
+Discovery_B -> Discovery_B: Watch remote endpoints \nand fill in dynamic ip
+Discovery_B -> TM_B: endpointAdded()
+note over TM_B: Dynamic ip endpoint description e.g.:\n{\ncelix.rsa.port: 80",\ncelix.rsa.ip.addresses:"192.168...1.1, 192.168...1.2"(replaced by Discovery),\n...\n}"
+TM_B -> RSA_B: importService()
+@enduml

bundles/remote_services/discovery_zeroconf/README.md

@@ -25,14 +25,14 @@ The `Discovery_zeroconf` is implemented based on [Bonjour](https://github.com/ap
 
 The mapping between celix and mdns services is as follows:
 
-| **mDNS service** | **celix service**                                                                                                            |
-|------------------|------------------------------------------------------------------------------------------------------------------------------|
-| instance name    | service name+pid(process id)                                                                                                 |
-| service type     | "${last word of service configuration type}._sub._celix-rpc._udp"                                                            |
-| domain name      | "local"                                                                                                                      |
-| txt record       | service properties                                                                                                           |
-| host             | hostname.                                                                                                                    |
-| port             | The property value of "${service configuration type}.port". If it is not network server, it will be set a dummy value(65535) |
+| **mDNS service** | **celix service**             |
+|------------------|-------------------------------|
+| instance name    | service name+pid(process id)  |
+| service type     | "${last word of service configuration type}._sub._celix-rpc._udp"|
+| domain name      | "local"                       |
+| txt record       | service properties            |
+| host             | hostname of OS(It can be got by gethostname function).|
+| port             | The property value of "celix.rsa.port". It is set by RSA. If it is not network server, Discovery will set a dummy value(65535) to mDNS daemon.|
 
 
 The domain name value is set to "local" , because for remote discovery the mDNS query will only use link-local multicast.

bundles/remote_services/remote_service_admin_dfi/README.md

@@ -39,6 +39,7 @@ Libffi is configured using descriptor files in the bundles.
                                     Default is false
     CELIX_RSA_BIND_ON_ALL_INTERFACES    If set to true the RSA will bind to all interfaces. Default is true.
 
+    CELIX_RSA_DFI_DYNAMIC_IP_SUPPORT    If set to true the RSA will support dynamic IP address fill-in for service exports. Default is false.
 
 ###### CMake option
     RSA_REMOTE_SERVICE_ADMIN_DFI=ON

libs/dfi/README.md

@@ -236,13 +236,15 @@ The data types supported by the interface description include:
   ~~~
   In order to represent the properties of function parameters (eg: in, out...), function parameters support the following metadata annotations:
 
-  |Meta-info|Description|
-  |---------|-----------|
-  |am=handle| void pointer for the handle|
-  |am=pre   | output pointer with memory pre-allocated|
-  |am=out   | output pointer, the caller should use `free` to release the memory|
+  |Meta-info| Description|
+  |---------|------------|
+  |am=handle| void pointer for the handle.|
+  |am=pre   | output pointer with memory pre-allocated, it should be pointer to [trivially copyable type](#notion-definitions).|
+  |am=out   | output pointer, the caller should use `free` to release the memory, and it should be pointer to text(t) or double pointer to [serializable types](#notion-definitions).|
   |const=true| text argument(t) can use it, Normally a text argument will be handled as char*, meaning that the callee is expected to take of ownership.If a const=true annotation is used the text argument will be handled as a const char*, meaning that the caller keeps ownership of the string.|
 
+  If there is no metadata annotation, the default is standard argument(input parameter). And it can be any serializable type.
+
   *Example*:
   ~~~
   add(#am=handle;PDD#am=pre;*D)N
@@ -251,9 +253,16 @@ The data types supported by the interface description include:
   ~~~
   int add(void* handle,double a, double b, double *ret);
   ~~~
-  > **Notes**:
-  > - For RPC interface, the return type of methods must be N, because remote service calls usually return error codes.
-  > - Currently, the method only supports one output parameter, so the method cannot be defined in a multi-output parameter form.
+
+##### Notion Definitions
+
+- **trivially copyable type**: A trivially copyable type is a type that can be copied with a simple memcpy without the usual danger of shallow copying.
+- **serializable type**: All types except types involving untyped pointer or double pointer (pointer to pointer) are serializable. For example, complex types consisting of non-pointer fields are serializable while complex type containing a untyped pointer field is not serializable; [I is serializable while [P and [**D are not serializable.
+
+##### RSA Interface Convention Enforcement:
+  - For RSA interface, the return type of methods must be N, because remote service calls usually return error codes.
+  - The first parameter of a method must be `handle`, and`am=handle` can appear exactly once.
+  - If exists, output parameter (either `am=pre` or `am=out`) is only allowed as the last one. Therefore, there is at most one output parameter.
 
 #### Interface Description File