cocotb 2.0.0rc2__cp311-cp311-macosx_11_0_arm64.whl

cocotb/share/include/gpi_logging.h

@@ -0,0 +1,291 @@
+// Copyright cocotb contributors
+// Copyright (c) 2013 Potential Ventures Ltd
+// Copyright (c) 2013 SolarFlare Communications Inc
+// Licensed under the Revised BSD License, see LICENSE for details.
+// SPDX-License-Identifier: BSD-3-Clause
+
+#ifndef COCOTB_GPI_LOGGING_H_
+#define COCOTB_GPI_LOGGING_H_
+
+#include <cstdarg>  // va_list
+#include <cstring>  // strlen
+
+#include "exports.h"
+
+#ifdef GPILOG_EXPORTS
+#define GPILOG_EXPORT COCOTB_EXPORT
+#else
+#define GPILOG_EXPORT COCOTB_IMPORT
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Named logging level
+ *
+ *  The native logger only logs level names at these log level values.
+ *  They were specifically chosen to align with the default level values in the
+ *  Python logging module. Implementers of custom loggers should emit human
+ *  readable level names for these value, but may support other values.
+ */
+enum gpi_log_level {
+    GPI_NOTSET = 0,  ///< Lets the parent logger in the hierarchy decide the
+                     ///< effective log level. By default this behaves like
+                     ///< `INFO`.
+    GPI_TRACE = 5,   ///< Prints `TRACE` by default. Information about execution
+                     ///< of simulator callbacks and Python/simulator contexts.
+    GPI_DEBUG = 10,  ///< Prints `DEBUG` by default. Verbose information, useful
+                     ///< for debugging.
+    GPI_INFO = 20,   ///< Prints `INFO` by default. Information about major
+                     ///< events in the current program.
+    GPI_WARNING = 30,  ///< Prints `WARN` by default. Encountered a recoverable
+                       ///< bug, or information about surprising behavior.
+    GPI_ERROR = 40,    ///< Prints `ERROR` by default. An unrecoverable error
+    GPI_CRITICAL = 50  ///< Prints `CRITICAL` by default. An unrecoverable
+                       ///< error, to be followed by immediate simulator
+                       ///< shutdown.
+};
+
+#define LOG_EXPLICIT(logger, level, file, func, lineno, ...) \
+    gpi_log_(logger, level, file, func, lineno, __VA_ARGS__)
+
+#define LOG_(level, ...) \
+    gpi_log_("gpi", level, __FILE__, __func__, __LINE__, __VA_ARGS__)
+
+/** Logs a message at TRACE log level using the current log handler.
+ Automatically populates arguments using information in the called context.
+*/
+#define LOG_TRACE(...) LOG_(GPI_TRACE, __VA_ARGS__)
+
+/** Logs a message at DEBUG log level using the current log handler.
+ Automatically populates arguments using information in the called context.
+*/
+#define LOG_DEBUG(...) LOG_(GPI_DEBUG, __VA_ARGS__)
+
+/** Logs a message at INFO log level using the current log handler.
+ Automatically populates arguments using information in the called context.
+*/
+#define LOG_INFO(...) LOG_(GPI_INFO, __VA_ARGS__)
+
+/** Logs a message at WARN log level using the current log handler.
+ Automatically populates arguments using information in the called context.
+*/
+#define LOG_WARN(...) LOG_(GPI_WARNING, __VA_ARGS__)
+
+/** Logs a message at ERROR log level using the current log handler.
+ Automatically populates arguments using information in the called context.
+*/
+#define LOG_ERROR(...) LOG_(GPI_ERROR, __VA_ARGS__)
+
+/** Logs a message at CRITICAL log level using the current log handler.
+ Automatically populates arguments using information in the called context.
+*/
+#define LOG_CRITICAL(...) LOG_(GPI_CRITICAL, __VA_ARGS__)
+
+#define MAKE_LOG_NAME_(extra_name) \
+    (extra_name[0] == '\0' ? "gpi" : "gpi." extra_name)
+
+/** Type of a logger handler function.
+ * @param userdata  private implementation data registered with this function
+ * @param name      Name of the logger
+ * @param level     Level at which to log the message
+ * @param pathname  Name of the file where the call site is located
+ * @param funcname  Name of the function where the call site is located
+ * @param lineno    Line number of the call site
+ * @param msg       The message to log, uses C-sprintf-style format specifier
+ * @param args      Additional arguments; formatted and inserted in message
+ *                  according to format specifier in msg argument
+ */
+typedef void (*gpi_log_handler_ftype)(void *userdata, const char *name,
+                                      int level, const char *pathname,
+                                      const char *funcname, long lineno,
+                                      const char *msg, va_list args);
+
+/** Type of a logger filter function.
+ *
+ * Log filter functions test to see if a message would be emitted if logged at
+ * the given log level.
+ *
+ * @param userdata  Private implementation data registered with this function.
+ * @param logger    Name of the logger.
+ * @param level     Level at which to test if the logger would emit a message.
+ * @return `true` if the *logger* is enabled at *level*.
+ */
+typedef bool (*gpi_log_filter_ftype)(void *userdata, const char *logger,
+                                     int level);
+
+/** Type of a logger set level function.
+ *
+ * Log filter functions test to see if a message would be emitted if logged at
+ * the given log level.
+ *
+ * @param userdata  Private implementation data registered with this function.
+ * @param logger    Name of the logger.
+ * @param level     Level at which to test if the logger would emit a message.
+ * @return `true` if the *logger* is enabled at *level*.
+ */
+typedef bool (*gpi_log_set_level_ftype)(void *userdata, const char *logger,
+                                        int level);
+
+/** Log a message using the currently registered log handler.
+ *
+ * @param extra_name  Name of the "gpi" child logger, "" for the root logger
+ * @param level       Level at which to log the message
+ * @param pathname    Name of the file where the call site is located
+ * @param funcname    Name of the function where the call site is located
+ * @param lineno      Line number of the call site
+ * @param msg         The message to log, uses C-sprintf-style format specifier
+ * @param ...         Additional arguments; formatted and inserted in message
+ *                    according to format specifier in msg argument
+ */
+#define gpi_log(extra_name, level, pathname, funcname, lineno, ...)         \
+    gpi_log_(MAKE_LOG_NAME_(extra_name), level, pathname, funcname, lineno, \
+             __VA_ARGS__)
+
+// Don't call this function directly unless the name is "gpi" or starts with
+// "gpi."
+GPILOG_EXPORT void gpi_log_(const char *name, int level, const char *pathname,
+                            const char *funcname, long lineno, const char *msg,
+                            ...);
+
+/** Log a message using the currently registered log handler.
+ *
+ * @param extra_name  Name of the "gpi" child logger, "" for the root logger
+ * @param level       Level at which to log the message
+ * @param pathname    Name of the file where the call site is located
+ * @param funcname    Name of the function where the call site is located
+ * @param lineno      Line number of the call site
+ * @param msg         The message to log, uses C-sprintf-style format specifier
+ * @param args        Additional arguments; formatted and inserted in message
+ *                    according to format specifier in msg argument
+ */
+#define gpi_vlog(extra_name, level, pathname, funcname, lineno, msg, args)   \
+    gpi_vlog_(MAKE_LOG_NAME_(extra_name), level, pathname, funcname, lineno, \
+              msg, args)
+
+// Don't call this function directly unless the name is "gpi" or starts with
+// "gpi."
+GPILOG_EXPORT void gpi_vlog_(const char *name, int level, const char *pathname,
+                             const char *funcname, long lineno, const char *msg,
+                             va_list args);
+
+/** Check if a log would be filtered.
+ *
+ * @param logger Name of the logger.
+ * @param level Level at which to test if the logger would emit a message.
+ * @return `true` if the *logger* is enabled at *level*.
+ */
+GPILOG_EXPORT bool gpi_log_filtered(const char *logger, int level);
+
+/** Set the log level of a logger.
+ *
+ * @param logger Name of the logger.
+ * @param level Level to set the logger to.
+ * @return The old log level.
+ */
+GPILOG_EXPORT int gpi_log_set_level(const char *logger, int level);
+
+/** @return The string representation of the GPI log level. */
+GPILOG_EXPORT const char *gpi_log_level_to_str(int level);
+
+/** Retrieve the current log handler.
+ * @param handler   Location to return current log handler function. If no
+ *                  custom logger is registered this will be `NULL`.
+ * @param filter    Location to return current log filter function. If no
+ *                  custom logger is registered this will be `NULL`.
+ * @param set_level Location to return current log set level function. If no
+ *                  custom logger is registered this will be `NULL`.
+ * @param userdata  Location to return log handler userdata. If no custom
+ *                  logger is registered this will be `NULL`.
+ */
+GPILOG_EXPORT void gpi_get_log_handler(gpi_log_handler_ftype *handler,
+                                       gpi_log_filter_ftype *filter,
+                                       gpi_log_set_level_ftype *set_level,
+                                       void **userdata);
+
+/** Set custom log handler
+ * @param handler   Logger handler function.
+ * @param filter    Logger level filter function.
+ * @param set_level Logger set level function.
+ * @param userdata  Data passed to the above functions.
+ */
+GPILOG_EXPORT void gpi_set_log_handler(gpi_log_handler_ftype handler,
+                                       gpi_log_filter_ftype filter,
+                                       gpi_log_set_level_ftype set_level,
+                                       void *userdata);
+
+/** Clear the current custom log handler and use native logger. */
+GPILOG_EXPORT void gpi_clear_log_handler(void);
+
+/*******************************************************************************
+ * GPI Native Logger
+ *******************************************************************************/
+
+/** Log a message using the native log handler.
+ * User is expected to populate all arguments to this function.
+ * @param extra_name  Name of the "gpi" child logger, "" for the root logger
+ * @param level       Level at which to log the message
+ * @param pathname    Name of the file where the call site is located
+ * @param funcname    Name of the function where the call site is located
+ * @param lineno      Line number of the call site
+ * @param msg         The message to log, uses C-sprintf-style format specifier
+ * @param ...         Additional arguments; formatted and inserted in message
+ *                    according to format specifier in msg argument
+ */
+#define gpi_native_logger_log(extra_name, level, pathname, funcname, lineno, \
+                              ...)                                           \
+    gpi_native_logger_log_(MAKE_LOG_NAME_(extra_name), level, pathname,      \
+                           funcname, lineno, __VA_ARGS__)
+
+// Don't call this function directly unless the name is "gpi" or starts with
+// "gpi."
+GPILOG_EXPORT void gpi_native_logger_log_(const char *name, int level,
+                                          const char *pathname,
+                                          const char *funcname, long lineno,
+                                          const char *msg, ...);
+
+/** Log a message using the native log handler.
+ * User is expected to populate all arguments to this function.
+ * @param extra_name  Name of the "gpi" child logger, "" for the root logger
+ * @param level       Level at which to log the message
+ * @param pathname    Name of the file where the call site is located
+ * @param funcname    Name of the function where the call site is located
+ * @param lineno      Line number of the call site
+ * @param msg         The message to log, uses C-sprintf-style format specifier
+ * @param args        Additional arguments; formatted and inserted in message
+ *                    according to format specifier in msg argument
+ */
+#define gpi_native_logger_vlog(extra_name, level, pathname, funcname, lineno, \
+                               msg, args)                                     \
+    gpi_native_logger_vlog_(MAKE_LOG_NAME_(extra_name), level, pathname,      \
+                            funcname, lineno, msg, args)
+
+// Don't call this function directly unless the name is "gpi" or starts with
+// "gpi."
+GPILOG_EXPORT void gpi_native_logger_vlog_(const char *name, int level,
+                                           const char *pathname,
+                                           const char *funcname, long lineno,
+                                           const char *msg, va_list args);
+
+/** Check if a message would be filtered by the native logger.
+ *
+ * @param level     Level at which to test if the logger would emit a message.
+ * @return `true` if the *logger* is enabled at *level*.
+ */
+GPILOG_EXPORT bool gpi_native_logger_filtered(int level);
+
+/** Set minimum logging level of the native logger.
+ *
+ * If a logging request occurs where the logging level is lower than the level
+ * set by this function, it is not logged. Only affects the native logger.
+ * @param level     Logging level
+ * @return          Previous logging level
+ */
+GPILOG_EXPORT int gpi_native_logger_set_level(int level);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* COCOTB_GPI_LOGGING_H_ */

