[API-NEXT,PATCHv2,16/16] doc: updating docs for the shm interface extension

Message ID 1476791808-29363-17-git-send-email-christophe.milard@linaro.org
State New
Headers show

Commit Message

Christophe Milard Oct. 18, 2016, 11:56 a.m.
Signed-off-by: Christophe Milard <christophe.milard@linaro.org>

---
 doc/users-guide/users-guide.adoc | 58 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

-- 
2.7.4

Comments

Bill Fischofer Oct. 19, 2016, 3:20 a.m. | #1
On Tue, Oct 18, 2016 at 6:56 AM, Christophe Milard <
christophe.milard@linaro.org> wrote:

> Signed-off-by: Christophe Milard <christophe.milard@linaro.org>

> ---

>  doc/users-guide/users-guide.adoc | 58 ++++++++++++++++++++++++++++++

> +++++++++-

>  1 file changed, 57 insertions(+), 1 deletion(-)

>

> diff --git a/doc/users-guide/users-guide.adoc

> b/doc/users-guide/users-guide.adoc

> index 62f5833..60364cb 100755

> --- a/doc/users-guide/users-guide.adoc

> +++ b/doc/users-guide/users-guide.adoc

> @@ -649,13 +649,19 @@ mapping the shared memory block. There is no

> fragmentation.

>  By default ODP threads are assumed to behave as cache coherent systems:

>  Any change performed on a shared memory block is guaranteed to eventually

>  become visible to other ODP threads sharing this memory block.

> -(this behaviour may be altered by flags to `odp_shm_reserve()` in the

> future).

>  Nevertheless, there is no implicit memory barrier associated with any

> action

>  on shared memories: *When* a change performed by an ODP thread becomes

> visible

>  to another ODP thread is not known: An application using shared memory

>  blocks has to use some memory barrier provided by ODP to guarantee shared

> data

>  validity between ODP threads.

>

> +The virtual address at which a given memory block is mapped in different

> ODP

> +threads may differ from ODP thread to ODP thread, if ODP threads have

> separate

> +virtual spaces (for instance if ODP threads are implemented as processes).

> +However, the ODP_SHM_SINGLE_VA flag can be used at `odp_shm_reserve()`

> time

> +to guarantee address uniqueness in all ODP threads, regardless of their

> +implementation or creation time.

> +

>  === Lookup by name

>  As mentioned, shared memory handles can be sent from ODP threads to ODP

>  threads using any IPC mechanism, and then the block address retrieved.

> @@ -698,6 +704,46 @@ if (odp_shm_free(shm) != 0) {

>  }

>  ----

>

> +=== sharing memory with the external world

> +ODP provides ways of sharing memory with entities located outside

> +ODP instances:

> +

> +Sharing a block of memory with an external (non ODP) thread is achieved

> +by setting the ODP_SHM_PROC flag at `odp_shm_reserve()` time.

> +How the memory block is retrieved on the Operating System side is

> +implementation and Operating System dependent.

> +

> +Sharing a block of memory with an external ODP instance (running

> +on the same Operating System) is achieved

> +by setting the ODP_SHM_EXPORT flag at `odp_shm_reserve()` time.

> +A block of memory created with this flag in an ODP instance A, can be

> "mapped"

> +into a remote ODP instance B (on the same OS) by using the

> +`odp_shm_reserve_exported()`, on ODP instance B:

> +

> +.sharing memory between ODP instances: instance A

> +[source,c]

> +----

> +odp_shm_t shmA;

> +shmA = odp_shm_reserve("memoryA", size, 0, ODP_SHM_EXPORT);

> +----

> +

> +.sharing memory between ODP instances: instance B

> +[source,c]

> +----

> +odp_shm_t shmB;

> +odp_instance_t odpA;

> +

> +/* get ODP A instance handle by some OS method */

> +odpA = ...

> +

