Update package internal documentation and man pages

Makefile

@@ -222,11 +222,14 @@ docs:
 	@echo "===>  GENERATE DOXYGEN DOCS"
 	@cp doc/lua-doxygen.md doc/lua-doxygen.md.safe
 	@cp doc/likwid-doxygen.md doc/likwid-doxygen.md.safe
-	@sed -i -e s#'<PREFIX>'#$(PREFIX)#g -e s#'<VERSION>'#$(VERSION)#g -e s#'<DATE>'#'$(DATE)'#g -e s#'<RELEASE>'#$(RELEASE)#g -e s#'<MINOR>'#$(MINOR)#g -e s#'<GITCOMMIT>'#$(GITCOMMIT)#g doc/lua-doxygen.md
-	@sed -i -e s#'<PREFIX>'#$(PREFIX)#g -e s#'<VERSION>'#$(VERSION)#g -e s#'<DATE>'#'$(DATE)'#g -e s#'<RELEASE>'#$(RELEASE)#g -e s#'<MINOR>'#$(MINOR)#g -e s#'<GITCOMMIT>'#$(GITCOMMIT)#g doc/likwid-doxygen.md
+	@cp doc/Doxyfile doc/Doxyfile.safe
+	@sed -i -e 's#<PREFIX>#$(PREFIX)#g' -e 's#<VERSION>#$(VERSION)#g' -e 's#<DATE>#$(DATE)#g' -e 's#<RELEASE>#$(RELEASE)#g' -e 's#<MINOR>#$(MINOR)#g' -e 's#<GITCOMMIT>#$(GITCOMMIT)#g' doc/lua-doxygen.md
+	@sed -i -e 's#<PREFIX>#$(PREFIX)#g' -e 's#<VERSION>#$(VERSION)#g' -e 's#<DATE>#$(DATE)#g' -e 's#<RELEASE>#$(RELEASE)#g' -e 's#<MINOR>#$(MINOR)#g' -e 's#<GITCOMMIT>#$(GITCOMMIT)#g' doc/likwid-doxygen.md
+	@sed -i -e 's#<PREFIX>#$(PREFIX)#g' -e 's#<VERSION>#$(VERSION)#g' -e 's#<DATE>#$(DATE)#g' -e 's#<RELEASE>#$(RELEASE)#g' -e 's#<MINOR>#$(MINOR)#g' -e 's#<GITCOMMIT>#$(GITCOMMIT)#g' doc/Doxyfile
 	$(Q)doxygen doc/Doxyfile
 	@mv doc/lua-doxygen.md.safe doc/lua-doxygen.md
 	@mv doc/likwid-doxygen.md.safe doc/likwid-doxygen.md
+	@mv doc/Doxyfile.safe doc/Doxyfile
 
 $(L_APPS):  $(addprefix $(SRC_DIR)/applications/,$(addsuffix  .lua,$(L_APPS)))
 	@echo "===>  ADJUSTING  $@"

doc/applications/likwid-accessD.md

@@ -1,4 +1,4 @@
-/*! \page likwid-accessD <CODE>likwid-accessD</CODE>
+\page likwid-accessD likwid-accessD
 
 <H1>Information</H1>
 
@@ -24,7 +24,7 @@ root: # chown root:root likwid-accessD<BR>
 root: # chmod u+s likwid-accessD<BR>
 </CODE>
 </LI>
-<LI>GUID Method: (PCI devices cannot be accesses with this method but we are working on it)<BR>
+<LI>GUID Method: (PCI devices cannot be accesses with this method)<BR>
 <CODE>
 root: # groupadd likwid<BR>
 root: # chown root:likwid likwid-accessD<BR>
@@ -33,11 +33,11 @@ root: # chmod g+s likwid-accessD<BR>
 </LI>
 <LI>Libcap Method:<BR>
 <CODE>
-root: # setcap cap_sys_rawio+ep likwid-accessD
+root: # setcap cap_sys_rawio,cap_sys_admin,cap_dac_override=ep likwid-accessD
 </CODE>
 </LI>
 </UL>
-There are Linux distributions where settings the suid permission on <CODE>likwid-accessD</CODE> is not enough. Try also to set the capabilities for <CODE>likwid-accessD</CODE>. 
+There are Linux distributions where settings the suid permission on <CODE>likwid-accessD</CODE> is not enough. Try also to set the capabilities for <CODE>likwid-accessD</CODE>. It is important that the user of the devices files have to fit, e.g. changing the owner of <CODE>/dev/cpu/*/msr</CODE> and <CODE>/dev/mem</CODE> either directly or through ACLs. Be aware that this gives users the permissions to read ALL memory.
 
 <H1>Protocol</H1>
 Every likwid instance will start its own daemon. This client-server pair will communicate with a socket file in <CODE>/tmp</CODE>  named <CODE>likwid-$PID</CODE>. The daemon only accepts one connection. As soon as the connect is successful the socket file will be deleted.
