sascha/devlib
1
0
Fork 0
mirror of https://github.com/ARM-software/devlib.git synced 2025-01-30 17:50:46 +00:00
Code Issues Releases Wiki Activity

docs: Update to use module diretive

Browse Source 
Update the documentation to indicated which module each class is
located. This allows the documentation to be referenced from other
modules as well as enabling links to the source code directly from the
documentation.
This commit is contained in:
Marc Bonnici 2019-11-18 10:36:03 +00:00
parent 7f5e0f5b4d
commit ec0a5884c0
8 changed files with 246 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/connection.rst
View File

@ -3,16 +3,17 @@ Connection
A :class:`Connection` abstracts an actual physical connection to a device. The A :class:`Connection` abstracts an actual physical connection to a device. The
first connection is created when :func:`Target.connect` method is called. If a first connection is created when :func:`Target.connect` method is called. If a
:class:`Target` is used in a multi-threaded environment, it will maintain a :class:`~devlib.target.Target` is used in a multi-threaded environment, it will
connection for each thread in which it is invoked. This allows the same target maintain a connection for each thread in which it is invoked. This allows
object to be used in parallel in multiple threads. the same target object to be used in parallel in multiple threads.
:class:`Connection`\ s will be automatically created and managed by :class:`Connection`\ s will be automatically created and managed by
:class:`Target`\ s, so there is usually no reason to create one manually. :class:`~devlib.target.Target`\ s, so there is usually no reason to create one
Instead, configuration for a :class:`Connection` is passed as manually. Instead, configuration for a :class:`Connection` is passed as
`connection_settings` parameter when creating a :class:`Target`. The connection `connection_settings` parameter when creating a
to be used target is also specified on instantiation by `conn_cls` parameter, :class:`~devlib.target.Target`. The connection to be used target is also
though all concrete :class:`Target` implementations will set an appropriate specified on instantiation by `conn_cls` parameter, though all concrete
:class:`~devlib.target.Target` implementations will set an appropriate
default, so there is typically no need to specify this explicitly. default, so there is typically no need to specify this explicitly.
:class:`Connection` classes are not a part of an inheritance hierarchy, i.e. :class:`Connection` classes are not a part of an inheritance hierarchy, i.e.
@ -76,7 +77,7 @@ class that implements the following methods.
.. note:: This **will block the connection** until the command completes. .. note:: This **will block the connection** until the command completes.
.. note:: The above methods are directly wrapped by :class:`Target` methods, .. note:: The above methods are directly wrapped by :class:`~devlib.target.Target` methods,
however note that some of the defaults are different. however note that some of the defaults are different.
.. method:: cancel_running_command(self) .. method:: cancel_running_command(self)
@ -100,6 +101,9 @@ class that implements the following methods.
Connection Types Connection Types
---------------- ----------------
.. module:: devlib.utils.android
.. class:: AdbConnection(device=None, timeout=None, adb_server=None, adb_as_root=False) .. class:: AdbConnection(device=None, timeout=None, adb_server=None, adb_as_root=False)
A connection to an android device via ``adb`` (Android Debug Bridge). A connection to an android device via ``adb`` (Android Debug Bridge).
@ -116,6 +120,7 @@ Connection Types
:param adb_server: Allows specifying the address of the adb server to use. :param adb_server: Allows specifying the address of the adb server to use.
:param adb_as_root: Specify whether the adb server should be restarted in root mode. :param adb_as_root: Specify whether the adb server should be restarted in root mode.
.. module:: devlib.utils.ssh
.. class:: SshConnection(host, username, password=None, keyfile=None, port=None,\ .. class:: SshConnection(host, username, password=None, keyfile=None, port=None,\
timeout=None, password_prompt=None, \ timeout=None, password_prompt=None, \
@ -179,6 +184,7 @@ Connection Types
connection to reduce the possibility of clashes). connection to reduce the possibility of clashes).
This parameter is ignored for SSH connections. This parameter is ignored for SSH connections.
.. module:: devlib.host
.. class:: LocalConnection(keep_password=True, unrooted=False, password=None) .. class:: LocalConnection(keep_password=True, unrooted=False, password=None)
@ -194,6 +200,9 @@ Connection Types
prompting for it. prompting for it.
.. module:: devlib.utils.ssh
:noindex:
.. class:: Gem5Connection(platform, host=None, username=None, password=None,\ .. class:: Gem5Connection(platform, host=None, username=None, password=None,\
timeout=None, password_prompt=None,\ timeout=None, password_prompt=None,\
original_prompt=None) original_prompt=None)
@ -212,7 +221,7 @@ Connection Types
will be ignored, the gem5 simulation needs to be will be ignored, the gem5 simulation needs to be
on the same host the user is currently on, so if on the same host the user is currently on, so if
the host given as input parameter is not the the host given as input parameter is not the
same as the actual host, a ``TargetStableError`` same as the actual host, a :class:`TargetStableError`
will be raised to prevent confusion. will be raised to prevent confusion.
:param username: Username in the simulated system :param username: Username in the simulated system
@ -238,14 +247,14 @@ The only methods discussed below are those that will be overwritten by the
A connection to a gem5 simulation that emulates a Linux system. A connection to a gem5 simulation that emulates a Linux system.
.. method:: _login_to_device(self) .. method:: _login_to_device(self)
Login to the gem5 simulated system. Login to the gem5 simulated system.
.. class:: AndroidGem5Connection .. class:: AndroidGem5Connection
A connection to a gem5 simulation that emulates an Android system. A connection to a gem5 simulation that emulates an Android system.
.. method:: _wait_for_boot(self) .. method:: _wait_for_boot(self)
Wait for the gem5 simulated system to have booted and finished the booting animation. Wait for the gem5 simulated system to have booted and finished the booting animation.

24
doc/derived_measurements.rst
View File

