coil: cleanup commentsstabilize-rust-13720.B-cr50_stab

BUG=b:175244613
TEST=make buildall -j

Change-Id: Icbd143b072fdd5df3b67d7e5a09ee6c01a77f6b9
Signed-off-by: Mary Ruthven <mruthven@chromium.org>
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2622889
Reviewed-by: Namyoon Woo <namyoon@chromium.org>

8 files changed, 75 insertions, 59 deletions

diff --git a/chip/g/gpio.c b/chip/g/gpio.c
index f55e0fad35..a113419874 100644
--- a/chip/g/gpio.c
+++ b/chip/g/gpio.c
@@ -306,15 +306,19 @@ static void connect_pinmux(struct pinmux const *p)
 	int is_input;
 
 	if (p->flags & DIO_ENABLE_DIRECT_INPUT) {
-		/* We don't have to setup any muxes for directly connected
+		/*
+		 * We don't have to setup any muxes for directly connected
 		 * pads. The only ones that we are likely to ever care about
-		 * are tied to the SPS and SPI peripherals, and they're all
-		 * inouts, so we can just enable the digital input for them
-		 * regardless. */
+		 * are tied to the SPP and SPI peripherals, and they're all
+		 * inputs, so we can just enable the digital input for them
+		 * regardless.
+		 */
 		is_input = 1;
 	} else {
-		/* Pads that must be muxed to specific GPIOs or peripherals may
-		 * or may not be inputs. We'll check those individually. */
+		/*
+		 * Pads that must be muxed to specific GPIOs or peripherals may
+		 * or may not be inputs. We'll check those individually.
+		 */
 		if (p->flags & DIO_TO_PERIPHERAL)
 			is_input = connect_dio_to_peripheral(p);
 		else
diff --git a/chip/g/i2cp.c b/chip/g/i2cp.c
index 09d7235be6..ce98140289 100644
--- a/chip/g/i2cp.c
+++ b/chip/g/i2cp.c
@@ -203,7 +203,7 @@ DECLARE_DEFERRED(poll_read_state);
  * happens to fail and stops clocking.
  *
  * For example when the i2cp driver is:
- * 1) Transmitting an ACK for the slave address byte.
+ * 1) Transmitting an ACK for the peripheral address byte.
  * 2) Transmitting an ACK for a write transaction.
  * 3) Transmitting byte data for a read transaction.
  *
@@ -216,8 +216,8 @@ DECLARE_DEFERRED(poll_read_state);
  * We don't have to deal with the scenario where the driver gets stuck
  * transmitting a 1 on SDA since the controller can recover the bus by issuing a
  * normal transaction. The controller will at minimum clock 9 times on any
