1## Introduction
2
3A callout is typically an indication of a faulty hardware component in a system.
4In OpenBMC, a callout is defined as any other error, via a YAML file. An example
5would be `xyz.openbmc_project.Error.Callout.IIC`, to indicate an IIC callout.
6
7The goal is to have applications post callouts using hardware terminology which
8is familiar to them, such as a sysfs entry, or an IIC address. It would be up to
9the OpenBMC error handling component to map such a callout to actual field
10replaceable units (FRUs) on the system.
11
12## Architecture and usage
13
14An OpenBMC error has associated metadata, the same is true for a callout. Such
15metadata would be defined in the callout YAML interface. Here is an example (for
16xyz.openbmc_project.Error.Callout.IIC) :
17```
18- name: IIC
19  meta:
20    - str: "CALLOUT_IIC_BUS=%s"
21      type: string
22    - str: "CALLOUT_IIC_ADDR=%hu"
23      type: uint16
24```
25An application wanting to add an IIC callout will have to provide values for the
26metadata fields above. These fields will also let the error handling component
27figure out that this is in fact an IIC callout.
28
29A callout is typically associated with an error log. For eg,
30`xyz.openbmc_project.Error.Foo` may want to add an IIC callout. This is
31indicated in Foo's YAML interface as follows :
32```
33- name: Foo
34  description: this is the error Foo
35  inherits:
36    - xyz.openbmc_project.Error.Callout.IIC
37```
38The way this inheritance will be implemented is that, Foo's metadata will
39include Callout.IIC's as well, so an application wanting to add an IIC callout
40will have to provide values for Foo and IIC metadata. Like mentioned before,
41due to the presence of the Callout.IIC metadata, the error handling component
42can figure out that the error Foo includes an IIC callout.
43
44Currently, defined callout interfaces in turn inherit
45`xyz.openbmc_project.Error.Callout.Device`, which has metadata common to
46callouts :
47```
48- name: Device
49  meta:
50    - str: "CALLOUT_ERRNO=%d"
51      type: int32
52    - str: "CALLOUT_DEVICE_PATH=%s"
53      type: string
54```
55This way, say an application wants to express an IIC callout in terms of a
56device path, for lack of IIC information. The application can add the callout
57metadata fields for both Callout.Device and Callout.IIC, but provide values
58only for Callout.Callout. That way the error handling component can still
59decipher this as an IIC callout.
60
61## Creation of a callout
62
63This section talks about creation of a callout, once callout related metadata is
64already in the journal.
65
66Taking an example of a generic device callout here, but this would be the flow
67in general :
68
69* An application commits an error that has associated callout metadata. This
70  will cause the error-log server to create a d-bus object for the error.
71
72* The error-log server will detect that callout metadata is present, will
73  extract the same and hand it over to a sub-module which will map callout
74  metadata to one or more inventory object paths, and will create an
75  association between the error object and the inventory object(s). The
76  mapping from callout metadata to inventory objects is mostly done via
77  the aid of code generated by the system MRW parsers.
78
79* Generated code : consider a case where an application wants to callout
80  an EEPROM on the BMC planar, via a device path, such as
81  /sys/devices/platform/ahb/ahb:apb/1e78a000.i2c/i2c-11/i2c-11/11-0051/eeprom.
82  This would have to be mapped to the BMC planar as the FRU to be called out.
83  MRW parser(s) could be written which, for every device in the IIC subsystem,
84  can provide a corresponding inventory object path. The error-log server, in
85  this case, has to, by looking at the device path, determine that the device
86  is on an IIC bus, and make use of the code generated to map the device to
87  inventory objects.
88  Similar MRW parsers could be written for other device subsystems.
89