cpukit/libdl: Manual file header reordering (SPDX, Doxygen, Copyright)

Updates #3053.

35 files changed, 335 insertions, 300 deletions

diff --git a/cpukit/libdl/dlfcn-shell.c b/cpukit/libdl/dlfcn-shell.c
index 84a5d78e4a..6ea2501347 100644
--- a/cpukit/libdl/dlfcn-shell.c
+++ b/cpukit/libdl/dlfcn-shell.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor Dynamic Loading API Shell Support.
+ *
+ * Shell command wrappers for the Dynamic Loading API.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor Dynamic Loading API Shell Support.
- *
- * Shell command wrappers for the Dynamic Loading API.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/dlfcn.c b/cpukit/libdl/dlfcn.c
index 1eeb663b08..bc485f5b98 100644
--- a/cpukit/libdl/dlfcn.c
+++ b/cpukit/libdl/dlfcn.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtl
+ *
+ * @brief RTEMS POSIX Dynamic Module Loading Interface.
+ *
+ * This is the POSIX interface to run-time loading of code into RTEMS.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtl
- *
- * @brief RTEMS POSIX Dynamic Module Loading Interface.
- *
- * This is the POSIX interface to run-time loading of code into RTEMS.
- */
 
 #include <stdint.h>
 #include <dlfcn.h>
diff --git a/cpukit/libdl/rap-shell.c b/cpukit/libdl/rap-shell.c
index dcb5c2ad1e..48b9a246e7 100644
--- a/cpukit/libdl/rap-shell.c
+++ b/cpukit/libdl/rap-shell.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Application Loader.
+ *
+ * Shell command wrappers for the RTEMS Application loader.
+ */
+
 /*
  *  COPYRIGHT (c) 2013 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Application Loader.
- *
- * Shell command wrappers for the RTEMS Application loader.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rap.c b/cpukit/libdl/rap.c
index a11695f2ee..1a93721aec 100644
--- a/cpukit/libdl/rap.c
+++ b/cpukit/libdl/rap.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rap
+ *
+ * @brief RTEMS Application Loader
+ *
+ * This is the RAP implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rap
- *
- * @brief RTEMS Application Loader
- *
- * This is the RAP implementation.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-alloc-heap.c b/cpukit/libdl/rtl-alloc-heap.c
index d843f491b0..10150a0753 100644
--- a/cpukit/libdl/rtl-alloc-heap.c
+++ b/cpukit/libdl/rtl-alloc-heap.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Allocator for the standard heap.
+ */
+
 /*
  *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Allocator for the standard heap.
- */
 
 #include <stdlib.h>
 
diff --git a/cpukit/libdl/rtl-alloc-heap.h b/cpukit/libdl/rtl-alloc-heap.h
index b16778a467..e3990b9f70 100644
--- a/cpukit/libdl/rtl-alloc-heap.h
+++ b/cpukit/libdl/rtl-alloc-heap.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Allocator for the standard heap.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Allocator for the standard heap.
- */
 
 #if !defined (_RTEMS_RTL_ALLOC_HEAP_H_)
 #define _RTEMS_RTL_ALLOC_HEAP_H_
diff --git a/cpukit/libdl/rtl-allocator.c b/cpukit/libdl/rtl-allocator.c
index 7c6f972c02..f09690d71a 100644
--- a/cpukit/libdl/rtl-allocator.c
+++ b/cpukit/libdl/rtl-allocator.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Allocator
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Allocator
- */
 
 #include <stdio.h>
 #include <string.h>
diff --git a/cpukit/libdl/rtl-archive.c b/cpukit/libdl/rtl-archive.c
index 17cb5f6e16..f916336f7c 100644
--- a/cpukit/libdl/rtl-archive.c
+++ b/cpukit/libdl/rtl-archive.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtl
+ *
+ * @brief RTEMS Run-Time Linker Archive
+ */
+
 /*
  *  COPYRIGHT (c) 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtl
- *
- * @brief RTEMS Run-Time Linker Archive
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-bit-alloc.c b/cpukit/libdl/rtl-bit-alloc.c
index 4570a6d0f8..7014dc8b62 100644
--- a/cpukit/libdl/rtl-bit-alloc.c
+++ b/cpukit/libdl/rtl-bit-alloc.c
@@ -1,5 +1,17 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor Bit Allocator
+ *
+ * A configurable allocator for small peices of memory where embedding
+ * control blocks into the memory are not viable. The amount of memory
+ * should be small and the minimum allocator a 32bit work or higher.
+ */
+
 /*
  *  COPYRIGHT (c) 2019 Chris Johns <chrisj@rtems.org>
  *
@@ -24,17 +36,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor Bit Allocator
- *
- * A configurable allocator for small peices of memory where embedding
- * control blocks into the memory are not viable. The amount of memory
- * should be small and the minimum allocator a 32bit work or higher.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-bit-alloc.h b/cpukit/libdl/rtl-bit-alloc.h
index a4c264544d..9b4e6c31fb 100644
--- a/cpukit/libdl/rtl-bit-alloc.h
+++ b/cpukit/libdl/rtl-bit-alloc.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Bit Allocator Header
+ */
+
 /*
  *  COPYRIGHT (c) 2019 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Bit Allocator Header
- */
 
 #if !defined (_RTEMS_RTL_BIT_ALLOC_H_)
 #define _RTEMS_RTL_BIT_ALLOC_H_
