Initial commit of open source Workload Automation.

doc/source/additional_topics.rst

@@ -0,0 +1,101 @@
+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 it's 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 it's 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``.