cocotb/share/include/py_gpi_logging.h

@@ -0,0 +1,33 @@
+// Copyright cocotb contributors
+// Licensed under the Revised BSD License, see LICENSE for details.
+// SPDX-License-Identifier: BSD-3-Clause
+
+#ifndef PY_GPI_LOGGING_H
+#define PY_GPI_LOGGING_H
+
+#include <Python.h>
+
+#include "exports.h"
+
+#ifdef PYGPILOG_EXPORTS
+#define PYGPILOG_EXPORT COCOTB_EXPORT
+#else
+#define PYGPILOG_EXPORT COCOTB_IMPORT
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+PYGPILOG_EXPORT void py_gpi_logger_initialize(PyObject *handler,
+                                              PyObject *get_logger);
+
+PYGPILOG_EXPORT void py_gpi_logger_finalize();
+
+extern PYGPILOG_EXPORT PyObject *pEventFn;  // This is gross but I don't care
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

cocotb/share/include/vhpi_user_ext.h

@@ -0,0 +1,26 @@
+// Copyright cocotb contributors
+// Licensed under the Revised BSD License, see LICENSE for details.
+// SPDX-License-Identifier: BSD-3-Clause
+
+/* extensions to vhpi_user.h */
+
+#ifndef VHPI_USER_EXT_H
+#define VHPI_USER_EXT_H
+
+#ifdef  __cplusplus
+extern "C" {
+#endif
+
+/* arguments for vhpiStop or vhpiFinish */
+typedef enum
+{
+  vhpiDiagNone          = 0, /* prints nothing */
+  vhpiDiagTimeLoc       = 1, /* prints simulation time and location */
+  vhpiDiagTimeLocCPUMem = 2  /* prints simulation time, location and statistics about CPU and memory usage */
+} vhpiDiagT;
+
+#ifdef  __cplusplus
+}
+#endif
+
+#endif /* VHPI_USER_EXT_H */

