Jason Lowe-Power has uploaded this change for review. (
https://gem5-review.googlesource.com/c/public/gem5/+/31756 )
Change subject: base,sim,python: Add core python API
......................................................................
base,sim,python: Add core python API
Add documenation to the _m5.core library and add tags to all of the
functions used in this Python API.
When executing help(_m5.core) in Python, there is now a helpful message
printed.
This and following changes are setting up the Python interface for
larger updates. The first step is to improve the documentation.
Issue-on: https://gem5.atlassian.net/browse/GEM5-647
Change-Id: I0f290eb2b689020e53cf4393ec62a9ba1725ddc9
Signed-off-by: Jason Lowe-Power <ja...@lowepower.com>
---
M src/base/logging.hh
M src/base/socket.hh
M src/base/types.hh
M src/python/pybind11/core.cc
M src/sim/core.cc
M src/sim/core.hh
M src/sim/init.cc
M src/sim/serialize.hh
8 files changed, 114 insertions(+), 28 deletions(-)
diff --git a/src/base/logging.hh b/src/base/logging.hh
index 0c4265b..d97eeac 100644
--- a/src/base/logging.hh
+++ b/src/base/logging.hh
@@ -64,6 +64,9 @@
NUM_LOG_LEVELS,
};
+ /*
+ * @group api_python_core
+ */
static void
setLevel(LogLevel ll)
{
diff --git a/src/base/socket.hh b/src/base/socket.hh
index 74a379b..eae1faa 100644
--- a/src/base/socket.hh
+++ b/src/base/socket.hh
@@ -38,10 +38,15 @@
static bool bindToLoopback;
public:
+ /**
+ * @ingroup api_python_core
+ * @{
+ */
static void disableAll();
static bool allDisabled();
static void loopbackOnly();
+ /**@}*/ //end of api_python_core
protected:
bool listening;
diff --git a/src/base/types.hh b/src/base/types.hh
index 4f606cd..9e93d34 100644
--- a/src/base/types.hh
+++ b/src/base/types.hh
@@ -88,13 +88,17 @@
public:
- /** Explicit constructor assigning a value. */
+ /** Explicit constructor assigning a value.
+ * @ingroup api_python_core
+ */
explicit constexpr Cycles(uint64_t _c) : c(_c) { }
/** Default constructor for parameter classes. */
Cycles() : c(0) { }
- /** Converting back to the value type. */
+ /** Converting back to the value type.
+ * @ingroup api_python_core
+ */
constexpr operator uint64_t() const { return c; }
/** Prefix increment operator. */
@@ -113,9 +117,15 @@
constexpr bool operator>(const Cycles& cc) const
{ return c > cc.c; }
+ /**
+ * @ingroup api_python_core
+ */
constexpr Cycles operator +(const Cycles& b) const
{ return Cycles(c + b.c); }
+ /**
+ * @ingroup api_python_core
+ */
constexpr Cycles operator -(const Cycles& b) const
{
return c >= b.c ? Cycles(c - b.c) :
diff --git a/src/python/pybind11/core.cc b/src/python/pybind11/core.cc
index 8655d73..9dd26d9 100644
--- a/src/python/pybind11/core.cc
+++ b/src/python/pybind11/core.cc
@@ -210,11 +210,12 @@
void
pybind_init_core(py::module &m_native)
{
- py::module m_core = m_native.def_submodule("core");
+ py::module m_core = m_native.def_submodule("core",
+ "Contains gem5 core types and functions.");
py::class_<Cycles>(m_core, "Cycles")
- .def(py::init<>())
- .def(py::init<uint64_t>())
+ .def(py::init<>(), "Initializes the cycles to 0.")
+ .def(py::init<uint64_t>(), "Initializes the cycles to the given
value")
.def("__int__", &Cycles::operator uint64_t)
.def("__add__", &Cycles::operator+)
.def("__sub__", &Cycles::operator-)
@@ -241,22 +242,51 @@
;
m_core
- .def("setLogLevel", &Logger::setLevel)
- .def("setOutputDir", &setOutputDir)
- .def("doExitCleanup", &doExitCleanup)
+ .def("setLogLevel", &Logger::setLevel,
+ "Sets the log level to dump all logs at this level and above.")
+ .def("setOutputDir", &setOutputDir,
+ "Sets the directory for gem5's output files.\n"
+ "\n"
+ "These files include config.ini, stats.txt, etc.")
+ .def("doExitCleanup", &doExitCleanup,
+ "Do C++ simulator exit processing. Calls all exit callbacks.")
- .def("disableAllListeners", &ListenSocket::disableAll)
- .def("listenersDisabled", &ListenSocket::allDisabled)
- .def("listenersLoopbackOnly", &ListenSocket::loopbackOnly)
- .def("seedRandom", [](uint64_t seed) { random_mt.init(seed); })
+ .def("disableAllListeners", &ListenSocket::disableAll,
+ "Disable all socket listeners (e.g., gdb, term, etc.).")
+ .def("listenersDisabled", &ListenSocket::allDisabled,
+ "Returns true if all listeners are disabled.")
+ .def("listenersLoopbackOnly", &ListenSocket::loopbackOnly,
+ "Binds all listeners to the loopback device.")
+ .def("seedRandom", [](uint64_t seed) { random_mt.init(seed); },
+ "Sets gem5's random seed.\n"
+ "\n"
+ "There may be unexpected behavior when using dist-gem5. See "
+ "src/dev/net/dist_iface.cc for details.")
- .def("fixClockFrequency", &fixClockFrequency)
- .def("clockFrequencyFixed", &clockFrequencyFixed)
+ .def("fixClockFrequency", &fixClockFrequency,
+ "Finalizes the global tick frequency.\n"
+ "\n"
+ "Can only be called once. If called a second time, the
frequency "
+ "doesn't change.")
+ .def("clockFrequencyFixed", &clockFrequencyFixed,
+ "Returns true if the global tick frequency has been fixed.")
- .def("setClockFrequency", &setClockFrequency)
- .def("getClockFrequency", &getClockFrequency)
- .def("curTick", curTick)
+ .def("setClockFrequency", &setClockFrequency,
+ "Sets the global tick frequency.\n"
+ "\n"
+ "Sets the internal tick frequency to the specified number of "
+ "ticks per second.\n"
+ "Note: The global clock frequency cannot be changed after it
is "
+ "\"fixed.\" A panic will occur if this function is called
after "
+ "`fixClockFrequency`.")
+ .def("getClockFrequency", &getClockFrequency,
+ "Returns the number of ticks per second for gem5's internal "
+ "simulation clock.")
+ .def("curTick", curTick,
+ "Returns the current tick since the beginning of simulation.\n"
+ "\n"
+ "This is gem'5 universal simulation clock.")
;
/* TODO: These should be read-only */
@@ -274,12 +304,27 @@
* Serialization helpers
*/
m_core
- .def("serializeAll", &Serializable::serializeAll)
- .def("unserializeGlobals", &Serializable::unserializeGlobals)
+ .def("serializeAll", &Serializable::serializeAll,
+ "Creates a checkpoint in the given checkpoint directory.\n"
+ "\n"
+ "Finds all globals and all SimObjects in the simulation and
saves "
+ "their current state to the checkpoint directory specified.
This "
+ "checkpoint can then be loaded in a new simulation.")
+ .def("unserializeGlobals", &Serializable::unserializeGlobals,
+ "Given a checkpoint file, unserialize the \"globals\"\n"
+ "\n"
+ "The globals in a checkpoint include the current simulation
tick "
+ "and the version of the checkpoint. There are loud warnings
if "
+ "you try to run this function with a checkpoint scheme
version "
+ "which does not match.")
.def("getCheckpoint", [](const std::string &cpt_dir) {
- return new CheckpointIn(cpt_dir, pybindSimObjectResolver);
- })
-
+ return new CheckpointIn(cpt_dir, pybindSimObjectResolver);
+ },
+ "Returns a `CheckpointIn` object given a directory containing
a "
+ "checkpoint\n"
+ "\n"
+ "This `CheckpointIn` object can then be used to load every
object "
+ "in the *current* simulation context.")
;
diff --git a/src/sim/core.cc b/src/sim/core.cc
index 18c6985..c82cd05 100644
--- a/src/sim/core.cc
+++ b/src/sim/core.cc
@@ -142,10 +142,6 @@
exitCallbacks().add(callback);
}
-/**
- * Do C++ simulator exit processing. Exported to Python to be invoked
- * when simulator terminates via Python's atexit mechanism.
- */
void
doExitCleanup()
{
diff --git a/src/sim/core.hh b/src/sim/core.hh
index 48b7096..8545f9a 100644
--- a/src/sim/core.hh
+++ b/src/sim/core.hh
@@ -40,7 +40,9 @@
#include "base/types.hh"
#include "sim/eventq.hh"
-/// The universal simulation clock.
+/** The universal simulation clock.
+ * @ingroup api_python_core
+ */
inline Tick curTick() { return _curEventQueue->getCurTick(); }
/// These are variables that are set based on the simulator frequency
@@ -87,16 +89,30 @@
} // namespace SimClock
/** @} */
+/**
+ * @ingroup api_python_core
+ * @{
+ */
void fixClockFrequency();
bool clockFrequencyFixed();
void setClockFrequency(Tick ticksPerSecond);
Tick getClockFrequency(); // Ticks per second.
+/**@}*/ // end api_python_core
+/**
+ * @ingroup api_python_core
+ */
void setOutputDir(const std::string &dir);
class Callback;
void registerExitCallback(Callback *callback);
+
+/**
+ * Do C++ simulator exit processing. Exported to Python to be invoked
+ * when simulator terminates via Python's atexit mechanism.
+ * @ingroup api_python_core
+ */
void doExitCleanup();
#endif /* __SIM_CORE_HH__ */
diff --git a/src/sim/init.cc b/src/sim/init.cc
index 7b2e7e4..3c8fea4 100644
--- a/src/sim/init.cc
+++ b/src/sim/init.cc
@@ -198,7 +198,13 @@
{
std::list<EmbeddedPyBind *> pending;
- py::module m_m5 = py::module("_m5");
+ py::module m_m5 = py::module("_m5",
+ "Internal gem5 C++ components exposed to Python.\n"
+ "\n"
+ "This module should only be used by internal gem5 Python
libraries. "
+ "The APIs and modules contained in _m5 could change at any time. "
+ "The name is _m5 to keep backwards compatibility with all scripts "
+ "from before the m5->gem5 name change.");
m_m5.attr("__package__") = py::cast("_m5");
pybind_init_core(m_m5);
diff --git a/src/sim/serialize.hh b/src/sim/serialize.hh
index 1f31dd2..1dc3756 100644
--- a/src/sim/serialize.hh
+++ b/src/sim/serialize.hh
@@ -75,6 +75,9 @@
const std::string _cptDir;
public:
+ /**
+ * @ingroup api_python_core
+ */
CheckpointIn(const std::string &cpt_dir, SimObjectResolver &resolver);
~CheckpointIn();
@@ -298,11 +301,13 @@
/**
* @ingroup api_serialize
+ * @ingroup api_python_core
*/
static void serializeAll(const std::string &cpt_dir);
/**
* @ingroup api_serialize
+ * @ingroup api_python_core
*/
static void unserializeGlobals(CheckpointIn &cp);
--
To view, visit https://gem5-review.googlesource.com/c/public/gem5/+/31756
To unsubscribe, or for help writing mail filters, visit
https://gem5-review.googlesource.com/settings
Gerrit-Project: public/gem5
Gerrit-Branch: develop
Gerrit-Change-Id: I0f290eb2b689020e53cf4393ec62a9ba1725ddc9
Gerrit-Change-Number: 31756
Gerrit-PatchSet: 1
Gerrit-Owner: Jason Lowe-Power <power...@gmail.com>
Gerrit-MessageType: newchange
_______________________________________________
gem5-dev mailing list -- gem5-dev@gem5.org
To unsubscribe send an email to gem5-dev-le...@gem5.org
%(web_page_url)slistinfo%(cgiext)s/%(_internal_name)s
