linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: <Tudor.Ambarus@microchip.com>
To: <miquel.raynal@bootlin.com>, <richard@nod.at>, <vigneshr@ti.com>,
	<boris.brezillon@collabora.com>
Cc: <linux-mtd@lists.infradead.org>, <linux-kernel@vger.kernel.org>,
	<Tudor.Ambarus@microchip.com>
Subject: [PATCH v3 20/32] mtd: spi-nor: Describe all the Reg Ops
Date: Tue, 29 Oct 2019 11:17:20 +0000	[thread overview]
Message-ID: <20191029111615.3706-21-tudor.ambarus@microchip.com> (raw)
In-Reply-To: <20191029111615.3706-1-tudor.ambarus@microchip.com>

From: Tudor Ambarus <tudor.ambarus@microchip.com>

Document all the Register Operations.

Signed-off-by: Tudor Ambarus <tudor.ambarus@microchip.com>
---
 drivers/mtd/spi-nor/spi-nor.c | 138 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 127 insertions(+), 11 deletions(-)

diff --git a/drivers/mtd/spi-nor/spi-nor.c b/drivers/mtd/spi-nor/spi-nor.c
index 823b9b06d34d..6102318cfd03 100644
--- a/drivers/mtd/spi-nor/spi-nor.c
+++ b/drivers/mtd/spi-nor/spi-nor.c
@@ -388,9 +388,11 @@ static ssize_t spi_nor_write_data(struct spi_nor *nor, loff_t to, size_t len,
 	return nor->controller_ops->write(nor, to, len, buf);
 }
 
-/*
- * Set write enable latch with Write Enable command.
- * Returns negative if error occurred.
+/**
+ * spi_nor_write_enable() - Set write enable latch with Write Enable command.
+ * @nor:	pointer to 'struct spi_nor'.
+ *
+ * Return: 0 on success, -errno otherwise.
  */
 static int spi_nor_write_enable(struct spi_nor *nor)
 {
@@ -415,8 +417,11 @@ static int spi_nor_write_enable(struct spi_nor *nor)
 	return ret;
 }
 
-/*
- * Send write disable instruction to the chip.
+/**
+ * spi_nor_write_disable() - Send Write Disable instruction to the chip.
+ * @nor:	pointer to 'struct spi_nor'.
+ *
+ * Return: 0 on success, -errno otherwise.
  */
 static int spi_nor_write_disable(struct spi_nor *nor)
 {
@@ -534,6 +539,14 @@ static int spi_nor_read_cr(struct spi_nor *nor, u8 *cr)
 	return ret;
 }
 
