linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Rodrigo Siqueira <rodrigosiqueiramelo@gmail.com>
To: Lars-Peter Clausen <lars@metafoo.de>,
	Michael Hennerich <Michael.Hennerich@analog.com>,
	Jonathan Cameron <jic23@kernel.org>,
	Hartmut Knaack <knaack.h@gmx.de>,
	Peter Meerwald-Stadler <pmeerw@pmeerw.net>,
	Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
	Graff Yang <graff.yang@gmail.com>
Cc: linux-iio@vger.kernel.org, devel@driverdev.osuosl.org,
	daniel.baluta@nxp.com, linux-kernel@vger.kernel.org
Subject: [PATCH 4/4] staging:iio:ad2s1210: Add comments/documentation
Date: Fri, 9 Mar 2018 20:46:40 -0300	[thread overview]
Message-ID: <813ae9b3a8d6d9b0e6d4d4b6dda7fe354375fc8d.1520638889.git.rodrigosiqueiramelo@gmail.com> (raw)
In-Reply-To: <cover.1520638889.git.rodrigosiqueiramelo@gmail.com>

The original code of AD2S1210 does not have documentation for structs
and register configurations; this difficult the code comprehension. This
patch adds structs documentation, briefly comments some register
settings and acronyms, and adds little explanations of some calculation
found in the code.

Signed-off-by: Rodrigo Siqueira <rodrigosiqueiramelo@gmail.com>
---
 drivers/staging/iio/resolver/ad2s1210.c | 32 ++++++++++++++++++++++++++++++++
 drivers/staging/iio/resolver/ad2s1210.h |  9 ++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/drivers/staging/iio/resolver/ad2s1210.c b/drivers/staging/iio/resolver/ad2s1210.c
index ac13b99bd9cb..9bb8fd782f5a 100644
--- a/drivers/staging/iio/resolver/ad2s1210.c
+++ b/drivers/staging/iio/resolver/ad2s1210.c
@@ -24,8 +24,10 @@
 
 #define DRV_NAME "ad2s1210"
 
+/* The default value of the control register on power-up */
 #define AD2S1210_DEF_CONTROL		0x7E
 
+/* Control Register Bit */
 #define AD2S1210_MSB_IS_HIGH		0x80
 #define AD2S1210_MSB_IS_LOW		0x7F
 #define AD2S1210_PHASE_LOCK_RANGE_44	0x20
@@ -39,14 +41,23 @@
 
 #define AD2S1210_REG_POSITION		0x80
 #define AD2S1210_REG_VELOCITY		0x82
+
+/* Loss of Signal (LOS) register address */
 #define AD2S1210_REG_LOS_THRD		0x88
+
+/* Degradation of Signal (DOS) register address */
 #define AD2S1210_REG_DOS_OVR_THRD	0x89
 #define AD2S1210_REG_DOS_MIS_THRD	0x8A
 #define AD2S1210_REG_DOS_RST_MAX_THRD	0x8B
 #define AD2S1210_REG_DOS_RST_MIN_THRD	0x8C
+
+/* Loss of Tracking (LOT) register address */
 #define AD2S1210_REG_LOT_HIGH_THRD	0x8D
 #define AD2S1210_REG_LOT_LOW_THRD	0x8E
+
+/* Excitation Frequency (EXCIT) register address */
 #define AD2S1210_REG_EXCIT_FREQ		0x91
+
 #define AD2S1210_REG_CONTROL		0x92
 #define AD2S1210_REG_SOFT_RESET		0xF0
 #define AD2S1210_REG_FAULT		0xFF
