Adding thread_utils

Signed-off-by: Mark Burton <[email protected]>

Author: markfoodyburton

CMakeLists.txt

@@ -12,7 +12,7 @@ FetchContent_Declare(
   cpm-cmake
   GIT_REPOSITORY ${GITHUB}cpm-cmake/CPM.cmake.git
   GIT_SHALLOW True
-  GIT_TAG v0.31.1
+  GIT_TAG v0.40.2
 )
 
 FetchContent_MakeAvailable(cpm-cmake)
@@ -39,7 +39,10 @@ cpmaddpackage(
   NAME report
   SOURCE_DIR ${PROJECT_SOURCE_DIR}/report
 )
-
+cpmaddpackage(
+  NAME thread_utils
+  SOURCE_DIR ${PROJECT_SOURCE_DIR}/thread_utils
+)
 if("${PROJECT_NAME}" STREQUAL "${CMAKE_PROJECT_NAME}")
   add_subdirectory(examples)
   if(BUILD_TESTING)

report/CMakeLists.txt

@@ -12,7 +12,7 @@ FetchContent_Declare(
   cpm-cmake
   GIT_REPOSITORY ${GITHUB}cpm-cmake/CPM.cmake.git
   GIT_SHALLOW True
-  GIT_TAG v0.31.1
+  GIT_TAG v0.40.2
 )
 
 FetchContent_MakeAvailable(cpm-cmake)
@@ -51,7 +51,7 @@ FetchContent_Declare(
     GIT_TAG        "v1.9.2"
     GIT_SHALLOW    ON
 )
