Date:   Sat, 4 Mar 2023 16:46:01 +0000
From:   Jonathan Cameron <jic23@kernel.org>
To:     Mehdi Djait <mehdi.djait.k@gmail.com>
Cc:     lars@metafoo.de, andriy.shevchenko@linux.intel.com,
        linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v2 1/2] iio: Improve the kernel-doc of iio_trigger_poll
Message-ID: <20230304164601.3888bbd4@jic23-huawei>
In-Reply-To: <bd84fc17e9d22eab998bf48720297f9a77689f45.1677761379.git.mehdi.djait.k@gmail.com>
References: <cover.1677761379.git.mehdi.djait.k@gmail.com>
        <bd84fc17e9d22eab998bf48720297f9a77689f45.1677761379.git.mehdi.djait.k@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

On Thu,  2 Mar 2023 14:04:35 +0100
Mehdi Djait <mehdi.djait.k@gmail.com> wrote:

> Move the kernel-doc of the function to industrialio-trigger.c
> Add a note on the context where the function is expected to be called.
> 
> Signed-off-by: Mehdi Djait <mehdi.djait.k@gmail.com>
> ---
> v2:
> - Changed the expected context of from interrupt to hard IRQ context
> 
>  drivers/iio/industrialio-trigger.c | 7 +++++++
>  include/linux/iio/trigger.h        | 6 ------
>  2 files changed, 7 insertions(+), 6 deletions(-)
> 
> diff --git a/drivers/iio/industrialio-trigger.c b/drivers/iio/industrialio-trigger.c
> index a2f3cc2f65ef..bb0a44df8740 100644
> --- a/drivers/iio/industrialio-trigger.c
> +++ b/drivers/iio/industrialio-trigger.c
> @@ -192,6 +192,13 @@ static void iio_trigger_notify_done_atomic(struct iio_trigger *trig)
>  		schedule_work(&trig->reenable_work);
>  }
>  
> +/**
> + * iio_trigger_poll() - Call the IRQ trigger handler of the consumers
> + * @trig: trigger which occurred
> + *
> + * This function needs to be called from a hard IRQ context.
I tweaked this to drop the line below and to say
This function should only be called from a hard IRQ context.

Fun subtlety of English that reminds me of the sign on the London underground
escalators that said "Guide dogs must be carried" thus apparently limiting
their use to people who could find a guide dog to carry.

Here we don't want to oblige all code to call the function :)

> + *
> + */
>  void iio_trigger_poll(struct iio_trigger *trig)
>  {
>  	int i;
> diff --git a/include/linux/iio/trigger.h b/include/linux/iio/trigger.h
> index f6360d9a492d..42da55dc3aa7 100644
> --- a/include/linux/iio/trigger.h
> +++ b/include/linux/iio/trigger.h
> @@ -151,12 +151,6 @@ void iio_trigger_unregister(struct iio_trigger *trig_info);
>   **/
>  int iio_trigger_set_immutable(struct iio_dev *indio_dev, struct iio_trigger *trig);
>  
> -/**
> - * iio_trigger_poll() - called on a trigger occurring
> - * @trig:	trigger which occurred
> - *
> - * Typically called in relevant hardware interrupt handler.
> - **/
>  void iio_trigger_poll(struct iio_trigger *trig);
>  void iio_trigger_poll_chained(struct iio_trigger *trig);
>