.. _microkernel_apps: How to Develop Microkernel Applications ####################################### Microkernel applications are comprised of .c and . h files that are integrated with the |codename| using MDEF files, Makefiles and .conf files. Developing a microkernel application can be accomplished in five steps: #. Plan your application and take note of all microkernel objects it will need. #. Create the MDEF file for those microkernel objects. #. Code the application source files. #. Create the Makefiles to add the application's source files to the kernel's build system. #. Compile and test your application. The following procedures explain how to accomplish this using examples. Before Starting the Development of a Microkernel App **************************************************** Before you begin, read the :ref:`overview` and the :ref:`quick_start`. Then read the :ref:`collaboration_guidelines`. Finally, review the developers information contained in :ref:`developing_zephyr` and build a sample application, like :file:`hello.c`. Once you have completed those tasks, you should be able to answer: * How does the |codename| and its key objects work? * What is the difference between a nanokernel and a microkernel? * How is the |codename| built? * What rules and conventions must the development follow? If you are able to answer this questions, you can start developing your application. Creating an MDEF File ********************* The :abbr:`MDEF (Microkernel DEfinitions File)` contains the configuration entries for the kernel's objects. Therefore, it must include all microkernel objects used in the C code of the application. Each line in a MDEF file defines one item, unless it is empty or a comment line. All lines starting with a ``%`` are comments. The contents of an MDEF file can be, for example: .. code-block:: console :lineos: % TASKGROUP NAME % ======================= TASKGROUP ITERATIONS % TASK NAME PRIO ENTRY STACK GROUPS % ======================================================== TASK MASTER 7 master 1024 [EXE] TASK PLOTTER 5 plotter 1024 [EXE] TASK TASK10 6 task 2048 [ITERATIONS] TASK TASK11 6 task 2048 [ITERATIONS] TASK TASK12 6 task 2048 [ITERATIONS] TASK TASK13 6 task 2048 [ITERATIONS] % FIFO NAME DEPTH WIDTH % ============================= FIFO PLOTQ 200 20 FIFO COORDQ 16 16 FIFO SCREENQ 16 20 % SEMA NAME % ============= SEMA FINISHED % MUTEX NAME % ===================== MUTEX PRINT MUTEX GRAPH MUTEX POPPARAM MUTEX PUSHPARAM Each object must follow a specific syntax. The name of an object must be an alphanumeric, with an alphabetical first character. Upper- and lowercase letters are allowed, but embedded spaces are not. The convention is to give each object a name that is in all uppercase letters. This makes it easy to distinguish between object names and variable names. Finally, all names must be unique. A pipe cannot have the same name as a FIFO, even though they are different types. See :ref:`microkernel` for the correct syntax for the most important microkernel objects. Coding the Application's Source Files ************************************* We recommend you follow the project's :ref:`coding_style` when coding your application. The required MDEF file can be in any folder of your application as long as the path is referenced in the application's Makefile. The application's root folder must contain a Makefile that links the application to the kernel, see :ref:`root_makefile` for details. Each folder in your source tree needs to have a Makefile that links the folder's contents with the rest of your source tree, see :ref:`source_makefile` for details. Finally, remember that your application will be compiled into the kernel. If all MDEF files and Makefiles are correct and in place, the build system links your application with the kernel. The kernel delivers binaries, one for each selected platform, for testing. .. _app_makefile: Creating the Makefiles for the Application ****************************************** This section explains how the Makefiles within the folders of your application link it to the kernel. The build system's will assume that there is an application's root folder with a :file:`src` folder containing all source files. The name of the folder can be changed to whatever name suits your needs. The :file:`src` folder can have as many subfolders as needed but all folders must contain a Makefile. The contents of the Makefiles can fit the needs of your application. However, some contents are required for a successful integration. The contents required in the application's Makefile at the main folder differ from those required in the Makefiles inside the source folders. For the detailed information regarding the build system's Makefiles see: :ref:`kbuild_makefiles`. .. _root_makefile: The Application's Root Folder Makefile ====================================== The Makefile in the application's root folder must contain at least these entries: * :makevar:`MDEF_FILE`: The name of the the application's MDEF file. * :makevar:`KERNEL_TYPE`: Either `nano` for nanokernel applications or `micro` for microkernel applications. * :makevar:`PLATFORM_CONFIG`: The name of the platform configuration that will be used as a default. * :makevar:`CONF_FILE`: The name of the .conf file or files of the application. * ``include ${ZEPHYR_BASE}/Makefile.inc`` This instruction adds the contents of the :file:`Makefile.inc` found in the kernel's root folder. For all the information regarding the Makefile variables see: :ref:`kbuild_project`. Examples -------- The following example shows a generic application's root folder Makefile: .. code-block:: make :linenos: :emphasize-lines: 4, 6 MDEF_FILE = application.mdef KERNEL_TYPE = micro PLATFORM_CONFIG ?= basic_atom CONF_FILE = application_$(ARCH).conf include ${ZEPHYR_BASE}/Makefile.inc Line 4 shows how to conditionally add files. The build system replaces the variable ``$(ARCH)`` for each supported architecture. The entry in line 6 includes all the entries located in :file:`Makefile.inc` at the kernel's root folder. The entries let the build system know, that your application has to be included as part of the build. The next example comes from the kernel's code, specifically from :file:`samples/microkernel/apps/hello_world/Makefile`: .. literalinclude:: ../../samples/microkernel/apps/hello_world/Makefile :language: make :lines: 1-6 :emphasize-lines: 1, 4 :linenos: The file :file:`proj.mdef` from line 1 can be found in :file:`microkernel/apps/hello_world/` and contains the configuration entries of all microkernel objects used in the application. For more information regarding MDEF files see, the :ref:`microkernel` documentation. The entry in line 4 references the files :file:`proj_arm.conf` and :file:`proj_x86.conf` also found at that location. Those files include the configuration values that differ from the default. For more information regarding these configuration snippets see: :ref:`configuration_snippets`. The Application's Source Folders Makefiles ========================================== The Makefiles in the source folders add the files within the folders to the build system. All information about adding source files and directories to your project can be found in :ref:`makefile_conventions`. Examples -------- Example 1 shows the source folder Makefile of the microkernel Hello World application. Example 1: .. literalinclude:: ../../samples/microkernel/apps/hello_world/src/Makefile :language: make :lines: 1-4 :emphasize-lines: 1, 3 :linenos: Line 1 allows the application's source file access to the functions included in the project's .h files. Line 3 adds the :file:`hello.c` to the build system. Example 2 shows the source folder Makefile of the microkernel Philosophers application. Example 2: .. literalinclude:: ../../samples/microkernel/apps/philosophers/src/Makefile :language: make :lines: 1-4 :emphasize-lines: 3 :linenos: Line 3 adds the :file:`phil_fiber.c` and :file:`phil_task.c` files. Multiple files can be added on a single line by separating them with a space.