<commit_before>.. _running_apps:

Running Applications
####################

Running Applications in QEMU
****************************

Using QEMU from a different path
================================

If the QEMU binary path is different to the default path, set the
variable :envvar:`QEMU_BIN_PATH` with the new path, type:

.. code-block:: bash

   $ export QEMU_BIN_PATH=/usr/local/bin

Another option is to add it to the make command, for example:

.. code-block:: bash

   $ make QEMU_BIN_PATH=/usr/local/bin qemu

Running a Microkernel Application
=================================

Run a microkernel application using the default platform configuration, type:

.. code-block:: bash

   $ make pristine && make qemu

Run an application using the x86 basic_atom platform configuration, type:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_atom ARCH=x86 qemu

Run an application using the ARM basic_cortex_m3 platform configuration, type:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_cortex_m3 ARCH=arm qemu

Running a Nanokernel Application
================================

Run a nanokernel application using the default platform configuration use the
following commands:

.. code-block:: bash

   $ make pristine && make qemu

Run an application using the x86 basic_atom platform configuration, use the
following commands:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_atom ARCH=x86 qemu

Run an application using the ARM basic_cortex_m3 platform configuration use the
following commands:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_cortex_m3 ARCH=arm qemu


Running an Application on Galileo Gen2
**************************************

#. Set the platform configuration to Galileo by changing the :command:`make`
command to:

.. code-block:: bash

   make PLATFORM_CONFIG=galileo

#. Use one of these cables for serial output:

    `<http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm>`__

#. Format a microSD as FAT

#. Create the following directories

:file:`EFI`

:file:`EFI/BOOT`

:file:`kernel`

