diff --git a/documentation/source/index.rst b/documentation/source/index.rst index a4c5e5e4725eefe0c091b0bc4615f9acae8ac9ad..5ab506d7dbbecb06528d6ea65ecce73d44d2e4e1 100644 --- a/documentation/source/index.rst +++ b/documentation/source/index.rst @@ -6,4 +6,6 @@ OpenHarmony is an open-source project launched by the OpenAtom Foundation and se .. toctree:: :maxdepth: 1 :caption: Contents: + + BuildOpenharmony diff --git a/documentation/source/quickstart/BuildOpenharmony.rst b/documentation/source/quickstart/BuildOpenharmony.rst new file mode 100644 index 0000000000000000000000000000000000000000..c6f32647df14fdaafe98e52c21850d8bc6325f31 --- /dev/null +++ b/documentation/source/quickstart/BuildOpenharmony.rst @@ -0,0 +1,278 @@ +.. 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 add multiple layers called meta-ohos. meta-ohos is an umbrella meta layer containing all layers required to build OpenHarmony Image basing 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 Yocto <using yocto>`_ +* `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 + :alt: rest configuration + :align: center + +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 yocto: + + +Build and Run Using Yocto +---------------------------------------- +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: + + * For Nitrogen + + .. code-block:: console + + build$ DISTRO=freertos MACHINE=96b-nitrogen bitbake freertos-demo + + * For Avenger96 + + .. code-block:: console + + build$ DISTRO=freertos MACHINE=96b-avenger96 bitbake freertos-demo + +4. After the build is successful, run the image by executing the following command: + + * For Nitrogen + + .. code-block:: console + + build$ runqemu 96b-nitrogen + + + * For Avenger96 + + .. 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... + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/source/quickstart/images/architecture.png b/documentation/source/quickstart/images/architecture.png new file mode 100644 index 0000000000000000000000000000000000000000..90835273de6675e9be662f56c1d5898ad5217f6c Binary files /dev/null and b/documentation/source/quickstart/images/architecture.png differ