chromeos_firmware
=================
Get firmware information from a flash chip.

Function Arguments
------------------
.. list-table::
   :widths: 20 10 60
   :header-rows: 1
   :align: left

   * - Name
     - Type
     - Description

   * - field
     - ['firmware_keys', 'ro_ec_firmware', 'ro_fp_firmware', 'ro_main_firmware']
     - The flash chip where this function probes the firmware from.

Description
-----------
This function mainly runs ``flashrom`` to get the firmware image from the
specific flash chip and calculates the hash of some of the sections of the
image.

- If ``field="firmware_keys"``, this function outputs sha1sum hash of the
  root key and the recovery key recorded in the readonly main firmware.  If
  the keyset is develop keyset, the output will contain a special suffix mark
  ``#devkeys/rootkey`` and ``#devkeys/recoverykey``.  See `Examples`_ for
  detail.

- If ``field="ro_main_firmware"``, this function outputs the sha256 hash of
  the readonly main firmware and also the version of the firmware.

- If ``field="ro_ec_firmware"``, this function outputs the sha256 hash of
  the readonly EC firmware and also the version of the firmware.

- If ``field="ro_fp_firmware"``, this function outputs the sha256 hash of
  the readonly fingerprint firmware and also the version of the firmware.

Examples
--------

As this function has only one single argument, the ``eval`` part of the
probe statement can be simplified into a single string instead of a
dictionary.  For example, the probe statement for probing the key hash is ::

  {
    "eval": "chromeos_firmware:firmware_keys":
  }

, where ``chromeos_firmware:firmware_keys`` is equivalent to ::

  {
    "chromeos_firmware": {
      "field": "firmware_keys"
    }
  }

We category below examples into two use cases.

Probe the Key Hash (``field="firmware_keys"``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the firmware is not signed and contains a develop keyset, the probed
results must be ::

  [
    {
      "rootkey": "kv3#b11d74edd6c14...0bc20cf041f10#devkey/rootkey",
      "recoverykey": "kv3#c14bd0b70d9...d8f43de48d4ed#devkey/recoverykey"
    }
  ]

Probe the RO Firmware Image Hash (``field="ro_[main|ec]_firmware"``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``values`` of the output must contains two fields: ``hash`` and
``version``.  For example::

  [
    {
      "hash": "13497173ba1fb678ab3f...ebd27d00d",
      "version": "supercoolproj_v1.1.2738-3927abcd2"
    }
  ]