Skip to contentSkip to conversation

examples: add pthread-shim in performance-thread sample app

PATCH New ibetts 1 participant 1 message Dec 2, 2015 1 message not in the archive

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): [email protected]

ibetts

author
#1 lore raw

PATCH v4 2/2 examples: add pthread-shim in performance-thread sample app

From: Ian Betts <[email protected]>

This commit adds a simple pthread_shim example for the cooperative scheduler included with this patchset.

The shim demonstrates a way in which legacy code writtem for pthreads could be adapted to lighweight threads.

---
 doc/guides/sample_app_ug/performance_thread.rst    | 114 ++++
 examples/performance-thread/Makefile               |   2 +
 examples/performance-thread/pthread_shim/Makefile  |  60 ++
 examples/performance-thread/pthread_shim/main.c    | 284 ++++++++
 .../performance-thread/pthread_shim/pthread_shim.c | 714 +++++++++++++++++++++
 .../performance-thread/pthread_shim/pthread_shim.h | 113 ++++
 6 files changed, 1287 insertions(+)
 create mode 100644 examples/performance-thread/pthread_shim/Makefile
 create mode 100644 examples/performance-thread/pthread_shim/main.c
 create mode 100644 examples/performance-thread/pthread_shim/pthread_shim.c
 create mode 100644 examples/performance-thread/pthread_shim/pthread_shim.h
doc/guides/sample_app_ug/performance_thread.rst +114 -0
index 6ea83cc..d71bb84 100644
@@ -1102,6 +1102,120 @@ it the local data it needs, and pick up the new logical core specific values
 from pthread local storage at its new home.
 
 
+.. _pthread_shim:
+
+Pthread shim
+~~~~~~~~~~~~
+
+A convenient way to get something working with legacy code can be to use a
+shim that adapts pthread API calls to the corresponding L-thread ones.
+This approach will not mitigate any of the porting considerations mentioned
+in the previous sections, but it will reduce the amount of code churn that
+would otherwise been involved. It is a reasonable approach to evaluate
+L-threads, before investing effort in porting to the native L-thread APIs.
+
+
+Overview
+^^^^^^^^
+The L-thread subsystem includes an example pthread shim. This is a partial
+implementation but does contain the API stubs needed to get basic applications
+running. There is a simple "hello world" application that demonstrates the
+use of the pthread shim.
+
+A subtlety of working with a shim is that the application will still need
+to make use of the genuine pthread library functions, at the very least in
+order to create the EAL threads in which the L-thread schedulers will run.
+This is the case with DPDK initialization, and exit.
+
+To deal with the initialization and shutdown scenarios, the shim is capable of
+switching on or off its adaptor functionality, an application can control this
+behavior by the calling the function ``pt_override_set()``. The default state
+is disabled.
+
+The pthread shim uses the dynamic linker loader and saves the loaded addresses
+of the genuine pthread API functions in an internal table, when the shim
+functionality is enabled it performs the adaptor function, when disabled it
+invokes the genuine pthread function.
+
+The function ``pthread_exit()`` has additional special handling. The standard
+system header file pthread.h declares ``pthread_exit()`` with
+``__attribute__((noreturn))`` this is an optimization that is possible because
+the pthread is terminating and this enables the compiler to omit the normal
+handling of stack and protection of registers since the function is not
+expected to return, and in fact the thread is being destroyed. These
+optimizations are applied in both the callee and the caller of the
+``pthread_exit()`` function.
+
+In our cooperative scheduling environment this behavior is inadmissible. The
+pthread is the L-thread scheduler thread, and, although an L-thread is
+terminating, there must be a return to the scheduler in order that the system
+can continue to run. Further, returning from a function with attribute
+``noreturn`` is invalid and may result in undefined behavior.
+
+The solution is to redefine the ``pthread_exit`` function with a macro,
+causing it to be mapped to a stub function in the shim that does not have the
+``noreturn`` attribute. This macro is defined in the file
+``pthread_shim.h``. The stub function is otherwise no different than any of
+the other stub functions in the shim, and will switch between the real
+``pthread_exit()`` function or the ``lthread_exit()`` function as
+required. The only difference is that the mapping to the stub by macro
+substitution.
+
+A consequence of this is that the file ``pthread_shim.h`` must be included in
+legacy code wishing to make use of the shim. It also means that dynamic
+linkage of a pre-compiled binary that did not include pthread_shim.h is not be
+supported.
+
+Given the requirements for porting legacy code outlined in
+:ref:`porting_legacy_code_to_run_on_lthreads` most applications will require at
+least some minimal adjustment and recompilation to run on L-threads so
+pre-compiled binaries are unlikely to be met in practice.
+
+In summary the shim approach adds some overhead but can be a useful tool to help
+establish the feasibility of a code reuse project. It is also a fairly
+straightforward task to extend the shim if necessary.
+
+**Note:** Bearing in mind the preceding discussions about the impact of making
+blocking calls then switching the shim in and out on the fly to invoke any
+pthread API this might block is something that should typically be avoided.
+
+
+Building and running the pthread shim
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The shim example application is located in the sample application
+in the performance-thread folder
+
+To build and run the pthread shim example
+
+#. Go to the example applications folder
+
+   .. code-block:: console
+
+       export RTE_SDK=/path/to/rte_sdk
+       cd ${RTE_SDK}/examples/performance-thread/pthread_shim
+
+
+#. Set the target (a default target is used if not specified). For example:
+
+   .. code-block:: console
+
+       export RTE_TARGET=x86_64-native-linuxapp-gcc
+
+   See the DPDK Getting Started Guide for possible RTE_TARGET values.
+
+#. Build the application:
+
+   .. code-block:: console
+
+       make
+
+#. To run the pthread_shim example
+
+   .. code-block:: console
+
+       lthread-pthread-shim -c core_mask -n number_of_channels
+
 .. _lthread_diagnostics:
 
 L-thread Diagnostics
examples/performance-thread/Makefile +2 -0
index fce4f79..1be67e9 100644
@@ -39,6 +39,8 @@ RTE_TARGET ?= x86_64-native-linuxapp-gcc
 include $(RTE_SDK)/mk/rte.vars.mk
 
 DIRS-$(CONFIG_RTE_PERFORMANCE_THREAD) += l3fwd-thread
+DIRS-$(CONFIG_RTE_PERFORMANCE_THREAD) += pthread_shim
+
 
 
 
examples/performance-thread/pthread_shim/Makefile new file +60 -0

60 lines not on this page · raw message

examples/performance-thread/pthread_shim/main.c new file +284 -0

284 lines not on this page · raw message

examples/performance-thread/pthread_shim/pthread_shim.c new file +714 -0

714 lines not on this page · raw message

examples/performance-thread/pthread_shim/pthread_shim.h new file +113 -0

113 lines not on this page · raw message

Signature · 1 line
2.1.4