How to build Sensor
=======
Porting to a new machine
------------------------

### Add new machine

Example: Create a new machine, where the manufacture is `manu_1`, and the machine name is `name_2`:

1. Create `meta-manu_1` under `meta-openbmc-machines/meta-openpower` as a directory of `manu_1`;
2. Create `meta-name_2` under `meta_manu_1` as a directory for the machine
3. Use machine name `name_2` instead of `manu_1` in config files
4. Create a conf dir in `meta_manu_1`, following `meta-ibm/conf`
5. So the final directory tree looks like below:

    meta-manu_1
    ├── conf
    │ ├── layer.conf
    │ └── machine
    │ └── include
    │ └── manu_1.inc
    └── meta-name_2
    ├── conf
    │ ├── bblayers.conf.sample
    │ ├── conf-notes.txt
    │ ├── layer.conf
    │ ├── local.conf.sample
    │ └── machine
    │ └── manu_1.conf
    ├── recipes-kernel
    │ └── linux
    │ ├── linux-obmc
    │ │ └── manu_1.cfg
    │ └── linux-obmc_%.bbappend
    ├── recipes-phosphor
    │ └── workbook
    │ └── manu_1-config.bb
    └── recipes.txt
    

### Add machine’s kernel device tree

The device tree is in [https://github.com/openbmc/linux/arch/arm/boot/dts](https://github.com/openbmc/linux/arch/arm/boot/dts), follow `aspeed-bmc-opp-zaius.dts` or similar machine:
6. Add machine’s device tree
7. Modify Makefile to build the device tree
8. Modify arch/arm/mach-aspeed/aspeed.c to call the common setup function

### Add machine’s skeleton config

There is a python config is in [https://github.com/openbmc/skeleton/tree/master/configs](https://github.com/openbmc/skeleton/tree/master/configs), follow `Zaius.py`.
It defines GPIOs, FRUs, etc.
A **better** example is [meta-quanta](https://github.com/openbmc/openbmc/tree/master/meta-openbmc-machines/meta-x86/meta-quanta/meta-q71l/recipes-phosphor/workbook), that defines its own skeleton config in OpenBMC tree, so that it does not rely on skeleton repo.
But note that this python config file will eventually be replaced (e.g. FRU, sensors will be moved to separated config files in separated services).

Sensors and Inventories
-----------------------

#### Background

In OpenBMC, sensors and inventories are implemented by [phosphor-hwmon](https://github.com/openbmc/phosphor-hwmon) and [phosphor-host-ipmid](https://github.com/openbmc/phosphor-host-ipmid), which both highly depends on config files.
To support a new system, only config files need to be defined, no code change at all.
For details about sensor, check [Sensor Support for OpenBMC](https://github.com/openbmc/docs/blob/master/sensor-architecture.md)

#### Hwmon sensors

Taking Palmetto as exmaple.
It defines the config file in its [meta-palmetto/recipes-phosphor/sensors](https://github.com/openbmc/openbmc/tree/master/meta-openbmc-machines/meta-openpower/meta-ibm/meta-palmetto/recipes-phosphor/sensors)
It mainly includes sensors on board and sensors of OCC, which both are i2c devices on P8 systems.
E.g.
[obmc/hwmon/ahb/apb/i2c@1e78a000/i2c-bus@c0/[e-mail]](https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines/meta-openpower/meta-ibm/meta-palmetto/recipes-phosphor/sensors/phosphor-hwmon%25/obmc/hwmon/ahb/apb/i2c%401e78a000/i2c-bus%40c0/tmp423%404c.conf) : It defines the tmp423 sensor on `i2c-2` at address `0x4c`, which you can get the information from device tree.

LABEL_temp1=ambient
LABEL_temp2=cpu

In runtime, the device creates hwmon items in `/sys/class/hwmon/hwmonX`:

ls -l /sys/class/hwmon/hwmon1/
...
lrwxrwxrwx 1 root root 0 Aug 24 06:34 of_node -> ../../../../../../../../../../firmware/devicetree/base/ahb/apb/i2c@1e78a000/i2c-bus@c0/tmp423@4c
...
-r--r--r-- 1 root root 4096 Aug 24 06:34 temp1_input
-r--r--r-- 1 root root 4096 Aug 28 02:52 temp2_fault
-r--r--r-- 1 root root 4096 Aug 24 06:34 temp2_input
...

And phosphor-hwmon knows `temp1_input` is for temperature of `ambient`, and `temp2_input` is for temperature of `cpu`. Then you can get the temperatures on below dbus objects.

  "/xyz/openbmc_project/sensors/temperature/ambient",
  "/xyz/openbmc_project/sensors/temperature/cpu",

#### Inventories and other sensors

Inventory and FRUs are defined in ipmi’s config files.
E.g. Palmetto defines the information in [meta-palmetto/recipes-phosphor/ipmi](https://github.com/openbmc/openbmc/tree/master/meta-openbmc-machines/meta-openpower/meta-ibm/meta-palmetto/recipes-phosphor/ipmi).

- palmetto-ipmi-inventory-map: defines regular inventories, e.g. CPU, memory, motherboard
- phosphor-ipmi-fru-properties: defines extra properties of the inventories
- phosphor-ipmi-sensor-inventory: defines the sensors from IPMI.
For inventory map and fru-properties, they are similar between different systems, you can read it and make one for your system.
For ipmi-sensor-inventory, it has some differences between systems. E.g.

    0x08:
    sensorType: 0x07
    path: /org/open_power/control/occ0
    ...
    0x1e:
    sensorType: 0x0C
    path: /system/chassis/motherboard/dimm0
    ...
    0x22:
    sensorType: 0x07
    path: /system/chassis/motherboard/cpu0/core0
    

The first value `0x08`, `0x1e` and `0x22` are the sensor id of IPMI, which is defined in MRW.
You should follow your system’s MRW to define the above config.

Thanks!

—
Lei YU (郁雷)
IBM OpenPOWER Application Engineer
Tel: [phone]
E-Mail: [e-mail]