@@ -52,4 +52,4 @@ The daemon has the following error handling:
 <LI>If the client prematurely disconnects the daemon terminates.</LI>
 <LI>If the client disconnects between a read and write the daemon catches <CODE>SIGPIPE</CODE>  and disconnects.</LI>
 </UL>
-*/
+

doc/applications/likwid-bench.md

@@ -1,4 +1,4 @@
-/*! \page likwid-bench <CODE>likwid-bench</CODE>
+\page likwid-bench likwid-bench
 
 <H1>Information</H1>
 <CODE>likwid-bench</CODE> is a benchmark suite for low-level (assembly) benchmarks to measure bandwidths and instruction throughput for specific instruction code on x86 systems. The currently included benchmark codes include common data access patterns like load and store but also calculations like vector triad and sum.
@@ -70,6 +70,10 @@
   </TD>
   </TABLE>
 </TR>
+<TR>
+  <TD>-W &lt;workgroup&gt;</TD>
+  <TD>Set the workgroup for the benchmark but allocate all memory thread-local. For format, see -w &lt;workgroup&gt;</TD>
+</TR>
 </TABLE>
 
 
@@ -92,6 +96,3 @@ Run test <CODE>copy</CODE> using <CODE>2</CODE> threads in affinity domain <CODE
 </LI>
 </UL>
 
-
-
-*/

doc/applications/likwid-bridge.md

@@ -0,0 +1,27 @@
+\page likwid-bridge likwid-bridge
+
+<H1>Information</H1>
+<CODE>likwid-bridge</CODE> is proxy for using LIKWID inside of containers. For
+LIKWID installations inside containers with <CODE>ACCESSMODE=accessdaemon</CODE>,
+the access daemon within the containers run with user-priviledges (despite
+being owned by root inside the container). In order to provide also measurement
+functionality inside containers, the <CODE>likwid-bridge</CODE> starts a
+daemon outside of the container and forwards all requests of LIKWID inside the
+container to this outside daemon.
+
+<H1>Usage</H1>
+
+<P>In order to use LIKWID inside the container, you have to wrap the container
+startup with <CODE>likwid-bridge</CODE>:</P>
+
+Apptainer/Singularity:
+
+
+<UL>
+<LI>Apptainer/Singularity:<BR>
+<CODE>likwid-bridge apptainer run &lt;image&gt;</CODE>
+</LI>
+<LI>Docker<BR>
+<CODE>likwid-bridge docker run &lt;image&gt;</CODE>
+</LI>
+</UL>

doc/applications/likwid-features.md

@@ -1,4 +1,4 @@
-/*! \page likwid-features <CODE>likwid-features</CODE>
+\page likwid-features likwid-features
 
 <H1>Information</H1>
 <CODE>likwid-features</CODE> is a command line application to print and change some features of the CPU. Most of the features cannot be changed during runtime, but the prefetchers <CODE>HW_PREFETCHER</CODE>, <CODE>CL_PREFETCHER</CODE>, <CODE>DCU_PREFETCHER</CODE>, <CODE>IP_PREFETCHER</CODE> can be altered.<BR>
@@ -39,6 +39,5 @@
 </TR>
 </TABLE>
 
-<B><CODE>likwid-features</CODE> will be deprecated in 5.4</B>
+<B><CODE>likwid-features</CODE> will be deprecated in in future versions and replaced with \ref likwid-sysfeatures</B>
 
-*/

doc/applications/likwid-genTopoCfg.md

