Giter Site home page Giter Site logo

geopm.github.io's Introduction

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
  <meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>GEOPM Systemd Service &mdash; GEOPM  documentation</title>
      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  <!--[if lt IE 9]>
    <script src="_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
        <script src="_static/jquery.js"></script>
        <script src="_static/underscore.js"></script>
        <script src="_static/doctools.js"></script>
    <script src="_static/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="External Requirements" href="requires.html" />
    <link rel="prev" title="GEOPM Service Documentation" href="index.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
            <a href="index.html" class="icon icon-home"> GEOPM
            <img src="https://geopm.github.io/images/geopm-logo-clear.png" class="logo" alt="Logo"/>
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">GEOPM Systemd Service</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="#architecture-diagram">Architecture Diagram</a></li>
<li class="toctree-l2"><a class="reference internal" href="#status">Status</a></li>
<li class="toctree-l2"><a class="reference internal" href="#signals-and-controls">Signals and Controls</a></li>
<li class="toctree-l2"><a class="reference internal" href="#access-management">Access Management</a></li>
<li class="toctree-l2"><a class="reference internal" href="#opening-a-session">Opening a Session</a></li>
<li class="toctree-l2"><a class="reference internal" href="#batch-server">Batch Server</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="requires.html">External Requirements</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Building and Installing</a></li>
<li class="toctree-l1"><a class="reference internal" href="admin.html">Guide for Service Administrators</a></li>
<li class="toctree-l1"><a class="reference internal" href="client.html">Guide for Service Clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="runtime.html">Guide for HPC Runtime Users</a></li>
<li class="toctree-l1"><a class="reference internal" href="contrib.html">Guide for Contributors</a></li>
<li class="toctree-l1"><a class="reference internal" href="devel.html">Guide for GEOPM Developers</a></li>
<li class="toctree-l1"><a class="reference internal" href="info.html">Signals and Controls</a></li>
<li class="toctree-l1"><a class="reference internal" href="reference.html">Reference Manual</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">GEOPM</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="index.html" class="icon icon-home"></a> &raquo;</li>
      <li>GEOPM Systemd Service</li>
      <li class="wy-breadcrumbs-aside">
            <a href="_sources/readme.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="geopm-systemd-service">