> +/* get the shared memory exported by A:

> +shmB = odp_shm_reserve_exported("memoryA", odpA, "memoryB", 0, 0);

> +----

> +

> +Note that the handles shmA and shmB are scoped by each ODP instance

> +(you can not use them outside the ODP instance they belong to).

> +Also note that both ODP instances have to call `odp_shm_free()` when done.

> +

>  === Memory creation flags

>  The last argument to odp_shm_reserve() is a set of ORed flags.

>  Two flags are supported:

>


Three flags


> @@ -719,6 +765,16 @@ implementation), except for `odp_shm_lookup()` and

> `odp_shm_free()`.

>  ODP implementations may use this flag as a hint for performance

> optimization,

>  or may as well ignore this flag.

>

> +==== ODP_SHM_SINGLE_VA

> +This flag is used to guarantee the uniqueness of the address at which

> +the shared memory is mapped: without this flag, a given memory block may

> be

> +mapped at different virtual addresses (assuming the target have virtual

> +addresses) by different ODP threads. This means that the value returned by

> +`odp_shm_addr()` would be different in different threads, in this case.

> +Setting this flag guarantees that all ODP threads sharing this memory

> +block will see it at the same address (`odp_shm_addr()` would return the

> +same value on all ODP threads, for a given memory block, in this case)

> +

>


Are their any performance or other impacts to consider in choosing whether
or not to set this flag? If so they should be mentioned here.


>  == Queues

>  Queues are the fundamental event sequencing mechanism provided by ODP and

> all

>  ODP applications make use of them either explicitly or implicitly. Queues

> are

> --

> 2.7.4

>

>

Patch

diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc
index 62f5833..60364cb 100755
--- a/doc/users-guide/users-guide.adoc
+++ b/doc/users-guide/users-guide.adoc
@@ -649,13 +649,19 @@  mapping the shared memory block. There is no fragmentation.
 By default ODP threads are assumed to behave as cache coherent systems:
 Any change performed on a shared memory block is guaranteed to eventually
 become visible to other ODP threads sharing this memory block.
-(this behaviour may be altered by flags to `odp_shm_reserve()` in the future).
 Nevertheless, there is no implicit memory barrier associated with any action
 on shared memories: *When* a change performed by an ODP thread becomes visible
 to another ODP thread is not known: An application using shared memory
 blocks has to use some memory barrier provided by ODP to guarantee shared data
 validity between ODP threads.
 
+The virtual address at which a given memory block is mapped in different ODP
+threads may differ from ODP thread to ODP thread, if ODP threads have separate
+virtual spaces (for instance if ODP threads are implemented as processes).
+However, the ODP_SHM_SINGLE_VA flag can be used at `odp_shm_reserve()` time
+to guarantee address uniqueness in all ODP threads, regardless of their
+implementation or creation time.
+
 === Lookup by name
 As mentioned, shared memory handles can be sent from ODP threads to ODP
 threads using any IPC mechanism, and then the block address retrieved.
@@ -698,6 +704,46 @@  if (odp_shm_free(shm) != 0) {
 }
 ----
 
+=== sharing memory with the external world
+ODP provides ways of sharing memory with entities located outside
+ODP instances:
+
+Sharing a block of memory with an external (non ODP) thread is achieved
+by setting the ODP_SHM_PROC flag at `odp_shm_reserve()` time.
+How the memory block is retrieved on the Operating System side is
+implementation and Operating System dependent.
+
+Sharing a block of memory with an external ODP instance (running
+on the same Operating System) is achieved
+by setting the ODP_SHM_EXPORT flag at `odp_shm_reserve()` time.
+A block of memory created with this flag in an ODP instance A, can be "mapped"
+into a remote ODP instance B (on the same OS) by using the
+`odp_shm_reserve_exported()`, on ODP instance B:
+
+.sharing memory between ODP instances: instance A
+[source,c]
+----
+odp_shm_t shmA;
+shmA = odp_shm_reserve("memoryA", size, 0, ODP_SHM_EXPORT);
+----
+
+.sharing memory between ODP instances: instance B
+[source,c]
+----
+odp_shm_t shmB;
+odp_instance_t odpA;
+
+/* get ODP A instance handle by some OS method */
+odpA = ...
+
+/* get the shared memory exported by A:
+shmB = odp_shm_reserve_exported("memoryA", odpA, "memoryB", 0, 0);
+----
+
+Note that the handles shmA and shmB are scoped by each ODP instance
+(you can not use them outside the ODP instance they belong to).
+Also note that both ODP instances have to call `odp_shm_free()` when done.
+
 === Memory creation flags
 The last argument to odp_shm_reserve() is a set of ORed flags.
 Two flags are supported:
@@ -719,6 +765,16 @@  implementation), except for `odp_shm_lookup()` and `odp_shm_free()`.
 ODP implementations may use this flag as a hint for performance optimization,
 or may as well ignore this flag.
 
+==== ODP_SHM_SINGLE_VA
+This flag is used to guarantee the uniqueness of the address at which
+the shared memory is mapped: without this flag, a given memory block may be
+mapped at different virtual addresses (assuming the target have virtual
+addresses) by different ODP threads. This means that the value returned by
+`odp_shm_addr()` would be different in different threads, in this case.
+Setting this flag guarantees that all ODP threads sharing this memory
+block will see it at the same address (`odp_shm_addr()` would return the
+same value on all ODP threads, for a given memory block, in this case)
+
 == Queues
 Queues are the fundamental event sequencing mechanism provided by ODP and all
 ODP applications make use of them either explicitly or implicitly. Queues are