xref: /openbmc/bios-settings-mgr/README.md (revision 9b2334e1) 
1# Remote BIOS Configuration
2
3[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
4
5## Overview
6
7The **biosconfig_manager** service enables users to view and modify the BIOS
8setup configuration parameters remotely through the Baseboard Management
9Controller (BMC) at any host state. Changes to these parameters will take effect
10upon the next system reboot or immediately, depending on the host firmware.
11
12For more details, please refer to [design document][rbmc-design-document].
13
14## Features
15
16- **Remote management** of BIOS settings.
17- **Immediate updates** or scheduled changes upon reboot.
18- **Reset BIOS Settings** support through the dbus.
19- **ChangePassword** support to change the BIOS setup password.
20
21## RBC Manager Interface
22
23The Manager interface exposes methods and properties to Get & Set BIOS
24attributes via dbus and its documented [here][pdi-manager-bios]
25
26### Object Path
27
28```txt
29/xyz/openbmc_project/BIOSConfig/Manager
30```
31
32### Methods
33
34- **SetAttribute** Sets a specific BIOS attribute to a new value.
35- **GetAttribute** Retrieves the current and pending values of a BIOS attribute.
36
37### Properties
38
39- **ResetBIOSSettings** To reset the BIOS settings based on the Reset Flag.
40- **BaseBIOSTable** Captures the entire BIOS table (collective information of
41  all the BIOS attributes and their properties)
42
43## Signature of `BaseBIOSTable`
44
45The `BaseBIOSTable` property in the RBC Manager Interface is a complex
46dictionary that defines the structure of BIOS attributes. Its type signature is
47as follows:
48
49```plaintext
50dict[string, struct[
51    enum[self.AttributeType],
52    boolean,
53    string,
54    string,
55    string,
56    variant[int64, string],
57    variant[int64, string],
58    array[struct[enum[self.BoundType], variant[int64, string], string]]
59]]
60```
61
62This structure consists of:
63
64- **Attribute Name (string)**: The name of the BIOS attribute.
65- **Attribute Type (enum)**: The type of the BIOS attribute (e.g., String,
66  Integer).
67- **Read-only Status (boolean)**: Whether the attribute is read-only.
68- **Display Name (string)**: The human-readable name of the attribute.
69- **Description (string)**: A description of what the attribute does.
70- **Menu Path (string)**: The BIOS menu path where this attribute can be found.
71- **Current Value (variant[int64, string])**: The current value of the attribute.
72- **Default Value (variant[int64, string])**: The default value of the attribute.
73- **Options (array of structs)**: The available options or bounds for this
74  attribute.
75
76### Examples
77
78Here is an example json structure of a `String` attribute with `attributeName`
79`DrdFreqLimit` & its various properties in BaseBIOSTable signature.
80
81```json
82{
83  "DdrFreqLimit": {
84    "attributeType": "xyz.openbmc_project.BIOSConfig.Manager.AttributeType.String",
85    "readonlyStatus": false,
86    "displayname": "Memory Operating Speed Selection",
87    "description": "Force specific Memory Operating Speed or use Auto setting.",
88    "menuPath": "Advanced/Memory Configuration/Memory Operating Speed Selection",
89    "current": "0x00",
90    "default": "0x0B",
91    "options": [
92      { "optionstring": "auto", "optionvalue": "enum0" },
93      { "optionstring": "2133", "optionvalue": "enum1" },
94      { "optionstring": "2400", "optionvalue": "enum2" },
95      { "optionstring": "2664", "optionvalue": "enum3" },
96      { "optionstring": "2933", "optionvalue": "enum4" }
97    ]
98  }
99}
100```
101
102Here is another example json structure of a `Integer` attribute with attribute
103with name `BIOSSerialDebugLevel` & its various properties in BaseBIOSTable
104signature.
105
106```json
107{
108  "BIOSSerialDebugLevel": {
109    "attributeType": "xyz.openbmc_project.BIOSConfig.Manager.AttributeType.Integer",
110    "readonlyStatus": false,
111    "displayname": "BIOS Serial Debug level",
112    "description": "BIOS Serial Debug level during system boot.",
113    "menuPath": "Advanced/Debug Feature Selection",
114    "current": 0x00,
115    "default": 0x01,
116    "options": [
117      { "optionstring": "MinBound", "optionvalue": 0 },
118      { "optionstring": "MaxBound", "optionvalue": 4 },
119      { "optionstring": "ScalarIncrement", "optionvalue": 1 }
120    ]
121  }
122}
123```
124
125## Initialization of `BaseBIOSTable`
126
127When the `bios-settings-mgr` daemon starts, it initializes with an empty
128`BaseBIOSTable`. It is the responsibility of provider daemons, such as **PLDM**
129or **IPMI**, to populate this table by fetching or defining the BIOS settings.
130These provider daemons are expected to gather the necessary BIOS attributes and
131values from their respective sources (ex: bmc, system firmware) and then
132initialize the `BaseBIOSTable` property with those settings.
133
134### BIOS with PLDM as Communication Protocol
135
136For systems that use the **PLDM (Platform Level Data Model)** protocol between
137BMC & Host, OEM vendors can define their own BIOS attributes in the form of
138[JSON files][pldm-bios-json]. The PLDM daemon parses these files and initializes
139the `BaseBIOSTable` property accordingly. This allows for flexible and custom
140BIOS configuration options based on the vendor's specifications.
141
142For more details , refer to the [BIOS Support in PLDM][pldm-bios].
143
144### BIOS with IPMI as Communication Protocol
145
146For systems that use the **Intelligent Platform Management Interface** protocol
147between BMC & Host, BIOS attributes are gathered from BIOS as an `xml file` &
148`BaseBIOSTable` would then be initialized with the attributes data from the
149parsed xml file.
150
151For more details, refer to the code [BIOS Support in IPMI][ipmi-intel-bios].
152
153## RBC Password Interface
154
155### Object Path
156
157```txt
158xyz.openbmc_project.BIOSConfig.Password
159```
160
161### Methods
162
163- **ChangePassword**
164  Used to change the BIOS setup password.
165
166### Properties
167
168- **PasswordInitialized** Used to indicate whether the BIOS password-related
169  details have been received.
170
171[rbmc-design-document]:
172  https://github.com/openbmc/docs/blob/master/designs/remote-bios-configuration.md
173[pldm-bios-json]:
174  https://github.com/openbmc/pldm/blob/master/oem/ibm/configurations/bios/com.ibm.Hardware.Chassis.Model.Rainier2U/bios_attrs.json
175[pldm-bios]: https://github.com/openbmc/pldm?tab=readme-ov-file#bios-support
176[ipmi-intel-bios]:
177  https://github.com/openbmc/intel-ipmi-oem/blob/master/src/biosconfigcommands.cpp
178[pdi-manager-bios]:
179  https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/BIOSConfig/Manager.interface.yaml
180