+/**
+ * macronix_set_4byte() - Set 4-byte address mode for Macronix flashes.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @enable:	true to enter the 4-byte address mode, false to exit the 4-byte
+ *		address mode.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int macronix_set_4byte(struct spi_nor *nor, bool enable)
 {
 	int ret;
@@ -562,6 +575,14 @@ static int macronix_set_4byte(struct spi_nor *nor, bool enable)
 	return ret;
 }
 
+/**
+ * st_micron_set_4byte() - Set 4-byte address mode for ST and Micron flashes.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @enable:	true to enter the 4-byte address mode, false to exit the 4-byte
+ *		address mode.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int st_micron_set_4byte(struct spi_nor *nor, bool enable)
 {
 	int ret;
@@ -577,6 +598,14 @@ static int st_micron_set_4byte(struct spi_nor *nor, bool enable)
 	return spi_nor_write_disable(nor);
 }
 
+/**
+ * spansion_set_4byte() - Set 4-byte address mode for Spansion flashes.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @enable:	true to enter the 4-byte address mode, false to exit the 4-byte
+ *		address mode.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spansion_set_4byte(struct spi_nor *nor, bool enable)
 {
 	int ret;
@@ -602,6 +631,13 @@ static int spansion_set_4byte(struct spi_nor *nor, bool enable)
 	return ret;
 }
 
+/**
+ * spi_nor_write_ear() - Write Extended Address Register.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @ear:	value to write to the Extended Address Register.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_write_ear(struct spi_nor *nor, u8 ear)
 {
 	int ret;
@@ -627,6 +663,14 @@ static int spi_nor_write_ear(struct spi_nor *nor, u8 ear)
 	return ret;
 }
 
+/**
+ * winbond_set_4byte() - Set 4-byte address mode for Winbond flashes.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @enable:	true to enter the 4-byte address mode, false to exit the 4-byte
+ *		address mode.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int winbond_set_4byte(struct spi_nor *nor, bool enable)
 {
 	int ret;
@@ -651,6 +695,14 @@ static int winbond_set_4byte(struct spi_nor *nor, bool enable)
 	return spi_nor_write_disable(nor);
 }
 
+/**
+ * spi_nor_xread_sr() - Read the Status Register on S3AN flashes.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @sr:		pointer to a DMA-able buffer where the value of the
+ *              Status Register will be written.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_xread_sr(struct spi_nor *nor, u8 *sr)
 {
 	int ret;
@@ -674,6 +726,13 @@ static int spi_nor_xread_sr(struct spi_nor *nor, u8 *sr)
 	return ret;
 }
 
+/**
+ * s3an_sr_ready() - Query the Status Register of the S3AN flash to see if the
+ * flash is ready for new commands.
+ * @nor:	pointer to 'struct spi_nor'.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int s3an_sr_ready(struct spi_nor *nor)
 {
 	int ret;
@@ -685,6 +744,10 @@ static int s3an_sr_ready(struct spi_nor *nor)
 	return !!(nor->bouncebuf[0] & XSR_RDY);
 }
 
+/**
+ * spi_nor_clear_sr() - Clear the Status Register.
+ * @nor:	pointer to 'struct spi_nor'.
+ */
 static void spi_nor_clear_sr(struct spi_nor *nor)
 {
 	int ret;
@@ -706,6 +769,13 @@ static void spi_nor_clear_sr(struct spi_nor *nor)
 		dev_err(nor->dev, "error %d clearing SR\n", ret);
 }
 
+/**
+ * spi_nor_sr_ready() - Query the Status Register to see if the flash is ready
+ * for new commands.
+ * @nor:	pointer to 'struct spi_nor'.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_sr_ready(struct spi_nor *nor)
 {
 	int ret = spi_nor_read_sr(nor, &nor->bouncebuf[0]);
@@ -727,6 +797,10 @@ static int spi_nor_sr_ready(struct spi_nor *nor)
 	return !(nor->bouncebuf[0] & SR_WIP);
 }
 
+/**
+ * spi_nor_clear_fsr() - Clear the Flag Status Register.
+ * @nor:	pointer to 'struct spi_nor'.
+ */
 static void spi_nor_clear_fsr(struct spi_nor *nor)
 {
 	int ret;
@@ -748,6 +822,13 @@ static void spi_nor_clear_fsr(struct spi_nor *nor)
 		dev_err(nor->dev, "error %d clearing FSR\n", ret);
 }
 
+/**
+ * spi_nor_fsr_ready() - Query the Flag Status Register to see if the flash is
+ * ready for new commands.
+ * @nor:	pointer to 'struct spi_nor'.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_fsr_ready(struct spi_nor *nor)
 {
 	int ret = spi_nor_read_fsr(nor, &nor->bouncebuf[0]);
@@ -772,6 +853,12 @@ static int spi_nor_fsr_ready(struct spi_nor *nor)
 	return nor->bouncebuf[0] & FSR_READY;
 }
 
+/**
+ * spi_nor_ready() - Query the flash to see if it is ready for new commands.
+ * @nor:	pointer to 'struct spi_nor'.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_ready(struct spi_nor *nor)
 {
 	int sr, fsr;
@@ -788,9 +875,13 @@ static int spi_nor_ready(struct spi_nor *nor)
 	return sr && fsr;
 }
 
-/*
- * Service routine to read status register until ready, or timeout occurs.
- * Returns non-zero if error.
+/**
+ * spi_nor_wait_till_ready_with_timeout() - Service routine to read the
+ * Status Register until ready, or timeout occurs.
+ * @nor:		pointer to "struct spi_nor".
+ * @timeout_jiffies:	jiffies to wait until timeout.
+ *
+ * Return: 0 on success, -errno otherwise.
  */
 static int spi_nor_wait_till_ready_with_timeout(struct spi_nor *nor,
 						unsigned long timeout_jiffies)
