Define openbmc errors for generic device callouts

A Callout serves to blame a specific entity of which the system is
comprised of, such as hardware or firmware, for unexpected behavior.
Such an entity may need repair or replacement.

This change defines errors Callout.Device, for cases when a device
needs to be called out in terms of the device path, and
Callout.Inventory, for cases when an inventory object needs to be called
out.

Change-Id: Id54c76f38394cc47b60f6075487ab5e36304f197
Signed-off-by: Deepak Kodihalli <dkodihal@in.ibm.com>

5 files changed, 75 insertions, 0 deletions

diff --git a/xyz/openbmc_project/Error/Callout/Device.errors.yaml b/xyz/openbmc_project/Error/Callout/Device.errors.yaml
new file mode 100644
index 0000000..06e816d
--- /dev/null
+++ b/xyz/openbmc_project/Error/Callout/Device.errors.yaml
@@ -0,0 +1,3 @@
+# xyz.openbmc_project.Error.Callout.Device
+- name: Device
+  description: Generic device callout
diff --git a/xyz/openbmc_project/Error/Callout/Device.metadata.yaml b/xyz/openbmc_project/Error/Callout/Device.metadata.yaml
new file mode 100644
index 0000000..dc7914e
--- /dev/null
+++ b/xyz/openbmc_project/Error/Callout/Device.metadata.yaml
@@ -0,0 +1,6 @@
+- name: Device
+  meta:
+    - str: "CALLOUT_ERRNO=%d"
+      type: int32
+    - str: "CALLOUT_DEVICE_PATH=%s"
+      type: string
diff --git a/xyz/openbmc_project/Error/Callout/Inventory.errors.yaml b/xyz/openbmc_project/Error/Callout/Inventory.errors.yaml
new file mode 100644
index 0000000..ea95875
--- /dev/null
+++ b/xyz/openbmc_project/Error/Callout/Inventory.errors.yaml
@@ -0,0 +1,3 @@
+# xyz.openbmc_project.Error.Callout.Inventory
+- name: Inventory
+  description: Inventory item callout
diff --git a/xyz/openbmc_project/Error/Callout/Inventory.metadata.yaml b/xyz/openbmc_project/Error/Callout/Inventory.metadata.yaml
new file mode 100644
index 0000000..8ed1479
--- /dev/null
+++ b/xyz/openbmc_project/Error/Callout/Inventory.metadata.yaml
@@ -0,0 +1,4 @@
+- name: Inventory
+  meta:
+    - str: "CALLOUT_INVENTORY_PATH=%s"
+      type: string
diff --git a/xyz/openbmc_project/Error/Callout/README.md b/xyz/openbmc_project/Error/Callout/README.md
new file mode 100644
index 0000000..14a5397
--- /dev/null
+++ b/xyz/openbmc_project/Error/Callout/README.md
@@ -0,0 +1,59 @@
+## Introduction
+
+A callout is typically an indication of a faulty hardware component in a system.
+In openbmc, a callout is defined as any other error, via a YAML file. An example
+would be `xyz.openbmc_project.Error.Callout.IIC`, to indicate an IIC callout.
+
+The goal is to have applications post callouts using hardware terminology which
+is familiar to them, such as a sysfs entry, or an IIC address. It would be up to
+the openbmc error handling component to map such a callout to actual field
+replacable units (FRUs) on the system.
+
+## Architecture and usage
+
+An openbmc error has associated metadata, the same is true for a callout. Such
+metadata would be defined in the callout YAML interface. Here is an example (for
+xyz.openbmc_project.Error.Callout.IIC) :
+```
+- name: IIC
+  meta:
+    - str: "CALLOUT_IIC_BUS=%s"
+      type: string
+    - str: "CALLOUT_IIC_ADDR=%hu"
+      type: uint16
+```
+An application wanting to add an IIC callout will have to provide values for the
+metadata fields above. These fields will also let the error handling component
+figure out that this is in fact an IIC callout.
+
+A callout is typically associated with an error log. For eg,
+`xyz.openbmc_project.Error.Foo` may want to add an IIC callout. This is
+indicated in Foo's YAML interface as follows :
+```
+- name: Foo
+  description: this is the error Foo
+  inherits:
+    - xyz.openbmc_project.Error.Callout.IIC
+```
+The way this inheritance will be implemented is that, Foo's metadata will
+include Callout.IIC's as well, so an application wanting to add an IIC callout
+will have to provide values for Foo and IIC metadata. Like mentioned before,
+due to the presence of the Callout.IIC metadata, the error handling component
+can figure out that the error Foo includes an IIC callout.
+
+Currently defined callout interfaces in turn inherit
+`xyz.openbmc_project.Error.Callout.Device`, which has metadata common to
+callouts :
+```
+- name: Device
+  meta:
+    - str: "CALLOUT_ERRNO=%d"
+      type: int32
+    - str: "CALLOUT_DEVICE_PATH=%s"
+      type: string
+```
+This way, say an application wants to express an IIC callout in terms of a
+device path, for lack of IIC information. The application can add the callout
+metadata fields for both Callout.Device and Callout.IIC, but provide values
+only for Callout.Callout. That way the error handling component can still
+decipher this as an IIC callout.