doc/overview.rst

Overview
========

A :class:`Target` instance serves as the main interface to the target device. 
There currently three target interfaces:

- :class:`LinuxTarget` for interacting with Linux devices over SSH.
- :class:`AndroidTraget` for interacting with Android devices over adb.
- :class:`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).


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
``connection_settings``. Code snippet below gives a typical example of
instantiating each of the three target types. 

.. code:: python

   from devlib import LocalLinuxTarget, LinuxTarget, AndroidTarget

   # Local machine requires no special connection settings.
   t1 = LocalLinuxTarget()

   # For a Linux device, you will need to provide the normal SSH credentials.
   # Both password-based, and key-based authentication is supported (password
   # authentication requires sshpass to be installed on your host machine).'
   t2 = LinuxTarget(connection_settings={'host': '192.168.0.5',
                                        'username': 'root',
                                        'password': 'sekrit',
                                        # or
                                        'keyfile': '/home/me/.ssh/id_rsa'})

   # For an Android target, you will need to pass the device name as reported
   # by "adb devices". If there is only one device visible to adb, you can omit
   # this setting and instantiate similar to a local target.
   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.

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.

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.

One-time Setup
~~~~~~~~~~~~~~

.. code:: python

   from devlib import LocalLinuxTarget
   t = LocalLinuxTarget()

   t.setup()

This sets up the target for ``devlib`` interaction. This includes creating
working directories, deploying busybox, etc. It's usually enough to do this once
for a new device, as the changes this makes will persist across reboots.
However, there is no issue with calling this multiple times, so, to be on the
safe side, it's a good idea to call this once at the beginning of your scripts.

Command Execution
~~~~~~~~~~~~~~~~~

There are several ways to execute a command on the target. In each case, a
:class:`TargetError` will be raised if something goes wrong. In each case, it is
also possible to specify ``as_root=True`` if the specified command should be
executed as root.

.. code:: python

   from devlib import LocalLinuxTarget
   t = LocalLinuxTarget()

   # Execute a command 
   output = t.execute('echo $PWD')

   # Execute command via a subprocess and return the corresponding Popen object.
   # This will block current connection to the device until the command
   # completes.
   p = t.background('echo $PWD')
   output, error = p.communicate()

   # Run the command in the background on the device and return immediately.
   # This will not block the connection, allowing to immediately execute another
   # command. 
   t.kick_off('echo $PWD')

   # This is used to invoke an executable binary on the device. This allows some
   # finer-grained control over the invocation, such as specifying the directory
   # in which the executable will run; however you're limited to a single binary
   # and cannot construct complex commands (e.g. this does not allow chaining or
   # piping several commands together).
   output = t.invoke('echo', args=['$PWD'], in_directory='/')

File Transfer
~~~~~~~~~~~~~

.. code:: python

   from devlib import LocalLinuxTarget
   t = LocalLinuxTarget()

   # "push" a file from the local machine onto the target device.
   t.push('/path/to/local/file.txt', '/path/to/target/file.txt')

   # "pull" a file from the target device into a location on the local machine
   t.pull('/path/to/target/file.txt', '/path/to/local/file.txt')

   # Install the specified binary on the target. This will deploy the file and
   # ensure it's executable. This will *not* guarantee that the binary will be 
   # in PATH. Instead the path to the binary will be returned; this should be
   # used to call the binary henceforth.
   target_bin = t.install('/path/to/local/bin.exe')
   # Example invocation:
   output = t.execute('{} --some-option'.format(target_bin))

The usual access permission constraints on the user account (both on the target
and the host) apply. 

Process Control
~~~~~~~~~~~~~~~

.. code:: python

   import signal
   from devlib import LocalLinuxTarget
   t = LocalLinuxTarget()

   # return PIDs of all running instances of a process
   pids = t.get_pids_of('sshd')

   # kill a running process. This works the same ways as the kill command, so
   # SIGTERM will be used by default.
   t.kill(666, signal=signal.SIGKILL)

   # kill all running instances of a process.
   t.killall('badexe', signal=signal.SIGKILL)

   # List processes running on the target. This returns a list of parsed
   # PsEntry records.
   entries = t.ps()
   # e.g.  print virtual memory sizes of all running sshd processes:
   print ', '.join(str(e.vsize) for e in entries if e.name == 'sshd')


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.

Super User Privileges
---------------------

It is not necessary for the account logged in on the target to have super user
privileges, however the functionality will obviously be diminished, if that is
not the case. ``devilib`` will determine if the logged in user has root
privileges and the correct way to invoke it. You should avoid including "sudo"
directly in your commands, instead, specify ``as_root=True`` where needed. This
will make your scripts portable across multiple devices and OS's.


On-Target Locations
-------------------

File system layouts vary wildly between devices and operating systems.
Hard-coding absolute paths in your scripts will mean there is a good chance they
will break if run on a different device.  To help with this, ``devlib`` defines
a couple of "standard" locations and a means of working with them.

working_directory
        This is a directory on the target readable and writable by the account
        used to log in. This should generally be used for all output generated
        by your script on the device and as the destination for all
        host-to-target file transfers. It may or may not permit execution so
        executables should not be run directly from here.
        
executables_directory
        This directory allows execution. This will be used by ``install()``.

.. code:: python

   from devlib import LocalLinuxTarget
   t = LocalLinuxTarget()

   # t.path  is equivalent to Python standard library's os.path, and should be
   # used in the same way. This insures that your scripts are portable across
   # both target and host OS variations. e.g.
   on_target_path = t.path.join(t.working_directory, 'assets.tar.gz')
   t.push('/local/path/to/assets.tar.gz', on_target_path)

   # Since working_directory is a common base path for on-target locations,
   # there a short-hand for the above:
   t.push('/local/path/to/assets.tar.gz', t.get_workpath('assets.tar.gz'))


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.

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
on target device was built without hotplug support). To check whether a module
has been successfully installed on a target, you can use ``has()`` method, e.g.

.. code:: python

   from devlib import LocalLinuxTarget
   t = LocalLinuxTarget()

   cpu0_freqs = []
   if t.has('cpufreq'):
       cpu0_freqs = t.cpufreq.list_frequencies(0)


Please see the modules documentation for more detail.


Measurement and Trace
---------------------

You can collected traces (currently, just ftrace) using
:class:`TraceCollector`\ s. For example

.. code:: python

   from devlib import AndroidTarget, FtraceCollector
   t = LocalLinuxTarget()
  
   # Initialize a collector specifying the events you want to collect and
   # the buffer size to be used.
   trace = FtraceCollector(t, events=['power*'], buffer_size=40000)

   # clear ftrace buffer
   trace.reset()

   # start trace collection
   trace.start()

   # Perform the operations you want to trace here...
   import time; time.sleep(5)

   # stop trace collection
   trace.stop()

   # extract the trace file from the target into a local file
   trace.get_trace('/tmp/trace.bin')

   # View trace file using Kernelshark (must be installed on the host).
   trace.view('/tmp/trace.bin')

   # Convert binary trace into text format. This would normally be done
   # automatically during get_trace(), unless autoreport is set to False during
   # instantiation of the trace collector.
   trace.report('/tmp/trace.bin', '/tmp/trace.txt')

In a similar way, :class:`Instrument` instances may be used to collect
measurements (such as power) from targets that support it. Please see
instruments documentation for more details.