In my previous post  I mentioned the Drivers\Common folder which has ‘include’ files. These files are maintained automatically by the Component Wizard. But what is the purpose of these files?

The Common Folder has *.inc files which are included in the driver as ‘function’ header. The .inc file contains documentation about the function and parameters for that function.

In the example below I have a method named xTaskCreate(). This method has a list of parameters, plus ‘hints’ which is the documentation part:

Task Create Method

When I create/change that method in the wizard, it will automatically create/update the .inc file for it in the Drivers\Common folder.

In the driver code it will as well add an %include to include that file:

The file Common\FreeRTOSxTaskCreate.Inc has the following content:

%- AUTOREGENERATE If you remove this line, this file cannot be rewrited (by default)
%ifndef CommentLine
%{
%endif CommentLine
%;** ===================================================================
%include Common\GeneralMethod.inc (xTaskCreate)
%;**     Description :
%;**         Create a new task and add it to the list of tasks that are
%;**         ready to run.
%include Common\GeneralParameters.inc(27)
%;**         pvTaskCode%ParpvTaskCode %>27 - Pointer to the task entry
%;** %>29 function. Tasks must be implemented to
%;** %>29 never return (i.e. continuous loop).
%;**         pcName%ParpcName %>27 - A descriptive name for the task.
%;** %>29 This is mainly used to facilitate debugging.
%;** %>29 Max length defined by
%;** %>29 configMAX_TASK_NAME_LEN.
%;**         usStackDepth%ParusStackDepth %>27 - The size of the task
%;** %>29 stack specified as the number of variables
%;** %>29 the stack can hold - not the number of
%;** %>29 bytes. For example, if the stack is 16 bits
%;** %>29 wide and usStackDepth is defined as 100,
%;** %>29 200 bytes will be allocated for stack
%;** %>29 storage. The stack depth multiplied by the
%;** %>29 stack width must not exceed the maximum
%;** %>29 value that can be contained in a variable
%;** %>29 of type size_t.
%;**         pvParameters%ParpvParameters %>27 - Pointer that will be
%;** %>29 used as the parameter for the task being
%;** %>29 created.
%;**         uxPriority%ParuxPriority %>27 - The priority at which the
%;** %>29 task should run.
%;**         pvCreatedTask%ParpvCreatedTask %>27 - Used to pass back a
%;** %>29 handle by which the created task can be
%;** %>29 referenced.
%;**     Returns     :
%;**         ---%RetVal %>27 - pdPASS if the task was successfully
%;** %>29 created and added to a ready list,
%;** %>29 otherwise an error code defined in the file
%;** %>29 projdefs.h
%include Common\GeneralDamage.inc
%;** ===================================================================
%ifndef CommentLine
%}
%endif CommentLine

Then it will look like this in my generated code:

/*
** ===================================================================
**     Method      :  FRTOS1_xTaskCreate (component FreeRTOS)
**
**     Description :
**         Create a new task and add it to the list of tasks that are
**         ready to run.
**     Parameters  :
**         NAME            - DESCRIPTION
**         pvTaskCode      - Pointer to the task entry
**                           function. Tasks must be implemented to
**                           never return (i.e. continuous loop).
**         pcName          - A descriptive name for the task.
**                           This is mainly used to facilitate debugging.
**                           Max length defined by
**                           configMAX_TASK_NAME_LEN.
**         usStackDepth    - The size of the task
**                           stack specified as the number of variables
**                           the stack can hold - not the number of
**                           bytes. For example, if the stack is 16 bits
**                           wide and usStackDepth is defined as 100,
**                           200 bytes will be allocated for stack
**                           storage. The stack depth multiplied by the
**                           stack width must not exceed the maximum
**                           value that can be contained in a variable
**                           of type size_t.
**         pvParameters    - Pointer that will be
**                           used as the parameter for the task being
**                           created.
**         uxPriority      - The priority at which the
**                           task should run.
**         pvCreatedTask   - Used to pass back a
**                           handle by which the created task can be
**                           referenced.
**     Returns     :
**         ---             - pdPASS if the task was successfully
**                           created and added to a ready list,
**                           otherwise an error code defined in the file
**                           projdefs.h
** ===================================================================
*/
/*
portBASE_TYPE FRTOS1_xTaskCreate(pdTASK_CODE pvTaskCode, const portCHAR * const pcName, unsigned portSHORT usStackDepth, void *pvParameters, unsigned portBASE_TYPE uxPriority, xTaskHandle *pvCreatedTask)
{
*** Implemented as macro in the header file FRTOS1.h
}
*/

Happy Hacking 🙂