Newbie - Docs for file and build structure when writing a library driver for FreeRTOS

Libraries
1

Hi all,
I am new to FreeRTOS and working on a hobby project to teach myself some principles.
I have found similar topics in the forum, but can’t really find a good answer. I am looking for docs on writing a library for FreeRTOS that I want to include in my other projects (main programs). The library provides some convenience functions to address serial, I2C, etc through libopencm3 using queues and tasks and stuff. I am building both the library and my project with gnu make. In the future I would also like to add CMock and Unity to my library to test it, and aim making my library a (somewhat) “generic” library that I can just adapt to support all the different boards that are supported by libopencm3 by changing some make variables (by including the right libopencm3 and FreeRTOS port header files).
To get the RTFM answer first (which would be very helpful): are there any guides/docs on this (not a video if possible)? Or just a sample git repository that more or less matches what I am trying to setup would also be really helpful.

More specifically questions I am having trouble with (I can solve all of them probably eventually but I don’t want to loose too much time reinventing the wheel, or going down the wrong path first):

  • including FreeRTOS.h requires a FreeRTOSConfig.h. My projects certainly will have one of course, but my library also needs to #include some FreeRTOS header files (tasks and queues at least). So when building the library, I also need a FreeRTOSConfig.h file in there. But not all projects sharing that library should share the same FreeRTOSConfig.h file. If I have 2 FreeRTOSConfig.h files (one in the lib, one in the actual project/program) won’t the applied config depend on the order of the -I parameters? How is this normally dealt with?
  • Where should I build FreeRTOS itself? Should I let the library also build the FreeRTOS binaries and include them in the archive, so the main program should just link against it, and get FreeRTOS that way? Or would you recommend building FreeRTOS only in the main program, and just make sure the library can find the FreeRTOS header files?
  • Related to the previous: My library will be modular in the sense that with environment variables like USE_SERIAL=1 I want to only build the parts of the library into the archive that are actually needed by the project. But depending on these variables, different parts of FreeRTOS will be required. If I build the FreeRTOS kernel as part of the library, I can control which parts of FreeRTOS to add. But my main program may also have its own additional FreeRTOS requirements, which I would then somehow have to communicate down to the library (through env variables). If on the other hand, I build the FreeRTOS kernel in the main program, how do I let the library communicate back to the main program what FreeRTOS features it needs?

Sorry for the lengthy question. I know I am asking a lot, but since I am new to it, I don’t yet know enough to ask to-the-point easy-to-answer questions. I would be really grateful to anyone willing to take the time to answer or point to some good docs/guides/howtos.
Cheers,

Dolf.

2

The FreeRTOSConfig.h is always supplied by the application and not by the library. The application that is consuming your library should supply the FreeRTOSConfig.h.

I would suggest that let the application build the FreeRTOS. How are you planning to distribute your library? If you planning to open source it, everything can be built from source in the application as you are just going to create one binary.

Since the application supplies the FreeRTOSConfig.h, it controls which parts of FreeRTOS are included. You can generate a compiler error to stop the compilation if the FreeRTOS functionality required by your library is not enabled by the supplied FreeRTOSConfig.h:

#if ( configUSE_MUTEXES == 0 )
    #error Muxtes are required for this library. Please set configUSE_MUTEXES to 1 in FreeRTOSConfig.h.
#endif

Thanks.

3

Hi @aggarg

Thanks for the great answer. Yeah, opensourcing and github was the idea. The compile error is a good idea indeed. I didn’t think of that. I am providing a separate makefile for the library though (I want it to live in its own repo), and compile it as dependency from the application with

mylib: 
    $(MAKE) -C ../lib/mylib
.PHONY mylib
LDLIBS+=-L../lib/mylib -l libmylib
DEPS+=mylib

which will fail since it doesn’t have a FreeRTOSConfig.h in its include path. But I could send the path to the application level FreeRTOSConfig.h to it, so it can find it, and then check if the required stuff is there like this

mylib: 
    FREERTOS_CONFIG_PATH=$(APP_DIR)lib/FreeRTOSConfig.h $(MAKE) -C ../lib/mylib
.PHONY mylib
LDLIBS+=-L../lib/mylib -l mylib
DEPS+=mylib

Does that make sense? Is there no good writeup anywhere about this kind of stuff? If not, maybe I’ll make the writeup and publish it somewhere. I do want to make sure I set things up in a way that makes sense to most people though.

4

Technically, you are going to hit “Undefined Behavior” by having two different FreeRTOSConfig.h files being used when compiling the program. But, as long as when you compile the library, you don’t actually include any of the FreeRTOS modules in the library you should be ok, since I don’t think FreeRTOS uses any inline functions in its headers (since that would break its model of data-hiding).

What I personally do, is build my libraries in a similar manner to FreeRTOS, where rather than having an “object library” that I include, I include the source files into the project, I get around that sort of problem. Since an embedded project is inherently somewhat size limited, the added source files being checked if they need to be compiled isn’t a big time issue, and you can often even make them be a “sub project” which can help that dependency even more.

5

I’d suggest the same. Also, you probably should consider CMake also as we support CMake in FreeRTOS now.