diff --git a/cpukit/libdl/rtl-chain-iterator.c b/cpukit/libdl/rtl-chain-iterator.c
index 2591e26567..edc8f9ad5b 100644
--- a/cpukit/libdl/rtl-chain-iterator.c
+++ b/cpukit/libdl/rtl-chain-iterator.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor Chain Iterator
+ *
+ * A means of executing an iterator on a chain.
+ */
+
 /*
  *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor Chain Iterator
- *
- * A means of executing an iterator on a chain.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-chain-iterator.h b/cpukit/libdl/rtl-chain-iterator.h
index 860df0960b..8304fe1a24 100644
--- a/cpukit/libdl/rtl-chain-iterator.h
+++ b/cpukit/libdl/rtl-chain-iterator.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Chain Iterator.
+ */
+
 /*
  *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Chain Iterator.
- */
 
 #if !defined (_RTEMS_RTL_CHAIN_ITERATOR_H_)
 #define _RTEMS_RTL_CHAIN_ITERATOR_H_
diff --git a/cpukit/libdl/rtl-debugger.c b/cpukit/libdl/rtl-debugger.c
index 65e9db8a5b..3c25605f5e 100644
--- a/cpukit/libdl/rtl-debugger.c
+++ b/cpukit/libdl/rtl-debugger.c
@@ -1,5 +1,22 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtl
+ *
+ * @brief RTEMS Module Loading Debugger Interface.
+ *
+ * Inspection of run-time linkers in NetBSD and Android show a common type of
+ * structure that is used to interface to GDB. The NetBSD definition of this
+ * interface is being used and is defined in <link.h>. It defines a protocol
+ * that is used by GDB to inspect the state of dynamic libraries. I have not
+ * checked GDB code at when writing this comment but I suspect GDB sets a break
+ * point on the r_brk field of _rtld_debug and it has code that detects this
+ * break point being hit. When this happens it reads the state and performs the
+ * operation based on the r_state field.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,22 +41,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtl
- *
- * @brief RTEMS Module Loading Debugger Interface.
- *
- * Inspection of run-time linkers in NetBSD and Android show a common type of
- * structure that is used to interface to GDB. The NetBSD definition of this
- * interface is being used and is defined in <link.h>. It defines a protocol
- * that is used by GDB to inspect the state of dynamic libraries. I have not
- * checked GDB code at when writing this comment but I suspect GDB sets a break
- * point on the r_brk field of _rtld_debug and it has code that detects this
- * break point being hit. When this happens it reads the state and performs the
- * operation based on the r_state field.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-elf.c b/cpukit/libdl/rtl-elf.c
index 4a8f1cb752..37d9f4575e 100644
--- a/cpukit/libdl/rtl-elf.c
+++ b/cpukit/libdl/rtl-elf.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor
+ *
+ * This is the RTL implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2019 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor
- *
- * This is the RTL implementation.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-elf.h b/cpukit/libdl/rtl-elf.h
index 8c14f16181..c7c17c525a 100644
--- a/cpukit/libdl/rtl-elf.h
+++ b/cpukit/libdl/rtl-elf.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker ELF Headers
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker ELF Headers
- */
 
 #if !defined (_RTEMS_RTL_ELF_H_)
 #define _RTEMS_RTL_ELF_H_
diff --git a/cpukit/libdl/rtl-error.c b/cpukit/libdl/rtl-error.c
index 6132c376be..b3234031d7 100644
--- a/cpukit/libdl/rtl-error.c
+++ b/cpukit/libdl/rtl-error.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtl
+ *
+ * @brief RTEMS Run-Time Linker Error
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtl
- *
- * @brief RTEMS Run-Time Linker Error
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-error.h b/cpukit/libdl/rtl-error.h
index 7c04ac97e7..38268c3bae 100644
--- a/cpukit/libdl/rtl-error.h
+++ b/cpukit/libdl/rtl-error.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Error
+ */
+
 /*
  *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Error
- */
 
 #if !defined (_RTEMS_RTL_ERROR_H_)
 #define _RTEMS_RTL_ERROR_H_
