1# System JSON File Documentation 2 3This README documents the purpose, structure, and usage of system JSON files 4used for configuration. It includes descriptions of mandatory fields, expected 5formats, and examples to understand and extend the system. 6 7--- 8 9## devTree 10 11This field specifies the .dtb filename. While optional in the configuration JSON 12for non-IBM systems, it is mandatory for IBM systems because the system uses it 13to apply the correct configuration. A missing field on IBM systems may result in 14critical system failure. 15 16## backupRestoreConfigPath 17 18It is path to a JSON file which will contain details required to perform backup 19/restoration of EEPROM(s).For more details refer documentation of back up and 20restore JSON. 21 22## commonInterfaces 23 24This optional section allows defining DBus interfaces and properties that are 25common to all FRUs in the system configuration JSON.It serves as a place to 26specify shared interfaces so they do not need to be repeated for each FRU. 27 28> **Example:** > interfaces such as 29> `xyz.openbmc_project.Inventory.Decorator.Asset` may be included here when 30> applicable. 31 32Each of these fields maps to: 33 34- **keywordName** – The keyword used in VPD to locate the value. 35- **recordName** – The VPD record from which the value is extracted. 36 37## muxes 38 39This optional field provides configuration for I2C multiplexer (mux) devices 40present in the system.The system uses this information to identify and enable 41the required muxes.Currently this field is limited to IBM systems.Each mux must 42be defined with the below fields. 43 44- **i2bus** - The I2C bus number where the mux is connected. 45- **deviceaddress** - The 7-bit I2C address of the mux device. 46- **holdidlepath** - The absolute sysfs path to the mux driver's hold_idle 47 control node. 48 49## frus 50 51This mandatory section maps a physical EEPROM path to an array of one or more 52inventory objects.The first object in this array is considered the base FRU for 53that physical path. 54 55> **Note:** All fields by default are optional except the field which are marked 56> as mandatory. 57 58### `<ACTION_GROUP>` 59 60Action Groups define a standardized way for system operations(e.g., FRU 61initialization or data collection).They ensure tasks are handled reliably by 62managing environmental setup, clean finalization, or safe recovery on failure. 63Multiple Action Groups are supported. Currently, following Action Groups are 64supported: 65 66- **preAction** - (Preparation) Actions that run before the main task to ensure 67 the environment is ready.To validate prerequisites, allocate necessary 68 resources, and establish the required state before the primary task.VPD 69 collection depends on this step and may fail if it is skipped. 70- **postAction** - (Finalization) Operations executed exclusively after the 71 primary task (such as VPD collection) concludes successfully. Its purpose is 72 to transition the system from a "transient processing state" to a "stable 73 production state." 74- **postFailAction** - (Safety Recovery) Actions that run only if a task fails, 75 acting as a "safety net" to return the system to a known, safe state. 76 77#### `<ACTION_PHASE>` 78 79Represents a specific phase within the group(e.g.,collection, deletion). 80Multiple phases allowed. Currently following phases are supported: 81 82- **collection** - The collection phase is executed when the FRU's VPD data is 83 getting collected. 84- **deletion** - The deletion phase is executed when a FRU is removed. 85 86##### `<ACTION_TAG>` 87 88Specifies the action to perform in a given phase.The actions will be performed 89in the sequence in which it has been defined.To support any future actions other 90than supported, functions with specific signature needs to be defined in JSON 91utility file.Currently following actions are supported: 92 93- **gpioPresence** - Checks GPIO pin to detect FRU's presence. 94- **setGpio** - Set a GPIO pin to a required state for specific action. 95- **systemCmd** - Shell command executed. 96 97###### `<PROPERTY_NAME>` / `<VALUE>` 98 99Represents parameters required by the corresponding action tag. 100 101- `<PROPERTY_NAME>` defines the name of an action-specific parameter. 102 103- `<VALUE>` defines the value assigned to that parameter. 104 105Currently following property is supported: 106 107- **ccin** - card identification number. 108- **pin** - Gpio pin name. 109- **cmd** - shell command to execute. 110 111### Note on Extensibility 112 113> ⚠️ **Important** Although the JSON structure is generic and allows future 114> extensions, the current implementation recognizes only the action groups and 115> action tags explicitly supported by the source code. Adding new action groups 116> or action tags requires corresponding updates in the source code. 117 118## Sample JSON 119 120```json 121{ 122 "muxes": [ 123 { 124 "i2bus": "<string>", 125 "deviceaddress": "<string>", 126 "holdidlepath": "<string>" 127 }, 128 { 129 "...": "Any number of additional muxes" 130 } 131 ], 132 "frus": { 133 "<EEPROM_PATH_OF_FRU>": [ 134 { 135 "inventoryPath": "<string: Inventory object path. It is mandatory field.>", 136 "serviceName": "<string: Name of the service hosting the inventory object. 137 It is mandatory field>", 138 "isSystemVpd": "<bool: true if this EEPROM contains main system VPD>", 139 140 "extraInterfaces":"<It is used to define additional D-Bus interfaces 141 and properties to be hosted under FRU's inventory object path . This section 142 maps a specific Interface Name to a dictionary of Properties:Value pairs>" 143 { 144 "<DBUS_INTERFACE>": { 145 "<PROPERTY_NAME>": "<string: value>" 146 } 147 "...": "Any number of additional interfaces or properties" 148 149 "Below are the examples : ", 150 "com.ibm.ipzvpd.Location": { 151 "LocationCode": "<string: Unique physical FRU's location code>" 152 }, 153 "xyz.openbmc_project.Inventory.Item": { 154 "PrettyName": "<string: User-friendly FRU name>" 155 } 156 }, 157 158 "<ACTION_GROUP>": 159 { 160 "<ACTION_PHASE>": 161 { 162 "<ACTION_TAG>": { 163 "<PROPERTY_NAME>": "<VALUE>" 164 }, 165 166 "...": "Any number of additional action tags" 167 }, 168 169 "... ": "Any number of additional phases" 170 }, 171 "...": "Any number of additional action groups" 172 173 "<Below are the standard example currently utilized by the system.>", 174 175 "preAction": 176 { 177 "collection": 178 { 179 "gpioPresence": 180 { 181 "pin": "<string>", 182 "value": "<int: VALUE>" 183 }, 184 "setGpio":{ 185 "pin": "<string>", 186 "value": "<int: VALUE>" 187 }, 188 "systemCmd":{ 189 "cmd": "<string>" 190 } 191 }, 192 "deletion":{ 193 "systemCmd": { 194 "cmd": "<string>" 195 } 196 } 197 }, 198 "postAction": 199 { 200 "collection": 201 { 202 "ccin": ["<CCIN_1>", "<CCIN_2>", "..."], 203 "systemCmd":{ 204 "cmd": "<string>" 205 } 206 }, 207 "deletion":{ 208 "systemCmd": { 209 "cmd": "<string>" 210 }, 211 "setGpio":{ 212 "pin": "<string>", 213 "value":"<int: VALUE>" 214 } 215 } 216 }, 217 "postFailAction": { 218 "collection": 219 { 220 "setGpio":{ 221 "pin": "<string>", 222 "value": "<int: VALUE_TO_SET>" 223 } 224 }, 225 "deletion": 226 { 227 "setGpio": { 228 "pin": "<string>", 229 "value": "<int: VALUE_TO_SET>" 230 } 231 } 232 }, 233 "replaceableAtStandby": "<bool: FRU can be replaced when system is in standby>", 234 "replaceableAtRuntime": "<bool: FRU can be replaced while system is running>", 235 "pollingRequired": "<bool: GPIO polling is required to detect state changes>", 236 "hotPlugging": "<bool: FRU can be inserted or removed without reboot>", 237 "concurrentlyMaintainable": "<bool: indicating whether the FRU can be physically 238 serviced or replaced while the system is powered on and running>", 239 240 "redundantEeprom": "<string: Backup EEPROM path if primary fails or is inaccessible>", 241 242 "cpuType": "<string: CPU role (e.g. 'primary', 'secondary')>", 243 "powerOffOnly": "<bool: VPD can be collected only when chassis is powered OFF>", 244 "embedded": "<bool: FRU is physically embedded into parent FRU>", 245 "synthesized": "<bool: FRUs for which vpd-manager does not collect VPD>", 246 "noprime": "<bool: FRU is excluded from priming>", 247 248 "offset": "<integer: Byte offset inside shared EEPROM>", 249 "size": "<integer: Size of VPD block in bytes>", 250 251 "busType": "<string: Hardware bus type (e.g. I2C, SPI)>", 252 "driverType": "<string: Linux kernel driver name>", 253 "devAddress": "<string: 7-bit I2C slave address>", 254 255 "handlePresence": "<bool: vpd-manager manages FRU presence>", 256 "monitorPresence": "<bool: FRU presence is actively monitored>", 257 "essentialFru": "<bool: FRU is essential for system operation>", 258 "readOnly": "<bool: FRU or its VPD data is read-only>" 259 }, 260 { 261 "<All FRUs at index 1 or onwards are considered child FRUs>" 262 "inherit" : "<bool: indicating whether the child FRU inherits all 263 properties from the base FRU>", 264 "copyRecords": "<string, specifies which VPD fields should be copied 265 from the parent/base FRU. This is an array of field names,allowing the 266 child FRU to copy/inherit only the relevant VPD informations>", 267 268 }, 269 ] 270 } 271} 272``` 273