From 58ca01c22ab3b33609ca1e98bd2489d871792f34 Mon Sep 17 00:00:00 2001
From: Bob Fournier <bfournie@redhat.com>
Date: Tue, 1 Jun 2021 11:00:24 -0400
Subject: [PATCH] Add a section to redfish doc for BIOS registry fields

Move the descriptions of the BIOS registry fields in the API to
a new section in the Redfish documentation.

Change-Id: Ifedb4526113bb84ccc598e13f5767b71a60f5532
---
 api-ref/source/parameters.yaml       | 21 +++++++--------------
 doc/source/admin/drivers/redfish.rst | 26 ++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 14 deletions(-)

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index ef9b1b9756..240aed15d2 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -507,36 +507,31 @@ bios_interface:
   type: string
 bios_setting_allowable_values:
   description: |
-    A list of allowable values when the attribute_type is "Enumeration",
-    otherwise None.
+    A list of allowable values, otherwise ``null``.
   in: body
   required: true
   type: array
 bios_setting_attribute_type:
   description: |
-    A string describing the type of the Bios setting - "Enumeration",
-    "Integer", "String", "Boolean", or "Password".  May be None.
+    A string describing the type of the Bios setting. May be ``null``.
   in: body
   required: true
   type: string
 bios_setting_lower_bound:
   description: |
-    The lowest allowed value when attribute_type is "Integer".
-    May be None.
+    The lowest allowed integer value. May be ``null``.
   in: body
   required: true
   type: integer
 bios_setting_max_length:
   description: |
-    The maximum length when attribute_type is "String".
-    May be None.
+    The maximum string length of the value. May be ``null``.
   in: body
   required: true
   type: integer
 bios_setting_min_length:
   description: |
-    The minimum length when attribute_type is "String".
-    May be None.
+    The minimum string length of the value. May be ``null``.
   in: body
   required: true
   type: integer
@@ -562,15 +557,13 @@ bios_setting_reset_required:
   type: boolean
 bios_setting_unique:
   description: |
-    This Bios setting is unique to this node.
-    May be None.
+    This Bios setting is unique to this node. May be ``null``.
   in: body
   required: true
   type: boolean
 bios_setting_upper_bound:
   description: |
-    The lowest allowed value when attribute_type is "Integer".
-    May be None.
+    The highest allowed integer value. May be ``null``.
   in: body
   required: true
   type: integer
diff --git a/doc/source/admin/drivers/redfish.rst b/doc/source/admin/drivers/redfish.rst
index 63f2e4bbe5..24f0f11a18 100644
--- a/doc/source/admin/drivers/redfish.rst
+++ b/doc/source/admin/drivers/redfish.rst
@@ -478,7 +478,33 @@ In the following example, the JSON is specified directly on the command line::
    firmware may result in devices in the server, or the server itself becoming
    inoperable.
 
+Retrieving BIOS Settings
+========================
+
+When the :doc:`bios interface </admin/bios>` is set to ``redfish``, Ironic will
+retrieve the node's BIOS settings as described in `BIOS Configuration`_. In
+addition, via Sushy_, Ironic will get the BIOS Attribute Registry
+(`BIOS Registry`_) from the node which is a schema providing details on the
+settings. The following fields will be returned in the BIOS API
+(``/v1/nodes/{node_ident}/bios``) along with the setting name and value:
+
+.. csv-table::
+    :header: "Field", "Description"
+    :widths: 25, 120
+
+    "``attribute_type``", "The type of setting - ``Enumeration``, ``Integer``, ``String``, ``Boolean``, or ``Password``"
+    "``allowable_values``", "A list of allowable values when the attribute_type is ``Enumeration``"
+    "``lower_bound``", "The lowest allowed value when attribute_type is ``Integer``"
+    "``upper_bound``", "The highest allowed value when attribute_type is ``Integer``"
+    "``min_length``", "The shortest string length that the value can have when attribute_type is ``String``"
+    "``max_length``", "The longest string length that the value can have when attribute_type is ``String``"
+    "``read_only``", "The setting is ready only and cannot be modified"
+    "``unique``", "The setting is specific to this node"
+    "``reset_required``", "After changing this setting a node reboot is required"
+
 .. _Redfish: http://redfish.dmtf.org/
 .. _Sushy: https://opendev.org/openstack/sushy
 .. _TLS: https://en.wikipedia.org/wiki/Transport_Layer_Security
 .. _ESP: https://wiki.ubuntu.com/EFIBootLoaders#Booting_from_EFI
+.. _`BIOS Registry`: https://redfish.dmtf.org/schemas/v1/AttributeRegistry.v1_3_5.json
+.. _`BIOS Configuration`: https://docs.openstack.org/ironic/latest/admin/bios.html