[1/2] hwrng: Add support for ASPEED RNG
diff mbox series

Message ID 20200120150113.2565-1-linux@neuralgames.com
State New
Headers show
Series
  • [1/2] hwrng: Add support for ASPEED RNG
Related show

Commit Message

Oscar A Perez Jan. 20, 2020, 3:01 p.m. UTC
This minimal driver adds support for the Hardware Random Number Generator
that comes with the AST2400/AST2500/AST2600 SOCs from AspeedTech.

The HRNG on these SOCs uses Ring Oscillators working together to generate
a stream of random bits that can be read by the platform via a 32bit data
register.

Signed-off-by: Oscar A Perez <linux@neuralgames.com>
---
 .../devicetree/bindings/rng/aspeed-rng.yaml   | 90 +++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/rng/aspeed-rng.yaml

Comments

Joel Stanley Jan. 21, 2020, 1:53 a.m. UTC | #1
Hi,

On Mon, 20 Jan 2020 at 15:12, Oscar A Perez <linux@neuralgames.com> wrote:
>
> This minimal driver adds support for the Hardware Random Number Generator
> that comes with the AST2400/AST2500/AST2600 SOCs from AspeedTech.
>
> The HRNG on these SOCs uses Ring Oscillators working together to generate
> a stream of random bits that can be read by the platform via a 32bit data
> register.

Thanks for the patch.

We've been using the timeriomem-rng driver for the past few years on
aspeed hardware. You can see how that's set up by looking at
arch/arm/boot/dts/aspeed-g{4,5,6}.dtsi

I suggest we continue to use the generic driver.

Cheers,

Joel



>
> Signed-off-by: Oscar A Perez <linux@neuralgames.com>
> ---
>  .../devicetree/bindings/rng/aspeed-rng.yaml   | 90 +++++++++++++++++++
>  1 file changed, 90 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/rng/aspeed-rng.yaml
>
> diff --git a/Documentation/devicetree/bindings/rng/aspeed-rng.yaml b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
> new file mode 100644
> index 000000000000..06070ebe1c33
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
> @@ -0,0 +1,90 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/rng/aspeed-rng.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +
> +title: Bindings for Aspeed Hardware Random Number Generator
> +
> +
> +maintainers:
> +  - Oscar A Perez <linux@neuralgames.com>
> +
> +
> +description: |
> +  The HRNG on the AST2400/AST2500/AST2600 SOCs from AspeedTech  uses four Ring
> +  Oscillators working together to generate a stream of random bits that can be
> +  read by the platform via a 32bit data register every one microsecond.
> +  All the platform has to do is to provide to the driver the 'quality' entropy
> +  value, the  'mode' in which the combining  ROs will generate the  stream  of
> +  random bits and, the 'period' value that is used as a wait-time between reads
> +  from the 32bit data register.
> +
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - items:
> +          - enum:
> +              - aspeed,ast2400-rng
> +              - aspeed,ast2500-rng
> +              - aspeed,ast2600-rng
> +
> +
> +  reg:
> +    description:
> +      Base address and length of the register set of this block.
> +      Currently 'reg' must be eight bytes wide and 32-bit aligned.
> +
> +    maxItems: 1
> +
> +
> +  period:
> +    description:
> +      Wait time in microseconds to be used between reads.
> +      The RNG on these Aspeed SOCs generates 32bit of random data
> +      every one microsecond. Choose between 1 and n microseconds.
> +
> +    maxItems: 1
> +
> +
> +  mode:
> +    description:
> +      One of the eight modes in which the four internal ROs (Ring
> +      Oscillators)  are combined to generate a stream  of random
> +      bits. The default mode is seven which is the default method
> +      of combining RO random bits on these Aspeed SOCs.
> +
> +    maxItems: 1
> +
> +
> +  quality:
> +    description:
> +      Estimated number of bits of entropy per 1024 bits read from
> +      the RNG.  Note that the default quality is zero which stops
> +      this HRNG from automatically filling the kernel's entropy
> +      pool with data.
> +
> +    maxItems: 1
> +
> +
> +required:
> +  - compatible
> +  - reg
> +  - period
> +  - quality
> +
> +
> +examples:
> +  - |
> +    rng: hwrng@1e6e2074 {
> +         compatible = "aspeed,ast2500-rng";
> +         reg = <0x1e6e2074 0x8>;
> +         period = <4>;
> +         quality = <128>;
> +         mode = <0x7>;
> +    };
> +
> +
> +...
> --
> 2.17.1
>
Oscar A Perez Jan. 23, 2020, 1:25 a.m. UTC | #2
Hi Joel,

