From 7567c979ddfd1cfb4e9bfd6c82e97ca47eb7958b Mon Sep 17 00:00:00 2001 From: Allan Stephens Date: Fri, 28 Oct 2016 15:06:44 -0500 Subject: [PATCH] unified/doc: Update Application Development Primer Removes references to nanokernel/microkernel. Corrects numerous errors in content. Improves consistency in presentation of information. Change-Id: I83895d2cb03181da377b23323afc104ae32865a2 Signed-off-by: Allan Stephens --- doc/application/application.rst | 23 ++- doc/application/apps_build.rst | 135 ++++++++------ doc/application/apps_code_dev.rst | 203 +++++++++------------ doc/application/apps_common_procedures.rst | 2 +- doc/application/apps_dev_process.rst | 58 ------ doc/application/apps_kernel_conf.rst | 122 ++++++------- doc/application/apps_object_conf.rst | 96 ---------- doc/application/apps_overview.rst | 34 ++-- doc/application/apps_run.rst | 59 +++--- doc/application/apps_structure.rst | 94 +++------- 10 files changed, 319 insertions(+), 507 deletions(-) delete mode 100644 doc/application/apps_dev_process.rst delete mode 100644 doc/application/apps_object_conf.rst diff --git a/doc/application/application.rst b/doc/application/application.rst index f054aa039dd..1f29fbdbf2b 100644 --- a/doc/application/application.rst +++ b/doc/application/application.rst @@ -3,29 +3,38 @@ Application Development Primer ############################## -This section contains references that explain how to build microkernel -and nanokernel applications. +This section outlines how to create, build, and run a Zephyr application. Audience -------- -Although anybody may use this primer to learn how to build microkernel and -nanokernel applications, the primary audience for this guide is: +Although anybody may use this primer, the primary audience for this guide is: * Application developers coding an application. * System architects learning key functionality and usage. -These subsections explain the entire build process in more detail: +Before You Start +---------------- + +* Check that your Linux host meets the minimum requirements specified in the + :ref:`getting_started`. + +* Check that environment variables have been configured correctly as outlined + in :ref:`apps_common_procedures`. + +Workflow +-------- + +The following sections explain the application development process +from start to finish. .. toctree:: :maxdepth: 1 apps_overview - apps_dev_process apps_structure apps_kernel_conf - apps_object_conf apps_code_dev apps_build apps_run diff --git a/doc/application/apps_build.rst b/doc/application/apps_build.rst index e21b7680627..c4cdef40bdf 100644 --- a/doc/application/apps_build.rst +++ b/doc/application/apps_build.rst @@ -3,84 +3,115 @@ Build an Application #################### -The build process unifies all components of the application into -a coherent application image that can be run on both simulated and real -hardware targets. +The Zephyr build system compiles and links all components of an application +into a single application image that can be run on simulated hardware or real +hardware. -.. _building_base: +.. contents:: Procedures + :local: + :depth: 1 -Building a Base Application -=========================== +Building an Application +======================= -Build a base application image to test functionality in a simulated -environment and to ultimately run on your hardware target. Before -building, keep in mind the following: +The build system allows you to easily build an application using the +application's existing configuration. However, you can also build it +using different configuration settings, if desired. -* Each source code directory and sub-directory needs a directory-specific - :file:`Makefile`. +Before you begin +---------------- -* The :envvar:`$(ZEPHYR_BASE)` environment variable must be set for each - console terminal as outlined in :ref:`apps_common_procedures`. +* Ensure you have added all application-specific code to the application + directory, as described in :ref:`apps_code_dev`. Ensure each source code + directory and sub-directory has its own :file:`Makefile`. -To build the image, navigate to the :file:`~/appDir`. From here you can -build an image for a single target with :command:`make`. +* Ensure you have configured the application's kernel, as described + in :ref:`apps_kernel_conf`. +* Ensure the Zephyr environment variables are set for each console terminal; + see :ref:`apps_common_procedures`. -.. _developing_app: +Steps +----- -Developing the Application -========================== +#. Navigate to the application directory :file:`~/appDir`. -The app development process works best when changes are continually tested. -Frequently rebuilding with :command:`make` makes debugging less painful -as your application becomes more complex. It's usually a good idea to -rebuild and test after any major changes to source files, Makefiles, -.conf, or .mdef. +#. Enter the following command to build the application's :file:`zephyr.elf` + image using the configuration settings for the board type specified + in the application's :file:`Makefile`. + + .. code-block:: console + + $ make + + If desired, you can build the application using the configuration settings + specified in an alternate :file:`.conf` file using the :code:`CONF_FILE` + parameter. These settings will override the settings in the application's + :file:`.config` file or its default :file:`.conf` file. For example: + + .. code-block:: console + + $ make CONF_FILE=prj.alternate.conf + + If desired, you can build the application for a different board type + than the one specified in the application's :file:`Makefile` + using the :code:`BOARD` parameter. For example: + + .. code-block:: console + + $ make BOARD=arduino_101 + + Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified + when building the application. + +Rebuilding an Application +========================= + +Application development is usually fastest when changes are continually tested. +Frequently rebuilding your application makes debugging less painful +as the application becomes more complex. It's usually a good idea to +rebuild and test after any major changes to the application's source files, +Makefiles, or configuration settings. .. important:: - The Zephyr build system rebuilds only the parts of the application image - potentially affected by the changes; as such, the application may rebuild - significantly faster than it did when it was first built. + The Zephyr build system rebuilds only the parts of the application image + potentially affected by the changes. Consequently, rebuilding an application + is often significantly faster than building it the first time. +Steps +----- -Recovering from Build Failure ------------------------------ +#. Follow the steps specified in `Building an Application`_ above. + +Recovering from a Build Failure +=============================== Sometimes the build system doesn't rebuild the application correctly because it fails to recompile one or more necessary files. You can force the build system to rebuild the entire application from scratch with the following procedure: +Steps +----- + #. Navigate to the application directory :file:`~/appDir`. -#. Run :command:`$ make clean`, or manually delete the generated files, - including the :file:`.config` file. +#. Enter the following command to delete the application's generated files + for the specified board type, except for the :file:`.config` file that + contains the application's current configuration information. -#. Run :command:`$ make pristine`. + .. code-block:: console -#. You have the option to configure your project by running - :command:`$ make menuconfig`. If you choose not to configure your project - via :command:`menuconfig`, you can choose a configuration tailored for a - supported board later. - If you choose to use :command:`$ make menuconfig` be prepared to configure - all the parameters correctly for your specific board. + $ make [BOARD=] clean -#. Rebuild the application normally. Run :command:`$ make`. You can choose to - specify a default configuration for a supported board using the parameter - :command:`BOARD`. For example: :command:`$ make BOARD=arduino_101`. - You can see the boards that currently support a default configuration by - running the command :command:`$ make help` + Alternatively, enter the following command to delete *all* generated files + for *all* board types, including the :file:`.config` files that contain + the application's current configuration information for those board types. -#. Optionally, you can override the :file:`.config` file configuration (obtained - as a result of :command:`menuconfig` or :command:`BOARD` parameters) by using - the application’s :file:`.conf` file. Declare the kernel configuration settings - that cover the specific needs of your project. + .. code-block:: console + $ make pristine -.. note:: - We recommend to use the :command:`BOARD` parameter, since it will load - a preset configuration already tested to work properly with - that board. You can always tune the board configuration. Override specific - configuration elements by providing a configuration snippet file. Let the build - system know about it with the :command:`CONF_FILE` environment variable. +#. Rebuild the application normally following the steps specified + in `Building an Application`_ above. diff --git a/doc/application/apps_code_dev.rst b/doc/application/apps_code_dev.rst index b85c0d1f45e..79c6f7cec69 100644 --- a/doc/application/apps_code_dev.rst +++ b/doc/application/apps_code_dev.rst @@ -1,122 +1,90 @@ .. _apps_code_dev: -Application Code Development -############################ +Add Application-Specific Code +############################# -.. contents:: +Application-specific source code is typically added to an application +by placing it in the application directory itself (:file:`~/appDir`). +However, in some cases an application may also need to modify +or enhance the kernel itself. + +.. contents:: Procedures :local: :depth: 1 -.. _develop_services: +Adding Source Code to an Application Directory +********************************************** -Services -******** +Understanding Source Code Requirements +====================================== -The Zephyr kernel services architecture has services that are -specific to the microkernel, services that are specific to the -nanokernel, and services that are common, or shared, between the -two. - -Microkernel Services -==================== - -For a complete list of microkernel services, including a description -of each with code examples, see :ref:`microkernel`. +Application-specific source code files are normally added to the application's +:file:`src` directory. If the application adds a large number of files +the developer can group them into sub-directories under :file:`src`, +to whatever depth is needed. The developer must supply a :file:`Makefile` +for the :file:`src` directory, as well as for each sub-directory under +:file:`src`. .. note:: - There are more microkernel services than those defined in - the MDEF. + These Makefiles are distinct from the top-level application Makefile + that appears in :file:`~/appDir`. -Nanokernel Services -=================== +Application-specific source code should not use symbol name prefixes +that have been reserved by the kernel for its own use. +For more information, see +`Naming Conventions `_. -For a complete list of nanokernel services, including a description -of each with code examples, see :ref:`nanokernel`. +Understanding Makefile Requirements +=================================== -Common Services -=============== +The following requirements apply to all Makefiles in the :file:`src` +directory, including any sub-directories it may have. -For a complete list of services common to both the nanokernel and -microkernel, including a description of each with code examples, -see :ref:`common`. +* During the build process, Kbuild identifies the source files to compile + into object files by matching the file names identified in + the application's Makefile(s). + .. important:: -Procedures and Conventions -************************** + A source file that is not referenced by any Makefile is not included + when the application is built. -Understanding Naming Conventions -================================ +* A Makefile cannot directly reference source code. It can only + reference object files (:file:`.o` files) produced from source code files. -The kernel limits the use of some prefixes to internal use only. For -more information, see `naming conventions`_. +* A Makefile can only reference files in its own directory or in the + sub-directories of that directory. -.. _naming conventions: https://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions - -.. _src_makefiles_reqs: - -Understanding src Directory Makefile Requirements -================================================= - -The src directory needs a Makefile to specify how to build the application -source code. Likewise, any sub-directory within src must also have its own -Makefile. The following requirements apply to all Makefiles in the src -directory: - -* A Makefile must reference only its own files and sub-directories. - -* Code that references a file outside the directory cannot be included in the - Makefile; the referenced file is included only in its own directory's - Makefile. - -* A Makefile cannot directly reference source code; it can only - reference object files (.o files) produced by source code. - - .. note:: - - The src directory Makefiles discussed here are distinct from - the top-level application Makefile. - -.. _src_files_directories: - -Adding Source Files and Makefiles to src Directories -==================================================== - -Source code and associated Makefiles specify the how the -application image is built. In a Makefile, multiple files may be -referenced from a single-line entry. However, a separate line must -be used to reference each directory. During the build process, Kbuild -finds the source files to generate the object files by matching the -file names identified in the Makefile. - -.. note:: - - Source code without an associated Makefile is not included - when the application is built. +* A Makefile may reference multiple files from a single-line entry. + However, a separate line must be used to reference each directory. Before You Begin ----------------- +* Ensure you have created an application directory, as described + in :ref:`apps_structure`. + * The Zephyr environment variable must be set for each console terminal using :ref:`apps_common_procedures`. +* Many useful code examples cam be found at :file:`\$ZEPHYR_BASE/samples`. + Steps ----- -1. Create a directory structure for your source code in :file:`src` +#. Create a directory structure for your source code in :file:`src` and add your source code files to it. - For many useful code examples, see :ref:`common`, - :ref:`microkernel`, and :ref:`nanokernel`. - -2. Create a :file:`Makefile` for each :file:`src` directory. +#. Create a :file:`Makefile` in the :file:`src` directory. Then create + an additional :file:`Makefile` in each of the sub-directories under + the :file:`src` directory, if any. a) Use the following syntax to add file references: .. code-block:: make - obj-y += file.o file.o - + obj-y += file1.o file2.o b) Use the following syntax to add directory references: @@ -124,56 +92,61 @@ Steps obj-y += directory_name/** - Example src Makefile -------------------- This example is taken from the Philosopher's Sample. To examine this file in context, navigate to: -:file:`rootDir/samples/philosophers/microkernel/src`. +:file:`\$ZEPHYR_BASE/samples/philosophers/src`. .. code-block:: make - obj-y = phil_fiber.o phil_task.o + obj-y = main.o -.. _`enhancing_kernel`: - -Enhancing the Zephyr Kernel -=========================== - -When enhancing the Zephyr kernel, follow the subsystem naming -conventions and the :literal:`include path` usage guidelines. +Modifying and Enhancing the Kernel +********************************** Subsystem Naming Conventions ----------------------------- +============================ -In general, any sub-system can define its own naming conventions for -symbols. However, naming conventions should be implemented with a -unique namespace prefix (e.g. bt\_ for BlueTooth, or net\_ for IP) to -limit possible clashes with applications. Naming within a sub-system +When enhancing an existing kernel subsystem be sure to follow +any existing naming conventions. +For more information, see +`Naming Conventions `_. + +When creating a new subsystem, the subsystem can define its own naming +conventions for symbols. However, naming conventions should be implemented +with a unique namespace prefix (e.g. bt\_ for BlueTooth, or net\_ for IP) to +limit possible clashes with applications. Naming within a subsystem should continue to follow prefix conventions identified above; this keeps consistent interface for all users. Include Paths Usage Guidelines ------------------------------- +============================== -The current build system uses a series of defs.objs to define -common pieces for a specific subsystem. For example, there -are common defines for all architectures under :file:`\$ROOT/arch/x86`, -and more specific defines for each supported board within -the architecture, such as, :file:`\$ROOT/arch/x86/generic_pc`. +Do not add unnecessary include paths to system or default include paths, +as this can lead to ambiguous references when two or more directories +contain a file with the same name. +The only include path into :file:`\$ZEPHYR_BASE/include` should be +:file:`\$ZEPHYR_BASE/include` itself. -Do not add every possible :literal:`include paths` in the defs.obj files. -Too many default paths will cause problems when more than one file with -the same name exists. The only :literal:`include path` into -:file:`\${vBASE}/include` should be :file:`\${vBASE}/include` itself. +Source files should use :code:`#include` directives that specify the full path +from a common include directory. For example, you should always use +directives of the form :code:`#include `, and not +use directives of the form :code:`#include <[header].h>`. -Files should define includes to specific files with the complete path -:file:`#include subdirectory/header.h`. For example, when there -are two files, :file:`include/pci.h` and :file:`include/drvers/pci.h`, -and both have been set to :file:`-Iinclude/drivers` and -:file:`-Iinclude` for the compile, any code using -:file:`#include pci.h` becomes ambiguous; using the complete path -:file:`#include drivers/pci.h` is not. Not having :file:`-Iinclude/drivers` -forces users to use the second form, which is more explicit. +The following example illustrates the kind of problems that can arise when +unnecessary default include paths are specified. + +* Observe that the kernel contains both :file:`include/pci.h` and + :file:`include/drivers/pci.h`. + +* If both the :file:`include` and :file:`include/drivers` directories + are added to the default include paths (e.g. + :code:`gcc -Iinclude/drivers -Iinclude [...]`), then the directive + :code:`#include ` becomes ambiguous. + +The solution is to avoid adding :file:`include/drivers` to the default +include paths. Source files can then reference either :code:`#include ` +or :code:`#include `, as needed. diff --git a/doc/application/apps_common_procedures.rst b/doc/application/apps_common_procedures.rst index 4c4fce4d769..09cda9b9616 100644 --- a/doc/application/apps_common_procedures.rst +++ b/doc/application/apps_common_procedures.rst @@ -30,7 +30,7 @@ Steps $ export ZEPHYR_GCC_VARIANT=zephyr $ export ZEPHYR_SDK_INSTALL_DIR= -2. To set the environment variable :envvar:`$(ZEPHYR_BASE)`, navigate to the +2. To set the environment variable :envvar:`\$ZEPHYR_BASE`, navigate to the kernel's installation directory and enter: .. code-block:: console diff --git a/doc/application/apps_dev_process.rst b/doc/application/apps_dev_process.rst deleted file mode 100644 index 20fca0c5308..00000000000 --- a/doc/application/apps_dev_process.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _apps_dev_process: - -Application Development Workflow -################################ - -The application development workflow identifies procedures needed to create, build, and -run a Zephyr microkernel or nanokernel application. - -Before you build ----------------- - -* Check that your Linux host meets the minimum requirements specified in the - :ref:`getting_started`. - -* Check that environment variables have been configured correctly as outlined - in :ref:`apps_common_procedures`. - -Workflow --------- - -1. Create a directory structure for your Zephyr application. - - a) :ref:`create_directory_structure` - -2. Add a Makefile - - b) :ref:`create_src_makefile` - -3. Define the application's default kernel configuration using - :ref:`define_default_kernel_conf`. - -4. Define kernel configuration override options for the application - using :ref:`override_kernel_conf`. - -5. For a microkernel application, define objects as you develop code - using :ref:`create_mdef`. - -6. For all applications, define nanokernel objects as you need them in - code. - -7. Develop source code and add source code files to the src directory. - - * `naming conventions`_ - * :ref:`src_makefiles_reqs` - * :ref:`src_files_directories` - -.. _naming conventions: https://wiki.zephyrproject.org/view/Coding_conventio ns#Naming_Conventions - -8. Build an application image. - - * :ref:`apps_build` - - -9. To test the application image's functionality on simulated hardware - with QEMU, see :ref:`apps_run`. - -10. To load an application image on a target hardware, see using - :ref:`board` documentation. diff --git a/doc/application/apps_kernel_conf.rst b/doc/application/apps_kernel_conf.rst index 71abaac075b..d518c69169b 100644 --- a/doc/application/apps_kernel_conf.rst +++ b/doc/application/apps_kernel_conf.rst @@ -1,75 +1,69 @@ .. _apps_kernel_conf: -Kernel Configuration -#################### +Configure an Application's Kernel +################################# -The application's kernel is configured from a set of options that -can be customized for application-specific purposes. Each -configuration option is derived from the first source in which -it is specified: +The application's kernel is configured using a set of configuration options +that can be customized for application-specific purposes. +The Zephyr build system takes a configuration option's value +from the first source in which it is specified. +The available sources are (in order): - a. The value specified by the application’s current - configuration; that is, its :file:`.config` file. +#. The application's current configuration. + (i.e. The :file:`.config` file.) - b. The value specified by the application’s default - configuration; that is, its :file:`prj.conf` file. +#. The application's default configuration. + (i.e. The :file:`.conf` file.) - c. The value specified by the board configuration. +#. The board configuration used by the application. + (i.e. The board's :file:`.defconfig` file.) - d. The kernel’s default value for the configuration option. +#. The kernel's default configuration. + (i.e. One of the kernel's :file:`Kconfig` files.) -.. note:: +For information on available kernel configuration options, including +inter-dependencies between options, see the :ref:`configuration`. +Be careful to note if an option is an experimental option +that is not yet fully supported. - When the default board configuration settings are sufficient for your - application, a :file:`prj.conf` file is not needed. Skip ahead to - :ref:`override_kernel_conf`. - - -Procedures -********** - -* `define_default_kernel_conf`_ - -* `Overriding the Application's Default Kernel Configuration`_ - -The procedures that follow describe how to configure a :file:`prj.conf` -file and how to configure kernel options for microkernel and nanokernel -applications. For information on how to work with kernel option -inter-dependencies and board configuration-default options, see the -:ref:`configuration`. - -.. note:: - - There are currently a number of experimental options not yet - fully supported. - -.. _define_default_kernel_conf: +.. contents:: Procedures + :local: + :depth: 1 Defining the Application's Default Kernel Configuration ======================================================= -Create a :file:`prj.conf` file to define the application's -default kernel configuration. This file can contain -settings that override or augment board-configuration settings. +An application's :file:`.conf` file defines its default kernel configuration. +The settings in this file override or augment the board configuration settings. -The contents of the supported board configuration files -can be viewed in :file:`~/rootDir/boards/BOARD/BOARD_defconfig`. +The board configuration settings can be viewed +in :file:`\$ZEPHYR_BASE/boards/ARCHITECTURE/BOARD/BOARD_defconfig`. + +.. note:: + + When the default board configuration settings are sufficient for your + application, a :file:`.conf` file is not needed. Skip ahead to + :ref:`override_kernel_conf`. Before you begin ---------------- -* Confirm Zephyr environment variables are set for each console - terminal using :ref:`apps_common_procedures`. +* Ensure you have created an application directory, as described + in :ref:`apps_structure`. + +* Review the kernel configuration options available and know + which ones you want to set for your application. + Be aware of any dependencies involving these options. + See the :ref:`configuration` for a brief description of each option. Steps ----- 1. Navigate to the :file:`appDir`, and create the :file:`prj.conf` file. Enter: - .. code-block:: bash - - $ touch prj.conf + .. code-block:: bash + $ touch prj.conf The default name is :file:`prj.conf`. The filename must match the ``CONF_FILE`` entry in the application :file:`Makefile`. @@ -85,13 +79,13 @@ Steps d) Use a # followed by a space to comment a line. - This example shows a comment line and a board + The example below shows a comment line and a board configuration override in the :file:`prj.conf`. - .. code-block:: c + .. code-block:: c - # Change the number of IRQs supported by the application - CONFIG_NUM_IRQS=43 + # Change the number of IRQs supported by the application + CONFIG_NUM_IRQS=43 3. Save and close the file. @@ -102,7 +96,7 @@ Overriding the Application's Default Kernel Configuration ========================================================= Override the application's default kernel configuration to -temporarily alter the application’s configuration, perhaps +temporarily alter the application's configuration, perhaps to test the effect of a change. .. note:: @@ -117,16 +111,15 @@ is a preferred method. Before you begin ---------------- +* Ensure you have created an application directory, as described + in :ref:`apps_structure`. + * Review the kernel configuration options available and know - which ones you want to temporarily set for your application. - See the :ref:`configuration` for a brief description of each option. + which ones you want to set for your application. + Be aware of any dependencies involving these options. -* Be aware of any dependencies among the kernel configuration options. - -* Confirm an application :file:`Makefile` exists for your application. - -* Confirm the Zephyr environment variable is set for each console - terminal; see :ref:`apps_common_procedures`. +* Ensure the Zephyr environment variables are set for each console terminal; + see :ref:`apps_common_procedures`. Steps ----- @@ -141,7 +134,7 @@ Steps .. code-block:: bash - $ make menuconfig + $ make [BOARD=] menuconfig A question-based menu opens that allows you to set individual configuration options. @@ -202,7 +195,7 @@ Steps An :file:`outdir` directory is created in the application directory. The outdir directory contains symbolic links - to files under $(ZEPHYR_BASE). + to files under :file:`\$ZEPHYR_BASE`. .. note:: @@ -261,8 +254,3 @@ Steps 11. Press :kbd:`Enter` to retire the menu display and return to the console command line. - -**Next Steps**: For microkernel applications, go to :ref:`Creating and -Configuring an MDEF File for a Microkernel Application `. - -For nanokernel applications, go to :ref:`apps_code_dev`. diff --git a/doc/application/apps_object_conf.rst b/doc/application/apps_object_conf.rst deleted file mode 100644 index 634b9d0e1d2..00000000000 --- a/doc/application/apps_object_conf.rst +++ /dev/null @@ -1,96 +0,0 @@ -.. _apps_object_conf: - -Microkernel Object Configuration -################################ - -Microkernel objects are explained fully in the :ref:`kernel`. -See :ref:`microkernel` for example MDEF entries. - -Procedure -********* - -.. _create_mdef: - -Creating and Configuring an MDEF for a Microkernel Application -============================================================== - -Create the MDEF to define microkernel objects used in your -application when they apply to the application as a whole. -You do not need to define every object before writing code. In -some cases, the necessary objects aren't obvious until you begin -writing code. However, all objects used in your code must be defined -before your application will compile successfully. - -.. note:: - - Nanokernel applications do not use an MDEF because microkernel - objects cannot be used in applications of this type. - -Before you begin ----------------- - -* Confirm your :file:`~/appDir` already exists. - -* Confirm Zephyr environment variables are set for each console - terminal; for instructions, see :ref:`apps_common_procedures`. - -Steps ------ - -1. Create an MDEF in your application directory - (:file:`~/appDir ~) using - the name you specified in your application Makefile. - (See :ref:`Creating an Application Makefile`). - - .. code-block:: bash - - $ touch prj.mdef - - The default MDEF name is :file:`prj.mdef`. - -2. Open the file using a standard text editor. - -3. Add settings to the file to suit your application. - - The syntax for objects that can be defined in :file:`.mdef` - is: - - TASK name priority entry_point stack_size groups - - TASKGROUP name - - MUTEX name - - SEMA name - - FIFO name depth width - - PIPE name buffer_size - - MAILBOX name - - MAP name num_blocks block_size - - POOL name min_block_size max_block_size numMax - -.. note:: - - Some microkernel objects, such as Task IRQs, are not - defined in an :file:`.mdef` file. - -The following example shows the content of the -:file:`samples/legacy/philosophers/microkernel/proj.mdef` -for the Philosophers' sample application. The sample -uses seven tasks and six mutexes. - -Example MDEF ------------- - -.. literalinclude:: ../../samples/legacy/philosophers/microkernel/prj.mdef - :linenos: - -Related Topics --------------- - -:ref:`src_makefiles_reqs` -:ref:`src_files_directories` diff --git a/doc/application/apps_overview.rst b/doc/application/apps_overview.rst index 48eeaeee785..5de8513900d 100644 --- a/doc/application/apps_overview.rst +++ b/doc/application/apps_overview.rst @@ -13,21 +13,25 @@ The directory has the following structure. or more application-specific files, written in C or assembly language. These files are usually located in a sub-directory called :file:`src`. -* **Kernel configuration files**: An application typically provides a configuration - file (:file:`.conf`) that specifies values for one or more kernel configuration - options. If omitted, the application's existing kernel configuration option values - are used; if no existing values are provided, the kernel's default configuration - values are used. +* **Kernel configuration files**: An application typically provides + a configuration file (:file:`.conf`) that specifies values for one or more + kernel configuration options. If omitted, the application's existing kernel + configuration option values are used; if no existing values are provided, + the kernel's default configuration values are used. -* **MDEF file**: A microkernel application typically provides a Microkernel - DEFinitions file (:file:`.mdef`) that defines the public kernel objects - used by the application and the kernel. If omitted, no public kernel objects - are defined. This file is not used with a nanokernel-only application. - -* **Makefile**: This file typically contains a handful of lines that tell the build - system where to find the files mentioned above, as well as the desired target - board configuration and kernel type (either microkernel or nanokernel). +* **Makefile**: This file typically contains a handful of lines that tell + the build system where to find the files mentioned above, as well as + the desired target board configuration. Once the application has been defined, it can be built with a single command. -The results of the build process, including the final application image, -are located in a sub-directory called :file:`outdir`. +The results of the build process are located in a sub-directory +called :file:`outdir/BOARD`. This directory contains the files generated +by the build process, the most notable of which are listed below. + +* The :file:`.config` file that contains the configuration settings + used to build the application. + +* The various object files (:file:`.o` files and :file:`.a` files) containing + custom-built kernel and application-specific code. + +* The :file:`zephyr.elf` file that contains the final application image. diff --git a/doc/application/apps_run.rst b/doc/application/apps_run.rst index 768d80ded55..65efbc61246 100644 --- a/doc/application/apps_run.rst +++ b/doc/application/apps_run.rst @@ -3,59 +3,56 @@ Run an Application ################## -The kernel's built-in simulator is QEMU. It creates an environment -where you can run and test an application virtually, before (or -in lieu of) loading and running it on actual target hardware. +An appliction image can be run on real or simulated hardware. +The kernel's built-in simulator is QEMU. It allows you to run and test +an application virtually, before (or in lieu of) +loading and running it on actual target hardware. -Procedures -********** - -.. _run_app_qemu: +.. contents:: Procedures + :local: + :depth: 1 Running an Application using QEMU ================================= -Run your application in QEMU for testing and demonstration purposes. - Prerequisites ------------- -* You must have already generated a .elf image file for a - QEMU-supported board configuration, such as qemu_cortex_m3 or qemu_x86. +* Ensure the application can be built successfully using a QEMU-supported + board configuration, such as qemu_cortex_m3 or qemu_x86, as described + in :ref:`apps_build`. -* The environment variable must be set for each console - terminal using :ref:`apps_common_procedures`. +* Ensure the Zephyr environment variables are set for each console terminal; + see :ref:`apps_common_procedures`. Steps ----- -1. Open a terminal console and navigate to the application directory +#. Open a terminal console and navigate to the application directory :file:`~/appDir`. -2. Enter the following command to build and run an application - in QEMU: +#. Enter the following command to build and run the application + using a QEMU-supported board configuration, + such as qemu_cortex_m3 or qemu_x86. - .. code-block:: console + .. code-block:: console - $ make qemu + $ make [BOARD= ...] qemu + The Zephyr build system generates a :file:`zephyr.elf` image file + and then begins running it in the terminal console. - The application begins running in the terminal console. - -3. Press :kbd:`Ctrl A, X` to stop the application from running +#. Press :kbd:`Ctrl A, X` to stop the application from running in QEMU. - The application stops running and the terminal console prompt - redisplays. - -.. _loading_on_target: + The application stops running and the terminal console prompt + redisplays. Loading and Running an Application on Target Hardware ===================================================== -An application image is loaded on the target based on functionality -available on the hardware device. Loading instructions are often -unique to the particular target board. For this reason, loading -instructions reside with the board-specific documentation. - -For more information see :ref:`board`. +The procedure required to load an application image (:file:`zephyr.elf`) +on a target depends on the functionality available on its hardware, +and is often unique to that target board. +For this reason, loading instructions reside with the board-specific +documentation; see :ref:`board`. diff --git a/doc/application/apps_structure.rst b/doc/application/apps_structure.rst index eab6b79896d..6c0e61941ac 100644 --- a/doc/application/apps_structure.rst +++ b/doc/application/apps_structure.rst @@ -1,39 +1,29 @@ .. _apps_structure: -Application Development Directory Structure -########################################### +Create an Application Directory +############################### Each application resides in a uniquely-named application -directory created by the developer, typically, in the developer's +directory created by the developer, typically in the developer's workspace directory. The application developer also creates a :file:`src` directory for the application's source code. -.. note:: +.. contents:: Procedures + :local: + :depth: 1 - The Zephyr Kernel either supplies or generates all other application - directories. +Creating an Application and Source Code Directory +================================================= -Procedures -********** - -* `create_directory_structure`_ - -* `create_src_makefile`_ - -.. _create_directory_structure: - -Creating an Application and Source Code Directory using the CLI -=============================================================== - -Create one directory for your application and another for the application's -source code; this makes it easier to organize directories and files in the -structure that the kernel expects. +Create one directory for your application and a sub-directory for the +application's source code; this makes it easier to organize directories +and files in the structure that the kernel expects. Before You Begin ---------------- -* The environment variable must be set for each console terminal using - :ref:`set_environment_variables`. +* Ensure the Zephyr environment variables are set for each console terminal; + see :ref:`apps_common_procedures`. Steps ----- @@ -41,8 +31,8 @@ Steps 1. Create an application directory structure outside of the kernel's installation directory tree. Often this is your workspace directory. - a) In a Linux console, navigate to a location where you want your - applications to reside. + a) In a console terminal, navigate to a location where you want your + application to reside. b) Create the application's directory, enter: @@ -68,16 +58,13 @@ Steps -- appDir |-- src -.. _create_src_makefile: - Creating an Application Makefile ================================ -Create an application Makefile to define basic information such as the kernel -type, microkernel or nanokernel, and the board configuration used by the -application. The build system uses the Makefile to build an image with both -the application and the kernel libraries called either -:file:`microkernel.elf` or :file:`nanokernel.elf`. +Create an application Makefile to define basic information, +such as the board configuration used by the application. +The build system uses the Makefile to build a :file:`zephyr.elf` image +that contains both the application and the kernel libraries. Before You Begin ---------------- @@ -87,8 +74,8 @@ Before You Begin * Be familiar with the board configuration used for your application and, if it is a custom board configuration, where it is located. -* Set the environment variable for each console terminal using - :ref:`set_environment_variables`. +* Ensure the Zephyr environment variables are set for each console terminal; + see :ref:`apps_common_procedures`. Steps ----- @@ -106,16 +93,7 @@ Steps Ensure that there is a space after each ``=``. - a) Add the kernel type on a new line: - - .. code-block:: make - - KERNEL_TYPE = micro|nano - - Either micro or nano, short for microkernel or - nanokernel respectively. - - b) Add the name of the board configuration for your application on a + a) Add the name of the default board configuration for your application on a new line: .. code-block:: make @@ -124,30 +102,18 @@ Steps The supported boards can be found in :ref:`board`. - c) Add the name of the default kernel configuration file for your + b) Add the name of the default kernel configuration file for your application on a new line: .. code-block:: make - CONF_FILE = prj.conf + CONF_FILE ?= kernel_configuration_name - The default name is :file:`prj.conf`. If you are not using the default - name, this entry must match the filename of the :file:`.conf` file you - are using. + The default kernel configuration file entry may be omitted if the file + is called :file:`prj.conf`. It may also be omitted if the default board + configuration's kernel settings are sufficient for your application. - d) For microkernel applications, add the name of the MDEF for your - application: - - .. code-block:: make - - MDEF_FILE = prj.mdef - - The default name is :file:`prj.mdef`. If you are not using the default - name, this entry must match the filename of the :file:`.mdef` file you - are using. - - e) Include the mandatory :file:`Makefile` fragments on a new - line: + c) Include the mandatory :file:`Makefile` fragments on a new line: .. code-block:: make @@ -160,8 +126,6 @@ Example Makefile .. code-block:: make - KERNEL_TYPE = micro BOARD ?= qemu_x86 - CONF_FILE = prj.conf - MDEF_FILE = prj.mdef + CONF_FILE ?= prj.conf include ${ZEPHYR_BASE}/Makefile.inc