@@ -818,6 +909,13 @@ static int spi_nor_wait_till_ready_with_timeout(struct spi_nor *nor,
 	return -ETIMEDOUT;
 }
 
+/**
+ * spi_nor_wait_till_ready() - Wait for a predefined amount of time for the
+ * flash to be ready, or timeout occurs.
+ * @nor:	pointer to "struct spi_nor".
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_wait_till_ready(struct spi_nor *nor)
 {
 	return spi_nor_wait_till_ready_with_timeout(nor,
@@ -880,6 +978,14 @@ static int spi_nor_write_sr_and_check(struct spi_nor *nor, u8 status_new,
 	return ((nor->bouncebuf[0] & mask) != (status_new & mask)) ? -EIO : 0;
 }
 
+/**
+ * spi_nor_write_sr2() - Write the Status Register 2 using the
+ * SPINOR_OP_WRSR2 (3eh) command.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @sr2:	pointer to DMA-able buffer to write to the Status Register 2.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_write_sr2(struct spi_nor *nor, const u8 *sr2)
 {
 	int ret;
@@ -909,6 +1015,15 @@ static int spi_nor_write_sr2(struct spi_nor *nor, const u8 *sr2)
 	return spi_nor_wait_till_ready(nor);
 }
 
+/**
+ * spi_nor_read_sr2() - Read the Status Register 2 using the
+ * SPINOR_OP_RDSR2 (3fh) command.
+ * @nor:	pointer to 'struct spi_nor'.
+ * @sr2:	pointer to DMA-able buffer where the value of the
+ *		Status Register 2 will be written.
+ *
+ * Return: 0 on success, -errno otherwise.
+ */
 static int spi_nor_read_sr2(struct spi_nor *nor, u8 *sr2)
 {
 	int ret;
@@ -932,10 +1047,11 @@ static int spi_nor_read_sr2(struct spi_nor *nor, u8 *sr2)
 	return ret;
 }
 