On 2020-01-20 19:53, Joel Stanley wrote:
> Hi,
> 
> On Mon, 20 Jan 2020 at 15:12, Oscar A Perez <linux@neuralgames.com> 
> wrote:
>> 
>> This minimal driver adds support for the Hardware Random Number 
>> Generator
>> that comes with the AST2400/AST2500/AST2600 SOCs from AspeedTech.
>> 
>> The HRNG on these SOCs uses Ring Oscillators working together to 
>> generate
>> a stream of random bits that can be read by the platform via a 32bit 
>> data
>> register.
> 
> Thanks for the patch.
> 
> We've been using the timeriomem-rng driver for the past few years on
> aspeed hardware. You can see how that's set up by looking at
> arch/arm/boot/dts/aspeed-g{4,5,6}.dtsi
> 
> I suggest we continue to use the generic driver.
> 
> Cheers,
> 
> Joel
> 
> 
> 

Thanks for reviewing the patch.

The RNG on Aspeed hardware allows eight different modes for combining 
its four internal Ring Oscillators that together generate a stream of 
random bits. However, the timeriomem-rng driver does not allow for mode 
selection so, the Aspeed RNG with this generic driver runs always on 
mode 'seven' (The default value for mode according to the AspeedTech 
datasheets).

I've performed some testings on this Aspeed RNG using the NIST 
Statistical Test Suite (NIST 800-22r1a) and, the results I got show that 
the default mode 'seven' isn't producing the best entropy and linear 
rank when compared against the other modes available on these SOCs.  On 
the other hand, the driver that I'm proposing here allows for mode 
selection which would help improve the random output for those looking 
to get the best out of this Aspeed RNG.

Thanks and regards,

Oscar A Perez

