Quality RTOS & Embedded Software

 Real time embedded FreeRTOS RSS feed 
Real time embedded FreeRTOS mailing list 
Quick Start Supported MCUs PDF Books Trace Tools Ecosystem TCP & FAT Training




Loading

Suggestion for future FreeRTOS-versions

Posted by polarlightning on January 17, 2012
I am currently selecting the RTOS for our next products. When looking at FreeRTOS for the first time, the first thing that tells me something is not as well as it could be is the naming conventions used in FreeRTOS. Literals having sequences of lower case characters followed by a sequence of upper case characters is - well, to speak frankly - ugly to my mind . Hierarchical names and some more common naming convention would be better. I suggest that ALL literals and functions names should start with FREERTOS_ or FRTOS_ (literals) or FreeRTOS (functions and variables) even though this "return type encoding in names" would be applied. Now at first sight the lack of logic and making these identifiers not easily recognazible from own or third vendor codes is a little "threat" or big inconvinience. When looking and the available ports and documentation otherwise this looks very promising. If you want just one example of consistent naming, you might take a look at Micrium's uC/OS-II (commercial). I think it might not even be a big task to use some template engine to rename everything. Of course this can be done locally, but it is not as good as having the original code look very logical and very well named.

Good convention to stand out FreeRTOS-related stuff in project suggestion:
- FRTOS__ for literals and
- FRTOS for function, variables, types (applied suitably for each)

Examples:
#define FRTOS_QUEUE_TYPE_BASE (now: queueQUEUE_TYPE_BASE)

xFRTOSQueueAltGenericSend (now: xQueueAltGenericSend)
vFRTOSTaskSuspend (now: vTaskSuspend)

RE: Suggestion for future FreeRTOS-versions

Posted by Richard on January 17, 2012
Thanks for the feedback - it is always appreciated.

There are a few things that would, in hindsight, be changed, but the problem is that the code is now so entrenched in so many different projects that breaking backward compatibility would be a major problem. I have considered having a header file that maps the same API function names prefixed with "FreeRTOS_" to their actually implemented names. That way people could choose which to use. The problem is though, using macros in this manner is inconvenient when editing and debugging - right clicking on a function and selecting "go to definition" and being taken to a macro instead of the actual function definition.

With respect to the existing naming of literals. The capitalisation shows it is a macro or literal (there are exceptions) and the lowercase prefix denotes the name of the file in which the definition is found. Likewise with function names. For example, the "Task" in vTaskDelete() shows the function is defined in task.c, the "queue" in xQueueSendToBack() shows the function is defined in queue.c - so the functions are somewhat identifiable as FreeRTOS functions (likewise macros defined in semphr.h start with "Semaphore").

Regards.

RE: Suggestion for future FreeRTOS-versions

Posted by polarlightning on January 17, 2012
Thank you for the prompt reply!

That's what I guessed. Once some interfaces have gone public and are widely used, it is very difficult to make changes. I also acknowledge, that there is some naming logic.

Well, one option always remains: the FreeRTOS source codes could be modified into template, from which you can still generate the actual source code with old API identifiers currently used and the new generation hierarchical API names. Then these two template outputs would be published separately (or one package could be the template FreeRTOS with the template processor and the data-options for two output targets). In practice this is of course not so feasible - people could start feeling weightless because of all this abstraction :)

RE: Suggestion for future FreeRTOS-versions

Posted by David Brown on January 17, 2012
While there's a lot I don't like about FreeRTOS's conventions (someone seems to have misunderstood the point of Hungarian Notation...), I have seen few conventions more hideous than Micrium's - it is not worthy of copying.

http://www.eetimes.com/design/embedded/4215492/Adopting-C-programming-conventions

The FreeRTOS naming conventions are what they are - it would be very difficult to change them now. If one were starting a new system now, I would expect things to be done somewhat differently. For example, size-specific types would be based on stdint.h types - there would be no "signed char" nonsense in the code. Hungarian notation would be used properly or not at all. And quite possibly the whole thing would have been written in C++ to take advantage of better typing, templates for things like queues, and namespaces.