<h1>GEOPM Systemd Service<a class="headerlink" href="#geopm-systemd-service" title="Permalink to this headline"></a></h1>
<ul class="simple">
<li><p>Fine grained access management system for hardware features: read
hardware “signals” and write hardware “controls”.</p></li>
<li><p>System administrator configures access permissions based on Unix
group.</p></li>
<li><p>Save / restore of hardware controls based on client process lifetime.</p></li>
<li><p>A high performance interface enabling batch access to validated sets
of signals/controls.</p></li>
<li><p>Supports extensibility for heterogenous environments through C++
plugin infrastructure (IOGroups).</p></li>
<li><p><a class="reference external" href="https://geopm.github.io/pdf/geopm-service.pdf">Overview slides</a></p></li>
</ul>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline"></a></h2>
<p>The GEOPM service enables a client to make measurements from the
hardware platform and set hardware control parameters.  Fine grained
permissions management for both measurements (signals) and controls is
configurable by system administrators with the <code class="docutils literal notranslate"><span class="pre">geopmaccess</span></code> command
line tool.  The service can support many simultaneous client sessions
that make measurements, but only one client session is granted write
permission to set hardware control values at any time.  When a client
session is granted write access it will retain that permission until
the session ends.  When the client session ends, all hardware settings
that are managed by the GEOPM service are restored to the value they
had prior to the client opening a write session.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">geopmd</span></code> daemon is started by the GEOPM systemd service and uses
D-Bus for communication with client processes and for administrator
configuration.  The GEOPM service is used to extend the
<code class="docutils literal notranslate"><span class="pre">geopm::PlatformIO</span></code> features of libgeopm and libgeopmpolicy.  The
PlatformIO interface of GEOPM is extensible through IOGroup plugins
and the GEOPM service enables the ServiceIOGroup.  The ServiceIOGroup
is implemented to provide the requirements of the IOGroup class by
interfacing with <code class="docutils literal notranslate"><span class="pre">geopmd</span></code> over the D-Bus interface.  The
ServiceIOGroup plugin is loaded first by PlatformIO in libgeopm and
libgeopmpolicy, and is not loaded by the PlatformIO implementation in
libgeopmd.  For a libgeopm or libgeopmpolicy user, any IOGroup other
than the ServiceIOGroup that provides a requested signal or control
will be used.  The ServiceIOGroup will only be used when a user
requests a signal or control that cannot be provided by any of the
native IOGroup plugins loaded by the unprivileged user process.  The
geopmd process loads PlatformIO through libgeopmd as a root user which
has permissions to load all signals and controls from all IOGroups but
does not load the ProfileIOGroup that provides signals derived from
the user application.  The PlatformIO loaded by geopmd provides the
implementation for the GEOPM service D-Bus interfaces.</p>
</section>
<section id="architecture-diagram">
<h2>Architecture Diagram<a class="headerlink" href="#architecture-diagram" title="Permalink to this headline"></a></h2>
<a class="reference external image-reference" href="https://geopm.github.io/pdf/geopm-service-diagram.pdf"><img alt="" src="https://geopm.github.io/images/geopm-service-diagram.svg" /></a>
</section>
<section id="status">
<h2>Status<a class="headerlink" href="#status" title="Permalink to this headline"></a></h2>
<p>The GEOPM systemd service is a new feature.  What exists currently is
a proof of concept / prototype, and there are many outstanding issues
that must be resolved before the GEOPM service is ready for release.
These issues are tracked on github with the “geopm-service” tag:</p>
<p><a class="reference external" href="https://github.com/geopm/geopm/issues?q=is%3Aissue+is%3Aopen+label%3Ageopm-service">https://github.com/geopm/geopm/issues?q=is%3Aissue+is%3Aopen+label%3Ageopm-service</a></p>
</section>
<section id="signals-and-controls">
<h2>Signals and Controls<a class="headerlink" href="#signals-and-controls" title="Permalink to this headline"></a></h2>
<p>Each GEOPM signal and control has an associated name and a hardware
domain.  The name is a unique string identifier defined by the IOGroup
that provides the signal or control.  The hardware domain that
provides the interface is represented by one of the enumerations as
defined by PlatformTopo.  A detailed description of the signals and
controls available on a system can be discovered with the
<code class="docutils literal notranslate"><span class="pre">geopmaccess</span></code> command line tool.  The description includes information
useful for end-users, and it also provides information for system
administrators that will help them understand what is enabled for an
end-user when access is granted to a signal or control.</p>
</section>
<section id="access-management">
<h2>Access Management<a class="headerlink" href="#access-management" title="Permalink to this headline"></a></h2>
<p>Access to signals and controls through the GEOPM service is configured
by the system administrator.  The administrator controls a default
access list that applies to all users of the system.  This list can be
augmented based on Unix group associations.  The default lists are
stored in:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">geopm</span><span class="o">-</span><span class="n">service</span><span class="o">/</span><span class="mf">0.</span><span class="n">DEFAULT_ACCESS</span><span class="o">/</span><span class="n">allowed_signals</span>
<span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">geopm</span><span class="o">-</span><span class="n">service</span><span class="o">/</span><span class="mf">0.</span><span class="n">DEFAULT_ACCESS</span><span class="o">/</span><span class="n">allowed_controls</span>
</pre></div>
</div>
<p>Each Unix <code class="docutils literal notranslate"><span class="pre">&lt;GROUP&gt;</span></code> that has extended permissions can maintain one or
both of the files</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">geopm</span><span class="o">-</span><span class="n">service</span><span class="o">/&lt;</span><span class="n">GROUP</span><span class="o">&gt;/</span><span class="n">allowed_signals</span>
<span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">geopm</span><span class="o">-</span><span class="n">service</span><span class="o">/&lt;</span><span class="n">GROUP</span><span class="o">&gt;/</span><span class="n">allowed_controls</span>
</pre></div>
</div>
<p>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 <code class="docutils literal notranslate"><span class="pre">geopmaccess</span></code> command line tool.</p>
<p>Some filtering may be applied to the raw signals provided by the
IOGroups before being exposed to the client session.  In particular,
all monotonic signals (e.g. hardware counters) are reported with
respect to the value they had when they were first read in the
session, which is reported as zero.</p>
</section>
<section id="opening-a-session">
<h2>Opening a Session<a class="headerlink" href="#opening-a-session" title="Permalink to this headline"></a></h2>
<p>A client process opens a session with the GEOPM service each time a
PlatformIO object is created with libgeopm or libgeopmpolicy while the
GEOPM systemd service is active.  This session is initially opened in
read-only mode.  Calls into the D-Bus APIs that modify control values:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">io</span><span class="o">.</span><span class="n">github</span><span class="o">.</span><span class="n">geopm</span><span class="o">.</span><span class="n">PlatformWriteControl</span>
<span class="n">io</span><span class="o">.</span><span class="n">github</span><span class="o">.</span><span class="n">geopm</span><span class="o">.</span><span class="n">PlatformPushControl</span>
</pre></div>
</div>
<p>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.</p>
<p>When a session is converted to write mode, all controls that the
service is configured to support are recorded to a save directory in:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">var</span><span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">geopm</span><span class="o">-</span><span class="n">service</span><span class="o">/</span><span class="n">SAVE_FILES</span>
</pre></div>
</div>
<p>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.</p>
<p>The request to open a session is done in the ServiceIOGroup
constructor, and the request to close the session is made by the
ServiceIOGroup destructor.  Calls to the ServiceIOGroup’s
<code class="docutils literal notranslate"><span class="pre">write_control()</span></code> or <code class="docutils literal notranslate"><span class="pre">push_control()</span></code> methods will trigger the
conversion of the session to write mode.  Calls to these methods will
only occur when the ServiceIOGroup is the only loaded IOGroup that
provides the control requested by the user since all IOGroups are
loaded by the PlatformIO factory after the ServiceIOGroup.</p>
<p>Note that if any control adjustments are made during a session through
the GEOPM service then every control supported by GEOPM will be
reverted when the session ends.  One consequence of this is that when
a control is exposed to a user only through the GEOPM service, then
the geopmwrite command line tool will not be effective (the value will
be written, but reverted when the geopmwrite process ends).  The
geopmsession command line tool can be used to write any number of the
GEOPM supported controls and keep a session open for a specified
duration (or until the geopmsession process is killed).</p>
<p>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 use the <code class="docutils literal notranslate"><span class="pre">pidfd_open(2)</span></code>
mechanism for notification of the end of the client process if this is
supported by the Linux kernel, otherwise it will poll procfs for the
process ID.  The GEOPM service provides an interface that enables a
privileged user to end any currently running write mode session, and
block any access to controls by other clients.  There is a
corresponding unlock interface that will enable write mode sessions to
begin again.</p>
</section>
<section id="batch-server">
<h2>Batch Server<a class="headerlink" href="#batch-server" title="Permalink to this headline"></a></h2>
<p>The GEOPM service provides the implementation for the ServiceIOGroup
which accesses this implementation through the DBus interface.  When a
user program calls <code class="docutils literal notranslate"><span class="pre">read_signal()</span></code> or <code class="docutils literal notranslate"><span class="pre">write_control()</span></code> on a
PlatformIO object provided by libgeopm or libgeopmpolicy and the only
IOGroup that provides the signal or control requested is the
ServiceIOGroup, then each request goes through the slow D-Bus
interface.  When a client process uses the ServiceIOGroup for batch
operations a separate batch server process is created through the D-Bus
interface.  The implementations for <code class="docutils literal notranslate"><span class="pre">push_signal()</span></code> and
<code class="docutils literal notranslate"><span class="pre">push_control()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">read_batch()</span></code> and <code class="docutils literal notranslate"><span class="pre">write_batch()</span></code> interfaces of the
ServiceIOGroup.</p>
<p>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 <code class="docutils literal notranslate"><span class="pre">read_batch()</span></code> or <code class="docutils literal notranslate"><span class="pre">write_batch()</span></code> call.  Through
the D-Bus implementation, the GEOPM service verifies that the client
user has appropriate permissions for the requested signals and
controls.  When the first call to <code class="docutils literal notranslate"><span class="pre">read_batch()</span></code> or <code class="docutils literal notranslate"><span class="pre">write_batch()</span></code> 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 POSIX
signals to enable fast access to the configured stack of GEOPM signals
and controls.  In this documentation we will call always refer to
“POSIX signals” to differentiate from the GEOPM signal concept which
is unrelated to the POSIX signal as defined in the signal(7) man page.</p>
<p>To implement the <code class="docutils literal notranslate"><span class="pre">read_batch()</span></code> method, the ServiceIOGroup sends a
POSIX signal to notify the batch server that it would like the
configured GEOPM signals to be updated in shared memory.  The batch
server reads all GEOPM signals that are being 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 a SIGCONT POSIX signal is sent from the batch server to the
client process when the buffer is ready.  To implement the
<code class="docutils literal notranslate"><span class="pre">write_batch()</span></code> method, the client process’s ServiceIOGroup prepares
the shared memory buffer with all control settings that it is
supporting.  The client sends a SIGCONT POSIX signal to the batch
server to notify it to write the settings.  The batch server then
reads the clients settings from a shared memory buffer and writes the
values through the server process’s PlatformIO instance.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="index.html" class="btn btn-neutral float-left" title="GEOPM Service Documentation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="requires.html" class="btn btn-neutral float-right" title="External Requirements" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2021, Intel (R) Corporation.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>

geopm.github.io's People

Contributors

cmcantalupo avatar dianarg avatar bgeltz avatar dannosliwcd avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.