ChibiOS Free Embedded RTOS

Posted: **Tue Apr 19, 2016 12:16 pm**

Hi, last weekend I have created board files for some new Nucleo144 included the F746ZG. They are on trunk. Enjoy!

Posted: **Sun Apr 24, 2016 8:25 am**

Would it be an idea to create "generic" board file examples? i.e. board files that are completely empty except for the necessary defines?

In the beginning I got bitten by the fact that the board file for say the led flashing demo on a discovery board would KNOW that the board file had already configured the led as an output, so the demo code did not palSetPadMode for the output pin. So "porting" the blinky example to my own board was not as trivial as it should have been. Additionally I think the blinky examples (and the others) should have the palSetPadMode() in there, just to make it easier for people like me. Of course you should mark the line as: "// not strictly necessary on the Discovery board, as the board.h file already initializes this pin as an output".

As usual I'm willing to provide the patch, but I won't put in the legwork if the maintainers don't think it is a good idea. After having figured out what my problem was, I no longer benefit from this change.

Posted: **Sun Apr 24, 2016 11:44 am**

There is a lot of documentation about that. I think is not a good idea to create new code (which must be maintained over time) just to explain a mechanism that actually is well explained into documentation.

To be honest, when I started with ChibiOS I did not even know the existence of documentation, neither was interested in (booOOOooring :mrgreen:

). Actually, getting started requires just few knowledge of C, a bit of "dexterity" and existing demos. But if you want to understand how mechanisms work the documentation is of major importance.

Anyway, I was not an expert and I felt very uncomfortable with technical stuff and we decided (me and some of my friend) to write some user friendly articles about these topics. We wrote an article about PAL Driver and even an article about porting and board files.

I think this could be a better way to extend user knowledge. I await your considerations.
Ciao,
RM

Posted: **Sun Apr 24, 2016 6:59 pm**

Would it be an idea to create "generic" board file examples? i.e. board files that are completely empty except for the necessary defines?

I know that there is already board.h file generator infrastructure in chibistudio, but i wanted to have a simple generator outside of any IDE, so
i have wrote a perl script that generate board.h, for now it works for F4 and F7.

It take a readable text format (not xml). One has only to describe used pin, and the script generate generate board.h.
for the F7 which have numerous GPIO port, board.h size is about 1400 lines, but often board.cfg (the source file)
is between 50 and 100 lines

I use it on linux and macosx, since it's perl, it should works with windows, but i have not tested that it does.

I can put it on the user contrib if it can help.

Alexandre

Posted: **Sun Apr 24, 2016 7:14 pm**

You could use the generator outside Eclipse using FMPP as processor and taking the template from the plugin.

Giovanni

Posted: **Tue Apr 26, 2016 9:00 am**

RoccoMarco wrote:There is a lot of documentation about that. I think is not a good idea to create new code (which must be maintained over time) just to explain a mechanism that actually is well explained into documentation.

If you want to reduce the copied-a-million-times code that now has to be maintained in many places you can start with board.h .
it starts with:

Code: Select all

/*
 * Board oscillators-related settings.
 * NOTE: LSE not fitted.
 * NOTE: HSE not fitted.
 */
#if !defined(STM32_LSECLK)
#define STM32_LSECLK                0U
#endif

#if !defined(STM32_HSECLK)
#define STM32_HSECLK                0U
#endif

Why not use a post-board.h-include that does this? Many boards have this: we don't have crystals mounted.

Moreover, in mcuconf.h you can chose to enable the external clock. But the crystal specification is here. They should be in one place. I've been running off internal RC before I went in and enabled the external clock. Then all of a sudden I find this doesn't work-by-default define in a totally different place.

Then a few lines down we see:

Code: Select all

#define GPIOA_PIN6                  6U
#define GPIOA_PIN7                  7U
#define GPIOA_PIN8                  8U
#define GPIOA_PIN9                  9U
#define GPIOA_PIN10                 10U