@@ -1,4 +1,4 @@
-/*! \page likwid-genTopoCfg <CODE>likwid-genTopoCfg</CODE>
+\page likwid-genTopoCfg likwid-genTopoCfg
 
 <H1>Information</H1>
 <CODE>likwid-genTopoCfg</CODE> is a command line application that stores the system's CPU and NUMA topology to
@@ -25,5 +25,3 @@ file. LIKWID applications use this file to read in the topology fast instead of
 </TABLE>
 
 
-*/
-

doc/applications/likwid-memsweeper.md

@@ -1,4 +1,4 @@
-/*! \page likwid-memsweeper <CODE>likwid-memsweeper</CODE>
+\page likwid-memsweeper likwid-memsweeper
 
 <H1>Information</H1>
 <CODE>likwid-memsweeper</CODE> is a command line application to shrink the file buffer cache by filling the NUMA domain with random pages. Moreover, the tool invalidates all cachelines in the LLC.
@@ -31,4 +31,3 @@ Cleans the memory and LLC on NUMA nodes identified by the node IDs 0 and 1.
 </LI>
 </UL>
 
-*/

doc/applications/likwid-mpirun.md

@@ -1,4 +1,4 @@
-/*! \page likwid-mpirun <CODE>likwid-mpirun</CODE>
+\page likwid-mpirun likwid-mpirun
 
 <H1>Information</H1>
 <CODE>likwid-mpirun</CODE>
@@ -44,7 +44,7 @@ A tool to start and monitor MPI applications with LIKWID. It can be used as supp
 </TR>
 <TR>
   <TD>--mpi &lt;mpitype&gt;</TD>
-  <TD>Specify the type of the MPI implementation.<BR><CODE>likwid-mpirun</CODE> tries to read the MPI implementation from the <A HREF="http://modules.sourceforge.net/">modules</A> system.<BR>If not recognized automatically, possible values are <B>intelmpi</B>, <B>openmpi</B> and <B>mvapich2</B>.</TD>
+  <TD>Specify the type of the MPI implementation.<BR><CODE>likwid-mpirun</CODE> tries to read the MPI implementation from the <A HREF="http://modules.sourceforge.net/">modules</A> system.<BR>If not recognized automatically, possible values are <B>intelmpi</B>, <B>openmpi</B>, <B>slurm</B> and <B>mvapich2</B>.</TD>
 </TR>
 <TR>
   <TD>--omp &lt;omptype&gt;</TD>
@@ -84,4 +84,4 @@ Runs <CODE>./a.out</CODE> with 2 MPI processes per socket on each host in <CODE>
 Only one process per socket measures the Uncore/RAPL counters, the other one(s) only core-local counters.
 </LI>
 </UL>
-*/
+

doc/applications/likwid-perfctr.md

