Usually the compiler saves and restores registers in a function according to the calling convention and, in almost all cases, this is exactly what you want. However, there are some cases where it's just not necessary to save registers on entry to a function as it is a top-level function and will not be called directly from code. The compiler can't easily detect these cases so you can point them out using the __toplevel attribute.

The most common function, main, is a good example of a top-level function: it's only called by the runtime startup code, runs, and usually never terminates in an embedded system. As such, CrossWorks automatically marks main as a top-level function which instructs the code generator not to save and restore registers on entry and exit because their values are not required.

Another good example is top-level task functions when you're using the CrossWorks tasking library; in this case, you can safely declare all your task functions with the top-level attribute because none of their registers are unimportant on entry and exit. Using the top-level attrubute in this way will reduce the stack requirement of the task.

##### Example

    void task1(void *p) __toplevel
    {
      // task code
    }

    void task2(void *p) __toplevel
    {
      // task code
    }

    void main(void)
    {
      ctl_task_run(&task1Task, 1, task1, 0, "task1", sizeof(task1Stack)/sizeof(unsigned), task1Stack);
      ctl_task_run(&task2Task, 1, task2, 0, "task2", sizeof(task2Stack)/sizeof(unsigned), task2Stack);
    }