cocotb/share/include/vpi_user_ext.h

@@ -0,0 +1,33 @@
+// Copyright cocotb contributors
+// Copyright (c) 2013, 2019 Potential Ventures Ltd
+// Licensed under the Revised BSD License, see LICENSE for details.
+// SPDX-License-Identifier: BSD-3-Clause
+
+/* extensions to vpi_user.h */
+
+#ifndef VPI_USER_EXT_H
+#define VPI_USER_EXT_H
+
+#ifdef  __cplusplus
+extern "C" {
+#endif
+
+/* used by Cadence Xcelium for packed unions */
+#define vpiUnionNet          525
+
+/* used by Cadence Xcelium for Verilog-AMS */
+#define vpiRealNet           526
+#define vpiInterconnectNet   533
+#define vpiInterconnectArray 534
+
+/* arguments for vpiStop or vpiFinish */
+#define vpiDiagNone               0  /* prints nothing */
+#define vpiDiagTimeLoc            1  /* prints simulation time and location */
+#define vpiDiagTimeLocCPUMem      2  /* prints simulation time, location and
+                                        statistics about CPU and memory usage */
+
+#ifdef  __cplusplus
+}
+#endif
+
+#endif /* VPI_USER_EXT_H */

cocotb/share/lib/verilator/verilator.cpp