>> 
>> Signed-off-by: Oscar A Perez <linux@neuralgames.com>
>> ---
>>  .../devicetree/bindings/rng/aspeed-rng.yaml   | 90 
>> +++++++++++++++++++
>>  1 file changed, 90 insertions(+)
>>  create mode 100644 
>> Documentation/devicetree/bindings/rng/aspeed-rng.yaml
>> 
>> diff --git a/Documentation/devicetree/bindings/rng/aspeed-rng.yaml 
>> b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
>> new file mode 100644
>> index 000000000000..06070ebe1c33
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
>> @@ -0,0 +1,90 @@
>> +# SPDX-License-Identifier: GPL-2.0
>> +%YAML 1.2
>> +---
>> +$id: "http://devicetree.org/schemas/rng/aspeed-rng.yaml#"
>> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
>> +
>> +
>> +title: Bindings for Aspeed Hardware Random Number Generator
>> +
>> +
>> +maintainers:
>> +  - Oscar A Perez <linux@neuralgames.com>
>> +
>> +
>> +description: |
>> +  The HRNG on the AST2400/AST2500/AST2600 SOCs from AspeedTech  uses 
>> four Ring
>> +  Oscillators working together to generate a stream of random bits 
>> that can be
>> +  read by the platform via a 32bit data register every one 
>> microsecond.
>> +  All the platform has to do is to provide to the driver the 
>> 'quality' entropy
>> +  value, the  'mode' in which the combining  ROs will generate the  
>> stream  of
>> +  random bits and, the 'period' value that is used as a wait-time 
>> between reads
>> +  from the 32bit data register.
>> +
>> +
>> +properties:
>> +  compatible:
>> +    oneOf:
>> +      - items:
>> +          - enum:
>> +              - aspeed,ast2400-rng
>> +              - aspeed,ast2500-rng
>> +              - aspeed,ast2600-rng
>> +
>> +
>> +  reg:
>> +    description:
>> +      Base address and length of the register set of this block.
>> +      Currently 'reg' must be eight bytes wide and 32-bit aligned.
>> +
>> +    maxItems: 1
>> +
>> +
>> +  period:
>> +    description:
>> +      Wait time in microseconds to be used between reads.
>> +      The RNG on these Aspeed SOCs generates 32bit of random data
>> +      every one microsecond. Choose between 1 and n microseconds.
>> +
>> +    maxItems: 1
>> +
>> +
>> +  mode:
>> +    description:
>> +      One of the eight modes in which the four internal ROs (Ring
>> +      Oscillators)  are combined to generate a stream  of random
>> +      bits. The default mode is seven which is the default method
>> +      of combining RO random bits on these Aspeed SOCs.
>> +
>> +    maxItems: 1
>> +
>> +
>> +  quality:
>> +    description:
>> +      Estimated number of bits of entropy per 1024 bits read from
>> +      the RNG.  Note that the default quality is zero which stops
>> +      this HRNG from automatically filling the kernel's entropy
>> +      pool with data.
>> +
>> +    maxItems: 1
>> +
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - period
>> +  - quality
>> +
>> +
>> +examples:
>> +  - |
>> +    rng: hwrng@1e6e2074 {
>> +         compatible = "aspeed,ast2500-rng";
>> +         reg = <0x1e6e2074 0x8>;
>> +         period = <4>;
>> +         quality = <128>;
>> +         mode = <0x7>;
>> +    };
>> +
>> +
>> +...
>> --
>> 2.17.1
>>
Andrew Jeffery Jan. 23, 2020, 1:53 a.m. UTC | #3
> Thanks for reviewing the patch.
> 
> The RNG on Aspeed hardware allows eight different modes for combining 
> its four internal Ring Oscillators that together generate a stream of 
> random bits. However, the timeriomem-rng driver does not allow for mode 
> selection so, the Aspeed RNG with this generic driver runs always on 
> mode 'seven' (The default value for mode according to the AspeedTech 
> datasheets).
> 
> I've performed some testings on this Aspeed RNG using the NIST 
> Statistical Test Suite (NIST 800-22r1a) and, the results I got show that 
> the default mode 'seven' isn't producing the best entropy and linear 
> rank when compared against the other modes available on these SOCs.  On 
> the other hand, the driver that I'm proposing here allows for mode 
> selection which would help improve the random output for those looking 
> to get the best out of this Aspeed RNG.

Have you published the data and results of this study somewhere? This
really should be mentioned in the commit message as justification for
not using timeriomem-rng.

Andrew
Oscar A Perez Jan. 25, 2020, 1:10 a.m. UTC | #4
On 2020-01-22 19:53, Andrew Jeffery wrote:
>> Thanks for reviewing the patch.
>> 
>> The RNG on Aspeed hardware allows eight different modes for combining
>> its four internal Ring Oscillators that together generate a stream of
>> random bits. However, the timeriomem-rng driver does not allow for 
>> mode
>> selection so, the Aspeed RNG with this generic driver runs always on
>> mode 'seven' (The default value for mode according to the AspeedTech
>> datasheets).
>> 
>> I've performed some testings on this Aspeed RNG using the NIST
>> Statistical Test Suite (NIST 800-22r1a) and, the results I got show 
>> that
>> the default mode 'seven' isn't producing the best entropy and linear
>> rank when compared against the other modes available on these SOCs.  
>> On
>> the other hand, the driver that I'm proposing here allows for mode
>> selection which would help improve the random output for those looking
>> to get the best out of this Aspeed RNG.
> 
> Have you published the data and results of this study somewhere? This
> really should be mentioned in the commit message as justification for
> not using timeriomem-rng.
> 
> Andrew

