mirror of
https://github.com/ARM-software/workload-automation.git
synced 2024-10-06 19:01:15 +01:00
102 lines
4.2 KiB
ReStructuredText
102 lines
4.2 KiB
ReStructuredText
Additional Topics
|
|
+++++++++++++++++
|
|
|
|
Modules
|
|
=======
|
|
|
|
Modules are essentially plug-ins for Extensions. They provide a way of defining
|
|
common and reusable functionality. An Extension can load zero or more modules
|
|
during its creation. Loaded modules will then add their capabilities (see
|
|
Capabilities_) to those of the Extension. When calling code tries to access an
|
|
attribute of an Extension the Extension doesn't have, it will try to find the
|
|
attribute among its loaded modules and will return that instead.
|
|
|
|
.. note:: Modules are themselves extensions, and can therefore load their own
|
|
modules. *Do not* abuse this.
|
|
|
|
For example, calling code may wish to reboot an unresponsive device by calling
|
|
``device.hard_reset()``, but the ``Device`` in question does not have a
|
|
``hard_reset`` method; however the ``Device`` has loaded ``netio_switch``
|
|
module which allows to disable power supply over a network (say this device
|
|
is in a rack and is powered through such a switch). The module has
|
|
``reset_power`` capability (see Capabilities_ below) and so implements
|
|
``hard_reset``. This will get invoked when ``device.hard_rest()`` is called.
|
|
|
|
.. note:: Modules can only extend Extensions with new attributes; they cannot
|
|
override existing functionality. In the example above, if the
|
|
``Device`` has implemented ``hard_reset()`` itself, then *that* will
|
|
get invoked irrespective of which modules it has loaded.
|
|
|
|
If two loaded modules have the same capability or implement the same method,
|
|
then the last module to be loaded "wins" and its method will be invoke,
|
|
effectively overriding the module that was loaded previously.
|
|
|
|
Specifying Modules
|
|
------------------
|
|
|
|
Modules get loaded when an Extension is instantiated by the extension loader.
|
|
There are two ways to specify which modules should be loaded for a device.
|
|
|
|
|
|
Capabilities
|
|
============
|
|
|
|
Capabilities define the functionality that is implemented by an Extension,
|
|
either within the Extension itself or through loadable modules. A capability is
|
|
just a label, but there is an implied contract. When an Extension claims to have
|
|
a particular capability, it promises to expose a particular set of
|
|
functionality through a predefined interface.
|
|
|
|
Currently used capabilities are described below.
|
|
|
|
.. note:: Since capabilities are basically random strings, the user can always
|
|
define their own; and it is then up to the user to define, enforce and
|
|
document the contract associated with their capability. Below, are the
|
|
"standard" capabilities used in WA.
|
|
|
|
|
|
.. note:: The method signatures in the descriptions below show the calling
|
|
signature (i.e. they're omitting the initial self parameter).
|
|
|
|
active_cooling
|
|
--------------
|
|
|
|
Intended to be used by devices and device modules, this capability implies
|
|
that the device implements a controllable active cooling solution (e.g.
|
|
a programmable fan). The device/module must implement the following methods:
|
|
|
|
start_active_cooling()
|
|
Active cooling is started (e.g. the fan is turned on)
|
|
|
|
stop_active_cooling()
|
|
Active cooling is stopped (e.g. the fan is turned off)
|
|
|
|
|
|
reset_power
|
|
-----------
|
|
|
|
Intended to be used by devices and device modules, this capability implies
|
|
that the device is capable of performing a hard reset by toggling power. The
|
|
device/module must implement the following method:
|
|
|
|
hard_reset()
|
|
The device is restarted. This method cannot rely on the device being
|
|
responsive and must work even if the software on the device has crashed.
|
|
|
|
|
|
flash
|
|
-----
|
|
|
|
Intended to be used by devices and device modules, this capability implies
|
|
that the device can be flashed with new images. The device/module must
|
|
implement the following method:
|
|
|
|
flash(image_bundle=None, images=None)
|
|
``image_bundle`` is a path to a "bundle" (e.g. a tarball) that contains
|
|
all the images to be flashed. Which images go where must also be defined
|
|
within the bundle. ``images`` is a dict mapping image destination (e.g.
|
|
partition name) to the path to that specific image. Both
|
|
``image_bundle`` and ``images`` may be specified at the same time. If
|
|
there is overlap between the two, ``images`` wins and its contents will
|
|
be flashed in preference to the ``image_bundle``.
|