RE: Suggestion for future FreeRTOS-versions

Posted by Richard on January 17, 2012
“While there's a lot I don't like about FreeRTOS's conventions”


Like I say, with hindsight there are things that would change. I particularly regret calling a header file "list.h", despite its obvious and unambiguous name to content mapping - it is unfortunately obvious to lots of other projects. FreeRTOS_list.h would have been better.

“someone seems to have misunderstood the point of Hungarian Notation...”


Interesting statement, I'm not exactly sure what you mean and could read it one of two ways. Maybe you could elaborate.

I can't pretend to know exactly what a specific definition of Hungarian Notation is, if there is one. The FreeRTOS code has a convention that I made up myself at the beginning of my career, and have used ever since. It prefixes with type, but not to any documented standard as such. The FreeRTOS convention itself is document on the FreeRTOS.org site however.

Not to confuse coding standard with style guide too much, although there is a blur, FreeRTOS has extremely rigorous enforcement of both. Layout, variable and function naming (verbose, with no abbreviation, etc. etc.), MISRA rule compliance (not quite there yet, but very close in the core code), etc make people hate doing work for me because I am never satisfied ;o)

“The FreeRTOS naming conventions are what they are - it would be very difficult to change them now”


Yes, people would dislike it more if they were changed, than if they stayed the same.

“ For example, size-specific types would be based on stdint.h types”


Watch this space!

“there would be no "signed char" nonsense in the code”


Two reasons for that.

1) Portability. Different compilers default char to be different.
2) Coding standard. Thow shalt not using unqualified char types (see point 1).

Even then it is a pain, because standard library functions for different compilers expect signed or unsigned depending on the supplier. Therefore you sometimes have to cast to unqualified char in library functions to ensure there is no warning generated on all the 17 tool chains the code is compiled with.

“possibly the whole thing would have been written in C++”


Absolutely not - I disagree with you on that one. C++ can include C code, but the opposite is not true. Many compilers FreeRTOS is used with, especially on smaller microcontrollers, have limited or no C++ support. Templates on a PIC18 - eek.


Referring back to the original post - I have a new product coming out very soon (just documenting it now) that has FreeRTOS_ on the start of every API name (although it is not an extension to FreeRTOS, it does make use of FreeRTOS itself), and using stdint types throughout.

Regards.


RE: Suggestion for future FreeRTOS-versions

Posted by David Brown on January 17, 2012
Regarding Hungarian Notation - the original idea was for what is now termed "Application Hungarian Notation", in which prefixes were used to distinguish the usage of variables. A typical example of this is to use "ssName" and "usName" to distinguish between the "safe string" version of "Name" and the "unsafe string" version of "Name" - perhaps to ensure that input data has a suitable length, no awkward characters, no sql injection attacks, etc. The point is that these are the same types (char*, char[], string class, whatever) so the compiler can't help you spot mistakes - the naming convention helps you avoid passing unsafe strings to functions that assume their argument is safe. In the context of FreeRTOS, it might be used to distinguish between different uses of "void *" pointers - instead of calling them "pvXXX", you call some "pparamsXXX", and some "pownerXXX", etc.

What you use in FreeRTOS is know as "Systems Hungarian Notation", where the letters represent types of data or return types of functions. A little of this can be very useful - it is very common to have "pXXX" for pointers and perhaps "fXXX" for function pointers. Another useful convention is an "s" suffix on arrays or similar structures. But the idea of embedding type information as prefix letters based on a complete misunderstanding of Simonyi's original paper, and is mostly considered poor style. Any program or library that makes decent use of types is going to have too many to be able to express well in this manner - the code quickly becomes unreadable or at least unwriteable, and unmaintainable if things change. It doesn't add any information that the compiler doesn't already know and check, and any decent programmer's editor makes it quick and easy for the programmer to find out types. So you are duplicating existing information in a non-standard and inconsistent way, which is never a good idea.

