You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by GitBox <gi...@apache.org> on 2020/11/26 18:52:19 UTC
[GitHub] [incubator-nuttx] v01d opened a new issue #2409: Properly document each arch, SoC family and board
v01d opened a new issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409
I've been thinking for some time on how to better organize and document all the hardware that NuttX supports. My idea is to have three levels of "supported X" sections in Documentation:
1. Supported Architectures
2. Supported SoCs
3. Supported Boards
For (1) it would document how things are implemented in arch/arm (and each arm version), arch/risc-v, etc. Not very familiar with those parts but most likely something things are worth explaining.
For (2) it would document how each SoC family (stm32, stm32l4, nrf52, etc) exposes and implements hardware functionality on NuttX.
For (3) I think it would be useful to document each board similarly to how Zephyr does. For example: https://docs.zephyrproject.org/latest/boards/arm/atsamd21_xpro/doc/index.html
This means a picture of the board, description of on-board devices (possibly indicating either supported or not supported features) and maybe some examples of particular configurations demonstrating some interesting ability of the board (ie: LVGL running on embedded display, etc).
For both (1) and (2) there are surely quite a lot of APIs to document which would also help in understanding how to support new chips/boards. These are also good places to document required toolchains.
For (3) we currently have board READMEs, which vary in quality/techical detail. Many were copied from other READMEs and there's a lot of repetition explaining how to do basic NuttX things or things that apply to all boards with the SoC (an example of something to document at (2)). So I'm not sure how much we could take advantage of those READMEs but of course they would be a starting point for (3).
What I'm unsure about is where to place these RST documents. The normal thing would be to continue documenting all of this under Documentation/. But I wonder if someone who changes something for a board, SoC or architecture will really be aware of the documentation which need updating if it is placed elsewhere. Of course just placing the file "close" to the relevant sources is no guarantee either. The downside of doing so is that board pictures for example would probably have to be stored next to sources (probably not a good idea). What do you think about this?
I know all of this is a lot of documentation to write but I think it is better to have start exposing this with very basic information than to not have anything at all.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] acassis commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
acassis commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774519251
Yes, I noticed that the leaf was the nRF52 SoC, this is why I suggested creating Supported XXXX Platform as top item, but I agree with you it could be too crowded. Maybe we could modify the system to display one more level.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
btashton commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-734446299
I think it makes sense to put these docs in the Documentation folder. I think making sure people update the docs is just something we need to get in a habit of during the review process.
Putting the docs there also makes it easier to link to shared information. I'm happy to help get some of the board documentation up to date at least for boards that I have.
We do have a lot of boards that are quite old and not available anymore, I guess we can base it on what is already there.
There is still a lot of good information in the wiki that we should also start migrating over.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-734500205
I think we can start by the boards (point (3)) and work our way up. Documenting everything in arch or the different chips can be daunting. At least, we can just list the devices/features that are supported.
In the old documentation, we had an HTML table that groups all the supported architectures, chips and boards and then some descriptive details where given in a section below.
The boards READMEs are more for technical details, they show how to run the configs and how to overcome certain issues.
For the boards, we can group all the information in one document as suggested. We would end up with something similar to the Zephyr example.
> I think making sure people update the docs is just something we need to get in a habit of during the review process.
Yes, we really need to do that. In the previous 2 releases we had to update the documents during the preparation of the release notes. That was somewhat painful as things can accumulate.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] acassis commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
acassis commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774528893
@v01d That is perfect! Could you please submit it? So we will use it as base for other boards.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
btashton commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774532255
> BTW, how do we deal with licensing of images? This pinout diagram is from MakerDairy official GitHub with MIT license. Should I add the copyright notice somewhere?
Yes the NOTICE file needs to be updated for these bundled binaries see
https://www.apache.org/legal/src-headers.html#faq-media
We should also be very careful about keeping the images we use small if possible so we do not blow up the repository size.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] acassis commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
acassis commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774515446
@v01d I think the way you did in the screenshot is better. Separating by core-level and arch-variant is interesting only from technical point of view and organization. For end users it is better to have the name of the chip and the board names.
Maybe instead of having a single "Supported Platforms" session we could do this way:
```
Support ARM Platforms
Nordic nRF52
nRF52832-MDK
Clock Configuration
System Timer
Regulator Control
Peripheral Support
BLE Support
Supported Boards
Support RISC-V Platforms
Support Xtensa Platforms
```
This way we will get the board name
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] btashton commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
btashton commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774532371
I like this @v01d I think we should take this in whatever form seems reasonable and then iterate on it as we add content to it.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
v01d commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-734452076
> I think it makes sense to put these docs in the Documentation folder. I think making sure people update the docs is just something we need to get in a habit of during the review process.
Yes, it is probably better to do so.
>
> Putting the docs there also makes it easier to link to shared information. I'm happy to help get some of the board documentation up to date at least for boards that I have.
Great, thanks.
> We do have a lot of boards that are quite old and not available anymore, I guess we can base it on what is already there.
>
> There is still a lot of good information in the wiki that we should also start migrating over.
Yes, that is also something I looked over the other day. It will be challenging since it will probably involve finding good places for each piece of information and maybe creating new sections.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
v01d commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-734502182
> I think we can start by the boards (point (3)) and work our way up. Documenting everything in arch or the different chips can be daunting. At least, we can just list the devices/features that are supported.
Yes, there could be a lot to document, but we can focus on the important things first. I would create a skeleton for (1) and (2) and at least begin to document nRF52 in (2) which I'm most familiar with.
What I'm not sure is if we should create a "Supported Hardware" section which starts with a list of (1), and then for each item in (1) have all items in (2) and same with (3) (ie: mimicking the hierarchy of the code). The alternative is three lists, (1), (2) and (3) as top-level sections.
>
> In the old documentation, we had an HTML table that groups all the supported architectures, chips and boards and then some descriptive details where given in a section below.
Yes, that is in:
* https://nuttx.apache.org/docs/latest/introduction/supported_platforms.html
* https://nuttx.apache.org/docs/latest/introduction/detailed_support.html
but I think we should simply replace that as it gives mostly historical data which is already out of date in most cases.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
v01d commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774107175
I decided to start this, in the hopes that we can get better organized arch/board documentation. I documented nRF52 arch and will document the nRF52832-MDK board as a starting point. I also started some stubs for ESP32/BL602 to test how the hierarchy looks for boards on other archs.
I'm currently thinking how to organize the documentation. We discussed three top-level sections but I think that gets really messy since the arch-soc-board hierarchy gets flattened. I think the best way is to mimic the organization inside `boards/` as: `Documentation/platforms/<arch>/<soc>/<board>`, which allows to document things at their proper level with an individual `index.rst` (eg: `platforms/arm/index.rst`, `platforms/arm/nrf52/index.rst`, etc.).
The only thing I'm not sure how to handle is that I would like to have this three-level hierarchy visible as a ToC, but this means having the board index.rst's generate a section at the same level that of a SoC. To make this work, I had to create a "Supported Boards" section inside the soc document, which may feel a bit weird. The result is the following:
Notice that in the last screenshot the document is not visible on the sidebard as it is limited to three levels, to avoid listing too many document sections. The problem is that if I do not nest boards under a "Supported Boards" section, board entries will appear at the same level as soc document sections. Another option is to completely hide the "supported boards" section
(they can still be exposed as in the first screenshot) but it will still not be visible in the sidebar.
Do you think this approach is OK? The only other way I see is to manually create this hierarchy by writing a `boards/index.rst` with sections and subsections for arch-soc and manually written list of links to board documents. This would make the sidebar look as expected while having a similar layout as first screenshot. I guess this could be scripted (create this .rst on the fly), but I'm not sure what's better in that case.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
v01d commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774510873
@Ouss4 @btashton @xiaoxiang781216
Opinions?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
v01d commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774517640
You mean top-level sections? (like sidebar entries?) I think that when we include all supported archs it will get too crowded.
Also, note that the leaf sections are documenting a the nRF52 SoC, not the board.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] acassis edited a comment on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
acassis edited a comment on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774515446
@v01d I think the way you did in the screenshot is better. Separating by core-level and arch-variant is interesting only from technical point of view and organization. For end users it is better to have the name of the chip and the board names.
Maybe instead of having a single "Supported Platforms" session we could do this way:
```
Supported ARM Platforms
Nordic nRF52
nRF52832-MDK
Clock Configuration
System Timer
Regulator Control
Peripheral Support
BLE Support
Supported Boards
Supported RISC-V Platforms
Supported Xtensa Platforms
```
This way we will get the board name
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] Ouss4 commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
Ouss4 commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-734766504
> Yes, there could be a lot to document, but we can focus on the important things first. I would create a skeleton for (1) and (2) and at least begin to document nRF52 in (2) which I'm most familiar with.
What I'm not sure is if we should create a "Supported Hardware" section which starts with a list of (1), and then for each item in (1) have all items in (2) and same with (3) (ie: mimicking the hierarchy of the code). The alternative is three lists, (1), (2) and (3) as top-level sections.
I find the three top-level sections option better. I think it would be easier to surf and find information.
> but I think we should simply replace that as it gives mostly historical data which is already out of date in most cases.
I agree. Some of what's written there is still relevant and we can still leverage from it. But for the most part, it should be replaced by this new organisation.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
v01d commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774521764
I managed to increase depth of sidebar to five levels. As it requires expanding with the [+] it still looks OK for deeply nested sections (in fact it helps navigation). Now the first screenshot is the same, whereas the last one looks like:
The board description page is no longer "hidden" (note the sidebar):
BTW, how do we deal with licensing of images? This pinout diagram is from MakerDairy official GitHub with MIT license. Should I add the copyright notice somewhere?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] v01d commented on issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
v01d commented on issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409#issuecomment-774111180
BTW, I decided to overlook for the time being that maybe we should actually have core-level and arch-variant documentation (ie: cortex-m4, archv7m). I think these could be sibling documents to the arch one (`arm/cortex-m4.rst`), in which there could be extra ToCs for these in `arm/index.rst`. But I'm not really sure if it is really important to do this right now. I think documenting SoC-level and board-level functionality first is more important.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-nuttx] acassis closed issue #2409: Properly document each arch, SoC family and board
Posted by GitBox <gi...@apache.org>.
acassis closed issue #2409:
URL: https://github.com/apache/incubator-nuttx/issues/2409
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org