You may be used to running programs that are stored in files on Linux or Windows.  If you transition to using NuttX tasks on an MCU with limited resources, you will encounter some behavioral differences. This Wiki page will summarize a few of those differences.

NuttX Build Types

NuttX can be built in several different ways:

  • Kernel Build. The kernal build, selected with CONFIG_BUILD_KERNEL, uses the MCU's Memory Management Unit (MMU) to implement processes very similar to Linux processes. There is no interesting discussion here; NuttX behaves very much like Linux.
  • Flat Build. Most resource-limited MCUs have no MMU and the code is built as a blob that runs in an unprotected, flat address space out of on-chip FLASH memory. This build mode is selected with CONFIG_BUILD_FLAT and is, by far, the most common way that people build NuttX. This is the interesting case to which this Wiki page is directed.
  • Protected Build. Another build option is the protected build. This is essentially the same as the flat build, but uses the MCU's Memory Protection Unit (MPU) to separate unproctect user address ranges from protected system address ranges. The comments of this Wiki page also apply in this case.

Initialization of Global Variables

Linux Behavior

If you are used to writing programs for Linux, then one thing you will notice is that global variables are initialized only once when the system powers up. For example. Consider this tiny program:

  bool test = true;

  int main(int argc, char **argv)
  {
    printf("test: %i\n", test);
    test = false;
    printf("test: %i\n", test);
    return 0;
  }

If you build and run this program under Linux, you will always see this output:

  test: 1
  test: 0

In this case, the global variables are re-initialized each time that you load the file into memory and run it.

NuttX Flat-Build Behavior

But if you build this program into on-chip FLASH and start it as a task (via, say, task_start()) you will see this the first time that you run the program:

  test: 1
  test: 0

But after that, you will always see:

  test: 0
  test: 0

The test variable was initialized to true (1) only once at power up, but reset to false (0) each time that the program runs.

If you want the same behavior when the program is built into the common FLASH blob, then you will have modify the code so that global variables are explicitly reset each time the program runs like:

  bool test;
    
  int main(int argc, char **argv)
  {
    test = true;
    printf("test: %i\n", test);
    test = false;
    printf("test: %i\n", test);
    return 0;
  }

NuttX Load-able Programs

If you load programs from an file into RAM and execute them, as Linux does, then NuttX will again behave like Linux. Because the flat build NuttX works the same way:  When you execute a NuttX ELF or NxFLAT module in a file, the file is copied into RAM and the global variables are initialized before the program runs.

But code that is built into FLASH works differently.  There is only one set of global variables:  All of the global variables for the blob that is the monolithic FLASH image.  They are all initialized  once at power-up reset.

This is one of the things that makes porting Linux applications into the FLASH blob more complex.  You have to manually initialize each global variable in the main() each time your start the task.

Global Variables and Multiple Task Copies

It is better to avoid the use of global variables in the flat build context whenever possible because that usage adds another limitation:  No more that one copy of the program can run at any given time.  That is because the global variables are shared by each instance (unlike, again, running a program from a file where there is a private copy of each global variable).

One way to support multiple copies of an in-FLASH program is to move all global variables into a structure. If the amount of memory need for global variables is small, then each main() could simply allocate a copy of that structure on the stack. In the simple example above, this might be:

struct my_globals_s
{
  bool test;
}

int main(int argc, char **argv)
{
  struct my_globals_s my_globals = { true };

  printf("test: %i\n", my_globals.test);
  my_globals.test = false;
  printf("test: %i\n", my_globals.test);
  return EXIT_SUCCESS;
}

A pointer to the structure containing the allocated global variables would then have to passed as a parameter to every internal function that needs access to the global variables. So you would change a internal function like:

  static void print_value(void)
  {
    printf("test: %i\n", test);
  }

to

  static void print_value(FAR struct my_globals_s *globals)
  {
    printf("test: %i\n", globals->test);
  }

Then pass a reference to the allocated global data structure each time that the function is called like:

  print_value(&my_globals);

If the size of the global variable structure is large, then allocating the instance on the stack might not be such a good idea. In that case, it might be better to allocate the global variable structure using malloc(). But don't forget to free() the allocated variable structure before exiting! (See the following Memory Clean-Up discussion).

struct my_globals_s
{
  bool test;
}

int main(int argc, char **argv)
{
  FAR struct my_globals_s *my_globals;

  my_globals = (FAR struct my_globals_s *)malloc(sizeof(struct my_globals_s));
  if (my_globals = NULL)
    {
      fprintf(stderr, "ERROR: Failed to allocate state structure\n");
      return EXIT_FAILURE;
    }

  my_globals=>test = true;
  printf("test: %i\n", my_globals->test);
  my_globals=>test = false;
  printf("test: %i\n", my_globals->test);

  free(my_globals);
  return EXIT_SUCCESS;
}

Memory Clean-Up

Linux Process Exit