Having said that, it is worth remembering that opinions on these things change over time, both through fashion and better tools and styles - when FreeRTOS was started, expert opinion on Systems Hungarian Notation was much higher than it is now. So while I say that it would be wrong to use it for a new system, I don't mean to criticize the original decision when FreeRTOS was started.


Regarding "signed char" - a "char" is a character or letter, and it doesn't make sense for a letter to be signed or unsigned. It doesn't make sense to use a letter variable to hold numeric data. If you want a small integer, use types "uint8_t" or "int8_t", because they have names that match the use you intended. Because of limitations of C, the underlying type of "int8_t" will normally (but not necessarily) be "signed char" - but you should insulate your code from that sort of thing. Also, you should not have something like "unsigned portBASE_TYPE" - "portBASE_TYPE" should be declared as signed or unsigned as necessary in the type definition. And you should not use something like "unsigned long" in portable code - if you don't want to specifically fix the size with uint32_t, use "uint_fast16_t" or similar.

So a better rule is "thou shalt use unqualified char types - because if the signedness matters, you should use a stdint.h type".


Regarding C++ - it's a choice to consider. For something like an RTOS here, there is a great deal to be gained by using C++ and writing in an object-oriented style. Quite clearly there is a loss of portability to some platforms, especially the smallest and most limited. It is also not uncommon for toolchain vendors to charge differently for C++ tools rather than C tools. So it would be a question of balancing the benefits of C++ with the costs for your target users.

Incidentally, templates are a very misunderstood part of C++. Badly used templates can lead to bloated code, especially with older C++ compilers. Well used templates can lead to smaller and faster code than you get with generic C functions, as well as being safer to use.




RE: Suggestion for future FreeRTOS-versions

Posted by Richard Damon on January 18, 2012
I will agree with Richard Barry on NOT wanting FreeRTOS to be changed to be C++ based. A number of the enviroments I use it in do NOT have good cheep/free C++ compilers, but do have suitable C compilers. FreeRTOS is perfectly usable in C++ code, as I do that too in enviroments where I have access to a C++ compiler . I do have some simple wrappers for C++ which I do need to find the time to get cleaned up enough to make a submission.

I do agree that things that represent character strings, and are expected to normally be provided as quoted strings SHOULD be of type char* not signed char*. The portability rule of not using unqualified char should be "Do not use unqualified char for variables on which you will do arithmetic, i.e. when using the char type as a short-short", most of it uses for signed char* should actually be const char* since FreeRTOS will not change the strings passed to it.

RE: Suggestion for future FreeRTOS-versions

Posted by David Brown on January 18, 2012

I will agree with Richard Barry on NOT wanting FreeRTOS to be changed to be C++ based. A number of the enviroments I use it in do NOT have good cheep/free C++ compilers, but do have suitable C compilers. FreeRTOS is perfectly usable in C++ code, as I do that too in enviroments where I have access to a C++ compiler . I do have some simple wrappers for C++ which I do need to find the time to get cleaned up enough to make a submission.


I am definitely not saying that FreeRTOS should be changed to C++. What I am saying is that were one starting a similar project today, C++ should be under consideration. It has a lot of advantages - but also several disadvantages (of which free/cheap compiler support, especially for small devices, is the main issue).



I do agree that things that represent character strings, and are expected to normally be provided as quoted strings SHOULD be of type char* not signed char*. The portability rule of not using unqualified char should be "Do not use unqualified char for variables on which you will do arithmetic, i.e. when using the char type as a short-short", most of it uses for signed char* should actually be const char* since FreeRTOS will not change the strings passed to it.


I go further and say that "char" - signed, unsigned or (even worse) unqualified should not be used for arithmetic. This should simply not ever appear in user code, or even in systems like FreeRTOS. Standard C has had perfectly good 8-bit arithmetic types for a decade or so in - they are always a better choice. There are no exceptions here - if you are stuck with a brain-dead compiler from the dark ages, write your own compatible and use it.

