doc/porting-boards.md: improve with porting graph and reference section

[miri64]

Contribution description

The main objective of this PR is to provide a porting flowchart similar to the one AWS FreeRTOS provides (but way simpler, since we have a HAL). For the color scheme I oriented myself on other graphs (like the netdev description or the one on the gnrc main page).

Since we lack some guides however ("How to port a CPU?", "How to make a network device compatible with a network stack?") I added some TODO notes for those to the be provided so I have something to link to.

Regarding the "How to port a CPU?" part @akshaim has already something in the pipeline AFAIK, @jia200x, @fjmolinas should we look into the "How to make a network device compatible with a network stack?" part?

Testing procedure

Read the doc generated by CircleCI. When clicking the rectangle action nodes in the graph, you will be lead to the corresponding guide.

Issues/PRs references

None.

[MrKevinWeiss]

Can we either drop the todos and add them in a tracking issue or just implement them?

Whenever I read todo in others documentation I always get scared off.

[MrKevinWeiss]

Other than that I think it is helpful.

[waehlisch]

when i click on the rectangles, i get an error message. maybe this is because of CircleID?

rest looks good to me!

[miri64]

when i click on the rectangles, i get an error message. maybe this is because of CircleID?

Yeah, seems like a problem of CircleCI specifically in this case. Since I link it statically, CircleCI seems to try to access its static store for that link, so that might be the problem here.

But I can have a look, if one can reference a page dynamically from a dot file. As the name of the output HTML might change (and it also won't work for a LaTeX-generated PDF) this might be desirable anyway.

[miri64]

Whenever I read todo in others documentation I always get scared off.

Will remove the @todo from the netdev page, but keep the one for CPUs for now, since I expect a PR from @akshaim for that soon. I am a bit worried though, that not having a porting guide in netdev but referring to it in the graph might also confuse people. But confusion may be less harmful being scared off :-).

[miri64]

But I can have a look, if one can reference a page dynamically from a dot file.

Using @ref <page-name> seems to work just fine even in an imported dot file.

[miri64]

But I can have a look, if one can reference a page dynamically from a dot file.

Using @ref <page-name> seems to work just fine even in an imported dot file.

Done that and also did some style fixes to the dot file. Now, if porting-cpus.md would be removed it would generate an error and the link would just lead to the generated SVG of the graph itself.

[miri64]

Can you have another look @waehlisch, please, once CircleCI is done building the artifact?

[akshaim]

Hey @miri64 ,

Instead of the 'END", can you have it as "Blink the LED's" and link it to LED tests . Afterall its not really the end 😉

[miri64]

Instead of the 'END", can you have it as "Blink the LED's" and link it to LED tests

I thought the long-term plan was to get rid of the LEDx_* macros (see #15931). Since this is the final test, wouldn't linking to the hello-world example be a better way (and also be more "traditional", because let's be honest, every guide should at least contain a "Hello World" ;-))

[miri64]

Afterall its not really the end 😉

That makes it even more funny, because then the graph would literally end in a "Hello" ;-).

[akshaim]

Instead of the 'END", can you have it as "Blink the LED's" and link it to LED tests

I thought the long-term plan was to get rid of the LEDx_* macros (see #15931). Since this is the final test, wouldn't linking to the hello-world example be a better way (and also be more "traditional", because let's be honest, every guide should at least contain a "Hello World" ;-))

Ending on a "Hello World" sounds cool but making a board print hello world over serial might take more time than blinking the LED's which is pretty straight forward , doesn't event need timers :)

[miri64]

Ending on a "Hello World" sounds cool but making a board print hello world over serial might take more time than blinking the LED's which is pretty straight forward , doesn't event need timers :)

Mhhh, the porting guide mentions the LED macros within board.h but only in half a sentence, so the dev might not even see the LEDs blinking either. hello-world does not need timers either (when the stdio does not need it). But maybe, when the LED macros are gone, the test will be ported to either dbgpin or just straight periph_gpio, so OK.

[miri64]

Can you have another look @waehlisch, please, once CircleCI is done building the artifact?

Links still don't work I just noticed :-/. But they do locally when build with make doc.

[miri64]

Instead of the 'END", can you have it as "Blink the LED's" and link it to LED tests . Afterall its not really the end wink

Done

[miri64]

BTW feel free to provide more examples that I could integrate here. Feels a bit pretentious to only cite my own blog here ;-).

[MrKevinWeiss]

I think it is great!

[akshaim]

I did a porting guide for EFM32HG "CPU". Could be useful for similar ones as well. The porting guide does not include documentation on the generator tools used by @basilfx though.

[waehlisch]

why not adding this documentation as a concrete example for porting to the doxygen?

[miri64]

@akshaim I can link your guide. How would you prefer it to be cited here?

[akshaim]

You can have it as an additional reference for quick help.

On a side note, I was trying to document the process of board port for other platforms but it seems like there is no easy way to do it. The above example I cited is an easy "dirty" way to port the CPU but not the "recommended" method as different maintainers use different processes. Which do you think makes sense to document the easy method or recommended method?

[miri64]

Added.

[miri64]

Which do you think makes sense to document the easy method or recommended method?

I never ported a CPU, so I can't really tell what methods are there and which are preferred by whom. Me in your place would go for what you think is the best method first and then ask for input by other maintainers in the PR.

[akshaim]

Okay. That sounds good to me :)

[fjmolinas]

ping @miri64 @akshaim

[miri64]

ping @miri64 @akshaim

Still waiting for @akshaim's CPU porting guide.

[miri64]

Alternatively, I could delete the reference to it for now.

[akshaim]

Still waiting for @akshaim's CPU porting guide.

I think you can use the one I shared above for the CPUs from Silicon Labs. Regarding STM CPU's, I am currently porting one STM SOC but the port is not complete yet hence guide is incomplete. Regarding Atmel/Microchip CPU's I have not tried.

[benpicco]

Alternatively, I could delete the reference to it for now.

+1 let's move this forward.

[miri64]

Done. I removed the porting-cpus.md altogether for now and added a "(TBD: provide guide)" to the graph. Maybe some of the /cpu contributors (@haukepetersen, @benpicco, @aabadie, @jnohlgard, @kaspar030, @basilfx, @kYc0o, ...) can pick up from that in a follow-up.

[benpicco]

Please squash!

[miri64]

Please squash!

Done