Hi Andrew,

I have uploaded the results of my tests to my GitHub, along with all the 
binaries
containing the random bits that I collected from this Aspeed RNG using 
all 8 modes.
You can also find in this repository a patch for the hw_random core 
driver that
I've been using to collect this data. Here is the link:
   https://github.com/operezmuena/aspeed-rng-testing

You can see in the reports that when using large enough samples (40Mb in 
size)
this Aspeed RNG consistently fails the linear rank and entropy tests, no 
matter
what RNG mode is selected. However, modes 2, 4 and 6 produce better 
entropy than
the rest.
I'm now collecting rng data from 2 other AST2520 SOCs that I have in 
order to
compare results.

Regards,
Oscar
Andrew Jeffery Jan. 28, 2020, 12:53 a.m. UTC | #5
On Sat, 25 Jan 2020, at 11:40, linux@neuralgames.com wrote:
> On 2020-01-22 19:53, Andrew Jeffery wrote:
> >> Thanks for reviewing the patch.
> >> 
> >> The RNG on Aspeed hardware allows eight different modes for combining
> >> its four internal Ring Oscillators that together generate a stream of
> >> random bits. However, the timeriomem-rng driver does not allow for 
> >> mode
> >> selection so, the Aspeed RNG with this generic driver runs always on
> >> mode 'seven' (The default value for mode according to the AspeedTech
> >> datasheets).
> >> 
> >> I've performed some testings on this Aspeed RNG using the NIST
> >> Statistical Test Suite (NIST 800-22r1a) and, the results I got show 
> >> that
> >> the default mode 'seven' isn't producing the best entropy and linear
> >> rank when compared against the other modes available on these SOCs.  
> >> On
> >> the other hand, the driver that I'm proposing here allows for mode
> >> selection which would help improve the random output for those looking
> >> to get the best out of this Aspeed RNG.
> > 
> > Have you published the data and results of this study somewhere? This
> > really should be mentioned in the commit message as justification for
> > not using timeriomem-rng.
> > 
> > Andrew
> 
> Hi Andrew,
> 
> I have uploaded the results of my tests to my GitHub, along with all the 
> binaries
> containing the random bits that I collected from this Aspeed RNG using 
> all 8 modes.
> You can also find in this repository a patch for the hw_random core 
> driver that
> I've been using to collect this data. Here is the link:
>    https://github.com/operezmuena/aspeed-rng-testing
> 
> You can see in the reports that when using large enough samples (40Mb in 
> size)
> this Aspeed RNG consistently fails the linear rank and entropy tests, no 
> matter
> what RNG mode is selected. However, modes 2, 4 and 6 produce better 
> entropy than
> the rest.
> I'm now collecting rng data from 2 other AST2520 SOCs that I have in 
> order to
> compare results.

Nice work. Eyeballing the summaries, it seems mode 6 or mode 4 may be
improvements over 7? What's your analysis? It would be nice to have the
data from your other two SoCs to corroborate. Again, going forward, please
point to your measurements in your commit message.

Not that I've looked, but is it feasible to augment timeriomem-rng with
the ability to configure the RNG rather than implement a new driver? Why
didn't you go that route?