- * transaction. This is enough for the slave to complete its current operation
- * and NACK.
+ * transaction. This is enough for the peripheral to complete its current
+ * operation and NACK.
  */
 static void poll_read_state(void)
 {
diff --git a/chip/g/spi_controller.c b/chip/g/spi_controller.c
index 90ad033e46..912520e52f 100644
--- a/chip/g/spi_controller.c
+++ b/chip/g/spi_controller.c
@@ -23,14 +23,16 @@
  * by using the largest uint8_t clock divider of 256 (~235kHz). */
 #define SPI_TRANSACTION_TIMEOUT_USEC (5 * MSEC)
 
-/* There are two SPI masters or ports on this chip. */
+/* There are two SPI controllers or ports on this chip. */
 #define SPI_NUM_PORTS 2
 
 static struct mutex spi_mutex[SPI_NUM_PORTS];
 static enum spi_clock_mode clock_mode[SPI_NUM_PORTS];
 
-/* The Cr50 SPI master is not DMA auto-fill/drain capable, so async and flush
- * are not defined on purpose. */
+/*
+ * The Cr50 SPI controller is not DMA auto-fill/drain capable, so async and
+ * flush are not defined on purpose.
+ */
 int spi_transaction(const struct spi_device_t *spi_device,
 		    const uint8_t *txdata, int txlen,
 		    uint8_t *rxdata, int rxlen)
@@ -41,8 +43,10 @@ int spi_transaction(const struct spi_device_t *spi_device,
 	int transaction_size = 0;
 	int rxoffset = 0;
 
-	/* If SPI0's passthrough is enabled, SPI0 is not available unless the
-	 * SPS's BUSY bit is set. */
+	/*
+	 * If SPI0's passthrough is enabled, SPI0 is not available unless the
+	 * SPP's BUSY bit is set.
+	 */
 	if (port == 0) {
 		if (GREAD_FIELD_I(SPI, port, CTRL, ENPASSTHRU) &&
 		    !GREAD(SPS, EEPROM_BUSY_STATUS))
@@ -94,7 +98,7 @@ int spi_transaction(const struct spi_device_t *spi_device,
 	GWRITE_FIELD_I(SPI, port, XACT, SIZE, transaction_size - 1);
 	GWRITE_FIELD_I(SPI, port, XACT, START, 1);
 
-	/* Wait for the SPI master to finish the transaction. */
+	/* Wait for the SPI controller to finish the transaction. */
 	timeout.val = get_time().val + SPI_TRANSACTION_TIMEOUT_USEC;
 	while (!GREAD_FIELD_I(SPI, port, ISTATE, TXDONE)) {
 		/* Give up if the deadline has been exceeded. */
@@ -136,10 +140,11 @@ void set_spi_clock_mode(int port, enum spi_clock_mode mode)
 }
 
 /*
- * Configure the SPI0 master's passthrough mode. Note:
+ * Configure the SPI0 controller's passthrough mode. Note:
  * 1) This must be called after the SPI port is enabled.
- * 2) Passthrough cannot be safely disabled while the SPI slave port is active
- *    and the SPI slave port's status register's BUSY bit is not set.
+ * 2) Passthrough cannot be safely disabled while the SPI peripheral port is
+ *    active and the SPI peripheral port's status register's BUSY bit is not
+ *    set.
  */
 void configure_spi0_passthrough(int enable)
 {
@@ -201,7 +206,7 @@ int spi_enable(int port, int enable)
 		/* Set the clock divider, where freq / (div + 1). */
 		GWRITE_FIELD_I(SPI, port, CTRL, IDIV, max_div);
 
-		/* Master's CS is active low. */
+		/* Controller's CS is active low. */
 		GWRITE_FIELD_I(SPI, port, CTRL, CSBPOL, 0);
 
 		/* Byte 0 bit 7 is first in each double word in the buffers. */
@@ -255,9 +260,11 @@ static void spi_init(void)
 		/* Configure the SPI ports to default to mode0. */
 		set_spi_clock_mode(i, SPI_CLOCK_MODE0);
 
-		/* Ensure the SPI ports are disabled to prevent us from
+		/*
+		 * Ensure the SPI ports are disabled to prevent us from
 		 * interfering with the main chipset when we're not explicitly
-		 * using the SPI bus. */
+		 * using the SPI bus.
+		 */
 		spi_enable(i, 0);
 	}
 }
diff --git a/chip/g/spp.c b/chip/g/spp.c
index 5162b5652c..a4b4eaedaa 100644
--- a/chip/g/spp.c
+++ b/chip/g/spp.c
@@ -15,7 +15,7 @@
 #include "watchdog.h"
 
 /*
- * This file is a driver for the CR50 SPS (SPI slave) controller. The
+ * This file is a driver for the CR50 SPP (SPI peripheral) controller. The
  * controller deploys a 2KB buffer split evenly between receive and transmit
  * directions.
  *
@@ -70,7 +70,7 @@ void spp_tx_status(uint8_t byte)
 }
 
 /*
- * Push data to the SPS TX FIFO
+ * Push data to the SPP TX FIFO
  * @param data Pointer to 8-bit data
  * @param data_size Number of bytes to transmit
  * @return : actual number of bytes placed into tx fifo
@@ -116,7 +116,7 @@ int spp_transmit(uint8_t *data, size_t data_size)
 			fifo_contents = *spp_tx_fifo;
 			do {
 				/*
-				 * CR50 SPS controller does not allow byte
+				 * CR50 SPP controller does not allow byte
 				 * accesses for writes into the FIFO, so read
 				 * modify/write is required. Tracked under
 				 * http://b/20894727
@@ -164,7 +164,7 @@ int spp_transmit(uint8_t *data, size_t data_size)
 static int spp_cs_asserted(void)
 {
 	/*
-	 * Read the current value on the SPS CS line and return the iversion
+	 * Read the current value on the SPP CS line and return the iversion
 	 * of it (CS is active low).
 	 */
 	return !GREAD_FIELD(SPS, VAL, CSB);
@@ -255,7 +255,7 @@ int spp_register_rx_handler(enum spp_mode mode, rx_handler_f rx_handler,
 	return 0;
 }
 
-/* Function that sets up for SPS to enable INT_AP_L extension. */
+/* Function that sets up for SPP to enable INT_AP_L extension. */
 static void spp_int_ap_extension_enable_(void)
 {
 	enable_cs_assert_irq_();
@@ -266,8 +266,8 @@ static void spp_int_ap_extension_enable_(void)
 static void spp_init(void)
 {
 	/*
-	 * Check to see if slave SPI interface is required by the board before
-	 * initializing it. If SPI option is not set, then just return.
+	 * Check to see if peripheral SPI interface is required by the board
+	 * before initializing it. If SPI option is not set, then just return.
 	 */
 	if (!board_tpm_uses_spi())
 		return;
@@ -459,7 +459,7 @@ DECLARE_IRQ(GC_IRQNUM_SPS0_CS_ASSERT_INTR, sps0_cs_assert_interrupt_, 1);
 
 #ifdef CONFIG_SPP_TEST
 
-/* Function to test SPS driver. It expects the host to send SPI frames of size
+/* Function to test SPP driver. It expects the host to send SPI frames of size
  * <size> (not exceeding 1100) of the following format:
  *
  * <size/256> <size%256> [<size> bytes of payload]
diff --git a/chip/g/spp_tpm.c b/chip/g/spp_tpm.c
index a2bb4be171..bdd58b7be3 100644
--- a/chip/g/spp_tpm.c
+++ b/chip/g/spp_tpm.c
@@ -21,30 +21,31 @@
  *
  * ANYWAY, The goal of the TPM protocol is to provide read and write access to
  * device registers over the SPI bus. It is defined as follows (note that the
- * master clocks the bus, but both master and slave transmit data
+ * controller clocks the bus, but both controller and peripheral transmit data
  * simultaneously).
  *
- * Each transaction starts with the master clocking the bus to transfer 4
+ * Each transaction starts with the controller clocking the bus to transfer 4
  * bytes:
  *
- * The master sends 4 bytes:       [R/W+size-1] [Addr] [Addr] [Addr]
- * The slave also sends 4 bytes:       [xx]      [xx]   [xx]   [x?]
+ * The controller sends 4 bytes:       [R/W+size-1] [Addr] [Addr] [Addr]
+ * The peripheral also sends 4 bytes:  [xx]      [xx]   [xx]   [x?]
  *
- * Bytes sent by the master define the direction and size (1-64 bytes) of the
- * data transfer, and the address of the register to access.
+ * Bytes sent by the controller define the direction and size (1-64 bytes) of
+ * the data transfer, and the address of the register to access.
  *
- * The final bit of the 4th slave response byte determines whether or not the
- * slave needs some extra time. If that bit is 1, the master can IMMEDIATELY
- * clock in (or out) the number of bytes it specified with the header byte 0.
+ * The final bit of the 4th peripheral response byte determines whether or not
+ * the peripheral needs some extra time. If that bit is 1, the controller can
+ * IMMEDIATELY clock in (or out) the number of bytes it specified with the
+ * header byte 0.
  *
- * If the final bit of the 4th response byte is 0, the master clocks eight more
- * bits and looks again at the new received byte. It repeats this process
+ * If the final bit of the 4th response byte is 0, the controller clocks eight
+ * more bits and looks again at the new received byte. It repeats this process
  * (clock 8 bits, look at last bit) as long as every eighth bit is 0.
  *
- * When the slave is ready to proceed with the data transfer, it returns a 1
- * for the final bit of the response byte, at which point the master has to
- * resume transferring valid data for write transactions or to start reading
- * bytes sent by the slave for read transactions.
+ * When the peripheral is ready to proceed with the data transfer, it returns a
+ * 1 for the final bit of the response byte, at which point the controller has
+ * to resume transferring valid data for write transactions or to start reading
+ * bytes sent by the peripheral for read transactions.
  *
  * So here's what a 4-byte write of value of 0x11223344 to register 0xAABBCC
  * might look like:
@@ -53,9 +54,10 @@
  *   MOSI: 03 aa bb cc xx xx xx 11 22 33 44
  *   MISO: xx xx xx x0 x0 x0 x1 xx xx xx xx
  *
- * Bit 0 of MISO xfer #4 is 0, indicating that the slave needs to stall. The
- * slave stalled for three bytes before it was ready to continue accepting the
- * input data from the master. The slave released the stall in xfer #7.
+ * Bit 0 of MISO xfer #4 is 0, indicating that the peripheral needs to stall.
+ * The peripheral stalled for three bytes before it was ready to continue
+ * accepting the input data from the controller. The peripheral released the
+ * stall in xfer #7.
  *
  * Here's a 4-byte read from register 0xAABBCC:
  *
@@ -63,8 +65,8 @@
  *   MOSI: 83 aa bb cc xx xx xx xx xx xx xx
  *   MISO: xx xx xx x0 x0 x0 x1 11 22 33 44
  *
- * As before, the slave stalled the read for three bytes and indicated it was
- * done stalling at xfer #7.
+ * As before, the peripheral stalled the read for three bytes and indicated it
+ * was done stalling at xfer #7.
  *
  * Note that the ONLY place where a stall can be initiated is the last bit of
  * the fourth MISO byte of the transaction. Once the stall is released,
@@ -85,7 +87,7 @@
 /*
  * Incoming messages are collected here until they're ready to process. The
  * buffer will start with a four-byte header, followed by whatever data
- * is sent by the master (none for a read, 1 to 64 bytes for a write).
+ * is sent by the controller (none for a read, 1 to 64 bytes for a write).
  */
 #define RXBUF_MAX 512			/* chosen arbitrarily */
 static uint8_t rxbuf[RXBUF_MAX];
@@ -176,7 +178,7 @@ static void process_rx_data(uint8_t *data, size_t data_size, int cs_deasserted)
 		}
 
 		/*
-		 * Write the new idle byte value, to signal the master to
+		 * Write the new idle byte value, to signal the controller to
 		 * proceed with data.
 		 */
 		spp_tx_status(TPM_STALL_DEASSERT);
diff --git a/chip/host/spi_controller.c b/chip/host/spi_controller.c
index 83bde96163..e7dfae481e 100644
--- a/chip/host/spi_controller.c
+++ b/chip/host/spi_controller.c
@@ -2,7 +2,7 @@
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  *
- * Dummy Master SPI driver for unit test.
+ * Dummy SPI Controller driver for unit test.
  */
 
 #include <stdint.h>
diff --git a/chip/lm4/gpio.c b/chip/lm4/gpio.c
index 65d6548f90..39baae3bf6 100644
--- a/chip/lm4/gpio.c
+++ b/chip/lm4/gpio.c
@@ -328,7 +328,7 @@ static void gpio_interrupt(int port, uint32_t mis)
 
 /**
  * Handlers for each GPIO port.  These read and clear the interrupt bits for
- * the port, then call the master handler above.
+ * the port, then call the controller handler above.
  */
 #define GPIO_IRQ_FUNC(irqfunc, gpiobase)		\
 	void irqfunc(void)				\
diff --git a/chip/lm4/lpc.c b/chip/lm4/lpc.c
index 0c672bd63a..8a59d6b434 100644
--- a/chip/lm4/lpc.c
+++ b/chip/lm4/lpc.c
@@ -759,16 +759,19 @@ static void lpc_init(void)
 #endif
 
 	/*
-	 * Ensure the EC (slave) has control of the memory-mapped I/O space.
-	 * Once the EC has won arbitration for the memory-mapped space, it will
-	 * keep control of it until it writes the last byte in the space.
-	 * (That never happens; we can't use the last byte in the space because
-	 * ACPI can't see it anyway.)
+	 * Ensure the EC (peripheral) has control of the memory-mapped I/O
+	 * space. Once the EC has won arbitration for the memory-mapped space,
+	 * it will keep control of it until it writes the last byte in the
+	 * space. (That never happens; we can't use the last byte in the space
+	 * because ACPI can't see it anyway.)
 	 */
 	while (!(LM4_LPC_ST(LPC_CH_MEMMAP) & 0x10)) {
 		/* Clear HW1ST */
 		LM4_LPC_ST(LPC_CH_MEMMAP) &= ~0x40;
-		/* Do a dummy slave write; this should cause SW1ST to be set */
+		/*
+		 * Do a dummy peripheral write; this should cause SW1ST to be
+		 * set.
+		 */
 		*LPC_POOL_MEMMAP = *LPC_POOL_MEMMAP;
 	}