Re: [PATCH v4 21/28] net: wan: Add framer framework support

[Herve Codina <herve.codina@bootlin.com>]

Hi Simon,

On Sun, 20 Aug 2023 19:15:11 +0200
Simon Horman <horms@kernel.org> wrote:

> On Fri, Aug 18, 2023 at 06:39:15PM +0200, Christophe Leroy wrote:
> > From: Herve Codina <herve.codina@bootlin.com>
> > 
> > A framer is a component in charge of an E1/T1 line interface.
> > Connected usually to a TDM bus, it converts TDM frames to/from E1/T1
> > frames. It also provides information related to the E1/T1 line.
> > 
> > The framer framework provides a set of APIs for the framer drivers
> > (framer provider) to create/destroy a framer and APIs for the framer
> > users (framer consumer) to obtain a reference to the framer, and
> > use the framer.
> > 
> > This basic implementation provides a framer abstraction for:
> >  - power on/off the framer
> >  - get the framer status (line state)
> >  - be notified on framer status changes
> >  - get/set the framer configuration
> > 
> > Signed-off-by: Herve Codina <herve.codina@bootlin.com>
> > Reviewed-by: Christophe Leroy <christophe.leroy@csgroup.eu>
> > Signed-off-by: Christophe Leroy <christophe.leroy@csgroup.eu>  
> 
> Hi Christophe and Herve,
> 
> some minor feedback from my side.
> 
> ...
> 
> > diff --git a/drivers/net/wan/framer/framer-core.c b/drivers/net/wan/framer/framer-core.c  
> 
> ...
> 
> > +/**
> > + * framer_create() - create a new framer
> > + * @dev: device that is creating the new framer
> > + * @node: device node of the framer. default to dev->of_node.
> > + * @ops: function pointers for performing framer operations
> > + *
> > + * Called to create a framer using framer framework.
> > + */
> > +struct framer *framer_create(struct device *dev, struct device_node *node,
> > +			     const struct framer_ops *ops)
> > +{
> > +	int ret;
> > +	int id;
> > +	struct framer *framer;  
> 
> Please arrange local variable declarations for Networking code
> using reverse xmas tree order - longest line to shortest.

Yes, will be done in the next iteration.

> 
> https://github.com/ecree-solarflare/xmastree is helpful here.
> 
> ...
> 
> > diff --git a/include/linux/framer/framer-provider.h b/include/linux/framer/framer-provider.h  
> 
> ...
> 
> > +/**
> > + * struct framer_ops - set of function pointers for performing framer operations
> > + * @init: operation to be performed for initializing the framer
> > + * @exit: operation to be performed while exiting
> > + * @power_on: powering on the framer
> > + * @power_off: powering off the framer
> > + * @flags: OR-ed flags (FRAMER_FLAG_*) to ask for core functionality
> > + *          - @FRAMER_FLAG_POLL_STATUS:
> > + *            Ask the core to perfom a polling to get the framer status and  
> 
> nit: perfom -> perform

Will be fixed in the next iteration.

> 
>      checkpatch.pl --codespell is your friend here
> 
> > + *            notify consumers on change.
> > + *            The framer should call @framer_notify_status_change() when it
> > + *            detects a status change. This is usally done using interrutps.  
> 
> nit: usally -> usually
>      interrutps -> interrupts

Will be fixed in the next iteration.

> 
> ...
> 
> > diff --git a/include/linux/framer/framer.h b/include/linux/framer/framer.h
> > new file mode 100644
> > index 000000000000..0bee7135142f
> > --- /dev/null
> > +++ b/include/linux/framer/framer.h
> > @@ -0,0 +1,199 @@
> > +/* SPDX-License-Identifier: GPL-2.0-or-later */
> > +/*
> > + * Generic framer header file
> > + *
> > + * Copyright 2023 CS GROUP France
> > + *
> > + * Author: Herve Codina <herve.codina@bootlin.com>
> > + */
> > +
> > +#ifndef __DRIVERS_FRAMER_H
> > +#define __DRIVERS_FRAMER_H
> > +
> > +#include <linux/err.h>
> > +#include <linux/mutex.h>
> > +#include <linux/notifier.h>
> > +#include <linux/of.h>
> > +#include <linux/device.h>
> > +#include <linux/workqueue.h>
> > +
> > +/**
> > + * enum framer_iface - Framer interface  
> 
> As this is a kernel-doc, please include documentation for
> the defined constants: FRAMER_IFACE_E1 and FRAMER_IFACE_T1.
> 
> As flagged by: ./scripts/kernel-doc -none

Will be done in the next iteration.

> 
> > + */
> > +enum framer_iface {
> > +	FRAMER_IFACE_E1,      /* E1 interface */
> > +	FRAMER_IFACE_T1,      /* T1 interface */
> > +};
> > +
> > +/**
> > + * enum framer_clock_mode - Framer clock mode  
> 
> Likewise here too.
> 
> Also, nit: framer_clock_mode -> framer_clock_type
> 

Will be updated (doc and change to framer_clock_type) in the next iteration.

> > + */
> > +enum framer_clock_type {
> > +	FRAMER_CLOCK_EXT, /* External clock */
> > +	FRAMER_CLOCK_INT, /* Internal clock */
> > +};
> > +
> > +/**
> > + * struct framer_configuration - Framer configuration  
> 
> nit: framer_configuration -> framer_config

Will be fixed in the next iteration.

> 
> > + * @line_iface: Framer line interface
> > + * @clock_mode: Framer clock type
> > + * @clock_rate: Framer clock rate
> > + */
> > +struct framer_config {
> > +	enum framer_iface iface;
> > +	enum framer_clock_type clock_type;
> > +	unsigned long line_clock_rate;
> > +};
> > +
> > +/**
> > + * struct framer_status - Framer status
> > + * @link_is_on: Framer link state. true, the link is on, false, the link is off.
> > + */
> > +struct framer_status {
> > +	bool link_is_on;
> > +};
> > +
> > +/**
> > + * framer_event - event available for notification  
> 
> nit: framer_event -> enum framer_event

Will be fixed in the next iteration.

> 
> A~d please document FRAMER_EVENT_STATUS in the kernel doc too.

Will be documented in the next iteration.

> 
> > + */
> > +enum framer_event {
> > +	FRAMER_EVENT_STATUS,	/* Event notified on framer_status changes */
> > +};  
> 
> ...

Thanks for the review,
Best regards,
Hervé