diff --git a/documentation/source/quickstart/build-open-harmony.rst b/documentation/source/quickstart/build-open-harmony.rst new file mode 100644 index 0000000000000000000000000000000000000000..a42dd51f2975f841920036ad3708228347d8bfa6 --- /dev/null +++ b/documentation/source/quickstart/build-open-harmony.rst @@ -0,0 +1,267 @@ +.. BuildOpenharmony: + +Building OpenHarmony Image +########################## + +OpenHarmony is a distributed OS that is designed to run on top of variety of OS kernels. Currently the supported kernels are Zephyr, Yocto, and FreeRTOS. To build OpenHarmony image, you need to add multiple layers called meta-ohos. The meta-ohos is an umbrella meta layer containing all layers required to build OpenHarmony Image based on existing kernel meta-layers. This section describes how to build, add layers, and run the OpenHarmony image. + +* `Build and Run Using Zephyr <using zypher>`_ +* `Build and Run Using Linux <using linux>`_ +* `Build and Run Using FreeRTOS <using freertos>`_ + + +Currently OpenHarmony Supports building image using the following boards: + +* `Nitrogen <https://www.96boards.org/documentation/iot/nitrogen/>`_ +* `Avenger96 <https://www.96boards.org/documentation/consumer/avenger96/>`_ + +**Figure 1 meta-ohos overview** + +.. figure:: images/architecture.png + :align: center + :alt: meta-ohos overview + +Prerequisites +------------------- + +To start working with meta-ohos first install git repo: + +.. code-block:: console + + $ sudo add-apt-repository ppa:zyga/oh-tools + $ sudo apt-get update + $ sudo apt-get install git-repo + +.. _using zypher: + +Build and Run Using Zypher +----------------------------------------- + +1. Once git repo has been installed, clone the necessary repositories. + + .. code-block:: console + + $ mkdir ohos; cd ohos + $ repo init -u https://git.ostc-eu.org/incubate/meta-ohos/manifest.git + $ repo sync + $ cd poky + poky$ . oe-init-build-env + +2. Add layers for other kernels. Working directory will automatically change to ./poky/build. + + .. code-block:: console + + build$ bitbake-layers add-layer ../meta-openembedded/meta-oe + build$ bitbake-layers add-layer ../meta-openembedded/meta-python + build$ bitbake-layers add-layer ../meta-zephyr + build$ bitbake-layers add-layer ../meta-freertos + + .. note:: + Layers for poky were added automatically by sourcing oe-init-build-env. + +3. Build distro by selecting the prefered board: + + * For Nitrogen + + .. code-block:: console + + build$ DISTRO=zephyr MACHINE=96b-nitrogen bitbake zephyr-philosophers + + * For Avenger96 + + .. code-block:: console + + build$ DISTRO=zephyr MACHINE=96b-avenger96 bitbake zephyr-philosophers + + + .. note:: + For Zephyr, zephyr-philosophers is the one of sample applications available in meta-zephyr layer by Yocto project. It's easy to build other samples using recipes available in meta-zephyr/recipes-kernel/zephyr-kernel/ directory. + +4. After the build is successful, run the image by executing the following command: + + + * For Nitrogen + + .. code-block:: console + + build$ DEPLOY_DIR_IMAGE=tmp-newlib/deploy/images/96b-nitrogen runqemu 96b-nitrogen + + + * For Avenger96 + + .. code-block:: console + + build$ DEPLOY_DIR_IMAGE=tmp-newlib/deploy/images/96b-avenger96 runqemu 96b-avenger96 + +After successful bootup, the following message should be displayed: + +.. code-block:: console + + Booting from ROM..*** Booting Zephyr OS build zephyr-v2.4.0 *** + Philosopher 0 [P: 3] THINKING [ 300 ms ] + Philosopher 1 [P: 2] EATING [ 575 ms ] + Philosopher 2 [P: 1] STARVING + Philosopher 3 [P: 0] EATING [ 525 ms ] + Philosopher 4 [C: -1] THINKING [ 475 ms ] + +.. _using linux: + + +Build and Run Using Linux +---------------------------------------- + +1. Once git repo has been installed, clone the necessary repositories. + + .. code-block:: console + + $ mkdir ohos; cd ohos + $ repo init -u https://git.ostc-eu.org/incubate/meta-ohos/manifest.git + $ repo sync + $ cd poky + poky$ . oe-init-build-env + +2. Add layers for other kernels. Working directory will automatically change to ./poky/build. + + .. code-block:: console + + build$ bitbake-layers add-layer ../meta-openembedded/meta-oe + build$ bitbake-layers add-layer ../meta-openembedded/meta-python + build$ bitbake-layers add-layer ../meta-zephyr + build$ bitbake-layers add-layer ../meta-freertos + + .. note:: + Layers for poky were added automatically by sourcing oe-init-build-env. + +3. Build distro by selecting the prefered board: + + * For Nitrogen + + .. code-block:: console + + build$ DISTRO=poky-tiny MACHINE=96b-nitrogen bitbake core-image-minimal + + * For Avenger96 + + .. code-block:: console + + build$ DISTRO=poky-tiny MACHINE=96b-avenger96 bitbake core-image-minimal + +4. After the build is successful, run the image by executing the following command: + + * For Nitrogen + + .. code-block:: console + + build$ runqemu 96b-nitrogen ramfs qemuparams="-nographic" + + + * For Avenger96 + + .. code-block:: console + + build$ runqemu 96b-avenger96 ramfs qemuparams="-nographic" + +After successful bootup, the following message should be displayed: + + * For Nitrogen + + .. code-block:: console + + # For poky + 96b-nitrogen login: + # Default login is _root_ without a password. + # After login you should see prompt: + root@96b-nitrogen:~# + + * For Avenger96 + + .. code-block:: console + + # For poky + 96b-avenger96 login: + # Default login is _root_ without a password. + # After login you should see prompt: + root@96b-avenger96:~# + +.. _using freertos: + +Build and Run Using FreeRTOS +----------------------------------------------- + +1. Once git repo has been installed, clone the necessary repositories. + + .. code-block:: console + + $ mkdir ohos; cd ohos + $ repo init -u https://git.ostc-eu.org/incubate/meta-ohos/manifest.git + $ repo sync + $ cd poky + poky$ . oe-init-build-env + +2. Add layers for other kernels. Working directory will automatically change to ./poky/build. + + .. code-block:: console + + build$ bitbake-layers add-layer ../meta-openembedded/meta-oe + build$ bitbake-layers add-layer ../meta-openembedded/meta-python + build$ bitbake-layers add-layer ../meta-zephyr + build$ bitbake-layers add-layer ../meta-freertos + +3. Build distro by selecting the prefered board. + + .. Note:: + Currently FreeRTOS supports *qemu* boards only. + + .. code-block:: console + + build$ DISTRO=freertos MACHINE=qemuarmv5 bitbake freertos-demo + +4. After the build is successful, run the image by executing the following command: + + .. code-block:: console + + build$ runqemu 96b-nitrogen + +After successful bootup, the following message should be displayed: + +.. code-block:: console + + ###### - FreeRTOS sample application -###### + + A text may be entered using a keyboard. + It will be displayed when 'Enter' is pressed. + + Periodic task 10 secs + Waiting For Notification - Blocked... + Task1 + Task1 + You entered: "HelloFreeRTOS" + Unblocked + Notification Received + Waiting For Notification - Blocked... + + + + + + + + + + + + + + + + + + + + + + + + + +