#. Assuming you have built a micro kernel, copy the kernel file :file:`
microkernel.elf` to the :file:`$SDCARD/kernel` folder

#. Copy your built version of GRUB to :file:`$SDCARD/EFI/BOOT/BOOTIA32.EFI`

#. Create :file:`$SDCARD/EFI/BOOT/grub.cfg` containing the following:

.. code-block:: bash

   set default=0
   set timeout=10

   menuentry "Zephyr microkernel" {
      multiboot /kernel/microkernel.elf
    }

#. Insert the SDcard in the Galileo board.

#. Connect the board to the host system using the serial cable.

#. Configure your host system to watch for serial data.

    * On Linux, minicom is a popular method for reading serial
      data.

    * On Windows, PuTTY has an option to set up configuration for
      serial data.

#. Power on the Galileo board.

#. When asked press :kbd:`F7`.

#. By default Galileo has a pre-installed GRUB and Linux distro.
   Press :kbd:`c` to cancel the current boot.

#. Quit the currently running GRUB.

#. On the menu select the :guilabel:`UEFI Internal Shell` option.

#. If you've added a custom GRUB, please run it from here.

Building a Custom GRUB
**********************

If you are having problems running an application using the default GRUB
of the hardware, follow these steps to test on Galileo2 boards using a custom
GRUB.

1. Install the requirements to build GRUB on your host machine.

In Ubuntu, type:

.. code-block:: bash

    $ sudo apt-get install gnu-efi-i386 bison libopts25 \
    libselinux1-dev autogen m4 autoconf help2man libopts25-dev flex \
    libfont-freetype-perl automake autotools-dev libfreetype6-dev \
    texinfo \

In Fedora, type:

.. code-block:: bash

   $ sudo yum install gnu-efi-i386 bison libopts25 \
   libselinux1-dev autogen m4 autoconf help2man libopts25-dev flex \
   libfont-freetype-perl automake autotools-dev libfreetype6-dev texinfo

2. Clone the GRUB repository, type:

.. code-block:: bash

   $ cd ~

   $ git clone http://git.savannah.gnu.org/r/grub.git

3. Build the GRUB code, type:

.. code-block:: bash

    $ cd grub

    $ ./autogen.sh CFLAGS=”-march=i586 -m32” ./configure --with-platform=efi\
    --target=i386 --program-prefix=""

    $ make

    $ cd grub-core

    $ ../grub-mkimage -O i386-efi -d . -o grub.efi -p "" part_gpt part_msdos\
     fat ext2 normal chain boot configfile linux multiboot help serial \
     terminal elf efi_gop efi_uga terminfo

4. Look for the binary at :file:`~/grub/grub-core/grub.efi`.

Troubleshoot
============

If your custom built GRUB version returns the error:

.. error::

   error reported: Invalid parameter<commit_msg>doc: fix GRUB build instructions<commit_after>.. _running_apps:

Running Applications
####################

Running Applications in QEMU
****************************

Using QEMU from a different path
================================

If the QEMU binary path is different to the default path, set the
variable :envvar:`QEMU_BIN_PATH` with the new path, type:

.. code-block:: bash

   $ export QEMU_BIN_PATH=/usr/local/bin

Another option is to add it to the make command, for example:

.. code-block:: bash

   $ make QEMU_BIN_PATH=/usr/local/bin qemu

Running a Microkernel Application
=================================

Run a microkernel application using the default platform configuration, type:

.. code-block:: bash

   $ make pristine && make qemu

Run an application using the x86 basic_atom platform configuration, type:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_atom ARCH=x86 qemu

Run an application using the ARM basic_cortex_m3 platform configuration, type:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_cortex_m3 ARCH=arm qemu

Running a Nanokernel Application
================================

Run a nanokernel application using the default platform configuration use the
following commands:

.. code-block:: bash

   $ make pristine && make qemu

Run an application using the x86 basic_atom platform configuration, use the
following commands:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_atom ARCH=x86 qemu

Run an application using the ARM basic_cortex_m3 platform configuration use the
following commands:

.. code-block:: bash

   $ make pristine && make PLATFORM_CONFIG=basic_cortex_m3 ARCH=arm qemu


Running an Application on Galileo Gen2
**************************************

#. Set the platform configuration to Galileo by changing the :command:`make`
command to:

.. code-block:: bash

   make PLATFORM_CONFIG=galileo

#. Use one of these cables for serial output:

    `<http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm>`__

#. Format a microSD as FAT

#. Create the following directories

:file:`EFI`

:file:`EFI/BOOT`

:file:`kernel`

#. Assuming you have built a micro kernel, copy the kernel file :file:`
microkernel.elf` to the :file:`$SDCARD/kernel` folder

#. Copy your built version of GRUB to :file:`$SDCARD/EFI/BOOT/BOOTIA32.EFI`

#. Create :file:`$SDCARD/EFI/BOOT/grub.cfg` containing the following:

.. code-block:: bash

   set default=0
   set timeout=10

   menuentry "Zephyr microkernel" {
      multiboot /kernel/microkernel.elf
    }

#. Insert the SDcard in the Galileo board.

#. Connect the board to the host system using the serial cable.

#. Configure your host system to watch for serial data.

    * On Linux, minicom is a popular method for reading serial
      data.

    * On Windows, PuTTY has an option to set up configuration for
      serial data.

#. Power on the Galileo board.

#. When asked press :kbd:`F7`.

#. By default Galileo has a pre-installed GRUB and Linux distro.
   Press :kbd:`c` to cancel the current boot.

#. Quit the currently running GRUB.

#. On the menu select the :guilabel:`UEFI Internal Shell` option.

#. If you've added a custom GRUB, please run it from here.

Building a Custom GRUB
**********************

If you are having problems running an application using the default GRUB
of the hardware, follow these steps to test on Galileo2 boards using a custom
GRUB.

1. Install the requirements to build GRUB on your host machine.

In Ubuntu, type:

.. code-block:: bash

    $ sudo apt-get install gnu-efi:i386 bison libopts25 \
    libselinux1-dev autogen m4 autoconf help2man libopts25-dev flex \
    libfont-freetype-perl automake autotools-dev libfreetype6-dev \
    texinfo \

In Fedora, type:

.. code-block:: bash

   $ sudo yum install gnu-efi-i386 bison libopts25 \
   libselinux1-dev autogen m4 autoconf help2man libopts25-dev flex \
   libfont-freetype-perl automake autotools-dev libfreetype6-dev texinfo

2. Clone and build the GRUB repository using the script in Zephyr tree, type:

.. code-block:: bash

   $ cd $ZEPHYR_BASE
   $ ./scripts/build_grub.sh

4. Look for the binary at :file:`$ZEPHYR_BASE/scripts/grub/bin/grub.efi`.

Troubleshoot
============

If your custom built GRUB version returns the error:

.. error::

   error reported: Invalid parameter
{'fraction_non_alphanumeric': 0.12584170438238215, 'fraction_numerical': 0.011369908378408213, 'mean_word_length': 3.8114710568242165, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4909199', 'n_tokens_mistral': 2971, 'n_tokens_neox': 2708, 'n_words': 1022}