app/testpmd: merge ports list update functions

[dpdk.git] / doc / guides / prog_guide / multi_proc_support.rst

diff --git a/doc/guides/prog_guide/multi_proc_support.rst b/doc/guides/prog_guide/multi_proc_support.rst
index 371d028..1384fe3 100644 (file)
--- a/doc/guides/prog_guide/multi_proc_support.rst
+++ b/doc/guides/prog_guide/multi_proc_support.rst
@@ -63,6 +63,10 @@ and point to the same objects, in both processes.
     Refer to `Multi-process Limitations`_ for details of
     how Linux kernel Address-Space Layout Randomization (ASLR) can affect memory sharing.
 
     Refer to `Multi-process Limitations`_ for details of
     how Linux kernel Address-Space Layout Randomization (ASLR) can affect memory sharing.
 

+    If the primary process was run with ``--legacy-mem`` or
+    ``--single-file-segments`` switch, secondary processes must be run with the
+    same switch specified. Otherwise, memory corruption may occur.
+

 .. _figure_multi_process_memory:
 
 .. figure:: img/multi_process_memory.*
 .. _figure_multi_process_memory:
 
 .. figure:: img/multi_process_memory.*


@@ -116,8 +120,13 @@ The rte part of the filenames of each of the above is configurable using the fil
 
 In addition to specifying the file-prefix parameter,
 any DPDK applications that are to be run side-by-side must explicitly limit their memory use.
 
 In addition to specifying the file-prefix parameter,
 any DPDK applications that are to be run side-by-side must explicitly limit their memory use.

-This is done by passing the -m flag to each process to specify how much hugepage memory, in megabytes,
-each process can use (or passing ``--socket-mem`` to specify how much hugepage memory on each socket each process can use).
+This is less of a problem on Linux, as by default, applications will not
+allocate more memory than they need. However if ``--legacy-mem`` is used, DPDK
+will attempt to preallocate all memory it can get to, and memory use must be
+explicitly limited. This is done by passing the ``-m`` flag to each process to
+specify how much hugepage memory, in megabytes, each process can use (or passing
+``--socket-mem`` to specify how much hugepage memory on each socket each process
+can use).

 
 .. note::
 
 
 .. note::
 


@@ -144,8 +153,10 @@ There are a number of limitations to what can be done when running DPDK multi-pr
 Some of these are documented below:
 
 *   The multi-process feature requires that the exact same hugepage memory mappings be present in all applications.
 Some of these are documented below:
 
 *   The multi-process feature requires that the exact same hugepage memory mappings be present in all applications.

-    The Linux security feature - Address-Space Layout Randomization (ASLR) can interfere with this mapping,
-    so it may be necessary to disable this feature in order to reliably run multi-process applications.
+    This makes secondary process startup process generally unreliable. Disabling
+    Linux security feature - Address-Space Layout Randomization (ASLR) may
+    help getting more consistent mappings, but not necessarily more reliable -
+    if the mappings are wrong, they will be consistently wrong!

 
 .. warning::
 
 
 .. warning::
 


@@ -209,8 +220,8 @@ way communication mechanism, with the requester expecting a response from the
 other side.
 
 Both messages and requests will trigger a named callback on the receiver side.
 other side.
 
 Both messages and requests will trigger a named callback on the receiver side.

-These callbacks will be called from within a dedicated IPC thread that is not
-part of EAL lcore threads.
+These callbacks will be called from within a dedicated IPC or interrupt thread
+that are not part of EAL lcore threads.

 
 Registering for incoming messages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Registering for incoming messages
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


@@ -269,6 +280,13 @@ For asynchronous requests, a function pointer to the callback function must be
 provided instead. This callback will be called when the request either has timed
 out, or will have received a response to all the messages that were sent.
 
 provided instead. This callback will be called when the request either has timed
 out, or will have received a response to all the messages that were sent.
 

+.. warning::
+
+    When an asynchronous request times out, the callback will be called not by
+    a dedicated IPC thread, but rather from EAL interrupt thread. Because of
+    this, it may not be possible for DPDK to trigger another interrupt-based
+    event (such as an alarm) while handling asynchronous IPC callback.
+

 When the callback is called, the original request descriptor will be provided
 (so that it would be possible to determine for which sent message this is a
 callback to), along with a response descriptor like the one described above.
 When the callback is called, the original request descriptor will be provided
 (so that it would be possible to determine for which sent message this is a
 callback to), along with a response descriptor like the one described above.


@@ -300,6 +318,12 @@ supported. However, since sending messages (not requests) does not involve an
 IPC thread, sending messages while processing another message or request is
 supported.
 
 IPC thread, sending messages while processing another message or request is
 supported.
 

+Asynchronous request callbacks may be triggered either from IPC thread or from
+interrupt thread, depending on whether the request has timed out. It is
+therefore suggested to avoid waiting for interrupt-based events (such as alarms)
+inside asynchronous IPC request callbacks. This limitation does not apply to
+messages or synchronous requests.
+

 If callbacks spend a long time processing the incoming requests, the requestor
 might time out, so setting the right timeout value on the requestor side is
 imperative.
 If callbacks spend a long time processing the incoming requests, the requestor
 might time out, so setting the right timeout value on the requestor side is
 imperative.