@@ -0,0 +1,209 @@
+// Copyright cocotb contributors
+// Licensed under the Revised BSD License, see LICENSE for details.
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include <libgen.h>  // basename
+#include <stdio.h>   // stderr, fprintf
+
+#include <memory>  // std::unique_ptr
+#include <string>  // std::string
+
+#include "Vtop.h"
+#include "verilated.h"
+#include "verilated_vpi.h"
+
+#ifndef VM_TRACE_FST
+// emulate new verilator behavior for legacy versions
+#define VM_TRACE_FST 0
+#endif
+
+#if VM_TRACE
+#if VM_TRACE_FST
+#include <verilated_fst_c.h>
+using verilated_trace_t = VerilatedFstC;
+#else
+#include <verilated_vcd_c.h>
+using verilated_trace_t = VerilatedVcdC;
+#endif
+static verilated_trace_t *tfp;
+#endif
+
+static vluint64_t main_time = 0;  // Current simulation time
+
+double sc_time_stamp() {  // Called by $time in Verilog
+    return main_time;     // converts to double, to match
+                          // what SystemC does
+}
+
+extern "C" {
+void vlog_startup_routines_bootstrap(void);
+}
+
+static inline bool settle_value_callbacks() {
+    bool cbs_called, again;
+
+    // Call Value Change callbacks
+    // These can modify signal values so we loop
+    // until there are no more changes
+    cbs_called = again = VerilatedVpi::callValueCbs();
+    while (again) {
+        again = VerilatedVpi::callValueCbs();
+    }
+
+    return cbs_called;
+}
+
+void wrap_up() {
+    VerilatedVpi::callCbs(cbEndOfSimulation);
+
+#if VM_TRACE
+    if (tfp) {
+        delete tfp;
+        tfp = nullptr;
+    }
+#endif
+
+    // VM_COVERAGE is a define which is set if Verilator is
+    // instructed to collect coverage (when compiling the simulation)
+#if VM_COVERAGE
+    VerilatedCov::write();  // Uses +verilator+coverage+file+<filename>,
+                            // defaults to coverage.dat
+#endif
+}
+
+int main(int argc, char **argv) {
+#if VM_TRACE_FST
+    const char *traceFile = "dump.fst";
+#else
+    const char *traceFile = "dump.vcd";
+#endif
+    bool traceOn = false;
+    bool traceFlush = false;
+
+    for (int i = 1; i < argc; i++) {
+        std::string arg = std::string(argv[i]);
+        if (arg == "--trace") {
+#if VM_TRACE
+            traceOn = true;
+#else
+            fprintf(stderr,
+                    "Error: --trace requires the design to be built with trace "
+                    "support\n");
+            return -1;
+#endif
+        } else if (arg == "--trace-flush") {
+            traceFlush = true;
+        } else if (arg == "--trace-file") {
+            if (++i < argc) {
+                traceFile = argv[i];
+            } else {
+                fprintf(stderr, "Error: --trace-file requires a parameter\n");
+                return -1;
+            }
+        } else if (arg == "--help") {
+            fprintf(
+                stderr,
+                "usage: %s [--trace] [--trace-flush] [--trace-file TRACEFILE]\n"
+                "\n"
+                "cocotb + Verilator sim\n"
+                "\n"
+                "options:\n"
+                "  --trace       Enable tracing (VCD or FST)\n"
+                "  --trace-flush Flush trace at each time step (slow)\n"
+                "  --trace-file  Specify the trace file name (%s by "
+                "default)\n",
+                basename(argv[0]), traceFile);
+            return 0;
+        }
+    }
+
+    Verilated::commandArgs(argc, argv);
+#ifdef VERILATOR_SIM_DEBUG
+    Verilated::debug(99);
+#endif
+    std::unique_ptr<Vtop> top(new Vtop(""));
+    Verilated::fatalOnVpiError(false);  // otherwise it will fail on systemtf
+
+#ifdef VERILATOR_SIM_DEBUG
+    Verilated::internalsDump();
+#endif
+
+#if VM_TRACE
+    Verilated::traceEverOn(true);
+    if (traceOn) {
+        tfp = new verilated_trace_t;
+        top->trace(tfp, 99);
+        tfp->open(traceFile);
+    }
+#endif
+
+    vlog_startup_routines_bootstrap();
+    Verilated::addExitCb([](void *) { wrap_up(); }, nullptr);
+    VerilatedVpi::callCbs(cbStartOfSimulation);
+    settle_value_callbacks();
+
+    while (!Verilated::gotFinish()) {
+        do {
+            // We must evaluate whole design until we process all 'events' for
+            // this time step
+            do {
+                top->eval_step();
+                VerilatedVpi::clearEvalNeeded();
+                VerilatedVpi::doInertialPuts();
+                settle_value_callbacks();
+            } while (VerilatedVpi::evalNeeded());
+
+            // Run ReadWrite callback as we are done processing this eval step
+            VerilatedVpi::callCbs(cbReadWriteSynch);
+            VerilatedVpi::doInertialPuts();
+            settle_value_callbacks();
+        } while (VerilatedVpi::evalNeeded());
+
+        top->eval_end_step();
+
+        // Call ReadOnly callbacks
+        VerilatedVpi::callCbs(cbReadOnlySynch);
+
+#if VM_TRACE
+        if (tfp) {
+            tfp->dump(main_time);
+            if (traceFlush) {
+                tfp->flush();
+            }
+        }
+#endif
+        // cocotb controls the clock inputs using cbAfterDelay so
+        // skip ahead to the next registered callback
+        const vluint64_t NO_TOP_EVENTS_PENDING = static_cast<vluint64_t>(~0ULL);
+        vluint64_t next_time_cocotb = VerilatedVpi::cbNextDeadline();
+        vluint64_t next_time_timing =
+            top->eventsPending() ? top->nextTimeSlot() : NO_TOP_EVENTS_PENDING;
+        vluint64_t next_time = std::min(next_time_cocotb, next_time_timing);
+
+        // If there are no more cbAfterDelay callbacks,
+        // the next deadline is max value, so end the simulation now
+        if (next_time == NO_TOP_EVENTS_PENDING) {
+            break;
+        } else {
+            main_time = next_time;
+        }
+
+        // Call registered NextSimTime
+        // It should be called in simulation cycle before everything else
+        // but not on first cycle
+        VerilatedVpi::callCbs(cbNextSimTime);
+        settle_value_callbacks();
+
+        // Call registered timed callbacks (e.g. clock timer)
+        // These are called at the beginning of the time step
+        // before the iterative regions (IEEE 1800-2012 4.4.1)
+        VerilatedVpi::callTimedCbs();
+        settle_value_callbacks();
+    }
+
+    top->final();
+
+    wrap_up();
+
+    return 0;
+}