derek/gem5
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

misc, stdlib: Update documentation to adhere to RST formatting. (#631)

Browse Source 
This PR updates files in `src/python` to adhere to reStructuredText
formatting.
This commit is contained in:
Ivana Mitrovic
2023-12-01 11:43:49 -08:00
committed by GitHub
parent bfd25f5352
commit d96b6cdae7
92 changed files with 1039 additions and 920 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
src/python/m5/SimObject.py
View File

@@ -1322,7 +1322,6 @@ class SimObject(metaclass=MetaSimObject):
The format is the same as that supported by SimObjectCliWrapper.
:param simobj_path: Current state to be in.
:type simobj_path: str
"""
d = self._apply_config_get_dict()
return eval(simobj_path, d)

34
src/python/m5/ext/pystats/abstract_stat.py
View File

@@ -50,15 +50,16 @@ class AbstractStat(SerializableStat):
) -> List["AbstractStat"]:
"""Iterate through all of the children, optionally with a predicate
```
>>> system.children(lambda _name: 'cpu' in name)
[cpu0, cpu1, cpu2]
```
.. code-block::
:param: predicate(str) -> bool: Optional. Each child's name is passed
to this function. If it returns true, then the child is
yielded. Otherwise, the child is skipped.
If not provided then all children are returned.
>>> system.children(lambda _name: 'cpu' in name)
[cpu0, cpu1, cpu2]
:param predicate: Optional. Each child's name is passed to this function.
If it returns ``True``, then the child is yielded.
Otherwise, the child is skipped. If not provided then
all children are returned.
"""
to_return = []
@@ -78,15 +79,18 @@ class AbstractStat(SerializableStat):
"""Find all stats that match the name, recursively through all the
SimStats.
.. code-block::
```
>>> system.find('cpu[0-9]')
[cpu0, cpu1, cpu2]
```
Note: The above will not match `cpu_other`.
>>> system.find('cpu[0-9]')
[cpu0, cpu1, cpu2]
:param: regex: The regular expression used to search. Can be a
precompiled regex or a string in regex format
.. note::
The above will not match ``cpu_other``.
:param regex: The regular expression used to search. Can be a
precompiled regex or a string in regex format.
"""
if isinstance(regex, str):
pattern = re.compile(regex)

26
src/python/m5/ext/pystats/jsonloader.py
View File

@@ -46,17 +46,19 @@ from .statistic import (
class JsonLoader(json.JSONDecoder):
"""
Subclass of JSONDecoder that overrides 'object_hook'. Converts JSON object
Subclass of JSONDecoder that overrides ``object_hook``. Converts JSON object
into a SimStat object.
Usage
-----
```
from m5.ext.pystats.jsonloader import JsonLoader
with open(path) as f:
simstat_object = json.load(f, cls=JsonLoader)
```
.. code-block::
from m5.ext.pystats.jsonloader import JsonLoader
with open(path) as f:
simstat_object = json.load(f, cls=JsonLoader)
"""
def __init__(self):
@@ -99,12 +101,14 @@ def load(json_file: IO) -> SimStat:
Usage
-----
```
import m5.ext.pystats as pystats
with open(path) as f:
pystats.jsonloader.load(f)
```
.. code-block::
import m5.ext.pystats as pystats
with open(path) as f:
pystats.jsonloader.load(f)
"""
simstat_object = json.load(json_file, cls=JsonLoader)

79
src/python/m5/ext/pystats/serializable_stat.py
View File

@@ -44,22 +44,21 @@ class SerializableStat:
Usage
-----
```
import m5.pystats.gem5stats as gem5stats
simstat = gem5stats.get_simstat(root)
print(simstat.dumps())
```
.. code-block::
import m5.pystats.gem5stats as gem5stats
simstat = gem5stats.get_simstat(root)
print(simstat.dumps())
"""
def to_json(self) -> Dict:
"""
Translates the current object into a JSON dictionary.
Returns
-------
Dict
The JSON dictionary.
:returns: The JSON dictionary.
"""
model_dct = {}
@@ -75,15 +74,9 @@ class SerializableStat:
Translate values into a value which can be handled by the Python stdlib
JSON package.
Parameters
----------
value: Any
The value to be translated.
:param value: The value to be translated.
Returns
-------
Union[str,int,float,Dict,List]
A value which can be handled by the Python stdlib JSON package.
:returns: A value which can be handled by the Python stdlib JSON package.
"""
if isinstance(value, SerializableStat):
@@ -102,31 +95,26 @@ class SerializableStat:
def dumps(self, **kwargs) -> str:
"""
This function mirrors the Python stdlib JSON module method
`json.dumps`. It is used to obtain the gem5 statistics output to a
``json.dumps``. It is used to obtain the gem5 statistics output to a
JSON string.
Parameters
----------
root: Root
The root of the simulation.
:param root: The root of the simulation.
kwargs: Dict[str, Any]
Additional parameters to be passed to the `json.dumps` method.
:param kwargs: Additional parameters to be passed to the ``json.dumps`` method.
Returns
-------
str
A string of the gem5 Statistics in a JSON format.
:returns: A string of the gem5 Statistics in a JSON format.
Usage Example
-------------
```
import m5.pystats.gem5stats as gem5stats
simstat = gem5stats.get_simstat(root)
print(simstat.dumps(indent=6))
```
.. code-block::
import m5.pystats.gem5stats as gem5stats
simstat = gem5stats.get_simstat(root)
print(simstat.dumps(indent=6))
The above will print the simulation statistic JSON string. The
indentation will be 6 (by default the indentation is 4).
@@ -141,27 +129,24 @@ class SerializableStat:
def dump(self, fp: IO[str], **kwargs) -> None:
"""
This function mirrors the Python stdlib JSON module method
`json.dump`. The root of the simulation is passed, and the JSON is
``json.dump``. The root of the simulation is passed, and the JSON is
output to the specified.
:param fp: The Text IO stream to output the JSON to.
Parameters
----------
fp: IO[str]
The Text IO stream to output the JSON to.
**kwargs:
Additional parameters to be passed to the ``json.dump`` method.
:param kwargs: Additional parameters to be passed to the ``json.dump`` method.
Usage
-----
```
import m5.pystats.gem5stats as gem5stats
simstat = gem5stats.get_simstat(root)
with open("test.json") as f:
simstat.dump(fp=f, indent=6)
```
.. code-block::
import m5.pystats.gem5stats as gem5stats
simstat = gem5stats.get_simstat(root)
with open("test.json") as f:
simstat.dump(fp=f, indent=6)
The above will dump the json output to the 'test.json' file. The
indentation will be of 6 (by default the indentation is 4).

12
src/python/m5/ext/pystats/statistic.py
View File

@@ -116,10 +116,7 @@ class BaseScalarVector(Statistic):
"""
Returns the mean of the value vector.
Returns
-------
float
The mean value across all bins.
:returns: The mean value across all bins.
"""
assert self.value != None
assert isinstance(self.value, List)
@@ -132,10 +129,7 @@ class BaseScalarVector(Statistic):
"""
Returns the count across all the bins.
Returns
-------
float
The sum of all bin values.
:returns: The sum of all bin values.
"""
assert self.value != None
return sum(self.value)
@@ -146,7 +140,7 @@ class Distribution(BaseScalarVector):
A statistic type that stores information relating to distributions. Each
distribution has a number of bins (>=1)
between this range. The values correspond to the value of each bin.
E.g., value[3]` is the value of the 4th bin.
E.g., ``value[3]`` is the value of the 4th bin.
It is assumed each bucket is of equal size.
"""

26
src/python/m5/simulate.py
View File

@@ -244,15 +244,15 @@ def scheduleTickExitFromCurrent(
ticks: int, exit_string: str = "Tick exit reached"
) -> None:
"""Schedules a tick exit event from the current tick. I.e., if ticks == 100
then an exit event will be scheduled at tick `curTick() + 100`.
then an exit event will be scheduled at tick ``curTick() + 100``.
The default `exit_string` value is used by the stdlib Simulator module to
declare this exit event as `ExitEvent.SCHEDULED_TICK`.
The default ``exit_string`` value is used by the stdlib Simulator module to
declare this exit event as ``ExitEvent.SCHEDULED_TICK``.
:param ticks: The simulation ticks, from `curTick()` to schedule the exit
event.
:param ticks: The simulation ticks, from ``curTick()`` to schedule the exit
event.
:param exit_string: The exit string to return when the exit event is
triggered.
triggered.
"""
scheduleTickExitAbsolute(tick=ticks + curTick(), exit_string=exit_string)
@@ -263,12 +263,12 @@ def scheduleTickExitAbsolute(
"""Schedules a tick exit event using absolute ticks. I.e., if tick == 100
then an exit event will be scheduled at tick 100.
The default `exit_string` value is used by the stdlib Simulator module to
declare this exit event as `ExitEvent.SCHEDULED_TICK`.
The default ``exit_string`` value is used by the stdlib Simulator module to
declare this exit event as ``ExitEvent.SCHEDULED_TICK``.
:param tick: The absolute simulation tick to schedule the exit event.
:param exit_string: The exit string to return when the exit event is
triggered.
triggered.
"""
if tick <= curTick():
warn("Tick exit scheduled for the past. This will not be triggered.")
@@ -351,9 +351,11 @@ def _changeMemoryMode(system, mode):
def switchCpus(system, cpuList, verbose=True):
"""Switch CPUs in a system.
Note: This method may switch the memory mode of the system if that
is required by the CPUs. It may also flush all caches in the
system.
.. note::
This method may switch the memory mode of the system if that
is required by the CPUs. It may also flush all caches in the
system.
Arguments:
system -- Simulated system.

70
src/python/m5/stats/gem5stats.py
View File

@@ -48,7 +48,7 @@ import _m5.stats
class JsonOutputVistor:
"""
This is a helper vistor class used to include a JSON output via the stats
API (`src/python/m5/stats/__init__.py`).
API (``src/python/m5/stats/__init__.py``).
"""
file: str
@@ -56,14 +56,9 @@ class JsonOutputVistor:
def __init__(self, file: str, **kwargs):
"""
Parameters
----------
:param file: The output file location in which the JSON will be dumped.
file: str
The output file location in which the JSON will be dumped.
kwargs: Dict[str, Any]
Additional parameters to be passed to the `json.dumps` method.
:param kwargs: Additional parameters to be passed to the ``json.dumps`` method.
"""
self.file = file
@@ -74,14 +69,13 @@ class JsonOutputVistor:
Dumps the stats of a simulation root (or list of roots) to the output
JSON file specified in the JsonOutput constructor.
WARNING: This dump assumes the statistics have already been prepared
for the target root.
.. warning::
Parameters
----------
This dump assumes the statistics have already been prepared
for the target root.
roots: Union[List[Root], Root]]
The Root, or List of roots, whose stats are are to be dumped JSON.
:param roots: The Root, or List of roots, whose stats are are to be dumped JSON.
"""
with open(self.file, "w") as fp:
@@ -93,20 +87,14 @@ def get_stats_group(group: _m5.stats.Group) -> Group:
"""
Translates a gem5 Group object into a Python stats Group object. A Python
statistic Group object is a dictionary of labeled Statistic objects. Any
gem5 object passed to this will have its `getStats()` and `getStatGroups`
gem5 object passed to this will have its ``getStats()`` and ``getStatGroups``
function called, and all the stats translated (inclusive of the stats
further down the hierarchy).
Parameters
----------
group: _m5.stats.Group
The gem5 _m5.stats.Group object to be translated to be a Python stats
Group object. Typically this will be a gem5 SimObject.
:param group: The gem5 _m5.stats.Group object to be translated to be a Python
stats Group object. Typically this will be a gem5 SimObject.
Returns
-------
Group
The stats group object translated from the input gem5 object.
:returns: The stats group object translated from the input gem5 object.
"""
stats_dict = {}
@@ -127,16 +115,10 @@ def __get_statistic(statistic: _m5.stats.Info) -> Optional[Statistic]:
Translates a _m5.stats.Info object into a Statistic object, to process
statistics at the Python level.
Parameters
----------
statistic: Info
The Info object to be translated to a Statistic object.
:param statistic: The Info object to be translated to a Statistic object.
Returns
-------
Optional[Statistic]
The Statistic object of the Info object. Returns None if Info object
cannot be translated.
:returns: The Statistic object of the Info object. Returns ``None`` if
Info object cannot be translated.
"""
assert isinstance(statistic, _m5.stats.Info)
@@ -250,22 +232,16 @@ def get_simstat(
SimStat object will contain all the stats for all the SimObjects contained
within the "root", inclusive of the "root" SimObject/SimObjects.
Parameters
----------
root: Union[SimObject, List[SimObject]]
A SimObject, or list of SimObjects, of the simulation for translation
into a SimStat object. Typically this is the simulation's Root
SimObject as this will obtain the entirety of a run's statistics in a
single SimStat object.
:param root: A SimObject, or list of SimObjects, of the simulation for
translation into a SimStat object. Typically this is the
simulation's Root SimObject as this will obtain the entirety
of a run's statistics in a single SimStat object.
prepare_stats: bool
Dictates whether the stats are to be prepared prior to creating the
SimStat object. By default this is 'True'.
:param prepare_stats: Dictates whether the stats are to be prepared prior
to creating the SimStat object. By default this is
``True``.
Returns
-------
SimStat
The SimStat Object of the current simulation.
:Returns: The SimStat Object of the current simulation.
"""
stats_map = {}

2
src/python/m5/util/attrdict.py
View File

@@ -69,7 +69,7 @@ class multiattrdict(attrdict):
class optiondict(attrdict):
"""Modify attrdict so that a missing attribute just returns None"""
"""Modify attrdict so that a missing attribute just returns ``None``."""
def __getattr__(self, attr):
try: