mirror of
https://github.com/ARM-software/devlib.git
synced 2024-10-05 18:30:50 +01:00
docs: Update to use module diretive
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
parent
7f5e0f5b4d
commit
ec0a5884c0
@ -3,16 +3,17 @@ Connection
|
||||
|
||||
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
|
||||
:class:`Target` is used in a multi-threaded environment, it will maintain a
|
||||
connection for each thread in which it is invoked. This allows the same target
|
||||
object to be used in parallel in multiple threads.
|
||||
:class:`~devlib.target.Target` is used in a multi-threaded environment, it will
|
||||
maintain a connection for each thread in which it is invoked. This allows
|
||||
the same target object to be used in parallel in multiple threads.
|
||||
|
||||
:class:`Connection`\ s will be automatically created and managed by
|
||||
:class:`Target`\ s, so there is usually no reason to create one manually.
|
||||
Instead, configuration for a :class:`Connection` is passed as
|
||||
`connection_settings` parameter when creating a :class:`Target`. The connection
|
||||
to be used target is also specified on instantiation by `conn_cls` parameter,
|
||||
though all concrete :class:`Target` implementations will set an appropriate
|
||||
:class:`~devlib.target.Target`\ s, so there is usually no reason to create one
|
||||
manually. Instead, configuration for a :class:`Connection` is passed as
|
||||
`connection_settings` parameter when creating a
|
||||
:class:`~devlib.target.Target`. The connection to be used target is also
|
||||
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.
|
||||
|
||||
: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:: 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.
|
||||
|
||||
.. method:: cancel_running_command(self)
|
||||
@ -100,6 +101,9 @@ class that implements the following methods.
|
||||
Connection Types
|
||||
----------------
|
||||
|
||||
|
||||
.. module:: devlib.utils.android
|
||||
|
||||
.. class:: AdbConnection(device=None, timeout=None, adb_server=None, adb_as_root=False)
|
||||
|
||||
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_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,\
|
||||
timeout=None, password_prompt=None, \
|
||||
@ -179,6 +184,7 @@ Connection Types
|
||||
connection to reduce the possibility of clashes).
|
||||
This parameter is ignored for SSH connections.
|
||||
|
||||
.. module:: devlib.host
|
||||
|
||||
.. class:: LocalConnection(keep_password=True, unrooted=False, password=None)
|
||||
|
||||
@ -194,6 +200,9 @@ Connection Types
|
||||
prompting for it.
|
||||
|
||||
|
||||
.. module:: devlib.utils.ssh
|
||||
:noindex:
|
||||
|
||||
.. class:: Gem5Connection(platform, host=None, username=None, password=None,\
|
||||
timeout=None, password_prompt=None,\
|
||||
original_prompt=None)
|
||||
@ -212,7 +221,7 @@ Connection Types
|
||||
will be ignored, the gem5 simulation needs to be
|
||||
on the same host the user is currently on, so if
|
||||
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.
|
||||
|
||||
: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.
|
||||
|
||||
.. method:: _login_to_device(self)
|
||||
.. method:: _login_to_device(self)
|
||||
|
||||
Login to the gem5 simulated system.
|
||||
Login to the gem5 simulated system.
|
||||
|
||||
.. class:: AndroidGem5Connection
|
||||
|
||||
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.
|
||||
|
||||
@ -1,7 +1,6 @@
|
||||
Derived Measurements
|
||||
=====================
|
||||
|
||||
|
||||
The ``DerivedMeasurements`` API provides a consistent way of performing post
|
||||
processing on a provided :class:`MeasurementCsv` file.
|
||||
|
||||
@ -35,6 +34,8 @@ API
|
||||
Derived Measurements
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. module:: devlib.derived
|
||||
|
||||
.. class:: DerivedMeasurements
|
||||
|
||||
The ``DerivedMeasurements`` class provides an API for post-processing
|
||||
@ -102,17 +103,20 @@ Available Derived Measurements
|
||||
Energy
|
||||
~~~~~~
|
||||
|
||||
.. module:: devlib.derived.energy
|
||||
|
||||
.. class:: DerivedEnergyMeasurements
|
||||
|
||||
The ``DerivedEnergyMeasurements`` class is used to calculate average power and
|
||||
cumulative energy for each site if the required data is present.
|
||||
The ``DerivedEnergyMeasurements`` class is used to calculate average power
|
||||
and cumulative energy for each site if the required data is present.
|
||||
|
||||
The calculation of cumulative energy can occur in 3 ways. If a
|
||||
``site`` contains ``energy`` results, the first and last measurements are extracted
|
||||
and the delta calculated. If not, a ``timestamp`` channel will be used to calculate
|
||||
the energy from the power channel, failing back to using the sample rate attribute
|
||||
of the :class:`MeasurementCsv` file if timestamps are not available. If neither
|
||||
timestamps or a sample rate are available then an error will be raised.
|
||||
The calculation of cumulative energy can occur in 3 ways. If a ``site``
|
||||
contains ``energy`` results, the first and last measurements are extracted
|
||||
and the delta calculated. If not, a ``timestamp`` channel will be used to
|
||||
calculate the energy from the power channel, failing back to using the sample
|
||||
rate attribute of the :class:`MeasurementCsv` file if timestamps are not
|
||||
available. If neither timestamps or a sample rate are available then an error
|
||||
will be raised.
|
||||
|
||||
|
||||
.. method:: DerivedEnergyMeasurements.process(measurement_csv)
|
||||
@ -128,6 +132,8 @@ Energy
|
||||
FPS / Rendering
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. module:: devlib.derived.fps
|
||||
|
||||
.. class:: DerivedGfxInfoStats(drop_threshold=5, suffix='-fps', filename=None, outdir=None)
|
||||
|
||||
Produces FPS (frames-per-second) and other derived statistics from
|
||||
|
||||
@ -3,6 +3,8 @@
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
.. module:: devlib
|
||||
|
||||
Welcome to devlib documentation
|
||||
===============================
|
||||
|
||||
|
||||
@ -5,9 +5,9 @@ Instrumentation
|
||||
|
||||
The ``Instrument`` API provide a consistent way of collecting measurements from
|
||||
a target. Measurements are collected via an instance of a class derived from
|
||||
:class:`Instrument`. An ``Instrument`` allows collection of measurement from one
|
||||
or more channels. An ``Instrument`` may support ``INSTANTANEOUS`` or
|
||||
``CONTINUOUS`` collection, or both.
|
||||
:class:`~devlib.instrument.Instrument`. An ``Instrument`` allows collection of
|
||||
measurement from one or more channels. An ``Instrument`` may support
|
||||
``INSTANTANEOUS`` or ``CONTINUOUS`` collection, or both.
|
||||
|
||||
Example
|
||||
-------
|
||||
@ -50,6 +50,8 @@ Android target.
|
||||
API
|
||||
---
|
||||
|
||||
.. module:: devlib.instrument
|
||||
|
||||
Instrument
|
||||
~~~~~~~~~~
|
||||
|
||||
@ -122,14 +124,16 @@ Instrument
|
||||
Take a single measurement from ``active_channels``. Returns a list of
|
||||
: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.
|
||||
|
||||
.. method:: Instrument.start()
|
||||
|
||||
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.
|
||||
|
||||
.. method:: Instrument.stop()
|
||||
@ -137,7 +141,8 @@ Instrument
|
||||
Stops collecting measurements from ``active_channels``. Must be called after
|
||||
: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.
|
||||
|
||||
.. method:: Instrument.get_data(outfile)
|
||||
@ -148,9 +153,9 @@ Instrument
|
||||
``<site>_<kind>`` (see :class:`InstrumentChannel`). The order of the columns
|
||||
will be the same as the order of channels in ``Instrument.active_channels``.
|
||||
|
||||
If reporting timestamps, one channel must have a ``site`` named ``"timestamp"``
|
||||
and a ``kind`` of a :class:`MeasurmentType` of an appropriate time unit which will
|
||||
be used, if appropriate, during any post processing.
|
||||
If reporting timestamps, one channel must have a ``site`` named
|
||||
``"timestamp"`` and a ``kind`` of a :class:`MeasurmentType` of an appropriate
|
||||
time unit which will be used, if appropriate, during any post processing.
|
||||
|
||||
.. note:: Currently supported time units are seconds, milliseconds and
|
||||
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
|
||||
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.
|
||||
|
||||
.. method:: Instrument.get_raw()
|
||||
@ -185,7 +191,8 @@ Instrument
|
||||
|
||||
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.
|
||||
|
||||
Instrument Channel
|
||||
@ -194,8 +201,8 @@ Instrument Channel
|
||||
.. class:: InstrumentChannel(name, site, measurement_type, \*\*attrs)
|
||||
|
||||
An :class:`InstrumentChannel` describes a single type of measurement that may
|
||||
be collected by an :class:`Instrument`. A channel is primarily defined by a
|
||||
``site`` and a ``measurement_type``.
|
||||
be collected by an :class:`~devlib.instrument.Instrument`. A channel is
|
||||
primarily defined by a ``site`` and a ``measurement_type``.
|
||||
|
||||
A ``site`` indicates where on the target a measurement is collected from
|
||||
(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.
|
||||
|
||||
As described below (:meth:`BaylibreAcmeInstrument.reset`), the integration
|
||||
times for the bus and shunt voltage can be set separately which allows a
|
||||
tradeoff of accuracy between signals. This is particularly useful as the shunt
|
||||
voltage returned by the INA226 has a higher resolution than the bus voltage
|
||||
(2.5 μV and 1.25 mV LSB, respectively) and therefore would benefit more from a
|
||||
longer integration time.
|
||||
As described below (:meth:`BaylibreAcmeInstrument.reset
|
||||
<devlib.instrument.baylibre_acme.BaylibreAcmeInstrument.reset>`), the
|
||||
integration times for the bus and shunt voltage can be set separately which
|
||||
allows a tradeoff of accuracy between signals. This is particularly useful as
|
||||
the shunt voltage returned by the INA226 has a higher resolution than the bus
|
||||
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
|
||||
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
|
||||
buffer which is sent back to the host once it is full (see
|
||||
``buffer_samples_count`` in :meth:`BaylibreAcmeInstrument.setup` for setting
|
||||
its size). Therefore, the larger the buffer is, the longer it takes to be
|
||||
``buffer_samples_count`` in :meth:`BaylibreAcmeInstrument.setup
|
||||
<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
|
||||
this, consider the following graphs showing the time difference between
|
||||
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
|
||||
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)
|
||||
|
||||
Base class wrapper for the ACME instrument which itself is a wrapper for the
|
||||
|
||||
@ -1,11 +1,13 @@
|
||||
.. module:: devlib.module
|
||||
|
||||
.. _modules:
|
||||
|
||||
Modules
|
||||
=======
|
||||
|
||||
Modules add additional functionality to the core :class:`Target` interface.
|
||||
Usually, it is support for specific subsystems on the target. Modules are
|
||||
instantiated as attributes of the :class:`Target` instance.
|
||||
Modules add additional functionality to the core :class:`~devlib.target.Target`
|
||||
interface. Usually, it is support for specific subsystems on the target. Modules
|
||||
are instantiated as attributes of the :class:`~devlib.target.Target` instance.
|
||||
|
||||
hotplug
|
||||
-------
|
||||
@ -28,6 +30,8 @@ interface to this subsystem
|
||||
# Make sure all cpus are online
|
||||
target.hotplug.online_all()
|
||||
|
||||
.. module:: devlib.module.cpufreq
|
||||
|
||||
cpufreq
|
||||
-------
|
||||
|
||||
@ -132,6 +136,9 @@ policies (governors). The ``devlib`` module exposes the following interface
|
||||
``1`` or ``"cpu1"``).
|
||||
:param frequency: Frequency to set.
|
||||
|
||||
|
||||
.. module:: devlib.module.cupidle
|
||||
|
||||
cpuidle
|
||||
-------
|
||||
|
||||
@ -167,11 +174,15 @@ cpuidle
|
||||
You can also call ``enable()`` or ``disable()`` on :class:`CpuidleState` objects
|
||||
returned by get_state(s).
|
||||
|
||||
.. module:: devlib.module.cgroups
|
||||
|
||||
cgroups
|
||||
-------
|
||||
|
||||
TODO
|
||||
|
||||
.. module:: devlib.module.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
|
||||
that it may or may not be necessary for a particular application).
|
||||
|
||||
Every module (ultimately) derives from :class:`Module` class. A module must
|
||||
define the following class attributes:
|
||||
Every module (ultimately) derives from :class:`devlib.module.Module` class. A
|
||||
module must define the following class attributes:
|
||||
|
||||
: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.
|
||||
@ -204,14 +215,16 @@ define the following class attributes:
|
||||
which case the module's ``name`` will be treated as its
|
||||
``kind`` as well.
|
||||
|
||||
:stage: This defines when the module will be installed into a :class:`Target`.
|
||||
Currently, the following values are allowed:
|
||||
:stage: This defines when the module will be installed into a
|
||||
:class:`~devlib.target.Target`. Currently, the following values are
|
||||
allowed:
|
||||
|
||||
:connected: The module is installed after a connection to the target has
|
||||
been established. This is the default.
|
||||
:early: The module will be installed when a :class:`Target` is first
|
||||
created. This should be used for modules that do not rely on a
|
||||
live connection to the target.
|
||||
:early: The module will be installed when a
|
||||
:class:`~devlib.target.Target` is first created. This should be
|
||||
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
|
||||
has been performed. This allows the module to utilize assets
|
||||
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)
|
||||
|
||||
This method takes a :class:`Target` instance and returns ``True`` if this
|
||||
module is supported by that target, or ``False`` otherwise.
|
||||
This method takes a :class:`~devlib.target.Target` instance and returns
|
||||
``True`` if this module is supported by that target, or ``False`` otherwise.
|
||||
|
||||
.. note:: If the module ``stage`` is ``"early"``, this method cannot assume
|
||||
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
|
||||
:class:`Target` instance being the sole argument) and assign it to the target
|
||||
instance attribute named after the module's ``kind`` (or ``name`` if ``kind`` is
|
||||
``None``).
|
||||
:class:`~devlib.target.Target` instance being the sole argument) and assign it
|
||||
to the target instance attribute named after the module's ``kind`` (or
|
||||
``name`` if ``kind`` is ``None``).
|
||||
|
||||
It is possible to change the installation procedure for a module by overriding
|
||||
the default :func:`install` method. The method must have the following
|
||||
@ -344,10 +357,11 @@ FlashModule
|
||||
Module Registration
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Modules are specified on :class:`Target` or :class:`Platform` creation by name.
|
||||
In order to find the class associated with the name, the module needs to be
|
||||
registered with ``devlib``. This is accomplished by passing the module class
|
||||
into :func:`register_module` method once it is defined.
|
||||
Modules are specified on :class:`~devlib.target.Target` or
|
||||
:class:`~devlib.platform.Platform` creation by name. In order to find the class
|
||||
associated with the name, the module needs to be registered with ``devlib``.
|
||||
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
|
||||
base, you can place the file with the module class under
|
||||
|
||||
@ -1,25 +1,26 @@
|
||||
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:
|
||||
|
||||
- :class:`LinuxTarget` for interacting with Linux devices over SSH.
|
||||
- :class:`AndroidTarget` for interacting with Android devices over adb.
|
||||
- :class:`ChromeOsTarget`: for interacting with ChromeOS devices over SSH, and their Android containers over adb.
|
||||
- :class:`LocalLinuxTarget`: for interacting with the local Linux host.
|
||||
- :class:`~devlib.target.LinuxTarget` for interacting with Linux devices over SSH.
|
||||
- :class:`~devlib.target.AndroidTarget` for interacting with Android devices over adb.
|
||||
- :class:`~devlib.target.ChromeOsTarget`: for interacting with ChromeOS devices
|
||||
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
|
||||
how connection settings are specified; though there may also be a few APIs
|
||||
specific to a particular target type (e.g. :class:`AndroidTarget` exposes
|
||||
methods for working with logcat).
|
||||
specific to a particular target type (e.g. :class:`~devlib.target.AndroidTarget`
|
||||
exposes methods for working with logcat).
|
||||
|
||||
|
||||
Acquiring a Target
|
||||
------------------
|
||||
|
||||
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
|
||||
instantiating each of the three target types.
|
||||
|
||||
@ -46,21 +47,22 @@ instantiating each of the three target types.
|
||||
t3 = AndroidTarget(connection_settings={'device': '0123456789abcde'})
|
||||
|
||||
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
|
||||
create a :class:`Target` instance but not immediately connect to the remote
|
||||
device, you can pass ``connect=False`` parameter. If you do that, you would have
|
||||
to then explicitly call ``t.connect()`` before you can interact with the device.
|
||||
queried to initialize :class:`~devlib.target.Target`'s internal state. If you
|
||||
would like to create a :class:`~devlib.target.Target` instance but not
|
||||
immediately connect to the remote device, you can pass ``connect=False``
|
||||
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
|
||||
``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
|
||||
----------------
|
||||
|
||||
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
|
||||
more detailed documentation.
|
||||
:class:`~devlib.target.Target` API documentation for the full list of supported
|
||||
methods and more detailed documentation.
|
||||
|
||||
One-time Setup
|
||||
~~~~~~~~~~~~~~
|
||||
@ -173,8 +175,9 @@ More...
|
||||
~~~~~~~
|
||||
|
||||
As mentioned previously, the above is not intended to be exhaustive
|
||||
documentation of the :class:`Target` interface. Please refer to the API
|
||||
documentation for the full list of attributes and methods and their parameters.
|
||||
documentation of the :class:`~devlib.target.Target` interface. Please refer to
|
||||
the API documentation for the full list of attributes and methods and their
|
||||
parameters.
|
||||
|
||||
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:
|
||||
|
||||
.. module:: devlib.exception
|
||||
|
||||
- :class:`DevlibError`
|
||||
|
||||
- :class:`WorkerThreadError`
|
||||
@ -287,7 +292,7 @@ Modules
|
||||
Additional functionality is exposed via modules. Modules are initialized as
|
||||
attributes of a target instance. By default, ``hotplug``, ``cpufreq``,
|
||||
``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
|
||||
underlying platform does not support particular functionality (e.g. the kernel
|
||||
|
||||
@ -1,14 +1,17 @@
|
||||
.. module:: devlib.platform
|
||||
|
||||
.. _platform:
|
||||
|
||||
Platform
|
||||
========
|
||||
|
||||
:class:`Platform`\ s describe the system underlying the OS. They encapsulate
|
||||
hardware- and firmware-specific details. In most cases, the generic
|
||||
:class:`Platform` class, which gets used if a platform is not explicitly
|
||||
specified on :class:`Target` creation, will be sufficient. It will automatically
|
||||
query as much platform information (such CPU topology, hardware model, etc) if
|
||||
it was not specified explicitly by the user.
|
||||
:class:`~devlib.platform.Platform`\ s describe the system underlying the OS.
|
||||
They encapsulate hardware- and firmware-specific details. In most cases, the
|
||||
generic :class:`~devlib.platform.Platform` class, which gets used if a
|
||||
platform is not explicitly specified on :class:`~devlib.target.Target`
|
||||
creation, will be sufficient. It will automatically query as much platform
|
||||
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,\
|
||||
@ -31,6 +34,7 @@ it was not specified explicitly by the user.
|
||||
platform (e.g. for handling flashing, rebooting, etc). These
|
||||
would be added to the Target's modules. (See :ref:`modules`\ ).
|
||||
|
||||
.. module:: devlib.platform.arm
|
||||
|
||||
Versatile Express
|
||||
-----------------
|
||||
@ -38,8 +42,8 @@ Versatile Express
|
||||
The generic platform may be extended to support hardware- or
|
||||
infrastructure-specific functionality. Platforms exist for ARM
|
||||
VersatileExpress-based :class:`Juno` and :class:`TC2` development boards. In
|
||||
addition to the standard :class:`Platform` parameters above, these platforms
|
||||
support additional configuration:
|
||||
addition to the standard :class:`~devlib.platform.Platform` parameters above,
|
||||
these platforms support additional configuration:
|
||||
|
||||
|
||||
.. class:: VersatileExpressPlatform
|
||||
@ -116,43 +120,53 @@ support additional configuration:
|
||||
Gem5 Simulation Platform
|
||||
------------------------
|
||||
|
||||
By initialising a Gem5SimulationPlatform, devlib will start a gem5 simulation (based upon the
|
||||
arguments the user provided) and then connect to it using :class:`Gem5Connection`.
|
||||
Using the methods discussed above, some methods of the :class:`Target` will be altered
|
||||
slightly to better suit gem5.
|
||||
By initialising a Gem5SimulationPlatform, devlib will start a gem5 simulation
|
||||
(based upon the arguments the user provided) and then connect to it using
|
||||
:class:`~devlib.utils.ssh.Gem5Connection`. Using the methods discussed above,
|
||||
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)
|
||||
|
||||
During initialisation the gem5 simulation will be kicked off (based upon the arguments
|
||||
provided by the user) and the telnet port used by the gem5 simulation will be intercepted
|
||||
and stored for use by the :class:`Gem5Connection`.
|
||||
During initialisation the gem5 simulation will be kicked off (based upon the
|
||||
arguments provided by the user) and the telnet port used by the gem5
|
||||
simulation will be intercepted and stored for use by the
|
||||
:class:`~devlib.utils.ssh.Gem5Connection`.
|
||||
|
||||
: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_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
|
||||
to transfer files between the host and the gem5 simulated system.
|
||||
:param gem5_virtio: Arguments to be passed onto gem5 in terms of the virtIO
|
||||
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
|
||||
of devlib in which the user could use the platform to pick
|
||||
up an existing and running simulation.
|
||||
:param gem5_telnet_port: Not yet in use as it would be used in future
|
||||
implementations of devlib in which the user could
|
||||
use the platform to pick up an existing and running
|
||||
simulation.
|
||||
|
||||
|
||||
.. method:: Gem5SimulationPlatform.init_target_connection([target])
|
||||
|
||||
Based upon the OS defined in the :class:`Target`, the type of :class:`Gem5Connection`
|
||||
will be set (:class:`AndroidGem5Connection` or :class:`AndroidGem5Connection`).
|
||||
Based upon the OS defined in the :class:`~devlib.target.Target`, the type of
|
||||
: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])
|
||||
|
||||
This method provides specific setup procedures for a gem5 simulation. First of all, the m5
|
||||
binary will be installed on the guest (if it is not present). Secondly, three methods
|
||||
in the :class:`Target` will be monkey-patched:
|
||||
This method provides specific setup procedures for a gem5 simulation. First
|
||||
of all, the m5 binary will be installed on the guest (if it is not present).
|
||||
Secondly, three methods in the :class:`~devlib.target.Target` will be
|
||||
monkey-patched:
|
||||
|
||||
- **reboot**: 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
|
||||
transfer the existing screencaps.
|
||||
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`.
|
||||
|
||||
Finally, it will call the parent implementation of :func:`update_from_target`.
|
||||
|
||||
146
doc/target.rst
146
doc/target.rst
@ -1,57 +1,62 @@
|
||||
.. module:: devlib.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` is the primary interface to the remote device. All interactions
|
||||
with the device are performed via a :class:`Target` instance, either
|
||||
directly, or via its modules or a wrapper interface (such as an
|
||||
:class:`Instrument`).
|
||||
:class:`~devlib.target.Target` is the primary interface to the remote
|
||||
device. All interactions with the device are performed via a
|
||||
:class:`~devlib.target.Target` instance, either directly, or via its
|
||||
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
|
||||
device. Its contents depend on the specific :class:`Target` type (used see
|
||||
:param connection_settings: A ``dict`` that specifies how to connect to the
|
||||
remote device. Its contents depend on the specific
|
||||
:class:`~devlib.target.Target` type (used see
|
||||
:ref:`connection-types`\ ).
|
||||
|
||||
:param platform: A :class:`Target` defines interactions at Operating System level. A
|
||||
:class:`Platform` describes the underlying hardware (such as CPUs
|
||||
available). If a :class:`Platform` instance is not specified on
|
||||
:class:`Target` creation, one will be created automatically and it will
|
||||
dynamically probe the device to discover as much about the underlying
|
||||
hardware as it can. See also :ref:`platform`\ .
|
||||
:param platform: A :class:`~devlib.target.Target` defines interactions at
|
||||
Operating System level. A :class:`~devlib.platform.Platform` describes
|
||||
the underlying hardware (such as CPUs available). If a
|
||||
:class:`~devlib.platform.Platform` instance is not specified on
|
||||
:class:`~devlib.target.Target` creation, one will be created
|
||||
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
|
||||
interactions performed by ``devlib``. This location *must* be readable and
|
||||
writable directly (i.e. without sudo) by the connection's user account.
|
||||
It may or may not allow execution. This location will be created,
|
||||
if necessary, during ``setup()``.
|
||||
interactions performed by ``devlib``. This location *must* be readable
|
||||
and writable directly (i.e. without sudo) by the connection's user
|
||||
account. It may or may not allow execution. This location will be
|
||||
created, if necessary, during :meth:`setup()`.
|
||||
|
||||
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
|
||||
install executable binaries (either during ``setup()`` or via an
|
||||
explicit ``install()`` call). This location *must* support execution
|
||||
install executable binaries (either during :meth:`setup()` or via an
|
||||
explicit :meth:`install()` call). This location *must* support execution
|
||||
(obviously). It should also be possible to write to this location,
|
||||
possibly with elevated privileges (i.e. on a rooted Linux target, it
|
||||
should be possible to write here with sudo, but not necessarily directly
|
||||
by the connection's account). This location will be created,
|
||||
if necessary, during ``setup()``.
|
||||
by the connection's account). This location will be created, if
|
||||
necessary, during :meth:`setup()`.
|
||||
|
||||
This location does *not* need to be same as the system's executables
|
||||
location. In fact, to prevent devlib from overwriting system's defaults,
|
||||
it better if this is a separate location, if possible.
|
||||
|
||||
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
|
||||
target. If this is set to ``False``, then ``connect()`` must be
|
||||
explicitly called later on before the :class:`Target` instance can be
|
||||
used.
|
||||
target. If this is set to ``False``, then :meth:`connect()` must be
|
||||
explicitly called later on before the :class:`~devlib.target.Target`
|
||||
instance can be used.
|
||||
|
||||
:param modules: a list of additional modules to be installed. Some modules will
|
||||
try to install by default (if supported by the underlying target).
|
||||
:param modules: a list of additional modules to be installed. Some modules
|
||||
will try to install by default (if supported by the underlying target).
|
||||
Current default modules are ``hotplug``, ``cpufreq``, ``cpuidle``,
|
||||
``cgroups``, and ``hwmon`` (See :ref:`modules`\ ).
|
||||
|
||||
@ -59,40 +64,40 @@ Target
|
||||
|
||||
: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
|
||||
target instantiation (probing for initializing modules takes a bit of time)
|
||||
or if there is an issue with one of the modules on a particular device
|
||||
(the rest of the modules will then have to be explicitly specified in
|
||||
the ``modules``).
|
||||
target instantiation (probing for initializing modules takes a bit of
|
||||
time) or if there is an issue with one of the modules on a particular
|
||||
device (the rest of the modules will then have to be explicitly
|
||||
specified in the ``modules``).
|
||||
|
||||
: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
|
||||
auxiliary connections to a target over UART.
|
||||
|
||||
:param conn_cls: This is the type of connection that will be used to communicate
|
||||
with the device.
|
||||
:param conn_cls: This is the type of connection that will be used to
|
||||
communicate with the device.
|
||||
|
||||
.. attribute:: Target.core_names
|
||||
|
||||
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
|
||||
:class:`Platform`.
|
||||
:class:`~devlib.platform.Platform`.
|
||||
|
||||
.. attribute:: Target.core_clusters
|
||||
|
||||
Some devices feature heterogeneous core configurations (such as ARM
|
||||
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
|
||||
name). This is obtained via the underlying :class:`Platform`.
|
||||
name). This is obtained via the underlying :class:`~devlib.platform.Platform`.
|
||||
|
||||
.. attribute:: Target.big_core
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
@ -152,11 +157,11 @@ Target
|
||||
|
||||
The underlying connection object. This will be ``None`` if an active
|
||||
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
|
||||
thread. This will always be set to the connection for the current
|
||||
thread.
|
||||
.. note:: a :class:`~devlib.target.Target` will automatically create a
|
||||
connection per thread. This will always be set to the connection
|
||||
for the current thread.
|
||||
|
||||
.. method:: Target.connect([timeout])
|
||||
|
||||
@ -176,19 +181,20 @@ Target
|
||||
being executed.
|
||||
|
||||
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
|
||||
thread, so you don't normally need to use this explicitly in
|
||||
.. note:: :class:`~devlib.target.Target` will automatically create a connection
|
||||
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
|
||||
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.
|
||||
|
||||
.. method:: Target.setup([executables])
|
||||
|
||||
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`,
|
||||
creation of working locations on the device, etc.
|
||||
interaction. This involves deployment of tools relied on the
|
||||
: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
|
||||
will persist across reboots. However, it is safe to call this method multiple
|
||||
@ -281,31 +287,31 @@ Target
|
||||
a string.
|
||||
:param in_directory: execute the binary in the specified directory. This must
|
||||
be an absolute path.
|
||||
:param on_cpus: taskset the binary to these CPUs. This may be a single ``int`` (in which
|
||||
case, it will be interpreted as the mask), a list of ``ints``, in which
|
||||
case this will be interpreted as the list of cpus, or string, which
|
||||
will be interpreted as a comma-separated list of cpu ranges, e.g.
|
||||
``"0,4-7"``.
|
||||
:param on_cpus: taskset the binary to these CPUs. This may be a single
|
||||
``int`` (in which case, it will be interpreted as the mask), a list of
|
||||
``ints``, in which case this will be interpreted as the list of cpus,
|
||||
or string, which will be interpreted as a comma-separated list of cpu
|
||||
ranges, e.g. ``"0,4-7"``.
|
||||
: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
|
||||
of seconds, an exception will be raised.
|
||||
|
||||
.. 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
|
||||
task, under the specified conditions and return the :class:`subprocess.Popen`
|
||||
instance for the command.
|
||||
Execute the specified binary on target (must already be installed) as a
|
||||
background task, under the specified conditions and return the
|
||||
:class:`subprocess.Popen` instance for the command.
|
||||
|
||||
: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
|
||||
a string.
|
||||
:param in_directory: execute the binary in the specified directory. This must
|
||||
be an absolute path.
|
||||
:param on_cpus: taskset the binary to these CPUs. This may be a single ``int`` (in which
|
||||
case, it will be interpreted as the mask), a list of ``ints``, in which
|
||||
case this will be interpreted as the list of cpus, or string, which
|
||||
will be interpreted as a comma-separated list of cpu ranges, e.g.
|
||||
``"0,4-7"``.
|
||||
:param on_cpus: taskset the binary to these CPUs. This may be a single
|
||||
``int`` (in which case, it will be interpreted as the mask), a list of
|
||||
``ints``, in which case this will be interpreted as the list of cpus,
|
||||
or string, which will be interpreted as a comma-separated list of cpu
|
||||
ranges, e.g. ``"0,4-7"``.
|
||||
:param as_root: Specify whether the command should be run 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
|
||||
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
|
||||
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 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
|
||||
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` 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
|
||||
for installed Android packages on the device.
|
||||
:param package_data_directory: This is the location of the data stored for
|
||||
installed Android packages on the device.
|
||||
|
||||
.. method:: AndroidTarget.set_rotation(rotation)
|
||||
|
||||
@ -654,6 +661,7 @@ Android Target
|
||||
otherwise returns a ``TimeoutError``.
|
||||
|
||||
.. method:: AndroidTarget.reboot_bootloader(timeout=30)
|
||||
|
||||
Attempts to reboot the target into it's bootloader.
|
||||
|
||||
.. method:: AndroidTarget.homescreen()
|
||||
@ -687,9 +695,9 @@ ChromeOS Target
|
||||
:class:`ChromeOsTarget` if the device supports android otherwise only the
|
||||
:class:`LinuxTarget` methods will be available.
|
||||
|
||||
:param working_directory: This is the location of the working
|
||||
directory to be used for the Linux target container. If not specified will
|
||||
default to ``"/mnt/stateful_partition/devlib-target"``.
|
||||
:param working_directory: This is the location of the working directory to
|
||||
be used for the Linux target container. If not specified will default to
|
||||
``"/mnt/stateful_partition/devlib-target"``.
|
||||
|
||||
:param android_working_directory: This is the location of the working
|
||||
directory to be used for the android container. If not specified it will
|
||||
|
||||
Loading…
Reference in New Issue
Block a user