| Name | geopmdpy JSON |
| Version |
3.0.1
JSON |
| download |
| home_page | |
| Summary | GEOPM - Global Extensible Open Power Manager Daemon |
| upload_time | 2023-12-07 17:14:42 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | Copyright (c) 2015 - 2023, Intel Corporation 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 Intel Corporation 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 THE COPYRIGHT OWNER OR CONTRIBUTORS 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 LOG OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
service
hardware
telemetry
configuration
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
GEOPM Service
=============
Features
--------
Linux Integration
~~~~~~~~~~~~~~~~~
The Linux Systemd Service is integrated with a DBus interface, enabling
user-level access to hardware features on heterogeneous systems.
Hardware Telemetry
~~~~~~~~~~~~~~~~~~
Use a vendor-agnostic interface to read telemetry from hardware components on
heterogeneous systems.
Hardware Configuration
~~~~~~~~~~~~~~~~~~~~~~
User-friendly vendor-agnostic interface for configuring hardware component
device settings on heterogeneous systems.
Quality of Service
~~~~~~~~~~~~~~~~~~
The GEOPM Service reverts any changes made to hardware configurations once
the client's Linux process session concludes.
Security
~~~~~~~~
Linux system administrators have complete control over managing fine-grained
access permissions for capabilities exposed by the GEOPM Service.
Performance
~~~~~~~~~~~
A DBus interface can be utilized for the creation of a batch server. The
server provides a low-latency interface with a single permissions validation
when the server is created.
Extensibility
~~~~~~~~~~~~~
GEOPM Service supports extensibility for heterogeneous environments through
the C++ plugin infrastructure called IOGroups.
Overview
--------
The GEOPM Service provides an interface at the user level, allowing users to
read telemetry and configure heterogeneous hardware platforms. Linux system
administrators can manage the permissions for user access to telemetry and
configuration at very detailed level.
The GEOPM Service DBus interface is how clients interact with the service.
Access to the DBus interfaces can be gained from the command line or
programmatically with library interfaces for C, C++, and Python.
The service supports multiple simultaneous client sessions for making
measurements, however only clients from within a single Linux process session
are given write permission to configure hardware control values at any one
time. Upon termination of a client's process session leader, the GEOPM Service
restores all hardware settings to their original state before the first
client's write request.
For more information about the Linux session leader process, please consult the
`setsid(2) <https://man7.org/linux/man-pages/man2/setsid.2.html>`_ manual.
*
`Overview slides <https://geopm.github.io/pdf/geopm-service.pdf>`_
Architecture
------------
.. image:: https://geopm.github.io/images/geopm-service-diagram.svg
:target: https://geopm.github.io/pdf/geopm-service-diagram.pdf
:alt:
The architectural diagram shows the relationship between IOGroups and the GEOPM
Service. IOGroups are the C++ classes that abstract hardware interfaces.
IOGroups provide a plugin mechanism to extend GEOPM's functionality.
The PlatformIO interface is a container for all IOGroups and is the main
interface for users who interact with the hardware through the GEOPM Service.
The PlatformIO interface can be accessed through language bindings with Python,
C, and C++ as well as command line tools such as ``geopmread`` and
``geopmwrite``. The GEOPM DBus interface, ``io.github.geopm``, provides a
secure gateway to privileged PlatformIO features. The ``geopmaccess`` command line
tool is used by the administrator to enable user level access to any subset of
the privileged PlatformIO features.
Status
------
The GEOPM systemd service introduced in version 2.0 is fully tested and is now
ready for production.
Signals and Controls
--------------------
Each signal and control in GEOPM has a unique name and a hardware domain. The
signals and controls available on your system can be discovered with the
``geopmaccess`` command line tool. The description includes all the necessary
information for end users and system administrators to understand what is
enabled when granting access to a signal or control.
Access Management
-----------------
System administrators configure the access to signals and controls through the
GEOPM Service. The administrator maintains an access list that applies to all
users of the system. Special Unix groups can have enhanced access. The default
lists are stored in:
.. code-block::
/etc/geopm/0.DEFAULT_ACCESS/allowed_signals
/etc/geopm/0.DEFAULT_ACCESS/allowed_controls
Each Unix group name ``<GROUP>`` that has extended permissions can
maintain one or both of the files
.. code-block::
/etc/geopm/<GROUP>/allowed_signals
/etc/geopm/<GROUP>/allowed_controls
.. note::
Before GEOPM 3.0, service configuration files were stored in
``/etc/geopm-service``. Since version 3.0, they are stored in
``/etc/geopm``. Version 3.0 ignores the old file location if the new
location exists. If the service uses a configuration from the old location,
then a deprecation warning is emitted.
Any missing files are inferred to be empty lists, including the default access
files. A signal or control will not be available to non-root users through the
GEOPM Service until a system administrator enables access through these allow
lists. It is recommended that all manipulation of these files should be done
through the GEOPM Service with the ``geopmaccess`` command line tool.
All control settings can be read by requesting the signal with the same name.
Whenever a control name is added to the access list for writing, the
administrator implicitly grants read access to the control setting as well.
Opening a Session
-----------------
Each time a client process opens a session with the GEOPM Service, a PlatformIO
object is created with libgeopmd. This session starts in read-only mode. Calls
to the DBus APIs that modify control values convert the session into write mode.
The session retains write access until it ends. Calls into the DBus APIs that
modify control values:
.. code-block::
io.github.geopm.PlatformWriteControl
io.github.geopm.PlatformPushControl
convert the session into write mode. Only one write mode session is
allowed at any time. The request will fail if a client attempts to
begin a write session while another client has one open.
When a session is converted to write mode, all controls that the
service is configured to support are recorded to a save directory in:
.. code-block::
/run/geopm/SAVE_FILES
When a write mode session ends, all of these saved controls are
restored to the value they had when the session was converted,
regardless of whether or not they were adjusted during the session
through the service.
In addition to saving the state of controls, the GEOPM Service will
also lock access to controls for any other client until the
controlling session ends. When the controlling session ends the saved
state is used to restore the values for all controls supported by the
GEOPM Service to the values they had prior to enabling the client to
modify a control. The controlling session may end by an explicit
D-Bus call by the client, or when the process that initiated the
client session ends. The GEOPM Service will poll procfs for the
process ID.
Batch Server
------------
The GEOPM Service provides the implementation for the ServiceIOGroup
which accesses this implementation through the DBus interface. When a
user program calls ``read_signal()`` or ``write_control()`` on a
PlatformIO object provided by libgeopmd and the only
IOGroup that provides the signal or control requested is the
ServiceIOGroup, then each request goes through the slow DBus
interface. When a client process uses the ServiceIOGroup for batch
operations a separate batch server process is created through the DBus
interface. The implementations for ``push_signal()`` and
``push_control()`` are used to configure the stack of signals and
controls that will be enabled by the batch server. This batch server
interacts more directly with the client process to provide low latency
support for the ``read_batch()`` and ``write_batch()`` interfaces of the
ServiceIOGroup.
The batch server is configured to allow access to exactly the signals
and controls that were pushed onto the stack for the ServiceIOGroup
prior to the first ``read_batch()`` or ``write_batch()`` call.
Through the DBus implementation, the GEOPM Service verifies that the
client user has appropriate permissions for the requested signals and
controls. When the first call to ``read_batch()`` or
``write_batch()`` is made to user's PlatformIO object, the geopmd
process forks the batch server process and no more updates can be made
to the configured requests. The batch server uses inter-process
shared memory and FIFO special files to enable fast access to the
configured stack of GEOPM signals and controls.
To implement the ``read_batch()`` method, the ServiceIOGroup writes a
character to a FIFO to notify the batch server that it would like the
configured GEOPM signals to be updated in shared memory. The client
process then waits on a FIFO for a message from the server that the
request is ready. The batch server proceeds to read all GEOPM signals
that are supported by the client's ServiceIOGroup using the batch
server's instance of the PlatformIO object. GEOPM signals are copied
into the shared memory buffer and when the buffer is ready, a
character is written into the FIFO that the client process is waiting
on.
To implement the ``write_batch()`` method, the client process's
ServiceIOGroup prepares the shared memory buffer with all control
settings that the batch server is supporting. The client then writes
a character into a FIFO to notify the batch server that it would like
the configured GEOPM controls to be written. The client process then
waits on a FIFO for a message from the server that the controls have
been written. The batch server proceeds to read the clients settings
from the shared memory buffer and writes the values through the server
process's PlatformIO instance. When the write has completed, a
character is written into the FIFO that the client process is waiting
on.
Raw data
{
"_id": null,
"home_page": "",
"name": "geopmdpy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "Christopher Cantalupo <christopher.m.cantalupo@intel.com>, Brad Geltz <brad.geltz@intel.com>",
"keywords": "service,hardware,telemetry,configuration",
"author": "",
"author_email": "Christopher Cantalupo <christopher.m.cantalupo@intel.com>, Brad Geltz <brad.geltz@intel.com>",
"download_url": "https://files.pythonhosted.org/packages/65/6c/f79f1f86630658ce6ee97fbae8eee421d37fa6ae97a4e68f96f5561faf82/geopmdpy-3.0.1.tar.gz",
"platform": null,
"description": "GEOPM Service\n=============\n\nFeatures\n--------\n\nLinux Integration\n~~~~~~~~~~~~~~~~~\n The Linux Systemd Service is integrated with a DBus interface, enabling\n user-level access to hardware features on heterogeneous systems.\n\n\nHardware Telemetry\n~~~~~~~~~~~~~~~~~~\n Use a vendor-agnostic interface to read telemetry from hardware components on\n heterogeneous systems.\n\n\nHardware Configuration\n~~~~~~~~~~~~~~~~~~~~~~\n User-friendly vendor-agnostic interface for configuring hardware component\n device settings on heterogeneous systems.\n\n\nQuality of Service\n~~~~~~~~~~~~~~~~~~\n The GEOPM Service reverts any changes made to hardware configurations once\n the client's Linux process session concludes.\n\n\nSecurity\n~~~~~~~~\n Linux system administrators have complete control over managing fine-grained\n access permissions for capabilities exposed by the GEOPM Service.\n\n\nPerformance\n~~~~~~~~~~~\n A DBus interface can be utilized for the creation of a batch server. The\n server provides a low-latency interface with a single permissions validation\n when the server is created.\n\n\nExtensibility\n~~~~~~~~~~~~~\n GEOPM Service supports extensibility for heterogeneous environments through\n the C++ plugin infrastructure called IOGroups.\n\n\nOverview\n--------\n\nThe GEOPM Service provides an interface at the user level, allowing users to\nread telemetry and configure heterogeneous hardware platforms. Linux system\nadministrators can manage the permissions for user access to telemetry and\nconfiguration at very detailed level.\n\nThe GEOPM Service DBus interface is how clients interact with the service.\nAccess to the DBus interfaces can be gained from the command line or\nprogrammatically with library interfaces for C, C++, and Python.\n\nThe service supports multiple simultaneous client sessions for making\nmeasurements, however only clients from within a single Linux process session\nare given write permission to configure hardware control values at any one\ntime. Upon termination of a client's process session leader, the GEOPM Service\nrestores all hardware settings to their original state before the first\nclient's write request.\n\nFor more information about the Linux session leader process, please consult the\n`setsid(2) <https://man7.org/linux/man-pages/man2/setsid.2.html>`_ manual.\n\n*\n `Overview slides <https://geopm.github.io/pdf/geopm-service.pdf>`_\n\nArchitecture\n------------\n\n.. image:: https://geopm.github.io/images/geopm-service-diagram.svg\n :target: https://geopm.github.io/pdf/geopm-service-diagram.pdf\n :alt:\n\nThe architectural diagram shows the relationship between IOGroups and the GEOPM\nService. IOGroups are the C++ classes that abstract hardware interfaces.\nIOGroups provide a plugin mechanism to extend GEOPM's functionality.\n\nThe PlatformIO interface is a container for all IOGroups and is the main\ninterface for users who interact with the hardware through the GEOPM Service.\nThe PlatformIO interface can be accessed through language bindings with Python,\nC, and C++ as well as command line tools such as ``geopmread`` and\n``geopmwrite``. The GEOPM DBus interface, ``io.github.geopm``, provides a\nsecure gateway to privileged PlatformIO features. The ``geopmaccess`` command line\ntool is used by the administrator to enable user level access to any subset of\nthe privileged PlatformIO features.\n\n\nStatus\n------\n\nThe GEOPM systemd service introduced in version 2.0 is fully tested and is now\nready for production.\n\n\nSignals and Controls\n--------------------\n\nEach signal and control in GEOPM has a unique name and a hardware domain. The\nsignals and controls available on your system can be discovered with the\n``geopmaccess`` command line tool. The description includes all the necessary\ninformation for end users and system administrators to understand what is\nenabled when granting access to a signal or control.\n\n\nAccess Management\n-----------------\n\nSystem administrators configure the access to signals and controls through the\nGEOPM Service. The administrator maintains an access list that applies to all\nusers of the system. Special Unix groups can have enhanced access. The default\nlists are stored in:\n\n.. code-block::\n\n /etc/geopm/0.DEFAULT_ACCESS/allowed_signals\n /etc/geopm/0.DEFAULT_ACCESS/allowed_controls\n\nEach Unix group name ``<GROUP>`` that has extended permissions can\nmaintain one or both of the files\n\n.. code-block::\n\n /etc/geopm/<GROUP>/allowed_signals\n /etc/geopm/<GROUP>/allowed_controls\n\n.. note::\n\n Before GEOPM 3.0, service configuration files were stored in\n ``/etc/geopm-service``. Since version 3.0, they are stored in\n ``/etc/geopm``. Version 3.0 ignores the old file location if the new\n location exists. If the service uses a configuration from the old location,\n then a deprecation warning is emitted.\n\nAny missing files are inferred to be empty lists, including the default access\nfiles. A signal or control will not be available to non-root users through the\nGEOPM Service until a system administrator enables access through these allow\nlists. It is recommended that all manipulation of these files should be done\nthrough the GEOPM Service with the ``geopmaccess`` command line tool.\n\nAll control settings can be read by requesting the signal with the same name.\nWhenever a control name is added to the access list for writing, the\nadministrator implicitly grants read access to the control setting as well.\n\n\nOpening a Session\n-----------------\n\nEach time a client process opens a session with the GEOPM Service, a PlatformIO\nobject is created with libgeopmd. This session starts in read-only mode. Calls\nto the DBus APIs that modify control values convert the session into write mode.\nThe session retains write access until it ends. Calls into the DBus APIs that\nmodify control values:\n\n.. code-block::\n\n io.github.geopm.PlatformWriteControl\n io.github.geopm.PlatformPushControl\n\n\nconvert the session into write mode. Only one write mode session is\nallowed at any time. The request will fail if a client attempts to\nbegin a write session while another client has one open.\n\nWhen a session is converted to write mode, all controls that the\nservice is configured to support are recorded to a save directory in:\n\n.. code-block::\n\n /run/geopm/SAVE_FILES\n\n\nWhen a write mode session ends, all of these saved controls are\nrestored to the value they had when the session was converted,\nregardless of whether or not they were adjusted during the session\nthrough the service.\n\nIn addition to saving the state of controls, the GEOPM Service will\nalso lock access to controls for any other client until the\ncontrolling session ends. When the controlling session ends the saved\nstate is used to restore the values for all controls supported by the\nGEOPM Service to the values they had prior to enabling the client to\nmodify a control. The controlling session may end by an explicit\nD-Bus call by the client, or when the process that initiated the\nclient session ends. The GEOPM Service will poll procfs for the\nprocess ID.\n\nBatch Server\n------------\n\nThe GEOPM Service provides the implementation for the ServiceIOGroup\nwhich accesses this implementation through the DBus interface. When a\nuser program calls ``read_signal()`` or ``write_control()`` on a\nPlatformIO object provided by libgeopmd and the only\nIOGroup that provides the signal or control requested is the\nServiceIOGroup, then each request goes through the slow DBus\ninterface. When a client process uses the ServiceIOGroup for batch\noperations a separate batch server process is created through the DBus\ninterface. The implementations for ``push_signal()`` and\n``push_control()`` are used to configure the stack of signals and\ncontrols that will be enabled by the batch server. This batch server\ninteracts more directly with the client process to provide low latency\nsupport for the ``read_batch()`` and ``write_batch()`` interfaces of the\nServiceIOGroup.\n\nThe batch server is configured to allow access to exactly the signals\nand controls that were pushed onto the stack for the ServiceIOGroup\nprior to the first ``read_batch()`` or ``write_batch()`` call.\nThrough the DBus implementation, the GEOPM Service verifies that the\nclient user has appropriate permissions for the requested signals and\ncontrols. When the first call to ``read_batch()`` or\n``write_batch()`` is made to user's PlatformIO object, the geopmd\nprocess forks the batch server process and no more updates can be made\nto the configured requests. The batch server uses inter-process\nshared memory and FIFO special files to enable fast access to the\nconfigured stack of GEOPM signals and controls.\n\nTo implement the ``read_batch()`` method, the ServiceIOGroup writes a\ncharacter to a FIFO to notify the batch server that it would like the\nconfigured GEOPM signals to be updated in shared memory. The client\nprocess then waits on a FIFO for a message from the server that the\nrequest is ready. The batch server proceeds to read all GEOPM signals\nthat are supported by the client's ServiceIOGroup using the batch\nserver's instance of the PlatformIO object. GEOPM signals are copied\ninto the shared memory buffer and when the buffer is ready, a\ncharacter is written into the FIFO that the client process is waiting\non.\n\nTo implement the ``write_batch()`` method, the client process's\nServiceIOGroup prepares the shared memory buffer with all control\nsettings that the batch server is supporting. The client then writes\na character into a FIFO to notify the batch server that it would like\nthe configured GEOPM controls to be written. The client process then\nwaits on a FIFO for a message from the server that the controls have\nbeen written. The batch server proceeds to read the clients settings\nfrom the shared memory buffer and writes the values through the server\nprocess's PlatformIO instance. When the write has completed, a\ncharacter is written into the FIFO that the client process is waiting\non.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2015 - 2023, Intel Corporation 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 Intel Corporation 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 THE COPYRIGHT OWNER OR CONTRIBUTORS 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 LOG OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "GEOPM - Global Extensible Open Power Manager Daemon",
"version": "3.0.1",
"project_urls": {
"Documentation": "https://geopm.github.io/geopmdpy.7.html",
"Homepage": "https://geopm.github.io",
"Source": "https://github.com/geopm/geopm/"
},
"split_keywords": [
"service",
"hardware",
"telemetry",
"configuration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6f80aaef19f83ff6aa4fb80e418b131a77161d988e63983db73ab920f9ef8710",
"md5": "d792e6084eeb8f626558cdfd6d45410f",
"sha256": "ebdfa9b77fa92d3f411bfb1c94938039738d453b2441029b8ce44852115a8f73"
},
"downloads": -1,
"filename": "geopmdpy-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d792e6084eeb8f626558cdfd6d45410f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 55627,
"upload_time": "2023-12-07T17:14:40",
"upload_time_iso_8601": "2023-12-07T17:14:40.975764Z",
"url": "https://files.pythonhosted.org/packages/6f/80/aaef19f83ff6aa4fb80e418b131a77161d988e63983db73ab920f9ef8710/geopmdpy-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "656cf79f1f86630658ce6ee97fbae8eee421d37fa6ae97a4e68f96f5561faf82",
"md5": "aa0146bb31d55529a33bec6efa838857",
"sha256": "1d9ef65e7ffdb59919a9ed1e0902091b76985b70c2632806b1df2fc787401829"
},
"downloads": -1,
"filename": "geopmdpy-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "aa0146bb31d55529a33bec6efa838857",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 54149,
"upload_time": "2023-12-07T17:14:42",
"upload_time_iso_8601": "2023-12-07T17:14:42.417453Z",
"url": "https://files.pythonhosted.org/packages/65/6c/f79f1f86630658ce6ee97fbae8eee421d37fa6ae97a4e68f96f5561faf82/geopmdpy-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-07 17:14:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "geopm",
"github_project": "geopm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "geopmdpy"
}