Another, unrelated thing that makes porting Linux programs into the FLASH blob is the memory clean-up.  When a Linux process exits, its entire address environment is destroyed including all of allocated memory. This tiny program will not leak memory if implemented as a Linux process:

  int main(int argc, char **argv)
  {
    char *buffer = malloc(1024);
    ... do stuff with buffer ...
    return 0;
  }

That same program, if ported into the FLASH blob will now have memory leaks because there is no automatic clean-up of allocated memory when the task exits. Instead, you must explicitly clean up all allocated memory by freeing it:

  int main(int argc, char **argv)
  {
    char *buffer = malloc(1024);
    ... do stuff with buffer ...
    free(buffer);
    return 0;
  }

The memory clean-up with the Linux process exits is a consequent of the teardown of the process address environment when the process terminates. Each process contains its own heap; when the process address environment is torndown, that process heap is returned to the OS page allocator. So the memory clean-up basically comes for free.

NuttX Task Exit

But when you run a task in the monolithic, on-chip FLASH blob, you share the same heap with all other tasks. There is no magic clean-up that can find and free your tasks's allocations within the common heap (see "Ways to Free Memory on Task Exit")

NuttX Process Exit

NOTE that when you run processes on NuttX (with CONFIG_BUILD_KERNEL), NuttX also behaves the same way as Linux:  The address environment is destroyed with the task exits and all of the memory is reclaimed.  But all other cases will leak memory.

Ways to Free Memory on Task Exit

There are ways that you could associate allocated memory with a task so that it could cleaned up when the task exits. That approach has been rejected, however, because (1) it could not be done reliably, and (2) it would add a memory allocation overhead that would not be acceptable in context where memory is constrained. Below is the full text from the top-level TODO list coped on 2016-08-15:

Title:       FREE MEMORY ON TASK EXIT
Description: Add an option to free all memory allocated by a task when the
             task exits. This is probably not be worth the overhead for a
             deeply embedded system.
  
             There would be complexities with this implementation as well
             because often one task allocates memory and then passes the
             memory to another:  The task that "owns" the memory may not
             be the same as the task that allocated the memory.
  
             Update.  From the NuttX forum:
             ...there is a good reason why task A should never delete task B.
             That is because you will strand memory resources. Another feature
             lacking in most flat address space RTOSs is automatic memory
             clean-up when a task exits.
  
             That behavior just comes for free in a process-based OS like Linux:
             Each process has its own heap and when you tear down the process
             environment, you naturally destroy the heap too.
  
             But RTOSs have only a single, shared heap. I have spent some time
             thinking about how you could clean up memory required by a task
             when a task exits. It is not so simple. It is not as simple as
             just keeping memory allocated by a thread in a list then freeing
             the list of allocations when the task exists.
  
             It is not that simple because you don't know how the memory is
             being used. For example, if task A allocates memory that is used
             by task B, then when task A exits, you would not want to free that
             memory needed by task B. In a process-based system, you would
             have to explicitly map shared memory (with reference counting) in
             order to share memory. So the life of shared memory in that
             environment is easily managed.
  
             I have thought that the way that this could be solved in NuttX
             would be: (1) add links and reference counts to all memory allocated
             by a thread. This would increase the memory allocation overhead!
             (2) Keep the list head in the TCB, and (3) extend mmap() and munmap()
             to include the shared memory operations (which would only manage
             the reference counting and the life of the allocation).
  
             Then what about pthreads? Memory should not be freed until the last
             pthread in the group exists. That could be done with an additional
             reference count on the whole allocated memory list (just as streams
             and file descriptors are now shared and persist until the last
             pthread exits).
  
             I think that would work but to me is very unattractive and
             inconsistent with the NuttX "small footprint" objective. ...
  
             Other issues:
             - Memory free time would go up because you would have to remove
               the memory from that list in free().
             - There are special cases inside the RTOS itself.  For example,
               if task A creates task B, then initial memory allocations for
               task B are created by task A.  Some special allocators would
               be required to keep this memory on the correct list (or on
               no list at all).
  
             Updated 2016-06-25:
             For processors with an MMU (Memory Management Unit), NuttX can be
             built in a kernel mode.  In that case, each process will have a
             local copy of its heap (filled with sbrk()) and when the process
             exits, its local heap will be destroyed and the underlying page
             memory is recovered.
  
             So in this case, NuttX work just link Linux or or *nix systems:
             All memory allocated by processes or threads in processes will
             be recovered when the process exists.
  
             But not for the flat memory build.  In that case, the issues
             above do apply.  There is no safe way to recover the memory in
             that case (and even if there were, the additional overhead would
             not be acceptable on most platforms).
  
             This does not prohibit anyone from creating a wrapper for malloc()
             and an atexit() callback that frees memory on task exit.  People
             are free and, in fact, encouraged, to do that.  However, since
             it is inherently unsafe, I would never incorporate anything
             like that into NuttX.
  
Status:      Open.  No changes are planned.
Priority:    Medium/Low, a good feature to prevent memory leaks but would
             have negative impact on memory usage and code size.
  • No labels