COIL: update SPI terminology

This commit honors the new SPI terminology as defined here:
https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names

It also updates the comments in the code accordingly.

The #defines that use MSTR, NSS, SSI, SSM are not updated in this CL.
They will be addressed in a future CL since they require additional
thought.

BRANCH=None
BUG=b:163885307
TEST=compare_build.sh -b stm32 matches

Change-Id: Id24b055037937a49faddbe2cfa7bf57f9370b320
Signed-off-by: Ricardo Quesada <ricardoq@google.com>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3435066
Tested-by: Ricardo Quesada <ricardoq@chromium.org>
Reviewed-by: Aseda Aboagye <aaboagye@chromium.org>
Commit-Queue: Ricardo Quesada <ricardoq@chromium.org>
Auto-Submit: Ricardo Quesada <ricardoq@chromium.org>

6 files changed, 46 insertions, 45 deletions

diff --git a/chip/stm32/build.mk b/chip/stm32/build.mk
index 1e014a4cf9..9213ca3042 100644
--- a/chip/stm32/build.mk
+++ b/chip/stm32/build.mk
@@ -51,7 +51,7 @@ chip-y+=clock-f.o
 endif
 chip-$(CONFIG_FPU)+=fpu.o
 chip-$(CONFIG_SPI)+=spi.o
-chip-$(CONFIG_SPI_CONTROLLER)+=spi_master$(SPI_TYPE).o
+chip-$(CONFIG_SPI_CONTROLLER)+=spi_controller$(SPI_TYPE).o
 chip-$(CONFIG_COMMON_GPIO)+=gpio.o gpio-$(CHIP_FAMILY).o
 chip-$(CONFIG_COMMON_TIMER)+=hwtimer$(TIMER_TYPE).o
 chip-$(CONFIG_I2C)+=i2c-$(CHIP_FAMILY).o
