
Guide for Service Clients
=========================

The ``geopmsession`` command line tool is one way to use the GEOPM
Service's client facing DBus APIs.  This provides an easy way to read
signals once, read them periodically, or write to a set of controls
for the lifetime of the session.  Note that the system administrator
must grant access to the signals or controls with the ``geopmaccess``
command line tool before they will be available to a non-root user
with the ``geopmsession`` command.


Reading Instructions Retired
----------------------------

In this example we will read the hardware counter that measures
instructions retired for Linux logical CPU 0 and 1.  This read will be
done every 100 milliseconds for one second.  Additionally we will read
the TIME signal for the first column of output.  The result will be a
comma separated list of the three values read printed ten times to
standard output.

.. code-block:: bash

    echo "TIME board 0
          CPU_INSTRUCTIONS_RETIRED cpu 0
          CPU_INSTRUCTIONS_RETIRED cpu 1" | geopmsession -t 1 -p 0.1


Guide for Service Clients
=========================

The GEOPM Service facilitates the PlatformIO interfaces by providing
security and quality guaruantees.  Clients of the GEOPM service may
access the PlatformIO features through a variety of interfaces
including C, C++, Python and command line tools.  The administrator of
the system may manage client access rights through the ``geopmaccess``
command line tool.

A high level overview of the PlatformIO abstraction is described in
the :doc:`geopm_pio(7) <geopm_pio.7>` man page.  This page and the
pages linked within describe all signals and controls that are available
through this interface.  A client may read the signals or write the
controls described in the overview with the interfaces listed below.


PlatformIO Language Bindings
----------------------------

- C: :doc:`geopm_pio(3) <geopm_pio.3>` C Interface
- C++: :doc:`geopm::PlatformIO(3) <GEOPM_CXX_MAN_PlatformIO.3>`
- Python3: :ref:`geopmdpy.7:geopmdpy.pio`


PlatformIO Command Line Interfaces
----------------------------------

- Read one value: :doc:`geopmread(1) <geopmread.1>`
- Write one value: :doc:`geopmwrite(1) <geopmwrite.1>`
- Read time series of values :doc:`geopmsession(1) <geopmsession.1>`
- Access management :doc:`geopmaccess(1) <geopmaccess.1>`

Update GEOPM Service Client page
Update GEOPM Service Client page

Signed-off-by: Christopher M. Cantalupo <9cf3ecca60a3dd7112ab0e7250bedb8a752e3958@intel.com>
