[DAPHNE-daphne-eu#552] Document the PAPI profling support

Closes daphne-eu#552, Closes daphne-eu#561

doc/Profiling.md

@@ -0,0 +1,40 @@
+<!--
+Copyright 2023 The DAPHNE Consortium
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Profiling DAPHNE using PAPI
+You can profile your DAPHNE script by using the ```--enable-profiling``` CLI
+switch.
+
+DAPHNE supports profiling via the [PAPI](https://github.com/icl-utk-edu/papi)
+profiling library, specifically the
+[high-level (HL) PAPI API](https://github.com/icl-utk-edu/papi/wiki/PAPI-HL)).
+
+When run with profiling enabled, the DAPHNE compiler will generate code that
+automatically starts and stops profiling (via PAPI) at the start and end of the
+DAPHNE script.
+
+You can configure which events to profile via the ```PAPI_EVENTS```
+environmental variable, e.g.:
+```bash
+$ PAPI_EVENTS="perf::CYCLES,perf::INSTRUCTIONS,perf::CACHE-REFERENCES,perf::CACHE MISSES,perf::BRANCHES,perf::BRANCH-MI SSES" PAPI_REPORT=1 ./daphne --enable-profiling script.daph
+```
+
+For more details about the supported events as well as other PAPI-HL configuration
+options you can check the
+[PAPI HL API documentation](https://github.com/icl-utk-edu/papi/wiki/PAPI-HL#overview-of-environment-variables).
+You can also get a list of the supported events on your machine via the
+```papi_native_avail``` PAPI utility (included in the ```papi-tools``` package
+on Debian-based systems).

doc/README.md

@@ -31,6 +31,7 @@ limitations under the License.
 - [Using SQL in DaphneDSL](/doc/tutorial/sqlTutorial.md)
 - [A Few Early Example Algorithms in DaphneDSL](/scripts/algorithms/)
 - [FileMetaData Format (reading and writing data)](/doc/FileMetaDataFormat.md)
+- [Profiling DAPHNE using PAPI](/doc/Profiling.md)
 
 ## Developer Documentation
 
@@ -44,6 +45,7 @@ limitations under the License.
 - [Extending the DAPHNE Distributed Runtime](/doc/development/ExtendingDistributedRuntime.md)
 - [Building DAPHNE with the build.sh script](/doc/development/BuildingDaphne.md)
 - [Logging in DAPHNE](/doc/development/Logging.md)
+- [Profiling in DAPHNE](/doc/development/Profling.md)
 
 ### Source Code Documentation
 

doc/development/Profiling.md

@@ -0,0 +1,35 @@
+<!--
+Copyright 2023 The DAPHNE Consortium
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Profiling in DAPHNE
+For a general overview of the profiling support in DAPHNE see the [user
+profiling documentation](../Profiling.md).
+
+Profiling is implemented via an instrumentation pass that injects calls to the
+```StartProfiling``` and ```StopProfiling``` kernels at the start and end of
+each block. In turn, the kernels call the PAPI-HL API start and stop functions.
+
+### Known Issues / TODO:
+* For scripts with multiple blocks (e.g. UDFs), the compiler will generate
+  profiling passes for each block seperately instead of a single script-wide
+  profiling pass.
+* The profiling kernels should be exposed at the DSL / IR level, so that users
+  can instrument / profile specific parts of their script. This will also need
+  compiler cooperation, to make sure that the profiled bock is not rearranged /
+  fused with other operations.
+* To aid with the development and regression tracking of the runtime, the
+  profiling kernels could also be extended to suport profiling specific
+  kernels or parts of kernels.