Andrew
Oscar A Perez Jan. 29, 2020, 12:26 a.m. UTC | #6
On 2020-01-27 18:53, Andrew Jeffery wrote:
> On Sat, 25 Jan 2020, at 11:40, linux@neuralgames.com wrote:
>> On 2020-01-22 19:53, Andrew Jeffery wrote:
>> >> Thanks for reviewing the patch.
>> >>
>> >> The RNG on Aspeed hardware allows eight different modes for combining
>> >> its four internal Ring Oscillators that together generate a stream of
>> >> random bits. However, the timeriomem-rng driver does not allow for
>> >> mode
>> >> selection so, the Aspeed RNG with this generic driver runs always on
>> >> mode 'seven' (The default value for mode according to the AspeedTech
>> >> datasheets).
>> >>
>> >> I've performed some testings on this Aspeed RNG using the NIST
>> >> Statistical Test Suite (NIST 800-22r1a) and, the results I got show
>> >> that
>> >> the default mode 'seven' isn't producing the best entropy and linear
>> >> rank when compared against the other modes available on these SOCs.
>> >> On
>> >> the other hand, the driver that I'm proposing here allows for mode
>> >> selection which would help improve the random output for those looking
>> >> to get the best out of this Aspeed RNG.
>> >
>> > Have you published the data and results of this study somewhere? This
>> > really should be mentioned in the commit message as justification for
>> > not using timeriomem-rng.
>> >
>> > Andrew
>> 
>> Hi Andrew,
>> 
>> I have uploaded the results of my tests to my GitHub, along with all 
>> the
>> binaries
>> containing the random bits that I collected from this Aspeed RNG using
>> all 8 modes.
>> You can also find in this repository a patch for the hw_random core
>> driver that
>> I've been using to collect this data. Here is the link:
>>    https://github.com/operezmuena/aspeed-rng-testing
>> 
>> You can see in the reports that when using large enough samples (40Mb 
>> in
>> size)
>> this Aspeed RNG consistently fails the linear rank and entropy tests, 
>> no
>> matter
>> what RNG mode is selected. However, modes 2, 4 and 6 produce better
>> entropy than
>> the rest.
>> I'm now collecting rng data from 2 other AST2520 SOCs that I have in
>> order to
>> compare results.
> 
> Nice work. Eyeballing the summaries, it seems mode 6 or mode 4 may be
> improvements over 7? What's your analysis? It would be nice to have the
> data from your other two SoCs to corroborate. Again, going forward, 
> please
> point to your measurements in your commit message.
> 

Hi Andrew,

I pushed to my GitHub repository the RNG dumps and NIST reports from the 
other 2 SOCs. The results are similar to the first SOC. None of the 
modes passed the NIST test for linear rank and approximate entropy. 
Also, these SOCs show that mode 6 produces better results than mode 7. 
However, having only a sample of 3 SOCs isn't going to give us 
statistical significance about which mode would be the best one on these 
SOCs but, it is hinting us that perhaps allowing the selection of other 
RNG modes would be a good feature to have in a driver.
Now, I must say that this is the first RO-based RNG that I have tested 
and I'm a bit concerned about the results I've been getting. I'm now 
wondering how RNGs from other SOC vendors would perform with this same 
test suite.

> Not that I've looked, but is it feasible to augment timeriomem-rng with
> the ability to configure the RNG rather than implement a new driver? 
> Why
> didn't you go that route?
> 
> Andrew

I decided to wrote the Aspeed-RNG driver because was under the 
impression that the community would prefer dedicated drivers over 
generic ones for these SOCs.  However, enhancing timeriomem-rng module 
is not hard at all.  As I matter of fact, I'm currently testing changes 
to timeriomem-rng and so far so good. If you would like to have a quick 
look to my changes, I just pushed patches to the same repo a couple of 
hours ago:  
https://github.com/operezmuena/aspeed-rng-testing/tree/master/patches

Thanks
Oscar
Andrew Jeffery Feb. 3, 2020, 4:07 a.m. UTC | #7
On Wed, 29 Jan 2020, at 10:56, linux@neuralgames.com wrote:
> On 2020-01-27 18:53, Andrew Jeffery wrote:
> > Not that I've looked, but is it feasible to augment timeriomem-rng with
> > the ability to configure the RNG rather than implement a new driver? 
> > Why
> > didn't you go that route?
> > 
> 
> I decided to wrote the Aspeed-RNG driver because was under the 
> impression that the community would prefer dedicated drivers over 
> generic ones for these SOCs. 