-FetchContent_Populate(spdlog_git)
+FetchContent_MakeAvailable(spdlog_git)
 FetchContent_GetProperties(
   spdlog_git
   SOURCE_DIR spdlog_git_SRC_DIR

thread_utils/CMakeLists.txt

@@ -0,0 +1,69 @@
+cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+project(thread_utils VERSION 1.0 LANGUAGES CXX C)
+
+set(CMAKE_CXX_STANDARD 14 CACHE STRING "C++ standard to build all targets.")
+
+set(GITHUB "https://github.com/" CACHE STRING "github base url")
+
+include(FetchContent)
+include(CTest)
+
+FetchContent_Declare(
+  cpm-cmake
+  GIT_REPOSITORY ${GITHUB}cpm-cmake/CPM.cmake.git
+  GIT_SHALLOW True
+  GIT_TAG v0.40.2
+)
+
+FetchContent_MakeAvailable(cpm-cmake)
+include(${cpm-cmake_SOURCE_DIR}/cmake/CPM.cmake)
+
+cpmaddpackage("${GITHUB}TheLartians/[email protected]")
+
+cpmaddpackage(
+  NAME SystemCLanguage
+  GIT_REPOSITORY  ${GITHUB}accellera-official/systemc.git
+  GIT_SHALLOW True
+  GIT_TAG main
+)
+
+# upstream set INSTALL_NAME_DIR wrong !
+if (APPLE)
+  set_target_properties(
+    systemc
+    PROPERTIES
+    INSTALL_NAME_DIR "@rpath"
+  )
+endif()
+
+
+add_library(${PROJECT_NAME} INTERFACE)
+
+target_include_directories(
+   ${PROJECT_NAME} INTERFACE
+   $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
+   $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+)
+
+if(BUILD_TESTING AND ("${PROJECT_NAME}" STREQUAL "${CMAKE_PROJECT_NAME}"))
+   enable_testing()
+   add_subdirectory(tests)
+endif()
+
+add_library("scp::thread_utils::lib${PROJECT_NAME}" ALIAS ${PROJECT_NAME})
+packageproject(
+   NAME "${PROJECT_NAME}"
+   VERSION ${PROJECT_VERSION}
+   NAMESPACE scp
+   BINARY_DIR ${PROJECT_BINARY_DIR}
+   INCLUDE_DIR ${PROJECT_SOURCE_DIR}/include
+   INCLUDE_DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
+   VERSION_HEADER "${VERSION_HEADER_LOCATION}"
+   COMPATIBILITY SameMajorVersion
+)
+install(
+   TARGETS ${PROJECT_NAME}
+   LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+   COMPONENT "${PROJECT_NAME}_Runtime"
+   NAMELINK_COMPONENT "${PROJECT_NAME}_Development"
+)

thread_utils/README.md

@@ -0,0 +1,103 @@
+
+
+## Threading Utilities
+
+The library offers the following utilities
+
+# scp::scp_async_event
+***NB this could be considered for standardization within the SystemC kernel as sc_async_event***
+
+An ***scp_async_event*** is identical to an sc_event except that it can be notified in a thread safe manner from a different thread. In the same way that an ***sc_event*** may be notified many times, an ***scp_async_event*** makes no guarantee about the number of times the actual event listener is notified, but does guarantee that it will at least be notified after the last time that any of the thread safe notify methods are called.
+
+The ***scp_async_event*** also can be considered as a ***sc_prim_channel***. In addition to the standard ***sc_event*** interface, the ***scp_async_event*** also provides convenience functions to attach and detach the primary channel from the SystemC kernel as a potential source of external events.
+
+*** NOTE ***
+An ***scp_async_event***  *MUST* be constructed on the SystemC thread. Failure to do so is an error and will have unexpected consequences.
+
+```cpp
+class scp_async_event : public sc_core::sc_prim_channel, public sc_core::sc_event
+{
+public:
+    scp_async_event(bool start_attached = true);
+    void async_attach_suspending();
+    void async_detach_suspending();
+    void enable_attach_suspending(bool);
+}
+```
+Hence ***async_attach_suspending*** shall attach the primary channel to the SystemC kernel as a potential source of external events, and will therefore prevent the SystemC kernel from exiting. See ***sc_prim_channel::async_attach_suspending***. Likewise ***async_detach_suspending*** will detach the primary channel, while ***enable_attach_suspending*** shall attach if the boolean argument is true, else it will detach the channel.
+
+On construction by default the channel will be ***attached*** to the kernel, but this may be prevented by passing ***false*** to the constructor.
+
+Notifications of the event from within the same thread as the SystemC kernel shall be treated identically to notifications posted to a normal ***sc_event***. When notified from a different thread the delay posted in the notification of the ***scp_async_event*** shall be respected, but there is no guarantee that the SystemC time will not have advanced by the time the event is posted within the SystemC kernel, so it is recommended that this delay not be used. From a separate thread there is no means to perform an ***immediate*** notification, this will be treated as a delta notification (with SC_ZERO_TIME).
+
+Calling ***triggered()*** from a outside the SystemC kernel thread is an error and an SC_ERROR_REPORT will be generated.
+
+# scp::run_on_systemc
+***NB The interface of this class could be considered for standardization within the SystemC kernel***
+
+***run_on_systemc*** provides a convenience class that can be instanced in order to provide the means to execute a ```std::function``` on the SystemC thread in a thread safe manner from another thread.
+
+*** NOTE ***
+An instance of the ***run_on_systemc*** module *MUST* be constructed on the SystemC thread. Failure to do so is an error and will have unexpected consequences.
+
+```cpp
+class run_on_systemc : public sc_core::sc_module
+{
+public:
+
+    run_on_systemc()
+
+    void scp_cancel_pendings();
+    void scp_fork_on_systemc(std::function<void()> job_entry);
+    bool scp_run_on_systemc(std::function<void()> job_entry, bool wait = true);
+    bool scp_is_on_systemc() const;
+};
+```
+
+In order to run a job on the SystemC kernel thread, ***scp_run_on_systemc*** method should be called with an appropriate ```std::function```. The ***scp_run_on_systemc*** takes an optional argument to wait for the job to be scheduled and executed on SystemC, which defaults to true. 
+The return status is set to ***true*** if the job has been successfully executed and completed and ***false*** if the job was canceled before it was finished. 
+
+If ***run_on_systemc*** is called from within the SystemC thread, then the job is executed immediately (In this case the return status will be ***true***).
+
+The method ***scp_fork_on_systemc*** is a convenience function that calls ***scp_run_on_systemc*** with wait set to false (there is no return status as the job can not be interrupted).
+
+The method ***scp_cancel_pendings*** cancels all pending jobs. Any jobs which are queue'd waiting to be processed by SystemC will be canceled.
+
+
+# keep_alive
+This is a simple ***sc_module*** convenience class which contains an ***scp_async_event*** initialised to attach to the SystemC kernel, and shall therefore ensure that the simulation does not finish. The module provides a convenience function (***finish()***) to detach the event (and therefore allow the simulation to exit).
+
+```cpp
+class keep_alive : public sc_core::sc_module
+{
+public:
+    scp::async_event keep_alive_event;
+
+    keep_alive(sc_core::sc_module_name name): sc_core::sc_module(name) {
+        keep_alive_event.async_attach_suspending();
+    }
+    void finish() {
+        keep_alive_event.async_detach_suspending();
+        keep_alive_event.notify();
+    }
+    ~keep_alive() {}
+};
+```
+
+
+
+# realtimelimiter
+An instance of this sc_module will ensure that SystemC time never advances more than realtime (with a granularity of 100ms). Convenience functions to `enable` and `disable` this behavior are provided.
+
+```cpp
+SC_MODULE (real_time_limiter) {
+public:
+    void enable();
+    void disable();
+    real_time_limiter(const sc_core::sc_module_name& name,
+                      bool autostart = true,
+                      sc_core::sc_time accuracy=sc_core::sc_time(100, sc_core::SC_MS)):
+};
+```
+
+The constructor, and ***enable*** and ***disable*** funtions must be called from the systemc thread. By default, the ****real_time_limiter*** is constructed to start automatically, with an accuracy of 100ms.

thread_utils/include/scp/thread_utils/async_event.h

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2022-2024 Qualcomm Innovation Center, Inc. All Rights
+ * Reserved.
+ * Author: GreenSocs 2022
+ *
+ * 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.
+ *******************************************************************************/
+
+#ifndef _SCP_ASYNC_EVENT
+#define _SCP_ASYNC_EVENT
+
+#include <iostream>
+
+#include <systemc>
+#include <tlm>
+#include <thread>
+#include <mutex>
+
+namespace scp {
+class scp_async_event : public sc_core::sc_prim_channel,
+                        public sc_core::sc_event
+{
+private:
+    sc_core::sc_time m_delay;
+    std::thread::id tid;
+    std::mutex mutex; // Belt and braces
+    bool outstanding=false;
+
+public:
+    scp_async_event(bool start_attached = true) {
+        tid = std::this_thread::get_id();
+        enable_attach_suspending(start_attached);
+    }
+
+    void async_notify() { notify(); }
+
+    void notify() {
+        if (tid == std::this_thread::get_id()) {
+            sc_core::sc_event::notify();
+        } else {
+            notify(sc_core::SC_ZERO_TIME);
+        }
+    }
+    void notify(double d, sc_core::sc_time_unit u) {
+        notify(sc_core::sc_time(d, u));
+    }
+    void notify(sc_core::sc_time delay) {
+        if (tid == std::this_thread::get_id()) {
+            sc_core::sc_event::notify(delay);
+        } else {
+            mutex.lock();
+            m_delay = delay;
+            outstanding = true;
+            mutex.unlock();
+            async_request_update();
+        }
+    }
+
+    bool triggered() const {
+        if (tid == std::this_thread::get_id()) {
+            return sc_core::sc_event::triggered();
+        } else {
+            SC_REPORT_ERROR("scp_async_event",
+                            "It is an error to call triggered() from outside "
+                            "the SystemC thread");
+        }
+        return false;
+    }
+    void async_attach_suspending() {
+        this->sc_core::sc_prim_channel::async_attach_suspending();
+    }
+
+    void async_detach_suspending() {
+        this->sc_core::sc_prim_channel::async_detach_suspending();
+    }
+
+    void enable_attach_suspending(bool e) {
+        e ? this->async_attach_suspending() : this->async_detach_suspending();
+    }
+
+private:
+    void update(void) {
+        mutex.lock();
+        // we should be in SystemC thread
+        if (outstanding) {
+            sc_event::notify(m_delay);
+            outstanding = false;
+        }
+        mutex.unlock();
+    }
+    void start_of_simulation() {
+        // we should be in SystemC thread
+        if (outstanding) {
+            request_update();
+        }
+    }
+};
+} // namespace scp
+
+#endif // SCP_ASYNC_EVENT

thread_utils/include/scp/thread_utils/keep_alive.h

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2023 Qualcomm Innovation Center, Inc. All Rights Reserved.
+ *
+ * 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.
+ *******************************************************************************/
+
+/**
+ * @class KeepAlive
+ * @brief this class is used to keep the simulation alive by using an async
+ * event
+ */
+#ifndef _SCP_KEEP_ALIVE_H_
+#define _SCP_KEEP_ALIVE_H_
+
+#include <systemc>
+#include <scp/thread_utils/async_event.h>
+
+namespace scp {
+class keep_alive : public sc_core::sc_module
+{
+public:
+    scp::scp_async_event keep_alive_event;
+
+    keep_alive(sc_core::sc_module_name name): sc_core::sc_module(name) {
+        keep_alive_event.async_attach_suspending();
+    }
+    void finish() {
+        keep_alive_event.async_detach_suspending();
+        keep_alive_event.notify();
+    }
+    ~keep_alive() {}
+};
+} // namespace scp
+
+#endif