From patchwork Fri Mar 9 23:46:40 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Rodrigo Siqueira X-Patchwork-Id: 10272573 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 4997F60236 for ; Fri, 9 Mar 2018 23:46:48 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3B68F29FE0 for ; Fri, 9 Mar 2018 23:46:48 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 301F02A03C; Fri, 9 Mar 2018 23:46:48 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.8 required=2.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_HI, T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A920629FE0 for ; Fri, 9 Mar 2018 23:46:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751278AbeCIXqq (ORCPT ); Fri, 9 Mar 2018 18:46:46 -0500 Received: from mail-qk0-f193.google.com ([209.85.220.193]:35684 "EHLO mail-qk0-f193.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751225AbeCIXqp (ORCPT ); Fri, 9 Mar 2018 18:46:45 -0500 Received: by mail-qk0-f193.google.com with SMTP id s188so5509371qkb.2; Fri, 09 Mar 2018 15:46:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=/MO9GNZT+wHkf7acPV6H5n9pp6isQPZ4cMA4mOD69Sk=; b=nODgtEt6w67/QOO8ehktzD2+YfuCFY3/BnorQTTmHs+5IJ9uLXRx4KHa0tXTh5EgrB Ctg4T9nRhG49x4/6EYj5O+LZL+EZqeAQtA+t2fCSPbpJdw+jiAh9FFXKRezIKrgGWkLJ gs+2elCKnXY8f4FNMQzhsxa0IJxEMqj5OOX7LWinU4NHGoNeD2LxhgFXJn7leixe63xf +BcDwdGs3ej91YrbYemKDYgjzHgKoPeUMuVm+YWzLqasFLr91KmRxlij/MIsISFcM7cS bc4MwModTNlXt+c603vg+q4LarnCfsUHqw33W2JzFjtjIP8tvqDnsRSFqwtte5Pkv9FX NsSg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=/MO9GNZT+wHkf7acPV6H5n9pp6isQPZ4cMA4mOD69Sk=; b=V+Ebxj0lGAZWJPoZJPfSZO6Rs2s2J0TC68F/qlF4fgFDloXcOaVq7mr1897pIVz4a9 vhVq5MTUcWQpYOfY8SfDPZNsaulz+y6Sl7kI078ycN/+Z+/IUjxajzS1MYSYM3jejlyG XxYi80amI4dNN2JOkkVzQePMkVUEVuL4ZXhApNEdkiUOpUAxPeH4YzEIVPAoYEptjhcj m3prnZWHNAF0qt8gkuFPZ+216PyJPRoFbgAF9rXK4SC/sltZSx2HvrWX1dgFkkw+4hsQ FihIx7S/ifoRBRiufIojuTCGbQIeXEfYhg1S9t2rRSRw5Ou8pt48lBjLd+V6QSKhsfya /oPA== X-Gm-Message-State: AElRT7FkO+b/K8Zeaynf76Q1WhvkPsIR+E80cBZ3wViroD9aVrmckAr4 iAO3WeX+msExMk9J3dueVdU= X-Google-Smtp-Source: AG47ELvCf58bdmRP61K3lUZc1zKkJVpUiR6ARWAnPz5T1sG701Lyn8hnWGg/SImwY99+QQ2FAKqMgA== X-Received: by 10.55.173.18 with SMTP id f18mr407643qkm.112.1520639204897; Fri, 09 Mar 2018 15:46:44 -0800 (PST) Received: from smtp.gmail.com ([143.107.45.1]) by smtp.gmail.com with ESMTPSA id a8sm1400109qtc.23.2018.03.09.15.46.41 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Fri, 09 Mar 2018 15:46:44 -0800 (PST) Date: Fri, 9 Mar 2018 20:46:40 -0300 From: Rodrigo Siqueira To: Lars-Peter Clausen , Michael Hennerich , Jonathan Cameron , Hartmut Knaack , Peter Meerwald-Stadler , Greg Kroah-Hartman , Graff Yang Cc: daniel.baluta@nxp.com, linux-iio@vger.kernel.org, devel@driverdev.osuosl.org, linux-kernel@vger.kernel.org Subject: [PATCH 4/4] staging:iio:ad2s1210: Add comments/documentation Message-ID: <813ae9b3a8d6d9b0e6d4d4b6dda7fe354375fc8d.1520638889.git.rodrigosiqueiramelo@gmail.com> References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: User-Agent: NeoMutt/20171215 Sender: linux-iio-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-iio@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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 --- 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];