Add README.md files to the secureboot component

This commit adds a top-level README.md file to the secureboot
component that then calls into new README.md files in the different
sub-directories.

Change-Id: I7460a0e591232c2f8387321b0251ac3f62a1c76e
Reviewed-on: http://rchgit01.rchland.ibm.com/gerrit1/89025
Reviewed-by: Ilya Smirnov <ismirno@us.ibm.com>
Reviewed-by: Nicholas E Bofferding <bofferdn@us.ibm.com>
Reviewed-by: Christopher J Engel <cjengel@us.ibm.com>
Tested-by: Jenkins Server <pfd-jenkins+hostboot@us.ibm.com>
Tested-by: Jenkins OP Build CI <op-jenkins+hostboot@us.ibm.com>
Tested-by: Jenkins OP HW <op-hw-jenkins+hostboot@us.ibm.com>
Tested-by: FSP CI Jenkins <fsp-CI-jenkins+hostboot@us.ibm.com>
Reviewed-by: Daniel M Crowell <dcrowell@us.ibm.com>

src/usr/secureboot/README.md

@@ -0,0 +1,64 @@
+# Secureboot Services in Hostboot
+Hostboot provides multiple services to help secure the system and
+ ensure that only 'trusted' code is running on it. The multiple sub-directories
+ implement the various interfaces defined in the
+ [src/include/usr/secureboot/](../../include/usr/secureboot/) directory.
+
+## Directories
+* __base__
+  * The modules here define the core secureboot support: **defining and
+ implementing interfaces to retrieve the security state of the system**
+  * The directory is called 'base' because its contents are included in the
+ Hostboot Base Image (HBB) partition
+  * See [base/README.md](base/README.md) for more details
+
+* __common__
+  * The modules here provide common support like tracing, error callouts,
+ definitions of the secure "container" header, etc, that is used by the
+ secureboot modules in the peer directories
+  * See [common/README.md](common/README.md) for more details
+
+* __ext__
+  * The modules here provide some additional secureboot capabilities that are
+ beyond the core secureboot functionality found in the "base" directory
+  * This directory is called 'ext' because its contents are included in the
+ Hostboot Extended Image (HBI)
+  * Any module here can call into the Hostboot Base Image (ie the 'base' code
+ in the HBB partition)), but Hostboot Base Image modules cannot call into
+ these extended image modules
+  * See [ext/README.md](ext/README.md) for more details
+
+* __node_comm__
+  * The modules here implement a node-to-node communication protocol that is
+ used on multinode systems to share secureboot data between the nodes
+  * See [node_comm/README.md](node_comm/README.md) for more details
+
+* __runtime__
+  * The modules here implement a small subset of secureboot code that is used by
+ Hostboot runtime services.
+  * See [runtime/README.md](runtime/README.md) for more details
+
+* __smf__
+  * The modules here distribute different amounts of Secure SMF memory between
+ the available processors on the system based on a user-configurable petitboot
+ setting
+  * If we ever supported this on P9 FSP-based systems, the SMF memory amount
+ would be passed from the FSP to Hostboot using attributes.
+  * See [smf/README.md](smf/README.md) for more details
+
+* __trusted__
+  * The modules here define the trusted boot support which uses TPMs (Trusted
+ Platform Modules) to track what code is running on the system
+  * See [trusted/README.md](trusted/README.md) for more details
+
+## Other Files
+* __HBconfig__
+  * Standard HBconfig file that defines secureboot- and trustedboot-related
+ Hostboot compile variables
+
+* __makefile__
+  * Standard Hostboot makefile
+
+* __[README.md](./README.md)__
+  * This file
+

src/usr/secureboot/base/README.md