@ -1,7 +1,6 @@
Derived Measurements Derived Measurements
===================== =====================
The ``DerivedMeasurements`` API provides a consistent way of performing post The ``DerivedMeasurements`` API provides a consistent way of performing post
processing on a provided :class:`MeasurementCsv` file. processing on a provided :class:`MeasurementCsv` file.
@ -35,6 +34,8 @@ API
Derived Measurements Derived Measurements
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
.. module:: devlib.derived
.. class:: DerivedMeasurements .. class:: DerivedMeasurements
The ``DerivedMeasurements`` class provides an API for post-processing The ``DerivedMeasurements`` class provides an API for post-processing
@ -102,17 +103,20 @@ Available Derived Measurements
Energy Energy
~~~~~~ ~~~~~~
.. module:: devlib.derived.energy
.. class:: DerivedEnergyMeasurements .. class:: DerivedEnergyMeasurements
The ``DerivedEnergyMeasurements`` class is used to calculate average power and The ``DerivedEnergyMeasurements`` class is used to calculate average power
cumulative energy for each site if the required data is present. and cumulative energy for each site if the required data is present.
The calculation of cumulative energy can occur in 3 ways. If a The calculation of cumulative energy can occur in 3 ways. If a ``site``
``site`` contains ``energy`` results, the first and last measurements are extracted contains ``energy`` results, the first and last measurements are extracted
and the delta calculated. If not, a ``timestamp`` channel will be used to calculate and the delta calculated. If not, a ``timestamp`` channel will be used to
the energy from the power channel, failing back to using the sample rate attribute calculate the energy from the power channel, failing back to using the sample
of the :class:`MeasurementCsv` file if timestamps are not available. If neither rate attribute of the :class:`MeasurementCsv` file if timestamps are not
timestamps or a sample rate are available then an error will be raised. available. If neither timestamps or a sample rate are available then an error
will be raised.
.. method:: DerivedEnergyMeasurements.process(measurement_csv) .. method:: DerivedEnergyMeasurements.process(measurement_csv)
@ -128,6 +132,8 @@ Energy
FPS / Rendering FPS / Rendering
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
.. module:: devlib.derived.fps
.. class:: DerivedGfxInfoStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None) .. class:: DerivedGfxInfoStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None)
Produces FPS (frames-per-second) and other derived statistics from Produces FPS (frames-per-second) and other derived statistics from

2
doc/index.rst
View File

@ -3,6 +3,8 @@
You can adapt this file completely to your liking, but it should at least You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. contain the root `toctree` directive.
.. module:: devlib
Welcome to devlib documentation Welcome to devlib documentation
=============================== ===============================

53
doc/instrumentation.rst
View File