RE: Suggestion for future FreeRTOS-versions

Posted by Richard Damon on January 18, 2012
FreeRTOS as currently written works very well with C++, just needing a thing wrapper. One small improvement would be to change the data hiding method to allow the wrapper to derive from the FreeRTOS structures rather than containing a handle, this is a small nit. The one big issue is that FreeRTOS queues can only store classes with trivial copy constructors (since it uses memcpy). With a bit of refactoring, I think it would be possible to have FreeRTOS provide some primitives to allow you to define a template based queue allowing them to hold any copyable/movable type.

As for , the one issue I have with it is that int8_t is the wrong type. As defined, portable code should NOT use it, as it is not gaurenteed to exist (but it is the family of types most apt to be used), as it requires and EXACT sized type. By definition int_least8_t will be signed char (or a type with equivalent properties).

RE: Suggestion for future FreeRTOS-versions

Posted by David Brown on January 18, 2012
“As for , the one issue I have with it is that int8_t is the wrong type. As defined, portable code should NOT use it, as it is not gaurenteed to exist (but it is the family of types most apt to be used), as it requires and EXACT sized type. By definition int_least8_t will be signed char (or a type with equivalent properties). ”


Types such as int_least8_t and int_fast8_t are often underused. If portability is vital, even on painful cpu's which cannot address 8-bit data, then I agree that these are a better choice. int_fast8_t is typically best for local data - it is the type that has at least 8 bits, and is fastest for the cpu in question (and is thus often 32-bit on 32-bit cpus), while int_least8_t is typically best for stored data (being the smallest type with at least 8 bits). Often int8_t (being an exact size type) is not actually the best choice, though it is commonly used (being shorter, clearer and more specific than the others).

Whichever you choose, all of them are better than "char" - signed, unsigned or unqualified - when you want an arithmetic type.


[ Back to the top ]    [ About FreeRTOS ]    [ Sitemap ]    [ ]




Copyright (C) 2004-2010 Richard Barry. Copyright (C) 2010-2016 Real Time Engineers Ltd.
Any and all data, files, source code, html content and documentation included in the FreeRTOSTM distribution or available on this site are the exclusive property of Real Time Engineers Ltd.. See the files license.txt (included in the distribution) and this copyright notice for more information. FreeRTOSTM and FreeRTOS.orgTM are trade marks of Real Time Engineers Ltd.

Latest News:

FreeRTOS V9.0.0 is now available for download.


Free TCP/IP and file system demos for the RTOS


Sponsored Links

⇓ Now With No Code Size Limit! ⇓
⇑ Free Download Without Registering ⇑


FreeRTOS Partners

ARM Connected RTOS partner for all ARM microcontroller cores

Renesas Electronics Gold Alliance RTOS Partner.jpg

Microchip Premier RTOS Partner

RTOS partner of NXP for all NXP ARM microcontrollers

Atmel RTOS partner supporting ARM Cortex-M3 and AVR32 microcontrollers

STMicro RTOS partner supporting ARM7, ARM Cortex-M3, ARM Cortex-M4 and ARM Cortex-M0

Xilinx Microblaze and Zynq partner

Silicon Labs low power RTOS partner

Altera RTOS partner for Nios II and Cortex-A9 SoC

Freescale Alliance RTOS Member supporting ARM and ColdFire microcontrollers

Infineon ARM Cortex-M microcontrollers

Texas Instruments MCU Developer Network RTOS partner for ARM and MSP430 microcontrollers

Cypress RTOS partner supporting ARM Cortex-M3

Fujitsu RTOS partner supporting ARM Cortex-M3 and FM3

Microsemi (previously Actel) RTOS partner supporting ARM Cortex-M3

Atollic Partner

IAR Partner

Keil ARM Partner

Embedded Artists