diff --git a/chip/stm32/registers-stm32f4.h b/chip/stm32/registers-stm32f4.h
index 503a60cc64..12bfe31063 100644
--- a/chip/stm32/registers-stm32f4.h
+++ b/chip/stm32/registers-stm32f4.h
@@ -923,7 +923,7 @@ enum dma_channel {
 	STM32_DMAC_FMPI2C4_TX = STM32_DMA1_STREAM5,
 	STM32_DMAC_FMPI2C4_RX = STM32_DMA1_STREAM2,
 
-	/* Legacy naming for spi_master.c */
+	/* Legacy naming for spi_controller.c */
 	STM32_DMAC_SPI1_TX = STM32_DMA2_STREAM3, /* REQ 3 */
 	STM32_DMAC_SPI1_RX = STM32_DMA2_STREAM0, /* REQ 3 */
 	STM32_DMAC_SPI2_TX = STM32_DMA1_STREAM4, /* REQ 0 */
diff --git a/chip/stm32/registers-stm32f7.h b/chip/stm32/registers-stm32f7.h
index 2245d6775f..7c039c9d61 100644
--- a/chip/stm32/registers-stm32f7.h
+++ b/chip/stm32/registers-stm32f7.h
@@ -798,7 +798,7 @@ enum dma_channel {
 	STM32_DMAC_FMPI2C4_TX = STM32_DMA1_STREAM5,
 	STM32_DMAC_FMPI2C4_RX = STM32_DMA1_STREAM2,
 
-	/* Legacy naming for spi_master.c */
+	/* Legacy naming for spi_controller.c */
 	STM32_DMAC_SPI1_TX = STM32_DMA2_STREAM3, /* REQ 3 */
 	STM32_DMAC_SPI1_RX = STM32_DMA2_STREAM0, /* REQ 3 */
 	STM32_DMAC_SPI2_TX = STM32_DMA1_STREAM4, /* REQ 0 */
diff --git a/chip/stm32/registers-stm32h7.h b/chip/stm32/registers-stm32h7.h
index d02aaf1249..1ae8e3bdaa 100644
--- a/chip/stm32/registers-stm32h7.h
+++ b/chip/stm32/registers-stm32h7.h
@@ -839,7 +839,7 @@ enum dma_channel {
 	STM32_DMAC_FMPI2C4_TX = STM32_DMA1_STREAM5,
 	STM32_DMAC_FMPI2C4_RX = STM32_DMA1_STREAM2,
 
-	/* Legacy naming for spi_master.c */
+	/* Legacy naming for spi_controller.c */
 	STM32_DMAC_SPI1_TX = STM32_DMA2_STREAM3, /* REQ 3 */
 	STM32_DMAC_SPI1_RX = STM32_DMA2_STREAM0, /* REQ 3 */
 	STM32_DMAC_SPI2_TX = STM32_DMA1_STREAM4, /* REQ 0 */
diff --git a/chip/stm32/spi_master-stm32h7.c b/chip/stm32/spi_controller-stm32h7.c
index 4195dc595a..7792204a85 100644
--- a/chip/stm32/spi_master-stm32h7.c
+++ b/chip/stm32/spi_controller-stm32h7.c
@@ -3,7 +3,7 @@
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  *
- * SPI master driver.
+ * SPI controller driver.
  */
 
 #include "common.h"
@@ -16,7 +16,7 @@
 #include "timer.h"
 #include "util.h"
 
-/* SPI ports are used as master */
+/* SPI ports are used as controller */
 static stm32_spi_regs_t *SPI_REGS[] = {
 #ifdef CONFIG_STM32_SPI1_CONTROLLER
 	STM32_SPI1_REGS,
@@ -96,14 +96,14 @@ static uint8_t spi_enabled[ARRAY_SIZE(SPI_REGS)];
  * Initialize SPI module, registers, and clocks
  * @param spi_device  device to initialize.
  */
-static void spi_master_config(const struct spi_device_t *spi_device)
+static void spi_controller_config(const struct spi_device_t *spi_device)
 {
 	int port = spi_device->port;
 
 	stm32_spi_regs_t *spi = SPI_REGS[port];
 
 	/*
-	 * Set SPI master, baud rate, and software slave control.
+	 * Set SPI controller, baud rate, and software peripheral control.
 	 */
 	spi->cr1 = STM32_SPI_CR1_SSI;
 	spi->cfg2 = STM32_SPI_CFG2_MSTR | STM32_SPI_CFG2_SSM |
@@ -116,9 +116,9 @@ static void spi_master_config(const struct spi_device_t *spi_device)
 	dma_select_channel(dma_rx_option[port].channel, dma_req_rx[port]);
 }
 
-static int spi_master_initialize(const struct spi_device_t *spi_device)
+static int spi_controller_initialize(const struct spi_device_t *spi_device)
 {
-	spi_master_config(spi_device);
+	spi_controller_config(spi_device);
 
 	gpio_set_level(spi_device->gpio_cs, 1);
 
@@ -131,7 +131,7 @@ static int spi_master_initialize(const struct spi_device_t *spi_device)
 /**
  * Shutdown SPI module
  */
-static int spi_master_shutdown(const struct spi_device_t *spi_device)
+static int spi_controller_shutdown(const struct spi_device_t *spi_device)
 {
 	int rv = EC_SUCCESS;
 	int port = spi_device->port;
@@ -159,9 +159,9 @@ int spi_enable(const struct spi_device_t *spi_device, int enable)
 	if (enable == spi_enabled[port])
 		return EC_SUCCESS;
 	if (enable)
-		return spi_master_initialize(spi_device);
+		return spi_controller_initialize(spi_device);
 	else
-		return spi_master_shutdown(spi_device);
+		return spi_controller_shutdown(spi_device);
 }
 
 static int spi_dma_start(const struct spi_device_t *spi_device,
@@ -180,7 +180,7 @@ static int spi_dma_start(const struct spi_device_t *spi_device,
 	dma_clear_isr(dma_tx_option[port].channel);
 	dma_clear_isr(dma_rx_option[port].channel);
 	/* restore proper SPI configuration registers. */
-	spi_master_config(spi_device);
+	spi_controller_config(spi_device);
 
 	spi->cr2 = len;
 	spi->cfg1 |= STM32_SPI_CFG1_RXDMAEN;
diff --git a/chip/stm32/spi_master.c b/chip/stm32/spi_controller.c
index 8943c0c682..17bb5d8e32 100644
--- a/chip/stm32/spi_master.c
+++ b/chip/stm32/spi_controller.c
@@ -3,7 +3,7 @@
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  *
- * SPI master driver.
+ * SPI controller driver.
  */
 
 #include "common.h"
@@ -25,7 +25,7 @@
 #undef  HAS_SPI3
 #endif
 
-/* The second (and third if available) SPI port are used as master */
+/* The second (and third if available) SPI port are used as controller */
 static stm32_spi_regs_t *SPI_REGS[] = {
 #ifdef CONFIG_STM32_SPI1_CONTROLLER
 	STM32_SPI1_REGS,
@@ -148,56 +148,57 @@ static int spi_clear_tx_fifo(stm32_spi_regs_t *spi)
  *
  * - port: which port to initialize.
  */
-static int spi_master_initialize(const struct spi_device_t *spi_device)
+static int spi_controller_initialize(const struct spi_device_t *spi_device)
 {
 	int port = spi_device->port;
 
 	stm32_spi_regs_t *spi = SPI_REGS[port];
 
 	/*
-	 * Set SPI master, baud rate, and software slave control.
+	 * Set SPI controller, baud rate, and software peripheral control.
 	 * */
 
 	/*
 	 * STM32F412
-	 * Section 26.3.5 Slave select (NSS) pin management and Figure 276
+	 * Section 26.3.5 Chip select (NSS) pin management and Figure 276
 	 * https://www.st.com/resource/en/reference_manual/dm00180369.pdf#page=817
 	 *
 	 * The documentation in this section is a bit confusing, so here's a
 	 * summary based on discussion with ST:
 	 *
 	 * Software NSS management (SSM = 1):
-	 *   - In master mode, the NSS output is deactivated. You need to use a
-	 *     GPIO in output mode for slave select. This is generally used for
-	 *     multi-slave operation, but you can also use it for single slave
-	 *     operation. In this case, you should make sure to configure a GPIO
-	 *     for NSS, but *not* activate the SPI alternate function on that
-	 *     same pin since that will enable hardware NSS management (see
-	 *     below).
-	 *   - In slave mode, the NSS input level is equal to the SSI bit value.
+	 *   - In controller mode, the NSS output is deactivated. You need to
+	 *     use a GPIO in output mode for chip select. This is generally used
+	 *     for multi-peripheral operation, but you can also use it for
+	 *     single peripheral operation. In this case, you should make sure
+	 *     to configure a GPIO for NSS, but *not* activate the SPI alternate
+	 *     function on that same pin since that will enable hardware NSS
+	 *     management (see below).
+	 *   - In peripheral mode, the NSS input level is equal to the SSI bit
+	 *     value.
 	 *
 	 * Hardware NSS management (SSM = 0):
-	 *   - In slave mode, when NSS pin is detected low the slave (MCU) is
-	 *     selected.
-	 *   - In master mode, there are two configurations, depending on the
-	 *     SSOE bit in register SPIx_CR1.
+	 *   - In peripheral mode, when NSS pin is detected low the peripheral
+	 *     (MCU) is selected.
+	 *   - In controller mode, there are two configurations, depending on
+	 *     the SSOE bit in register SPIx_CR1.
 	 *       - NSS output enable (SSM=0, SSOE=1):
-	 *         The MCU (master) drives NSS low as soon as SPI is enabled
+	 *         The MCU (controller) drives NSS low as soon as SPI is enabled
 	 *         (SPE=1) and releases it when SPI is disabled (SPE=0).
 	 *
 	 *       - NSS output disable (SSM=0, SSOE=0):
-	 *         Allows multimaster capability. The MCU (master) drives NSS
-	 *         low.  If another master tries to takes control of the bus and
-	 *         NSS is pulled low, a mode fault is generated and the MCU
-	 *         changes to slave mode.
+	 *         Allows multi-controller capability. The MCU (controller)
+	 *         drives NSS low. If another controller tries to takes control
+	 *         of the bus and NSS is pulled low, a mode fault is generated
+	 *         and the MCU changes to peripheral mode.
 	 *
 	 *   - NSS output disable (SSM=0, SSOE=0): if the MCU is acting as
-	 *     master on the bus, this config allows multimaster capability. If
-	 *     the NSS pin is pulled low in this mode, the SPI enters master
-	 *     mode fault state and the device is automatically reconfigured in
-	 *     slave mode.  In slave mode, the NSS pin works as a standard "chip
-	 *     select" input and the slave is selected while NSS lin is at low
-	 *     level.
+	 *     controller on the bus, this config allows multi-controller
+	 *     capability. If the NSS pin is pulled low in this mode, the SPI
+	 *     enters controller mode fault state and the device is
+	 *     automatically reconfigured in peripheral mode. In peripheral
+	 *     mode, the NSS pin works as a standard "chip select" input and the
+	 *     peripheral is selected while NSS lin is at low level.
 	 */
 	spi->cr1 = STM32_SPI_CR1_MSTR | STM32_SPI_CR1_SSM | STM32_SPI_CR1_SSI |
 		   (spi_device->div << 3);
@@ -239,7 +240,7 @@ static int spi_master_initialize(const struct spi_device_t *spi_device)
 /**
  * Shutdown SPI module
  */
-static int spi_master_shutdown(const struct spi_device_t *spi_device)
+static int spi_controller_shutdown(const struct spi_device_t *spi_device)
 {
 	int rv = EC_SUCCESS;
 	int port = spi_device->port;
@@ -268,9 +269,9 @@ int spi_enable(const struct spi_device_t *spi_device, int enable)
 	if (enable == spi_enabled[spi_device->port])
 		return EC_SUCCESS;
 	if (enable)
-		return spi_master_initialize(spi_device);
+		return spi_controller_initialize(spi_device);
 	else
-		return spi_master_shutdown(spi_device);
+		return spi_controller_shutdown(spi_device);
 }
 
 static int spi_dma_start(int port, const uint8_t *txdata,