diff --git a/doc/source/api/output.rst b/doc/source/api/output.rst index 7f20fcb8..e4212ea1 100644 --- a/doc/source/api/output.rst +++ b/doc/source/api/output.rst @@ -1,3 +1,5 @@ +.. _output_processing_api: + Output ====== @@ -441,3 +443,95 @@ description classifiers Job- and run-level :term:`classifier`\ s will be propagated to the artifact. + + +Additional run info +------------------- + +:class:`RunOutput` object has ``target_info`` and ``run_info`` attributes that +contain structures that provide additional information about the run and device. + +.. _target-info-api: + +:class:`TargetInfo` +~~~~~~~~~~~~~~~~~~~ + +The :class:`TargetInfo` class presents various pieces of information about the +target device. An instance of this class will be instantiated and populated +automatically from the devlib `target +`_ created during a WA run +and serialized to a json file as part of the metadata exported +by WA at the end of a run. + +The available attributes of the class are as follows: + +target + The name of the target class that was uised ot interact with the device + during the run E.g. ``"AndroidTarget"``, ``"LinuxTarget"`` etc. + +cpus + A list of :class:`CpuInfo` objects describing the capabilities of each CPU. + +os + A generic name of the OS the target was running (e.g. ``"android"``). + +os_version + A dict that contains a mapping of OS version elements to their values. This + mapping is OS-specific. + +abi + The ABI of the target device. + +hostname + The hostname of the the device the run was executed on. + +is_rooted + A boolean value specifying whether root was detected on the device. + +kernel_version + The version of the kernel on the target device. This returns a + :class:`KernelVersion` instance that has separate version and release + fields. + +kernel_config + A :class:`KernelConfig` instance that contains parsed kernel config from the + target device. This may be ``None`` if the kernel config could not be + extracted. + +sched_features + A list of the available tweaks to the scheduler, if available from the + device. + +hostid + The unique identifier of the particular device the WA run was executed on. + + +.. _run-info-api: + +:class:`RunInfo` +~~~~~~~~~~~~~~~~ + +The :class:`RunInfo` provides general run information. It has the following +attributes: + + +uuid + A unique identifier for that particular run. + +run_name + The name of the run (if provided) + +project + The name of the project the run belongs to (if provided) + +project_stage + The project stage the run is associated with (if provided) + +duration + The length of time the run took to complete. + +start_time + The time the run was stared. + +end_time + The time at which the run finished. diff --git a/doc/source/developer_reference.rst b/doc/source/developer_reference.rst index 3bac067d..fdf74173 100644 --- a/doc/source/developer_reference.rst +++ b/doc/source/developer_reference.rst @@ -14,10 +14,6 @@ Developer Reference ----------------- -.. include:: developer_reference/APIs.rst - ------------------ - .. include:: developer_reference/writing_plugins.rst ----------------- diff --git a/doc/source/developer_reference/APIs.rst b/doc/source/developer_reference/APIs.rst deleted file mode 100644 index 3dd996f5..00000000 --- a/doc/source/developer_reference/APIs.rst +++ /dev/null @@ -1,114 +0,0 @@ -APIs -==== - -.. _output_processing_api: - -Output Processing API ---------------------- - -WA3 now has an output API that can be used to post process a runs -:ref:`Output Directory Structure ` which can be performed by using WA's -:class:`RunOutput` object. - -This object provides a simple way to access the various aspects of the run. A -few of the most useful attributes of the ``RunOutput`` object are as follows: - -- :confval:`jobs` - A list of all the job outputs that were generated for the - run. These can be used to used to access more detailed information about - individual jobs for example their ``status``, any ``metrics`` or ``artifacts`` - that were generated etc. -- :confval:`run_config` - A :ref:`RunConfiguration ` object - that can be used to access all the configuration of the run itself, for - example the ``reboot_policy``, ``execution_order``, ``device_config`` etc. -- :confval:`target_info` - A :ref:`TargetInfo ` object which can be used to - access various information about the target that was used during the run for - example it's ``abi``, ``hostname``, ``os`` etc. -- :confval:`info` - A :ref:`RunInfo ` object that contains - information about the run itself for example it's duration, name, uuid etc. -- :confval:`settings` - The :ref:`Meta Configuration ` used - during the run. -- :confval:`status` - The overall status of the run. -- :confval:`artifacts` - A list containing any run level artifacts (for example - logs, output generated by output processors etc.). -- :confval:`metrics` - A list of :ref:`Metrics ` that were generated - for the overall run. -- :confval:`classifiers` - A dict mapping of any run level - :ref:`classifiers `. -- :confval:`augmentations` - A list of the augmentations that were enabled - during the run. -- :confval:`event_summary` - A condensed summary of any events that occurred - during the run. -- :confval:`events` - A list of any events that occurred during the run like job - failures etc. -- :confval:`basepath` - The name of the base WA output directory. -- :confval:`configfile` - The relative file path to the config file generated - for the run. -- :confval:`failed_dir` - The relative file path to the directory containing any - failed jobs during the run. -- :confval:`infofile` - The file location of the json serialized file of the - :class:`RunInfo` object. -- :confval:`list_workloads()` - A method that generated a list of the workload - names that were executed during the run. -- :confval:`logfile` - A relative file path to the run log. -- :confval:`metadir` - A relative file path to the metadata directory. -- :confval:`targetfile` - The file location of the json serialized file of the - :class:`TargetInfo` object. - -.. include:: developer_reference/output_processing_example.rst - ---------------------- - -.. _target-info-api: - -TargetInfo API ---------------- - -The :class:`TargetInfo` class is designed to provide an easy way of presenting -various pieces of information about the target device. An instance of this class -will be instantiated and populated automatically from the devlib -`target `_ created -during a WA run and serialized to a json file as part of the metadata exported -by WA at the end of a run. - -The available attributes of the class are as follows: - -- :confval:`target` - The name of the target that was created. E.g. - AndroidTarget, LinuxTarget etc. -- :confval:`cpus` - A list of the unique cpu types that have been detected on - the target. E.g. 'A53', 'A72' etc. -- :confval:`os` - The OS that the target was running. -- :confval:`os_version` - A dict that contains a mapping of OS version elements - to their values. This mapping is OS-specific. -- :confval:`abi` - The ABI of the target device. -- :confval:`hostname` - The hostname of the the device the run was executed on. -- :confval:`is_rooted` - A boolean value specifying whether root was detected on - the device. -- :confval:`kernel_version` - The version of the kernel on the target device. - This returns a :class:`KernelVersion` instance that has separate version and - release fields. -- :confval:`kernel_config` - A :class:`KernelConfig` instance that contains - parsed kernel config from the target device. This may be ``None`` if the - kernel config could not be extracted. -- :confval:`sched_features` - A list of the available tweaks to the scheduler, - if available from the device. -- :confval:`hostid` - The unique identifier of the particular device the WA run - was executed on. - ---------------------- - -.. _run-info-api: - -Run Info API ------------- - -The :class:`RunInfo` can be used to provide information about the run in -general. The available attributes of the class are as follows: - - -- :confval:`uuid` - A unique identifier for that particular run. -- :confval:`run_name` - The name of the run (if provided) -- :confval:`project` - The name of the project the run belongs to (if provided) -- :confval:`project_stage` - The project stage the run is associated with (if provided) -- :confval:`duration` - The length of time the run took to complete. -- :confval:`start_time` - The time the run was stared. -- :confval:`end_time` - The time at which the run finished.