-/*
- * Erase the whole flash memory
+/**
+ * spi_nor_erase_chip() - Erase the entire flash memory.
+ * @nor:	pointer to 'struct spi_nor'.
  *
- * Returns 0 if successful, non-zero otherwise.
+ * Return: 0 on success, -errno otherwise.
  */
 static int spi_nor_erase_chip(struct spi_nor *nor)
 {
-- 
2.9.5


  parent reply	other threads:[~2019-10-29 11:17 UTC|newest]

Thread overview: 67+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-10-29 11:16 [PATCH v3 00/32] mtd: spi-nor: Quad Enable and (un)lock methods Tudor.Ambarus
2019-10-29 11:16 ` [PATCH v3 01/32] mtd: spi-nor: Prepend spi_nor_ to all Reg Ops methods Tudor.Ambarus
2019-10-31 10:34   ` Boris Brezillon
2019-11-02 10:34   ` Tudor.Ambarus
2019-10-29 11:16 ` [PATCH v3 02/32] mtd: spi-nor: Drop duplicated new line Tudor.Ambarus
2019-10-31 10:34   ` Boris Brezillon
2019-11-02 10:34   ` Tudor.Ambarus
2019-10-29 11:16 ` [PATCH v3 03/32] mtd: spi-nor: Group all Reg Ops to avoid forward declarations Tudor.Ambarus
2019-10-31 10:35   ` Boris Brezillon
2019-11-02 10:35   ` Tudor.Ambarus
2019-10-29 11:16 ` [PATCH v3 04/32] mtd: spi-nor: Stop compare with negative in Reg Ops methods Tudor.Ambarus
2019-10-31 10:36   ` Boris Brezillon
2019-11-02 10:36   ` Tudor.Ambarus
2019-10-29 11:16 ` [PATCH v3 05/32] mtd: spi-nor: Drop explicit cast to int to already int value Tudor.Ambarus
2019-10-31 10:36   ` Boris Brezillon
2019-11-02 10:37   ` Tudor.Ambarus
2019-10-29 11:16 ` [PATCH v3 06/32] mtd: spi-nor: Use dev_err() instead of pr_err() Tudor.Ambarus
2019-10-31 10:43   ` Boris Brezillon
2019-11-02 10:38   ` Tudor.Ambarus
2019-10-29 11:16 ` [PATCH v3 07/32] mtd: spi-nor: Don't overwrite errno from Reg Ops Tudor.Ambarus
2019-10-31 10:48   ` Boris Brezillon
2019-11-02 10:39   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 08/32] mtd: spi-nor: Pointer parameter for SR in spi_nor_read_sr() Tudor.Ambarus
2019-10-31 10:51   ` Boris Brezillon
2019-11-02 10:42   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 09/32] mtd: spi-nor: Pointer parameter for FSR in spi_nor_read_fsr() Tudor.Ambarus
2019-10-31 10:53   ` Boris Brezillon
2019-11-02 10:44   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 10/32] mtd: spi-nor: Pointer parameter for CR in spi_nor_read_cr() Tudor.Ambarus
2019-10-31 10:58   ` Boris Brezillon
2019-10-31 14:26     ` Tudor.Ambarus
2019-11-02 10:45   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 11/32] mtd: spi-nor: Drop redundant error reports in Reg Ops callers Tudor.Ambarus
2019-10-31 10:59   ` Boris Brezillon
2019-11-02 10:46   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 12/32] mtd: spi-nor: Void return type for spi_nor_clear_sr/fsr() Tudor.Ambarus
2019-10-31 11:02   ` Boris Brezillon
2019-10-29 11:17 ` [PATCH v3 13/32] mtd: spi-nor: Print error messages inside Reg Ops methods Tudor.Ambarus
2019-10-31 11:05   ` Boris Brezillon
2019-10-31 14:18     ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 14/32] mtd: spi-nor: Fix retlen handling in sst_write() Tudor.Ambarus
2019-10-31 11:12   ` Boris Brezillon
2019-11-02 10:47   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 15/32] mtd: spi-nor: Check for errors after each Register Operation Tudor.Ambarus
2019-10-31  6:57   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 16/32] mtd: spi-nor: Rename label as it is no longer generic Tudor.Ambarus
2019-10-31 11:14   ` Boris Brezillon
2019-10-29 11:17 ` [PATCH v3 17/32] mtd: spi-nor: Move the WE and wait calls inside Write SR methods Tudor.Ambarus
2019-10-31 11:15   ` Boris Brezillon
2019-10-29 11:17 ` [PATCH v3 18/32] mtd: spi-nor: Constify data to write to the Status Register Tudor.Ambarus
2019-10-31 11:16   ` Boris Brezillon
2019-11-02 10:48   ` Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 19/32] mtd: spi-nor: Merge spi_nor_write_sr() and spi_nor_write_sr_cr() Tudor.Ambarus
2019-10-31 11:17   ` Boris Brezillon
2019-10-29 11:17 ` Tudor.Ambarus [this message]
2019-10-29 11:17 ` [PATCH v3 21/32] mtd: spi-nor: Drop spansion_quad_enable() Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 22/32] mtd: spi-nor: Fix errno on Quad Enable methods Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 23/32] mtd: spi-nor: Check all the bits written, not just the BP ones Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 24/32] mtd: spi-nor: Print error message when the read back test fails Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 25/32] mtd: spi-nor: Fix clearing of QE bit on lock()/unlock() Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 26/32] mtd: spi-nor: Extend the QE Read Back test to the entire SR byte Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 27/32] mtd: spi-nor: Extend the QE Read Back test to both SR1 and SR2 Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 28/32] mtd: spi-nor: Rename CR_QUAD_EN_SPAN to SR2_QUAD_EN_BIT1 Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 29/32] mtd: spi-nor: Merge spansion Quad Enable methods Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 30/32] mtd: spi-nor: Rename macronix_quad_enable to spi_nor_sr1_bit6_quad_enable Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 31/32] mtd: spi-nor: Prepend "spi_nor_" to "sr2_bit7_quad_enable" Tudor.Ambarus
2019-10-29 11:17 ` [PATCH v3 32/32] mtd: spi-nor: Rework the disabling of block write protection Tudor.Ambarus

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=20191029111615.3706-21-tudor.ambarus@microchip.com \
    --to=tudor.ambarus@microchip.com \
    --cc=boris.brezillon@collabora.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-mtd@lists.infradead.org \
    --cc=miquel.raynal@bootlin.com \
    --cc=richard@nod.at \
    --cc=vigneshr@ti.com \
    /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).