cocotb 1.9.2__cp312-cp312-win_amd64.whl → 2.0.0b1__cp312-cp312-win_amd64.whl

cocotb/share/include/gpi_logging.h

@@ -1,44 +1,23 @@
-/******************************************************************************
- * Copyright (c) 2013 Potential Ventures Ltd
- * Copyright (c) 2013 SolarFlare Communications Inc
- * All rights reserved.
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions are met:
- *    * Redistributions of source code must retain the above copyright
- *      notice, this list of conditions and the following disclaimer.
- *    * 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.
- *    * Neither the name of Potential Ventures Ltd,
- *       SolarFlare Communications Inc nor the
- *      names of its contributors may be used to endorse or promote products
- *      derived from this software without specific prior written permission.
- *
- * 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 POTENTIAL VENTURES LTD 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.
- ******************************************************************************/
+// 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 <exports.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
 
-#include <cstdarg>
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -50,158 +29,258 @@ extern "C" {
  *  Python logging module. Implementers of custom loggers should emit human
  *  readable level names for these value, but may support other values.
  */
-enum gpi_log_levels {
-    GPITrace = 5,   ///< Prints `TRACE` by default. Information about execution
-                    ///< of simulator callbacks and Python / simulator contexts
-    GPIDebug = 10,  ///< Prints `DEBUG` by default. Verbose information, useful
-                    ///< for debugging
-    GPIInfo = 20,  ///< Prints `INFO` by default. Information about major events
-                   ///< in the current program
-    GPIWarning = 30,  ///< Prints `WARN` by default. Encountered a recoverable
-                      ///< bug, or information about surprising behavior
-    GPIError = 40,    ///< Prints `ERROR` by default. An unrecoverable error
-    GPICritical = 50  ///< Prints `CRITICAL` by default. An unrecoverable error,
-                      ///< to be followed by immediate simulator shutdown
+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.
 };
 
-/** Logs a message at the given log level using the current log handler.
-    Automatically populates arguments using information in the called context.
-    @param level The level at which to log the message
- */
+#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__);
+    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_(GPITrace, __VA_ARGS__)
+ 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_(GPIDebug, __VA_ARGS__)
+ 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_(GPIInfo, __VA_ARGS__);
+ 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_(GPIWarning, __VA_ARGS__);
+ 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_(GPIError, __VA_ARGS__);
+ 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.
+ 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
  */
-#define LOG_CRITICAL(...) LOG_(GPICritical, __VA_ARGS__);
-
-/** Type of a log 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 void(gpi_log_handler_type)(void *userdata, const char *name, int level,
-                                   const char *pathname, const char *funcname,
-                                   long lineno, const char *msg, va_list args);
+typedef bool (*gpi_log_filter_ftype)(void *userdata, const char *logger,
+                                     int level);
 
-/** Log a message using the currently registered log handler.
-    User is expected to populate all arguments to 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 ...       Additional arguments; formatted and inserted in message
-                     according to format specifier in msg argument
+/** 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*.
  */
-GPILOG_EXPORT void gpi_log(const char *name, int level, const char *pathname,
-                           const char *funcname, long lineno, const char *msg,
-                           ...);
+typedef bool (*gpi_log_set_level_ftype)(void *userdata, const char *logger,
+                                        int level);
 
 /** Log a message using the currently registered log handler.
-    User is expected to populate all arguments to 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
+ *
+ * @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
  */
-GPILOG_EXPORT void gpi_vlog(const char *name, int level, const char *pathname,
+#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,
-                            va_list args);
+                            ...);
+
+/** 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. If no custom logger
-                    is registered this will be `NULL`.
-    @param userdata Location to return log handler userdata
+ * @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_type **handler,
+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   Handler function to call when the GPI logs a message
-    @param userdata  Data to pass to the handler function when logging a message
+ * @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_type *handler,
+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
- */
+/** Clear the current custom log handler and use native logger. */
 GPILOG_EXPORT void gpi_clear_log_handler(void);
 
-/** Log a message using the native log handler.
-    User is expected to populate all arguments to 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 ...       Additional arguments; formatted and inserted in message
-                     according to format specifier in msg argument
- */
-GPILOG_EXPORT void gpi_native_logger_log(const char *name, int level,
-                                         const char *pathname,
-                                         const char *funcname, long lineno,
-                                         const char *msg, ...);
+/*******************************************************************************
+ * GPI Native Logger
+ *******************************************************************************/
 
 /** Log a message using the native log handler.
-    User is expected to populate all arguments to 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
+ * 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
  */
-GPILOG_EXPORT void gpi_native_logger_vlog(const char *name, int level,
+#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, va_list args);
+                                          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
+ *
+ * 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);
 

cocotb/share/include/py_gpi_logging.h

@@ -5,7 +5,10 @@
 #ifndef PY_GPI_LOGGING_H
 #define PY_GPI_LOGGING_H
 
-#include <exports.h>
+#include <Python.h>
+
+#include "exports.h"
+
 #ifdef PYGPILOG_EXPORTS
 #define PYGPILOG_EXPORT COCOTB_EXPORT
 #else
@@ -16,13 +19,13 @@
 extern "C" {
 #endif
 
-PYGPILOG_EXPORT void py_gpi_logger_set_level(int level);
-
 PYGPILOG_EXPORT void py_gpi_logger_initialize(PyObject* handler,
-                                              PyObject* filter);
+                                              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

cocotb/share/include/vpi_user_ext.h

@@ -1,29 +1,7 @@
-/******************************************************************************
-* Copyright (c) 2013, 2019 Potential Ventures Ltd
-* All rights reserved.
-*
-* Redistribution and use in source and binary forms, with or without
-* modification, are permitted provided that the following conditions are met:
-*    * Redistributions of source code must retain the above copyright
-*      notice, this list of conditions and the following disclaimer.
-*    * 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.
-*    * Neither the name of Potential Ventures Ltd
-*      names of its contributors may be used to endorse or promote products
-*      derived from this software without specific prior written permission.
-*
-* 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 POTENTIAL VENTURES LTD 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.
-******************************************************************************/
+// 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 */