diff --git a/cpukit/libdl/rtl-find-file.c b/cpukit/libdl/rtl-find-file.c
index 23c7bc6024..7821355fd9 100644
--- a/cpukit/libdl/rtl-find-file.c
+++ b/cpukit/libdl/rtl-find-file.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtl
+ *
+ * @brief RTEMS Run-Time Linker Error
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2013 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtl
- *
- * @brief RTEMS Run-Time Linker Error
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-find-file.h b/cpukit/libdl/rtl-find-file.h
index 52a1843a42..b4cd9f6c84 100644
--- a/cpukit/libdl/rtl-find-file.h
+++ b/cpukit/libdl/rtl-find-file.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Object Support.
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2013 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Object Support.
- */
 
 #if !defined (_RTEMS_RTL_FIND_FILE_H_)
 #define _RTEMS_RTL_FIND_FILE_H_
diff --git a/cpukit/libdl/rtl-obj-cache.c b/cpukit/libdl/rtl-obj-cache.c
index bceca37c58..837fd330eb 100644
--- a/cpukit/libdl/rtl-obj-cache.c
+++ b/cpukit/libdl/rtl-obj-cache.c
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Object File cache buffers a section of the
+ *        object file in a buffer to localise read performance.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,14 +33,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Object File cache buffers a section of the
- *        object file in a buffer to localise read performance.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-obj-comp.c b/cpukit/libdl/rtl-obj-comp.c
index bc333424ce..ea408527b7 100644
--- a/cpukit/libdl/rtl-obj-comp.c
+++ b/cpukit/libdl/rtl-obj-comp.c
@@ -1,5 +1,14 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Object Compression manages a compress
+ *        stream of data.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,14 +33,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Object Compression manages a compress
- *        stream of data.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-obj.c b/cpukit/libdl/rtl-obj.c
index 6957100485..24d1e09048 100644
--- a/cpukit/libdl/rtl-obj.c
+++ b/cpukit/libdl/rtl-obj.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtl
+ *
+ * @brief RTEMS Run-Time Linker Error
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtl
- *
- * @brief RTEMS Run-Time Linker Error
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-rap.c b/cpukit/libdl/rtl-rap.c
index 7eaa213218..64ee2947a3 100644
--- a/cpukit/libdl/rtl-rap.c
+++ b/cpukit/libdl/rtl-rap.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor
+ *
+ * This is the RAP format loader support..
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2013, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor
- *
- * This is the RAP format loader support..
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-rap.h b/cpukit/libdl/rtl-rap.h
index 8ded95758f..49d83a872f 100644
--- a/cpukit/libdl/rtl-rap.h
+++ b/cpukit/libdl/rtl-rap.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker ELF Headers
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker ELF Headers
- */
 
 #if !defined (_RTEMS_RTL_RAP_H_)
 #define _RTEMS_RTL_RAP_H_
diff --git a/cpukit/libdl/rtl-shell.c b/cpukit/libdl/rtl-shell.c
index a58384f22f..732f66131e 100644
--- a/cpukit/libdl/rtl-shell.c
+++ b/cpukit/libdl/rtl-shell.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor Shell Commands
+ *
+ * A simple RTL command to aid using the RTL.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor Shell Commands
- *
- * A simple RTL command to aid using the RTL.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-string.c b/cpukit/libdl/rtl-string.c
index 373f9914cc..dc2f6be526 100644
--- a/cpukit/libdl/rtl-string.c
+++ b/cpukit/libdl/rtl-string.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker String managment.
+ */
+
 /*
  *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker String managment.
- */
 
 #include <string.h>
 
diff --git a/cpukit/libdl/rtl-string.h b/cpukit/libdl/rtl-string.h
index 6a1a4db8c7..fe4c50d2ed 100644
--- a/cpukit/libdl/rtl-string.h
+++ b/cpukit/libdl/rtl-string.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker String managment.
+ */
+
 /*
  *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker String managment.
- */
 
 #if !defined (_RTEMS_RTL_STRING_H_)
 #define _RTEMS_RTL_STRING_H_
