From: Dmitry Osipenko <digetx@gmail.com>
To: "Thierry Reding" <thierry.reding@gmail.com>,
"Jonathan Hunter" <jonathanh@nvidia.com>,
"Laxman Dewangan" <ldewangan@nvidia.com>,
"Wolfram Sang" <wsa@the-dreams.de>,
"Michał Mirosław" <mirq-linux@rere.qmqm.pl>,
"Andy Shevchenko" <andy.shevchenko@gmail.com>
Cc: linux-i2c@vger.kernel.org, linux-tegra@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: [PATCH v4 30/31] i2c: tegra: Clean up and improve comments
Date: Sat, 5 Sep 2020 23:41:50 +0300 [thread overview]
Message-ID: <20200905204151.25343-31-digetx@gmail.com> (raw)
In-Reply-To: <20200905204151.25343-1-digetx@gmail.com>
Make all comments to be consistent in regards to capitalization and
punctuation, correct spelling and grammar errors.
Signed-off-by: Dmitry Osipenko <digetx@gmail.com>
---
drivers/i2c/busses/i2c-tegra.c | 85 +++++++++++++++++-----------------
1 file changed, 43 insertions(+), 42 deletions(-)
diff --git a/drivers/i2c/busses/i2c-tegra.c b/drivers/i2c/busses/i2c-tegra.c
index dccad2429117..d389ea5813c3 100644
--- a/drivers/i2c/busses/i2c-tegra.c
+++ b/drivers/i2c/busses/i2c-tegra.c
@@ -148,11 +148,10 @@
#define I2C_PIO_MODE_PREFERRED_LEN 32
/*
- * msg_end_type: The bus control which need to be send at end of transfer.
- * @MSG_END_STOP: Send stop pulse at end of transfer.
- * @MSG_END_REPEAT_START: Send repeat start at end of transfer.
- * @MSG_END_CONTINUE: The following on message is coming and so do not send
- * stop or repeat start.
+ * msg_end_type: The bus control which needs to be sent at end of transfer.
+ * @MSG_END_STOP: Send stop pulse.
+ * @MSG_END_REPEAT_START: Send repeat-start.
+ * @MSG_END_CONTINUE: Don't send stop or repeat-start.
*/
enum msg_end_type {
MSG_END_STOP,
@@ -161,10 +160,10 @@ enum msg_end_type {
};
/**
- * struct tegra_i2c_hw_feature : Different HW support on Tegra
- * @has_continue_xfer_support: Continue transfer supports.
+ * struct tegra_i2c_hw_feature : per hardware generation features
+ * @has_continue_xfer_support: Continue-transfer supported.
* @has_per_pkt_xfer_complete_irq: Has enable/disable capability for transfer
- * complete interrupt per packet basis.
+ * completion interrupt on per packet basis.
* @has_config_load_reg: Has the config load register to load the new
* configuration.
* @clk_divisor_hs_mode: Clock divisor in HS mode.
@@ -184,7 +183,7 @@ enum msg_end_type {
* @has_mst_fifo: The I2C controller contains the new MST FIFO interface that
* provides additional features and allows for longer messages to
* be transferred in one go.
- * @quirks: i2c adapter quirks for limiting write/read transfer size and not
+ * @quirks: I2C adapter quirks for limiting write/read transfer size and not
* allowing 0 length transfers.
* @supports_bus_clear: Bus Clear support to recover from bus hang during
* SDA stuck low from device for some unknown reasons.
@@ -247,7 +246,7 @@ struct tegra_i2c_hw_feature {
* @msg_buf_remaining: size of unsent data in the message buffer
* @msg_read: identifies read transfers
* @bus_clk_rate: current I2C bus clock rate
- * @is_multimaster_mode: track if I2C controller is in multi-master mode
+ * @is_multimaster_mode: indicates that I2C controller is in multi-master mode
* @tx_dma_chan: DMA transmit channel
* @rx_dma_chan: DMA receive channel
* @dma_phys: handle to DMA resources
@@ -300,8 +299,8 @@ static u32 dvc_readl(struct tegra_i2c_dev *i2c_dev, unsigned long reg)
}
/*
- * i2c_writel and i2c_readl will offset the register if necessary to talk
- * to the I2C block inside the DVC block
+ * If necessary, i2c_writel() and i2c_readl() will offset the register
+ * in order to talk to the I2C block inside the DVC block.
*/
static unsigned long tegra_i2c_reg_addr(struct tegra_i2c_dev *i2c_dev,
unsigned long reg)
@@ -319,7 +318,7 @@ static void i2c_writel(struct tegra_i2c_dev *i2c_dev, u32 val,
{
writel_relaxed(val, i2c_dev->base + tegra_i2c_reg_addr(i2c_dev, reg));
- /* Read back register to make sure that register writes completed */
+ /* read back register to make sure that register writes completed */
if (reg != I2C_TX_FIFO)
readl_relaxed(i2c_dev->base + tegra_i2c_reg_addr(i2c_dev, reg));
}
@@ -475,7 +474,7 @@ static int tegra_i2c_init_dma(struct tegra_i2c_dev *i2c_dev)
* block. This block is identical to the rest of the I2C blocks, except that
* it only supports master mode, it has registers moved around, and it needs
* some extra init to get it into I2C mode. The register moves are handled
- * by i2c_readl and i2c_writel
+ * by i2c_readl() and i2c_writel().
*/
static void tegra_dvc_init(struct tegra_i2c_dev *i2c_dev)
{
@@ -625,7 +624,7 @@ static int tegra_i2c_init(struct tegra_i2c_dev *i2c_dev)
break;
}
- /* Make sure clock divisor programmed correctly */
+ /* make sure clock divisor programmed correctly */
clk_divisor = FIELD_PREP(I2C_CLK_DIVISOR_HSMODE,
i2c_dev->hw->clk_divisor_hs_mode) |
FIELD_PREP(I2C_CLK_DIVISOR_STD_FAST_MODE, non_hs_mode);
@@ -638,8 +637,8 @@ static int tegra_i2c_init(struct tegra_i2c_dev *i2c_dev)
}
/*
- * configure setup and hold times only when tsu_thd is non-zero.
- * otherwise, preserve the chip default values
+ * Configure setup and hold times only when tsu_thd is non-zero.
+ * Otherwise, preserve the chip default values.
*/
if (i2c_dev->hw->has_interface_timing_reg && tsu_thd)
i2c_writel(i2c_dev, tsu_thd, I2C_INTERFACE_TIMING_1);
@@ -683,7 +682,7 @@ static int tegra_i2c_disable_packet_mode(struct tegra_i2c_dev *i2c_dev)
/*
* NACK interrupt is generated before the I2C controller generates
- * the STOP condition on the bus. So wait for 2 clock periods
+ * the STOP condition on the bus. So wait for 2 clock periods
* before disabling the controller so that the STOP condition has
* been delivered properly.
*/
@@ -705,8 +704,8 @@ static int tegra_i2c_empty_rx_fifo(struct tegra_i2c_dev *i2c_dev)
u32 val;
/*
- * Catch overflow due to message fully sent
- * before the check for RX FIFO availability.
+ * Catch overflow due to message fully sent before the check for
+ * RX FIFO availability.
*/
if (WARN_ON_ONCE(!(i2c_dev->msg_buf_remaining)))
return -EINVAL;
@@ -731,8 +730,8 @@ static int tegra_i2c_empty_rx_fifo(struct tegra_i2c_dev *i2c_dev)
rx_fifo_avail -= words_to_transfer;
/*
- * If there is a partial word at the end of buf, handle it manually to
- * prevent overwriting past the end of buf
+ * If there is a partial word at the end of buffer, handle it
+ * manually to prevent overwriting past the end of buffer.
*/
if (rx_fifo_avail > 0 && buf_remaining > 0) {
/*
@@ -747,7 +746,7 @@ static int tegra_i2c_empty_rx_fifo(struct tegra_i2c_dev *i2c_dev)
rx_fifo_avail--;
}
- /* RX FIFO must be drained, otherwise it's an Overflow case. */
+ /* RX FIFO must be drained, otherwise it's an Overflow case */
if (WARN_ON_ONCE(rx_fifo_avail))
return -EINVAL;
@@ -773,16 +772,16 @@ static int tegra_i2c_fill_tx_fifo(struct tegra_i2c_dev *i2c_dev)
tx_fifo_avail = FIELD_GET(I2C_FIFO_STATUS_TX, val);
}
- /* Rounds down to not include partial word at the end of buf */
+ /* rounds down to not include partial word at the end of buffer */
words_to_transfer = buf_remaining / BYTES_PER_FIFO_WORD;
- /* It's very common to have < 4 bytes, so optimize that case. */
+ /* it's very common to have < 4 bytes, so optimize that case */
if (words_to_transfer) {
if (words_to_transfer > tx_fifo_avail)
words_to_transfer = tx_fifo_avail;
/*
- * Update state before writing to FIFO. If this casues us
+ * Update state before writing to FIFO. If this causes us
* to finish writing all bytes (AKA buf_remaining goes to 0) we
* have a potential for an interrupt (PACKET_XFER_COMPLETE is
* not maskable). We need to make sure that the isr sees
@@ -800,8 +799,8 @@ static int tegra_i2c_fill_tx_fifo(struct tegra_i2c_dev *i2c_dev)
}
/*
- * If there is a partial word at the end of buf, handle it manually to
- * prevent reading past the end of buf, which could cross a page
+ * If there is a partial word at the end of buffer, handle it manually
+ * to prevent reading past the end of buffer, which could cross a page
* boundary and fault.
*/
if (tx_fifo_avail > 0 && buf_remaining > 0) {
@@ -813,7 +812,7 @@ static int tegra_i2c_fill_tx_fifo(struct tegra_i2c_dev *i2c_dev)
memcpy(&val, buf, buf_remaining);
val = le32_to_cpu(val);
- /* Again update before writing to FIFO to make sure isr sees. */
+ /* again update before writing to FIFO to make sure ISR sees */
i2c_dev->msg_buf_remaining = 0;
i2c_dev->msg_buf = NULL;
@@ -850,7 +849,7 @@ static irqreturn_t tegra_i2c_isr(int irq, void *dev_id)
}
/*
- * I2C transfer is terminated during the bus clear so skip
+ * I2C transfer is terminated during the bus clear, so skip
* processing the other interrupts.
*/
if (i2c_dev->hw->supports_bus_clear && (status & I2C_INT_BUS_CLR_DONE))
@@ -886,7 +885,8 @@ static irqreturn_t tegra_i2c_isr(int irq, void *dev_id)
* During message read XFER_COMPLETE interrupt is triggered prior to
* DMA completion and during message write XFER_COMPLETE interrupt is
* triggered after DMA completion.
- * PACKETS_XFER_COMPLETE indicates completion of all bytes of transfer.
+ *
+ * PACKETS_XFER_COMPLETE indicates completion of all bytes of transfer,
* so forcing msg_buf_remaining to 0 in DMA mode.
*/
if (status & I2C_INT_PACKET_XFER_COMPLETE) {
@@ -904,7 +904,7 @@ static irqreturn_t tegra_i2c_isr(int irq, void *dev_id)
}
goto done;
err:
- /* An error occurred, mask all interrupts */
+ /* error occurred, mask all interrupts */
tegra_i2c_mask_irq(i2c_dev, I2C_INT_NO_ACK | I2C_INT_ARBITRATION_LOST |
I2C_INT_PACKET_XFER_COMPLETE | I2C_INT_TX_FIFO_DATA_REQ |
I2C_INT_RX_FIFO_DATA_REQ);
@@ -1335,6 +1335,7 @@ static int tegra_i2c_xfer(struct i2c_adapter *adap, struct i2c_msg msgs[],
enum msg_end_type end_type = MSG_END_STOP;
if (i < (num - 1)) {
+ /* check whether follow up message is coming */
if (msgs[i + 1].flags & I2C_M_NOSTART)
end_type = MSG_END_CONTINUE;
else
@@ -1565,7 +1566,6 @@ static const struct tegra_i2c_hw_feature tegra194_i2c_hw = {
.has_interface_timing_reg = true,
};
-/* Match table for of_platform binding */
static const struct of_device_id tegra_i2c_of_match[] = {
{ .compatible = "nvidia,tegra194-i2c", .data = &tegra194_i2c_hw, },
{ .compatible = "nvidia,tegra186-i2c", .data = &tegra186_i2c_hw, },
@@ -1589,7 +1589,7 @@ static void tegra_i2c_parse_dt(struct tegra_i2c_dev *i2c_dev)
ret = of_property_read_u32(np, "clock-frequency",
&i2c_dev->bus_clk_rate);
if (ret)
- i2c_dev->bus_clk_rate = I2C_MAX_STANDARD_MODE_FREQ; /* default clock rate */
+ i2c_dev->bus_clk_rate = I2C_MAX_STANDARD_MODE_FREQ;
multi_mode = of_property_read_bool(np, "multi-master");
i2c_dev->is_multimaster_mode = multi_mode;
@@ -1653,11 +1653,13 @@ static int tegra_i2c_init_runtime_pm_and_hardware(struct tegra_i2c_dev *i2c_dev)
int ret;
/*
- * VI I2C is in VE power domain which is not always on and not
- * an IRQ safe. So, IRQ safe device can't be attached to a non-IRQ
- * safe domain as it prevents powering off the PM domain.
- * Also, VI I2C device don't need to use runtime IRQ safe as it will
- * not be used for atomic transfers.
+ * VI I2C is in VE power domain which is not always ON and not
+ * IRQ-safe. Thus, IRQ-safe device shouldn't be attached to a
+ * non IRQ-safe domain because this prevents powering off the power
+ * domain.
+ *
+ * VI I2C device shouldn't be marked as IRQ-safe because VI I2C won't
+ * be used for atomic transfers.
*/
if (!i2c_dev->is_vi)
pm_runtime_irq_safe(i2c_dev->dev);
@@ -1806,9 +1808,8 @@ static int __maybe_unused tegra_i2c_runtime_resume(struct device *dev)
/*
* VI I2C device is attached to VE power domain which goes through
- * power ON/OFF during PM runtime resume/suspend. So, controller
- * should go through reset and need to re-initialize after power
- * domain ON.
+ * power ON/OFF during of runtime PM resume/suspend, meaning that
+ * controller needs to be re-initialized after power ON.
*/
if (i2c_dev->is_vi) {
ret = tegra_i2c_init(i2c_dev);
--
2.27.0
next prev parent reply other threads:[~2020-09-05 20:43 UTC|newest]
Thread overview: 48+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-05 20:41 [PATCH v4 00/31] Improvements for Tegra I2C driver Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 01/31] i2c: tegra: Make tegra_i2c_flush_fifos() usable in atomic transfer Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 02/31] i2c: tegra: Handle potential error of tegra_i2c_flush_fifos() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 03/31] i2c: tegra: Initialization div-clk rate unconditionally Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 04/31] i2c: tegra: Remove i2c_dev.clk_divisor_non_hs_mode member Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 05/31] i2c: tegra: Runtime PM always available on Tegra Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 06/31] i2c: tegra: Remove error message used for devm_request_irq() failure Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 07/31] i2c: tegra: Use reset_control_reset() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 08/31] i2c: tegra: Use devm_platform_get_and_ioremap_resource() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 09/31] i2c: tegra: Use platform_get_irq() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 10/31] i2c: tegra: Use clk-bulk helpers Dmitry Osipenko
2020-09-05 21:56 ` Michał Mirosław
2020-09-05 22:08 ` Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 11/31] i2c: tegra: Factor out runtime PM and hardware initialization Dmitry Osipenko
2020-09-05 22:10 ` Michał Mirosław
2020-09-05 22:24 ` Dmitry Osipenko
2020-09-05 22:51 ` Michał Mirosław
2020-09-05 23:10 ` Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 12/31] i2c: tegra: Move out all device-tree parsing into tegra_i2c_parse_dt() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 13/31] i2c: tegra: Clean up probe function Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 14/31] i2c: tegra: Remove likely/unlikely from the code Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 15/31] i2c: tegra: Remove bogus barrier() Dmitry Osipenko
2020-09-05 23:35 ` Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 16/31] i2c: tegra: Remove "dma" variable from tegra_i2c_xfer_msg() Dmitry Osipenko
2020-09-05 22:23 ` Michał Mirosław
2020-09-05 22:36 ` Dmitry Osipenko
2020-09-05 22:49 ` Michał Mirosław
2020-09-05 22:54 ` Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 17/31] i2c: tegra: Improve formatting of function variables Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 18/31] i2c: tegra: Improve coding style of tegra_i2c_wait_for_config_load() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 19/31] i2c: tegra: Rename wait/poll functions Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 20/31] i2c: tegra: Rename variable in tegra_i2c_issue_bus_clear() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 21/31] i2c: tegra: Factor out error recovery from tegra_i2c_xfer_msg() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 22/31] i2c: tegra: Factor out packet header setup " Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 23/31] i2c: tegra: Factor out register polling into separate function Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 24/31] i2c: tegra: Reorder location of functions in the code Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 25/31] i2c: tegra: Check errors for both positive and negative values Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 26/31] i2c: tegra: Consolidate error handling in tegra_i2c_xfer_msg() Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 27/31] i2c: tegra: Clean up printk messages Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 28/31] i2c: tegra: Clean up whitespaces, newlines and indentation Dmitry Osipenko
2020-09-05 20:41 ` [PATCH v4 29/31] i2c: tegra: Improve driver module description Dmitry Osipenko
2020-09-05 20:41 ` Dmitry Osipenko [this message]
2020-09-05 22:47 ` [PATCH v4 30/31] i2c: tegra: Clean up and improve comments Michał Mirosław
2020-09-05 22:53 ` Dmitry Osipenko
2020-09-05 22:58 ` Michał Mirosław
2020-09-05 20:41 ` [PATCH v4 31/31] i2c: tegra: Rename couple "ret" variables to "err" Dmitry Osipenko
2020-09-05 23:16 ` [PATCH v4 00/31] Improvements for Tegra I2C driver Michał Mirosław
2020-09-05 23:35 ` Dmitry Osipenko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200905204151.25343-31-digetx@gmail.com \
--to=digetx@gmail.com \
--cc=andy.shevchenko@gmail.com \
--cc=jonathanh@nvidia.com \
--cc=ldewangan@nvidia.com \
--cc=linux-i2c@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-tegra@vger.kernel.org \
--cc=mirq-linux@rere.qmqm.pl \
--cc=thierry.reding@gmail.com \
--cc=wsa@the-dreams.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).