| Message ID | 20200301215029.15196-19-nieklinnenbank@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | Add Allwinner H3 SoC and Orange Pi PC Machine | expand |
Niek Linnenbank <nieklinnenbank@gmail.com> writes: > The Xunlong Orange Pi PC machine is a functional ARM machine > based on the Allwinner H3 System-on-Chip. It supports mainline > Linux, U-Boot, NetBSD and is covered by acceptance tests. > > This commit adds a documentation text file with a description > of the machine and instructions for the user. This is great, thanks for taking the time to include documentation. > > Signed-off-by: Niek Linnenbank <nieklinnenbank@gmail.com> > --- > docs/orangepi.rst | 226 > ++++++++++++++++++++++++++++++++++++++++++++++ I suspect there is a better place to put this is than the top level. I wonder if it should be docs/specs? > MAINTAINERS | 1 + > 2 files changed, 227 insertions(+) > create mode 100644 docs/orangepi.rst > > diff --git a/docs/orangepi.rst b/docs/orangepi.rst > new file mode 100644 > index 0000000000..a9b46f553c > --- /dev/null > +++ b/docs/orangepi.rst > @@ -0,0 +1,226 @@ > +========================= > +Orange Pi PC Machine Type > +========================= > + > +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip > +based embedded computer with mainline support in both U-Boot > +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz, > +1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and > +various other I/O. When Peter's document PR goes in later this week there will also be a: docs/system/target-arm.rst which would benefit from a section for the Orange Pi in it. > + > +Supported devices > +----------------- > + > +The Orange Pi PC machine supports the following devices: > + > + * SMP (Quad Core Cortex A7) > + * Generic Interrupt Controller configuration > + * SRAM mappings > + * SDRAM controller > + * Real Time Clock > + * Timer device (re-used from Allwinner A10) > + * UART > + * SD/MMC storage controller > + * EMAC ethernet Do we ever exercise the ethernet in the acceptance tests? I see we have some that boots a full OS but boot console only seems to touch the serial console. <snip>
Hello Alex, On Wed, Mar 4, 2020 at 11:35 AM Alex Bennée <alex.bennee@linaro.org> wrote: > > Niek Linnenbank <nieklinnenbank@gmail.com> writes: > > > The Xunlong Orange Pi PC machine is a functional ARM machine > > based on the Allwinner H3 System-on-Chip. It supports mainline > > Linux, U-Boot, NetBSD and is covered by acceptance tests. > > > > This commit adds a documentation text file with a description > > of the machine and instructions for the user. > > This is great, thanks for taking the time to include documentation. > Sure, I'm happy to contribute it. I tried to include most relevant information in there for developers and potential users of the machine. If something is missing just let me know and I'll make an update for it. > > > > > Signed-off-by: Niek Linnenbank <nieklinnenbank@gmail.com> > > --- > > docs/orangepi.rst | 226 > > ++++++++++++++++++++++++++++++++++++++++++++++ > > I suspect there is a better place to put this is than the top level. I > wonder if it should be docs/specs? > Yeah I'm fine to move it to a different subdirectory if needed. Right now its placed in docs, as it seems that documents for machines are also placed there, for example docs/microvm.rst > > > MAINTAINERS | 1 + > > 2 files changed, 227 insertions(+) > > create mode 100644 docs/orangepi.rst > > > > diff --git a/docs/orangepi.rst b/docs/orangepi.rst > > new file mode 100644 > > index 0000000000..a9b46f553c > > --- /dev/null > > +++ b/docs/orangepi.rst > > @@ -0,0 +1,226 @@ > > +========================= > > +Orange Pi PC Machine Type > > +========================= > > + > > +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip > > +based embedded computer with mainline support in both U-Boot > > +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz, > > +1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and > > +various other I/O. > > When Peter's document PR goes in later this week there will also be a: > > docs/system/target-arm.rst > > which would benefit from a section for the Orange Pi in it. > Nice, I'll have a look at it when it gets merged and add a section for Orange Pi. I'll try to include that in the next version of this series. > > > + > > +Supported devices > > +----------------- > > + > > +The Orange Pi PC machine supports the following devices: > > + > > + * SMP (Quad Core Cortex A7) > > + * Generic Interrupt Controller configuration > > + * SRAM mappings > > + * SDRAM controller > > + * Real Time Clock > > + * Timer device (re-used from Allwinner A10) > > + * UART > > + * SD/MMC storage controller > > + * EMAC ethernet > > Do we ever exercise the ethernet in the acceptance tests? I see we have > some that boots a full OS but boot console only seems to touch the > serial console. > Good point. Currently in the acceptance tests U-Boot and Linux detect the ethernet device, but there are no explicit checks for that in the acceptance tests nor any actual packet transmission. I'll try to extend the current tests in the next version of this series to include some basic checks for the ethernet device, perhaps with DHCP or a ping. I'm open to suggestions for the preferred way to do this. Regards, Niek > > <snip> > > -- > Alex Bennée >
On Wed, 4 Mar 2020 at 20:55, Niek Linnenbank <nieklinnenbank@gmail.com> wrote: > > Hello Alex, > > On Wed, Mar 4, 2020 at 11:35 AM Alex Bennée <alex.bennee@linaro.org> wrote: >> >> >> Niek Linnenbank <nieklinnenbank@gmail.com> writes: >> > --- >> > docs/orangepi.rst | 226 >> > ++++++++++++++++++++++++++++++++++++++++++++++ >> >> I suspect there is a better place to put this is than the top level. I >> wonder if it should be docs/specs? > > > Yeah I'm fine to move it to a different subdirectory if needed. Right now its placed in docs, > as it seems that documents for machines are also placed there, for example docs/microvm.rst The only things in the top level docs/ are a handful of legacy-ish files that went there because we didn't yet have a better place to put them. We should avoid increasing the number of orphan files in the top level (and indeed should try to move the existing orphans elsewhere). >> When Peter's document PR goes in later this week there will also be a: >> >> docs/system/target-arm.rst >> >> which would benefit from a section for the Orange Pi in it. Yes, this is now the right place to put arm board-specific documentation (the rearranging and conversion from texinfo is now in master). I should move microvm.rst's contents there I guess. thanks -- PMM
Hi Alex, On Wed, Mar 4, 2020 at 9:55 PM Niek Linnenbank <nieklinnenbank@gmail.com> wrote: > Hello Alex, > > On Wed, Mar 4, 2020 at 11:35 AM Alex Bennée <alex.bennee@linaro.org> > wrote: > >> >> Niek Linnenbank <nieklinnenbank@gmail.com> writes: >> >> > The Xunlong Orange Pi PC machine is a functional ARM machine >> > based on the Allwinner H3 System-on-Chip. It supports mainline >> > Linux, U-Boot, NetBSD and is covered by acceptance tests. >> > >> > This commit adds a documentation text file with a description >> > of the machine and instructions for the user. >> >> This is great, thanks for taking the time to include documentation. >> > > Sure, I'm happy to contribute it. I tried to include most relevant > information > in there for developers and potential users of the machine. If something > is missing > just let me know and I'll make an update for it. > > >> >> > >> > Signed-off-by: Niek Linnenbank <nieklinnenbank@gmail.com> >> > --- >> > docs/orangepi.rst | 226 >> > ++++++++++++++++++++++++++++++++++++++++++++++ >> >> I suspect there is a better place to put this is than the top level. I >> wonder if it should be docs/specs? >> > > Yeah I'm fine to move it to a different subdirectory if needed. Right now > its placed in docs, > as it seems that documents for machines are also placed there, for example > docs/microvm.rst > > >> >> > MAINTAINERS | 1 + >> > 2 files changed, 227 insertions(+) >> > create mode 100644 docs/orangepi.rst >> > >> > diff --git a/docs/orangepi.rst b/docs/orangepi.rst >> > new file mode 100644 >> > index 0000000000..a9b46f553c >> > --- /dev/null >> > +++ b/docs/orangepi.rst >> > @@ -0,0 +1,226 @@ >> > +========================= >> > +Orange Pi PC Machine Type >> > +========================= >> > + >> > +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip >> > +based embedded computer with mainline support in both U-Boot >> > +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz, >> > +1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and >> > +various other I/O. >> >> When Peter's document PR goes in later this week there will also be a: >> >> docs/system/target-arm.rst >> >> which would benefit from a section for the Orange Pi in it. >> > > Nice, I'll have a look at it when it gets merged and add a section for > Orange Pi. > I'll try to include that in the next version of this series. > > >> >> > + >> > +Supported devices >> > +----------------- >> > + >> > +The Orange Pi PC machine supports the following devices: >> > + >> > + * SMP (Quad Core Cortex A7) >> > + * Generic Interrupt Controller configuration >> > + * SRAM mappings >> > + * SDRAM controller >> > + * Real Time Clock >> > + * Timer device (re-used from Allwinner A10) >> > + * UART >> > + * SD/MMC storage controller >> > + * EMAC ethernet >> >> Do we ever exercise the ethernet in the acceptance tests? I see we have >> some that boots a full OS but boot console only seems to touch the >> serial console. >> > > Good point. Currently in the acceptance tests U-Boot and Linux detect > the ethernet device, but there are no explicit checks for that in the > acceptance tests > nor any actual packet transmission. > > I'll try to extend the current tests in the next version of this series to > include some > basic checks for the ethernet device, perhaps with DHCP or a ping. > I'm open to suggestions for the preferred way to do this. > FYI, I added some coverage for the ethernet device by extending the test_arm_orangepi_sd test with a few lines like: + exec_command_and_wait_for_pattern(self, 'ifconfig eth0 up', 'eth0: Link is Up') + exec_command_and_wait_for_pattern(self, 'udhcpc eth0', + 'udhcpc: lease of 10.0.2.15 obtained') + exec_command_and_wait_for_pattern(self, 'ping -c 3 10.0.2.2', + '3 packets transmitted, 3 packets received, 0% packet loss') Regards, Niek > Regards, > Niek > > > > > > >> >> <snip> >> >> -- >> Alex Bennée >> > > > -- > Niek Linnenbank > >
Hi Peter, On Mon, Mar 9, 2020 at 12:22 PM Peter Maydell <peter.maydell@linaro.org> wrote: > On Wed, 4 Mar 2020 at 20:55, Niek Linnenbank <nieklinnenbank@gmail.com> > wrote: > > > > Hello Alex, > > > > On Wed, Mar 4, 2020 at 11:35 AM Alex Bennée <alex.bennee@linaro.org> > wrote: > >> > >> > >> Niek Linnenbank <nieklinnenbank@gmail.com> writes: > >> > --- > >> > docs/orangepi.rst | 226 > >> > ++++++++++++++++++++++++++++++++++++++++++++++ > >> > >> I suspect there is a better place to put this is than the top level. I > >> wonder if it should be docs/specs? > > > > > > Yeah I'm fine to move it to a different subdirectory if needed. Right > now its placed in docs, > > as it seems that documents for machines are also placed there, for > example docs/microvm.rst > > The only things in the top level docs/ are a handful of > legacy-ish files that went there because we didn't yet have > a better place to put them. We should avoid increasing the > number of orphan files in the top level (and indeed should > try to move the existing orphans elsewhere). > > >> When Peter's document PR goes in later this week there will also be a: > >> > >> docs/system/target-arm.rst > >> > >> which would benefit from a section for the Orange Pi in it. > > Yes, this is now the right place to put arm board-specific > documentation (the rearranging and conversion from texinfo > is now in master). I should move microvm.rst's contents there > I guess. > OK, I'll move orangepi.rst to docs/system/orangepi.rst and add a short section about the Orange Pi PC machine to docs/system/target-arm.rst as well. Regards, Niek > > thanks > -- PMM >
On Mon, 9 Mar 2020 at 19:38, Niek Linnenbank <nieklinnenbank@gmail.com> wrote: > On Mon, Mar 9, 2020 at 12:22 PM Peter Maydell <peter.maydell@linaro.org> wrote: >> Yes, this is now the right place to put arm board-specific >> documentation (the rearranging and conversion from texinfo >> is now in master). I should move microvm.rst's contents there >> I guess. > > > OK, I'll move orangepi.rst to docs/system/orangepi.rst and add a short section > about the Orange Pi PC machine to docs/system/target-arm.rst as well. You should include/reference the orangepi.rst from target-arm.rst, I think -- that's where the per-board docs would belong in the structure we have. If you just drop a .rst file into the docs directory somewhere it won't actually go into the documentation and instead Sphinx will error out about it not being in the table of contents anywhere. (I'll have a look at microvm.rst to see how best to make the structure work -- at the moment it kind of assumes there board documentation is always quite short so they're all in one file.) thanks -- PMM
On Mon, Mar 9, 2020 at 8:43 PM Peter Maydell <peter.maydell@linaro.org> wrote: > On Mon, 9 Mar 2020 at 19:38, Niek Linnenbank <nieklinnenbank@gmail.com> > wrote: > > On Mon, Mar 9, 2020 at 12:22 PM Peter Maydell <peter.maydell@linaro.org> > wrote: > >> Yes, this is now the right place to put arm board-specific > >> documentation (the rearranging and conversion from texinfo > >> is now in master). I should move microvm.rst's contents there > >> I guess. > > > > > > OK, I'll move orangepi.rst to docs/system/orangepi.rst and add a short > section > > about the Orange Pi PC machine to docs/system/target-arm.rst as well. > > You should include/reference the orangepi.rst from target-arm.rst, I think > -- > that's where the per-board docs would belong in the structure we have. > If you just drop a .rst file into the docs directory somewhere it won't > actually go into the documentation and instead Sphinx will error > out about it not being in the table of contents anywhere. > Ah now I see what is going on here. So the new rst files are ment to automatically generate documentation in various formats using the Python sphinx tool, correct? I played around a bit with running 'make html' and using the include directive you suggested in the target-arm.rst file like: .. include:: orangepi.rst That seems to work. And, now I also see that the orangepi.rst file contains rst syntax errors which I need to resolve. I'll make sure those are resolved in the next version. > > (I'll have a look at microvm.rst to see how best to make the structure > work -- at the moment it kind of assumes there board documentation > is always quite short so they're all in one file.) > Yeah that is fine Peter. If you have any update on that later, I'll adjust the orangepi.rst file to fit in as well. Regards, Niek > > thanks > -- PMM >
On Mon, 9 Mar 2020 at 20:05, Niek Linnenbank <nieklinnenbank@gmail.com> wrote: > Ah now I see what is going on here. So the new rst files are ment to automatically generate > documentation in various formats using the Python sphinx tool, correct? Yep. Assuming you have Sphinx installed, "make" should build the documentation as well as the executables (ie you don't need specifically 'make html'). > I played around a bit with running 'make html' and using the include directive you suggested in > the target-arm.rst file like: > > .. include:: orangepi.rst I'm currently writing a patchset which splits the existing target-arm.rst into a bunch of per-board files in docs/system/arm/. If that patchset goes in before you roll the next verison of the series then it should just be a matter of putting orangepi.rst in the docs/system/arm/ directory and adding a line to the table-of-contents in docs/system/target-arm.rst. If you're ready to send out the next version before that, then leave it with the include:: directive and we can fix it up to the new structure later. thanks -- PMM
On Mon, Mar 9, 2020 at 9:12 PM Peter Maydell <peter.maydell@linaro.org> wrote: > On Mon, 9 Mar 2020 at 20:05, Niek Linnenbank <nieklinnenbank@gmail.com> > wrote: > > Ah now I see what is going on here. So the new rst files are ment to > automatically generate > > documentation in various formats using the Python sphinx tool, correct? > > Yep. Assuming you have Sphinx installed, "make" should build the > documentation as well as the executables (ie you don't need > specifically 'make html'). > > > I played around a bit with running 'make html' and using the include > directive you suggested in > > the target-arm.rst file like: > > > > .. include:: orangepi.rst > > I'm currently writing a patchset which splits the existing > target-arm.rst into a bunch of per-board files in > docs/system/arm/. If that patchset goes in before you > roll the next verison of the series then it should > just be a matter of putting orangepi.rst in the > docs/system/arm/ directory and adding a line to the > table-of-contents in docs/system/target-arm.rst. > Ah yes, that makes sense indeed. I'll keep an eye out for your new patchset. > If you're ready to send out the next version before that, > then leave it with the include:: directive and we can > fix it up to the new structure later. > OK Peter! Regards, Niek > thanks > -- PMM >
On Mon, 9 Mar 2020 at 20:12, Peter Maydell <peter.maydell@linaro.org> wrote: > If you're ready to send out the next version before that, > then leave it with the include:: directive and we can > fix it up to the new structure later. PS: in case you weren't aware, softfreeze for the 5.0 release is 17th March, so if this series is going to go in for 5.0 then (a) people interested in reviewing it should hurry up and review patches 9..18 and (b) the final version would need to be on the list sometime this week so it can go into a pull request by the 17th. It's no big deal if it goes into 5.1 instead I guess, but it feels like the series is nearly ready so I figured I'd set out the timeline if people want to push to get it into 5.0. thanks -- PMM
Niek Linnenbank <nieklinnenbank@gmail.com> writes: > Hi Alex, > > On Wed, Mar 4, 2020 at 9:55 PM Niek Linnenbank <nieklinnenbank@gmail.com> > wrote: > >> Hello Alex, >> >> On Wed, Mar 4, 2020 at 11:35 AM Alex Bennée <alex.bennee@linaro.org> >> wrote: >> >>> >>> Niek Linnenbank <nieklinnenbank@gmail.com> writes: >>> >>> > The Xunlong Orange Pi PC machine is a functional ARM machine >>> > based on the Allwinner H3 System-on-Chip. It supports mainline >>> > Linux, U-Boot, NetBSD and is covered by acceptance tests. >>> > >>> > This commit adds a documentation text file with a description >>> > of the machine and instructions for the user. >>> >>> This is great, thanks for taking the time to include documentation. >>> >> >> Sure, I'm happy to contribute it. I tried to include most relevant >> information >> in there for developers and potential users of the machine. If something >> is missing >> just let me know and I'll make an update for it. >> >> >>> >>> > >>> > Signed-off-by: Niek Linnenbank <nieklinnenbank@gmail.com> >>> > --- >>> > docs/orangepi.rst | 226 >>> > ++++++++++++++++++++++++++++++++++++++++++++++ >>> >>> I suspect there is a better place to put this is than the top level. I >>> wonder if it should be docs/specs? >>> >> >> Yeah I'm fine to move it to a different subdirectory if needed. Right now >> its placed in docs, >> as it seems that documents for machines are also placed there, for example >> docs/microvm.rst >> >> >>> >>> > MAINTAINERS | 1 + >>> > 2 files changed, 227 insertions(+) >>> > create mode 100644 docs/orangepi.rst >>> > >>> > diff --git a/docs/orangepi.rst b/docs/orangepi.rst >>> > new file mode 100644 >>> > index 0000000000..a9b46f553c >>> > --- /dev/null >>> > +++ b/docs/orangepi.rst >>> > @@ -0,0 +1,226 @@ >>> > +========================= >>> > +Orange Pi PC Machine Type >>> > +========================= >>> > + >>> > +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip >>> > +based embedded computer with mainline support in both U-Boot >>> > +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz, >>> > +1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and >>> > +various other I/O. >>> >>> When Peter's document PR goes in later this week there will also be a: >>> >>> docs/system/target-arm.rst >>> >>> which would benefit from a section for the Orange Pi in it. >>> >> >> Nice, I'll have a look at it when it gets merged and add a section for >> Orange Pi. >> I'll try to include that in the next version of this series. >> >> >>> >>> > + >>> > +Supported devices >>> > +----------------- >>> > + >>> > +The Orange Pi PC machine supports the following devices: >>> > + >>> > + * SMP (Quad Core Cortex A7) >>> > + * Generic Interrupt Controller configuration >>> > + * SRAM mappings >>> > + * SDRAM controller >>> > + * Real Time Clock >>> > + * Timer device (re-used from Allwinner A10) >>> > + * UART >>> > + * SD/MMC storage controller >>> > + * EMAC ethernet >>> >>> Do we ever exercise the ethernet in the acceptance tests? I see we have >>> some that boots a full OS but boot console only seems to touch the >>> serial console. >>> >> >> Good point. Currently in the acceptance tests U-Boot and Linux detect >> the ethernet device, but there are no explicit checks for that in the >> acceptance tests >> nor any actual packet transmission. >> >> I'll try to extend the current tests in the next version of this series to >> include some >> basic checks for the ethernet device, perhaps with DHCP or a ping. >> I'm open to suggestions for the preferred way to do this. >> > > FYI, I added some coverage for the ethernet device by extending the > test_arm_orangepi_sd test with a few lines like: > > + exec_command_and_wait_for_pattern(self, 'ifconfig eth0 up', 'eth0: > Link is Up') > + exec_command_and_wait_for_pattern(self, 'udhcpc eth0', > + 'udhcpc: lease of > 10.0.2.15 obtained') > + exec_command_and_wait_for_pattern(self, 'ping -c 3 10.0.2.2', > + '3 packets transmitted, 3 packets received, 0% packet loss') > That will work as a smoke test. Are you going to re-spin this week so we can get the final reviews done? > Regards, > Niek > > >> Regards, >> Niek >> >> >> >> >> >> >>> >>> <snip> >>> >>> -- >>> Alex Bennée >>> >> >> >> -- >> Niek Linnenbank >> >>
Hi Peter, On Mon, Mar 9, 2020 at 11:01 PM Peter Maydell <peter.maydell@linaro.org> wrote: > On Mon, 9 Mar 2020 at 20:12, Peter Maydell <peter.maydell@linaro.org> > wrote: > > If you're ready to send out the next version before that, > > then leave it with the include:: directive and we can > > fix it up to the new structure later. > > PS: in case you weren't aware, softfreeze for the 5.0 release > is 17th March, so if this series is going to go in for 5.0 > then (a) people interested in reviewing it should hurry up > and review patches 9..18 and (b) the final version would > need to be on the list sometime this week so it can go into > a pull request by the 17th. > Ah I was not aware of that date indeed! Yes, ofcourse, if we can get the remaining parts reviewed as well to include it in 5.0, that would be great. As a side note, I'm basically doing this project in my spare time in the (late) evenings (Amsterdam timezone), so I'll make sure to reserve some extra time the coming days so I can reply and respin fast if needed. I'm finalizing & testing the v7 update now and will send it out in a few hours to the list. Regards, Niek > > It's no big deal if it goes into 5.1 instead I guess, > but it feels like the series is nearly ready so I figured > I'd set out the timeline if people want to push to get it > into 5.0. > > thanks > -- PMM >
On Tue, Mar 10, 2020 at 9:16 AM Alex Bennée <alex.bennee@linaro.org> wrote: > > Niek Linnenbank <nieklinnenbank@gmail.com> writes: > > > Hi Alex, > > > > On Wed, Mar 4, 2020 at 9:55 PM Niek Linnenbank <nieklinnenbank@gmail.com > > > > wrote: > > > >> Hello Alex, > >> > >> On Wed, Mar 4, 2020 at 11:35 AM Alex Bennée <alex.bennee@linaro.org> > >> wrote: > >> > >>> > >>> Niek Linnenbank <nieklinnenbank@gmail.com> writes: > >>> > >>> > The Xunlong Orange Pi PC machine is a functional ARM machine > >>> > based on the Allwinner H3 System-on-Chip. It supports mainline > >>> > Linux, U-Boot, NetBSD and is covered by acceptance tests. > >>> > > >>> > This commit adds a documentation text file with a description > >>> > of the machine and instructions for the user. > >>> > >>> This is great, thanks for taking the time to include documentation. > >>> > >> > >> Sure, I'm happy to contribute it. I tried to include most relevant > >> information > >> in there for developers and potential users of the machine. If something > >> is missing > >> just let me know and I'll make an update for it. > >> > >> > >>> > >>> > > >>> > Signed-off-by: Niek Linnenbank <nieklinnenbank@gmail.com> > >>> > --- > >>> > docs/orangepi.rst | 226 > >>> > ++++++++++++++++++++++++++++++++++++++++++++++ > >>> > >>> I suspect there is a better place to put this is than the top level. I > >>> wonder if it should be docs/specs? > >>> > >> > >> Yeah I'm fine to move it to a different subdirectory if needed. Right > now > >> its placed in docs, > >> as it seems that documents for machines are also placed there, for > example > >> docs/microvm.rst > >> > >> > >>> > >>> > MAINTAINERS | 1 + > >>> > 2 files changed, 227 insertions(+) > >>> > create mode 100644 docs/orangepi.rst > >>> > > >>> > diff --git a/docs/orangepi.rst b/docs/orangepi.rst > >>> > new file mode 100644 > >>> > index 0000000000..a9b46f553c > >>> > --- /dev/null > >>> > +++ b/docs/orangepi.rst > >>> > @@ -0,0 +1,226 @@ > >>> > +========================= > >>> > +Orange Pi PC Machine Type > >>> > +========================= > >>> > + > >>> > +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip > >>> > +based embedded computer with mainline support in both U-Boot > >>> > +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz, > >>> > +1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and > >>> > +various other I/O. > >>> > >>> When Peter's document PR goes in later this week there will also be a: > >>> > >>> docs/system/target-arm.rst > >>> > >>> which would benefit from a section for the Orange Pi in it. > >>> > >> > >> Nice, I'll have a look at it when it gets merged and add a section for > >> Orange Pi. > >> I'll try to include that in the next version of this series. > >> > >> > >>> > >>> > + > >>> > +Supported devices > >>> > +----------------- > >>> > + > >>> > +The Orange Pi PC machine supports the following devices: > >>> > + > >>> > + * SMP (Quad Core Cortex A7) > >>> > + * Generic Interrupt Controller configuration > >>> > + * SRAM mappings > >>> > + * SDRAM controller > >>> > + * Real Time Clock > >>> > + * Timer device (re-used from Allwinner A10) > >>> > + * UART > >>> > + * SD/MMC storage controller > >>> > + * EMAC ethernet > >>> > >>> Do we ever exercise the ethernet in the acceptance tests? I see we have > >>> some that boots a full OS but boot console only seems to touch the > >>> serial console. > >>> > >> > >> Good point. Currently in the acceptance tests U-Boot and Linux detect > >> the ethernet device, but there are no explicit checks for that in the > >> acceptance tests > >> nor any actual packet transmission. > >> > >> I'll try to extend the current tests in the next version of this series > to > >> include some > >> basic checks for the ethernet device, perhaps with DHCP or a ping. > >> I'm open to suggestions for the preferred way to do this. > >> > > > > FYI, I added some coverage for the ethernet device by extending the > > test_arm_orangepi_sd test with a few lines like: > > > > + exec_command_and_wait_for_pattern(self, 'ifconfig eth0 up', > 'eth0: > > Link is Up') > > + exec_command_and_wait_for_pattern(self, 'udhcpc eth0', > > + 'udhcpc: lease of > > 10.0.2.15 obtained') > > + exec_command_and_wait_for_pattern(self, 'ping -c 3 10.0.2.2', > > + '3 packets transmitted, 3 packets received, 0% packet loss') > > > > That will work as a smoke test. Are you going to re-spin this week so we > can get the final reviews done? > OK Alex! Yes, as I just replied to Peter as well, I'm finalizing / testing the v7 update now and will send it to the list in a few hours. I'll reserve some extra time the coming days so I can reply & respin quickly. Regards, Niek > > > Regards, > > Niek > > > > > >> Regards, > >> Niek > >> > >> > >> > >> > >> > >> > >>> > >>> <snip> > >>> > >>> -- > >>> Alex Bennée > >>> > >> > >> > >> -- > >> Niek Linnenbank > >> > >> > > > -- > Alex Bennée >
diff --git a/docs/orangepi.rst b/docs/orangepi.rst new file mode 100644 index 0000000000..a9b46f553c --- /dev/null +++ b/docs/orangepi.rst @@ -0,0 +1,226 @@ +========================= +Orange Pi PC Machine Type +========================= + +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip +based embedded computer with mainline support in both U-Boot +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz, +1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and +various other I/O. + +Supported devices +----------------- + +The Orange Pi PC machine supports the following devices: + + * SMP (Quad Core Cortex A7) + * Generic Interrupt Controller configuration + * SRAM mappings + * SDRAM controller + * Real Time Clock + * Timer device (re-used from Allwinner A10) + * UART + * SD/MMC storage controller + * EMAC ethernet + * USB 2.0 interfaces + * Clock Control Unit + * System Control module + * Security Identifier device + +Limitations +----------- + +Currently, Orange Pi PC does *not* support the following features: + +- Graphical output via HDMI, GPU and/or the Display Engine +- Audio output +- Hardware Watchdog + +Also see the 'unimplemented' array in the Allwinner H3 SoC module +for a complete list of unimplemented I/O devices: + ./hw/arm/allwinner-h3.c + +Using the Orange Pi PC machine type +----------------------------------- + +Boot options +~~~~~~~~~~~~ + +The Orange Pi PC machine can start using the standard -kernel functionality +for loading a Linux kernel or ELF executable. Additionally, the Orange Pi PC +machine can also emulate the BootROM which is present on an actual Allwinner H3 +based SoC, which loads the bootloader from a SD card, specified via the -sd argument +to qemu-system-arm. + +Machine-specific options +~~~~~~~~~~~~~~~~~~~~~~~~ + +The following machine-specific options are supported: + +- allwinner-rtc.base-year=YYYY + + The Allwinner RTC device is automatically created by the Orange Pi PC machine + and uses a default base year value which can be overridden using the 'base-year' property. + The base year is the actual represented year when the RTC year value is zero. + This option can be used in case the target operating system driver uses a different + base year value. The minimum value for the base year is 1900. + +- allwinner-sid.identifier=abcd1122-a000-b000-c000-12345678ffff + + The Security Identifier value can be read by the guest. + For example, U-Boot uses it to determine a unique MAC address. + +The above machine-specific options can be specified in qemu-system-arm +via the '-global' argument, for example: + + $ qemu-system-arm -M orangepi-pc -sd mycard.img \ + -global allwinner-rtc.base-year=2000 + +Running mainline Linux +~~~~~~~~~~~~~~~~~~~~~~ + +Mainline Linux kernels from 4.19 up to latest master are known to work. +To build a Linux mainline kernel that can be booted by the Orange Pi PC machine, +simply configure the kernel using the sunxi_defconfig configuration: + + $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make mrproper + $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make sunxi_defconfig + +To be able to use USB storage, you need to manually enable the corresponding +configuration item. Start the kconfig configuration tool: + + $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make menuconfig + +Navigate to the following item, enable it and save your configuration: + + Device Drivers > USB support > USB Mass Storage support + +Build the Linux kernel with: + + $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make + +To boot the newly build linux kernel in QEMU with the Orange Pi PC machine, use: + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -kernel /path/to/linux/arch/arm/boot/zImage \ + -append 'console=ttyS0,115200' \ + -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb + +Orange Pi PC images +~~~~~~~~~~~~~~~~~~~ + +Note that the mainline kernel does not have a root filesystem. You may provide it +with an official Orange Pi PC image from the official website: + + http://www.orangepi.org/downloadresources/ + +Another possibility is to run an Armbian image for Orange Pi PC which +can be downloaded from: + + https://www.armbian.com/orange-pi-pc/ + +Alternatively, you can also choose to build you own image with buildroot +using the orangepi_pc_defconfig. Also see https://buildroot.org for more information. + +You can choose to attach the selected image either as an SD card or as USB mass storage. +For example, to boot using the Orange Pi PC Debian image on SD card, simply add the -sd +argument and provide the proper root= kernel parameter: + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -kernel /path/to/linux/arch/arm/boot/zImage \ + -append 'console=ttyS0,115200 root=/dev/mmcblk0p2' \ + -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb \ + -sd OrangePi_pc_debian_stretch_server_linux5.3.5_v1.0.img + +To attach the image as an USB mass storage device to the machine, +simply append to the command: + + -drive if=none,id=stick,file=myimage.img \ + -device usb-storage,bus=usb-bus.0,drive=stick + +Instead of providing a custom Linux kernel via the -kernel command you may also +choose to let the Orange Pi PC machine load the bootloader from SD card, just like +a real board would do using the BootROM. Simply pass the selected image via the -sd +argument and remove the -kernel, -append, -dbt and -initrd arguments: + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -sd Armbian_19.11.3_Orangepipc_buster_current_5.3.9.img + +Note that both the official Orange Pi PC images and Armbian images start +a lot of userland programs via systemd. Depending on the host hardware and OS, +they may be slow to emulate, especially due to emulating the 4 cores. +To help reduce the performance slow down due to emulating the 4 cores, you can +give the following kernel parameters (or via -append): + + => setenv extraargs 'systemd.default_timeout_start_sec=9000 loglevel=7 nosmp console=ttyS0,115200' + +Running U-Boot +~~~~~~~~~~~~~~ + +U-Boot mainline can be build and configured using the orangepi_pc_defconfig +using similar commands as describe above for Linux. Note that it is recommended +for development/testing to select the following configuration setting in U-Boot: + + Device Tree Control > Provider for DTB for DT Control > Embedded DTB + +To start U-Boot using the Orange Pi PC machine, provide the +u-boot binary to the -kernel argument: + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -kernel /path/to/uboot/u-boot -sd disk.img + +Use the following U-boot commands to load and boot a Linux kernel from SD card: + + -> setenv bootargs console=ttyS0,115200 + -> ext2load mmc 0 0x42000000 zImage + -> ext2load mmc 0 0x43000000 sun8i-h3-orangepi-pc.dtb + -> bootz 0x42000000 - 0x43000000 + +Running NetBSD +~~~~~~~~~~~~~~ + +The NetBSD operating system also includes support for Allwinner H3 based boards, +including the Orange Pi PC. NetBSD 9.0 is known to work best for the Orange Pi PC +board and provides a fully working system with serial console, networking and storage. +For the Orange Pi PC machine, get the 'evbarm-earmv7hf' based image from: + + https://cdn.netbsd.org/pub/NetBSD/NetBSD-9.0/evbarm-earmv7hf/binary/gzimg/armv7.img.gz + +The image requires manually installing U-Boot in the image. Build U-Boot with +the orangepi_pc_defconfig configuration as described in the previous section. +Next, unzip the NetBSD image and write the U-Boot binary including SPL using: + + $ gunzip armv7.img.gz + $ dd if=/path/to/u-boot-sunxi-with-spl.bin of=armv7.img bs=1024 seek=8 conv=notrunc + +Finally, before starting the machine the SD image must be extended such +that the NetBSD kernel will not conclude the NetBSD partition is larger than +the emulated SD card: + + $ dd if=/dev/zero bs=1M count=64 >> armv7.img + +Start the machine using the following command: + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -sd armv7.img -global allwinner-rtc.base-year=2000 + +At the U-Boot stage, interrupt the automatic boot process by pressing a key +and set the following environment variables before booting: + + => setenv bootargs root=ld0a + => setenv kernel netbsd-GENERIC.ub + => setenv fdtfile dtb/sun8i-h3-orangepi-pc.dtb + => setenv bootcmd 'fatload mmc 0:1 ${kernel_addr_r} ${kernel}; fatload mmc 0:1 ${fdt_addr_r} ${fdtfile}; fdt addr ${fdt_addr_r}; bootm ${kernel_addr_r} - ${fdt_addr_r}' + +Optionally you may save the environment variables to SD card with 'saveenv'. +To continue booting simply give the 'boot' command and NetBSD boots. + +Orange Pi PC acceptance tests +----------------------------- + +The Orange Pi PC machine has several acceptance tests included. +To run the whole set of tests, build QEMU from source and simply +provide the following command: + + $ AVOCADO_ALLOW_LARGE_STORAGE=yes avocado --show=app,console run \ + -t machine:orangepi-pc tests/acceptance/boot_linux_console.py diff --git a/MAINTAINERS b/MAINTAINERS index 02ecba8d9c..643906bd18 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -497,6 +497,7 @@ S: Maintained F: hw/*/allwinner-h3* F: include/hw/*/allwinner-h3* F: hw/arm/orangepi.c +F: docs/orangepi.rst ARM PrimeCell and CMSDK devices M: Peter Maydell <peter.maydell@linaro.org>
The Xunlong Orange Pi PC machine is a functional ARM machine based on the Allwinner H3 System-on-Chip. It supports mainline Linux, U-Boot, NetBSD and is covered by acceptance tests. This commit adds a documentation text file with a description of the machine and instructions for the user. Signed-off-by: Niek Linnenbank <nieklinnenbank@gmail.com> --- docs/orangepi.rst | 226 ++++++++++++++++++++++++++++++++++++++++++++++ MAINTAINERS | 1 + 2 files changed, 227 insertions(+) create mode 100644 docs/orangepi.rst