@@ -0,0 +1,60 @@
+# **'base'** Secureboot Services in Hostboot
+This directory implements the core of the secureboot-related functionality
+ that Hostboot provides.
+It is available in the Hostboot Base Image (ie the HBB partition) and all
+ non-runtime Hostboot code can invoke functions provided by it.
+
+## Key Points
+* The **libsecureboot_base.so** module created here is available in Hostboot's
+ base image and is used to securely bringup the rest of the Hostboot.
+* It implements the functions in these header files:
+  * [service.H](../../../include/usr/secureboot/service.H)
+  * [settings.H](../../../include/usr/secureboot/settings.H)
+* It is used to tell if security is enabled at the system or processor level
+* It is used to determine the state of the secureboot jumper on the different
+ processors
+* It provides the interface into the SecureRom to verify code packages run
+ on the system
+
+## Files
+
+* __header.C__
+  * Implements functions related to loading and retrieving the
+ Hostboot Base header from Hostboot Base (HBB) PNOR partition
+
+* __makefile__
+  * Standard Hostboot makefile
+
+* __purge.H__
+  * Defines a special purge function
+
+* __[README.md](./README.md)__
+  * This file
+
+* __securerommgr.C, securerommgr.H__
+  * Defines and implements the SecureRomManager class and its member functions
+  * These functions call into the securerom and takes advantage of
+ its functionality
+
+* __service.C__
+  * Retrieves the secureboot registers on the processors in the system
+    * These functions are then used to add information to errorlogs and traces
+  * Initliaizes the SecureRomManager class
+  * Function to handle special secureboot failures
+  * Retrieves some global secureboot settings taken from Hostboot's bootloader
+  * NOTE: Functions in this file call into functions in settings.C when
+ appropriate
+
+* __settings.C__
+  * Gets and Sets the two primary Secureboot-related SCOM registers:
+    * ProcSecurity (aka Proc Security Switch)
+    * ProcCbsControl
+  * Also applies knowledge of key bits of these two registers, like returning
+ if a processor is set in 'secureboot enabled mode' and what the state of its
+ secureboot jumper is
+
+
+## sub-directories
+* __test__
+  * Standard Hostboot test directory that implements CXX Unit Tests
+

src/usr/secureboot/common/README.md

@@ -0,0 +1,33 @@
+# **'common'** Secureboot Services in Hostboot
+This directory implements utility functions for tracing and error logging
+ that other secureboot modules in the peer directories can use.
+For example, the secureboot_base, secureboot_rt (runtime), secureboot_trusted,
+secureboot_ext, and node_comm modules use these functions.
+
+## Files
+
+* __common.mk__
+  * Makefile that other makefiles can call to include the generated .o files
+
+* __containerheader.C__
+  * Implements the ContainerHeader class's member functions
+  * Functions are defined in
+ [containerheader.H](../../../include/usr/secureboot/containerheader.H)
+
+* __errlud_secure.C, errlud_secure.H__
+  * These files define and implement custom error log user detail sections to
+ capture security information on the system
+
+* __[README.md](./README.md)__
+  * This file
+
+* __securetrace.C, securetrace.H__
+  * Defines and implements standard Hostboot trace descriptors for the
+ secureboot component
+
+## sub-directories
+* __plugins__
+  * Standard Hostboot 'plugins' directory where the errorlog parser finds the
+ information to properly parse the custom error log user detail sections
+ defined in errlud_secure.H
+

src/usr/secureboot/ext/README.md

@@ -0,0 +1,24 @@
+# **'ext'** Secureboot Services in Hostboot
+This directory implements additional (or 'extended') secureboot functionality
+ that is not considered part of the 'base' secureboot support.
+
+## Files
+
+* __makefile__
+  * Standard Hostboot makefile
+
+* __phys_presence.C__
+  * Implements the 'physical presence'-related functions, which are used to
+ assert that a system owner is physically present at the site of a system.
+    * This is done by using GPIO devices on the system's power button to
+ capture that the button was physically pressed.
+  * Functions are defined in
+ [phys_presence_if.H](../../../include/usr/secureboot/phys_presence_if.H)
+
+* __[README.md](./README.md)__
+  * This file
+
+* __service_ext.C__
+  * Implements some additional (or 'extended') functionality as defined in
+ [service_ext.H](../../../include/usr/secureboot/service_ext.H)
+