@@ -1,4 +1,4 @@
-/*! \page likwid-perfctr <CODE>likwid-perfctr</CODE>
+\page likwid-perfctr likwid-perfctr
 
 <H1>Information</H1>
 <CODE>likwid-perfctr</CODE> is a lightweight command line application to configure and read out hardware performance monitoring data
@@ -210,7 +210,7 @@ While installation of LIKWID, the performance groups are copied to the path <COD
 \anchor Marker_API
 <H1>Marker API</H1>
 The Marker API enables measurement of user-defined code regions in order to get deeper insight what is happening at a specific point in the application. The Marker API itself has 8 commands. In order to activate the Marker API, the code must be compiled with <CODE>-DLIKWID_PERFMON</CODE>. If the code is compiled without this define, the Marker API functions perform no operation and cause no overhead. You can also run code compiled with LIKWID_PERFMON defined without measurements but a message will be printed.<BR>
-Even pure serial applications have to call LIKWID_MARKER_THREADINIT to initialize the accessDaemon or the direct accesses.<BR>
+It is recommended to register all regions with <CODE>LIKWID_MARKER_REGISTER</CODE> in a parallel region. This sets up the data structures for the region and if compiled with <CODE>ACCESSMODE=accessdaemon</CODE>, the accessdaemon is started for each thread.<BR>
 The names for the regions can be freely chosen but <I>whitespaces are not allowed</I>.
 <H2>C/C++ Code</H2>
 <H3>Original code</H3>
@@ -246,7 +246,7 @@ int main(int argc, char* argv[])<BR>
 &nbsp;&nbsp;LIKWID_MARKER_INIT;<BR>
 \#pragma omp parallel<BR>
 {<BR>
-&nbsp;&nbsp;LIKWID_MARKER_THREADINIT;<BR>
+&nbsp;&nbsp;LIKWID_MARKER_REGISTER("sum");<BR>
 }<BR>
 \#pragma omp parallel<BR>
 {<BR>
@@ -279,11 +279,11 @@ Besides the Marker API for C/C++ programms, LIKWID offers to build a Fortran mod
 The LIKWID package contains an example code: see \ref F-markerAPI-code.
 
 <H2>Hints for the usage of the Marker API</H2>
-Since the calls to the LIKWID library are executed by your application, the runtime will raise and in specific circumstances, there are some other problems like the time measurement. You can execute <CODE>LIKWID_MARKER_THREADINIT</CODE> and <CODE>LIKWID_MARKER_START</CODE> inside the same parallel region but put a barrier between the calls to ensure that there is no big timing difference between the threads. The common way is to init LIKWID and the participating threads inside of an initialization routine, use only START and STOP in your code and close the Marker API in a finalization routine. Be aware that at the first start of a region, the thread-local hash table gets a new entry to store the measured values. If your code inside the region is short or you are executing the region only once, the overhead of creating the hash table entry can be significant compared to the execution of the region code. The overhead of creating the hash tables can be done in prior by using the <CODE>LIKWID_MARKER_REGISTER</CODE> function. It must be called by each thread and one time for each compute region. It is completely <I>optional</I>, <CODE>LIKWID_MARKER_START</CODE> performs the same operations.
+Since the calls to the LIKWID library are executed by your application, the runtime will raise and in specific circumstances, there are some other problems like the time measurement. You can execute <CODE>LIKWID_MARKER_THREADINIT</CODE> and <CODE>LIKWID_MARKER_START</CODE> inside the same parallel region but put a barrier between the calls to ensure that there is no big timing difference between the threads. The common way is to init LIKWID and the participating threads inside of an initialization routine, use only START and STOP in your code and close the Marker API in a finalization routine. Be aware that at the first start of a region, the thread-local hash table gets a new entry to store the measured values. If your code inside the region is short or you are executing the region only once, the overhead of creating the hash table entry can be significant compared to the execution of the region code. The overhead of creating the hash tables can be done in prior by using the <CODE>LIKWID_MARKER_REGISTER</CODE> function. It must be called by each thread and one time for each compute region. It is completely <I>optional</I>, <CODE>LIKWID_MARKER_START</CODE> performs the same operations. See the <a href="https://github.com/RRZE-HPC/likwid/wiki/LikwidMarkerAPIPitfalls">MarkerAPI Pitfalls</a> wiki page for further information.
 
 <H2>CUDA code</H2>
-With LIKWID 5.0 CUDA kernels can be measured. There is a special NvMarkerAPI for Nvidia GPUs. The usage is similar to the CPU MarkerAPI, just replace <CODE>LIKWID_MARKER_</CODE> with <CODE>LIKWID_NVMARKER_</CODE>. All MarkerAPIs can be mixed.
+With LIKWID 5.0 CUDA kernels can be measured. There is a special NvMarkerAPI for Nvidia GPUs. The usage is similar to the CPU MarkerAPI, just replace <CODE>LIKWID_MARKER_</CODE> with <CODE>NVMON_MARKER_</CODE>. All MarkerAPIs can be mixed.
 
 <H2>ROCm code</H2>
 ROCm kernels can be measured. There is a special RocmonMarkerAPI for AMD GPUs. The usage is similar to the CPU or Nvidia MarkerAPI, just replace <CODE>LIKWID_MARKER_</CODE> with <CODE>ROCMON_MARKER_</CODE>. All MarkerAPIs can be mixed.
-*/
+

doc/applications/likwid-perfscope.md

@@ -1,4 +1,4 @@
-/*! \page likwid-perfscope <CODE>likwid-perfscope</CODE>
+\page likwid-perfscope likwid-perfscope
 
 <H1>Information</H1>
 <CODE>likwid-perfscope</CODE> is a command line application written in Lua that uses the timeline daemon mode of \ref likwid-perfctr
@@ -103,4 +103,3 @@ Pin the executable <CODE>./a.out</CODE> to CPU 1 on Socket 0 and use the predefi
 </LI>
 </UL>
 
-*/