Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1562790 > unrolled thread

Re: [Patch v3 1/2] arm: kernel: Add SMC structure parameter

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [Patch v3 1/2] arm: kernel: Add SMC structure parameter Russell King - ARM Linux <linux@armlinux.org.uk> - 2017-01-19 15:50 +0100
    Re: [Patch v3 1/2] arm: kernel: Add SMC structure parameter Russell King - ARM Linux <linux@armlinux.org.uk> - 2017-01-19 16:50 +0100
      Re: [Patch v3 1/2] arm: kernel: Add SMC structure parameter Russell King - ARM Linux <linux@armlinux.org.uk> - 2017-01-19 17:40 +0100
      Re: [Patch v3 1/2] arm: kernel: Add SMC structure parameter Andy Gross <andy.gross@linaro.org> - 2017-01-19 17:50 +0100
    Re: [Patch v3 1/2] arm: kernel: Add SMC structure parameter Andy Gross <andy.gross@linaro.org> - 2017-01-19 17:20 +0100

#1562790 — Re: [Patch v3 1/2] arm: kernel: Add SMC structure parameter

On Wed, Jan 11, 2017 at 04:31:57PM -0600, Andy Gross wrote:
> diff --git a/include/linux/arm-smccc.h b/include/linux/arm-smccc.h
> index b5abfda..3e28d08 100644
> --- a/include/linux/arm-smccc.h
> +++ b/include/linux/arm-smccc.h
> @@ -72,19 +72,33 @@ struct arm_smccc_res {
>  };
>  
>  /**
> - * arm_smccc_smc() - make SMC calls
> + * struct arm_smccc_quirk - Contains quirk information
> + * id contains quirk identification
> + * state contains the quirk specific information

Given that this is a kerneldoc comment, it should really conform to the
kerneldoc requirements - see Documentation/kernel-doc-nano-HOWTO.txt:

/**
 * struct arm_smccc_quirk - Contains quirk information
 * @id: quirk identification
 * @state: the quirk specific information

> + */
> +struct arm_smccc_quirk {
> +	int	id;
> +	union {
> +		unsigned long a6;
> +	} state;
> +};
> +
> +/**
> + * __arm_smccc_smc() - make SMC calls
>   * @a0-a7: arguments passed in registers 0 to 7
>   * @res: result values from registers 0 to 3
> + * @quirk: optional quirk structure
>   *
>   * This function is used to make SMC calls following SMC Calling Convention.
>   * The content of the supplied param are copied to registers 0 to 7 prior
>   * to the SMC instruction. The return values are updated with the content
> - * from register 0 to 3 on return from the SMC instruction.
> + * from register 0 to 3 on return from the SMC instruction.  An optional
> + * quirk structure provides vendor specific behavior.

It's quite odd to have the result buried in the middle of arguments
passed to a function, but I guess for the sake of simplicity in the
assembly code that's what we need.

Also:

"@quirk points to an arm_smccc_quirk, or NULL when no quirks are required."

And... should this not be const?  Are we expecting anyone to modify
the quirk structure?

Thanks.

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line: currently at 9.6Mbps down 400kbps up
according to speedtest.net.

[toc] | [next] | [standalone]

#1562844

On Thu, Jan 19, 2017 at 09:45:06AM -0600, Andy Gross wrote:
> On Thu, Jan 19, 2017 at 02:40:08PM +0000, Russell King - ARM Linux wrote:
> > On Wed, Jan 11, 2017 at 04:31:57PM -0600, Andy Gross wrote:
> > > diff --git a/include/linux/arm-smccc.h b/include/linux/arm-smccc.h
> > > index b5abfda..3e28d08 100644
> > > --- a/include/linux/arm-smccc.h
> > > +++ b/include/linux/arm-smccc.h
> > > @@ -72,19 +72,33 @@ struct arm_smccc_res {
> > >  };
> > >  
> > >  /**
> > > - * arm_smccc_smc() - make SMC calls
> > > + * struct arm_smccc_quirk - Contains quirk information
> > > + * id contains quirk identification
> > > + * state contains the quirk specific information
> > 
> > Given that this is a kerneldoc comment, it should really conform to the
> > kerneldoc requirements - see Documentation/kernel-doc-nano-HOWTO.txt:
> > 
> > /**
> >  * struct arm_smccc_quirk - Contains quirk information
> >  * @id: quirk identification
> >  * @state: the quirk specific information
> 
> Ah, I flubbed that.  I'll fix this.
> 
> > 
> > > + */
> > > +struct arm_smccc_quirk {
> > > +	int	id;
> > > +	union {
> > > +		unsigned long a6;
> > > +	} state;
> > > +};
> > > +
> > > +/**
> > > + * __arm_smccc_smc() - make SMC calls
> > >   * @a0-a7: arguments passed in registers 0 to 7
> > >   * @res: result values from registers 0 to 3
> > > + * @quirk: optional quirk structure
> > >   *
> > >   * This function is used to make SMC calls following SMC Calling Convention.
> > >   * The content of the supplied param are copied to registers 0 to 7 prior
> > >   * to the SMC instruction. The return values are updated with the content
> > > - * from register 0 to 3 on return from the SMC instruction.
> > > + * from register 0 to 3 on return from the SMC instruction.  An optional
> > > + * quirk structure provides vendor specific behavior.
> > 
> > It's quite odd to have the result buried in the middle of arguments
> > passed to a function, but I guess for the sake of simplicity in the
> > assembly code that's what we need.
> > 
> > Also:
> > 
> > "@quirk points to an arm_smccc_quirk, or NULL when no quirks are required."
> 
> Fixed.
> 
> > 
> > And... should this not be const?  Are we expecting anyone to modify
> > the quirk structure?
> 
> No, unfortunately.  For qcom, we are stuffing the contents of a6 into the
> structure so the caller can get that information.

Please add that detail to the kerneldoc comments for the structure
concerning state.a6.  It's important that such information is not
lost in the depths of history.

Thanks.

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line: currently at 9.6Mbps down 400kbps up
according to speedtest.net.

[toc] | [prev] | [next] | [standalone]

#1562882

On Thu, Jan 19, 2017 at 10:16:58AM -0600, Andy Gross wrote:
> On Thu, Jan 19, 2017 at 03:48:18PM +0000, Russell King - ARM Linux wrote:
> > Please add that detail to the kerneldoc comments for the structure
> > concerning state.a6.  It's important that such information is not
> > lost in the depths of history.
> 
> For documentation, should I split out the union separately?  I don't see any
> good examples for documenting union members in unions defined inside structures.

Good question - I don't know.

 @state.a6: blah

would seem to be a logical and unambiguous way to document it, but I
don't know whether kerneldoc will accept that.

-- 
RMK's Patch system: http://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line: currently at 9.6Mbps down 400kbps up
according to speedtest.net.

[toc] | [prev] | [next] | [standalone]

#1562893

On Thu, Jan 19, 2017 at 03:48:18PM +0000, Russell King - ARM Linux wrote:
> On Thu, Jan 19, 2017 at 09:45:06AM -0600, Andy Gross wrote:
> > On Thu, Jan 19, 2017 at 02:40:08PM +0000, Russell King - ARM Linux wrote:
> > > On Wed, Jan 11, 2017 at 04:31:57PM -0600, Andy Gross wrote:
> > > > diff --git a/include/linux/arm-smccc.h b/include/linux/arm-smccc.h
> > > > index b5abfda..3e28d08 100644
> > > > --- a/include/linux/arm-smccc.h
> > > > +++ b/include/linux/arm-smccc.h
> > > > @@ -72,19 +72,33 @@ struct arm_smccc_res {
> > > >  };
> > > >  
> > > >  /**
> > > > - * arm_smccc_smc() - make SMC calls
> > > > + * struct arm_smccc_quirk - Contains quirk information
> > > > + * id contains quirk identification
> > > > + * state contains the quirk specific information
> > > 
> > > Given that this is a kerneldoc comment, it should really conform to the
> > > kerneldoc requirements - see Documentation/kernel-doc-nano-HOWTO.txt:
> > > 
> > > /**
> > >  * struct arm_smccc_quirk - Contains quirk information
> > >  * @id: quirk identification
> > >  * @state: the quirk specific information
> > 
> > Ah, I flubbed that.  I'll fix this.
> > 
> > > 
> > > > + */
> > > > +struct arm_smccc_quirk {
> > > > +	int	id;
> > > > +	union {
> > > > +		unsigned long a6;
> > > > +	} state;
> > > > +};
> > > > +
> > > > +/**
> > > > + * __arm_smccc_smc() - make SMC calls
> > > >   * @a0-a7: arguments passed in registers 0 to 7
> > > >   * @res: result values from registers 0 to 3
> > > > + * @quirk: optional quirk structure
> > > >   *
> > > >   * This function is used to make SMC calls following SMC Calling Convention.
> > > >   * The content of the supplied param are copied to registers 0 to 7 prior
> > > >   * to the SMC instruction. The return values are updated with the content
> > > > - * from register 0 to 3 on return from the SMC instruction.
> > > > + * from register 0 to 3 on return from the SMC instruction.  An optional
> > > > + * quirk structure provides vendor specific behavior.
> > > 
> > > It's quite odd to have the result buried in the middle of arguments
> > > passed to a function, but I guess for the sake of simplicity in the
> > > assembly code that's what we need.
> > > 
> > > Also:
> > > 
> > > "@quirk points to an arm_smccc_quirk, or NULL when no quirks are required."
> > 
> > Fixed.
> > 
> > > 
> > > And... should this not be const?  Are we expecting anyone to modify
> > > the quirk structure?
> > 
> > No, unfortunately.  For qcom, we are stuffing the contents of a6 into the
> > structure so the caller can get that information.
> 
> Please add that detail to the kerneldoc comments for the structure
> concerning state.a6.  It's important that such information is not
> lost in the depths of history.

For documentation, should I split out the union separately?  I don't see any
good examples for documenting union members in unions defined inside structures.

Regards,
Andy

[toc] | [prev] | [next] | [standalone]

#1562865

On Thu, Jan 19, 2017 at 02:40:08PM +0000, Russell King - ARM Linux wrote:
> On Wed, Jan 11, 2017 at 04:31:57PM -0600, Andy Gross wrote:
> > diff --git a/include/linux/arm-smccc.h b/include/linux/arm-smccc.h
> > index b5abfda..3e28d08 100644
> > --- a/include/linux/arm-smccc.h
> > +++ b/include/linux/arm-smccc.h
> > @@ -72,19 +72,33 @@ struct arm_smccc_res {
> >  };
> >  
> >  /**
> > - * arm_smccc_smc() - make SMC calls
> > + * struct arm_smccc_quirk - Contains quirk information
> > + * id contains quirk identification
> > + * state contains the quirk specific information
> 
> Given that this is a kerneldoc comment, it should really conform to the
> kerneldoc requirements - see Documentation/kernel-doc-nano-HOWTO.txt:
> 
> /**
>  * struct arm_smccc_quirk - Contains quirk information
>  * @id: quirk identification
>  * @state: the quirk specific information

Ah, I flubbed that.  I'll fix this.

> 
> > + */
> > +struct arm_smccc_quirk {
> > +	int	id;
> > +	union {
> > +		unsigned long a6;
> > +	} state;
> > +};
> > +
> > +/**
> > + * __arm_smccc_smc() - make SMC calls
> >   * @a0-a7: arguments passed in registers 0 to 7
> >   * @res: result values from registers 0 to 3
> > + * @quirk: optional quirk structure
> >   *
> >   * This function is used to make SMC calls following SMC Calling Convention.
> >   * The content of the supplied param are copied to registers 0 to 7 prior
> >   * to the SMC instruction. The return values are updated with the content
> > - * from register 0 to 3 on return from the SMC instruction.
> > + * from register 0 to 3 on return from the SMC instruction.  An optional
> > + * quirk structure provides vendor specific behavior.
> 
> It's quite odd to have the result buried in the middle of arguments
> passed to a function, but I guess for the sake of simplicity in the
> assembly code that's what we need.
> 
> Also:
> 
> "@quirk points to an arm_smccc_quirk, or NULL when no quirks are required."

Fixed.

> 
> And... should this not be const?  Are we expecting anyone to modify
> the quirk structure?

No, unfortunately.  For qcom, we are stuffing the contents of a6 into the
structure so the caller can get that information.

I'll resend with the documentation fixes.

Regards,

Andy

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web