From a1b83207fbbeb97471cb234576af59287a5d88ed Mon Sep 17 00:00:00 2001 From: Mary Ruthven Date: Wed, 6 Jan 2021 08:50:24 -0800 Subject: coil: cleanup i2c comments Remove coil terms from i2c comments BUG=b:175244613 TEST=make buildall -j Change-Id: If056c099304e1fa676991e22ddaa9cb91ccfdeb3 Signed-off-by: Mary Ruthven Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/2613509 Reviewed-by: Namyoon Woo --- board/cr50/board.c | 6 +-- board/cr50/board.h | 4 +- board/cr50/gpio.inc | 14 +++---- board/cr50/usb_i2c.c | 2 +- chip/g/i2cc.c | 16 +++---- chip/g/i2cp.c | 78 +++++++++++++++++----------------- chip/g/i2cp.h | 14 +++---- chip/g/ite_flash.c | 11 ++--- chip/lm4/i2c.c | 12 +++--- common/i2c_controller.c | 12 +++--- common/i2c_peripheral.c | 2 +- common/i2c_wedge.c | 4 +- common/i2cp_tpm.c | 20 ++++----- docs/case_closed_debugging_cr50.md | 2 +- docs/ec_terms.md | 12 +++--- include/config.h | 14 +++---- include/ec_commands.h | 4 +- include/i2c.h | 85 +++++++++++++++++++++----------------- include/usb_i2c.h | 6 +-- include/usb_mux.h | 2 +- 20 files changed, 164 insertions(+), 156 deletions(-) diff --git a/board/cr50/board.c b/board/cr50/board.c index 6968ac44bb..1f5ad35e3b 100644 --- a/board/cr50/board.c +++ b/board/cr50/board.c @@ -570,7 +570,7 @@ void pmu_wakeup_interrupt(void) reset_wake_logic(); /* - * Delay sleep long enough for a SPI slave transaction to start + * Delay sleep long enough for a SPI periph transaction to start * or for the system to be reset. */ delay_sleep_by(5 * SECOND); @@ -589,7 +589,7 @@ DECLARE_IRQ(GC_IRQNUM_PMU_INTR_WAKEUP_INT, pmu_wakeup_interrupt, 1); void board_configure_deep_sleep_wakepins(void) { /* - * Disable the i2c and spi slave wake sources since the TPM is + * Disable the i2c and spi periph wake sources since the TPM is * not being used and reenable them in their init functions on * resume. */ @@ -1591,7 +1591,7 @@ void i2cp_set_pinmux(void) /* * Provide access to the SDA line to be able to detect 'hosed i2c - * slave' condition. + * periph' condition. */ GWRITE(PINMUX, GPIO0_GPIO14_SEL, GC_PINMUX_DIOA1_SEL); diff --git a/board/cr50/board.h b/board/cr50/board.h index bf54ba7c9f..6817751699 100644 --- a/board/cr50/board.h +++ b/board/cr50/board.h @@ -426,8 +426,8 @@ void board_start_ite_sync(void); /* * Board specific function (needs information about pinmux settings) which - * allows to take the i2cp controller out of the 'wedged' state where the - * master stopped i2c access mid transaction and the slave is holding SDA low, + * allows to take the i2cp driver out of the 'wedged' state where the controller + * stopped i2c access mid transaction and the periph is holding SDA low. */ void board_unwedge_i2cp(void); diff --git a/board/cr50/gpio.inc b/board/cr50/gpio.inc index ec09d88a4c..3c01e4199e 100644 --- a/board/cr50/gpio.inc +++ b/board/cr50/gpio.inc @@ -14,15 +14,15 @@ * Ports' architecture and programmig is described in "ARM Cortex-M System * Design Kit TRM" DDIO47B. * - * - a set of peripherals - slave and master SPI and I2C controllers, UARTs, - * interrupt controller, etc. + * - a set of modules - SPI and I2C controller and peripheral interfaces, + * UARTs, interrupt controller, etc. * * - 28 pins on the package named DIOA0..14, DIOB0..7 and DIOM0..4 * * - a PINMUX - a unit which allows to interconnect objects from the three - * groups listed above. Note that some peripherals are attached to some - * pins directly, so in case those peripherals are used the pins should - * not be connected by PINMUX to any other outputs. + * groups listed above. Note that some modules are attached to some pins + * directly, so in case those modules are used the pins should not be + * connected by PINMUX to any other outputs. * * The below macros are somewhat misleading (apparently for historical * reasons), as PIN(p, b) component in fact refers not to the external pin, @@ -293,7 +293,7 @@ PINMUX(GPIO(DETECT_SERVO), B5, DIO_INPUT) * I2CP pins are bi-directional and would be configured here as shown. However, * A1 is also used as a strapping option GPIO input which is configured * above. If a board is configured (via the strapping pins) to support the I2CP - * interface, then the connection of A1 and A9 to/from the I2C0_SDA and I2C0_SCL + * driver, then the connection of A1 and A9 to/from the I2C0_SDA and I2C0_SCL * lines is done in the function i2cp_set_pinmux() which lives in board.c. * * PINMUX(FUNC(I2C0_SCL), A9, DIO_INPUT) @@ -315,7 +315,7 @@ PINMUX(GPIO(DETECT_SERVO), B5, DIO_INPUT) * DIOA8 = SPI_CLK (output) * DIOA11 = SPI_MISO (input) * DIOA14 = SPI_CS_L (output) - * The pads are only connected to the peripheral outputs when SPI is enabled to + * The pads are only connected to the module outputs when SPI is enabled to * avoid interfering with other things on the board. * Note: Double-check to be sure these are configured in spi_master.c */ diff --git a/board/cr50/usb_i2c.c b/board/cr50/usb_i2c.c index 39e4a4f27c..1e875a3b8f 100644 --- a/board/cr50/usb_i2c.c +++ b/board/cr50/usb_i2c.c @@ -60,7 +60,7 @@ static void ina_connect(void) GWRITE(PINMUX, I2C0_SDA_SEL, GC_PINMUX_DIOB1_SEL); GWRITE(PINMUX, I2C0_SCL_SEL, GC_PINMUX_DIOB0_SEL); - /* Connect I2CS SDA/SCL output to B1/B0 pads */ + /* Connect i2cp SDA/SCL output to B1/B0 pads */ GWRITE(PINMUX, DIOB1_SEL, GC_PINMUX_I2C0_SDA_SEL); GWRITE(PINMUX, DIOB0_SEL, GC_PINMUX_I2C0_SCL_SEL); diff --git a/chip/g/i2cc.c b/chip/g/i2cc.c index ad80c3b724..b2f2fcaef9 100644 --- a/chip/g/i2cc.c +++ b/chip/g/i2cc.c @@ -4,7 +4,7 @@ */ /* - * This is a driver for the I2C controller interface (i2cc) of the g chip. + * This is a driver for the I2C controller driver (i2cc) of the g chip. * * The g chip i2cc module supports 3 modes of operation, disabled, bit-banging, * and instruction based. These modes are selected via the I2C_CTRL @@ -34,10 +34,10 @@ * compound instruction for the transaction: * * I2C_INST_START = 1 -> send start bit - * I2C_INST_FWDEVADDR = 1 -> first send the slave device address + * I2C_INST_FWDEVADDR = 1 -> first send the periph device address * I2C_INST_FWBYTESCOUNT = 3 -> 3 bytes in FWBYTES (register + 16 bit value) * I2C_INST_FINALSTOP = 1 -> send stop bit - * I2C_INST_DEVADDRVAL = slave address + * I2C_INST_DEVADDRVAL = periph address * * I2C_FWBYTES[b7:b0] = out[0] -> register address * I2C_FWBYTES[b15:b8] = out[1] -> first byte of value @@ -47,14 +47,14 @@ * compound instruction for the transaction: * * I2C_INST_START = 1 -> send start bit - * I2C_INST_FWDEVADDR = 1 -> first send the slave device address + * I2C_INST_FWDEVADDR = 1 -> first send the periph device address * I2C_INST_FWBYTESCOUNT = 1 -> 1 byte in FWBYTES (register address) * I2C_INST_REPEATEDSTART = 1 -> send start bit following write - * I2C_INST_RWDEVADDR = 1 -> send slave address in read mode - * I2C_INST_RWDEVADDR_RWB = 1 -> read bytes following slave address + * I2C_INST_RWDEVADDR = 1 -> send periph address in read mode + * I2C_INST_RWDEVADDR_RWB = 1 -> read bytes following periph address * I2C_INST_FINALNA = 1 -> ACK read bytes, NACK last byte read * I2C_INST_FINALSTOP = 1 -> send stop bit - * I2C_INST_DEVADDRVAL = slave address + * I2C_INST_DEVADDRVAL = periph address * I2C_FWBYTES[b7:b0] = out[0] -> register address byte * * Once transaction is complete: @@ -254,7 +254,7 @@ static uint32_t i2cc_create_inst(int periph_addr_flags, int is_write, if (flags & I2C_XFER_START) { /* - * Start sequence will have to be issued, slave address needs + * Start sequence will have to be issued, periph address needs * to be included. */ inst |= INST_START; diff --git a/chip/g/i2cp.c b/chip/g/i2cp.c index 801ce05968..09d7235be6 100644 --- a/chip/g/i2cp.c +++ b/chip/g/i2cp.c @@ -7,17 +7,17 @@ * This is a driver for the I2C peripheral (i2cp) of the g chip. * * The driver has two register files, 64 bytes each, one for storing data - * received from the master, and one for storing data to be transmitted to the - * master. Both files are accessed only as 4 byte quantities, so the driver - * must provide adaptation to concatenate messages with sizes not divisible by - * 4 and or not properly aligned. + * received from the controller, and one for storing data to be transmitted to + * the controller. Both files are accessed only as 4 byte quantities, so the + * driver must provide adaptation to concatenate messages with sizes not + * divisible by 4 and or not properly aligned. * - * The file holding data written by the master has associated with it a + * The file holding data written by the controller has associated with it a * register showing where the driver accessed the file last, comparing it * with its previous value tells the driver how many bytes recently written by - * the master are there. + * the controller are there. * - * The file holding data to be read by the master has a register associated + * The file holding data to be read by the controller has a register associated * with it showing where was the latest BIT the driver transmitted. * * The driver can generate interrupts on three different conditions: @@ -26,35 +26,35 @@ * - end of a write cycle * * Since this driver's major role is to serve as a TPM interface, it is safe - * to assume that the master will always write first, even when it needs to + * to assume that the controller will always write first, even when it needs to * read data from the device. * - * Each write or read access will be started by the master writing the one + * Each write or read access will be started by the controller writing the one * byte address of the TPM register to access. * - * If the master needs to read this register, the originating write + * If the controller needs to read this register, the originating write * transaction will be limited to a single byte payload, a read transaction * would follow immediately. * - * If the master needs to write into this register, the data to be written + * If the controller needs to write into this register, the data to be written * will be included in the same i2c transaction immediately following the one * byte register address. * * This protocol allows to keep the driver simple: the only interrupt the * driver enables is the 'end a write cycle'. The number of bytes received - * from the master gives the callback function a hint as of what the master - * intention is, to read or to write. + * from the controller gives the callback function a hint as of what the + * controller intention is, to read or to write. * * In both cases the same callback function is called. On write accesses the * callback function converts the data as necessary and passes it to the TPM. * On read accesses the callback function retrieves data from the TPM and puts - * it into the read register file to be available to the master to retrieve in - * the following read access. In both cases the callback function completes + * it into the read register file to be available to the controller to retrieve + * in the following read access. In both cases the callback function completes * processing on the invoking interrupt context. * * The driver API consists of two functions, one to register the callback to - * process interrupts, another one - to add a byte to the master read register - * file. See the accompanying .h file for details. + * process interrupts, another one - to add a byte to the congroller read + * register file. See the accompanying .h file for details. * * TODO: * - figure out flow control - clock stretching can be challenging with this @@ -87,19 +87,19 @@ static wr_complete_handler_f write_complete_handler_; static uint8_t i2cp_buffer[REGISTER_FILE_SIZE]; /* - * Pointer where the CPU stopped retrieving the write data sent by the master - * last time the write access was processed. + * Pointer where the CPU stopped retrieving the write data sent by the + * controller last time the write access was processed. */ static uint16_t last_write_pointer; /* - * Pointer where the CPU stopped writing data for the master to read last time - * the read data was prepared. + * Pointer where the CPU stopped writing data for the controller to read last + * time the read data was prepared. */ static uint16_t last_read_pointer; /* - * Keep track number of times the "hosed slave" condition was encountered. + * Keep track number of times the "hosed periph" condition was encountered. */ static uint16_t i2cp_read_recovery_count; static uint16_t i2cp_sda_low_count; @@ -139,13 +139,13 @@ static void i2cp_init(void) GWRITE(I2CS, READ_PTR, 0); GWRITE(I2CS, WRITE_PTR, 0); - /* Just in case we were wedged and the master starts with a read. */ + /* Just in case we were wedged and the controller starts with a read. */ *GREG32_ADDR(I2CS, READ_BUFFER0) = ~0; /* Enable I2CP interrupt */ GWRITE_FIELD(I2CS, INT_ENABLE, INTR_WRITE_COMPLETE, 1); - /* Slave address is hardcoded to 0x50. */ + /* periph address is hardcoded to 0x50. */ GWRITE(I2CS, SLAVE_DEVADDRVAL, 0x50); } @@ -176,7 +176,7 @@ DECLARE_DEFERRED(poll_read_state); * If the poller happened to run during time 3 and time 4 while SDA was low, * i2cp_sda_low_count would = 2. This is not considered an error case. If we * were to see a third low value before time 5, we can assume the bus is stuck, - * or the master performed multiple reads between writes (which is not + * or the controller performed multiple reads between writes (which is not * expected). * * If we were to enable the read complete interrupt and use it to clear @@ -199,7 +199,7 @@ DECLARE_DEFERRED(poll_read_state); * Restart the i2cp driver if the driver gets stuck transmitting a 0 on * SDA. * - * This can happen anytime the i2cp driver has control of SDA and the master + * This can happen anytime the i2cp driver has control of SDA and the controller * happens to fail and stops clocking. * * For example when the i2cp driver is: @@ -207,15 +207,15 @@ DECLARE_DEFERRED(poll_read_state); * 2) Transmitting an ACK for a write transaction. * 3) Transmitting byte data for a read transaction. * - * The reason this is problematic is because the master can't recover the bus - * by issuing a new transaction. A start condition is defined as the master - * pulling SDA low while SCL is high. The master can only initiate the start - * condition when the bus is free (i.e., SDA is high), otherwise the master + * The reason this is problematic is because the i2cc can't recover the bus + * by issuing a new transaction. A start condition is defined as the i2cc + * pulling SDA low while SCL is high. The i2cc can only initiate the start + * condition when the bus is free (i.e., SDA is high), otherwise the i2cc * thinks that it lost arbitration. * * We don't have to deal with the scenario where the driver gets stuck - * transmitting a 1 on SDA since the master can recover the bus by issuing a - * normal transaction. The master will at minimum clock 9 times on any + * 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. */ @@ -226,16 +226,16 @@ static void poll_read_state(void) * When the AP is off, the SDA line might drop low since the * pull ups might not be powered. * - * If the AP is on, the bus is either idle, the master has + * If the AP is on, the bus is either idle, the controller has * stopped clocking while SDA is high, or we have polled in the * middle of a transaction where SDA happens to be high. */ i2cp_sda_low_count = 0; } else { /* - * The master has stopped clocking while the slave is holding - * SDA low, or we have polled in the middle of a transaction - * where SDA happens to be low. + * The controller has stopped clocking while the periph is + * holding SDA low, or we have polled in the middle of a + * transaction where SDA happens to be low. */ i2cp_sda_low_count++; @@ -280,7 +280,7 @@ void __attribute__((used)) _i2cp_write_complete_int(void) uint16_t bytes_processed; uint32_t word_in_value = 0; - /* How many bytes has the master just written. */ + /* How many bytes has the controller just written. */ bytes_written = ((uint16_t)GREAD(I2CS, WRITE_PTR) - last_write_pointer) & REGISTER_FILE_MASK; @@ -294,7 +294,7 @@ void __attribute__((used)) _i2cp_write_complete_int(void) while (bytes_written != bytes_processed) { /* * This loop iterates over bytes retrieved from the - * master write register file in 4 byte quantities. + * controller write register file in 4 byte quantities. * Each time the ever incrementing last_write_pointer * is aligned at 4 bytes, a new value needs to be * retrieved from the next register, indexed by @@ -321,7 +321,7 @@ void __attribute__((used)) _i2cp_write_complete_int(void) write_complete_handler_(i2cp_buffer, bytes_processed); } - /* The transaction is complete so the slave has released SDA. */ + /* The transaction is complete so the periph has released SDA. */ i2cp_sda_low_count = 0; /* diff --git a/chip/g/i2cp.h b/chip/g/i2cp.h index 5ab7286fc7..f7c5d283dd 100644 --- a/chip/g/i2cp.h +++ b/chip/g/i2cp.h @@ -19,13 +19,13 @@ typedef void (*wr_complete_handler_f)(void *i2cp_data, size_t i2cp_data_size); int i2cp_register_write_complete_handler(wr_complete_handler_f wc_handler); /* - * Post a byte for the master to read. Blend the byte into the appropriate - * 4byte register of the master read register file. + * Post a byte for the controller to read. Blend the byte into the appropriate + * 4byte register of the controller read register file. */ void i2cp_post_read_data(uint8_t byte_to_read); /* - * Configure the pinmux registers required to connect the I2CP interface. This + * Configure the pinmux registers required to connect the I2CP driver. This * function is board specific and so it exists in the associated board.c file. */ void i2cp_set_pinmux(void); @@ -41,7 +41,7 @@ void i2cp_set_pinmux(void); size_t i2cp_zero_read_fifo_buffer_depth(void); /* - * Write buffer of data into the I2CS HW read fifo. The function will operate a + * Write buffer of data into the I2CP HW read fifo. The function will operate a * byte at a time until the fifo write pointer is word aligned. Then it will * consume all remaining words of input data. There is another stage to handle * any excess bytes. The efficiency benefits relative the byte at a time @@ -51,10 +51,10 @@ size_t i2cp_zero_read_fifo_buffer_depth(void); void i2cp_post_read_fill_fifo(uint8_t *buffer, size_t len); /* - * Provide upper layers with information with the I2CP interface + * Provide upper layers with information with the I2CP driver * status/statistics. The only piece of information currently provided is the - * counter of "hosed" i2c interface occurences, where i2c clocking stopped - * while slave was transmitting a zero. + * counter of "hosed" i2c driver occurences, where i2c clocking stopped + * while periph was transmitting a zero. */ struct i2cp_status { uint16_t read_recovery_count; diff --git a/chip/g/ite_flash.c b/chip/g/ite_flash.c index b4e1699a08..d010e7beca 100644 --- a/chip/g/ite_flash.c +++ b/chip/g/ite_flash.c @@ -57,9 +57,9 @@ void generate_ite_sync(void) (both_one >> 8) * 4); /* - * Let's take over the i2c master pins. Connect pads DIOB0(aka i2c - * scl) to gpio0.12 and DIOB1(aka sda) to gpio0.13. I2c master - * controller is disconnected from the pads. + * Let's take over the i2c controller pins. Connect pads DIOB0(aka i2c + * scl) to gpio0.12 and DIOB1(aka sda) to gpio0.13. I2c controller + * is disconnected from the pads. */ REG32(GBASE(PINMUX) + GOFFSET(PINMUX, DIOB0_SEL)) = GC_PINMUX_GPIO0_GPIO12_SEL; @@ -86,10 +86,7 @@ void generate_ite_sync(void) interrupt_enable(); - /* - * Restore I2C configuration, re-attach i2c master controller to the - * pads. - */ + /* Restore I2C configuration, re-attach i2c controller to the pads. */ REG32(GBASE(PINMUX) + GOFFSET(PINMUX, DIOB0_SEL)) = GC_PINMUX_I2C0_SCL_SEL; REG32(GBASE(PINMUX) + GOFFSET(PINMUX, DIOB1_SEL)) = diff --git a/chip/lm4/i2c.c b/chip/lm4/i2c.c index 2392182415..9481d66e66 100644 --- a/chip/lm4/i2c.c +++ b/chip/lm4/i2c.c @@ -40,7 +40,7 @@ /* * Minimum delay between resetting the port or sending a stop condition, and - * when the port can be expected to be back in an idle state (and the slave + * when the port can be expected to be back in an idle state (and the periph * has had long enough to see the start/stop condition edges). * * 500 us = 50 clocks at 100 KHz bus speed. This has been experimentally @@ -103,7 +103,7 @@ int i2c_do_work(int port) /* * Error after starting; abort transfer. Ignore errors at * start because arbitration and timeout errors are taken care - * of in chip_i2c_xfer(), and slave ack failures will + * of in chip_i2c_xfer(), and periph ack failures will * automatically clear once we send a start condition. */ pd->err = EC_ERROR_UNKNOWN; @@ -212,13 +212,13 @@ int chip_i2c_xfer(const int port, const uint16_t periph_addr_flags, LM4_I2C_MTPR(port) = tpr; /* - * We don't know what edges the slave saw, so sleep long enough - * that the slave will see the new start condition below. + * We don't know what edges the periph saw, so sleep long enough + * that the periph will see the new start condition below. */ usleep(I2C_IDLE_US); } - /* Set slave address for transmit */ + /* Set periph address for transmit */ LM4_I2C_MSA(port) = (I2C_GET_ADDR(periph_addr_flags) << 1) & 0xff; /* Enable interrupts */ @@ -358,7 +358,7 @@ void i2c_init(void) /* Configure GPIOs */ gpio_config_module(MODULE_I2C, 1); - /* Initialize ports as master, with interrupts enabled */ + /* Initialize ports as controller, with interrupts enabled */ for (i = 0; i < i2c_ports_used; i++) LM4_I2C_MCR(i2c_ports[i].port) = 0x10; diff --git a/common/i2c_controller.c b/common/i2c_controller.c index 5a8f58196f..ac65483185 100644 --- a/common/i2c_controller.c +++ b/common/i2c_controller.c @@ -775,13 +775,13 @@ int i2c_raw_mode(int port, int enable) * low). * * We attempt to unwedge the bus by doing: - * - If SCL is being held low, then a slave is clock extending. The only - * thing we can do is try to wait until the slave stops clock extending. - * - Otherwise, we will toggle the clock until the slave releases the SDA line. - * Once the SDA line is released, try to send a STOP bit. Rinse and repeat - * until either the bus is normal, or we run out of attempts. + * - If SCL is being held low, then a peripheral is clock extending. The only + * thing we can do is try to wait until the peripheral stops clock extending. + * - Otherwise, we will toggle the clock until the peripheral releases the SDA + * line. Once the SDA line is released, try to send a STOP bit. Rinse and + * repeat until either the bus is normal, or we run out of attempts. * - * Note this should work for most devices, but depending on the slaves i2c + * Note this should work for most devices, but depending on the i2c peripheral's * state machine, it may not be possible to unwedge the bus. */ int i2c_unwedge(int port) diff --git a/common/i2c_peripheral.c b/common/i2c_peripheral.c index 7e710b2ef4..20a4b4b0ae 100644 --- a/common/i2c_peripheral.c +++ b/common/i2c_peripheral.c @@ -3,7 +3,7 @@ * found in the LICENSE file. */ -/* I2C slave cross-platform code for Chrome EC */ +/* I2C peripheral cross-platform code for Chrome EC */ #include "host_command.h" #include "i2c.h" diff --git a/common/i2c_wedge.c b/common/i2c_wedge.c index f044b84dc3..0d930a7729 100644 --- a/common/i2c_wedge.c +++ b/common/i2c_wedge.c @@ -117,7 +117,7 @@ static int i2c_bang_in_bit(void) { int bit; - /* Let the slave drive data */ + /* Let the peripheral drive data */ i2c_raw_set_sda(I2C_PORT_HOST, 1); i2c_bang_delay(); @@ -134,7 +134,7 @@ static int i2c_bang_in_bit(void) return bit; } -/* Write a byte to I2C bus. Return 0 if ack by the slave. */ +/* Write a byte to I2C bus. Return 0 if ack by the peripheral. */ static int i2c_bang_out_byte(int send_start, int send_stop, unsigned char byte) { unsigned bit; diff --git a/common/i2cp_tpm.c b/common/i2cp_tpm.c index 48af3a22b3..4fbc27c899 100644 --- a/common/i2cp_tpm.c +++ b/common/i2cp_tpm.c @@ -19,9 +19,9 @@ * interrupts on the interrupt context. * * Each "write complete" interrupt is associated with some data receved from - * the master. If the package received from the master contains just one byte - * payload, the value of this byte is considered the address of the TPM2 - * register to reach, read or write. + * the controller. If the package received from the controller contains just + * one byte payload, the value of this byte is considered the address of the + * TPM2 register to reach, read or write. * * Real TPM register addresses can be two bytes in size (even within locality * zero), to keep the i2c protocol simple and efficient, the real TPM register @@ -34,7 +34,7 @@ * around to itself. Outside of the TPM fifo register, all other registers are * either 1 byte or 4 byte writes. * - * The master knows how many bytes to write into FIFO or to read from it by + * The controller knows how many bytes to write into FIFO or to read from it by * consulting the "burst size" field of the TPM status register. This happens * transparently for this layer. * @@ -48,13 +48,13 @@ * TODO (scollyer crosbug.com/p/56539): Should modify the register access code * so that the Host can access 1-4 bytes of a given register. * - * Master write accesses followed by data result in the register address + * Controller write accesses followed by data result in the register address * mapped, data converted, if necessary, and passed to the tpm register task. * - * Master write accesses requesting register reads result in the register + * Controller write accesses requesting register reads result in the register * address mappend and accessing the tpm task to retrieve the proper register - * data, converting it, if necessary, and passing it to the 12cs controller to - * make available for master read accesses. + * data, converting it, if necessary, and passing it to the i2cp driver to + * make available for controller read accesses. * * Again, both read and write accesses complete on the same interrupt context * they were invoked on. @@ -94,8 +94,8 @@ static void process_read_access(uint16_t reg_size, uint8_t reg_value[4]; /* - * The master wants to read the register, read the value and pass it - * to the controller. + * The controller wants to read the register, read the value and pass it + * to the interface. */ if (reg_size == 1 || reg_size == 4) { /* Always read regsize number of bytes */ diff --git a/docs/case_closed_debugging_cr50.md b/docs/case_closed_debugging_cr50.md index 5a71bc42ad..0a9c76bbbd 100644 --- a/docs/case_closed_debugging_cr50.md +++ b/docs/case_closed_debugging_cr50.md @@ -64,7 +64,7 @@ Capability | Default | Function `OpenNoLongPP` | `IfOpened` | Allow opening Cr50 without physical presence `BatteryBypassPP` | `Always` | Allow opening Cr50 without physical presence and developer mode if the battery is removed `UpdateNoTPMWipe` | `Always` | Allow updating Cr50 without wiping the TPM -`I2C` | `IfOpened` | Allow access to the I2C master (used for measuring power) +`I2C` | `IfOpened` | Allow access to the I2C controller (used for measuring power) `FlashRead` | `Always` | Allow dumping a hash of the AP or EC flash `OpenNoDevMode` | `IfOpened` | Allow opening Cr50 without developer mode `OpenFromUSB` | `IfOpened` | Allow opening Cr50 from USB diff --git a/docs/ec_terms.md b/docs/ec_terms.md index 8c3e4e2f48..3242302940 100644 --- a/docs/ec_terms.md +++ b/docs/ec_terms.md @@ -92,17 +92,17 @@ * **I/O Expander**{#ioexpander} - An [I2C](#i2c) slave device that provides additional GPIO signals (anywhere + An [I2C](#i2c) periph device that provides additional GPIO signals (anywhere from 8 - 32 signals). GPIOs behind an I/O expander are written and read - using I2C register accesses from the I2C master. + using I2C register accesses from the I2C controller. * **I2C - Inter-Integrated Circuit**{#i2c} A 2-wire synchronous communication bus, consisting of a clock signal and a - bidirectional data signal. An I2C bus typically contains one master device - and one more slave devices. The I2C standard defines supported clock speeds - of 100 KHz and 400 KHz. The full [I2C Specification] is available from NXP - (formerly Phillips). + bidirectional data signal. An I2C bus typically contains one controller + device and one more periph devices. The I2C standard defines supported + clock speeds of 100 KHz and 400 KHz. The full [I2C Specification] is + available from NXP (formerly Phillips). * **LED - Light Emitting Diode**{#led} diff --git a/include/config.h b/include/config.h index acb2cc340f..259d533008 100644 --- a/include/config.h +++ b/include/config.h @@ -2162,10 +2162,10 @@ */ #undef CONFIG_I2C_CONTROLLER -/* EC uses an I2C slave interface */ +/* EC uses an I2C peripheral interface */ #undef CONFIG_I2C_PERIPH -/* Defines I2C operation retry count when slave nack'd(EC_ERROR_BUSY) */ +/* Defines I2C operation retry count when peripheral nack'd(EC_ERROR_BUSY) */ #define CONFIG_I2C_NACK_RETRY_COUNT 0 /* * I2C SCL gating. @@ -2179,10 +2179,10 @@ #undef CONFIG_I2C_SCL_GATE_GPIO /* - * Some chip supports two owned slave address. The second slave address is used - * for other purpose such as board specific i2c commands. This option can be - * set if user of the second slave address requires larger host packet buffer - * size. + * Some chip supports two owned peripheral address. The second peripheral + * address is used for other purpose such as board specific i2c commands. This + * option can be set if user of the second peripheral address requires larger + * host packet buffer size. */ #define CONFIG_I2C_EXTRA_PACKET_SIZE 0 @@ -2203,7 +2203,7 @@ * i2c_read_string and i2c_write_block. Where * - write operation appends an error checking byte at end of transfer, and * - read operatoin verifies the correctness of error checking byte from the - * slave. + * peripheral. * Set I2C_FLAG on addr_flags parameter to use this feature. * * This option also enables error checking function on smart batteries. diff --git a/include/ec_commands.h b/include/ec_commands.h index 64b77d3e3b..2cdb4df192 100644 --- a/include/ec_commands.h +++ b/include/ec_commands.h @@ -4121,7 +4121,7 @@ struct ec_response_power_info_v1 { #define EC_I2C_STATUS_ERROR (EC_I2C_STATUS_NAK | EC_I2C_STATUS_TIMEOUT) struct ec_params_i2c_passthru_msg { - uint16_t addr_flags; /* I2C slave address and flags */ + uint16_t addr_flags; /* I2C periph address and flags */ uint16_t len; /* Number of bytes to read or write */ } __ec_align2; @@ -5843,7 +5843,7 @@ struct ec_response_battery_dynamic_info { } __ec_align2; /* - * Control charger chip. Used to control charger chip on the slave. + * Control charger chip. Used to control charger chip on the periph. */ #define EC_CMD_CHARGER_CONTROL 0x0602 diff --git a/include/i2c.h b/include/i2c.h index cf5729f91b..e61e0a6375 100644 --- a/include/i2c.h +++ b/include/i2c.h @@ -3,7 +3,7 @@ * found in the LICENSE file. */ -/* I2C interface for Chrome EC */ +/* I2C driver for Chrome EC */ #ifndef __CROS_EC_I2C_H #define __CROS_EC_I2C_H @@ -14,7 +14,7 @@ #include "stddef.h" /* - * I2C Slave Address encoding + * I2C Peripheral Address encoding * * EC will favor 7bit I2C/SPI address encoding. The variable/define * naming should follow the pattern, if it is just the 7 bit address @@ -29,7 +29,7 @@ * clear. I suggest, since this is a very small amount of usage, that * ending the variable as "addr_8bit" would make this clear. * - * NOTE: Slave addresses are always 16 bit values. The least significant + * NOTE: Peripheral addresses are always 16 bit values. The least significant * 10 bits are available as an address. More significant bits are * used here and in motion_sense to give specific meaning to the * address that is pertinent to its use. @@ -148,7 +148,7 @@ extern const int i2c_test_dev_used; * by locking the I2C port and performing an I2C_XFER_SINGLE transfer. * * @param port Port to access - * @param periph_addr Slave device address + * @param periph_addr peripheral device address * @param out Data to send * @param out_size Number of bytes to send * @param in Destination buffer for received data @@ -183,7 +183,7 @@ int i2c_xfer_unlocked(const int port, * i2c_xfer(). * * @param port Port to access - * @param periph_addr Slave device address + * @param periph_addr peripheral device address * @param out Data to send * @param out_size Number of bytes to send * @param in Destination buffer for received data @@ -287,80 +287,90 @@ void i2c_prepare_sysjump(void); void i2c_set_timeout(int port, uint32_t timeout); /** - * Read a 32-bit register from the slave at 7-bit slave address , at - * the specified 8-bit in the slave's address space. + * Read a 32-bit register from the peripheral at 7-bit peripheral address + * , at the specified 8-bit in the peripheral's address + * space. */ int i2c_read32(const int port, const uint16_t periph_addr_flags, int offset, int *data); /** - * Write a 32-bit register to the slave at 7-bit slave address , at - * the specified 8-bit in the slave's address space. + * Write a 32-bit register to the peripheral at 7-bit peripheral address + * , at the specified 8-bit in the peripheral's address + * space. */ int i2c_write32(const int port, const uint16_t periph_addr_flags, int offset, int data); /** - * Read a 16-bit register from the slave at 7-bit slave address , at - * the specified 8-bit in the slave's address space. + * Read a 16-bit register from the peripheral at 7-bit peripheral address + * , at the specified 8-bit in the peripheral's address + * space. */ int i2c_read16(const int port, const uint16_t periph_addr_flags, int offset, int *data); /** - * Write a 16-bit register to the slave at 7-bit slave address , at - * the specified 8-bit in the slave's address space. + * Write a 16-bit register to the peripheral at 7-bit peripheral address + * , at the specified 8-bit in the peripheral's address + * space. */ int i2c_write16(const int port, const uint16_t periph_addr_flags, int offset, int data); /** - * Read an 8-bit register from the slave at 7-bit slave address , at - * the specified 8-bit in the slave's address space. + * Read an 8-bit register from the peripheral at 7-bit peripheral address + * , at the specified 8-bit in the peripheral's address + * space. */ int i2c_read8(const int port, const uint16_t periph_addr_flags, int offset, int *data); /** - * Write an 8-bit register to the slave at 7-bit slave address , at - * the specified 8-bit in the slave's address space. + * Write an 8-bit register to the peripheral at 7-bit peripheral address + * , at the specified 8-bit in the peripheral's address + * space. */ int i2c_write8(const int port, const uint16_t periph_addr_flags, int offset, int data); /** - * Read one or two bytes data from the slave at 7-bit slave address - * * , at 16-bit in the slave's address space. + * Read one or two bytes data from the peripheral at 7-bit peripheral address + * , at 16-bit in the peripheral's address + * space. */ int i2c_read_offset16(const int port, const uint16_t periph_addr_flags, uint16_t offset, int *data, int len); /** - * Write one or two bytes data to the slave at 7-bit slave address - * , at 16-bit in the slave's address space. + * Write one or two bytes data to the peripheral at 7-bit peripheral address + * , at 16-bit in the peripheral's address + * space. */ int i2c_write_offset16(const int port, const uint16_t periph_addr_flags, uint16_t offset, int data, int len); /** - * Read bytes block data from the slave at 7-bit slave address - * * , at 16-bit in the slave's address space. + * Read bytes block data from the peripheral at 7-bit peripheral address + * , at 16-bit in the peripheral's address + * space. */ int i2c_read_offset16_block(const int port, const uint16_t periph_addr_flags, uint16_t offset, uint8_t *data, int len); /** - * Write bytes block data to the slave at 7-bit slave address - * , at 16-bit in the slave's address space. + * Write bytes block data to the peripheral at 7-bit peripheral address + * , at 16-bit in the peripheral's address + * space. */ int i2c_write_offset16_block(const int port, const uint16_t periph_addr_flags, @@ -396,18 +406,18 @@ int i2c_read_string(const int port, int offset, uint8_t *data, int len); /** - * Read a data block of 8-bit transfers from the slave at 7-bit slave - * address , at the specified 8-bit in the slave's address - * space. + * Read a data block of 8-bit transfers from the peripheral at 7-bit + * peripheral address , at the specified 8-bit in the + * peripheral's address space. */ int i2c_read_block(const int port, const uint16_t periph_addr_flags, int offset, uint8_t *data, int len); /** - * Write a data block of 8-bit transfers to the slave at 7-bit slave - * address , at the specified 8-bit in the slave's address - * space. + * Write a data block of 8-bit transfers to the peripheral at 7-bit + * peripheral address , at the specified 8-bit in the + * peripheral's address space. */ int i2c_write_block(const int port, const uint16_t periph_addr_flags, @@ -435,11 +445,12 @@ enum ec_status i2c_get_protocol_info(struct host_cmd_handler_args *args); /** * Callbacks processing received data and response * - * i2c_data_recived will be called when a slave finishes receiving data and - * i2c_set_response will be called when a slave is expected to send response. + * i2c_data_recived will be called when a peripheral finishes receiving data and + * i2c_set_response will be called when a peripheral is expected to send + * response. * * Using these, Chrome OS host command protocol should be separated from - * i2c slave drivers (e.g. i2c-stm32f0.c, i2c-stm32f3.c). + * i2c peripheral drivers (e.g. i2c-stm32f0.c, i2c-stm32f3.c). * * @param port: I2C port number * @param buf: Buffer containing received data on call and response on return @@ -487,7 +498,7 @@ int board_is_i2c_port_powered(int port); * CONFIG_I2C_XFER_BOARD_CALLBACK. * * @param port: I2C port number - * @param periph_addr: Slave device address + * @param periph_addr: peripheral device address * */ void i2c_start_xfer_notify(const int port, @@ -499,7 +510,7 @@ void i2c_start_xfer_notify(const int port, * CONFIG_I2C_XFER_BOARD_CALLBACK. * * @param port: I2C port number - * @param periph_addr: Slave device address + * @param periph_addr: peripheral device address * */ void i2c_end_xfer_notify(const int port, @@ -510,7 +521,7 @@ void i2c_end_xfer_notify(const int port, * funcionality of transactions. * * @param port: I2C port number - * @param periph_addr: slave device address + * @param periph_addr: peripheral device address * @param direction: 0 for write, * 1 for read * @param data: pointer to data read or written diff --git a/include/usb_i2c.h b/include/usb_i2c.h index 5719ee4333..d5ea414e3b 100644 --- a/include/usb_i2c.h +++ b/include/usb_i2c.h @@ -50,10 +50,10 @@ * Fields: * * - wc/port: 1 byte: 4 top bits are the 4 top bits of the 12 bit write - * counter, the 4 bottom bits are the port address, i2c interface + * counter, the 4 bottom bits are the port address, i2c driver * index. * - * - addr: slave address, 1 byte, i2c 7-bit bus address. + * - addr: peripheral address, 1 byte, i2c 7-bit bus address. * * - wc: write count, 1 byte, zero based count of bytes to write. If the * indicated write count cause the payload + header exceeds 64 bytes, @@ -216,7 +216,7 @@ int usb_i2c_board_is_enabled(void); /* * Special i2c address to use when the client is required to execute some - * command which does not directly involve the i2c master driver. + * command which does not directly involve the i2c controller driver. */ #define USB_I2C_CMD_ADDR_FLAGS 0x78 diff --git a/include/usb_mux.h b/include/usb_mux.h index c628cfc869..ad683e5920 100644 --- a/include/usb_mux.h +++ b/include/usb_mux.h @@ -184,7 +184,7 @@ struct usb_retimer { * no retimer driver is to be called. */ - /* I2C port and slave address */ + /* I2C port and peripheral address */ const int i2c_port; const uint16_t i2c_addr_flags; -- cgit v1.2.1