src/usr/secureboot/node_comm/README.md

@@ -0,0 +1,97 @@
+# **'node\_comm'** Secureboot Services in Hostboot
+This directory implements the Hostboot functions necessary to create a
+ secure channel between nodes using a series of a-bus mailbox registers
+ enabled after a-bus training but before the iovalid drop.
+This secure channel is used in a multi-node evironment for nodes to exchange
+ cryptographic material that can later be used for internode authentication
+ higher up the firmware stack.
+
+## Key Points
+* This code implements device driver-like functionality to send messages
+ across the a-bus connection from one node to another
+  * This functionality is based on a-bus mailbox registers which are used to
+ detect incoming messages, retrieve data, and send data messages to/from
+ specific nodes
+* This code establishes a master node which then starts the process of exchanging
+ information with each of the other slave nodes
+* The files are built into libnode_comm.so
+* This module implements the interfaces defined in
+ [nodecommif.H](../../../include/usr/secureboot/nodecommif.H)
+* NOTE: The P9 code references "OBUS" a lot which is the specific processor
+ chiplet that the a-bus messaging system runs through.
+
+## Algorithm
+* First, each node does the following:
+  * Determine the nodes in the system
+  * Determine the master processor of this node
+  * Determine the a-bus connection to its master processor peers on the
+ other nodes
+
+* ***The Master Processor on Master Node*** does the following
+ (see node_comm_exchange.C's nodeCommAbusExchangeMaster()):
+  * **Loop 1:** Exchange SBID/nonces between Master and each of the Slave Nodes
+    * Generate SBID/nonce and send to slave node
+    * Look for return SBID/nonce from the slave
+  * **Loop 2:** Master Node requests quotes from each Slave Node
+    * Generate and send Quote Request to a slave
+    * Look for Quote Response from the slave node
+    * Process the Quote Response that was returned from the slave node
+  * NOTE:
+    * Nonces are encoded 64-bytes of data: part random number, part node ID
+    * Quotes are a form of attestation between two TPMs on the system.  See
+ TrustedComputingGroup.org's Trusted Platform Module Library Specification,
+ Family "2.0" for more details.
+
+* ***The Master Processor on each Slave Node*** does the following
+ (see node_comm_exchange.C's nodeCommAbusExchangeSlave()):
+
+  * Wait for SBID/nonce from the master node
+  * Send a SBID/nonce back to the master node
+  * Wait for Quote Request from master node
+  * Generate the Quote Response
+  * Send the Quote Response to the master node
+
+
+* NOTE: Generating the SBID/Nonces, Quote Requests, and Quote Responses above
+ all require interacting with the TPMs on the different nodes in specific
+ ways
+  * The devil is truly in the details, and the details can be found in the
+ supporting functions of node_comm_exchange.C
+* NOTE: In the event that one node fails in this process there will be an
+ attempt to poison the TPMs on that node and move on in most cases.  This is
+ to prevent an entire system from failing to boot with one bad node.
+
+## Files
+
+* __makefile__
+  * Standard Hostboot makefile
+
+* __node_comm.C, node_comm.H__
+  * The majority of the sub-functions used to implement the algorithm are
+ defined and implemented here, including the a-bus mapping details between
+ the nodes
+
+* __node_comm_dd.C, node_comm_dd.H__
+  * Defines and implements the "NODECOMM" device driver that interacts directly
+ with the a-bus mailbox registers
+
+* __node_comm_exchange.C__
+  * The core of this module - the primary function nodeCommAbusExchange()
+ is implemented here and shows the high-level data flow between the nodes
+  * The procedure for the master node is defined in nodeCommAbusExchangeMaster()
+  * The procedure for the slave nodes is defiend in nodeCommAbusExchangeSlave()
+  * The interactions with the TPM - generating and logging SBID/Nonces, Quote
+ Requests, Quote Responses - are all in this file
+
+* __node_comm_test.C__
+  * Implements the proof-of-concept "nodeCommXbus2ProcTest" test to transfer
+ data across the x-bus between processors using a similar method to the a-bus
+ mechanism
+
+* __node_comm_transfer.C, node_comm_transfer.H__
+  * Defines and implements the different types of messages that can be sent
+ between the nodes, including the actual send and receive functions
+
+* __[README.md](./README.md)__
+  * This file
+

src/usr/secureboot/runtime/README.md

@@ -0,0 +1,21 @@
+# **'runtime'** Secureboot Services in Hostboot
+This directory implements a small, select subset of core secureboot-related
+ functionality that Hostboot provides at runtime, ie as part of
+ Hostboot runtime services.
+
+## Files
+
+* __makefile__
+  * Standard Hostboot makefile
+
+* __[README.md](./README.md)__
+  * This file
+
+* __rt_secureboot.C__
+  * This file implements several secureboot functions for hostboot runtime
+ services
+
+## sub-directories
+* __test__
+  * Standard Hostboot test directory that implements CXX Unit Tests
+

src/usr/secureboot/trusted/README.md

@@ -0,0 +1,74 @@
+# **'trusted'** Secureboot Services in Hostboot
+This directory implements the 'trusted' boot functionality that Hostboot
+ provides.
+It primarily does this by measuring and storing firmware images and system
+ data into the system's TPMs (Trusted Platform Modules).
+
+## Key Points
+* This code measures specific information on the system, including different
+ firmware images that are loaded onto the system by hostboot
+* These mesasurements, along with other system data, are stored in the TPMs
+ on the system
+* This code also determines which TPMs exist on the system, if they are
+ functional, and initializes them
+* To directly talk to the TPMs this code uses the TPM Device Driver, which
+ is built on top of the I2C Device Driver:
+  * [src/usr/i2c/tmpdd.C](../../i2c/tpmdd.C)
+  * [src/usr/i2c/tpmdd.H](../../i2c/tpmdd.H)
+
+* The **libsecureboot_trusted.so** module created here is available in
+ Hostboot's extended image
+* However, the code in the 'base' sub-directory is built into
+ libsecureboot_base.so and is available in Hostboot's base image
+* This module implements the interfaces defined in
+ [trustedbootif.H](../../../include/usr/secureboot/trustedbootif.H)
+
+## Files
+
+* __makefile__
+  * Standard Hostboot makefile
+
+* __[README.md](./README.md)__
+  * This file
+
+* __tpmLogMgr.C, tpmLogMgr.H__
+  * Defines and implements functions around the TPM Event Log, including
+ adding new events, extending the log to the TPM,  and moving the log to
+ different memory locations
+
+* __trustedTypes.C, trustedTypes.H__
+  * Defines different structures and methods for sending and receiving data
+ to and from the TPM
+
+* __trustedboot.C, trustedboot.H__
+  * Defines and implements the majority of the functions that interact with the
+ TPMs
+  * Implements the majority of the functions that verify and initialize the TPMs
+
+* __trustedbootCmds.C, trustedbootCmds.H__
+  * Defines and implements commands sent to the TPM and then processes (aka
+ marshall and unmarshall) the data appropriately
+
+* __trustedbootUtils.C, trustedbootUtils.H__
+  * Defines and implements a few utility functions like a wrapper to the TPM
+ Device Driver and creating trustedboot error logs.
+
+
+## sub-directories
+* __base__
+  * These files create a message queue to reserve operations that can be
+ implemented once the full Hostboot extended code, including
+ libsecureboot_trusted.so, is available to process them
+  * These files also take the basic operations that the Hostboot base code
+ needs and sends them to the message queue
+  * __trustedboot_base.C__
+    * Implements early trustedboot/TPM calls be calling into a message
+ queue so that they can be processed later
+
+  * __trustedbootMsg.C, trustedbootMsg.H__
+    * Defines and implements the message queue so that commands can be
+ processed later when libsecureboot_trusted.so is available
+
+* __test__
+  * Standard Hostboot test directory that implements CXX Unit Tests
+