diff --git a/cpukit/libdl/rtl-sym.c b/cpukit/libdl/rtl-sym.c
index 3fea4b5d20..c29c8c49d6 100644
--- a/cpukit/libdl/rtl-sym.c
+++ b/cpukit/libdl/rtl-sym.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Object File Symbol Table.
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2014, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Object File Symbol Table.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-trace.c b/cpukit/libdl/rtl-trace.c
index 884cab685c..f3f86902cd 100644
--- a/cpukit/libdl/rtl-trace.c
+++ b/cpukit/libdl/rtl-trace.c
@@ -1,5 +1,16 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor Trace
+ *
+ * A configurable tracer for the RTL. See the header file for the enable and
+ * disable.
+ */
+
 /*
  *  COPYRIGHT (c) 2012 Chris Johns <chrisj@rtems.org>
  *
@@ -24,16 +35,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor Trace
- *
- * A configurable tracer for the RTL. See the header file for the enable and
- * disable.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-trampoline.h b/cpukit/libdl/rtl-trampoline.h
index 21aed8a1c3..d3f5a5ae39 100644
--- a/cpukit/libdl/rtl-trampoline.h
+++ b/cpukit/libdl/rtl-trampoline.h
@@ -1,29 +1,5 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
-/*
- *  COPYRIGHT (c) 2019 Chris Johns <chrisj@rtems.org>
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- * 1. Redistributions of source code must retain the above copyright
- *    notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above copyright
- *    notice, this list of conditions and the following disclaimer in the
- *    documentation and/or other materials provided with the distribution.
- *
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
- * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
- * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- * POSSIBILITY OF SUCH DAMAGE.
- */
 /**
  * @file
  *
@@ -73,6 +49,31 @@
  * used as the instructions cannot be loaded.
  */
 
+/*
+ *  COPYRIGHT (c) 2019 Chris Johns <chrisj@rtems.org>
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
 #if !defined (_RTEMS_RTL_TRAMPOLINE_H_)
 #define _RTEMS_RTL_TRAMPOLINE_H_
 
diff --git a/cpukit/libdl/rtl-unresolved.c b/cpukit/libdl/rtl-unresolved.c
index caf7ac6b10..a774c7f1c9 100644
--- a/cpukit/libdl/rtl-unresolved.c
+++ b/cpukit/libdl/rtl-unresolved.c
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Object File Unresolved Relocations Table.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Object File Unresolved Relocations Table.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-unwind-dw2.c b/cpukit/libdl/rtl-unwind-dw2.c
index f2299981d5..4198092baa 100644
--- a/cpukit/libdl/rtl-unwind-dw2.c
+++ b/cpukit/libdl/rtl-unwind-dw2.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor
+ *
+ * This is the RTL implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 2012-2016, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor
- *
- * This is the RTL implementation.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libdl/rtl-unwind-dw2.h b/cpukit/libdl/rtl-unwind-dw2.h
index 7cc781c14f..44f79fb057 100644
--- a/cpukit/libdl/rtl-unwind-dw2.h
+++ b/cpukit/libdl/rtl-unwind-dw2.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Unwind DWARF  Support.
+ */
+
 /*
  *  COPYRIGHT (c) 2016, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Unwind DWARF  Support.
- */
 
 #if !defined (_RTEMS_RTL_UNWIND_DW2_H_)
 #define _RTEMS_RTL_UNWIND_DW2_H_
diff --git a/cpukit/libdl/rtl-unwind.h b/cpukit/libdl/rtl-unwind.h
index f24f83c23e..0eed49381e 100644
--- a/cpukit/libdl/rtl-unwind.h
+++ b/cpukit/libdl/rtl-unwind.h
@@ -1,5 +1,13 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtl
+ *
+ * @brief RTEMS Run-Time Linker Unwind Support.
+ */
+
 /*
  *  COPYRIGHT (c) 2016, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,13 +32,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtl
- *
- * @brief RTEMS Run-Time Linker Unwind Support.
- */
 
 #if !defined (_RTEMS_RTL_UNWIND_H_)
 #define _RTEMS_RTL_UNWIND_H_
diff --git a/cpukit/libdl/rtl.c b/cpukit/libdl/rtl.c
index 57449d44b8..21ddb00aac 100644
--- a/cpukit/libdl/rtl.c
+++ b/cpukit/libdl/rtl.c
@@ -1,5 +1,15 @@
 /* SPDX-License-Identifier: BSD-2-Clause */
 
+/**
+ * @file
+ *
+ * @ingroup rtems_rtld
+ *
+ * @brief RTEMS Run-Time Link Editor
+ *
+ * This is the RTL implementation.
+ */
+
 /*
  *  COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org>
  *
@@ -24,15 +34,6 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
-/**
- * @file
- *
- * @ingroup rtems_rtld
- *
- * @brief RTEMS Run-Time Link Editor
- *
- * This is the RTL implementation.
- */
 
 #ifdef HAVE_CONFIG_H
 #include "config.h"