soc/amd/common/block/psp: Add comments

Explain when the MBOX_PSP return codes are send and which behaviour
is invoked by the PSP when seeing such return codes.

Change-Id: Ibe7ceb5d7cd025f3b3ab0c9167d23f6eb664c165
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/88511
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-by: Alicja Michalska <ahplka19@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

src/soc/amd/common/block/psp/psp_def.h

@@ -143,9 +143,21 @@ enum mbox_p2c_status {
 	MBOX_PSP_SUCCESS		= 0x00,
 	MBOX_PSP_INVALID_PARAMETER	= 0x01,
 	MBOX_PSP_CRC_ERROR		= 0x02,
+	/*
+	 * Send to PSP when the requested SPI command in the psp_smi_handler()
+	 * handler failed due to an unknown error. The PSP usually doesn't like
+	 * seeing this return code and will stop operating.
+	 */
 	 MBOX_PSP_COMMAND_PROCESS_ERROR	= 0x04,
 	 MBOX_PSP_UNSUPPORTED		= 0x08,
 	 MBOX_PSP_SPI_BUSY_ASYNC	= 0x0a,
+	 /*
+	  * Send to PSP when the requested SPI command in the psp_smi_handler()
+	  * handler cannot be executed right away. This can happen when the SPI
+	  * flash is busy or the SPI controller is busy or being used by ring 0.
+	  *
+	  * The PSP will raise an SMI later again.
+	  */
 	 MBOX_PSP_SPI_BUSY		= 0x0b,
 };
 

src/soc/amd/common/block/psp/psp_smi_flash.c

@@ -92,6 +92,14 @@ static enum mbox_p2c_status find_psp_spi_flash_device_region(uint64_t target_nv_
 	return MBOX_PSP_SUCCESS;
 }
 
+/*
+ * Returns true when the SPI flash is busy, the SPI controller is busy or the SPI
+ * MMIO register access is blocked by ring0. When the SPI flash is busy all
+ * operations, including reading, would fail.
+ * Thus even memory mapped structures like FMAP would not be accessible
+ * from memory mapped SPI flash (ROM2/ROM3). Caller must return MBOX_PSP_SPI_BUSY
+ * to PSP when this function returns true.
+ */
 static bool spi_controller_busy(void)
 {
 	bool busy;