Document GDB Ext, Try to Fix Embedded GDB Ext

dds/DCPS/Definitions.h

@@ -87,6 +87,12 @@
 #  define OPENDDS_HAS_EXPLICIT_INTS 0
 #endif
 
+#if defined __GNUC__ && !defined __clang__
+#  define OPENDDS_GCC 1
+#else
+#  define OPENDDS_GCC 0
+#endif
+
 #if defined __GNUC__ && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 6) || defined __clang__)
 #  define OPENDDS_GCC_HAS_DIAG_PUSHPOP 1
 #else

dds/DCPS/Service_Participant.cpp

@@ -62,13 +62,13 @@
 extern char **environ;
 #endif
 
+#if OPENDDS_GCC
 // Embed GDB Extension
-#ifdef __GNUC__
 asm(
   ".pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n"
   ".byte 4\n" // 4 means this is an embedded Python script
   ".ascii \"gdb.inlined-script\\n\"\n"
-  ".incbin \"tools/scripts/gdbext.py\"\n"
+  ".incbin \"../tools/scripts/gdbext.py\"\n"
   ".byte 0\n"
   ".popsection\n"
 );

docs/design/security.md

@@ -3,7 +3,7 @@
 This document is intended as a collection of high-level notes on OpenDDS
 Security. OpenDDS Security provides security controls and capabilities for
 RTPS, which includes authentication of participants and encryption of messages.
-It an implementation of DDS Security Version 1.1 (OMG formal/2018-04-01).
+It is an implementation of DDS Security Version 1.1 (OMG formal/2018-04-01).
 
 ## Debug Logging
 
@@ -14,14 +14,14 @@ transitioned. Security debug messages are broken broken down into named
 categories which can be specified individually or activated on the same
 accumulative 1 to 10 scale as `DCPSDebugLevel`.
 
-See OpenDDS Developer's Guide Section 7.2 "Common Configuration Options" for
-the categories and usage, or `dds/DCPS/debug.h` and `dds/DCPS/debug.cpp` for
-the source.
+See https://opendds.readthedocs.io/en/master/devguide/run_time_configuration.html#security-debug-logging
+for the categories and usage, or `dds/DCPS/debug.h` and `dds/DCPS/debug.cpp`
+for the source.
 
 ## Authentication
 
 Authentication occurs after participants discover each other. It consists of a
-three-way handshake using the "builtin SDP participant" readers and writers.
+three-way handshake using the "builtin SPDP participant" readers and writers.
 
 - Request
   - Based on GUIDs, one side takes the lead and starts the handshake by sending
@@ -44,7 +44,7 @@ During key exchange all keys of secure entities will be exchanged using the
 "Builtin Participant Volatile Message Secure" topic. It can be thought of as a
 boot strap to the normal security.
 
-- Because they are special keys, "Volitile" keys all have the key id `00 00 00 00`.
+- Because they are special keys, "volatile" keys all have the key id `00 00 00 00`.
 
 - Each side should send at least 8 keys, one for each secure entity.
 

docs/internal/dev_guidelines.rst

@@ -53,17 +53,15 @@ Dependencies
 
   :doc:`/devguide/building/dependencies` for all dependencies and details on how these are used in OpenDDS.
 
-*********************
 Dependency Management
-*********************
+=====================
 
 ACE/TAO
-=======
+-------
 
 By default, the :ghfile:`configure` script and :ref:`CMake support<cmake-building>` use released versions of ACE/TAO.
 The same versions are used for pull requests.
-The versions are documented in :ghfile:`acetao.ini`.
-Currently, the :ghfile:`configure` scripts uses a release of ACE6 and CMake uses a release of ACE7.
+The versions are listed :ref:`here <deps-ace-tao>` and defined in :ghfile:`acetao.ini`.
 
 The versions are updated by the GitHub Actions workflow in :ghfile:`.github/workflows/update-ace-tao.yml` for micro/patch releases.
 When a new version of ACE/TAO is available, the workflow creates a pull request based on the new version.
@@ -78,7 +76,7 @@ If this is not a release, then the PR would be merged after the necessary ACE/TA
 Ideally, the GitHub Actions files would be extended with variables that allow the default versions to be changed easily and a lint script would be added to prevent unintended changes.
 
 TODO
-====
+----
 
 * MPC
 * Perl
@@ -88,6 +86,18 @@ TODO
 * GoogleTest
 * vcpkg
 
+.. _dev_guidelines-debugging:
+
+*********
+Debugging
+*********
+
+Here are a list of tools resources available to OpenDDS developers:
+
+- `Wireshark <https://objectcomputing.com/resources/publications/sett/october-2021-wireshark-and-opendds>`__ is a indispensable tool for debugging network applications.
+- There is a :ghfile:`GDB extension <tools/scripts/gdbext.py>` to make working with a OpenDDS program/core file easier: .
+- :ghfile:`Notes on debugging DDS security <tools/scripts/gdbext.py>`.
+
 .. _dev_guidelines-text_file_formating:
 
 ********************

tools/scripts/gdbext.py

@@ -7,17 +7,23 @@
 #   - Shortcuts to all participants, discoveries, SPDP and SEDP instances, user
 #     readers, and user writers
 #   - Helpers to make it easier to work with data structures in Python:
-#     value_is, std_*_values, deref, deref_holder.
+#     value_is, std_*_values, real_ptr, etc.
 #
 # To use:
+#   - The script is embedded within the Dcps library, but by default, GDB will
+#     have to be configured to load it for safety reasons. You will also have
+#     to run the `opendds` GDB command to complete initialization.
 #   - Run `gdb -x path/to/gdbext.py ...` for a new session
 #   - `source path/to/gdbext.py` for an existing session
-#   - You might run into this python exception comming from libstdcpp.py:
+#   - You might run into this python exception coming from libstdcpp.py:
 #       'NoneType' object has no attribute 'pointer'
 #     This is a GDB patch that might fix it:
 #       https://sourceware.org/pipermail/libstdc++/2020-December/051773.html
 #     However it can also be fixed by switching to a frame of a C++ function
 #     and sourcing the file again.
+#   - If the extension failed to fully initialize automatically because of
+#     libstdcpp or another problem, it can be initialized or reinitialized using
+#     the `opendds` GDB command.
 #
 # Tested with Ubuntu 22.04 (GDB 12.1, gcc 11.4, and libstdc++ 3.4.30)
 # This script might break with changes to either OpenDDS, GDB, or gcc/libstdc++