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