Simplifying working with Chibios.

[rew]

Again I was "bitten" by an upgrade in Chibios that caused my project to stop compiling.

The standard advice is then to start with a working demo and modify that. That's a hassle if my project has grown a bit and already has lots of code. Also, "starting over" with the demo and then putting every thing back in is not a fun past-time.

My suggestion is to reduce the amount of "stuff" in the demo/test directories by a lot.

I think we should have a "BLINKY" demo:

Code: Select all

#include "ch.h"
#include "hal.h"

/*
 * Green LED blinker thread, times are in milliseconds.
 */
static THD_WORKING_AREA(waThread1, 128);
static THD_FUNCTION(Thread1, arg) {

  (void)arg;
  chRegSetThreadName("blinker");
  // The board already makes this line an output, but to demo how to change a line's mode:
  palSetLineMode (LINE_LED, PAL_MODE_OUTPUT_PUSHPULL);
  while (true) {
    palToggleLine (LINE_LED);
    chThdSleepMilliseconds(fs_ready ? 125 : 500);
  }
}

int main (void)
{
   // I would prefer if these moved to a chibios startup file eventually, but until then.....
  halInit();
  chSysInit();
 
  chThdCreateStatic(waThread1, sizeof(waThread1), NORMALPRIO, Thread1, NULL);
  // in this demo, main does nothing.
 
  while (true) {
      chThdSleepMilliseconds(100);
  }
}

The makefile too would benefit from some simplifications:

Code: Select all

CHIBIOS=../../..
BOARD=$(CHIBIOS)/boards/stm32/NUCLEO-F072/
APPSRC=main.c
include $(CHIBIOS)/.../rules.mk


This demo should then run on ALL supported boards by just changing the BOARD=... line. Also, note that you can change the board hardware by copying the whole directory into your project directory, and then modifying the board stuff. Again, as little as possible should be in the board directory,

Furthermore, a file like "halconf.h" should be simplified in that it only requires those defines that are actually enabled. In the case of this demo, an empty halconf.h should suffice. (can you disable the Pal driver?) The demonstration halconf.h files might, instead of being super-small, contain things like:

Code: Select all

//#define HAL_USE_EXT                 TRUE


You might add a comment that explains what this does.

Code: Select all

// Enables the driver for the external interrupt module (EXTI).


Comments like:

Code: Select all

/**
 * @brief   Enables the CAN subsystem.
 */

are useless. The "enables the xxx subsystem" is repeated for every enable-something define. After a few repetitions that does not add any information. Similarly the "xxx" is found in "HAL_USE_xxx", so again nothing useful is added by that part of the comment.


When this is in place, the actual user-part of projects contain much less chibios-copied code, that may need to change when chibios is upgraded.

[steved]

The standard advice is then to start with a working demo and modify that. That's a hassle if my project has grown a bit and already has lots of code. Also, "starting over" with the demo and then putting every thing back in is not a fun past-time.

My own practice is to vary this by getting a working demo program on the closest available hardware (something using at least the same processor), then doing a file compare with halconf.h, mcuconf.h, chconf.h and makefile to see what's changed and what needs updating in my project. Sometimes the board config files need the same treatment.

[Giovanni]

Hi,

I think that "starting over" is a bit of an overstatement. There are just the configuration files to consider and that is done easily using a compare tool.

About simplifying halconf.h, it is used to generate documentation, having a custom file for each demo would complicate things, mcuconf.h is highly MCU-specific so cannot be simplified, chconf.h changes only when the kernel changes.

Note that configuration files never change between minor releases. You only need to do those checks when upgrading to a new version, so every 6..12 months or so.

Giovanni

[rew]

Giovanni,
In a project that I started AFTER 3.0 came out, I now have compilation errors. Some ASM sources were renamed from .s to .S, and that required a change in the Makefile.
Some startup files were moved. So that requires a change in the Makefile.

Similarly, I tried "porting" the F103 FATFS demo to my '103. The complexity of everything caused me to spend hours trying to get it to work before I found out that my '103 CPU doesn't have SPI2.

Then I tried porting it to my 072 board. That resulted in lots of problems because of '103 related things in the Makefile. (e.g. armV6 vs armV7 startup files)

If the Makefile could just be BOARD=<someboard> (which has a default CPU) and that I can then add CPU=STM32F103R6 to my Makefile to compile for a different CPU on the same board, then things would have much simpler to try and port this. Then I would have immediately gotten a "your CPU doesn't have SPI2" error. Now I changed the minimal things, knowing the cpu WAS and REMAINED a '103, to make it work. Of course thinking that STM32F103R6 is almost the same as the STM32F103R8 on the board I was cloning is a mistake that can still happen. But with just ONE thing to change, the chance for errors becomes a lot smaller.