I think we should leverage existing work where we can. Lets not make
more extra for ourselves :)

> However, enhancing timeriomem-rng module 
> is not hard at all.  As I matter of fact, I'm currently testing changes 
> to timeriomem-rng and so far so good. If you would like to have a quick 
> look to my changes, I just pushed patches to the same repo a couple of 
> hours ago:  
> https://github.com/operezmuena/aspeed-rng-testing/tree/master/patches

I think this is a good approach  so long as we can create a clean interface
to the control MMIO(s) inside the driver, i.e. we shouldn't be baking any
Aspeed-specific information into generic sections of code. Usually this
means sticking a pointer to an ops struct in the data member of the
matching OF ID struct.

Input from the RNG maintainers will be helpful here.

Andrew
Andrew Jeffery Feb. 3, 2020, 4:09 a.m. UTC | #8
On Mon, 3 Feb 2020, at 14:37, Andrew Jeffery wrote:
> 
> I think we should leverage existing work where we can. Lets not make
> more extra for ourselves :)

Dammit, replaced the wrong word there - the irony:

"Lets not make _extra work_ for ourselves"
Rob Herring Feb. 3, 2020, 10:31 a.m. UTC | #9
On Mon, Jan 20, 2020 at 03:01:08PM +0000, Oscar A Perez wrote:
> This minimal driver adds support for the Hardware Random Number Generator
> that comes with the AST2400/AST2500/AST2600 SOCs from AspeedTech.

This patch is not a driver. 'dt-bindings: rng: ...' for the subject. 
(Plus, 2 patches with the same subject is never a good idea.)

> 
> The HRNG on these SOCs uses Ring Oscillators working together to generate
> a stream of random bits that can be read by the platform via a 32bit data
> register.
> 
> Signed-off-by: Oscar A Perez <linux@neuralgames.com>
> ---
>  .../devicetree/bindings/rng/aspeed-rng.yaml   | 90 +++++++++++++++++++
>  1 file changed, 90 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/rng/aspeed-rng.yaml
> 
> diff --git a/Documentation/devicetree/bindings/rng/aspeed-rng.yaml b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
> new file mode 100644
> index 000000000000..06070ebe1c33
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
> @@ -0,0 +1,90 @@
> +# SPDX-License-Identifier: GPL-2.0

Dual license new bindings:

(GPL-2.0-only OR BSD-2-Clause)

> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/rng/aspeed-rng.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +
> +title: Bindings for Aspeed Hardware Random Number Generator
> +
> +
> +maintainers:
> +  - Oscar A Perez <linux@neuralgames.com>
> +
> +
> +description: |
> +  The HRNG on the AST2400/AST2500/AST2600 SOCs from AspeedTech  uses four Ring
> +  Oscillators working together to generate a stream of random bits that can be
> +  read by the platform via a 32bit data register every one microsecond.
> +  All the platform has to do is to provide to the driver the 'quality' entropy
> +  value, the  'mode' in which the combining  ROs will generate the  stream  of
> +  random bits and, the 'period' value that is used as a wait-time between reads
> +  from the 32bit data register.
> +
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - items:
> +          - enum:
> +              - aspeed,ast2400-rng
> +              - aspeed,ast2500-rng
> +              - aspeed,ast2600-rng

Just:

compatible:
  enum: ...

> +
> +
> +  reg:
> +    description:
> +      Base address and length of the register set of this block.

Drop. That's *every* 'reg' property.

> +      Currently 'reg' must be eight bytes wide and 32-bit aligned.

Currently? Is that going to change? Are things going to break if the DT 
has a bigger size?

> +
> +    maxItems: 1
> +
> +
> +  period:

Needs a vendor prefix and unit suffix.

> +    description:
> +      Wait time in microseconds to be used between reads.
> +      The RNG on these Aspeed SOCs generates 32bit of random data
> +      every one microsecond. Choose between 1 and n microseconds.

Why would you pick something more than 1?

> +
> +    maxItems: 1
> +
> +
> +  mode:

