From c9674da220361482b679717e7fca56e34bfa0dca Mon Sep 17 00:00:00 2001
From: Dmitry Tantsur <dtantsur@redhat.com>
Date: Tue, 2 Feb 2016 16:35:03 +0100
Subject: [PATCH] Document hardware inventory sent to lookup and inspection

Also add a missing docstring to HardwareManager.list_hardware_info.

Change-Id: Iee3584320f0591398e7761513ff588efeb62886d
---
 doc/source/index.rst            | 41 +++++++++++++++++++++++++++++++++
 ironic_python_agent/hardware.py |  8 +++++++
 2 files changed, 49 insertions(+)

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 4edd7a74c..315bcc77a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -76,6 +76,47 @@ Make sure your DHCP environment is set to boot IPA by default.
 
 .. _Ironic Inspector: https://github.com/openstack/ironic-inspector
 
+Hardware Inventory
+------------------
+IPA collects various hardware information using its `Hardware Managers`_,
+and sends it to Ironic on lookup and to Ironic Inspector on Inspection_.
+
+The exact format of the inventory depends on the hardware manager used.
+Here is the basic format expected to be provided by all hardware managers.
+The inventory is a dictionary (JSON object), containing at least the following
+fields:
+
+``cpu``
+    CPU information: ``model_name``, ``frequency``, ``count`` and
+    ``architecture``.
+
+``memory``
+    RAM information: ``total`` (total size in bytes), ``physical_mb``
+    (physically installed memory size in MiB, optional).
+
+    .. note::
+        The difference is that the latter includes the memory region reserved
+        by the kernel and is always slightly bigger. It also matches what
+        the Nova flavor would contain for this node and thus is used by the
+        inspection process instead of ``total``.
+
+``bmc_address``
+    IP address of the node's BMC (aka IPMI address), optional.
+
+``disks``
+    list of disk block devices with fields: ``name``, ``model``,
+    ``size`` (in bytes), ``rotational`` (boolean), ``wwn``, ``serial``,
+    ``vendor``, ``wwn_with_extension``, ``wwn_vendor_extension``.
+
+``interfaces``
+    list of network interfaces with fields: ``name``, ``mac_address``,
+    ``ipv4_address``. Currently IPA also returns 2 fields ``switch_port_descr``
+    and ``switch_chassis_descr`` which are reserved for future use.
+
+``system_vendor``
+    system vendor information from SMBIOS as reported by ``dmidecode``:
+    ``product_name``, ``serial_number`` and ``manufacturer``.
+
 Image Builders
 --------------
 Unlike most other python software, you must build an IPA ramdisk image before
diff --git a/ironic_python_agent/hardware.py b/ironic_python_agent/hardware.py
index e15926a5c..f3167ab92 100644
--- a/ironic_python_agent/hardware.py
+++ b/ironic_python_agent/hardware.py
@@ -267,6 +267,14 @@ class HardwareManager(object):
         return erase_results
 
     def list_hardware_info(self):
+        """Return full hardware inventory as a serializable dict.
+
+        This inventory is sent to Ironic on lookup and to Inspector on
+        inspection.
+
+        :return: a dictionary representing inventory
+        """
+        # NOTE(dtantsur): don't forget to update docs when extending inventory
         hardware_info = {}
         hardware_info['interfaces'] = self.list_network_interfaces()
         hardware_info['cpu'] = self.get_cpus()