@@ -69,6 +80,20 @@ enum ad2s1210_mode {
 
 static const unsigned int ad2s1210_resolution_value[] = { 10, 12, 14, 16 };
 
+/**
+ * struct ad2s1210_state - device instance specific state.
+ * @pdata:		chip model specific constants, gpioin, etc
+ * @lock:		lock to ensure state is consistent
+ * @sdev:		the SPI device for this driver instance
+ * @fclkin:		frequency of clock input
+ * @fexcit:		excitation frequency
+ * @hysteresis:		cache of whether hysteresis is enabled
+ * @old_data:		cache of SPI communication after operation
+ * @resolution:		chip resolution could be 10/12/14/16-bit
+ * @mode:		indicates the operating mode
+ * @rx:			receive buffer
+ * @tx:			transmit buffer
+ */
 struct ad2s1210_state {
 	const struct ad2s1210_platform_data *pdata;
 	struct mutex lock;
@@ -82,6 +107,7 @@ struct ad2s1210_state {
 	u8 tx[2] ____cacheline_aligned;
 };
 
+/* Maps A0 and A1 inputs to the respective mode.  */
 static const int ad2s1210_mode_vals[4][2] = {
 	[MOD_POS] = { 0, 0 },
 	[MOD_VEL] = { 0, 1 },
@@ -137,6 +163,11 @@ int ad2s1210_update_frequency_control_word(struct ad2s1210_state *st)
 	int ret;
 	unsigned char fcw;
 
+	/*
+	 * The fcw stands for frequency control word, which can be obtained
+	 * from:
+	 * fcw = (Excitation Frequency * 2^15) / fclkin
+	 */
 	fcw = (unsigned char)(st->fexcit * (1 << 15) / st->fclkin);
 	if (fcw < AD2S1210_MIN_FCW || fcw > AD2S1210_MAX_FCW) {
 		dev_err(&st->sdev->dev, "ad2s1210: FCW out of range\n");
@@ -158,6 +189,7 @@ static unsigned char ad2s1210_read_resolution_pin(struct ad2s1210_state *st)
 	return ad2s1210_resolution_value[resolution];
 }
 
+/* Maps RES0 and RES1 inputs to the respective mode.  */
 static const int ad2s1210_res_pins[4][2] = {
 	{ 0, 0 }, {0, 1}, {1, 0}, {1, 1}
 };
diff --git a/drivers/staging/iio/resolver/ad2s1210.h b/drivers/staging/iio/resolver/ad2s1210.h
index e9b2147701fc..cbe21bca7638 100644
--- a/drivers/staging/iio/resolver/ad2s1210.h
+++ b/drivers/staging/iio/resolver/ad2s1210.h
@@ -1,5 +1,5 @@
 /*
- * ad2s1210.h plaform data for the ADI Resolver to Digital Converters:
+ * ad2s1210.h platform data for the ADI Resolver to Digital Converters:
  * AD2S1210
  *
  * Copyright (c) 2010-2010 Analog Devices Inc.
@@ -11,6 +11,13 @@
 #ifndef _AD2S1210_H
 #define _AD2S1210_H
 
+/**
+ * struct ad2s1210_platform_data - chip model
+ * @sample:	sample input used to clearing the fault register
+ * @a:		array of inputs (A0 and A1)
+ * @res:	array of resolution inputs (RES0 and RES1)
+ * @gpioin:	control the read operation
+ */
 struct ad2s1210_platform_data {
 	unsigned int		sample;
 	unsigned int		a[2];
-- 
2.16.2

_______________________________________________
devel mailing list
devel@linuxdriverproject.org
http://driverdev.linuxdriverproject.org/mailman/listinfo/driverdev-devel

  parent reply	other threads:[~2018-03-09 23:46 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-03-09 23:45 [PATCH 0/4] staging:iio:ad2s1210: Driver cleanup Rodrigo Siqueira
2018-03-09 23:45 ` [PATCH 1/4] staging:iio:ad2s1210: Remove end of line with '[' Rodrigo Siqueira
2018-03-10 16:41   ` Jonathan Cameron
2018-03-09 23:46 ` [PATCH 2/4] staging:iio:ad2s1210: Remove unused #define directive Rodrigo Siqueira
2018-03-10 16:45   ` Jonathan Cameron
2018-03-09 23:46 ` [PATCH 3/4] staging:iio:ad2s1210: Remove old_data from ad2s1210_state Rodrigo Siqueira
2018-03-10 17:21   ` Jonathan Cameron
2018-03-09 23:46 ` Rodrigo Siqueira [this message]
2018-03-10 17:52   ` [PATCH 4/4] staging:iio:ad2s1210: Add comments/documentation Jonathan Cameron
2018-03-12 12:25     ` Rodrigo Siqueira

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=813ae9b3a8d6d9b0e6d4d4b6dda7fe354375fc8d.1520638889.git.rodrigosiqueiramelo@gmail.com \
    --to=rodrigosiqueiramelo@gmail.com \
    --cc=Michael.Hennerich@analog.com \
    --cc=daniel.baluta@nxp.com \
    --cc=devel@driverdev.osuosl.org \
    --cc=graff.yang@gmail.com \
    --cc=gregkh@linuxfoundation.org \
    --cc=jic23@kernel.org \
    --cc=knaack.h@gmx.de \
    --cc=lars@metafoo.de \
    --cc=linux-iio@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=pmeerw@pmeerw.net \
    /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).