@ -5,9 +5,9 @@ Instrumentation
The ``Instrument`` API provide a consistent way of collecting measurements from The ``Instrument`` API provide a consistent way of collecting measurements from
a target. Measurements are collected via an instance of a class derived from a target. Measurements are collected via an instance of a class derived from
:class:`Instrument`. An ``Instrument`` allows collection of measurement from one :class:`~devlib.instrument.Instrument`. An ``Instrument`` allows collection of
or more channels. An ``Instrument`` may support ``INSTANTANEOUS`` or measurement from one or more channels. An ``Instrument`` may support
``CONTINUOUS`` collection, or both. ``INSTANTANEOUS`` or ``CONTINUOUS`` collection, or both.
Example Example
------- -------
@ -50,6 +50,8 @@ Android target.
API API
--- ---
.. module:: devlib.instrument
Instrument Instrument
~~~~~~~~~~ ~~~~~~~~~~
@ -122,14 +124,16 @@ Instrument
Take a single measurement from ``active_channels``. Returns a list of Take a single measurement from ``active_channels``. Returns a list of
:class:`Measurement` objects (one for each active channel). :class:`Measurement` objects (one for each active channel).
.. note:: This method is only implemented by :class:`Instrument`\ s that .. note:: This method is only implemented by
:class:`~devlib.instrument.Instrument`\ s that
support ``INSTANTANEOUS`` measurement. support ``INSTANTANEOUS`` measurement.
.. method:: Instrument.start() .. method:: Instrument.start()
Starts collecting measurements from ``active_channels``. Starts collecting measurements from ``active_channels``.
.. note:: This method is only implemented by :class:`Instrument`\ s that .. note:: This method is only implemented by
:class:`~devlib.instrument.Instrument`\ s that
support ``CONTINUOUS`` measurement. support ``CONTINUOUS`` measurement.
.. method:: Instrument.stop() .. method:: Instrument.stop()
@ -137,7 +141,8 @@ Instrument
Stops collecting measurements from ``active_channels``. Must be called after Stops collecting measurements from ``active_channels``. Must be called after
:func:`start()`. :func:`start()`.
.. note:: This method is only implemented by :class:`Instrument`\ s that .. note:: This method is only implemented by
:class:`~devlib.instrument.Instrument`\ s that
support ``CONTINUOUS`` measurement. support ``CONTINUOUS`` measurement.
.. method:: Instrument.get_data(outfile) .. method:: Instrument.get_data(outfile)
@ -148,9 +153,9 @@ Instrument
``<site>_<kind>`` (see :class:`InstrumentChannel`). The order of the columns ``<site>_<kind>`` (see :class:`InstrumentChannel`). The order of the columns
will be the same as the order of channels in ``Instrument.active_channels``. will be the same as the order of channels in ``Instrument.active_channels``.
If reporting timestamps, one channel must have a ``site`` named ``"timestamp"`` If reporting timestamps, one channel must have a ``site`` named
and a ``kind`` of a :class:`MeasurmentType` of an appropriate time unit which will ``"timestamp"`` and a ``kind`` of a :class:`MeasurmentType` of an appropriate
be used, if appropriate, during any post processing. time unit which will be used, if appropriate, during any post processing.
.. note:: Currently supported time units are seconds, milliseconds and .. note:: Currently supported time units are seconds, milliseconds and
microseconds, other units can also be used if an appropriate microseconds, other units can also be used if an appropriate
@ -160,7 +165,8 @@ Instrument
that can be used to stream :class:`Measurement`\ s lists (similar to what is that can be used to stream :class:`Measurement`\ s lists (similar to what is
returned by ``take_measurement()``. returned by ``take_measurement()``.
.. note:: This method is only implemented by :class:`Instrument`\ s that .. note:: This method is only implemented by
:class:`~devlib.instrument.Instrument`\ s that
support ``CONTINUOUS`` measurement. support ``CONTINUOUS`` measurement.
.. method:: Instrument.get_raw() .. method:: Instrument.get_raw()
@ -185,7 +191,8 @@ Instrument
Sample rate of the instrument in Hz. Assumed to be the same for all channels. Sample rate of the instrument in Hz. Assumed to be the same for all channels.
.. note:: This attribute is only provided by :class:`Instrument`\ s that .. note:: This attribute is only provided by
:class:`~devlib.instrument.Instrument`\ s that
support ``CONTINUOUS`` measurement. support ``CONTINUOUS`` measurement.
Instrument Channel Instrument Channel
@ -194,8 +201,8 @@ Instrument Channel
.. class:: InstrumentChannel(name, site, measurement_type, \*\*attrs) .. class:: InstrumentChannel(name, site, measurement_type, \*\*attrs)
An :class:`InstrumentChannel` describes a single type of measurement that may An :class:`InstrumentChannel` describes a single type of measurement that may
be collected by an :class:`Instrument`. A channel is primarily defined by a be collected by an :class:`~devlib.instrument.Instrument`. A channel is
``site`` and a ``measurement_type``. primarily defined by a ``site`` and a ``measurement_type``.
A ``site`` indicates where on the target a measurement is collected from A ``site`` indicates where on the target a measurement is collected from
(e.g. a voltage rail or location of a sensor). (e.g. a voltage rail or location of a sensor).
@ -488,12 +495,13 @@ voltage (see previous figure), samples are retrieved at a frequency of
where :math:`T_X` is the integration time for the :math:`X` voltage. where :math:`T_X` is the integration time for the :math:`X` voltage.
As described below (:meth:`BaylibreAcmeInstrument.reset`), the integration As described below (:meth:`BaylibreAcmeInstrument.reset
times for the bus and shunt voltage can be set separately which allows a <devlib.instrument.baylibre_acme.BaylibreAcmeInstrument.reset>`), the
tradeoff of accuracy between signals. This is particularly useful as the shunt integration times for the bus and shunt voltage can be set separately which
voltage returned by the INA226 has a higher resolution than the bus voltage allows a tradeoff of accuracy between signals. This is particularly useful as
(2.5 μV and 1.25 mV LSB, respectively) and therefore would benefit more from a the shunt voltage returned by the INA226 has a higher resolution than the bus
longer integration time. voltage (2.5 μV and 1.25 mV LSB, respectively) and therefore would benefit more
from a longer integration time.
As an illustration, consider the following sampled sine wave and notice how As an illustration, consider the following sampled sine wave and notice how
increasing the integration time (of the bus voltage in this case) "smoothes" increasing the integration time (of the bus voltage in this case) "smoothes"
@ -601,8 +609,9 @@ Buffer-based transactions
Samples made available by the INA226 are retrieved by the BBB and stored in a Samples made available by the INA226 are retrieved by the BBB and stored in a
buffer which is sent back to the host once it is full (see buffer which is sent back to the host once it is full (see
``buffer_samples_count`` in :meth:`BaylibreAcmeInstrument.setup` for setting ``buffer_samples_count`` in :meth:`BaylibreAcmeInstrument.setup
its size). Therefore, the larger the buffer is, the longer it takes to be <devlib.instrument.baylibre_acme.BaylibreAcmeInstrument.setup>` for setting its
size). Therefore, the larger the buffer is, the longer it takes to be
transmitted back but the less often it has to be transmitted. To illustrate transmitted back but the less often it has to be transmitted. To illustrate
this, consider the following graphs showing the time difference between this, consider the following graphs showing the time difference between
successive samples in a retrieved signal when the size of the buffer changes: successive samples in a retrieved signal when the size of the buffer changes:
@ -624,6 +633,8 @@ given by `libiio (the Linux IIO interface)`_ however only the network-based one
has been tested. For the other classes, please refer to the official IIO has been tested. For the other classes, please refer to the official IIO
documentation for the meaning of their constructor parameters. documentation for the meaning of their constructor parameters.
.. module:: devlib.instrument.baylibre_acme
.. class:: BaylibreAcmeInstrument(target=None, iio_context=None, use_base_iio_context=False, probe_names=None) .. class:: BaylibreAcmeInstrument(target=None, iio_context=None, use_base_iio_context=False, probe_names=None)
Base class wrapper for the ACME instrument which itself is a wrapper for the Base class wrapper for the ACME instrument which itself is a wrapper for the

52
doc/modules.rst
View File

@ -1,11 +1,13 @@
.. module:: devlib.module
.. _modules: .. _modules:
Modules Modules
======= =======
Modules add additional functionality to the core :class:`Target` interface. Modules add additional functionality to the core :class:`~devlib.target.Target`
Usually, it is support for specific subsystems on the target. Modules are interface. Usually, it is support for specific subsystems on the target. Modules
instantiated as attributes of the :class:`Target` instance. are instantiated as attributes of the :class:`~devlib.target.Target` instance.
hotplug hotplug
------- -------
@ -28,6 +30,8 @@ interface to this subsystem
# Make sure all cpus are online # Make sure all cpus are online
target.hotplug.online_all() target.hotplug.online_all()
.. module:: devlib.module.cpufreq
cpufreq cpufreq
------- -------
@ -132,6 +136,9 @@ policies (governors). The ``devlib`` module exposes the following interface
``1`` or ``"cpu1"``). ``1`` or ``"cpu1"``).
:param frequency: Frequency to set. :param frequency: Frequency to set.
.. module:: devlib.module.cupidle
cpuidle cpuidle
------- -------
@ -167,11 +174,15 @@ cpuidle
You can also call ``enable()`` or ``disable()`` on :class:`CpuidleState` objects You can also call ``enable()`` or ``disable()`` on :class:`CpuidleState` objects
returned by get_state(s). returned by get_state(s).
.. module:: devlib.module.cgroups
cgroups cgroups
------- -------
TODO TODO
.. module:: devlib.module.hwmon
hwmon hwmon
----- -----
@ -187,8 +198,8 @@ Modules implement discrete, optional pieces of functionality ("optional" in the
sense that the functionality may or may not be present on the target device, or sense that the functionality may or may not be present on the target device, or
that it may or may not be necessary for a particular application). that it may or may not be necessary for a particular application).
Every module (ultimately) derives from :class:`Module` class. A module must Every module (ultimately) derives from :class:`devlib.module.Module` class. A
define the following class attributes: module must define the following class attributes:
:name: A unique name for the module. This cannot clash with any of the existing :name: A unique name for the module. This cannot clash with any of the existing
names and must be a valid Python identifier, but is otherwise free-form. names and must be a valid Python identifier, but is otherwise free-form.
@ -204,14 +215,16 @@ define the following class attributes:
which case the module's ``name`` will be treated as its which case the module's ``name`` will be treated as its
``kind`` as well. ``kind`` as well.
:stage: This defines when the module will be installed into a :class:`Target`. :stage: This defines when the module will be installed into a
Currently, the following values are allowed: :class:`~devlib.target.Target`. Currently, the following values are
allowed:
:connected: The module is installed after a connection to the target has :connected: The module is installed after a connection to the target has
been established. This is the default. been established. This is the default.
:early: The module will be installed when a :class:`Target` is first :early: The module will be installed when a
created. This should be used for modules that do not rely on a :class:`~devlib.target.Target` is first created. This should be
live connection to the target. used for modules that do not rely on a live connection to the
target.
:setup: The module will be installed after initial setup of the device :setup: The module will be installed after initial setup of the device
has been performed. This allows the module to utilize assets has been performed. This allows the module to utilize assets
deployed during the setup stage for example 'Busybox'. deployed during the setup stage for example 'Busybox'.
@ -220,8 +233,8 @@ Additionally, a module must implement a static (or class) method :func:`probe`:
.. method:: Module.probe(target) .. method:: Module.probe(target)
This method takes a :class:`Target` instance and returns ``True`` if this This method takes a :class:`~devlib.target.Target` instance and returns
module is supported by that target, or ``False`` otherwise. ``True`` if this module is supported by that target, or ``False`` otherwise.
.. note:: If the module ``stage`` is ``"early"``, this method cannot assume .. note:: If the module ``stage`` is ``"early"``, this method cannot assume
that a connection has been established (i.e. it can only access that a connection has been established (i.e. it can only access
@ -231,9 +244,9 @@ Installation and invocation
*************************** ***************************
The default installation method will create an instance of a module (the The default installation method will create an instance of a module (the
:class:`Target` instance being the sole argument) and assign it to the target :class:`~devlib.target.Target` instance being the sole argument) and assign it
instance attribute named after the module's ``kind`` (or ``name`` if ``kind`` is to the target instance attribute named after the module's ``kind`` (or
``None``). ``name`` if ``kind`` is ``None``).
It is possible to change the installation procedure for a module by overriding It is possible to change the installation procedure for a module by overriding
the default :func:`install` method. The method must have the following the default :func:`install` method. The method must have the following
@ -344,10 +357,11 @@ FlashModule
Module Registration Module Registration
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
Modules are specified on :class:`Target` or :class:`Platform` creation by name. Modules are specified on :class:`~devlib.target.Target` or
In order to find the class associated with the name, the module needs to be :class:`~devlib.platform.Platform` creation by name. In order to find the class
registered with ``devlib``. This is accomplished by passing the module class associated with the name, the module needs to be registered with ``devlib``.
into :func:`register_module` method once it is defined. This is accomplished by passing the module class into :func:`register_module`
method once it is defined.
.. note:: If you're wiring a module to be included as part of ``devlib`` code .. note:: If you're wiring a module to be included as part of ``devlib`` code
base, you can place the file with the module class under base, you can place the file with the module class under

41
doc/overview.rst
View File

@ -1,25 +1,26 @@
Overview Overview
======== ========
A :class:`Target` instance serves as the main interface to the target device. A :class:`~devlib.target.Target` instance serves as the main interface to the target device.
There are currently four target interfaces: There are currently four target interfaces:
- :class:`LinuxTarget` for interacting with Linux devices over SSH. - :class:`~devlib.target.LinuxTarget` for interacting with Linux devices over SSH.
- :class:`AndroidTarget` for interacting with Android devices over adb. - :class:`~devlib.target.AndroidTarget` for interacting with Android devices over adb.
- :class:`ChromeOsTarget`: for interacting with ChromeOS devices over SSH, and their Android containers over adb. - :class:`~devlib.target.ChromeOsTarget`: for interacting with ChromeOS devices
- :class:`LocalLinuxTarget`: for interacting with the local Linux host. over SSH, and their Android containers over adb.
- :class:`~devlib.target.LocalLinuxTarget`: for interacting with the local Linux host.
They all work in more-or-less the same way, with the major difference being in They all work in more-or-less the same way, with the major difference being in
how connection settings are specified; though there may also be a few APIs how connection settings are specified; though there may also be a few APIs
specific to a particular target type (e.g. :class:`AndroidTarget` exposes specific to a particular target type (e.g. :class:`~devlib.target.AndroidTarget`
methods for working with logcat). exposes methods for working with logcat).
Acquiring a Target Acquiring a Target
------------------ ------------------
To create an interface to your device, you just need to instantiate one of the To create an interface to your device, you just need to instantiate one of the
:class:`Target` derivatives listed above, and pass it the right :class:`~devlib.target.Target` derivatives listed above, and pass it the right
``connection_settings``. Code snippet below gives a typical example of ``connection_settings``. Code snippet below gives a typical example of
instantiating each of the three target types. instantiating each of the three target types.
@ -46,21 +47,22 @@ instantiating each of the three target types.
t3 = AndroidTarget(connection_settings={'device': '0123456789abcde'}) t3 = AndroidTarget(connection_settings={'device': '0123456789abcde'})
Instantiating a target may take a second or two as the remote device will be Instantiating a target may take a second or two as the remote device will be
queried to initialize :class:`Target`'s internal state. If you would like to queried to initialize :class:`~devlib.target.Target`'s internal state. If you
create a :class:`Target` instance but not immediately connect to the remote would like to create a :class:`~devlib.target.Target` instance but not
device, you can pass ``connect=False`` parameter. If you do that, you would have immediately connect to the remote device, you can pass ``connect=False``
to then explicitly call ``t.connect()`` before you can interact with the device. parameter. If you do that, you would have to then explicitly call
``t.connect()`` before you can interact with the device.
There are a few additional parameters you can pass in instantiation besides There are a few additional parameters you can pass in instantiation besides
``connection_settings``, but they are usually unnecessary. Please see ``connection_settings``, but they are usually unnecessary. Please see
:class:`Target` API documentation for more details. :class:`~devlib.target.Target` API documentation for more details.
Target Interface Target Interface
---------------- ----------------
This is a quick overview of the basic interface to the device. See This is a quick overview of the basic interface to the device. See
:class:`Target` API documentation for the full list of supported methods and :class:`~devlib.target.Target` API documentation for the full list of supported
more detailed documentation. methods and more detailed documentation.
One-time Setup One-time Setup
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
@ -173,8 +175,9 @@ More...
~~~~~~~ ~~~~~~~
As mentioned previously, the above is not intended to be exhaustive As mentioned previously, the above is not intended to be exhaustive
documentation of the :class:`Target` interface. Please refer to the API documentation of the :class:`~devlib.target.Target` interface. Please refer to
documentation for the full list of attributes and methods and their parameters. the API documentation for the full list of attributes and methods and their
parameters.
Super User Privileges Super User Privileges
--------------------- ---------------------
@ -238,6 +241,8 @@ complete. Retrying it or bailing out is therefore a responsability of the caller
The hierarchy is as follows: The hierarchy is as follows:
.. module:: devlib.exception
- :class:`DevlibError` - :class:`DevlibError`
- :class:`WorkerThreadError` - :class:`WorkerThreadError`
@ -287,7 +292,7 @@ Modules
Additional functionality is exposed via modules. Modules are initialized as Additional functionality is exposed via modules. Modules are initialized as
attributes of a target instance. By default, ``hotplug``, ``cpufreq``, attributes of a target instance. By default, ``hotplug``, ``cpufreq``,
``cpuidle``, ``cgroups`` and ``hwmon`` will attempt to load on target; additional ``cpuidle``, ``cgroups`` and ``hwmon`` will attempt to load on target; additional
modules may be specified when creating a :class:`Target` instance. modules may be specified when creating a :class:`~devlib.target.Target` instance.
A module will probe the target for support before attempting to load. So if the A module will probe the target for support before attempting to load. So if the
underlying platform does not support particular functionality (e.g. the kernel underlying platform does not support particular functionality (e.g. the kernel

68
doc/platform.rst
View File

@ -1,14 +1,17 @@
.. module:: devlib.platform
.. _platform: .. _platform:
Platform Platform
======== ========
:class:`Platform`\ s describe the system underlying the OS. They encapsulate :class:`~devlib.platform.Platform`\ s describe the system underlying the OS.
hardware- and firmware-specific details. In most cases, the generic They encapsulate hardware- and firmware-specific details. In most cases, the
:class:`Platform` class, which gets used if a platform is not explicitly generic :class:`~devlib.platform.Platform` class, which gets used if a
specified on :class:`Target` creation, will be sufficient. It will automatically platform is not explicitly specified on :class:`~devlib.target.Target`
query as much platform information (such CPU topology, hardware model, etc) if creation, will be sufficient. It will automatically query as much platform
it was not specified explicitly by the user. information (such CPU topology, hardware model, etc) if it was not specified
explicitly by the user.
.. class:: Platform(name=None, core_names=None, core_clusters=None,\ .. class:: Platform(name=None, core_names=None, core_clusters=None,\
@ -31,6 +34,7 @@ it was not specified explicitly by the user.
platform (e.g. for handling flashing, rebooting, etc). These platform (e.g. for handling flashing, rebooting, etc). These
would be added to the Target's modules. (See :ref:`modules`\ ). would be added to the Target's modules. (See :ref:`modules`\ ).
.. module:: devlib.platform.arm
Versatile Express Versatile Express
----------------- -----------------
@ -38,8 +42,8 @@ Versatile Express
The generic platform may be extended to support hardware- or The generic platform may be extended to support hardware- or
infrastructure-specific functionality. Platforms exist for ARM infrastructure-specific functionality. Platforms exist for ARM
VersatileExpress-based :class:`Juno` and :class:`TC2` development boards. In VersatileExpress-based :class:`Juno` and :class:`TC2` development boards. In
addition to the standard :class:`Platform` parameters above, these platforms addition to the standard :class:`~devlib.platform.Platform` parameters above,
support additional configuration: these platforms support additional configuration:
.. class:: VersatileExpressPlatform .. class:: VersatileExpressPlatform
@ -116,43 +120,53 @@ support additional configuration:
Gem5 Simulation Platform Gem5 Simulation Platform
------------------------ ------------------------
By initialising a Gem5SimulationPlatform, devlib will start a gem5 simulation (based upon the By initialising a Gem5SimulationPlatform, devlib will start a gem5 simulation
arguments the user provided) and then connect to it using :class:`Gem5Connection`. (based upon the arguments the user provided) and then connect to it using
Using the methods discussed above, some methods of the :class:`Target` will be altered :class:`~devlib.utils.ssh.Gem5Connection`. Using the methods discussed above,
slightly to better suit gem5. some methods of the :class:`~devlib.target.Target` will be altered slightly to
better suit gem5.
.. module:: devlib.platform.gem5
.. class:: Gem5SimulationPlatform(name, host_output_dir, gem5_bin, gem5_args, gem5_virtio, gem5_telnet_port=None) .. class:: Gem5SimulationPlatform(name, host_output_dir, gem5_bin, gem5_args, gem5_virtio, gem5_telnet_port=None)
During initialisation the gem5 simulation will be kicked off (based upon the arguments During initialisation the gem5 simulation will be kicked off (based upon the
provided by the user) and the telnet port used by the gem5 simulation will be intercepted arguments provided by the user) and the telnet port used by the gem5
and stored for use by the :class:`Gem5Connection`. simulation will be intercepted and stored for use by the
:class:`~devlib.utils.ssh.Gem5Connection`.
:param name: Platform name :param name: Platform name
:param host_output_dir: Path on the host where the gem5 outputs will be placed (e.g. stats file) :param host_output_dir: Path on the host where the gem5 outputs will be
placed (e.g. stats file)
:param gem5_bin: gem5 binary :param gem5_bin: gem5 binary
:param gem5_args: Arguments to be passed onto gem5 such as config file etc. :param gem5_args: Arguments to be passed onto gem5 such as config file etc.
:param gem5_virtio: Arguments to be passed onto gem5 in terms of the virtIO device used :param gem5_virtio: Arguments to be passed onto gem5 in terms of the virtIO
to transfer files between the host and the gem5 simulated system. device used to transfer files between the host and the gem5 simulated
system.
:param gem5_telnet_port: Not yet in use as it would be used in future implementations :param gem5_telnet_port: Not yet in use as it would be used in future
of devlib in which the user could use the platform to pick implementations of devlib in which the user could
up an existing and running simulation. use the platform to pick up an existing and running
simulation.
.. method:: Gem5SimulationPlatform.init_target_connection([target]) .. method:: Gem5SimulationPlatform.init_target_connection([target])
Based upon the OS defined in the :class:`Target`, the type of :class:`Gem5Connection` Based upon the OS defined in the :class:`~devlib.target.Target`, the type of
will be set (:class:`AndroidGem5Connection` or :class:`AndroidGem5Connection`). :class:`~devlib.utils.ssh.Gem5Connection` will be set
(:class:`~devlib.utils.ssh.AndroidGem5Connection` or
:class:`~devlib.utils.ssh.AndroidGem5Connection`).
.. method:: Gem5SimulationPlatform.update_from_target([target]) .. method:: Gem5SimulationPlatform.update_from_target([target])
This method provides specific setup procedures for a gem5 simulation. First of all, the m5 This method provides specific setup procedures for a gem5 simulation. First
binary will be installed on the guest (if it is not present). Secondly, three methods of all, the m5 binary will be installed on the guest (if it is not present).
in the :class:`Target` will be monkey-patched: Secondly, three methods in the :class:`~devlib.target.Target` will be
monkey-patched:
- **reboot**: this is not supported in gem5 - **reboot**: this is not supported in gem5
- **reset**: this is not supported in gem5 - **reset**: this is not supported in gem5
@ -160,7 +174,7 @@ slightly to better suit gem5.
monkey-patched method will first try to monkey-patched method will first try to
transfer the existing screencaps. transfer the existing screencaps.
In case that does not work, it will fall back In case that does not work, it will fall back
to the original :class:`Target` implementation to the original :class:`~devlib.target.Target` implementation
of :func:`capture_screen`. of :func:`capture_screen`.
Finally, it will call the parent implementation of :func:`update_from_target`. Finally, it will call the parent implementation of :func:`update_from_target`.

146
doc/target.rst
View File

@ -1,57 +1,62 @@
.. module:: devlib.target
Target Target
====== ======
.. class:: Target(connection_settings=None, platform=None, working_directory=None, executables_directory=None, connect=True, modules=None, load_default_modules=True, shell_prompt=DEFAULT_SHELL_PROMPT, conn_cls=None) .. class:: Target(connection_settings=None, platform=None, working_directory=None, executables_directory=None, connect=True, modules=None, load_default_modules=True, shell_prompt=DEFAULT_SHELL_PROMPT, conn_cls=None)
:class:`Target` is the primary interface to the remote device. All interactions :class:`~devlib.target.Target` is the primary interface to the remote
with the device are performed via a :class:`Target` instance, either device. All interactions with the device are performed via a
directly, or via its modules or a wrapper interface (such as an :class:`~devlib.target.Target` instance, either directly, or via its
:class:`Instrument`). modules or a wrapper interface (such as an
:class:`~devlib.instrument.Instrument`).
:param connection_settings: A ``dict`` that specifies how to connect to the remote :param connection_settings: A ``dict`` that specifies how to connect to the
device. Its contents depend on the specific :class:`Target` type (used see remote device. Its contents depend on the specific
:class:`~devlib.target.Target` type (used see
:ref:`connection-types`\ ). :ref:`connection-types`\ ).
:param platform: A :class:`Target` defines interactions at Operating System level. A :param platform: A :class:`~devlib.target.Target` defines interactions at
:class:`Platform` describes the underlying hardware (such as CPUs Operating System level. A :class:`~devlib.platform.Platform` describes
available). If a :class:`Platform` instance is not specified on the underlying hardware (such as CPUs available). If a
:class:`Target` creation, one will be created automatically and it will :class:`~devlib.platform.Platform` instance is not specified on
dynamically probe the device to discover as much about the underlying :class:`~devlib.target.Target` creation, one will be created
hardware as it can. See also :ref:`platform`\ . automatically and it will dynamically probe the device to discover
as much about the underlying hardware as it can. See also
:ref:`platform`\ .
:param working_directory: This is primary location for on-target file system :param working_directory: This is primary location for on-target file system
interactions performed by ``devlib``. This location *must* be readable and interactions performed by ``devlib``. This location *must* be readable
writable directly (i.e. without sudo) by the connection's user account. and writable directly (i.e. without sudo) by the connection's user
It may or may not allow execution. This location will be created, account. It may or may not allow execution. This location will be
if necessary, during ``setup()``. created, if necessary, during :meth:`setup()`.
If not explicitly specified, this will be set to a default value If not explicitly specified, this will be set to a default value
depending on the type of :class:`Target` depending on the type of :class:`~devlib.target.Target`
:param executables_directory: This is the location to which ``devlib`` will :param executables_directory: This is the location to which ``devlib`` will
install executable binaries (either during ``setup()`` or via an install executable binaries (either during :meth:`setup()` or via an
explicit ``install()`` call). This location *must* support execution explicit :meth:`install()` call). This location *must* support execution
(obviously). It should also be possible to write to this location, (obviously). It should also be possible to write to this location,
possibly with elevated privileges (i.e. on a rooted Linux target, it possibly with elevated privileges (i.e. on a rooted Linux target, it
should be possible to write here with sudo, but not necessarily directly should be possible to write here with sudo, but not necessarily directly
by the connection's account). This location will be created, by the connection's account). This location will be created, if
if necessary, during ``setup()``. necessary, during :meth:`setup()`.
This location does *not* need to be same as the system's executables This location does *not* need to be same as the system's executables
location. In fact, to prevent devlib from overwriting system's defaults, location. In fact, to prevent devlib from overwriting system's defaults,
it better if this is a separate location, if possible. it better if this is a separate location, if possible.
If not explicitly specified, this will be set to a default value If not explicitly specified, this will be set to a default value
depending on the type of :class:`Target` depending on the type of :class:`~devlib.target.Target`
:param connect: Specifies whether a connections should be established to the :param connect: Specifies whether a connections should be established to the
target. If this is set to ``False``, then ``connect()`` must be target. If this is set to ``False``, then :meth:`connect()` must be
explicitly called later on before the :class:`Target` instance can be explicitly called later on before the :class:`~devlib.target.Target`
used. instance can be used.
:param modules: a list of additional modules to be installed. Some modules will :param modules: a list of additional modules to be installed. Some modules
try to install by default (if supported by the underlying target). will try to install by default (if supported by the underlying target).
Current default modules are ``hotplug``, ``cpufreq``, ``cpuidle``, Current default modules are ``hotplug``, ``cpufreq``, ``cpuidle``,
``cgroups``, and ``hwmon`` (See :ref:`modules`\ ). ``cgroups``, and ``hwmon`` (See :ref:`modules`\ ).
@ -59,40 +64,40 @@ Target
:param load_default_modules: If set to ``False``, default modules listed :param load_default_modules: If set to ``False``, default modules listed
above will *not* attempt to load. This may be used to either speed up above will *not* attempt to load. This may be used to either speed up
target instantiation (probing for initializing modules takes a bit of time) target instantiation (probing for initializing modules takes a bit of
or if there is an issue with one of the modules on a particular device time) or if there is an issue with one of the modules on a particular
(the rest of the modules will then have to be explicitly specified in device (the rest of the modules will then have to be explicitly
the ``modules``). specified in the ``modules``).
:param shell_prompt: This is a regular expression that matches the shell :param shell_prompt: This is a regular expression that matches the shell
prompted on the target. This may be used by some modules that establish prompted on the target. This may be used by some modules that establish
auxiliary connections to a target over UART. auxiliary connections to a target over UART.
:param conn_cls: This is the type of connection that will be used to communicate :param conn_cls: This is the type of connection that will be used to
with the device. communicate with the device.
.. attribute:: Target.core_names .. attribute:: Target.core_names
This is a list containing names of CPU cores on the target, in the order in This is a list containing names of CPU cores on the target, in the order in
which they are index by the kernel. This is obtained via the underlying which they are index by the kernel. This is obtained via the underlying
:class:`Platform`. :class:`~devlib.platform.Platform`.
.. attribute:: Target.core_clusters .. attribute:: Target.core_clusters
Some devices feature heterogeneous core configurations (such as ARM Some devices feature heterogeneous core configurations (such as ARM
big.LITTLE). This is a list that maps CPUs onto underlying clusters. big.LITTLE). This is a list that maps CPUs onto underlying clusters.
(Usually, but not always, clusters correspond to groups of CPUs with the same (Usually, but not always, clusters correspond to groups of CPUs with the same
name). This is obtained via the underlying :class:`Platform`. name). This is obtained via the underlying :class:`~devlib.platform.Platform`.
.. attribute:: Target.big_core .. attribute:: Target.big_core
This is the name of the cores that are the "big"s in an ARM big.LITTLE This is the name of the cores that are the "big"s in an ARM big.LITTLE
configuration. This is obtained via the underlying :class:`Platform`. configuration. This is obtained via the underlying :class:`~devlib.platform.Platform`.
.. attribute:: Target.little_core .. attribute:: Target.little_core
This is the name of the cores that are the "little"s in an ARM big.LITTLE This is the name of the cores that are the "little"s in an ARM big.LITTLE
configuration. This is obtained via the underlying :class:`Platform`. configuration. This is obtained via the underlying :class:`~devlib.platform.Platform`.
.. attribute:: Target.is_connected .. attribute:: Target.is_connected
@ -152,11 +157,11 @@ Target
The underlying connection object. This will be ``None`` if an active The underlying connection object. This will be ``None`` if an active
connection does not exist (e.g. if ``connect=False`` as passed on connection does not exist (e.g. if ``connect=False`` as passed on
initialization and ``connect()`` has not been called). initialization and :meth:`connect()` has not been called).
.. note:: a :class:`Target` will automatically create a connection per .. note:: a :class:`~devlib.target.Target` will automatically create a
thread. This will always be set to the connection for the current connection per thread. This will always be set to the connection
thread. for the current thread.
.. method:: Target.connect([timeout]) .. method:: Target.connect([timeout])
@ -176,19 +181,20 @@ Target
being executed. being executed.
This should *not* be used to establish an initial connection; use This should *not* be used to establish an initial connection; use
``connect()`` instead. :meth:`connect()` instead.
.. note:: :class:`Target` will automatically create a connection per .. note:: :class:`~devlib.target.Target` will automatically create a connection
thread, so you don't normally need to use this explicitly in per thread, so you don't normally need to use this explicitly in
threaded code. This is generally useful if you want to perform a threaded code. This is generally useful if you want to perform a
blocking operation (e.g. using ``background()``) while at the same blocking operation (e.g. using :class:`background()`) while at the same
time doing something else in the same host-side thread. time doing something else in the same host-side thread.
.. method:: Target.setup([executables]) .. method:: Target.setup([executables])
This will perform an initial one-time set up of a device for devlib This will perform an initial one-time set up of a device for devlib
interaction. This involves deployment of tools relied on the :class:`Target`, interaction. This involves deployment of tools relied on the
creation of working locations on the device, etc. :class:`~devlib.target.Target`, creation of working locations on the device,
etc.
Usually, it is enough to call this method once per new device, as its effects Usually, it is enough to call this method once per new device, as its effects
will persist across reboots. However, it is safe to call this method multiple will persist across reboots. However, it is safe to call this method multiple
@ -281,31 +287,31 @@ Target
a string. a string.
:param in_directory: execute the binary in the specified directory. This must :param in_directory: execute the binary in the specified directory. This must
be an absolute path. be an absolute path.
:param on_cpus: taskset the binary to these CPUs. This may be a single ``int`` (in which :param on_cpus: taskset the binary to these CPUs. This may be a single
case, it will be interpreted as the mask), a list of ``ints``, in which ``int`` (in which case, it will be interpreted as the mask), a list of
case this will be interpreted as the list of cpus, or string, which ``ints``, in which case this will be interpreted as the list of cpus,
will be interpreted as a comma-separated list of cpu ranges, e.g. or string, which will be interpreted as a comma-separated list of cpu
``"0,4-7"``. ranges, e.g. ``"0,4-7"``.
:param as_root: Specify whether the command should be run as root :param as_root: Specify whether the command should be run as root
:param timeout: If this is specified and invocation does not terminate within this number :param timeout: If this is specified and invocation does not terminate within this number
of seconds, an exception will be raised. of seconds, an exception will be raised.
.. method:: Target.background_invoke(binary [, args [, in_directory [, on_cpus [, as_root ]]]]) .. method:: Target.background_invoke(binary [, args [, in_directory [, on_cpus [, as_root ]]]])
Execute the specified binary on target (must already be installed) as a background Execute the specified binary on target (must already be installed) as a
task, under the specified conditions and return the :class:`subprocess.Popen` background task, under the specified conditions and return the
instance for the command. :class:`subprocess.Popen` instance for the command.
:param binary: binary to execute. Must be present and executable on the device. :param binary: binary to execute. Must be present and executable on the device.
:param args: arguments to be passed to the binary. The can be either a list or :param args: arguments to be passed to the binary. The can be either a list or
a string. a string.
:param in_directory: execute the binary in the specified directory. This must :param in_directory: execute the binary in the specified directory. This must
be an absolute path. be an absolute path.
:param on_cpus: taskset the binary to these CPUs. This may be a single ``int`` (in which :param on_cpus: taskset the binary to these CPUs. This may be a single
case, it will be interpreted as the mask), a list of ``ints``, in which ``int`` (in which case, it will be interpreted as the mask), a list of
case this will be interpreted as the list of cpus, or string, which ``ints``, in which case this will be interpreted as the list of cpus,
will be interpreted as a comma-separated list of cpu ranges, e.g. or string, which will be interpreted as a comma-separated list of cpu
``"0,4-7"``. ranges, e.g. ``"0,4-7"``.
:param as_root: Specify whether the command should be run as root :param as_root: Specify whether the command should be run as root
.. method:: Target.kick_off(command [, as_root]) .. method:: Target.kick_off(command [, as_root])
@ -361,7 +367,7 @@ Target
multiple files at once, leaving them in their original state on exit. If one multiple files at once, leaving them in their original state on exit. If one
write fails, all the already-performed writes will be reverted as well. write fails, all the already-performed writes will be reverted as well.
.. method:: Target.read_tree_values(path, depth=1, dictcls=dict, [, tar [, decode_unicode [, strip_null_char ]]]): .. method:: Target.read_tree_values(path, depth=1, dictcls=dict, [, tar [, decode_unicode [, strip_null_char ]]])
Read values of all sysfs (or similar) file nodes under ``path``, traversing Read values of all sysfs (or similar) file nodes under ``path``, traversing
up to the maximum depth ``depth``. up to the maximum depth ``depth``.
@ -386,7 +392,7 @@ Target
:param decode_unicode: decode the content of tar-ed files as utf-8 :param decode_unicode: decode the content of tar-ed files as utf-8
:param strip_null_char: remove null chars from utf-8 decoded files :param strip_null_char: remove null chars from utf-8 decoded files
.. method:: Target.read_tree_values_flat(path, depth=1): .. method:: Target.read_tree_values_flat(path, depth=1)
Read values of all sysfs (or similar) file nodes under ``path``, traversing Read values of all sysfs (or similar) file nodes under ``path``, traversing
up to the maximum depth ``depth``. up to the maximum depth ``depth``.
@ -559,10 +565,11 @@ Android Target
.. class:: AndroidTarget(connection_settings=None, platform=None, working_directory=None, executables_directory=None, connect=True, modules=None, load_default_modules=True, shell_prompt=DEFAULT_SHELL_PROMPT, conn_cls=AdbConnection, package_data_directory="/data/data") .. class:: AndroidTarget(connection_settings=None, platform=None, working_directory=None, executables_directory=None, connect=True, modules=None, load_default_modules=True, shell_prompt=DEFAULT_SHELL_PROMPT, conn_cls=AdbConnection, package_data_directory="/data/data")
:class:`AndroidTarget` is a subclass of :class:`Target` with additional features specific to a device running Android. :class:`AndroidTarget` is a subclass of :class:`~devlib.target.Target` with
additional features specific to a device running Android.
:param package_data_directory: This is the location of the data stored :param package_data_directory: This is the location of the data stored for
for installed Android packages on the device. installed Android packages on the device.
.. method:: AndroidTarget.set_rotation(rotation) .. method:: AndroidTarget.set_rotation(rotation)
@ -654,6 +661,7 @@ Android Target
otherwise returns a ``TimeoutError``. otherwise returns a ``TimeoutError``.
.. method:: AndroidTarget.reboot_bootloader(timeout=30) .. method:: AndroidTarget.reboot_bootloader(timeout=30)
Attempts to reboot the target into it's bootloader. Attempts to reboot the target into it's bootloader.
.. method:: AndroidTarget.homescreen() .. method:: AndroidTarget.homescreen()
@ -687,9 +695,9 @@ ChromeOS Target
:class:`ChromeOsTarget` if the device supports android otherwise only the :class:`ChromeOsTarget` if the device supports android otherwise only the
:class:`LinuxTarget` methods will be available. :class:`LinuxTarget` methods will be available.
:param working_directory: This is the location of the working :param working_directory: This is the location of the working directory to
directory to be used for the Linux target container. If not specified will be used for the Linux target container. If not specified will default to
default to ``"/mnt/stateful_partition/devlib-target"``. ``"/mnt/stateful_partition/devlib-target"``.
:param android_working_directory: This is the location of the working :param android_working_directory: This is the location of the working
directory to be used for the android container. If not specified it will directory to be used for the android container. If not specified it will