Needs a vendor prefix and a type reference.

> +    description:
> +      One of the eight modes in which the four internal ROs (Ring
> +      Oscillators)  are combined to generate a stream  of random
> +      bits. The default mode is seven which is the default method
> +      of combining RO random bits on these Aspeed SOCs.
> +
> +    maxItems: 1
> +
> +
> +  quality:

Needs a vendor prefix and a type reference.

> +    description:
> +      Estimated number of bits of entropy per 1024 bits read from
> +      the RNG.  Note that the default quality is zero which stops
> +      this HRNG from automatically filling the kernel's entropy
> +      pool with data.
> +
> +    maxItems: 1
> +
> +
> +required:
> +  - compatible
> +  - reg
> +  - period
> +  - quality
> +
> +
> +examples:
> +  - |
> +    rng: hwrng@1e6e2074 {

rng@...

> +         compatible = "aspeed,ast2500-rng";
> +         reg = <0x1e6e2074 0x8>;
> +         period = <4>;
> +         quality = <128>;
> +         mode = <0x7>;
> +    };
> +
> +
> +...
> -- 
> 2.17.1
> 
> 
> _______________________________________________
> linux-arm-kernel mailing list
> linux-arm-kernel@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Patch
diff mbox series

diff --git a/Documentation/devicetree/bindings/rng/aspeed-rng.yaml b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
new file mode 100644
index 000000000000..06070ebe1c33
--- /dev/null
+++ b/Documentation/devicetree/bindings/rng/aspeed-rng.yaml
@@ -0,0 +1,90 @@ 
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: "http://devicetree.org/schemas/rng/aspeed-rng.yaml#"
+$schema: "http://devicetree.org/meta-schemas/core.yaml#"
+
+
+title: Bindings for Aspeed Hardware Random Number Generator
+
+
+maintainers:
+  - Oscar A Perez <linux@neuralgames.com>
+
+
+description: |
+  The HRNG on the AST2400/AST2500/AST2600 SOCs from AspeedTech  uses four Ring
+  Oscillators working together to generate a stream of random bits that can be
+  read by the platform via a 32bit data register every one microsecond.
+  All the platform has to do is to provide to the driver the 'quality' entropy
+  value, the  'mode' in which the combining  ROs will generate the  stream  of
+  random bits and, the 'period' value that is used as a wait-time between reads
+  from the 32bit data register.
+
+
+properties:
+  compatible:
+    oneOf:
+      - items:
+          - enum:
+              - aspeed,ast2400-rng
+              - aspeed,ast2500-rng
+              - aspeed,ast2600-rng
+
+
+  reg:
+    description:
+      Base address and length of the register set of this block.
+      Currently 'reg' must be eight bytes wide and 32-bit aligned.
+
+    maxItems: 1
+
+
+  period:
+    description:
+      Wait time in microseconds to be used between reads.
+      The RNG on these Aspeed SOCs generates 32bit of random data
+      every one microsecond. Choose between 1 and n microseconds.
+
+    maxItems: 1
+
+
+  mode:
+    description:
+      One of the eight modes in which the four internal ROs (Ring
+      Oscillators)  are combined to generate a stream  of random
+      bits. The default mode is seven which is the default method
+      of combining RO random bits on these Aspeed SOCs.
+
+    maxItems: 1
+
+
+  quality:
+    description:
+      Estimated number of bits of entropy per 1024 bits read from
+      the RNG.  Note that the default quality is zero which stops
+      this HRNG from automatically filling the kernel's entropy
+      pool with data.
+
+    maxItems: 1
+
+
+required:
+  - compatible
+  - reg
+  - period
+  - quality
+
+
+examples:
+  - |
+    rng: hwrng@1e6e2074 {
+         compatible = "aspeed,ast2500-rng";
+         reg = <0x1e6e2074 0x8>;
+         period = <4>;
+         quality = <128>;
+         mode = <0x7>;
+    };
+
+
+...