What use is it to write GPIOA_PIN7 instead of "7" in the PalSetPinMode (GPIOA, ... call?

Then we see:

Code: Select all

#define PIN_MODE_INPUT(n)           (0U << ((n) * 2U))
#define PIN_MODE_OUTPUT(n)          (1U << ((n) * 2U))

Why does this have to be duplicated for each board? This depends on the processor family and maybe there are a few exceptions, but why not centrally somewhere for STM boards? Actually I just checked. This code is present in 20 board.h files. There are 30 STM32 boards... I'm guessing there is a copy-paste maintenance problem here....

To be honest, when I started with ChibiOS I did not even know the existence of documentation, neither was interested in (booOOOooring ). Actually, getting started requires just few knowledge of C, a bit of "dexterity" and existing demos. But if you want to understand how mechanisms work the documentation is of major importance.

I don't know about you, but each time I need documentation for chibios, I get a dead end. When I want to now say "strstr" in php, I google for "strstr php" and I get THE manual for strstr in php. It explains what it is for, it explains that there are a bunch of arguments and what these arguments do.

For chibios, once I know the function name, or maybe hal subsystem, I google for "chibios <keyword>" and get a hit for the 2.6.6 documentation. You have to be aware of that version number, because at first you don't realize that you're looking at old documentation. There you find a big listing with the names of the functions (I could have grepped the source for that) with the names of the arguments (I could have grepped the source for that) and... nothing more. No explanation of what those arguments do, or when to call that function. Yeah. there is a "state diagram". It tells me the driver needs to be initialized before I can use it. But then it doesn't tell me that I need to call that or if it will be done for me. From the driver's point of view, it's all clear ("Of course the driver needs to be initialized!"), but from the user it is not.

Yeah. there is documentation. But noting "usable".

Posted: **Tue Apr 26, 2016 10:30 am**

rew wrote:If you want to reduce the copied-a-million-times code that now has to be maintained in many places you can start with board.h

We don't copy this code million of time. It is auto-generated. There is a video in the post i linked before that show this.

rew wrote:Why not use a post-board.h-include that does this? Many boards have this: we don't have crystals mounted.

This is automatically created. Even more crystals depends on board!

rew wrote:Moreover, in mcuconf.h you can chose to enable the external clock. But the crystal specification is here. They should be in one place. I've been running off internal RC before I went in and enabled the external clock. Then all of a sudden I find this doesn't work-by-default define in a totally different place.

mcuconf contains configuration for the MCU only. MCU decides what should be its clock source and how to configure it. If an oscillator is mounted depends on specific board.

rew wrote:What use is it to write GPIOA_PIN7 instead of "7" in the PalSetPinMode (GPIOA, ... call?

This is auto created when in the board generator isn't specified a name for a pin.

rew wrote:Why does this have to be duplicated for each board? This depends on the processor family and maybe there are a few exceptions, but why not centrally somewhere for STM boards? Actually I just checked. This code is present in 20 board.h files. There are 30 STM32 boards... I'm guessing there is a copy-paste maintenance problem here....

Still auto created...

rew wrote:I don't know about you, but each time I need documentation for chibios, I get a dead end. When I want to now say "strstr" in php, I google for "strstr php" and I get THE manual for strstr in php. It explains what it is for, it explains that there are a bunch of arguments and what these arguments do.

For chibios, once I know the function name, or maybe hal subsystem, I google for "chibios <keyword>" and get a hit for the 2.6.6 documentation. You have to be aware of that version number, because at first you don't realize that you're looking at old documentation. There you find a big listing with the names of the functions (I could have grepped the source for that) with the names of the arguments (I could have grepped the source for that) and... nothing more. No explanation of what those arguments do, or when to call that function. Yeah. there is a "state diagram". It tells me the driver needs to be initialized before I can use it. But then it doesn't tell me that I need to call that or if it will be done for me. From the driver's point of view, it's all clear ("Of course the driver needs to be initialized!"), but from the user it is not.

Yeah. there is documentation. But noting "usable".

In first place there are several way to use this documentation. I said documentation is boring not that is not valid. :mrgreen:

You can download a pdf version of the documentation.
If you are using eclipse you can just press "open declaration" and read documentation directly into the code (my preferred).

About search on google this could be a good idea. I will see if this is easily viable. Note that documentation is auto generated from code using doxygen.
Ciao,
RM

Posted: **Tue Apr 26, 2016 11:01 am**

What he said

Anyway, it is auto-generated so many points are answered.

Said that, there is space for improvements, for example I am evaluating some kind of support for shields and looking into making board code independent from the PAL driver.

Giovanni

Posted: **Fri Apr 29, 2016 8:42 am**

RoccoMarco wrote:
rew wrote:If you want to reduce the copied-a-million-times code that now has to be maintained in many places you can start with board.h

We don't copy this code million of time. It is auto-generated. There is a video in the post i linked before that show this.

So why, when I have my own board, do I end up copying and editing the board.h?

When I (and I expect many others) start to work with chibios we first compile an example in-the-tree. Then we modify the blink frequency to see if we can make a difference. Is everything under control? Next, you copy the project out-of-tree and try to compile there. Next you start modifying stuff, adding your own code. After a while, the board configuration of say the F407 discovery you copied is no longer acceptable. So you have to switch to using your own board files.

So then I follow the compilation process of my project, find the board file I have been using all along, copy it into a subdirectory of my project and start changing it. If it is a generated file, I expect it to start with " /* This file is generated from ... by tool-X DO NOT EDIT */" but instead it starts with the standard source-code-copyright claim.

In technical situations, sometimes the "bottom-up" way of thinking leads to one situation, while top down would lead to another way of organizing. Bottom-up dictates that indeed the external crystal frequency be specified at the board level and not in mcuconf. But why isn't there a "if you enable external clock here, don't forget to set the crystal frequency in board.h!" in mcuconf? it cost me countless hours to figure that one out.

Your preferred way of structuring things is not applicable to all situations. In your case, the board always defines what hardware is on it, like crystal, CPU and other hardware. I have a bunch of boards that can have many different CPUs and any crystal I like (OK, as to crystal I limit myself to none or 8MHz).

Posted: **Fri Apr 29, 2016 9:52 am**

Hey rew,
I will try to answer your question even if I think we are going out of topic.

rew wrote:So why, when I have my own board, do I end up copying and editing the board.h?

Have you seen the video? You just need the .chcfg, editing it and than use generation tool.

rew wrote:So then I follow the compilation process of my project, find the board file I have been using all along, copy it into a subdirectory of my project and start changing it. If it is a generated file, I expect it to start with " /* This file is generated from ... by tool-X DO NOT EDIT */" but instead it starts with the standard source-code-copyright claim

Why this should be notified? The configuration tool (included un ChibiStudio) is an utility. As each utility, it must be used with awareness. Quoting: "There aren't magic bullets..."

rew wrote:In technical situations, sometimes the "bottom-up" way of thinking leads to one situation, while top down would lead to another way of organizing. Bottom-up dictates that indeed the external crystal frequency be specified at the board level and not in mcuconf. But why isn't there a "if you enable external clock here, don't forget to set the crystal frequency in board.h!" in mcuconf? it cost me countless hours to figure that one out.

Well, mcuconf.h and board.h are part of the code, not a strange kind of tutorial. I think over-commenting is useless and make code less readable. Even more there are articles and tutorials about this.

rew wrote:Your preferred way of structuring things is not applicable to all situations. In your case, the board always defines what hardware is on it, like crystal, CPU and other hardware. I have a bunch of boards that can have many different CPUs and any crystal I like (OK, as to crystal I limit myself to none or 8MHz).

It doesn't have to be applicable to all situations, it is crazy make something working with everything. We are talking about an abstraction layer: it must be applicable to most scenarios. Even more if user have to create a board with more CPUs and different crystals it is for sure a custom application. Most likely HAL is not suitable for this.

HAL is meant to be a resource to help people to develop most of their application but it is not a magic bullet. I don't think It is able to solve world hunger :mrgreen:

Note that, as example, STM32 can have just 2 external clock source, an high speed (HSE) and a low speed (LSE). I mostly use STM32 and I don't know much about other MCUs but if there are some that can have more than 2 clock sources most likely generator plugin can be improved.

If you have an idea for a good article about clock configuring we can discuss this privately. You can contact me using the pvt or the contact us page of PLAY Embedded. It is always a pleasure to create useful resources to help people to figure out how thinks work.

I hope I have answered everything, because I am going out of answers.
Ciao,
RM

ChibiOS Free Embedded RTOS

NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!

Re: NUCLEO-F746ZG - ChibiOS is great!