Maybe I'm exagerating a bit. But IMHO for the success of Chibios to improve, I think it would be a useful idea to try and put my sample source and sample Makefile in a "demo" subdirectory, and then make it work. At first the Makefile will just include a chibios-rules file that is in that same directory. Then we should try to make another demo work with a very similar "small" makefile, using the same "generic" makefile. Once that works, we can consider integrating it into Chibios.

I might even be persuaded to provide patches. But then you have to be "on board" that they will go into the main Chibios. Of course just changing the makefile, and using diff to figure out the differences is at each point in time faster and easier than in rewriting the whole thing to do it better.....

About "halconf" generating documentation... I honestly do not see the value of documenting

Code: Select all

HAL_USE_SPI enable the HAL SPI module
HAL_USE_DAC enable the HAL DAC module
HAL_USE_UART enable the HAL UART module


etc.

There needs to be an actual documentation there. Something that the code not already says. The classic example is a beginning programmer who documents:

Code: Select all

  i++; // increment i


Granted, for someone doing their first baby steps in the "C" language that might be a reminder for how "increment i" is written in C. But for the most of us the documentation at that level is useless. Similarly to me a lot of chibios documentation is useless. Here HAL_USE_UART tells me exactly the same thing as "enable the HAL UART module". Similarly I scrolled to a random page somewhere in the middle of the HAL documentation. I find:

Code: Select all

static bool sdc_init(SDCDriver *sdcp) [static]
Parameters:
in | sdcp | pointer to the SDCDriver object


What does this document? Reading the prototype, I can see that the function is static. (the "[static]" is redundant), and the rest of the declaration tells me that there is a parameter called sdcp that is a pointer to an SDCDriver object. Again, this is documentation that might remind a "first week of C" programmer as to what that definition does, but it does not help someone with more than a month of C-experience in how to use this function.


About the mcuconf file being CPU dependent, there should be enough defaults to make an empty one work.

That might mean that the "central" mcuconf file does something like:

Code: Select all

#if CPU == STM32F103x6
  #include "mcuconf_103x6.h"
#else
 ...
#endif

And that suitable defautls are used:
[/code]
#if defined (HAL_USE_SPI) AND !defined( MCU_USE_SPI1) && !defined (MCU_USE_SPI2) && ...
#define MCU_USE_SPI1
#endif[/code]This will allow you to turn on SPI and by default it will enable SPI1. If you want to make it explicit, or if you want to use another SPI module, just #define MCU_USE_SPIx in the "small" mcuconf.h file.

Similarly, I would want Chibios to help me find a DMA channel for my module. On STM32F4 I can simply select a channel, but on STM32F0 there is no choice. So, for the rest of CHIBIOS, the not-really-a-choice of the DMA channel on F0 should be somewhere central, and not in MY mcuconf.h. And for F4, a default would be provided that tries to prevent common clashes, but may need configuration by the user if the situation gets complicated.

Try to imagine 10 users using SPI on an F4 discovery board. Which SPI module are they going to use, what DMA channels are they assigning?

[Giovanni]

Hi,

You don't have to be "on board" to submit patches, everything is discussed here and, if approved, merged in the trunk code. Focused changes are likely accepted, broad changes require a very good reason.

About your points regarding comments, probably you are missing that comments inside the code are used to generate documentation. Something that is obvious reading the code could not be so obvious when you are reading a PDF, moreover, the documentation tool complains if some parameter is not commented so what looks redundant to you is just a good practice from my point of view.

Everything is done according to this: http://chibios.org/dokuwiki/doku.php?id ... tyle_guide

About the idea of the "universal demo", it could be nice but out of the usual patterns. Demos are meant to provide minimal template projects, customized header files and inclusions do not make for a good template. There could be a place in the community repository for something like that.

Giovanni

[rew]

The generalized demo is not a goal in itself. The goal is to make things easier for beginners. (and more experienced people like me).

Today I'm bringing up four boards today with different processors. The boards are the same and all have the leds on the same pins. So a "blinky" application is useful to verify that the board+CPU works. (My intern put the components on. It is his first SMD "pick and place" experience).

But a "general blinky" application that is SIMPLE and works "across the board" would be useful. It is the first test that anybody tries when bringing up new hardware. Someone switching from AVR to STM32+chibios, will need to verify compiler / programmer / board. The simpler the software, the less things can go wrong, the better.

My proposition is that the "minimal template" becomes a lot smaller. And easier to port between CPUs. When successful, maybe all the CDC demo projects can be merged. So the readme could say something like: "by default this is configured for the STM32F4discovery board. Change the BOARD definition in the Makefile to select one of the other supported boards: STM32F3discovery, ... ".

Porting this demo to an "unexpected" target should then become much easier. Is there a '042 board with the USB broken out? I suspect not. But changing the CPU definition could be very close to all that is needed to port a "CDC shell only" application.