From 7808f7e1f0bc4f015a59e64ce6e0c721f36f5fc8 Mon Sep 17 00:00:00 2001 From: Wayne Ren Date: Fri, 31 Dec 2021 15:50:37 +0800 Subject: [PATCH] docs: add initial structure and configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 增加初始文档配置和内容 Signed-off-by: Wayne Ren --- docs/make.bat | 35 --- docs/source/conf.py | 4 +- docs/source/features/distributed_soft_bus.rst | 4 + docs/source/features/index.rst | 12 + docs/source/features/mcs.rst | 4 + docs/source/getting_started/index.rst | 225 ++++++++++++++++++ docs/source/index.rst | 42 +--- docs/source/introduction/index.rst | 10 + docs/source/releases/index.rst | 12 + .../releases/release-notes-21.09.30.rst | 9 + .../releases/release-notes-22.03.30.rst | 9 + docs/source/yocto/index.rst | 30 +++ 12 files changed, 330 insertions(+), 66 deletions(-) delete mode 100644 docs/make.bat create mode 100644 docs/source/features/distributed_soft_bus.rst create mode 100644 docs/source/features/index.rst create mode 100644 docs/source/features/mcs.rst create mode 100644 docs/source/getting_started/index.rst create mode 100644 docs/source/introduction/index.rst create mode 100644 docs/source/releases/index.rst create mode 100644 docs/source/releases/release-notes-21.09.30.rst create mode 100644 docs/source/releases/release-notes-22.03.30.rst create mode 100644 docs/source/yocto/index.rst diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6fcf05b4b76..00000000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/conf.py b/docs/source/conf.py index 9bba86ddafb..f3d4bfc4980 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -18,8 +18,8 @@ # -- Project information ----------------------------------------------------- project = 'yocto-doc' -copyright = '2021, lisiming' -author = 'lisiming' +copyright = '2021, openEuler Embedded' +author = 'openEuler Embedded' # The full version, including alpha/beta/rc tags release = '1.0.0' diff --git a/docs/source/features/distributed_soft_bus.rst b/docs/source/features/distributed_soft_bus.rst new file mode 100644 index 00000000000..2cd6e685c69 --- /dev/null +++ b/docs/source/features/distributed_soft_bus.rst @@ -0,0 +1,4 @@ +.. _distributed_soft_bus: + +分布式软总线 +############# \ No newline at end of file diff --git a/docs/source/features/index.rst b/docs/source/features/index.rst new file mode 100644 index 00000000000..7468b986291 --- /dev/null +++ b/docs/source/features/index.rst @@ -0,0 +1,12 @@ +.. _openeuler_embedded_features: + + +openEuler embedded关键特性 +################################ + +.. toctree:: + :maxdepth: 1 + :caption: 内容 + + mcs.rst + distributed_soft_bus.rst \ No newline at end of file diff --git a/docs/source/features/mcs.rst b/docs/source/features/mcs.rst new file mode 100644 index 00000000000..a700adf6819 --- /dev/null +++ b/docs/source/features/mcs.rst @@ -0,0 +1,4 @@ +.. _mixed_critical_system: + +混合关键性系统 +################### diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst new file mode 100644 index 00000000000..00b2470d534 --- /dev/null +++ b/docs/source/getting_started/index.rst @@ -0,0 +1,225 @@ +.. _getting_started: + +快速上手 +########## + +openEuler Embedded是基于openEuler社区面向嵌入式场景的Linux版本。由于嵌入式系统应用受到多个因素的约束，如资源、功耗、多样性等， +使得面向服务器领域的Linux及相应的构建系统很难满足嵌入式场景的要求，因此业界广泛采用 `Yocto `_ +来定制化构建嵌入式Linux。openEuler Embedded当前也采用的Yocto构建，但实现了与openEuler其他版本代码同源，具体的构建方法请参考 +`SIG-Yocto `_ +下相关代码仓中的内容。 + +本文档主要用于介绍如何获取预先构建好的镜像，如何运行镜像，以及如何基于镜像完成基本的嵌入式Linux应用开发。 + +获取镜像 +*********** + +当前发布的已构建好的镜像，只支持arm和aarch64两种架构，且只支持qemu中ARM virt-4.0平台，您可以通过如下链接获得相应的镜像： + +- `qemu_arm `_： 32位arm架构, ARM Cortex A15处理器 +- `qemu_aarch64 `_: 64位aarch64架构 ARM Cortex A57处理器 + +只要相应环境支持qemu仿真器（版本5.0以上），您可以将提供的openEuler Embedded镜像部署在物理裸机、云环境、容器或虚拟机上。 + +镜像内容 +*********** + +所下载的镜像，由以下几部分组成： + +- 内核镜像 **zImage**: 基于openEuler社区Linux 5.10代码构建得到。相应的内核配置可通过如下链接获取： + + - `arm(cortex a15) `_ + - `arm(cortex a57) `_, + 针对aarch64架构，额外增加了镜像自解压功能，可以参见相应的 `patch `_ + +- 根文件系统镜像（依据具体需求，以下二选一） + + - **initrd_tiny**：极简根文件系统镜像，只包含基本功能。包含 busybox 和基本的 glibc 库。该镜像功能简单，但内存消耗很小，适合探索 Linux内核相关功能。 + - **initrd**：标准根文件系统镜像，在极简根文件系统镜像的基础上，进行了必要安全加固，增加了audit、cracklib、OpenSSH、Linux PAM、shadow、iSula容器等软件包。该镜像适合进行更加丰富的功能探索。 + +运行镜像 +*********** + +通过运行镜像，一方面您可以体验openEuler Embedded的功能，一方面也可以完成基本的嵌入式Linux开发。 + +.. note:: + + - 建议使用QEMU5.0以上版本运行镜像，由于一些额外功能（网络、共享文件系统)需要依赖QEMU的virtio-net, virtio-fs等特性，如未在QEMU中使能，则运行时可能会产生错误，此时可能需要从源码重新编译QEMU。 + + - 运行镜像时，建议把内核镜像和根文件系统镜像放在同一目录下，后续说明以标准根文件系统为例(initrd)。 + + +极简运行场景 +============== + +该场景下，qemu未使能网络和共享文件系统，适合快速的功能体验。 + +针对arm(ARM Cortex A15)，运行如下命令： + +.. code-block:: console + + qemu-system-arm -M virt-4.0 -cpu cortex-a15 -nographic -kernel zImage -initrd initrd + +针对aarch64(ARM Cortex A57)，运行如下命令： + +.. code-block:: console + + qemu-system-aarch64 -M virt-4.0 -cpu cortex-a57 -nographic -kernel zImage -initrd initrd + + +由于标准根文件系统镜像进行了安全加固，因此第一次启动时，需要为登录用户名root设置密码，且密码强度有相应要求， 需要数字、字母、特殊字符组合最少8位，例如openEuler@2021。当使用极简根文件系统镜像时，系统会自动登录, 无需输入用户名和密码。 + +qemu运行成功并登录后，将会呈现openEuler Embedded的Shell。 + +使能共享文件系统场景 +========================== + +通过共享文件系统，可以使得运行qemu仿真器的宿主机和openEuler Embedded共享文件，这样在宿主机上交叉编译的程序，拷贝到共享目录中，即可在openEuler Embedded上运行。 + +假设将宿主机的/tmp目录作为共享目录，并事先在其中创建了名为hello_openeuler.txt的文件，使能共享文件系统功能的操作指导如下： + +1. **启动qemu** + +针对arm(ARM Cortex A15)，运行如下命令： + +.. code-block:: console + + qemu-system-arm -M virt-4.0 -cpu cortex-a15 -nographic -kernel zImage -initrd initrd -device virtio-9p-device,fsdev=fs1,mount_tag=host -fsdev local,security_model=passthrough,id=fs1,path=/tmp + +针对aarch64(ARM Cortex A57)，运行如下命令： + +.. code-block:: console + + qemu-system-aarch64 -M virt-4.0 -cpu cortex-a57 -nographic -kernel zImage -initrd initrd -device virtio-9p-device,fsdev=fs1,mount_tag=host -fsdev local,security_model=passthrough,id=fs1,path=/tmp + + +2. **映射文件系统** + +在openEuler Embedded启动并登录之后，需要运行如下命令，映射(mount)共享文件系统 + +.. code-block:: console + + cd /tmp + mkdir host + mount -t 9p -o trans=virtio,version=9p2000.L host /tmp/host + +即把共享文件系统映射到openEuler Embedded的/tmp/host目录下。 + +3. **检查共享是否成功** + +在openEuler Embedded中，运行如下命令: + +.. code-block:: console + + cd /tmp/host + ls + +如能发现hello_openeuler.txt，则共享成功。 + +使能网络场景 +=============== + +通过qemu的virtio-net和宿主机上的虚拟网卡，可以实现宿主机和openEuler embedded之间的网络通信。 + +1. **启动qemu** + +针对arm(ARM Cortex A15)，运行如下命令： + +.. code-block:: console + + qemu-system-arm -M virt-4.0 -cpu cortex-a15 -nographic -kernel zImage -initrd initrd -device virtio-net-device,netdev=tap0 -netdev tap,id=tap0,script=/etc/qemu-ifup + +针对aarch64(ARM Cortex A57)，运行如下命令： + +.. code-block:: console + + qemu-system-aarch64 -M virt-4.0 -cpu cortex-a57 -nographic -kernel zImage -initrd initrd -device virtio-net-device,netdev=tap0 -netdev tap,id=tap0,script=/etc/qemu-ifup + +2. **宿主上建立虚拟网卡** + +在宿主机上需要建立名为tap0的虚拟网卡，可以借助/etc/qemu-ifup脚本实现，其执行需要root权限，具体内容如下： + +.. code-block:: console + + #!/bin/bash + ifconfig $1 192.168.10.1 up + +通过qemu-ifup脚本，宿主机上将创建名为tap0的虚拟网卡，地址为192.168.10.1。 + +3. **配置openEuler embedded网卡** + +openEuler Embedded登陆后，执行如下命令： + +.. code-block:: console + + ifconfig eth0 192.168.10.2 + + +4. **确认网络连通** + +在openEuler Embedded中，执行如下命令： + +.. code-block:: console + + ping 192.168.10.1 + +如能ping通，则宿主机和openEuler Embedded之间的网络是连通的。 + +.. note:: + + 如需openEuler embedded借助宿主机访问互联网，则需要在宿主机上建立网桥，此处不详述，如有需要，请自行查阅相关资料。 + + + +基于openEuler embedded的用户态应用开发 +******************************************** + +当前发布的镜像除了体验openEuler Embedded的基本功能外，还可以进行基本的用户态应用开发，也即在openEuler embedded上运行用户自己的程序。 + + +1. **环境准备** + +由于当前镜像采用了linaro arm/aarch64 gcc 7.3.1工具链构建，因此建议应用开发也使用相同的工具链接进行，可以从如下链接中获取相应工具链： + +- `linaro arm `_ +- `linrao arm sysroot `_ +- `linaro aarch64 `_ +- `linrao aarch64 sysroot `_ + +下载并解压到指定的目录中，例如/opt/openEuler_toolchain。 + +2. **创建并编译用户态程序** + +以构建一个hello openEuler程序为例，运行在aarch64的标准根文件系统镜像中。 + +在宿主机中，创建一个hello.c文件，源码如下： + +.. code-block:: c + + #include + + int main(void) + { + printf("hello openEuler\r\n"); + } + +然后在宿主机上使用对应的工具链编译, 相应命令如下： + +.. code-block:: console + + export PATH=$PATH:/opt/openEuler_toolchain/gcc-linaro-7.3.1-2018.05-x86_64_aarch64-linux-gnu/bin + aarch64-linux-gnu-gcc --sysroot= hello.c -o hello + mv hello /temp + +把交叉编译好的hello程序拷贝到/tmp目录下，然后参照使能共享文件系统中的描述，使得openEuler embedded可以访问宿主机的目录。 + +3. **运行用户态程序** + +在openEuler embedded中运行hello程序。 + +.. code-block:: console + + cd /tmp/host + ./hello + +如运行成功，openEuler Embedded的shell中就会输出hello openEuler。 diff --git a/docs/source/index.rst b/docs/source/index.rst index 1b4432eea7d..e95546675f7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,40 +3,24 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -=========================================== + openeuler embedded yocto原理介绍及使用指导 =========================================== -1.Openeuler yocto 基础框架 -===================================== -https://docs.yoctoproject.org/overview-manual/yp-intro.html# - -1.1 yocto是什么 ------------------- -https://docs.yoctoproject.org/overview-manual/yp-intro.html#what-is-the-yocto-project -https://docs.yoctoproject.org/overview-manual/yp-intro.html#the-yocto-project-layer-model - - -1.2 主要组件和工具 ------------------- -https://docs.yoctoproject.org/overview-manual/yp-intro.html#components-and-tools -https://docs.yoctoproject.org/overview-manual/yp-intro.html#the-openembedded-build-system-workflow -https://docs.yoctoproject.org/overview-manual/concepts.html - -1.2.1 bitbake -^^^^^^^^^^^^^^^^ - -1.2.2 oe-core -^^^^^^^^^^^^^^^^ -1.2.3 Poky -^^^^^^^^^^^^^^^^ -https://docs.yoctoproject.org/overview-manual/yp-intro.html#reference-embedded-distribution-poky -1.2.4 opkg -^^^^^^^^^^^^^^^^ +章节 +***** +.. toctree:: + :maxdepth: 1 + :caption: 内容 + introduction/index.rst + getting_started/index.rst + features/index.rst + yocto/index.rst + releases/index.rst -Indices and tables -================== +索引与表格 +*********** diff --git a/docs/source/introduction/index.rst b/docs/source/introduction/index.rst new file mode 100644 index 00000000000..b49a79b7861 --- /dev/null +++ b/docs/source/introduction/index.rst @@ -0,0 +1,10 @@ +.. _introducing_openeuler_embedded: + + +介绍 +##### + + + +主要特点 +********** \ No newline at end of file diff --git a/docs/source/releases/index.rst b/docs/source/releases/index.rst new file mode 100644 index 00000000000..0b6da249778 --- /dev/null +++ b/docs/source/releases/index.rst @@ -0,0 +1,12 @@ +.. _release_notes: + +版本说明 +######### + + +.. toctree:: + :maxdepth: 1 + :glob: + :reversed: + + release-notes-* diff --git a/docs/source/releases/release-notes-21.09.30.rst b/docs/source/releases/release-notes-21.09.30.rst new file mode 100644 index 00000000000..b0aa9826cbb --- /dev/null +++ b/docs/source/releases/release-notes-21.09.30.rst @@ -0,0 +1,9 @@ +:orphan: + +.. _openeuler_embedded_21_09_30: + +openEuler embedded 21.09.30 +########################### + +openEuler embedded 21.09.30的主要特性包括： + diff --git a/docs/source/releases/release-notes-22.03.30.rst b/docs/source/releases/release-notes-22.03.30.rst new file mode 100644 index 00000000000..4387d4e67e9 --- /dev/null +++ b/docs/source/releases/release-notes-22.03.30.rst @@ -0,0 +1,9 @@ +:orphan: + +.. _openeuler_embedded_22_03_30: + +openEuler embedded 22.03.30 +########################### + +openEuler embedded 22.03.30的主要特性包括： + diff --git a/docs/source/yocto/index.rst b/docs/source/yocto/index.rst new file mode 100644 index 00000000000..3153929042b --- /dev/null +++ b/docs/source/yocto/index.rst @@ -0,0 +1,30 @@ +.. _yocto: + +Openeuler yocto 基础框架 +################################ +https://docs.yoctoproject.org/overview-manual/yp-intro.html# + +1.1 yocto是什么 +******************* + +https://docs.yoctoproject.org/overview-manual/yp-intro.html#what-is-the-yocto-project +https://docs.yoctoproject.org/overview-manual/yp-intro.html#the-yocto-project-layer-model + + +1.2 主要组件和工具 +******************** + + +https://docs.yoctoproject.org/overview-manual/yp-intro.html#components-and-tools +https://docs.yoctoproject.org/overview-manual/yp-intro.html#the-openembedded-build-system-workflow +https://docs.yoctoproject.org/overview-manual/concepts.html + +1.2.1 bitbake +^^^^^^^^^^^^^^^^ + +1.2.2 oe-core +^^^^^^^^^^^^^^^^ + +1.2.3 Poky +^^^^^^^^^^^^^^^^ +https://docs.yoctoproject.org/overview-manual/yp-intro.html#reference-embedded-distribution-poky \ No newline at end of file -- Gitee