├── README.md ├── at ├── at.md └── figures │ ├── at_framework.jpg │ └── at_multiple_client.jpg ├── basic ├── basic.md └── figures │ ├── 03Memory_distribution.png │ ├── 03Startup_process.png │ ├── 03kernel_Framework.png │ ├── 03kernel_object.png │ └── 03kernel_object2.png ├── contribution_guide ├── contribution_guide.md └── figures │ ├── add_usb_driver.png │ ├── branch.png │ ├── checkok.png │ ├── cla.png │ ├── cloneformgit.png │ ├── cloneformgit2.png │ ├── git_clone.png │ ├── pr_description.png │ └── pull_request_step2.png ├── device ├── adc │ ├── adc.md │ └── figures │ │ └── adc-p.png ├── device.md ├── figures │ ├── block-dev.png │ ├── io-call.png │ ├── io-dev.png │ ├── io-fun-call.png │ ├── io-parent.png │ └── wtd-uml.png ├── hwtimer │ └── hwtimer.md ├── i2c │ ├── figures │ │ ├── i2c1.png │ │ ├── i2c2.png │ │ └── i2c3.png │ └── i2c.md ├── pin │ ├── figures │ │ └── pin2.png │ └── pin.md ├── pwm │ ├── figures │ │ ├── pwm-f.png │ │ └── pwm-l.png │ └── pwm.md ├── rtc │ └── rtc.md ├── sensor │ └── sensor.md ├── spi │ ├── figures │ │ ├── spi1.png │ │ ├── spi2.png │ │ └── spi5.png │ └── spi.md ├── uart │ ├── figures │ │ ├── uart-dma.png │ │ ├── uart-int.png │ │ └── uart1.png │ └── uart.md ├── watchdog │ └── watchdog.md └── wlan │ ├── figures │ ├── an0026_1.png │ ├── an0026_3.png │ ├── an0026_4.png │ └── an0026_5.png │ └── wlan.md ├── dlmodule └── README.md ├── env ├── env.md └── figures │ ├── Add_Env_To_Right-click_Menu-1.png │ ├── Add_Env_To_Right-click_Menu-2.png │ ├── Add_Env_To_Right-click_Menu-3.png │ ├── cd_cmd.png │ ├── console.png │ ├── hotkey.png │ ├── menuconfig_packages_list.png │ ├── menuconfig_s.png │ ├── menuconfig_s_auto_prj.png │ ├── menuconfig_s_auto_update.png │ ├── q1.png │ ├── scons_done.png │ └── use_scons.png ├── figures └── 02Software_framework_diagram.png ├── filesystem ├── README.md └── figures │ ├── elm-fat-mkfs.png │ ├── fs-dir-mg.png │ ├── fs-dir.png │ ├── fs-layer.png │ ├── fs-mg.png │ ├── fs-reg-block.png │ └── fs-reg.png ├── finsh ├── figures │ ├── finsh-hd.png │ ├── finsh-mdk.png │ └── finsh-run.png └── finsh.md ├── interrupt ├── figures │ ├── 09fun1.png │ ├── 09fun2.png │ ├── 09interrupt_handle.png │ ├── 09interrupt_ops.png │ ├── 09interrupt_reque.png │ ├── 09interrupt_table.png │ ├── 09interrupt_work.png │ ├── 09interrupt_work_process.png │ ├── 09interrupt_work_sta.png │ ├── 09relation.png │ └── 09ths_switch.png └── interrupt.md ├── introduction ├── figures │ └── 02Software_framework_diagram.png └── introduction.md ├── kernel-porting ├── figures │ ├── 10pendsv.png │ ├── 10stack.png │ ├── 10switch.png │ ├── 10switch2.png │ ├── 10ths_env1.png │ └── 10ths_env2.png └── kernel-porting.md ├── memory ├── figures │ ├── 08Memory_distribution.png │ ├── 08heap_ops.png │ ├── 08memheap.png │ ├── 08mempool.png │ ├── 08mempool_ops.png │ ├── 08mempool_work.png │ ├── 08slab.png │ ├── 08smem_work.png │ ├── 08smem_work2.png │ └── 08smem_work3.png └── memory.md ├── network ├── figures │ ├── net-hello.png │ ├── net-layer.png │ ├── net-osi.png │ ├── net-recv.png │ ├── net-send.png │ ├── net-tcp-s.png │ ├── net-tcp.png │ ├── net-udp-client.png │ ├── net-udp-server.png │ └── net-udp.png └── network.md ├── pm ├── figures │ ├── pm_architecture.png │ ├── pm_description.png │ ├── pm_sequence.png │ └── pm_system.png └── pm.md ├── posix └── README.md ├── quick-start ├── figures │ ├── 10.png │ ├── 11.png │ ├── 14.png │ ├── 5.png │ ├── 6.png │ ├── 7.png │ ├── 8.png │ ├── 9.png │ ├── compile.jpg │ └── debug.jpg ├── keil-installation │ ├── figures │ │ ├── 1.png │ │ ├── 12.png │ │ ├── 13.png │ │ ├── 2.png │ │ ├── 3.png │ │ └── 4.png │ └── keil-installation.md ├── quick-start.md ├── quick_start_qemu │ ├── figures │ │ ├── echo-cat.png │ │ ├── env.png │ │ ├── env_menu.png │ │ ├── env_menu_ubuntu.png │ │ ├── finsh-cmd.png │ │ ├── finsh-thread.png │ │ ├── menuconfig.png │ │ ├── menuconfig_menu.png │ │ ├── mkfs-sd0.png │ │ ├── python3-version.png │ │ ├── qemu.bat.png │ │ ├── qemu.png │ │ ├── qemubsp.png │ │ ├── scons.png │ │ ├── ubuntu-env-menu.png │ │ ├── ubuntu-filesys.png │ │ ├── ubuntu-menuconfig.png │ │ ├── ubuntu-mkfs-sd0.png │ │ ├── ubuntu-msh-help.png │ │ ├── ubuntu-pkg-menuconfig.png │ │ ├── ubuntu-pkg-set.png │ │ ├── ubuntu-pkgs-add-to-menu.png │ │ ├── ubuntu-qemu-bsp.png │ │ ├── ubuntu-qume-sh.png │ │ ├── ubuntu-rtconfig-py.png │ │ ├── ubuntu-save.png │ │ ├── ubuntu-scons.png │ │ ├── ubuntu-select-pkg.png │ │ ├── ubuntu-thread-timer.png │ │ ├── ubuntu-update-pkg.png │ │ └── win-menuconfig.png │ ├── quick_start_qemu.md │ └── quick_start_qemu_linux.md ├── rtthread_simulator_v0.1.0.7z └── rtthread_simulator_v0.1.0.zip ├── sal ├── figures │ └── sal_frame.jpg └── sal.md ├── scons ├── figures │ ├── hello-menu.png │ ├── hello-rtconfig.png │ ├── hello-value.png │ ├── hello.png │ ├── kconfig.png │ └── scons.png └── scons.md ├── thread-comm ├── figures │ ├── 07mb_ops.png │ ├── 07mb_work.png │ ├── 07msg_ops.png │ ├── 07msg_syn.png │ ├── 07msg_work.png │ ├── 07signal_ops.png │ └── 07signal_work.png └── thread-comm.md ├── thread-sync ├── figures │ ├── 06event_ops.png │ ├── 06event_use.png │ ├── 06event_work.png │ ├── 06inter_ths_commu1.png │ ├── 06inter_ths_commu2.png │ ├── 06mutex_ops.png │ ├── 06mutex_work.png │ ├── 06priority_inherit.png │ ├── 06priority_inversion.png │ ├── 06sem_lock.png │ ├── 06sem_ops.png │ └── 06sem_work.png └── thread-sync.md ├── thread ├── figures │ ├── 04Object_container.png │ ├── 04Task_switching.png │ ├── 04main_thread.png │ ├── 04thread_ops.png │ ├── 04thread_sta.png │ ├── 04thread_stack.png │ └── 04time_slience.png └── thread.md ├── timer ├── figures │ ├── 05timer_env.png │ ├── 05timer_linked_list.png │ ├── 05timer_linked_list2.png │ ├── 05timer_ops.png │ ├── 05timer_skip_list.png │ ├── 05timer_skip_list2.png │ └── 05timer_skip_list3.png └── timer.md ├── ulog ├── figures │ ├── ulog_async_vs_sync.png │ ├── ulog_example.png │ ├── ulog_example_all_format.png │ ├── ulog_example_async.png │ ├── ulog_example_filter20.png │ ├── ulog_example_filter30.png │ ├── ulog_example_filter40.png │ ├── ulog_example_hexdump.png │ ├── ulog_example_syslog.png │ ├── ulog_framework.png │ ├── ulog_framework_backend.png │ ├── ulog_menuconfig_async.png │ ├── ulog_menuconfig_format.png │ └── ulog_syslog_format.png └── ulog.md └── utest ├── figures ├── UtestAppStruct-1.png ├── UtestRunLogShow.png └── testcase-runflowchart.jpg └── utest.md /README.md: -------------------------------------------------------------------------------- 1 | # Attention 2 | ## ⚠️ This repository is no longer maintained any more. Please move to: https://github.com/RT-Thread/rt-thread/tree/master/documentation 3 | 4 | 5 | # RT-Thread 6 | 7 | RT-Thread (Real-Time Thread) is an open source embedded real-time operating system and released under Apache License v2.0. It has a strong scalability: from a nano kernel running on a tiny MCU, for example ARM Cortex-M0, or Cortex-M3/4/7, to a rich feature system running on MIPS32, ARM Cortex-A, even the emerging open source RISC-V architecture is supported. RT-Thread can run either on single-core systems or on symmetric multi-core processors(SMP) systems. 8 | 9 | ## Introduction 10 | 11 | RT-Thread has not noly a real-time kernel, but also rich components. Its architecture is as follows: 12 | 13 | ![RT-Thread system framework](figures/02Software_framework_diagram.png) 14 | 15 | - **Kernel**: It includes preemptive multi-task real-time scheduler, and infrastructure such as semaphore, mutex, mailbox, message queue, signal, event, memory management, timer management, interrupt management, etc. It also includes libcpu/BSP (file related to chip transplantation/board support package). 16 | - **components**: It is a software unit on the RT-Thread kernel layer, such as command line (FinSH), device driver framework (Device Drivers), network framework, virtual file system (FAT, YAFFS, UFFS, ROM/RAM file system, etc.), TCP/IP network protocol stack (lwIP), libc/POSIX standard layer and so on. Generally, a software component is placed in a folder in the RT-Thread/components directory, and each software component is described by a *SConscript* file and added to the RT-Thread construction system. When a software component is opened in the system configuration, it will be compiled and linked to the final RT-Thread firmware. 17 | - **Packages**: It is a middleware running on RT-Thread IoT operating system platform and facing different application fields. Packages consist of description information, source code or library files. These packages can be provided by RT-Thread, third-party developers and enterprises, and the license agreement of the packages is provided by the author of the packages. These software packages have strong reusability and high modularity, which greatly facilitates application developers to build their desired application systems in the shortest time. For more package information, visit the [RT-Thread package repository](https://github.com/RT-Thread-packages). 18 | 19 | ## Licence 20 | 21 | RT-Thread is an open source software and has been licensed under Apache License Version 2.0 since v3.1.1. License information and copyright information can generally be seen at the beginning of the code: 22 | 23 | ``` 24 | /* 25 | * Copyright (c) 2006-2018, RT-Thread Development Team 26 | * 27 | * SPDX-License-Identifier: Apache-2.0 28 | */ 29 | ``` 30 | 31 | To avoid possible future license conflicts, developers need to sign a Contributor License Agreement (CLA) when submitting PR to RT-Thread. 32 | 33 | > Note: Because the BSP also contains the code provided by the chip manufacturer, this part of the code follows the license provided by the chip manufacturer, such as STM32 HAL, NXP, Atmel, etc. Relevant codes are usually only used in the chips of the corresponding manufacturers. 34 | 35 | ## Supported Architectures 36 | 37 | RT-Thread RTOS can support many architectures,and has covered the major architectures in current applications. Architecture and chip manufacturer involved: 38 | 39 | - **ARM Cortex-M0/M0+**：manufacturers like ST 40 | - **ARM Cortex-M3**：manufacturers like ST、Winner Micro、MindMotion, ect. 41 | - **ARM Cortex-M4**：manufacturers like ST、Nuvton、NXP、GigaDevice、Realtek、Ambiq Micro, ect. 42 | - **ARM Cortex-M7**：manufacturers like ST、NXP 43 | - **ARM Cortex-M23**：manufacturers like GigaDevice 44 | - **ARM Cortex-R4** 45 | - **ARM Cortex-A8/A9**：manufacturers like NXP 46 | - **ARM7**：manufacturers like Samsung 47 | - **ARM9**：manufacturers like Allwinner、Xilinx 、GOKE 48 | - **ARM11**：manufacturers like Fullhan 49 | - **MIPS32**：manufacturers like loongson、Ingenic 50 | - **RISC-V**：manufacturers like Hifive、Kendryte 51 | - **ARC**：manufacturers like SYNOPSYS 52 | - **DSP**：manufacturers like TI 53 | - **C-Sky** 54 | - **x86** 55 | 56 | ## Supported IDE and Compiler 57 | 58 | The main IDE/compilers supported by RT-Thread are: 59 | 60 | - MDK KEIL 61 | - IAR 62 | - GCC 63 | 64 | Use Python-based [scons](http://www.scons.org) for command-line builds. 65 | 66 | # Source Code and Tools 67 | 68 | **Get the source code**: The source code of RT-Thread is hosted on Github, and click on the link to get the source code. 69 | 70 | - [Download RT-Thread source code](https://github.com/RT-Thread/rt-thread) 71 | 72 | **Get the Env Tool**: To better help developers, the RT-Thread team also provides Env tools (or Env scripts for Linux/MacOS). On Windows, Env tool is a development assistant tool launched by RT-Thread. It provides compiling and building environment, graphical system configuration and software package management functions for project projects based on RT-Thread operating system. Its built-in menuconfig provides a simple and easy-to-use configuration tailoring tool, which can tailor the kernel, components and software packages freely, so that the system can be built in the way of building blocks. 73 | 74 | - [Download Env Tool]() 75 | - [User manual of Env](env/env.md) 76 | 77 | # Getting Started 78 | 79 | RT-Thread BSP can be compiled directly and downloaded to the corresponding development board for use. In addition, RT-Thread also provides qemu-vexpress-a9 BSP, which can be used without hardware platform. See the getting started guide below for details. 80 | 81 | - [Getting Started of QEMU (Windows)](quick-start/quick_start_qemu/quick_start_qemu.md) 82 | - [Getting Started of QEMU (Ubuntu)](quick-start/quick_start_qemu/quick_start_qemu_linux.md) 83 | 84 | # Help 85 | 86 | Any questions can be asked in the [issue section of rtthread-manual-doc](https://github.com/RT-Thread/rtthread-manual-doc/issues). By creating a new issue to describe your questions, community members will answer them. 87 | 88 | # Contribution 89 | 90 | If you are interested in RT-Thread and want to join in the development of RT-Thread and become a code contributor,please refer to the [Code Contribution Guide](documentation/contribution_guide/contribution_guide.md). 91 | 92 | # Manual Catalogue 93 | 94 | - [RT-Thread Introduction](introduction/introduction.md) 95 | - [Start Guide: Simulate STM32F103 on KEIL simulator](quick-start/quick-start.md) 96 | 97 | **Kernel** 98 | 99 | - [Kernel Basics](basic/basic.md) 100 | - [Thread Management](thread/thread.md) 101 | - [Clock&Timer Management](timer/timer.md) 102 | - [Inter-thread Synchronization](thread-sync/thread-sync.md) 103 | - [Inter-thread Communication](thread-comm/thread-comm.md) 104 | - [Memory Management](memory/memory.md) 105 | - [Interrupt Management](interrupt/interrupt.md) 106 | - [Kernel Porting](kernel-porting/kernel-porting.md) 107 | 108 | **Tool** 109 | 110 | - [User Manual of Env](env/env.md) 111 | - [SCons](scons/scons.md) 112 | 113 | **Device** 114 | 115 | - [I/O Device Framework](device/device.md) 116 | - [PIN Device](device/pin/pin.md) 117 | - [UART Device](device/uart/uart.md) 118 | - [ADC Device](device/adc/adc.md) 119 | - [I2C Bus Device](device/i2c/i2c.md) 120 | - [SPI Device](device/spi/spi.md) 121 | - [PWM Device](device/pwm/pwm.md) 122 | - [RTC Device](device/rtc/rtc.md) 123 | - [HWTIMER Device](device/hwtimer/hwtimer.md) 124 | - [WATCHDOG Device](device/watchdog/watchdog.md) 125 | - [WLAN Device](device/wlan/wlan.md) 126 | - [Sensor Device](device/sensor/sensor.md) 127 | 128 | **Components** 129 | 130 | - [FinSH Console](finsh/finsh.md) 131 | - [Virtual File System](filesystem/README.md) 132 | - [utest Framework](utest/utest.md) 133 | - [Dynamic Module: dlmodule](dlmodule/README.md) 134 | - [Socket Abstraction Layer: SAL](sal/sal.md) 135 | - [AT Commands](at/at.md) 136 | - [POSIX Interface](posix/README.md) 137 | - [Ulog Log](ulog/ulog.md) 138 | - [Power Management: PM](pm/pm.md) 139 | - [Network Framework](network/network.md) 140 | 141 | -------------------------------------------------------------------------------- /at/figures/at_framework.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/at/figures/at_framework.jpg -------------------------------------------------------------------------------- /at/figures/at_multiple_client.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/at/figures/at_multiple_client.jpg -------------------------------------------------------------------------------- /basic/figures/03Memory_distribution.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/basic/figures/03Memory_distribution.png -------------------------------------------------------------------------------- /basic/figures/03Startup_process.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/basic/figures/03Startup_process.png -------------------------------------------------------------------------------- /basic/figures/03kernel_Framework.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/basic/figures/03kernel_Framework.png -------------------------------------------------------------------------------- /basic/figures/03kernel_object.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/basic/figures/03kernel_object.png -------------------------------------------------------------------------------- /basic/figures/03kernel_object2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/basic/figures/03kernel_object2.png -------------------------------------------------------------------------------- /contribution_guide/contribution_guide.md: -------------------------------------------------------------------------------- 1 | # Contribution Guide 2 | 3 | We sincerely thank you for your contribution, and welcome to submit the code through GitHub's fork and Pull Request processes. 4 | 5 | First, explain the word Pull Request. Pull request means to send a request. The purpose of the developer initiating Pull Request is to request the repository maintainer to adopt the code submitted by the developer. 6 | 7 | When you want to correct mistakes in other people's repositories, follow the following procedure: 8 | 9 | - To fork someone else's repository is equivalent to copying someone else's information. Because you can't guarantee that your modification is correct and beneficial to the project, you can't modify it directly in someone else's repository, but first fork it into your own git repository. 10 | - Clone code to your own PC local, create a new branch, modify bugs or add new features, and then launch pull request to the original repository, so that the original repository manager can see the changes you submitted. 11 | - The original repository manager reviews this submission and, if correct, merge it into his own project. Merge means merging, merging the part of code you modified into the original repository to add code or replace the original code. So far, the whole Pull Request process is over. 12 | 13 | ## Coding Style 14 | 15 | Refer to the `coding_style_en.txt` file in the rt_thread project documentation directory for the RT-Thread code programming style. 16 | 17 | ## Preparation 18 | 19 | Install Git: You need to add Git's directory to the system environment variable. 20 | 21 | ## Contribution Process 22 | 23 | Now take RT-Thread repository as an example to illustrate the process of contributing code: 24 | 25 | ### Fork 26 | 27 | Fork the RT-Thread/rt-thread repository into your git repository. 28 | 29 | ![fork rt-thread repository](figures/cloneformgit.png) 30 | 31 | ### Clone 32 | 33 | In your repository, copy the repository links after your fork: 34 | 35 | ![clone rt-thread from your repo](figures/cloneformgit2.png) 36 | 37 | You can use the `git clone` command to copy the repository to your PC: 38 | 39 | ``` 40 | git clone [url] 41 | ``` 42 | 43 | ![git clone](figures/git_clone.png) 44 | 45 | ### Create a New Branch 46 | 47 | It is recommended that you create your own development branch based on the master branch, and use following commands to create a new branch: 48 | 49 | ``` 50 | git checkout -b YourBranchName 51 | ``` 52 | 53 | For example, create a branch named "dev": `git checkout -b dev`. 54 | 55 | ### Developing 56 | 57 | Modify bugs and submit new functional code. For example, suppose the developer adds a USB driver: 58 | 59 | ![Add a USB driver](figures/add_usb_driver.png) 60 | 61 | ### Temporarily Store Modified Files 62 | 63 | Add all changes to the temporary area: 64 | 65 | ``` 66 | git add . 67 | ``` 68 | 69 | If you only want to add some specified files to the temporary area, use other commands of `git add`. 70 | 71 | ### Commit 72 | 73 | Submit this modification to the local repository: 74 | 75 | ``` 76 | git commit -m "Describe your submission here" 77 | ``` 78 | 79 | > Note: If there are multiple commits in the local development branch, in order to ensure that the RT-Thread repository commit is clean, please tidy up the local commits. More than five commits are not accepted by Pull Request.。 80 | 81 | ### Push to Your Remote Repository 82 | 83 | Push the modified content to the branch of your remote repository. It is recommended that the branch name of the remote repository be consistent with the local branch name.Use the following command to push: 84 | 85 | ``` 86 | git push origin YourBranchName 87 | ``` 88 | 89 | ### Create a Pull Request 90 | 91 | Enter the RT-Thread repository under your Github account and click `New pull request -> Create pull request`. Make sure you choose the right branch. 92 | 93 | ![Create a Pull Request](figures/pull_request_step2.png) 94 | 95 | Step 1: Fill in the title of this Pull Request 96 | 97 | Step 2: Modify the description information of this Pull Request (modify it in `Write` and preview it with `Preview`): 98 | 99 | - Modify PR Description: Replace the content in the red box below with the description of this pull request according to the requirements in the red box below. 100 | 101 | - Check PR Options: Fill in [x] in the OK Options check box to confirm. Note that there are no spaces on both sides of [x]. 102 | 103 | ![Modify PR Description and Check PR Options](figures/pr_description.png) 104 | 105 | Step 3：Create pull request. 106 | 107 | ### Sign CLA 108 | 109 | The first contribution to RT-Thread requires signing the *Contributor License Agreement*. 110 | 111 | ![Sign CLA](figures/cla.png) 112 | 113 | Make sure that CLA shows successful signing and CI compilation, as shown in the following figure: 114 | 115 | ![CLA successful](figures/checkok.png) 116 | 117 | Note: Do not submit commmit using a non-GitHub account, or commit using a different account, which can lead to CLA signing failure. 118 | 119 | ### Review Pull Request 120 | 121 | Once the request is successful, the RT-Thread maintainer can see the code you submitted. The code will be reviewed and comments will be filled in on GitHub. Please check the PR status in time and update the code according to the comments. 122 | 123 | ### Merge Pull Request 124 | 125 | If the Pull Request code is okay, the code will be merged into the RT-Thread repository. This time Pull Request succeeded. 126 | 127 | So far, we have completed a code contribution process. 128 | 129 | ## Keep in Sync with RT-Thread Repository 130 | 131 | The content of the RT-Thread GitHub repository is always updated. To develop based on the latest RT-Thread code, you need to update the local repository. 132 | 133 | After clone, the local master branch content is consistent with the master branch content of the RT-Thread repository. But when the RT-Thread repository is updated, your local code is different from the RT-Thread code. 134 | 135 | The local master is synchronized with the RT-Thread repository of your own GitHub account. If there is no content modification for the master branch (please create a new branch for development), then you can keep the local code synchronized with the RT-Thread repository according to the following steps: 136 | 137 | - To view the existing remote repository, there is usually only one default origin, which is your own remote repository: 138 | 139 | ```c 140 | $ git remote -v 141 | origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) 142 | origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) 143 | ``` 144 | 145 | * Add the RT-Thread remote repository and name it `rtt`, or you can customize the name by yourself: 146 | 147 | ```c 148 | $ git remote add rtt https://github.com/RT-Thread/rt-thread.git 149 | ``` 150 | 151 | * View all remote repositories tracked locally: 152 | 153 | ```c 154 | $ git remote -v 155 | origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) 156 | origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) 157 | rtt https://github.com/RT-Thread/rt-thread.git (fetch) 158 | rtt https://github.com/RT-Thread/rt-thread.git (push) 159 | ``` 160 | 161 | * Pull the code from the master branch of RT-Thread remote repository and merge it into the local master branch: 162 | 163 | ```c 164 | git pull rtt master 165 | ``` 166 | 167 | ## Reference 168 | 169 | * Refer to the [*GitHub - Contributing to a Project*](https://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) section of the official Git document for details. 170 | 171 | 172 | -------------------------------------------------------------------------------- /contribution_guide/figures/add_usb_driver.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/add_usb_driver.png -------------------------------------------------------------------------------- /contribution_guide/figures/branch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/branch.png -------------------------------------------------------------------------------- /contribution_guide/figures/checkok.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/checkok.png -------------------------------------------------------------------------------- /contribution_guide/figures/cla.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/cla.png -------------------------------------------------------------------------------- /contribution_guide/figures/cloneformgit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/cloneformgit.png -------------------------------------------------------------------------------- /contribution_guide/figures/cloneformgit2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/cloneformgit2.png -------------------------------------------------------------------------------- /contribution_guide/figures/git_clone.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/git_clone.png -------------------------------------------------------------------------------- /contribution_guide/figures/pr_description.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/pr_description.png -------------------------------------------------------------------------------- /contribution_guide/figures/pull_request_step2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/contribution_guide/figures/pull_request_step2.png -------------------------------------------------------------------------------- /device/adc/adc.md: -------------------------------------------------------------------------------- 1 | # ADC Device 2 | 3 | ## An Introduction to ADC 4 | 5 | ADC refers to analog to digital converter which is a device that converts continuously changing analog signals into discrete digital signals. Analog signals , such as temperature, pressure, sound, or images, need to be converted into digital forms that are easier to be stored, processed, and transmitted. The analog-to-digital converter can do this, and it can be found in a variety of different products. The corresponding DAC (Digital-to-Analog Converter) has a reverse conversion process compared to that of the ADC. The ADC was first used to convert wireless signals to digital signals such as television signals, or signals from long-short broadcast stations. 6 | 7 | ### Conversion Process 8 | 9 | As shown in the figure below, the analog-to-digital conversion generally involves steps of sampling, holding, quantifying, and encoding. In actual circuits, some processes are combined, such as sampling and holding, and quantization and encoding are implemented simultaneously in the conversion process. 10 | 11 | ![ADC Conversion Process](figures/adc-p.png) 12 | 13 | Sampling is the conversion of analog signals that changes continuously over time into time-discrete analog signals. It takes a certain amount of time for the analog signals obtained by sampling to be converted into digital signals. In order to provide a stable value for the subsequent quantization coding process, it is required to keep the sampling analog signals for a period of time after the sampling circuit. 14 | 15 | The process of converting a numerically continuous analog quantity into a digital quantity is called quantization. Digital signals are discrete numerically. The output voltage of the sample-and-hold circuit also needs to be naturalized to a corresponding discrete level in a similar way, and any digital quantity can only be an integer multiple of a certain minimum quantity unit. The quantized value also requires the encoding process, which is the digital output of the A/D converter. 16 | 17 | ### Resolution 18 | 19 | The resolution is expressed in binary (or decimal) digits. Generally, there are 8 bits, 10 bits, 12 bits, 16 bits, etc. It explains the resolution capability of the input signals by the analog-to-digital converter. The more bits, the higher the resolution, and the more accurate the analog signal will be. 20 | 21 | ### Precision 22 | 23 | Precision represents the maximum error value between the analog and real values of the ADC devices at all numerical points, that is, the distance at which the output value deviates from the linear maximum. 24 | 25 | >Precision and resolution are two different concepts, so please pay attention to the distinction. 26 | 27 | ### Conversion Rate 28 | 29 | The conversion rate is the reciprocal of the time it takes for the A/D converter to complete an AD conversion from analog to digital. For example, an A/D converter with a conversion rate of 1MHz means that an AD conversion time is 1 microsecond. 30 | 31 | ## Access ADC Device 32 | 33 | The application accesses the ADC hardware through the ADC device management interface provided by RT-Thread. The relevant interfaces are as follows: 34 | 35 | | **Function** | Description | 36 | | --------------- | ------------------ | 37 | | rt_device_find() | Find device handles based on ADC device name | 38 | | rt_adc_enable() | Enable ADC devices | 39 | | rt_adc_read() | Read ADC device data | 40 | | rt_adc_disable() | Close the ADC device | 41 | 42 | ### Find ADC Devices 43 | 44 | The application gets the device handle based on the ADC device name, which in turn operates the ADC device. Functions for looking for devices are as follows: 45 | 46 | ```c 47 | rt_device_t rt_device_find(const char* name); 48 | ``` 49 | 50 | | **Parameter** | Description | 51 | | -------- | ---------------------------------- | 52 | | name | The name of the ADC device | 53 | | **Return** | —— | 54 | | Device handle | Finding the corresponding device will return to the corresponding device handle | 55 | | RT_NULL | No device found | 56 | 57 | In general, the names of the ADC device registered to the system are adc0, adc1, etc., and an usage example is as follows: 58 | 59 | ```c 60 | #define ADC_DEV_NAME "adc1" /* ADC device name */ 61 | rt_adc_device_t adc_dev; /* ADC device handle */ 62 | /* find the device */ 63 | adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME); 64 | ``` 65 | 66 | ### Enable ADC Channel 67 | 68 | Before reading the ADC device data, Use the following function to enable the device: 69 | 70 | ```c 71 | rt_err_t rt_adc_enable(rt_adc_device_t dev, rt_uint32_t channel); 72 | ``` 73 | 74 | | Parameter | Description | 75 | | ---------- | ------------------------------- | 76 | | dev | ADC device handle | 77 | | channel | ADC channel | 78 | | **Return** | —— | 79 | | RT_EOK | Succeed | 80 | | -RT_ENOSYS | Failed, the device operation method is empty | 81 | | Other error code | Failed | 82 | 83 | An usage example is as follows: 84 | 85 | ```c 86 | #define ADC_DEV_NAME "adc1" /* ADC device name */ 87 | #define ADC_DEV_CHANNEL 5 /* ADC channel */ 88 | rt_adc_device_t adc_dev; /* ADC device handle */ 89 | /* find the device */ 90 | adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME); 91 | /* enable the device */ 92 | rt_adc_enable(adc_dev, ADC_DEV_CHANNEL); 93 | ``` 94 | 95 | ### Read ADC Channel Sample Values 96 | 97 | Reading the ADC channel sample values can be done by the following function: 98 | 99 | ```c 100 | rt_uint32_t rt_adc_read(rt_adc_device_t dev, rt_uint32_t channel); 101 | ``` 102 | 103 | | Parameter | Description | 104 | | ---------- | ----------------- | 105 | | dev | ADC device handle | 106 | | channel | ADC channel | 107 | | **Return** | —— | 108 | | Read values | | 109 | 110 | An example of using the ADC sampled voltage value is as follows: 111 | 112 | ```c 113 | #define ADC_DEV_NAME "adc1" /* ADC device name */ 114 | #define ADC_DEV_CHANNEL 5 /* ADC channel */ 115 | #define REFER_VOLTAGE 330 /* Reference voltage 3.3V, data accuracy multiplied by 100 and reserve 2 decimal places*/ 116 | #define CONVERT_BITS (1 << 12) /* The number of conversion bits is 12 */ 117 | 118 | rt_adc_device_t adc_dev; /* ADC device handle */ 119 | rt_uint32_t value； 120 | /* find the device */ 121 | adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME); 122 | /* enable the device */ 123 | rt_adc_enable(adc_dev, ADC_DEV_CHANNEL); 124 | /* Read sampling values */ 125 | value = rt_adc_read(adc_dev, ADC_DEV_CHANNEL); 126 | /* Convert to the corresponding voltage value */ 127 | vol = value * REFER_VOLTAGE / CONVERT_BITS; 128 | rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100); 129 | ``` 130 | 131 | The calculation formula of the actual voltage value is: `sampling value * reference voltage/(1 << resolution digit)`. In the above example, variable *vol* was enlarged 100 times, so finally the integer part of voltage is obtained through *vol / 100*, and the decimal part of voltage is obtained through *vol % 100*. 132 | 133 | ### Close the ADC Channel 134 | 135 | Use the following function can close the ADC channel : 136 | 137 | ```c 138 | rt_err_t rt_adc_disable(rt_adc_device_t dev, rt_uint32_t channel); 139 | ``` 140 | 141 | | **Parameter** | **Description** | 142 | | ---------- | ------------------------------- | 143 | | dev | ADC device handle | 144 | | channel | ADC channel | 145 | | **Return** | —— | 146 | | RT_EOK | Succeed | 147 | | -RT_ENOSYS | Failed, the device operation method is empty | 148 | | Other error code | Failed | 149 | 150 | An example: 151 | 152 | ```c 153 | #define ADC_DEV_NAME "adc1" /* ADC device name */ 154 | #define ADC_DEV_CHANNEL 5 /* ADC channel */ 155 | rt_adc_device_t adc_dev; /* ADC device handle */ 156 | rt_uint32_t value； 157 | /* find the device */ 158 | adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME); 159 | /* enable the device */ 160 | rt_adc_enable(adc_dev, ADC_DEV_CHANNEL); 161 | /* read sampling values */ 162 | value = rt_adc_read(adc_dev, ADC_DEV_CHANNEL); 163 | /* convert to the corresponding voltage value */ 164 | vol = value * REFER_VOLTAGE / CONVERT_BITS; 165 | rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100); 166 | /* close the channel */ 167 | rt_adc_disable(adc_dev, ADC_DEV_CHANNEL); 168 | ``` 169 | 170 | ### FinSH Command 171 | 172 | Before using the device, you need to find out whether the device exists. You can use the command `adc probe` followed by the name of the registered ADC device. As follows: 173 | 174 | ```c 175 | msh >adc probe adc1 176 | probe adc1 success 177 | ``` 178 | 179 | A channel of the enabled device can use the command `adc enable` followed by the channel number. 180 | 181 | ```c 182 | msh >adc enable 5 183 | adc1 channel 5 enables success 184 | ``` 185 | 186 | To read data from a channel of an ADC device, you can use the command `adc read` followed by the channel number. 187 | 188 | ```c 189 | msh >adc read 5 190 | adc1 channel 5 read value is 0x00000FFF 191 | msh > 192 | ``` 193 | 194 | To close a channel of an ADC device, you can use the command `adc disable` followed by the channel number. 195 | 196 | ```c 197 | msh >adc disable 5 198 | adc1 channel 5 disable success 199 | msh > 200 | ``` 201 | 202 | ## ADC Device Usage Example 203 | 204 | The specific usage of the ADC device can refer to the following sample code. The main steps of the sample code are as follows: 205 | 206 | 1. First find the device handle based on the ADC device name “adc1”. 207 | 2. After the device is enabled, read the sample value of the corresponding channel 5 of the adc1 device, and then calculate the actual voltage value with the resolution of 12 bits and the reference voltage of 3.3V. 208 | 3. Finally close the corresponding channel of the ADC device. 209 | 210 | Running result: Print the raw and converted data which actually read , and print the calculated actual voltage value. 211 | 212 | ```c 213 | /* 214 | * Program Listing： ADC Device Usage Routines 215 | * The routine exports the adc_sample command to the control terminal 216 | * adc_sample Command call format: adc_sample 217 | * Program function: The voltage value is sampled by the ADC device and converted to a numerical value. 218 | * The sample code reference voltage is 3.3V and the number of conversion bits is 12 bits. 219 | */ 220 | 221 | #include 222 | #include 223 | 224 | #define ADC_DEV_NAME "adc1" /* ADC device name */ 225 | #define ADC_DEV_CHANNEL 5 /* ADC channel */ 226 | #define REFER_VOLTAGE 330 /* Reference voltage 3.3V, data accuracy multiplied by 100 and reserve 2 decimal places*/ 227 | #define CONVERT_BITS (1 << 12) /* The number of conversion bits is 12 */ 228 | 229 | static int adc_vol_sample(int argc, char *argv[]) 230 | { 231 | rt_adc_device_t adc_dev; 232 | rt_uint32_t value, vol; 233 | rt_err_t ret = RT_EOK; 234 | 235 | /* find the device */ 236 | adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME); 237 | if (adc_dev == RT_NULL) 238 | { 239 | rt_kprintf("adc sample run failed! can't find %s device!\n", ADC_DEV_NAME); 240 | return RT_ERROR; 241 | } 242 | 243 | /* enable the device */ 244 | ret = rt_adc_enable(adc_dev, ADC_DEV_CHANNEL); 245 | 246 | /* read sampling values */ 247 | value = rt_adc_read(adc_dev, ADC_DEV_CHANNEL); 248 | rt_kprintf("the value is :%d \n", value); 249 | 250 | /* convert to the corresponding voltage value */ 251 | vol = value * REFER_VOLTAGE / CONVERT_BITS; 252 | rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100); 253 | 254 | /* close the channel */ 255 | ret = rt_adc_disable(adc_dev, ADC_DEV_CHANNEL); 256 | 257 | return ret; 258 | } 259 | /* export to the msh command list */ 260 | MSH_CMD_EXPORT(adc_vol_sample, adc voltage convert sample); 261 | ``` 262 | 263 | 264 | 265 | -------------------------------------------------------------------------------- /device/adc/figures/adc-p.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/adc/figures/adc-p.png -------------------------------------------------------------------------------- /device/figures/block-dev.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/figures/block-dev.png -------------------------------------------------------------------------------- /device/figures/io-call.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/figures/io-call.png -------------------------------------------------------------------------------- /device/figures/io-dev.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/figures/io-dev.png -------------------------------------------------------------------------------- /device/figures/io-fun-call.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/figures/io-fun-call.png -------------------------------------------------------------------------------- /device/figures/io-parent.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/figures/io-parent.png -------------------------------------------------------------------------------- /device/figures/wtd-uml.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/figures/wtd-uml.png -------------------------------------------------------------------------------- /device/i2c/figures/i2c1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/i2c/figures/i2c1.png -------------------------------------------------------------------------------- /device/i2c/figures/i2c2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/i2c/figures/i2c2.png -------------------------------------------------------------------------------- /device/i2c/figures/i2c3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/i2c/figures/i2c3.png -------------------------------------------------------------------------------- /device/i2c/i2c.md: -------------------------------------------------------------------------------- 1 | # I2C Bus Device 2 | 3 | ## Introduction of I2C 4 | 5 | The I2C (Inter Integrated Circuit) bus is a half-duplex, bidirectional two-wire synchronous serial bus developed by PHILIPS. The I2C bus has only two signal lines, one is the bidirectional data line SDA (serial data), and the other is the bidirectional clock line SCL (serial clock). The SPI bus has two lines for receiving data and transmitting data between the master and slave devices, while the I2C bus uses only one line for data transmission and reception. 6 | 7 | Like SPI, I2C works in a master-slave manner. Unlike SPI-master-multi-slave architecture, it allows multiple master devices to exist at the same time. Each device connected to the bus has a unique address, and the master device initiates data transfer, and generates a clock signal. The slave device is addressed by the master device, and only one master device is allowed at a time. As shown below: 8 | 9 | ![I2C Bus master-slave device connection mode](figures/i2c1.png) 10 | 11 | The main data transmission format of the I2C bus is shown in the following figure: 12 | 13 | ![I2C Bus Data Transmission Format](figures/i2c2.png) 14 | 15 | When the bus is idle, both SDA and SCL are in a high state. When the host wants to communicate with a slave, it will send a start condition first, then send the slave address and read and write control bits, and then transfer the data (host send or receive data). The host will send a stop condition when the data transfer ends. Each byte transmitted is 8 bits, with the high bit first and the low bit last. The different terms in the data transmission process are as follows: 16 | 17 | * **Starting Condition：** When SCL is high, the host pulls SDA low, indicating that data transfer is about to begin. 18 | 19 | * **Slave Address：** The first byte sent by the master is the slave address, the upper 7 bits are the address, the lowest bit is the R/W read/write control bit, R/W bit equals to 1 means the read operation, and 0 means the write operation. The general slave address has 7-bit address mode and 10-bit address mode. In the 10-bit address mode, the first 7 bits of the first byte are a combination of 11110XX, where the last two bits (XX) are two highest 10-bit addresses. The second byte is the remaining 8 bits of the 10-bit slave address, as shown in the following figure: 20 | 21 | ![7-bit address and 10-bit address format](figures/i2c3.png) 22 | 23 | * **Answer Signal：** Each time a byte of data is transmitted, the receiver needs to reply with an ACK (acknowledge). The slave sends an ACK when writing data and the ACK by the host when reading data. When the host reads the last byte of data, it can send NACK (Not acknowledge) and then stop the condition. 24 | 25 | * **Data：** After the slave address is sent, some commands may be sent, depending on the slave, and then the data transmission starts, and is sent by the master or the slave. Each data is 8 bits, and the number of bytes of data is not limited. 26 | 27 | * **Repeat Start Condition：** In a communication process, when the host may need to transfer data with different slaves or need to switch read and write operations, the host can send another start condition. 28 | 29 | * **Stop Condition：** When SDA is low, the master pulls SCL high and stays high, then pulls SDA high to indicate the end of the transfer. 30 | 31 | ## Access to I2C Bus Devices 32 | 33 | In general, the MCU's I2C device communicates as a master and slave. In the RT-Thread, the I2C master is virtualized as an I2C bus device. The I2C slave communicates with the I2C bus through the I2C device interface. The related interfaces are as follows: 34 | 35 | | **Function** | **Description** | 36 | | --------------- | ---------------------------------- | 37 | | rt_device_find() | Find device handles based on I2C bus device name | 38 | | rt_i2c_transfer() | transfer data | 39 | 40 | ### Finding I2C Bus Device 41 | 42 | Before using the I2C bus device, you need to obtain the device handle according to the I2C bus device name, so that you can operate the I2C bus device. The device function is as follows. 43 | 44 | ```c 45 | rt_device_t rt_device_find(const char* name); 46 | ``` 47 | 48 | | Parameter | Description | 49 | | -------- | ---------------------------------- | 50 | | name | I2C bus device name | 51 | | **Return Value** | —— | 52 | | device handle | Finding the corresponding device will return the corresponding device handle | 53 | | RT_NULL | No corresponding device object found | 54 | 55 | In general, the name of the I2C device registered to the system is i2c0, i2c1, etc. The usage examples are as follows: 56 | 57 | ```c 58 | #define AHT10_I2C_BUS_NAME "i2c1" /* Sensor connected I2C bus device name */ 59 | struct rt_i2c_bus_device *i2c_bus; /* I2C bus device handle */ 60 | 61 | /* Find the I2C bus device and get the I2C bus device handle */ 62 | i2c_bus = (struct rt_i2c_bus_device *)rt_device_find(name); 63 | ``` 64 | 65 | ### Data Transmission 66 | 67 | You can use `rt_i2c_transfer()` for data transfer by getting the I2C bus device handle. The function prototype is as follows: 68 | 69 | ```c 70 | rt_size_t rt_i2c_transfer(struct rt_i2c_bus_device *bus, 71 | struct rt_i2c_msg msgs[], 72 | rt_uint32_t num); 73 | ``` 74 | 75 | | Parameter | Description | 76 | |--------------------|----------------------| 77 | | bus | I2C bus device handle | 78 | | msgs[] | Message array pointer to be transmitted | 79 | | num | The number of elements in the message array | 80 | | **Return Value** | —— | 81 | | the number of elements in the message array | succeeded | 82 | | error code | failed | 83 | 84 | Like the custom transport interface of the SPI bus, the data transmitted by the custom transport interface of the I2C bus is also in units of one message. The parameter msgs[] points to the array of messages to be transmitted. The user can customize the content of each message to implement two different data transmission modes supported by the I2C bus. If the master needs to send a repeat start condition, it will need to send 2 messages. 85 | 86 | >This function will call rt_mutex_take(), which cannot be called inside the interrupt service routine, which will cause assertion to report an error. 87 | 88 | The prototypes of the I2C message data structure are as follows: 89 | 90 | ```c 91 | struct rt_i2c_msg 92 | { 93 | rt_uint16_t addr; /* Slave address */ 94 | rt_uint16_t flags; /* Reading, writing signs, etc. */ 95 | rt_uint16_t len; /* Read and write data bytes */ 96 | rt_uint8_t *buf; /* Read and write data buffer pointer　*/ 97 | } 98 | ``` 99 | 100 | Slave address (addr): Supports 7-bit and 10-bit binary addresses. You need to view the data sheets of different devices. 101 | 102 | >The slave address used by the RT-Thread I2C device interface does not contain read/write bits. The read/write bit control needs to modify the flag `flags`. 103 | 104 | The flags `flags` can be defined as macros that can be combined with other macros using the bitwise operation "|" as needed. 105 | 106 | ```c 107 | #define RT_I2C_WR 0x0000 /* Write flag */ 108 | #define RT_I2C_RD (1u << 0) /* Read flag */ 109 | #define RT_I2C_ADDR_10BIT (1u << 2) /* 10-bit address mode */ 110 | #define RT_I2C_NO_START (1u << 4) /* No start condition */ 111 | #define RT_I2C_IGNORE_NACK (1u << 5) /* Ignore NACK */ 112 | #define RT_I2C_NO_READ_ACK (1u << 6) /* Do not send ACK when reading */ 113 | ``` 114 | 115 | Examples of use are as follows: 116 | 117 | ```c 118 | #define AHT10_I2C_BUS_NAME "i2c1" /* Sensor connected I2C bus device name */ 119 | #define AHT10_ADDR 0x38 /* Slave address */ 120 | struct rt_i2c_bus_device *i2c_bus; /* I2C bus device handle */ 121 | 122 | /* Find the I2C bus device and get the I2C bus device handle */ 123 | i2c_bus = (struct rt_i2c_bus_device *)rt_device_find(name); 124 | 125 | /* Read sensor register data */ 126 | static rt_err_t read_regs(struct rt_i2c_bus_device *bus, rt_uint8_t len, rt_uint8_t *buf) 127 | { 128 | struct rt_i2c_msg msgs; 129 | 130 | msgs.addr = AHT10_ADDR; /* Slave address */ 131 | msgs.flags = RT_I2C_RD; /* Read flag */ 132 | msgs.buf = buf; /* Read and write data buffer pointer　*/ 133 | msgs.len = len; /* Read and write data bytes */ 134 | 135 | /* Call the I2C device interface to transfer data */ 136 | if (rt_i2c_transfer(bus, &msgs, 1) == 1) 137 | { 138 | return RT_EOK; 139 | } 140 | else 141 | { 142 | return -RT_ERROR; 143 | } 144 | } 145 | ``` 146 | 147 | ## I2C Bus Device Usage Example 148 | 149 | The specific usage of the I2C device can be referred to the following sample code. The main steps of the sample code are as follows: 150 | 151 | 1. First find the I2C name based on the I2C device name, get the device handle, and then initialize the aht10 sensor. 152 | 2. The two functions that control the sensor are the write sensor register `write_reg()` and the read sensor register `read_regs()`, both called `rt_i2c_transfer()` to transfer the data. The function `read_temp_humi()` calls the above two functions to read the temperature and humidity information. 153 | 154 | ```c 155 | /* 156 | * Program listing: This is an I2C device usage routine 157 | * The routine exports the i2c_aht10_sample command to the control terminal 158 | * Command call format: i2c_aht10_sample i2c1 159 | * Command explanation: The second parameter of the command is the name of the I2C bus device to be used. If it is empty, the default I2C bus device is used. 160 | * Program function: read the temperature and humidity data of the aht10 sensor and print. 161 | */ 162 | 163 | #include 164 | #include 165 | 166 | #define AHT10_I2C_BUS_NAME "i2c1" /* Sensor connected I2C bus device name */ 167 | #define AHT10_ADDR 0x38 /* Slave address */ 168 | #define AHT10_CALIBRATION_CMD 0xE1 /* Calibration command */ 169 | #define AHT10_NORMAL_CMD 0xA8 /* General command */ 170 | #define AHT10_GET_DATA 0xAC /* Get data command */ 171 | 172 | static struct rt_i2c_bus_device *i2c_bus = RT_NULL; /* I2C bus device handle */ 173 | static rt_bool_t initialized = RT_FALSE; /* Sensor initialization status */ 174 | 175 | /* Write sensor register */ 176 | static rt_err_t write_reg(struct rt_i2c_bus_device *bus, rt_uint8_t reg, rt_uint8_t *data) 177 | { 178 | rt_uint8_t buf[3]; 179 | struct rt_i2c_msg msgs; 180 | 181 | buf[0] = reg; //cmd 182 | buf[1] = data[0]; 183 | buf[2] = data[1]; 184 | 185 | msgs.addr = AHT10_ADDR; 186 | msgs.flags = RT_I2C_WR; 187 | msgs.buf = buf; 188 | msgs.len = 3; 189 | 190 | /* Call the I2C device interface to transfer data */ 191 | if (rt_i2c_transfer(bus, &msgs, 1) == 1) 192 | { 193 | return RT_EOK; 194 | } 195 | else 196 | { 197 | return -RT_ERROR; 198 | } 199 | } 200 | 201 | /* Read sensor register data */ 202 | static rt_err_t read_regs(struct rt_i2c_bus_device *bus, rt_uint8_t len, rt_uint8_t *buf) 203 | { 204 | struct rt_i2c_msg msgs; 205 | 206 | msgs.addr = AHT10_ADDR; 207 | msgs.flags = RT_I2C_RD; 208 | msgs.buf = buf; 209 | msgs.len = len; 210 | 211 | /* Call the I2C device interface to transfer data */ 212 | if (rt_i2c_transfer(bus, &msgs, 1) == 1) 213 | { 214 | return RT_EOK; 215 | } 216 | else 217 | { 218 | return -RT_ERROR; 219 | } 220 | } 221 | 222 | static void read_temp_humi(float *cur_temp, float *cur_humi) 223 | { 224 | rt_uint8_t temp[6]; 225 | 226 | write_reg(i2c_bus, AHT10_GET_DATA, 0); /* send command */ 227 | rt_thread_mdelay(400); 228 | read_regs(i2c_bus, 6, temp); /* obtian sensor data */ 229 | 230 | /* Humidity data conversion */ 231 | *cur_humi = (temp[1] << 12 | temp[2] << 4 | (temp[3] & 0xf0) >> 4) * 100.0 / (1 << 20); 232 | /* Temperature data conversion */ 233 | *cur_temp = ((temp[3] & 0xf) << 16 | temp[4] << 8 | temp[5]) * 200.0 / (1 << 20) - 50; 234 | } 235 | 236 | static void aht10_init(const char *name) 237 | { 238 | rt_uint8_t temp[2] = {0, 0}; 239 | 240 | /* Find the I2C bus device and get the I2C bus device handle */ 241 | i2c_bus = (struct rt_i2c_bus_device *)rt_device_find(name); 242 | 243 | if (i2c_bus == RT_NULL) 244 | { 245 | rt_kprintf("can't find %s device!\n", name); 246 | } 247 | else 248 | { 249 | write_reg(i2c_bus, AHT10_NORMAL_CMD, temp); 250 | rt_thread_mdelay(400); 251 | 252 | temp[0] = 0x08; 253 | temp[1] = 0x00; 254 | write_reg(i2c_bus, AHT10_CALIBRATION_CMD, temp); 255 | rt_thread_mdelay(400); 256 | initialized = RT_TRUE; 257 | } 258 | } 259 | 260 | static void i2c_aht10_sample(int argc, char *argv[]) 261 | { 262 | float humidity, temperature; 263 | char name[RT_NAME_MAX]; 264 | 265 | humidity = 0.0; 266 | temperature = 0.0; 267 | 268 | if (argc == 2) 269 | { 270 | rt_strncpy(name, argv[1], RT_NAME_MAX); 271 | } 272 | else 273 | { 274 | rt_strncpy(name, AHT10_I2C_BUS_NAME, RT_NAME_MAX); 275 | } 276 | 277 | if (!initialized) 278 | { 279 | /* Sensor initialization */ 280 | aht10_init(name); 281 | } 282 | if (initialized) 283 | { 284 | /* Read temperature and humidity data */ 285 | read_temp_humi(&temperature, &humidity); 286 | 287 | rt_kprintf("read aht10 sensor humidity : %d.%d %%\n", (int)humidity, (int)(humidity * 10) % 10); 288 | rt_kprintf("read aht10 sensor temperature: %d.%d \n", (int)temperature, (int)(temperature * 10) % 10); 289 | } 290 | else 291 | { 292 | rt_kprintf("initialize sensor failed!\n"); 293 | } 294 | } 295 | /* Export to the msh command list */ 296 | MSH_CMD_EXPORT(i2c_aht10_sample, i2c aht10 sample); 297 | ``` 298 | 299 | -------------------------------------------------------------------------------- /device/pin/figures/pin2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/pin/figures/pin2.png -------------------------------------------------------------------------------- /device/pin/pin.md: -------------------------------------------------------------------------------- 1 | # PIN Device 2 | 3 | ## Introduction of Pin 4 | 5 | The pins on the chip are generally divided into four categories: power supply, clock, control, and I/O. The I/O port is further divided into General Purpose Input Output (GPIO) and function multiplex I/O (such as SPI/I2C/UART, etc.) in the usage mode. 6 | 7 | Most MCU pins have more than one function. The internal structure of different pins is different and the functions are different. The actual function of the pin can be switched through different configurations. The main features of the General Purpose Input Output (GPIO) port are as follows: 8 | 9 | * Programmable Interrupt: The interrupt trigger mode is configurable. Generally, there are five interrupt trigger modes as shown in the following figure: 10 | 11 | ![5 Interrupt Trigger Modes](figures/pin2.png) 12 | 13 | * Input and output modes can be controlled. 14 | 15 | * Output modes generally include Output push-pull, Output open-drain, Output pull-up, and Output pull-down. When the pin is in the output mode, the connected peripherals can be controlled by configuring the level of the pin output to be high or low. 16 | 17 | * Input modes generally include: Input floating, Input pull-up, Input pull-down, and Analog. When the pin is in the input mode, the level state of the pin can be read, that is, high level or low level. 18 | 19 | ## Access PIN Device 20 | 21 | The application accesses the GPIO through the PIN device management interface provided by RT-Thread. The related interfaces are as follows: 22 | 23 | | Function | **Description** | 24 | | ---------------- | ---------------------------------- | 25 | | rt_pin_mode() | Set pin mode | 26 | | rt_pin_write() | Set the pin level | 27 | | rt_pin_read() | Read pin level | 28 | | rt_pin_attach_irq() | Bind pin interrupt callback function | 29 | | rt_pin_irq_enable() | Enable pin interrupt | 30 | | rt_pin_detach_irq() | Detach pin interrupt callback function | 31 | 32 | ### Obtain Pin Number 33 | 34 | The pin numbers provided by RT-Thread need to be distinguished from the chip pin numbers. They are not the same concept. The pin numbers are defined by the PIN device driver and are related to the specific chip. There are two ways to obtain the pin number: use the macro definition or view the PIN driver file. 35 | 36 | #### Use Macro Definition 37 | 38 | If you use the BSP in the `rt-thread/bsp/stm32` directory, you can use the following macro to obtain the pin number: 39 | 40 | ```c 41 | GET_PIN(port, pin) 42 | ``` 43 | 44 | The sample code for the pin number corresponding to LED0 with pin number PF9 is as follows: 45 | 46 | ```c 47 | #define LED0_PIN GET_PIN(F, 9) 48 | ``` 49 | 50 | #### View Driver Files 51 | 52 | If you use a different BSP, you will need to check the PIN driver code `drv_gpio.c` file to confirm the pin number. There is an array in this file that holds the number information for each PIN pin, as shown below: 53 | 54 | ```c 55 | static const rt_uint16_t pins[] = 56 | { 57 | __STM32_PIN_DEFAULT, 58 | __STM32_PIN_DEFAULT, 59 | __STM32_PIN(2, A, 15), 60 | __STM32_PIN(3, B, 5), 61 | __STM32_PIN(4, B, 8), 62 | __STM32_PIN_DEFAULT, 63 | __STM32_PIN_DEFAULT, 64 | __STM32_PIN_DEFAULT, 65 | __STM32_PIN(8, A, 14), 66 | __STM32_PIN(9, B, 6), 67 | ... ... 68 | } 69 | ``` 70 | 71 | Take `__STM32_PIN(2, A, 15)` as an example, 2 is the pin number used by RT-Thread, A is the port number, and 15 is the pin number, so the pin number corresponding to PA15 is 2. 72 | 73 | ### Set Pin Mode 74 | 75 | Before the pin is used, you need to set the input or output mode first, and the following functions are used: 76 | 77 | ```c 78 | void rt_pin_mode(rt_base_t pin, rt_base_t mode); 79 | ``` 80 | 81 | | Parameter | **Discription** | 82 | | --------- | ------------------ | 83 | | pin | Pin number | 84 | | mode | Pin operation mode | 85 | 86 | At present, the pin working mode supported by RT-Thread can take one of the five macro definition values as shown. The mode supported by the chip corresponding to each mode needs to refer to the specific implementation of the PIN device driver: 87 | 88 | ```c 89 | #define PIN_MODE_OUTPUT 0x00 /* Output */ 90 | #define PIN_MODE_INPUT 0x01 /* Input */ 91 | #define PIN_MODE_INPUT_PULLUP 0x02 /* input Pull up */ 92 | #define PIN_MODE_INPUT_PULLDOWN 0x03 /* input Pull down */ 93 | #define PIN_MODE_OUTPUT_OD 0x04 /* output Open drain */ 94 | ``` 95 | 96 | An example of use is as follows: 97 | 98 | ```c 99 | #define BEEP_PIN_NUM 35 /* PB0 */ 100 | 101 | /* Buzzer pin is in output mode */ 102 | rt_pin_mode(BEEP_PIN_NUM, PIN_MODE_OUTPUT); 103 | ``` 104 | 105 | ### Set The Pin Level 106 | 107 | The function to set the pin output level is as follows: 108 | 109 | ```c 110 | void rt_pin_write(rt_base_t pin, rt_base_t value); 111 | ``` 112 | 113 | | **Parameter** | Discription | 114 | |----------|-------------------------| 115 | | pin | Pin number | 116 | | value | Level logic value, which can take one of two macro definition values: PIN_LOW means low level, or PIN_HIGH means high level | 117 | 118 | Examples of use are as follows: 119 | 120 | ```c 121 | #define BEEP_PIN_NUM 35 /* PB0 */ 122 | 123 | /* Beep's pin is in output mode */ 124 | rt_pin_mode(BEEP_PIN_NUM, PIN_MODE_OUTPUT); 125 | /* Set low level */ 126 | rt_pin_write(BEEP_PIN_NUM, PIN_LOW); 127 | ``` 128 | 129 | ### Read Pin Level 130 | 131 | The functions to read the pin level are as follows: 132 | 133 | ```c 134 | int rt_pin_read(rt_base_t pin); 135 | ``` 136 | 137 | | Parameter | Description | 138 | | ---------- | ----------- | 139 | | pin | Pin number | 140 | | **return** | —— | 141 | | PIN_LOW | Low level | 142 | | PIN_HIGH | High level | 143 | 144 | Examples of use are as follows: 145 | 146 | ```c 147 | #define BEEP_PIN_NUM 35 /* PB0 */ 148 | int status; 149 | 150 | /* Buzzer pin is in output mode */ 151 | rt_pin_mode(BEEP_PIN_NUM, PIN_MODE_OUTPUT); 152 | /* Set low level */ 153 | rt_pin_write(BEEP_PIN_NUM, PIN_LOW); 154 | 155 | status = rt_pin_read(BEEP_PIN_NUM); 156 | ``` 157 | 158 | ### Bind Pin Interrupt Callback Function 159 | 160 | To use the interrupt function of the pin, you can use the following function to configure a pin to some interrupt trigger mode and bind an interrupt callback function to the corresponding pin. When the pin interrupt occurs, the callback function will be executed. : 161 | 162 | ```c 163 | rt_err_t rt_pin_attach_irq(rt_int32_t pin, rt_uint32_t mode, 164 | void (*hdr)(void *args), void *args); 165 | ``` 166 | 167 | | Parameter | Description | 168 | | ---------- | ------------------------------------------------------------ | 169 | | pin | Pin number | 170 | | mode | Interrupt trigger mode | 171 | | hdr | Interrupt callback function. Users need to define this function | 172 | | args | Interrupt the parameters of the callback function, set to RT_NULL when not needed | 173 | | return | —— | 174 | | RT_EOK | Binding succeeded | 175 | | error code | Binding failed | 176 | 177 | Interrupt trigger mode mode can take one of the following five macro definition values: 178 | 179 | ```c 180 | #define PIN_IRQ_MODE_RISING 0x00 /* Rising edge trigger */ 181 | #define PIN_IRQ_MODE_FALLING 0x01 /* Falling edge trigger */ 182 | #define PIN_IRQ_MODE_RISING_FALLING 0x02 /* Edge trigger (triggered on both rising and falling edges)*/ 183 | #define PIN_IRQ_MODE_HIGH_LEVEL 0x03 /* High level trigger */ 184 | #define PIN_IRQ_MODE_LOW_LEVEL 0x04 /* Low level trigger */ 185 | ``` 186 | 187 | Examples of use are as follows: 188 | 189 | ```c 190 | #define KEY0_PIN_NUM 55 /* PD8 */ 191 | /* Interrupt callback function */ 192 | void beep_on(void *args) 193 | { 194 | rt_kprintf("turn on beep!\n"); 195 | 196 | rt_pin_write(BEEP_PIN_NUM, PIN_HIGH); 197 | } 198 | static void pin_beep_sample(void) 199 | { 200 | /* Button 0 pin is the input mode */ 201 | rt_pin_mode(KEY0_PIN_NUM, PIN_MODE_INPUT_PULLUP); 202 | /* Bind interrupt, rising edge mode, callback function named beep_on */ 203 | rt_pin_attach_irq(KEY0_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_on, RT_NULL); 204 | } 205 | ``` 206 | 207 | ### Enable Pin Interrupt 208 | 209 | After binding the pin interrupt callback function, use the following function to enable pin interrupt: 210 | 211 | ```c 212 | rt_err_t rt_pin_irq_enable(rt_base_t pin, rt_uint32_t enabled); 213 | ``` 214 | 215 | | **Parameter** | **Description** | 216 | |----------|----------------| 217 | | pin | Pin number | 218 | | enabled | Status, one of two values: PIN_IRQ_ENABLE, and PIN_IRQ_DISABLE | 219 | | **return** | —— | 220 | | RT_EOK | Enablement succeeded | 221 | | error code | Enablement failed | 222 | 223 | Examples of use are as follows: 224 | 225 | ```c 226 | #define KEY0_PIN_NUM 55 /* PD8 */ 227 | /* Interrupt callback function */ 228 | void beep_on(void *args) 229 | { 230 | rt_kprintf("turn on beep!\n"); 231 | 232 | rt_pin_write(BEEP_PIN_NUM, PIN_HIGH); 233 | } 234 | static void pin_beep_sample(void) 235 | { 236 | /* Key 0 pin is the input mode */ 237 | rt_pin_mode(KEY0_PIN_NUM, PIN_MODE_INPUT_PULLUP); 238 | /* Bind interrupt, rising edge mode, callback function named beep_on */ 239 | rt_pin_attach_irq(KEY0_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_on, RT_NULL); 240 | /* Enable interrupt */ 241 | rt_pin_irq_enable(KEY0_PIN_NUM, PIN_IRQ_ENABLE); 242 | } 243 | ``` 244 | 245 | ### Detach Pin Interrupt Callback Function 246 | 247 | You can use the following function to detach the pin interrupt callback function: 248 | 249 | ```c 250 | rt_err_t rt_pin_detach_irq(rt_int32_t pin); 251 | ``` 252 | 253 | | **Parameter** | **Description** | 254 | | ------------- | -------------------- | 255 | | pin | Pin number | 256 | | **return** | —— | 257 | | RT_EOK | Detachment succeeded | 258 | | error code | Detachment failed | 259 | 260 | After the pin detaches the interrupt callback function, the interrupt is not closed. You can also call the bind interrupt callback function to bind the other callback functions again. 261 | 262 | ```c 263 | #define KEY0_PIN_NUM 55 /* PD8 */ 264 | /* Interrupt callback function */ 265 | void beep_on(void *args) 266 | { 267 | rt_kprintf("turn on beep!\n"); 268 | 269 | rt_pin_write(BEEP_PIN_NUM, PIN_HIGH); 270 | } 271 | static void pin_beep_sample(void) 272 | { 273 | /* Key 0 pin is the input mode */ 274 | rt_pin_mode(KEY0_PIN_NUM, PIN_MODE_INPUT_PULLUP); 275 | /* Bind interrupt, rising edge mode, callback function named beep_on */ 276 | rt_pin_attach_irq(KEY0_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_on, RT_NULL); 277 | /* Enable interrupt */ 278 | rt_pin_irq_enable(KEY0_PIN_NUM, PIN_IRQ_ENABLE); 279 | /* Detach interrupt callback function */ 280 | rt_pin_detach_irq(KEY0_PIN_NUM); 281 | } 282 | ``` 283 | 284 | ## PIN Device Usage Example 285 | 286 | The following sample code is the pin device usage example. The main steps of the sample code are as follows: 287 | 288 | 1. Set the corresponding pin of the beep to the output mode and give a default low state. 289 | 290 | 2. Set the key 0 and button 1 corresponding to the input mode, then bind the interrupt callback function and enable the interrupt. 291 | 292 | 3. When the key 0 is pressed, the beep starts to sound, and when the key 1 is pressed, the beep stops. 293 | 294 | ```c 295 | /* 296 | * Program listing: This is a PIN device usage routine 297 | * The routine exports the pin_beep_sample command to the control terminal 298 | * Command call format：pin_beep_sample 299 | * Program function: control the buzzer by controlling the level state of the corresponding pin of the buzzer by pressing the button 300 | */ 301 | 302 | #include 303 | #include 304 | 305 | /* Pin number, determined by looking at the device driver file drv_gpio.c */ 306 | #ifndef BEEP_PIN_NUM 307 | #define BEEP_PIN_NUM 35 /* PB0 */ 308 | #endif 309 | #ifndef KEY0_PIN_NUM 310 | #define KEY0_PIN_NUM 55 /* PD8 */ 311 | #endif 312 | #ifndef KEY1_PIN_NUM 313 | #define KEY1_PIN_NUM 56 /* PD9 */ 314 | #endif 315 | 316 | void beep_on(void *args) 317 | { 318 | rt_kprintf("turn on beep!\n"); 319 | 320 | rt_pin_write(BEEP_PIN_NUM, PIN_HIGH); 321 | } 322 | 323 | void beep_off(void *args) 324 | { 325 | rt_kprintf("turn off beep!\n"); 326 | 327 | rt_pin_write(BEEP_PIN_NUM, PIN_LOW); 328 | } 329 | 330 | static void pin_beep_sample(void) 331 | { 332 | /* Beep pin is in output mode */ 333 | rt_pin_mode(BEEP_PIN_NUM, PIN_MODE_OUTPUT); 334 | /* Default low level */ 335 | rt_pin_write(BEEP_PIN_NUM, PIN_LOW); 336 | 337 | /* KEY 0 pin is the input mode */ 338 | rt_pin_mode(KEY0_PIN_NUM, PIN_MODE_INPUT_PULLUP); 339 | /* Bind interrupt, falling edge mode, callback function named beep_on */ 340 | rt_pin_attach_irq(KEY0_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_on, RT_NULL); 341 | /* Enable interrupt */ 342 | rt_pin_irq_enable(KEY0_PIN_NUM, PIN_IRQ_ENABLE); 343 | 344 | /* KEY 1 pin is input mode */ 345 | rt_pin_mode(KEY1_PIN_NUM, PIN_MODE_INPUT_PULLUP); 346 | /* Binding interrupt, falling edge mode, callback function named beep_off */ 347 | rt_pin_attach_irq(KEY1_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_off, RT_NULL); 348 | /* Enable interrupt */ 349 | rt_pin_irq_enable(KEY1_PIN_NUM, PIN_IRQ_ENABLE); 350 | } 351 | /* Export to the msh command list */ 352 | MSH_CMD_EXPORT(pin_beep_sample, pin beep sample); 353 | ``` 354 | -------------------------------------------------------------------------------- /device/pwm/figures/pwm-f.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/pwm/figures/pwm-f.png -------------------------------------------------------------------------------- /device/pwm/figures/pwm-l.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/pwm/figures/pwm-l.png -------------------------------------------------------------------------------- /device/pwm/pwm.md: -------------------------------------------------------------------------------- 1 | # PWM Device 2 | 3 | ## Introduction to PWM 4 | 5 | PWM (Pulse Width Modulation) is a method of digitally encoding the level of an analog signal. The frequency of the square wave is used to encode the level of a specific analog signal by pulses of different frequencies. The output receives a series of pulses of equal magnitude and uses these pulses to replace the device with the desired waveform. 6 | 7 | ![PWM Schematic Diagram](figures/pwm-f.png) 8 | 9 | Above is a simple schematic diagram of PWM. Assuming that the timer works in a up-counter mode. When the count value is less than the threshold, it outputs a level state, such as a high level. When the count value is greater than the threshold, it outputs the opposite, such as a low level. When the count value reaches the maximum value, the counter recounts from 0 and returns to the original level state. The ratio of the high-level duration (pulse width) to the cycle time is the duty cycle, ranging from 0 to 100%. The high level of the above picture is just half of the cycle time, so the duty cycle is 50%. 10 | 11 | One of the common PWM control scenarios is to adjust the brightness of the light or screen. The brightness can be adjusted according to the duty cycle. The PWM adjusts the brightness not continuously, but constantly lights up and turns off the screen. When the light is turned on and off fast enough, the naked eye will always think that it is always bright. In the process of on and off, the longer the light is off, the lower the brightness of the screen to the naked eye. The longer the light is on, the less time is spent and the screen will be brighter. 12 | 13 | ![PWM Brightness Adjustment](figures/pwm-l.png) 14 | 15 | ## Access to PWM Devices 16 | 17 | The application accesses the PWM device hardware through the PWM device management interface provided by RT-Thread. The related interfaces are as follows: 18 | 19 | | **Function** | Description | 20 | | ----------------- | ---------------------------------- | 21 | | rt_device_find() | Find device handles based on the name of PWM device | 22 | | rt_pwm_set() | Set PWM period and pulse width | 23 | | rt_pwm_enable() | Enable PWM device | 24 | | rt_pwm_disable() | Disable the PWM device | 25 | 26 | ### Find the PWM Device 27 | 28 | The application obtains the device handle based on the name of PWM device, which in turn can operate the PWM device. The function is as follows: 29 | 30 | ```c 31 | rt_device_t rt_device_find(const char* name); 32 | ``` 33 | 34 | | Parameter | Description | 35 | | -------- | ---------------------------------- | 36 | | name | Device | 37 | | **Return** | —— | 38 | | Device handle | Found the corresponding device, will return the corresponding device handle | 39 | | RT_NULL | Device not found | 40 | 41 | In general, the name of the PWM device registered to the system is pwm0, pwm1, etc. The usage examples are as follows: 42 | 43 | ```c 44 | #define PWM_DEV_NAME "pwm3" /* name of PWM device */ 45 | struct rt_device_pwm *pwm_dev; /* PWM device handle */ 46 | /* Search the device */ 47 | pwm_dev = (struct rt_device_pwm *)rt_device_find(PWM_DEV_NAME); 48 | ``` 49 | 50 | ### Set PWM Period and Pulse Width 51 | 52 | Set the PWM period and duty cycle by using the following function: 53 | 54 | ```c 55 | rt_err_t rt_pwm_set(struct rt_device_pwm *device, 56 | int channel, 57 | rt_uint32_t period, 58 | rt_uint32_t pulse); 59 | ``` 60 | 61 | | Parameter | Description | 62 | | ---------- | ----------------- | 63 | | device | PWM device handle | 64 | | channel | PWM channel | 65 | | period | PWM period (ns) | 66 | | pulse | PWM pulse width time (ns) | 67 | | **Return** | —— | 68 | | RT_EOK | successful | 69 | | -RT_EIO | device is null | 70 | | -RT_ENOSYS | Device operation method is null | 71 | | Other Errors | Execute failed | 72 | 73 | The output frequency of the PWM is determined by the period. For example, the time of a period is 0.5ms (milliseconds), the period value is 500000ns (nanoseconds), the output frequency is 2KHz, the duty cycle is `pulse / period`, and the pulse value cannot exceed period. 74 | 75 | An example of use is as follows: 76 | 77 | ```c 78 | #define PWM_DEV_NAME "pwm3" /* name of PWM device */ 79 | #define PWM_DEV_CHANNEL 4 /* PWM channel */ 80 | struct rt_device_pwm *pwm_dev; /* PWM device handle */ 81 | rt_uint32_t period, pulse; 82 | 83 | period = 500000; /* The period is 0.5ms, the unit is nanoseconds */ 84 | pulse = 0; /* PWM pulse width value, the unit is nanoseconds */ 85 | /* Search the device */ 86 | pwm_dev = (struct rt_device_pwm *)rt_device_find(PWM_DEV_NAME); 87 | /* Set the PWM period and pulse width */ 88 | rt_pwm_set(pwm_dev, PWM_DEV_CHANNEL, period, pulse); 89 | ``` 90 | 91 | ### Enable the PWM Device 92 | 93 | After setting the PWM period and pulse width, you can enable the PWM device by the following function: 94 | 95 | ```c 96 | rt_err_t rt_pwm_enable(struct rt_device_pwm *device, int channel); 97 | ``` 98 | 99 | | Parameter | Description | 100 | | ---------- | ------------------------------- | 101 | | device | PWM device handle | 102 | | channel | PWM channel | 103 | | **Return** | —— | 104 | | RT_EOK | Enable device successful | 105 | | -RT_ENOSYS | Device operation method is null | 106 | | Other Errors | Enable device failed | 107 | 108 | An example of use is as follows: 109 | 110 | ```c 111 | #define PWM_DEV_NAME "pwm3" /* name of PWM device */ 112 | #define PWM_DEV_CHANNEL 4 /* PWM channel */ 113 | struct rt_device_pwm *pwm_dev; /* PWM device handle */ 114 | rt_uint32_t period, pulse; 115 | 116 | period = 500000; /* The period is 0.5ms, the unit is nanoseconds */ 117 | pulse = 0; /* PWM pulse width value, the unit is nanoseconds */ 118 | /* Search the device */ 119 | pwm_dev = (struct rt_device_pwm *)rt_device_find(PWM_DEV_NAME); 120 | /* Set the PWM period and pulse width */ 121 | rt_pwm_set(pwm_dev, PWM_DEV_CHANNEL, period, pulse); 122 | /* Enable the device */ 123 | rt_pwm_enable(pwm_dev, PWM_DEV_CHANNEL); 124 | ``` 125 | 126 | ### Disable the PWM device Channel 127 | 128 | Use the following function to turn off the corresponding channel of the PWM device. 129 | 130 | ```c 131 | rt_err_t rt_pwm_disable(struct rt_device_pwm *device, int channel); 132 | ``` 133 | 134 | | **Parameter** | Description | 135 | | ---------- | ------------------------------- | 136 | | device | PWM device handle | 137 | | channel | PWM channel | 138 | | **Return** | —— | 139 | | RT_EOK | Turn off device successful | 140 | | -RT_EIO | Device handle is null | 141 | | Other Errors | Turn off device failed | 142 | 143 | An example of use is as follows: 144 | 145 | ```c 146 | #define PWM_DEV_NAME "pwm3" /* name of PWM device */ 147 | #define PWM_DEV_CHANNEL 4 /* PWM channel */ 148 | struct rt_device_pwm *pwm_dev; /* PWM device handle */ 149 | rt_uint32_t period, pulse; 150 | 151 | period = 500000; /* The period is 0.5ms, the unit is nanoseconds */ 152 | pulse = 0; /* PWM pulse width value, the unit is nanoseconds */ 153 | /* Search the device */ 154 | pwm_dev = (struct rt_device_pwm *)rt_device_find(PWM_DEV_NAME); 155 | /* Set the PWM period and pulse width */ 156 | rt_pwm_set(pwm_dev, PWM_DEV_CHANNEL, period, pulse); 157 | /* Enable the device */ 158 | rt_pwm_enable(pwm_dev, PWM_DEV_CHANNEL); 159 | /* Turn off the device channel */ 160 | rt_pwm_disable(pwm_dev,PWM_DEV_CHANNEL); 161 | ``` 162 | 163 | ## FinSH Command 164 | 165 | To set the period and duty cycle of a channel of a PWM device, use the command `pwm_set pwm1 1 500000 5000`. The first parameter is the command, the second parameter is the PWM device name, the third parameter is the PWM channel, and the fourth parameter is PWM period(ns), the fifth parameter is the pulse width (ns). 166 | 167 | ```c 168 | msh />pwm_set pwm1 1 500000 5000 169 | msh /> 170 | ``` 171 | 172 | To enable a channel of the PWM device, use the command`pwm_enable pwm1 1`. The first parameter is the command, the second parameter is the PWM device name, and the third parameter is the PWM channel. 173 | 174 | ```c 175 | msh />pwm_enable pwm1 1 176 | msh /> 177 | ``` 178 | 179 | To disable a channel of the PWM device, use the command `pwm_disable pwm1 1`. The first parameter is the command, the second parameter is the PWM device name, and the third parameter is the PWM channel. 180 | 181 | ```c 182 | msh />pwm_disable pwm1 1 183 | msh /> 184 | ``` 185 | 186 | ## PWM Device Usage Example 187 | 188 | The following sample code is a PWM device usage sample . The main steps of the sample code are as follows: 189 | 190 | 1. Find the PWM device to get the device handle. 191 | 2. Set the PWM period and pulse width. 192 | 3. Enable the PWM device. 193 | 4. The pulse width is modified every 50 milliseconds in the while loop. 194 | 5. Connect the PWM channel to a LED, and you can see that the LED changes from dark to bright gradually, and then from bright to dark. 195 | 196 | ```c 197 | /* 198 | * Program list: This is PWM device usage example 199 | * The routine exports the pwm_led_sample command to the control terminal 200 | * Format for Command: pwm_led_sample 201 | * Program function: By controlling the brightness of the LED light through the PWM device, 202 | * you can see that the LED changes from dark to bright gradually, then from bright to dark. 203 | */ 204 | 205 | #include 206 | #include 207 | 208 | #define PWM_DEV_NAME "pwm3" /* PWM device name */ 209 | #define PWM_DEV_CHANNEL 4 /* PWM channel */ 210 | 211 | struct rt_device_pwm *pwm_dev; /* PWM device handle */ 212 | 213 | static int pwm_led_sample(int argc, char *argv[]) 214 | { 215 | rt_uint32_t period, pulse, dir; 216 | 217 | period = 500000; /* The period is 0.5ms, the unit is nanoseconds */ 218 | dir = 1; /* Increase or decrease direction of PWM pulse width value */ 219 | pulse = 0; /* PWM pulse width value, the unit is nanoseconds*/ 220 | 221 | /* Set LED pin mode to output */ 222 | rt_pin_mode(LED_PIN_NUM, PIN_MODE_OUTPUT); 223 | /* Set high LED pin mode */ 224 | rt_pin_write(LED_PIN_NUM, PIN_HIGH); 225 | 226 | /* Search the Device */ 227 | pwm_dev = (struct rt_device_pwm *)rt_device_find(PWM_DEV_NAME); 228 | if (pwm_dev == RT_NULL) 229 | { 230 | rt_kprintf("pwm sample run failed! can't find %s device!\n", PWM_DEV_NAME); 231 | return RT_ERROR; 232 | } 233 | 234 | /* Set PWM period and pulse width defaults */ 235 | rt_pwm_set(pwm_dev, PWM_DEV_CHANNEL, period, pulse); 236 | /* Enable device */ 237 | rt_pwm_enable(pwm_dev, PWM_DEV_CHANNEL); 238 | 239 | while (1) 240 | { 241 | rt_thread_mdelay(50); 242 | if (dir) 243 | { 244 | pulse += 5000; /* Increase 5000ns each time from 0 */ 245 | } 246 | else 247 | { 248 | pulse -= 5000; /* 5000ns reduction from the maximum */ 249 | } 250 | if (pulse >= period) 251 | { 252 | dir = 0; 253 | } 254 | if (0 == pulse) 255 | { 256 | dir = 1; 257 | } 258 | 259 | /* Set the PWM period and pulse width */ 260 | rt_pwm_set(pwm_dev, PWM_DEV_CHANNEL, period, pulse); 261 | } 262 | } 263 | /* Export to the msh command list */ 264 | MSH_CMD_EXPORT(pwm_led_sample, pwm sample); 265 | ``` 266 | -------------------------------------------------------------------------------- /device/rtc/rtc.md: -------------------------------------------------------------------------------- 1 | # RTC Device 2 | 3 | ## Introduction of RTC 4 | 5 | The RTC (Real-Time Clock) provides accurate real-time clock time, which can be used to generate information such as year, month, day, hour, minute, and second. At present, most real-time clock chips use a higher precision crystal oscillator as a clock source. In order to work when the main power supply is powered down, some clock chips will be powered by a battery to keep the time information valid. 6 | 7 | The RT-Thread RTC device provides the basic services for the operating system's time system. In the face of more and more IoT scenarios, RTC has become the standard configuration of the product, and even in the secure transmission process such as SSL, RTC has become an indispensable part. 8 | 9 | 10 | ## Access RTC Devices 11 | 12 | The application accesses the RTC hardware through the RTC device management interface, and the relevant interfaces are as follows: 13 | 14 | | **Function** | Description | 15 | | ------------- | ---------------------------------- | 16 | | set_date() | Set date, year, month, day | 17 | | set_time() | Set time, hour, minute, second | 18 | | time() | Obtain current time | 19 | 20 | ### Set Date 21 | 22 | Set the current date value of the RTC device by the following functions: 23 | 24 | ```c 25 | rt_err_t set_date(rt_uint32_t year, rt_uint32_t month, rt_uint32_t day) 26 | ``` 27 | 28 | | **Parameter** | **Description** | 29 | | -------- | ---------------------------------- | 30 | |year |The year to be set to take effect| 31 | |month |The month to be set to take effect| 32 | |day | The date to be set to take effect | 33 | | **return** | —— | 34 | | RT_EOK | Set-up succeeded | 35 | | -RT_ERROR | Set-up failed, no rtc device found | 36 | | other error code | Set-up failed | 37 | 38 | An example of use is as follows: 39 | 40 | ```c 41 | /* Set the date to December 3, 2018 */ 42 | set_date(2018, 12, 3); 43 | ``` 44 | 45 | ### Set Time 46 | 47 | Set the current time value of the RTC device by the following function: 48 | 49 | ```c 50 | rt_err_t set_time(rt_uint32_t hour, rt_uint32_t minute, rt_uint32_t second) 51 | ``` 52 | 53 | | **Parameter** | **Description** | 54 | | ---------- | ------------------------------- | 55 | |hour |The hour to be set to take effect| 56 | |minute |The minute to be set to take effect| 57 | |second |The second to be set to take effect| 58 | | **return** | —— | 59 | | RT_EOK | Set-up succeeded | 60 | | -RT_ERROR | Set-up failed, no rtc device found | 61 | | other error code | Set-up failed | 62 | 63 | An example of use is as follows: 64 | 65 | ```c 66 | /* Set the time to 11:15:50 */ 67 | set_time(11, 15, 50); 68 | ``` 69 | 70 | ### Obtain Current Time 71 | 72 | Obtain time using the time API in the C standard library: 73 | 74 | ```c 75 | time_t time(time_t *t) 76 | ``` 77 | 78 | | **Parameter** | **Description** | 79 | | ---------- | ------------------------------- | 80 | |t |Time data pointer | 81 | | **return** | —— | 82 | | Current time value | | 83 | 84 | Examples of use are as follows: 85 | 86 | ```c 87 | time_t now; /* Save the current time value obtained */ 88 | /* Obtain Time */ 89 | now = time(RT_NULL); 90 | /* Printout time information */ 91 | rt_kprintf("%s\n", ctime(&now)); 92 | ``` 93 | 94 | >Currently only one RTC device is allowed in the system and the name is `"rtc"`. 95 | 96 | ## Functional Configuration 97 | 98 | ### Enable Soft RTC (Software Emulation RTC) 99 | 100 | You can use the function of enabling RTC software emulation, which is ideal for products that do not require high time precision and have no hardware RTC. The configuration options of menuconfig are as follows: 101 | 102 | ```c 103 | RT-Thread Components → 104 | Device Drivers: 105 | -*- Using RTC device drivers /* Use RTC device driver */ 106 | [ ] Using software simulation RTC device /* Use software simulation RTC device */ 107 | ``` 108 | 109 | ### Enable NTP Time Automatic Synchronization 110 | 111 | If the RT-Thread is connected to the Internet, you can enable automatic NTP time synchronization to synchronize local time periodically. 112 | 113 | First open the NTP function in menuconfig as follows: 114 | 115 | ```c 116 | RT-Thread online packages → 117 | IoT - internet of things → 118 | netutils: Networking utilities for RT-Thread: 119 | [*] Enable NTP(Network Time Protocol) client 120 | ``` 121 | 122 | After the NTP is turned on, the RTC's automatic synchronization function will be automatically turned on, and the synchronization period and the delay time of the first synchronization can also be set: 123 | 124 | ```c 125 | RT-Thread Components → 126 | Device Drivers: 127 | -*- Using RTC device drivers /* Use RTC device driver */ 128 | [ ] Using software simulation RTC device /* Use software simulation RTC device */ 129 | [*] Using NTP auto sync RTC time /* Automatically synchronize RTC time with NTP */ 130 | (30) NTP first sync delay time(second) for network connect /* The delay for performing NTP time synchronization for the first time. The purpose of the delay is to reserve a certain amount of time for the network connection and try to increase the success rate of the first NTP time synchronization. The default time is 30S； */ 131 | (3600) NTP auto sync period(second) /* NTP The synchronization period is automatically synchronized in seconds, and the default period is one hour (ie 3600S). */ 132 | ``` 133 | 134 | ## FinSH Command 135 | 136 | Enter `date` to view the current time. 137 | 138 | ```c 139 | msh />date 140 | Fri Feb 16 01:11:56 2018 141 | msh /> 142 | ``` 143 | 144 | Also use the `date` command, after the command, enter `year` `month` `date` `hour ` ` minute ` ` second ` (between spaces, 24H system), and set the current time to 2018-02-16 01:15:30. The approximate effect is as follows: 145 | 146 | ```c 147 | msh />date 2018 02 16 01 15 30 148 | msh /> 149 | ``` 150 | 151 | ## RTC Device Usage Examples 152 | 153 | For the specific usage of the RTC device, refer to the following example code. First, set the year, month, date, hour, minute and second information, and then delay the data for 3 seconds to get the current time information. 154 | 155 | ```c 156 | /* 157 | * Program listing: This is an RTC device usage routine 158 | * The routine exports the rtc_sample command to the control terminal 159 | * Command call format：rtc_sample 160 | * Program function: Set the date and time of the RTC device. After a delay, obtain the current time and print the display. 161 | */ 162 | 163 | #include 164 | #include 165 | 166 | static int rtc_sample(int argc, char *argv[]) 167 | { 168 | rt_err_t ret = RT_EOK; 169 | time_t now; 170 | 171 | /* Set date */ 172 | ret = set_date(2018, 12, 3); 173 | if (ret != RT_EOK) 174 | { 175 | rt_kprintf("set RTC date failed\n"); 176 | return ret; 177 | } 178 | 179 | /* Set time */ 180 | ret = set_time(11, 15, 50); 181 | if (ret != RT_EOK) 182 | { 183 | rt_kprintf("set RTC time failed\n"); 184 | return ret; 185 | } 186 | 187 | /* Delay 3 seconds */ 188 | rt_thread_mdelay(3000); 189 | 190 | /* Obtain Time */ 191 | now = time(RT_NULL); 192 | rt_kprintf("%s\n", ctime(&now)); 193 | 194 | return ret; 195 | } 196 | /* Export to the msh command list */ 197 | MSH_CMD_EXPORT(rtc_sample, rtc sample); 198 | ``` 199 | -------------------------------------------------------------------------------- /device/spi/figures/spi1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/spi/figures/spi1.png -------------------------------------------------------------------------------- /device/spi/figures/spi2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/spi/figures/spi2.png -------------------------------------------------------------------------------- /device/spi/figures/spi5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/spi/figures/spi5.png -------------------------------------------------------------------------------- /device/uart/figures/uart-dma.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/uart/figures/uart-dma.png -------------------------------------------------------------------------------- /device/uart/figures/uart-int.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/uart/figures/uart-int.png -------------------------------------------------------------------------------- /device/uart/figures/uart1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/uart/figures/uart1.png -------------------------------------------------------------------------------- /device/watchdog/watchdog.md: -------------------------------------------------------------------------------- 1 | # WATCHDOG Device 2 | 3 | ## An Introduction to WATCHDOG 4 | 5 | The hardware watchdog timer is a timer whose timing output is connected to the reset terminal of the circuit. In a productized embedded system, in order to automatically reset the system under abnormal conditions, it generally needs a watchdog. 6 | 7 | When the watchdog was started, the counter starts counting automatically. If it is not reset counter value before the counter overflows, the counter overflow will generate a reset signal to the CPU to restart the system. When the system is running normally, it is necessary to clear the watchdog counter within the time interval allowed by the watchdog (commonly known as "feeding the dog"), and the reset signal will not be generated. If the program can "feed the dog" on time，the system does not go wrong，otherwise the system will reset. 8 | 9 | In general, users can feed the dog in the idlehook function and key function of RT-Thread. 10 | 11 | ## Access to the WATCHDOG Device 12 | 13 | The application accesses the watchdog hardware through the I/O device management interface provided by RT-Thread. The related interfaces are as follows: 14 | 15 | | **Function** | **Description** | 16 | | ---------------- | ---------------------------------- | 17 | | rt_device_find() | Find the device handle based on the device name of the watchdog device | 18 | | rt_device_init() | Initialize the watchdog device | 19 | | rt_device_control() |Control the watchdog device | 20 | | rt_device_close() | Close the watchdog device | 21 | 22 | ### Find the Watchdog Device 23 | 24 | The application obtains the device handle based on the watchdog device's name, and then it can operate the watchdog device. The function for finding a device is as follows: 25 | 26 | ```c 27 | rt_device_t rt_device_find(const char* name); 28 | ``` 29 | 30 | | **Function** | **Description** | 31 | | -------- | ---------------------------------- | 32 | | name | the name of the watchdog device | 33 | | **return** | —— | 34 | | device handle | finding the corresponding device and then return to the corresponding device handle | 35 | | RT_NULL | no corresponding device object found | 36 | 37 | An usage example is as follows: 38 | 39 | ```c 40 | #define IWDG_DEVICE_NAME "iwg" /* the name of the watchdog device */ 41 | 42 | static rt_device_t wdg_dev; /* device handle of the watchdog */ 43 | /* find the watchdog device based on the device's name and obtain the device handle */ 44 | wdg_dev = rt_device_find(IWDG_DEVICE_NAME); 45 | ``` 46 | 47 | ### Initialize the Watchdog Device 48 | 49 | The watchdog device need to be initialized before using, which can be done by the following function: 50 | 51 | ```c 52 | rt_err_t rt_device_init(rt_device_t dev); 53 | ``` 54 | 55 | | **Function** | **Description** | 56 | | ---------- | ------------------------------- | 57 | | dev | handle of the watchdog device | 58 | | **return** | —— | 59 | | RT_EOK | the device succeeded initializing | 60 | | -RT_ENOSYS | initialization failed, the watchdog device driver initialization function is empty | 61 | | other error code | the device failed to open | 62 | 63 | An example is as follows: 64 | 65 | ```c 66 | #define IWDG_DEVICE_NAME "iwg" /* the name of the watchdog device */ 67 | 68 | static rt_device_t wdg_dev; /* handle of the watchdog device */ 69 | /* find the watchdog device based on the device's name and obtain the device handle */ 70 | wdg_dev = rt_device_find(IWDG_DEVICE_NAME); 71 | 72 | /* initialize the device */ 73 | rt_device_init(wdg_dev); 74 | ``` 75 | 76 | ### Control the Watchdog Device 77 | 78 | The application can configure the watchdog device using the command control word, which can be done by the following function: 79 | 80 | ```c 81 | rt_err_t rt_device_control(rt_device_t dev, rt_uint8_t cmd, void* arg); 82 | ``` 83 | 84 | | **Function** | **Description** | 85 | | ---------------- | ---------------------------------- | 86 | | dev | handle of the watchdog device | 87 | | cmd | the command word | 88 | | arg | controlled parameter | 89 | | **return** | —— | 90 | | RT_EOK | function executed successfully | 91 | | -RT_ENOSYS | execution failed, the dev is empty | 92 | | other error code | execution failed | 93 | 94 | The command control word `'cmd'` can take the following macro definition values: 95 | 96 | ```c 97 | #define RT_DEVICE_CTRL_WDT_GET_TIMEOUT (1) /* get the overflow time */ 98 | #define RT_DEVICE_CTRL_WDT_SET_TIMEOUT (2) /* set the overflow time */ 99 | #define RT_DEVICE_CTRL_WDT_GET_TIMELEFT (3) /* get the remaining time */ 100 | #define RT_DEVICE_CTRL_WDT_KEEPALIVE (4) /* feed the dog */ 101 | #define RT_DEVICE_CTRL_WDT_START (5) /* start the watchdog */ 102 | #define RT_DEVICE_CTRL_WDT_STOP (6) /* stop the watchdog */ 103 | ``` 104 | 105 | An example of setting the overflow time of the watchdog is as follows: 106 | 107 | ```c 108 | #define IWDG_DEVICE_NAME "iwg" /* the name of the watchdog device */ 109 | 110 | rt_uint32_t timeout = 1000; /* the overflow time */ 111 | static rt_device_t wdg_dev; /* handle of the watchdog device */ 112 | /* find the watchdog device based on the device's name and obtain the device handle */ 113 | wdg_dev = rt_device_find(IWDG_DEVICE_NAME); 114 | /* initialize the device */ 115 | rt_device_init(wdg_dev); 116 | 117 | /* set the overflow time of the watch dog */ 118 | rt_device_control(wdg_dev, RT_DEVICE_CTRL_WDT_SET_TIMEOUT, (void *)timeout); 119 | /* set idle-hook function */ 120 | rt_thread_idle_sethook(idle_hook); 121 | ``` 122 | 123 | An example of feeding a dog in an idle thread hook function is as follows: 124 | 125 | ```c 126 | static void idle_hook(void) 127 | { 128 | /* Feed the dog in the callback function of the idle thread */ 129 | rt_device_control(wdg_dev, RT_DEVICE_CTRL_WDT_KEEPALIVE, NULL); 130 | } 131 | ``` 132 | 133 | ### Close the Watchdog Device 134 | 135 | When the application completes the operation of the watchdog, it can close the watchdog device: 136 | 137 | ```c 138 | rt_err_t rt_device_close(rt_device_t dev); 139 | ``` 140 | 141 | | **Function** | **Description** | 142 | | ---------- | ---------------------------------- | 143 | | dev | handle of the watchdog device | 144 | | **return** | —— | 145 | | RT_EOK | close the device successfully | 146 | | -RT_ERROR | The device has been completely shut down and cannot be closed repeatedly | 147 | | other error code | fail to close the device | 148 | 149 | Closing the device interface and opening the device interface need to match each other. When you open the device, you need to close the device once correspondingly, so that the device will be completely shut down, otherwise the device will remain unclosed. 150 | 151 | ## Watchdog Device usage example 152 | 153 | The specific use of the watchdog device can be referred to the following sample code. The main steps of the sample code are as follows: 154 | 155 | 1. First find the device handle based on the device name "iwg". 156 | 2. Set the overflow time of the watchdog after initializing the device. 157 | 3. Set the idle thread callback function. 158 | 4. This callback function will run and feed the dog when the system executes idle threads. 159 | 160 | ```c 161 | /* 162 | * Program list: This is an independent watchdog device usage routine 163 | * The routine exports the iwdg_sample command to the control terminal 164 | * Command call format: iwdg_sample iwg 165 | * Command explanation: The second parameter of the command is the name of the watchdog device to be used. If it is empty, you can use the default watchdog device of the routine. 166 | * Program function: The program finds the watchdog device through the device's name, and then initializes the device and sets the overflow time of the watchdog device. 167 | * Then set the idle thread callback function, which will feed the dog in the idle callback function. 168 | */ 169 | 170 | #include 171 | #include 172 | 173 | #define IWDG_DEVICE_NAME "iwg" /* the name of the watchdog device */ 174 | 175 | static rt_device_t wdg_dev; /* handle of the watchdog device */ 176 | 177 | static void idle_hook(void) 178 | { 179 | /* feed the dog in the callback function */ 180 | rt_device_control(wdg_dev, RT_DEVICE_CTRL_WDT_KEEPALIVE, NULL); 181 | rt_kprintf("feed the dog!\n "); 182 | } 183 | 184 | static int iwdg_sample(int argc, char *argv[]) 185 | { 186 | rt_err_t ret = RT_EOK; 187 | rt_uint32_t timeout = 1000; /* the overflow time */ 188 | char device_name[RT_NAME_MAX]; 189 | 190 | /* Determine if the command-line parameter is given the device name */ 191 | if (argc == 2) 192 | { 193 | rt_strncpy(device_name, argv[1], RT_NAME_MAX); 194 | } 195 | else 196 | { 197 | rt_strncpy(device_name, IWDG_DEVICE_NAME, RT_NAME_MAX); 198 | } 199 | /* find the watchdog device based on the device's name and obtain the device handle */ 200 | wdg_dev = rt_device_find(device_name); 201 | if (!wdg_dev) 202 | { 203 | rt_kprintf("find %s failed!\n", device_name); 204 | return RT_ERROR; 205 | } 206 | /* initialize the device */ 207 | ret = rt_device_init(wdg_dev); 208 | if (ret != RT_EOK) 209 | { 210 | rt_kprintf("initialize %s failed!\n", device_name); 211 | return RT_ERROR; 212 | } 213 | /* set the overflow time of the watch dog */ 214 | ret = rt_device_control(wdg_dev, RT_DEVICE_CTRL_WDT_SET_TIMEOUT, &timeout); 215 | if (ret != RT_EOK) 216 | { 217 | rt_kprintf("set %s timeout failed!\n", device_name); 218 | return RT_ERROR; 219 | } 220 | /* set idle thread callback function */ 221 | rt_thread_idle_sethook(idle_hook); 222 | 223 | return ret; 224 | } 225 | /* export to the msh command list */ 226 | MSH_CMD_EXPORT(iwdg_sample, iwdg sample); 227 | ``` 228 | 229 | -------------------------------------------------------------------------------- /device/wlan/figures/an0026_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/wlan/figures/an0026_1.png -------------------------------------------------------------------------------- /device/wlan/figures/an0026_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/wlan/figures/an0026_3.png -------------------------------------------------------------------------------- /device/wlan/figures/an0026_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/wlan/figures/an0026_4.png -------------------------------------------------------------------------------- /device/wlan/figures/an0026_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/device/wlan/figures/an0026_5.png -------------------------------------------------------------------------------- /dlmodule/README.md: -------------------------------------------------------------------------------- 1 | # Dynamic Module: dlmodule # 2 | 3 | In traditional desktop operating systems, user space and kernel space are separate. The application runs in user space, and the kernel and kernel modules run in kernel space. The kernel module can be dynamically loaded and deleted to extend the kernel functionality. `dlmodule` is a software component of the dynamic module loading mechanism provided in kernel space of RT-Thread. In versions of RT-Thread v3.1.0, this was also called the `Application Module`. After RT-Thread v3.1.0 and later, it returned to the tradition and was named after the `dynamic module`. 4 | 5 | `dlmodule` is more of an ELF format loader. The code segment and data segment of a separately compiled elf file are loaded into memory, and the symbols are parsed and bound to the API address exported by the kernel. The elf files are primarily placed on file systems under RT-Thread. 6 | 7 | ## Introduction ## 8 | 9 | The dynamic module provides a mechanism for dynamically loading program modules for RT-Thread. Because it is also compiled independently of the kernel, it is more flexible to use. In terms of implementation, this is a mechanism to separate the kernel from the dynamic modules. Through this mechanism, the kernel and dynamic modules can be compiled separately, and at runtime, the compiled dynamic modules are loaded into the kernel through the module loader in the kernel. 10 | 11 | In the dynamic module of RT-Thread, two formats are currently supported: 12 | 13 | * `.mo` is an executable dynamic module that is suffixed with `.mo` when compiled; it can be loaded, and a main thread is automatically created in the system to execute `main()` function in this dynamic module; at the same time, `main(int argc, char**argv)` can also accept arguments on the command line. 14 | * `.so` is a dynamic library compiled with `.so` as a suffix; it can be loaded and resided in memory, and some set of functions is used by other programs (code or dynamic modules in the kernel). 15 | 16 | The current RT-Thread architecture supporting dynamic modules mainly includes ARM architecture and x86 architecture, and will be extended to MIPS and RISC-V architecture in the future. The RT-Thread kernel firmware section can use a variety of compiler toolchains, such as GCC, ARMCC, IAR and other toolchains; however, dynamic module partial compilation currently only supports GNU GCC toolchain compilation. Therefore, compiling the RT-Thread module requires downloading GCC tools, such as CodeSourcery's arm-none-eabi toolchain. In general, it's best to use kernel and dynamic modules to compile with the same toolchain (so that it doesn't produce inconsistent behavior in *libc*). In addition, dynamic modules can only be loaded into RAM and used for symbol resolution binding to the API address exported by the kernel. Instead of running directly in XIP mode based on Flash (because Flash can't modify the code segment again). 17 | 18 | ## Using Dynamic Module ## 19 | 20 | When you want to use the dynamic modules in your system, you need to compile a firmware that supports dynamic modules, as well as dynamic modules that need to be run. The following two parts are compiling firmware and compiling dynamic modules. 21 | 22 | ### Compile Firmware ### 23 | 24 | When you want to use the dynamic module, you need to open the corresponding option in the firmware configuration, use menuconfig to open the following configuration: 25 | 26 | ```c 27 | RT-Thread Components ---> 28 | POSIX layer and C standard library ---> 29 | [*] Enable dynamic module with dlopen/dlsym/dlclose feature 30 | ``` 31 | 32 | Also open the configuration options of the file system: 33 | 34 | ```c 35 | RT-Thread Components ---> 36 | Device virtual file system ---> 37 | [*] Using device virtual file system 38 | ``` 39 | 40 | The configuration parameters required for dynamic module compilation are set in *rtconfig.py* file corresponding to bsp: 41 | 42 | ```Python 43 | M_CFLAGS = CFLAGS + '-mlong-calls -fPIC' 44 | M_CXXFLAGS = CXXFLAGS + '-mlong-calls -fPIC' 45 | M_LFLAGS = DEVICE + CXXFLAGS + '-Wl,--gc-sections,-z,max-page-size=0x4' +\ 46 | '-shared -fPIC -nostartfiles -nostdlib -static-libgcc' 47 | M_POST_ACTION = STRIP + '-R .hash $TARGET\n' + SIZE + '$TARGET \n' 48 | M_BIN_PATH = r'E:\qemu-dev310\fatdisk\root' 49 | ``` 50 | 51 | The relevant explanation is as follows: 52 | 53 | * **M_CFLAGS**: C code compilation parameters used in dynamic module compilation, generally compiled here in PIC mode (that is, the code address supports floating mode execution); 54 | - **M_CXXFLAGS**: C++ code compilation parameters used in dynamic module compilation, parameters similar to M_CFLAGS above; 55 | - **M_LFLAGS**: Parameters when the dynamic module is linked. The same is the PIC method, and is linked in a shared library (partial link); 56 | - **M_POST_ACTION**: the action to be performed after the dynamic module is compiled. Here, the elf file is stripped to reduce the size of the elf file. 57 | - **M_BIN_PATH**: When the dynamic module is successfully compiled, whether the corresponding dynamic module file needs to be copied to a unified place; 58 | 59 | Basically, these compilation configuration parameters for the ARM9, Cortex-A, and Cortex-M series are the same. 60 | 61 | The kernel firmware also exports some function APIs to the dynamic module via `RTM(function)`. All exported symbols information in firmware can be listed by command A under MSH: 62 | 63 | ``` 64 | list_symbols 65 | ``` 66 | 67 | The `dlmodule` loader also parses the symbols that need to be parsed in the dynamic module according to the symbol table exported here to complete the final binding action. 68 | 69 | This symbol table will be placed in a special section named `RTMSymTab`, so the corresponding firmware link script also needs to retain this area, and will not be removed by the linker optimization. You can add the corresponding information in the link script: 70 | 71 | ```text 72 | /* section information for modules */ 73 | . = ALIGN(4); 74 | __rtmsymtab_start = .; 75 | KEEP(*(RTMSymTab)) 76 | __rtmsymtab_end = .; 77 | ``` 78 | 79 | Then execute the `scons` under the BSP project directory and generate the firmware without errors. Execute the command in the BSP project directory: 80 | 81 | `scons --target=ua -s` 82 | 83 | to generate the kernel header file search path and global macro definitions that need to be included when compiling the dynamic module. 84 | 85 | ### Compile Dynamic Module ### 86 | 87 | There is a separate repository on github: [rtthread-apps](https://github.com/RT-Thread/rtthread-apps) , which contains some examples of dynamic modules and dynamic libraries. 88 | 89 | Its directory structure is as follows: 90 | 91 | | **Directory** | **Description** | 92 | | --- | ---------------- | 93 | | cxx | Demonstrates how to program in C++ using dynamic modules | 94 | | hello | A "hello world" example | 95 | | lib | Example of dynamic library | 96 | | md5 | Generate md5 code for a file | 97 | | tools | *Python/SConscript* scripts required for dynamic module compilation | 98 | | ymodem | Download a file to the file system through the serial port using the YModem protocol | 99 | 100 | You can clone this repository locally and compile it with the scons from the command line. For Windows platforms, the ENV tool is recommended. 101 | 102 | After entering the console command line, enter the directory where the `rtthread-apps` repo is located (the same, please ensure that the full path of this directory does not contain spaces, Chinese characters, etc.), and set two variables: 103 | 104 | * RTT_ROOT: points to the root directory of the RT-Thread code; 105 | - BSP_ROOT: points to the project directory of the BSP; 106 | 107 | Use follow commands on Windows in Env tool(assuming the BSP used is qemu-vexpress-a9): 108 | 109 | ```c 110 | set RTT_ROOT=d:\your_rtthread 111 | set BSP_ROOT=d:\your_rtthread\bsp\qemu-vexpress-a9 112 | ``` 113 | 114 | to set the corresponding environment variable. Then use the following command to compile the dynamic module, such as the hello example: 115 | 116 | ``` 117 | scons --app=hello 118 | ``` 119 | 120 | After compiling successfully, it will generate a `hello.mo` file in the `rtthread-apps/hello` directory. 121 | 122 | You can also compile dynamic libraries, such as the lib example: 123 | 124 | ``` 125 | scons --lib=lib 126 | ``` 127 | 128 | After compiling successfully, it will generate the `lib.so` file in the `rtthread-apps/lib` directory. 129 | 130 | We can put these `mo` and `so` files under the RT-Thread file system. Under msh, you can simply execute the `hello.mo` dynamic module as a `hello` command: 131 | 132 | ```c 133 | msh />ls 134 | Directory /: 135 | hello.mo 1368 136 | lib.so 1376 137 | msh />hello 138 | msh />Hello, world 139 | ``` 140 | 141 | After calling hello, the main function in `hello.mo` will be executed, and the corresponding dynamic module will be exited after execution. The code for `hello/main.c` is as follows: 142 | 143 | ```c 144 | #include 145 | 146 | int main(int argc, char *argv[]) 147 | { 148 | printf("Hello, world\n"); 149 | 150 | return 0; 151 | } 152 | ``` 153 | 154 | ## APIs of Dynamic Module 155 | 156 | In addition to dynamically loading and executing dynamic modules via msh, dynamic modules can be loaded or unloaded using the dynamic module API provided by RT-Thread in the main program. 157 | 158 | ### Load Dynamic Module 159 | 160 | ```c 161 | struct rt_dlmodule *dlmodule_load(const char* pgname); 162 | ``` 163 | 164 | |**Parameter**|**Description**| 165 | | ---- | ---- | 166 | | pgname | Dynamic module path | 167 | |**Return**| —— | 168 | | Dynamic module pointer | Successfully loaded | 169 | | RT_NULL | Failed | 170 | 171 | This function loads the dynamic module from the file system into memory, and if it is loaded correctly, returns a pointer to the module. This function does not create a thread to execute this dynamic module, just load the module into memory and parse the symbolic address. 172 | 173 | ### Execute Dynamic Module 174 | 175 | ```c 176 | struct rt_dlmodule *dlmodule_exec(const char* pgname, const char* cmd, int cmd_size); 177 | ``` 178 | 179 | |**Parameter**|**Description**| 180 | | ---- | ---- | 181 | | pgname | Dynamic module path | 182 | | cmd | Command line string including the dynamic module command itself | 183 | | cmd_size | Command line string size | 184 | |**Return**| —— | 185 | | Dynamic module pointer | Run successfully | 186 | | RT_NULL | Failed | 187 | 188 | This function loads the dynamic module according to the `pgname` path and starts a thread to execute `main` of the dynamic module. At the same time, `cmd` is passed as the command line Parameter to `main` entry of the dynamic module. 189 | 190 | ### Exit Dynamic Module 191 | 192 | ```c 193 | void dlmodule_exit(int ret_code); 194 | ``` 195 | 196 | |**Parameter**|**Description**| 197 | | ---- | ---- | 198 | | ret_code | Module's return parameter | 199 | 200 | This function is called by the module runtime, it can set the return value of the module exit `ret_code`, and then exit from the module. 201 | 202 | ### Find Dynamic Modules 203 | 204 | ```c 205 | struct rt_dlmodule *dlmodule_find(const char *name); 206 | ``` 207 | 208 | |**Parameter**|**Description**| 209 | | ---- | ---- | 210 | | name | Module name | 211 | |**Return**| —— | 212 | | Dynamic module pointer | Successful | 213 | | RT_NULL | Failed | 214 | 215 | This function uses `name` to find out if there is already a dynamic module loaded in the system. 216 | 217 | ### Return Dynamic Module 218 | 219 | ```c 220 | struct rt_dlmodule *dlmodule_self(void); 221 | ``` 222 | 223 | |**Return**|**Description**| 224 | | ---- | ---- | 225 | | Dynamic module pointer | Successful | 226 | | RT_NULL | Failed | 227 | 228 | This function returns a pointer of the dynamic module in the calling context. 229 | 230 | ### Find Symbol 231 | 232 | ```c 233 | rt_uint32_t dlmodule_symbol_find(const char *sym_str); 234 | ``` 235 | 236 | |**Parameter**|**Description**| 237 | | ---- | ---- | 238 | | sym_str | Symbol name | 239 | |**Return**| —— | 240 | | Symbol address | Successful | 241 | | 0 | Failed | 242 | 243 | This function returns the symbol address based on the symbol name. 244 | 245 | ## Libdl API of POSIX Standard ## 246 | 247 | The POSIX standard libdl API is also supported in RT-Thread dlmodule. It is similar to loading a dynamic library into memory (and parsing some of the symbol information). This dynamic library provides the corresponding set of function operations. The libdl API needs to include the header files: `#include ` 248 | 249 | ### Open Dynamic Library 250 | 251 | ```c 252 | void * dlopen (const char * pathname, int mode); 253 | ``` 254 | 255 | |**Parameter**|**Description**| 256 | | ---- | ---- | 257 | | pathname | Dynamic library path name | 258 | | mode | The mode when opening a dynamic library, not used in RT-Thread | 259 | |**Return**| —— | 260 | | Dynamic library handle (`struct dlmodule` structure pointer) | Successful | 261 | | NULL | Failed | 262 | 263 | This function is similar to the `dlmodule_load` , which loads the dynamic library from the file system and returns the handle pointer of the dynamic library. 264 | 265 | ### Find Symbol 266 | 267 | ```c 268 | void* dlsym(void *handle, const char *symbol); 269 | ``` 270 | 271 | |**Parameter**|**Description**| 272 | | ---- | ---- | 273 | | handle | Dynamic library handle, return value of `dlopen` | 274 | | symbol | The symbol address to return | 275 | |**Return**| —— | 276 | | symbol address | Successful | 277 | | NULL | Failed | 278 | 279 | This function looks in the dynamic library `handle` for the presence of the symbol of `symbol` , if there is an address that returns it. 280 | 281 | ### Close Dynamic Library 282 | 283 | ``` 284 | int dlclose (void *handle); 285 | ``` 286 | 287 | |**Parameter**|**Description**| 288 | | ---- | ---- | 289 | | handle | Dynamic library handle | 290 | |**Return**| —— | 291 | | 0 | Successful | 292 | | Negative number | Failed | 293 | 294 | This function closes the dynamic library pointed to by `handle` and unloads it from memory. It should be noted that when the dynamic library is closed, the symbolic address originally returned by `dlsym` will no longer be available. If you still try to access it, it may cause a fault error. 295 | 296 | ## FAQs 297 | 298 | Please refer to [*User Manual of Env*](../env/env.md) for issues related to the Env tool. 299 | 300 | ### Q: Dynamic modules cannot be run successfully according to the documentation. 301 | 302 | **A:** Please update the RT-Thread source code to version 3.1.0 and above. 303 | 304 | ### Q: Compile the project with the scons command, prompting "undefined reference to __rtmsymtab_start". 305 | 306 | **A:** Please refer to the qemu-vexpress-a9 BSP GCC link script file *link.lds* to add the following to the TEXT section of the project's GCC link script. 307 | 308 | ``` 309 | /* section information for modules */ 310 | . = ALIGN(4); 311 | __rtmsymtab_start = .; 312 | KEEP(*(RTMSymTab)) 313 | __rtmsymtab_end = .; 314 | ``` 315 | -------------------------------------------------------------------------------- /env/figures/Add_Env_To_Right-click_Menu-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/Add_Env_To_Right-click_Menu-1.png -------------------------------------------------------------------------------- /env/figures/Add_Env_To_Right-click_Menu-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/Add_Env_To_Right-click_Menu-2.png -------------------------------------------------------------------------------- /env/figures/Add_Env_To_Right-click_Menu-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/Add_Env_To_Right-click_Menu-3.png -------------------------------------------------------------------------------- /env/figures/cd_cmd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/cd_cmd.png -------------------------------------------------------------------------------- /env/figures/console.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/console.png -------------------------------------------------------------------------------- /env/figures/hotkey.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/hotkey.png -------------------------------------------------------------------------------- /env/figures/menuconfig_packages_list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/menuconfig_packages_list.png -------------------------------------------------------------------------------- /env/figures/menuconfig_s.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/menuconfig_s.png -------------------------------------------------------------------------------- /env/figures/menuconfig_s_auto_prj.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/menuconfig_s_auto_prj.png -------------------------------------------------------------------------------- /env/figures/menuconfig_s_auto_update.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/menuconfig_s_auto_update.png -------------------------------------------------------------------------------- /env/figures/q1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/q1.png -------------------------------------------------------------------------------- /env/figures/scons_done.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/scons_done.png -------------------------------------------------------------------------------- /env/figures/use_scons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/env/figures/use_scons.png -------------------------------------------------------------------------------- /figures/02Software_framework_diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/figures/02Software_framework_diagram.png -------------------------------------------------------------------------------- /filesystem/figures/elm-fat-mkfs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/filesystem/figures/elm-fat-mkfs.png -------------------------------------------------------------------------------- /filesystem/figures/fs-dir-mg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/filesystem/figures/fs-dir-mg.png -------------------------------------------------------------------------------- /filesystem/figures/fs-dir.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/filesystem/figures/fs-dir.png -------------------------------------------------------------------------------- /filesystem/figures/fs-layer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/filesystem/figures/fs-layer.png -------------------------------------------------------------------------------- /filesystem/figures/fs-mg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/filesystem/figures/fs-mg.png -------------------------------------------------------------------------------- /filesystem/figures/fs-reg-block.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/filesystem/figures/fs-reg-block.png -------------------------------------------------------------------------------- /filesystem/figures/fs-reg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/filesystem/figures/fs-reg.png -------------------------------------------------------------------------------- /finsh/figures/finsh-hd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/finsh/figures/finsh-hd.png -------------------------------------------------------------------------------- /finsh/figures/finsh-mdk.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/finsh/figures/finsh-mdk.png -------------------------------------------------------------------------------- /finsh/figures/finsh-run.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/finsh/figures/finsh-run.png -------------------------------------------------------------------------------- /interrupt/figures/09fun1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09fun1.png -------------------------------------------------------------------------------- /interrupt/figures/09fun2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09fun2.png -------------------------------------------------------------------------------- /interrupt/figures/09interrupt_handle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09interrupt_handle.png -------------------------------------------------------------------------------- /interrupt/figures/09interrupt_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09interrupt_ops.png -------------------------------------------------------------------------------- /interrupt/figures/09interrupt_reque.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09interrupt_reque.png -------------------------------------------------------------------------------- /interrupt/figures/09interrupt_table.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09interrupt_table.png -------------------------------------------------------------------------------- /interrupt/figures/09interrupt_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09interrupt_work.png -------------------------------------------------------------------------------- /interrupt/figures/09interrupt_work_process.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09interrupt_work_process.png -------------------------------------------------------------------------------- /interrupt/figures/09interrupt_work_sta.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09interrupt_work_sta.png -------------------------------------------------------------------------------- /interrupt/figures/09relation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09relation.png -------------------------------------------------------------------------------- /interrupt/figures/09ths_switch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/interrupt/figures/09ths_switch.png -------------------------------------------------------------------------------- /introduction/figures/02Software_framework_diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/introduction/figures/02Software_framework_diagram.png -------------------------------------------------------------------------------- /introduction/introduction.md: -------------------------------------------------------------------------------- 1 | # RT-Thread Introduction 2 | 3 | As a beginner of RTOS, you might be new to RT-Thread. However, with a better understanding of it overtime, you will gradually discover the charm of RT-Thread and its advantages over other RTOSs of the same type. RT-Thread is an Embedded Real-time Operating System (RTOS) . After nearly 12 years of experiences accumulated, along with the rise of the Internet of Things, it is evolving into a powerful, component-rich IoT operating system. 4 | 5 | ## RT-Thread Overview 6 | 7 | RT-Thread, short for Real Time-Thread, as its name implies, is an embedded real-time multi-threaded operating system. One of its basic properties is to support multi-tasking. Allowing multiple tasks to run at the same time does not mean that the processor actually performed multiple tasks at the same time. In fact, a processor core can only run one task at a time. Every task is executed quickly, and through the task scheduler (the scheduler determines the sequence according to priority), the tasks are switched rapidly which gives the illusion that multiple tasks are running at the same time. In the RT-Thread system, the task is implemented by threads. The thread scheduler in RT-Thread is the task scheduler mentioned above. 8 | 9 | RT-Thread is mainly written in C language, easy to understand and easy to port. It applies object-oriented programming methods to real-time system design, making the code elegant, structured, modular, and very tailorable. For resource-constrained Microcontroller Unit (MCU) systems, NANO version (NANO is a minimum kernel officially released by RT-Thread in July 2017) that requires only 3KB of Flash and 1.2KB of RAM memory resources can be tailored with easy-to-use tools; for resource-rich IoT devices, RT-Thread can use the on-line software package management tool, together with system configuration tools, to achieve intuitive and rapid modular cutting, seamlessly import rich Software f0 eature packs, thus achieving complex functions like Android's graphical interface and touch sliding effects, smart voice interaction effects, and so on. 10 | 11 | Compared with the Linux operating system, RT-Thread is small in size, low in cost, low in power consumption and fast in startup. In addition, RT-Thread has high instantaneity and low occupation, which is very suitable for various resource constraints (such as cost, power consumption, etc.). Although the 32-bit MCU is its main operating platform, other CPUs, ones with MMU, ones based on ARM9, ARM11 and even the Cortex-A series CPUs are suitable for RT-Thread in specific applications. 12 | 13 | ## License Agreement 14 | 15 | The RT-Thread system is a completely open source system, the 3.1.0 version and its earlier versions follow the GPL V2 + open source license agreement. Versions from the 3.1.0 version onwards follow the Apache License 2.0 open source license agreement. The RT-Thread system can be used free of charge in commercial products and does not require opening private code to the public. 16 | 17 | ## RT-Thread Frame 18 | 19 | In recent years, the concept of Internet of Things (IoT) has become widely known , and the Internet of Things market has developed rapidly. The networking of embedded devices is the trend of the times. Terminal networking has greatly increased the complexity of software. The traditional RTOS kernel can hardly meet the needs of the market. In this case, the concept of the Internet of Things Operating System (IoT OS) came into being. **IoT operating system refers to the software platform that is based on operating system kernel (like RTOS, Linux, etc.) and includes relatively complete middleware components such as file system, graphics library, etc. It is low in consumption and high in secure, abides by the Communication Protocol and has cloud-connect abilities.** RT-Thread is an IoT OS. 20 | 21 | One of the main differences between RT-Thread and many other RTOS such as FreeRTOS and uC/OS is that it is not only a real-time kernel, but also has a rich middle-tier component, as shown in the following figure. 22 | 23 | ![RT-Thread Software Framework](figures/02Software_framework_diagram.png) 24 | 25 | It includes: 26 | 27 | - Kernel layer: RT-Thread kernel, the core part of RT-Thread, includes the implementation of objects in the kernel system, such as multi-threading and its scheduling, semaphore, mailbox, message queue, memory management, timer, etc.; libcpu/BSP (Chip Migration Related Files/Board Support Package) is closely related to hardware and consists of peripheral drivers and CPU transport. 28 | - Components and Service Layer: Components are based on upper-level software on top of the RT-Thread kernel, such as virtual file systems, FinSH command-line interfaces, network frameworks, device frameworks, and more. Its modular design allows for high internal cohesion within the assembly and low coupling between components. 29 | - RT-Thread software package: A general-purpose software component running on the RT-Thread IoT operating system platform for different application areas, consisting of description information, source code or library files. RT-Thread provides an open package platform with officially available or developer-supplied packages that provide developers with a choice of reusable packages that are an important part of the RT-Thread ecosystem. The package ecosystem is critical to the choice of an operating system because these packages are highly reusable and modular, making it easy for application developers to build the system they want in the shortest amount of time. RT-Thread supports more than 60 software packages, listed below: 30 | 31 | 1. Internet of Things related software packages: Paho MQTT, WebClient, mongoose, WebTerminal, etc. 32 | 2. Scripting language related software packages: JerryScript and MicroPython are currently supported. 33 | 3. Multimedia related software packages: Openmv, mupdf. 34 | 4. Tools packages: CmBacktrace, EasyFlash, EasyLogger, SystemView. 35 | 5. System related software packages: RTGUI, Persimmon UI, lwext4, partition, SQLite, etc. 36 | 6. Peripheral library and driver software packages: RealTek RTL8710BN SDK. 37 | 7. Others. -------------------------------------------------------------------------------- /kernel-porting/figures/10pendsv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/kernel-porting/figures/10pendsv.png -------------------------------------------------------------------------------- /kernel-porting/figures/10stack.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/kernel-porting/figures/10stack.png -------------------------------------------------------------------------------- /kernel-porting/figures/10switch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/kernel-porting/figures/10switch.png -------------------------------------------------------------------------------- /kernel-porting/figures/10switch2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/kernel-porting/figures/10switch2.png -------------------------------------------------------------------------------- /kernel-porting/figures/10ths_env1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/kernel-porting/figures/10ths_env1.png -------------------------------------------------------------------------------- /kernel-porting/figures/10ths_env2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/kernel-porting/figures/10ths_env2.png -------------------------------------------------------------------------------- /memory/figures/08Memory_distribution.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08Memory_distribution.png -------------------------------------------------------------------------------- /memory/figures/08heap_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08heap_ops.png -------------------------------------------------------------------------------- /memory/figures/08memheap.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08memheap.png -------------------------------------------------------------------------------- /memory/figures/08mempool.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08mempool.png -------------------------------------------------------------------------------- /memory/figures/08mempool_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08mempool_ops.png -------------------------------------------------------------------------------- /memory/figures/08mempool_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08mempool_work.png -------------------------------------------------------------------------------- /memory/figures/08slab.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08slab.png -------------------------------------------------------------------------------- /memory/figures/08smem_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08smem_work.png -------------------------------------------------------------------------------- /memory/figures/08smem_work2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08smem_work2.png -------------------------------------------------------------------------------- /memory/figures/08smem_work3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/memory/figures/08smem_work3.png -------------------------------------------------------------------------------- /network/figures/net-hello.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-hello.png -------------------------------------------------------------------------------- /network/figures/net-layer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-layer.png -------------------------------------------------------------------------------- /network/figures/net-osi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-osi.png -------------------------------------------------------------------------------- /network/figures/net-recv.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-recv.png -------------------------------------------------------------------------------- /network/figures/net-send.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-send.png -------------------------------------------------------------------------------- /network/figures/net-tcp-s.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-tcp-s.png -------------------------------------------------------------------------------- /network/figures/net-tcp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-tcp.png -------------------------------------------------------------------------------- /network/figures/net-udp-client.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-udp-client.png -------------------------------------------------------------------------------- /network/figures/net-udp-server.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-udp-server.png -------------------------------------------------------------------------------- /network/figures/net-udp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/network/figures/net-udp.png -------------------------------------------------------------------------------- /pm/figures/pm_architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/pm/figures/pm_architecture.png -------------------------------------------------------------------------------- /pm/figures/pm_description.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/pm/figures/pm_description.png -------------------------------------------------------------------------------- /pm/figures/pm_sequence.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/pm/figures/pm_sequence.png -------------------------------------------------------------------------------- /pm/figures/pm_system.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/pm/figures/pm_system.png -------------------------------------------------------------------------------- /quick-start/figures/10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/10.png -------------------------------------------------------------------------------- /quick-start/figures/11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/11.png -------------------------------------------------------------------------------- /quick-start/figures/14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/14.png -------------------------------------------------------------------------------- /quick-start/figures/5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/5.png -------------------------------------------------------------------------------- /quick-start/figures/6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/6.png -------------------------------------------------------------------------------- /quick-start/figures/7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/7.png -------------------------------------------------------------------------------- /quick-start/figures/8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/8.png -------------------------------------------------------------------------------- /quick-start/figures/9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/9.png -------------------------------------------------------------------------------- /quick-start/figures/compile.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/compile.jpg -------------------------------------------------------------------------------- /quick-start/figures/debug.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/figures/debug.jpg -------------------------------------------------------------------------------- /quick-start/keil-installation/figures/1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/keil-installation/figures/1.png -------------------------------------------------------------------------------- /quick-start/keil-installation/figures/12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/keil-installation/figures/12.png -------------------------------------------------------------------------------- /quick-start/keil-installation/figures/13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/keil-installation/figures/13.png -------------------------------------------------------------------------------- /quick-start/keil-installation/figures/2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/keil-installation/figures/2.png -------------------------------------------------------------------------------- /quick-start/keil-installation/figures/3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/keil-installation/figures/3.png -------------------------------------------------------------------------------- /quick-start/keil-installation/figures/4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/keil-installation/figures/4.png -------------------------------------------------------------------------------- /quick-start/keil-installation/keil-installation.md: -------------------------------------------------------------------------------- 1 | # Keil MDK Installation 2 | 3 | Before running the RT-Thread operating system, we need to install MDK-ARM 5.24 (either official or evaluation version, version 5.14 and above), this version is also a relatively new version. This version can provide relatively complete debugging functions. Here, we are using evaluation version 5.24 of 16k compiled code limit. If you want to remove the 16k compiled code limit, please purchase the official MDK-ARM. 4 | 5 | Firstly, download the MDK-ARM evaluation version from the official website of www.keil.com: 6 | [http://www.keil.com/download/](http://www.keil.com/download/) 7 | 8 | When downloading, you need to fill in some basic information, please fill in the corresponding complete information, and then start downloading. After it is downloaded, double-click the mouse to start the installation, you will see the software installation as shown: 9 | 10 | ![First Step](./figures/1.png) 11 | 12 | This is the MDK-ARM installation instructions, click “Next>>” to enter the next step, as shown. 13 | 14 | ![Second Step](./figures/2.png) 15 | 16 | Click "√" in the box next to "I agree to all the terms of the preceding License Agreement" and click "Next >>" to proceed to the next step of installation, as shown: 17 | 18 | ![Third Step](./figures/3.png) 19 | 20 | Click "Browse..." to select the installation directory of MDK-ARM or directly input installation path in the "Destination Folder" box. Here, we default to "C:/Keil_v5", then click "Next>>" to proceed to the next step of installation, as shown: 21 | 22 | ![Fourth Step](./figures/4.png) 23 | 24 | Input your name after "First Name", input your last name after "Last Name", input your company name after "Company Name", input your email address after "E-mail", and then click "Next>> " for the installation. Wait for a while for the installation to finish and you will see the following: 25 | 26 | ![Fifth Step](./figures/12.png) 27 | 28 | The default selection does not need to be changed, just click “Next” to enter the next step as shown. 29 | 30 | ![MDK-ARM Installment Complete](./figures/13.png) 31 | 32 | Here, you can click "Finish" to complete the installation of the entire MDK-ARM software. 33 | 34 | With a useful took like MDK-ARM, you can start the RT-Thread operating system easily and explore real-time operating systems. 35 | 36 | >Note: There is a charge for Official version of MDK-ARM. If you want to be able to compile larger binaries, please purchase the official version of MDK-ARM. RT-Thread operating system also supports GNU GCC compiler by Free Software Foundation which is an open source compiler. For more information on how to use GNU related tools, please refer to the related documentation on RT-Thread website. 37 | -------------------------------------------------------------------------------- /quick-start/quick-start.md: -------------------------------------------------------------------------------- 1 | # Start Guide: Simulate STM32F103 on keil simulator 2 | 3 | Because of its particularity, the embedded operating system is often closely related to the hardware platform. Specific embedded operating system can only run on specific hardware. For those who are new to the RT-Thread operating system, it is not easy to get a hardware module that is compatible with the RT-Thread operating system. However, with the development of computer technology, we can use software to simulate a hardware module that has the ability to run RT-Thread operating system. This is the simulation environment called MDK-ARM produced by the company ARM. 4 | 5 | MDK-ARM (MDK-ARM Mi6hyicrocontroller Development Kit) software is a complete integrated development environment (IDE) from ARM. It includes efficient C/C++ compiler for ARM chips (ARM7, ARM9, Cortex-M series, Cortex-R series, etc.) ; project wizard and project management for various ARM devices, evaluation boards; simulator for software simulating hardware platform; and debuggers connected to simulators debugging the target board, common on-line simulators on the market are stlink jlink, etc. The simulator software in MDK-ARM uses a complete software simulation to interpret and execute machine instructions from ARM and implement some peripheral logic to form a complete virtual hardware environment, enabling users to execute the corresponding target program on the computer without using real hardware platform. 6 | 7 | Because of its full STM32F103 software simulation environment, the MDK-ARM integrated development environment gives us the opportunity to run object code directly on the computer without using a real hardware environment . This simulator platform can completely virtualize the various operating modes and peripherals of the ARM Cortex-M3, such as exceptional interrupts, clock timers, serial ports, etc., which is almost identical to the real hardware environment. Practice has also proved that the RT-Thread introductory sample used in this article, after compiling into binary code, can not only run on the simulator platform, but also can run normally on the real hardware platform without modification. 8 | 9 | Next, we will select the MDK-ARM integrated development environment as the target hardware platform to observe how the RT-Thread operating system works. 10 | 11 | ## Preparation 12 | 13 | MDK development environment: MDK-ARM 5.24 (official or evaluation version, version 5.14 and above) needs to be installed. This version is also a relatively new version, which can provide relatively complete debugging functions. How to install can be referred to the [Keil MDK Installation](./keil-installation/keil-installation.md). 14 | 15 | ## First acquaintance with RT-Thread 16 | 17 | As an operating system, what is the code size of RT-Thread? Before we can figure this out, the first thing we need to do is to get an example of RT-Thread that corresponds to this manual. This example can be obtained from the following link: 18 | 19 | [RT-Thread Simulator Sample](./rtthread_simulator_v0.1.0.zip) 20 | 21 | This example is a zip file, unzip it. Here, we decompressed it to D:/. The directory structure after decompression is as shown below: 22 | 23 | ![rtthread_simulator_v0.1.0 Code Directory ](./figures/7.png) 24 | 25 | Descriptions of the file types contained in each directory are shown in the following table: 26 | 27 | Directory Name | Description 28 | --- | --- 29 | applications| RT-Thread application. 30 | rt-thread | Source file for RT-Thread. 31 | - components| Respective component directories of RT-Thread. 32 | - include | Header file for RT-Thread kernel. 33 | - libcpu | Porting code for various types of chips, including porting files of STM32. 34 | - src | Source file for RT-Thread kernel. 35 | - tools | Script file of RT-Thread commanding building tool. 36 | drivers | Driver of RT-Thread, implementations of bottom driver of different platforms. 37 | Libraries | ST's STM32 firmware library file. 38 | kernel-sample-0.1.0 | Kernel sample for RT-Thread. 39 | 40 | In the directory, there is project.uvprojx file, which is an MDK5 project file in the sample referenced in this manual. Double-click "project.uvprojx" icon to open the project file: 41 | 42 | ![Open the project](./figures/5.png) 43 | 44 | Under the "Project" column on the left side of the main window of the project, you can see the file list of the project. These files are stored in the following groups, respectively: 45 | 46 | | Directory Group | Description | 47 | | :-------------- | ------------------------------------------------------------ | 48 | | Applications | The corresponding directory is rtthread_simulator_v0.1.0/applications, used to store user application code. | 49 | | Drivers | The corresponding directory is rtthread_simulator_v0.1.0/drivers, used to store the bottom driver code for RT-Thread. | 50 | | STM32_HAL | The corresponding directory is rtthread_simulator_v0.1.0/Libraries/CMSIS/Device/ST/STM32F1xx, used to store the firmware library files of STM32. | 51 | | kernel-sample | The corresponding directory is rtthread_simulator_v0.1.0/kernel-sample-0.1.0, used to store kernel samples of RT-Thread. | 52 | | Kernel | The corresponding directory is rtthread_simulator_v0.1.0/src, used to store RT-Thread kernel core code. | 53 | | CORTEX-M3 | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/libcpu, used to store ARM Cortex-M3 porting code. | 54 | | DeviceDrivers | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/components/drivers, used to store driver framework source code of RT-Thread. | 55 | | finsh | The corresponding directory is rtthread_simulator_v0.1.0/rt-thread/components/finsh, used to store command line of RT-Thread finsh command line component. | 56 | 57 | Now let's click the button from the toolbar on the top the window,![img](./figures/compile.jpg), compiling the project as shown: 58 | 59 | ![compiling](./figures/9.png) 60 | 61 | The result of the compilation is displayed in the "Build Output" bar at the bottom of the window. If nothing else, it will say "0 Error(s), * Warning(s)." on the last line, that is, there are no errors or warnings. 62 | 63 | After compiling RT-Thread/STM32, we can simulate running RT-Thread through the MDK-ARM simulator. Click ![img](./figures/debug.jpg)at the top right of the window or directly hit Ctrl+F5 to enter the simulation interface and hit F5 to start, then click the button in the toolbar shown in the screen shot or select “View→Serial Windows→UART#1” in the menu bar to open the serial port 1 window. You can see that the output of the serial port only shows the LOGO of RT-Thread. This is because the user code is empty and the result of its simulation is as shown: 64 | 65 | ![simulate RT-Thread1](./figures/10.png) 66 | 67 | >We can output all the commands supported by the current system by inputting the Tab key or `help + enter ` , as shown in the following figure. 68 | 69 | ![simulate RT-Thread2](./figures/6.png) 70 | 71 | 72 | ## User Entry Code 73 | 74 | The above startup code is basically related to the RT-Thread system, so how do users add initialization code for their own applications? RT-Thread uses main function as the user code entry, all you need to do is just add your own code to the main function. 75 | 76 | ```c 77 | int main(void) 78 | { 79 | /* user app entry */ 80 | return 0; 81 | } 82 | ``` 83 | 84 | >Note: In order to complete the initialization for the system functions before entering the main program, you can use the `$sub$$` and `$super$$` function identifiers to call another sample before entering the main program, this was, users can ignore the initialization operations before the main() function. See [ARM® Compiler v5.06 for µVision® armlink User Guide](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0377g/pge1362065967698.html) for details. 85 | 86 | ## Example of a Marquee 87 | 88 | For technical engineers working on electronics, marquee is probably the simplest example, it is like the first program Hello World in every programming language that programmers learned. So we will start with a marquee in the following example, to make it periodically update (turn on or off) the LED. 89 | 90 | Under UART#1, input msh command: led and then click Enter to run it, as shown: 91 | 92 | ![run led](./figures/11.png) 93 | 94 | **Example of a Marquee** 95 | 96 | ```c 97 | /* 98 | * Manifest of programs: Marquee sample 99 | * 100 | * marquee is probably the simplest example, it is like the first program 101 | * Hello World in every programming language that programmers learned. So we will start with a marquee in the following example, start a thread to make it periodically 102 | * update (turn on or off) the LED. 103 | */ 104 | 105 | int led(void) 106 | { 107 | rt_uint8_t count; 108 | 109 | rt_pin_mode(LED_PIN, PIN_MODE_OUTPUT); 110 | 111 | for(count = 0 ; count < 10 ;count++) 112 | { 113 | rt_pin_write(LED_PIN, PIN_HIGH); 114 | rt_kprintf("led on, count : %d\r\n", count); 115 | rt_thread_mdelay(500); 116 | 117 | rt_pin_write(LED_PIN, PIN_LOW); 118 | rt_kprintf("led off\r\n"); 119 | rt_thread_mdelay(500); 120 | } 121 | return 0; 122 | } 123 | MSH_CMD_EXPORT(led, RT-Thread first led sample); 124 | ``` 125 | 126 | ## Other Examples 127 | 128 | Additional kernel examples can be found in the kernel-sample-0.1.0 directory. 129 | 130 | ![more kernel samples](./figures/14.png) 131 | 132 | ## Frequently Asked Question 133 | 134 | * Compilation error occurred as following: 135 | 136 | ``` 137 | rt-thread\src\kservice.c(823): error: #929: incorrect use of vaarg fieldwidth = aarg(args, int); 138 | rt-thread\src\kservice.c(842): error: #929: incorrect use of vaarg precision = aarg(args, int); 139 | ……… 140 | ``` 141 | 142 | Cause: This type of problem is usually caused by installation of ADS, when ADS and keil coexist, the header file of va_start points to the ADS folder. 143 | 144 | Solution: 145 | 146 | - Delete ADS environment variables 147 | - Uninstall ADS and keil, restart the computer, reload keil 148 | 149 | 150 | 151 | -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/echo-cat.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/echo-cat.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/env.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/env.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/env_menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/env_menu.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/env_menu_ubuntu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/env_menu_ubuntu.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/finsh-cmd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/finsh-cmd.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/finsh-thread.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/finsh-thread.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/menuconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/menuconfig.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/menuconfig_menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/menuconfig_menu.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/mkfs-sd0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/mkfs-sd0.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/python3-version.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/python3-version.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/qemu.bat.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/qemu.bat.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/qemu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/qemu.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/qemubsp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/qemubsp.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/scons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/scons.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-env-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-env-menu.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-filesys.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-filesys.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-menuconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-menuconfig.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-mkfs-sd0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-mkfs-sd0.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-msh-help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-msh-help.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-pkg-menuconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-pkg-menuconfig.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-pkg-set.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-pkg-set.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-pkgs-add-to-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-pkgs-add-to-menu.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-qemu-bsp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-qemu-bsp.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-qume-sh.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-qume-sh.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-rtconfig-py.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-rtconfig-py.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-save.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-save.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-scons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-scons.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-select-pkg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-select-pkg.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-thread-timer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-thread-timer.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/ubuntu-update-pkg.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/ubuntu-update-pkg.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/figures/win-menuconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/quick_start_qemu/figures/win-menuconfig.png -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/quick_start_qemu.md: -------------------------------------------------------------------------------- 1 | # Getting Started of QEMU (Windows) 2 | 3 | The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board. 4 | 5 | ## Preparations 6 | 7 | - [Download RT-Thread Source Code](https://github.com/RT-Thread/rt-thread) 8 | - Download Env Tool 9 | - [Install Git on your PC](https://www.git-scm.com/download/) 10 | 11 | 12 | ## Instructions for the Env tool 13 | 14 | When using Env tools, you need to enter the corresponding BSP directory in the Env terminal. 15 | 16 | ### Configuration 17 | 18 | ``` 19 | menuconfig 20 | ``` 21 | 22 | Type the `menuconfig` command in the Env terminal to enter the configuration interface, and then configure the BSP: 23 | 24 | ![menuconfig command](figures/win-menuconfig.png) 25 | 26 | ![enter the configuration interface](figures/env_menu.png) 27 | 28 | You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and use the `Esc` key to exit the current directory. 29 | 30 | ### Acquisition of software packages 31 | 32 | ``` 33 | pkgs --update 34 | ``` 35 | 36 | If a package is selected in menuconfig, download the package using the `pkgs --update` command (Git needs to be installed) 37 | 38 | ### Compile 39 | 40 | ``` 41 | scons 42 | ``` 43 | 44 | Compile using the `scons` command. 45 | 46 | ### Generate IDE's Project Files 47 | 48 | ``` 49 | scons --target=xxx 50 | ``` 51 | 52 | If you use the MDK or IAR IDE for development, you need to regenerate project files to make the configuration work after the configuration is completed. The command is `scons --target=xxx`, as shown below, which is the generation of IAR project, MDK4 project and MDK5 project. 53 | 54 | ```c 55 | scons --target=iar 56 | scons --target=mdk4 57 | scons --target=mdk5 58 | ``` 59 | 60 | ## Introduction of QEMU BSP Catalogue 61 | 62 | The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `qemu-vexpress-a9` folder under the BSP directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure. 63 | 64 | ![qemu-vexpress-a9 folder](figures/qemubsp.png) 65 | 66 | The main files and directories of `qemu-vexpress-a9` BSP are described as follows: 67 | 68 | | Fles/Directories | Description | 69 | | ---------------- | ------------------------------------------- | 70 | | .vscode | configuration file of vscode | 71 | | applications | User application code directory | 72 | | drivers | The underlying driver provided by RT-Thread | 73 | | qemu.bat | Script files running on Windows platform | 74 | | qemu.sh | Script files running on Linux platform | 75 | | qemu-dbg.bat | Debugging script files on Windows platform | 76 | | qemu-dbg.sh | Debugging script files on Linux platform | 77 | | README.md | Description document of BSP | 78 | | rtconfig.h | A header file of BSP | 79 | 80 | ## Compile and Run 81 | 82 | ### Step 1. Use the *scons* Command to Compile the Project 83 | 84 | Open the Env folder and double-click the `env.exe` file to open the Env console: 85 | 86 | ![Env folder](figures/env.png) 87 | 88 | Switch to the QEMU BSP directory and enter the `scons` command to compile the project. If the compilation is correct, the `rtthread.elf` file will be generated in the BSP directory, which is a target file required for QEMU to run. 89 | 90 | ![compile the project](figures/scons.png) 91 | 92 | ### Step 2. Use the *qemu.bat* Command to Run the Project 93 | 94 | After compiling, type `qemu.bat` to start the virtual machine and BSP project. `qemu.bat` is a Windows batch file. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture: 95 | 96 | ![run the project](figures/qemu.bat.png) 97 | 98 | ![QEMU virtual machine](figures/qemu.png) 99 | 100 | ### Run the Finsh Console 101 | 102 | RT-Thread supports Finsh, and users can use command operations in command line mode. 103 | 104 | Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right. 105 | 106 | ![view all supported commands](figures/finsh-cmd.png) 107 | 108 | For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers. 109 | 110 | ![threads and timers](figures/finsh-thread.png) 111 | 112 | ### Run the File System 113 | 114 | Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability. 115 | 116 | For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html) 117 | 118 | ![format the SD card ](figures/mkfs-sd0.png) 119 | 120 | The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `qemu.bat` on the Env command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread: 121 | 122 | ![commands of file system](figures/echo-cat.png) 123 | 124 | - ls: Display file and directory information 125 | - cd: Switch to the specified directory 126 | - rm: Delete files or directories 127 | - echo: Writes the specified content to the target file 128 | - cat: Displays the details of a file 129 | - mkdir: Create folders 130 | 131 | Please enter `help` to see more commands. 132 | 133 | ## More Functions 134 | 135 | Open the Env tool in the BSP directory and enter the `menuconfig` command: 136 | 137 | ![menuconfig](figures/menuconfig.png) 138 | 139 | You can configure more functions in the configuration interface. After the configuration is completed, save the configuration first, and then exit the configuration interface: 140 | 141 | ![menuconfig interface](figures/menuconfig_menu.png) 142 | 143 | 1. If you choose a package, you need to use the command `pkgs --update` to download the package. 144 | 2. Compile with `scons`. 145 | 3. Then enter `qemu.bat` to run. 146 | 4. Use `help` to view all commands of the BSP. And then use the commands. 147 | -------------------------------------------------------------------------------- /quick-start/quick_start_qemu/quick_start_qemu_linux.md: -------------------------------------------------------------------------------- 1 | # Getting Started of QEMU (Ubuntu) 2 | 3 | The development of embedded software is inseparable from the development board. Without physical development boards, similar virtual machines like QEMU can be used to simulate the development board. QEMU is a virtual machine that supports cross-platform virtualization. It can virtualize many development boards. To facilitate the experience of RT-Thread without a development board, RT-Thread provides a board-level support package (BSP) for QEMU-simulated **ARM vexpress A9** development board. 4 | 5 | ## 1 Install dependency libraries 6 | 7 | We need to type commands as following in the terminal: 8 | 9 | ```shell 10 | sudo apt install gcc 11 | sudo apt install python3 12 | sudo apt install python3-pip 13 | sudo apt install gcc-arm-none-eabi 14 | sudo apt install gdb-arm-none-eabi 15 | sudo apt install binutils-arm-none-eabi 16 | sudo apt install scons 17 | sudo apt install libncurses5-dev 18 | sudo apt install qemu 19 | sudo apt install qemu-system-arm 20 | sudo apt install git 21 | ``` 22 | 23 | ## 2 Get RT-Thread source code 24 | 25 | Download RT-Thread Source Code : `git clone https://github.com/RT-Thread/rt-thread.git` 26 | 27 | You can directly ignore the following steps, this is used for setting GCC compiler manually. Usually, you don't need to set this. 28 | 29 | > - Install the compiler. If the compiler version installed with `apt-get` command is too old, it will cause compilation errors. You can download and install the new version using the following command in turn. The download link and the decompression folder name will vary according to the download version. The following Compression Packet will unzip to the `/opt` folder. 30 | > 31 | > - `wget https://armkeil.blob.core.windows.net/developer/Files/downloads/gnu-rm/6-2016q4/gcc-arm-none-eabi-6_2-2016q4-20161216-linux.tar.bz2` 32 | > - `cd /opt` 33 | > - `sudo tar xf ~/gcc-arm-none-eabi-6_2-2016q4-20161216-linux.tar.bz2` 34 | > 35 | > 36 | > - After the compiler is installed, it is necessary to modify the `rtconfig.py` file under `rt-thread/bsp/qemu-vexpress-a9` BSP, modify the corresponding path to the bin directory corresponding to the compiler decompressed into the opt directory. Referring to the following figure, the directory name varies according to the downloaded version of the compiler: 37 | > 38 | > ![edit EXEC_PATH in rtconfig.py](figures/ubuntu-rtconfig-py.png) 39 | > 40 | 41 | 42 | 43 | ## 3 Build QEMU Project 44 | 45 | ### 3.1 Move into QEMU folder 46 | 47 | ``` 48 | cd rt-thread/bsp/qemu-vexpress-a9/ 49 | ``` 50 | 51 | ### 3.2 Configure the environment of Env tool 52 | 53 | #### 3.2.1 Remap python command 54 | 55 | We need to remap `python` command as python3 by default. 56 | 57 | Using `whereis` command to identify your python3's version: 58 | 59 | ![python3-version](figures/python3-version.png) 60 | 61 | For instance, as you can see, in my computer, the python3's version is python 3.9. You need to identify python3's version in your computer. Then, we remap the `python` command as python3 by default: 62 | 63 | ```shell 64 | sudo rm -rf /usr/bin/python3 65 | sudo rm -rf /usr/bin/python 66 | sudo ln -s /usr/bin/python3.9 /usr/bin/python3 67 | sudo ln -s /usr/bin/python3.9 /usr/bin/python 68 | ``` 69 | 70 | ### 3.3 Install Env and Configure BSP 71 | 72 | Type following the command under `bsp/qemu-vexpress-a9` folder: 73 | 74 | ``` 75 | scons --menuconfig 76 | ``` 77 | 78 | The Env tool will be installed and initialized after using the `scons --menuconfig` command. Then it will enter the configuration interface, and you could configure the BSP: 79 | 80 | ![install env tool](figures/ubuntu-menuconfig.png) 81 | 82 | ![enter the configuration interface](figures/ubuntu-env-menu.png) 83 | 84 | You can use the keyboard `↑` key and `↓` key to look up and down menu items, use the `Enter` key to enter the selected directory, use the `Space` key to select or cancel bool variables, and press `Esc Esc` to exit the current directory. 85 | 86 | > Notice: Please make sure that the terminal size is larger than 80x24 character size. 87 | 88 | ### 3.4 Configure the QEMU BSP and acquisition of software packages 89 | 90 | ``` 91 | source ~/.env/env.sh 92 | scons --menuconfig 93 | pkgs --update 94 | ``` 95 | 96 | The `env.sh` file is a file that needs to be executed. It configures the environment variables so that we can update the package with the pkgs command and execute it with the `source ~/.env/env.sh` command. 97 | 98 | Then use `scons --menuconfig` command to enter menuconfig, and you could select the online packages by this time. 99 | 100 | ![commands of acquisition of pkgs](figures/ubuntu-pkg-menuconfig.png) 101 | 102 | ![add pkg menu](figures/ubuntu-pkgs-add-to-menu.png) 103 | 104 | For example, select the kernel sample package: semphore sample. 105 | 106 | ![select a package](figures/ubuntu-select-pkg.png) 107 | 108 | Exit and save the configuration. 109 | 110 | ![save the configuration](figures/ubuntu-save.png) 111 | 112 | If you have selected an online package, you can download the package to the packages folder in the BSP directory using the `pkgs --update` command (Git needs to be installed): 113 | 114 | ![download the package](figures/ubuntu-update-pkg.png) 115 | 116 | #### 4.1 Tips 117 | 118 | Before you use the `pkgs` command, you need to type command `source ~/.env/env.sh`. This is a annoying work. We can attach this command as a new line at the end of `~/.bashrc`, which can let you to to use `pkgs` command directly. 119 | 120 | ### 3.5 Compile the QEMU project 121 | 122 | ``` 123 | scons 124 | ``` 125 | 126 | Using the `scons` command to compile the BSP. 127 | 128 | ![compile the BSP](figures/ubuntu-scons.png) 129 | 130 | ## 4 Introduction of QEMU BSP Catalogue 131 | 132 | The board-level support package (BSP) provided by RT-Thread simulates ARM vexpress A9 development board is located in the `qemu-vexpress-a9` folder under the `bsp` directory of RT-Thread source code. This BSP implements LCD, keyboard, mouse, SD card, Ethernet card, serial port and other related drivers. The contents of the folder are shown in the following figure. 133 | 134 | ![qemu-vexpress-a9 folder](figures/ubuntu-qemu-bsp.png) 135 | 136 | The main files and directories of `qemu-vexpress-a9` BSP are described as follows: 137 | 138 | | Fles/Directories | Description | 139 | | ---------------- | ------------------------------------------- | 140 | | applications | User application code directory | 141 | | drivers | The underlying driver provided by RT-Thread | 142 | | qemu.bat | Script files running on Windows platform | 143 | | qemu.sh | Script files running on Linux platform | 144 | | qemu-dbg.bat | Debugging script files on Windows platform | 145 | | qemu-dbg.sh | Debugging script files on Linux platform | 146 | | README.md | Description document of BSP | 147 | | rtconfig.h | A header file of BSP | 148 | 149 | ## 5 Compile and Run 150 | 151 | ### 5.1 Use the *scons* Command to Compile the Project 152 | 153 | Switch to the QEMU BSP directory and enter the `scons` command to compile the project. If the compilation is correct, the `rtthread.elf` file will be generated in the BSP directory, which is a target file required for QEMU to run. 154 | 155 | ![compile the project](figures/ubuntu-scons.png) 156 | 157 | ### 5.2 Use the *./qemu.sh* Command to Run the Project 158 | 159 | After compiling, type `./qemu.sh` to start the virtual machine and BSP project. `qemu.sh` is a Linux batch file. This file is located in the BSP folder, mainly including the execution instructions of QEMU. The first run of the project will create a blank `sd.bin` file under the BSP folder, which is a virtual SD card with a size of 64M. The Env command interface displays the initialization information and version number information printed during the start-up of RT-Thread system, and the QEMU virtual machine is also running. As shown in the following picture: 160 | 161 | ![run the project](figures/ubuntu-qume-sh.png) 162 | 163 | ### 5.3 Run the Finsh Console 164 | 165 | RT-Thread supports Finsh, and users can use command operations in command line mode. 166 | 167 | Type `help` or press `Tab` to view all supported commands. As shown in the figure below, commands are on the left and command descriptions are on the right. 168 | 169 | ![view all supported commands](figures/ubuntu-msh-help.png) 170 | 171 | For example, by entering the `list_thread` command, you can see the currently running threads, thread status and stack size; by entering the `list_timer`, you can see the status of the timers. 172 | 173 | ![threads and timers](figures/ubuntu-thread-timer.png) 174 | 175 | ### 5.4 Run the File System 176 | 177 | Type `list_device` to view all devices registered in the system. You can see the virtual SD card "sd0" device as shown in the following picture. Next, we can format the SD card using the `mkfs sd0` command, which will format the SD card into a FatFS file system. FatFs is a Microsoft fat-compatible file system developed for small embedded devices. It is written in ANSI C, uses abstract hardware I/O layer and provides continuous maintenance, so it has good portability. 178 | 179 | > For more information on FatFS, click on the link: [http://elm-chan.org/fsw/ff/00index_e.html](http://elm-chan.org/fsw/ff/00index_e.html) 180 | 181 | ![format the SD card](figures/ubuntu-mkfs-sd0.png) 182 | 183 | The file system will not be loaded immediately after the first formatting of the SD card, and the file system will be loaded correctly only after the second boot. So exit the virtual machine, and then restart the virtual machine and project by entering `./qemu.sh` on the command line interface. Entering `ls` command, you can see that the `Directory` directory has been added, the file system has been loaded, and then you can experience the file system with other commands provided by RT-Thread: 184 | 185 | ![commands of file system](figures/ubuntu-filesys.png) 186 | 187 | - ls: Display the file and directory information 188 | - cd: Switch to the specified directory 189 | - rm: Delete files or directories 190 | - echo: Writes the specified content to the target file 191 | - cat: Displays the details of a file 192 | - mkdir: Create folders 193 | 194 | Please enter `help` to see more commands. 195 | 196 | ## 6 More Functions 197 | 198 | You can configure more functions in the menuconfig's configuration interface. use `scons --menuconfig` to config the BSP. After the configuration is completed, save the configuration first, and then exit the configuration interface, then: 199 | 200 | 1. If you choose a package, you need to use the command `pkgs --update` to download the package. 201 | 2. Compile with `scons`. 202 | 3. Then enter `./qemu.sh` to run QEMU. 203 | 4. Use `help` to view all commands of the BSP. And then use the commands. 204 | -------------------------------------------------------------------------------- /quick-start/rtthread_simulator_v0.1.0.7z: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/rtthread_simulator_v0.1.0.7z -------------------------------------------------------------------------------- /quick-start/rtthread_simulator_v0.1.0.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/quick-start/rtthread_simulator_v0.1.0.zip -------------------------------------------------------------------------------- /sal/figures/sal_frame.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/sal/figures/sal_frame.jpg -------------------------------------------------------------------------------- /scons/figures/hello-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/scons/figures/hello-menu.png -------------------------------------------------------------------------------- /scons/figures/hello-rtconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/scons/figures/hello-rtconfig.png -------------------------------------------------------------------------------- /scons/figures/hello-value.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/scons/figures/hello-value.png -------------------------------------------------------------------------------- /scons/figures/hello.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/scons/figures/hello.png -------------------------------------------------------------------------------- /scons/figures/kconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/scons/figures/kconfig.png -------------------------------------------------------------------------------- /scons/figures/scons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/scons/figures/scons.png -------------------------------------------------------------------------------- /thread-comm/figures/07mb_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-comm/figures/07mb_ops.png -------------------------------------------------------------------------------- /thread-comm/figures/07mb_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-comm/figures/07mb_work.png -------------------------------------------------------------------------------- /thread-comm/figures/07msg_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-comm/figures/07msg_ops.png -------------------------------------------------------------------------------- /thread-comm/figures/07msg_syn.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-comm/figures/07msg_syn.png -------------------------------------------------------------------------------- /thread-comm/figures/07msg_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-comm/figures/07msg_work.png -------------------------------------------------------------------------------- /thread-comm/figures/07signal_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-comm/figures/07signal_ops.png -------------------------------------------------------------------------------- /thread-comm/figures/07signal_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-comm/figures/07signal_work.png -------------------------------------------------------------------------------- /thread-sync/figures/06event_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06event_ops.png -------------------------------------------------------------------------------- /thread-sync/figures/06event_use.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06event_use.png -------------------------------------------------------------------------------- /thread-sync/figures/06event_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06event_work.png -------------------------------------------------------------------------------- /thread-sync/figures/06inter_ths_commu1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06inter_ths_commu1.png -------------------------------------------------------------------------------- /thread-sync/figures/06inter_ths_commu2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06inter_ths_commu2.png -------------------------------------------------------------------------------- /thread-sync/figures/06mutex_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06mutex_ops.png -------------------------------------------------------------------------------- /thread-sync/figures/06mutex_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06mutex_work.png -------------------------------------------------------------------------------- /thread-sync/figures/06priority_inherit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06priority_inherit.png -------------------------------------------------------------------------------- /thread-sync/figures/06priority_inversion.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06priority_inversion.png -------------------------------------------------------------------------------- /thread-sync/figures/06sem_lock.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06sem_lock.png -------------------------------------------------------------------------------- /thread-sync/figures/06sem_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06sem_ops.png -------------------------------------------------------------------------------- /thread-sync/figures/06sem_work.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread-sync/figures/06sem_work.png -------------------------------------------------------------------------------- /thread/figures/04Object_container.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread/figures/04Object_container.png -------------------------------------------------------------------------------- /thread/figures/04Task_switching.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread/figures/04Task_switching.png -------------------------------------------------------------------------------- /thread/figures/04main_thread.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread/figures/04main_thread.png -------------------------------------------------------------------------------- /thread/figures/04thread_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread/figures/04thread_ops.png -------------------------------------------------------------------------------- /thread/figures/04thread_sta.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread/figures/04thread_sta.png -------------------------------------------------------------------------------- /thread/figures/04thread_stack.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread/figures/04thread_stack.png -------------------------------------------------------------------------------- /thread/figures/04time_slience.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/thread/figures/04time_slience.png -------------------------------------------------------------------------------- /timer/figures/05timer_env.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/timer/figures/05timer_env.png -------------------------------------------------------------------------------- /timer/figures/05timer_linked_list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/timer/figures/05timer_linked_list.png -------------------------------------------------------------------------------- /timer/figures/05timer_linked_list2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/timer/figures/05timer_linked_list2.png -------------------------------------------------------------------------------- /timer/figures/05timer_ops.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/timer/figures/05timer_ops.png -------------------------------------------------------------------------------- /timer/figures/05timer_skip_list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/timer/figures/05timer_skip_list.png -------------------------------------------------------------------------------- /timer/figures/05timer_skip_list2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/timer/figures/05timer_skip_list2.png -------------------------------------------------------------------------------- /timer/figures/05timer_skip_list3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/timer/figures/05timer_skip_list3.png -------------------------------------------------------------------------------- /ulog/figures/ulog_async_vs_sync.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_async_vs_sync.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example_all_format.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example_all_format.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example_async.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example_async.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example_filter20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example_filter20.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example_filter30.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example_filter30.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example_filter40.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example_filter40.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example_hexdump.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example_hexdump.png -------------------------------------------------------------------------------- /ulog/figures/ulog_example_syslog.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_example_syslog.png -------------------------------------------------------------------------------- /ulog/figures/ulog_framework.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_framework.png -------------------------------------------------------------------------------- /ulog/figures/ulog_framework_backend.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_framework_backend.png -------------------------------------------------------------------------------- /ulog/figures/ulog_menuconfig_async.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_menuconfig_async.png -------------------------------------------------------------------------------- /ulog/figures/ulog_menuconfig_format.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_menuconfig_format.png -------------------------------------------------------------------------------- /ulog/figures/ulog_syslog_format.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/ulog/figures/ulog_syslog_format.png -------------------------------------------------------------------------------- /utest/figures/UtestAppStruct-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/utest/figures/UtestAppStruct-1.png -------------------------------------------------------------------------------- /utest/figures/UtestRunLogShow.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/utest/figures/UtestRunLogShow.png -------------------------------------------------------------------------------- /utest/figures/testcase-runflowchart.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/RT-Thread/rtthread-manual-doc/16eb4600ec7f8ea8b037abd7e1cfc2eaba9baf39/utest/figures/testcase-runflowchart.jpg -------------------------------------------------------------------------------- /utest/utest.md: -------------------------------------------------------------------------------- 1 | # utest Framework 2 | 3 | ## utest Introduction 4 | 5 | utest (unit test) is a unit testing framework developed by RT-Thread. The original intention of designing utest is to make it easier for RT-Thread developers to write test programs using a unified framework interface for unit testing, coverage testing, and integration testing. 6 | 7 | ### Test Case Definition 8 | 9 | A test case (tc) is a single test performed to achieve a specific test objective. It is a specification that includes test input, execution conditions, test procedures, and expected results. It is a infinite loop with clear end conditions and test results. 10 | 11 | The utest (unit test) framework defines user-written test programs as **test cases**, and a test case contains only one *testcase* function (similar to the main function), which can contain multiple *test unit* functions. 12 | 13 | The test code for a function, specifically through the API provided by the utest framework, is a test case. 14 | 15 | ### Test Unit Definition 16 | 17 | The test unit is a test point subdivided by the function to be tested. Each test point can be the smallest measurable unit of the function to be tested. Of course, different classification methods will subdivide different test units. 18 | 19 | ### utest Application Block Diagram 20 | 21 | ![utest Application Block Diagram](./figures/UtestAppStruct-1.png) 22 | 23 | As shown in the figure above, the test case is designed based on the service interface provided by the test framework utest, which supports compiling multiple test cases together for testing. In addition, as you can see from the figure, a test case corresponds to a unique *testcase* function, and multiple test units are included in *testcase*. 24 | 25 | ## utest API 26 | 27 | To enable uniform test case code, the test framework utest provides a common API interface for test case writing. 28 | 29 | ### Macros of assertion 30 | 31 | > NOTE: 32 | > Here assert only records the number of passes and failures, it does not generate assertions or terminates program execution. Its function is not equivalent to RT_ASSERT. 33 | 34 | 35 | | assert Macro | Description | 36 | | :------ | :------ | 37 | | uassert_true(value) | If the value is true then the test passes, otherwise the test fails. | 38 | | uassert_false(value) | If the value is false then the test passes, otherwise the test fails. | 39 | | uassert_null(value) | If the Value is null then the test passes, otherwise the test fails | 40 | | uassert_not_null(value)| If the value is a non-null value, the test passes, otherwise the test fails. | 41 | | uassert_int_equal(a, b)| If the values of a and b are equal, the test passes, otherwise the test fails. | 42 | | uassert_int_not_equal(a, b)| If the values of a and b are not equal, the test passes, otherwise the test fails. | 43 | | uassert_str_equal(a, b) | If the string a and the string b are the same, the test passes, otherwise the test fails. | 44 | | uassert_str_not_equal(a, b)| If the string a and the string b are not the same, the test passes, otherwise the test fails. | 45 | | uassert_in_range(value, min, max) | If the value is in the range of min and max, the test passes, otherwise the test fails. | 46 | | uassert_not_in_range(value, min, max)| If the value is not in the range of min and max, the test passes, otherwise the test fails. | 47 | 48 | ### Macros for Running Test Units 49 | 50 | ```c 51 | UTEST_UNIT_RUN(test_unit_func) 52 | ``` 53 | 54 | In the test case, the specified test unit function `test_unit_func` is executed using the `UTEST_UNIT_RUN` macro. The test unit must be executed using the `UTEST_UNIT_RUN` macro. 55 | 56 | ### Macros for Exporting Test Cases 57 | 58 | ```c 59 | UTEST_TC_EXPORT(testcase, name, init, cleanup, timeout) 60 | ``` 61 | 62 | | Parameters | Description | 63 | | :----- | :------ | 64 | | testcase | Test case main-bearing function (**specifies** using a function called *static void testcase(void)* | 65 | | name | Test case name (uniqueness). Specifies the naming format for connecting relative names of test cases relative to `testcases directory` with `.` | 66 | | init | the initialization function before Test case startup | 67 | | cleanup | Cleanup function after the end of the test case | 68 | | timeout | Test case expected test time (in seconds) | 69 | 70 | **Test case naming requirements:** 71 | 72 | Test cases need to be named in the prescribed format. Specifies the naming format for the connection of the current test case relative to the `testcases directory ` linked with `.` . The name contains the file name of the current test case file (the file name except the suffix name). 73 | 74 | **Test case naming example:** 75 | 76 | Assuming that there is a `testcases\components\filesystem\dfs\dfs_api_tc.c` test case file in the test case `testcases` directory, the test case name in the `dfs_api_tc.c` is named `components.filesystem.dfs.dfs_api_tc`. 77 | 78 | ### Test Case LOG Output Interface 79 | 80 | The utest framework relies on the *ulog log module* for log output and the log output level in the utest framework. So just add `#include "utest.h"` to the test case to use all level interfaces (LOG_D/LOG_I/LOG_E) of the ulog log module. 81 | 82 | In addition, the utest framework adds an additional log control interface as follows: 83 | 84 | ```c 85 | #define UTEST_LOG_ALL (1u) 86 | #define UTEST_LOG_ASSERT (2u) 87 | 88 | void utest_log_lv_set(rt_uint8_t lv); 89 | ``` 90 | 91 | Users can use the `utest_log_lv_set` interface to control the log output level in test cases. The `UTEST_LOG_ALL` configuration outputs all logs, and the `UTEST_LOG_ASSERT` configuration only outputs logs after the failure of uassert. 92 | 93 | ## Configuration Enable 94 | 95 | Using the utest framework requires the following configuration in the ENV tool using menuconfig: 96 | 97 | ```c 98 | RT-Thread Kernel ---> 99 | Kernel Device Object ---> 100 | (256) the buffer size for console log printf /* The minimum buffer required by the utest log */ 101 | RT-Thread Components ---> 102 | Utilities ---> 103 | -*- Enable utest (RT-Thread test framework) /* Enable utest framework */ 104 | (4096) The utest thread stack size /* Set the utest thread stack (required for -thread mode) */ 105 | (20) The utest thread priority /* Set utest thread priority (required for -thread mode) */ 106 | ``` 107 | 108 | ## Application Paradigm 109 | 110 | The utest framework and related APIs were introduced earlier. The basic test case code structure is described here. 111 | 112 | The code blocks necessary for the test case file are as follows: 113 | 114 | ```c 115 | /* 116 | * Copyright (c) 2006-2019, RT-Thread Development Team 117 | * 118 | * SPDX-License-Identifier: Apache-2.0 119 | * 120 | * Change Logs: 121 | * Date Author Notes 122 | * 2019-01-16 MurphyZhao the first version 123 | */ 124 | 125 | #include 126 | #include "utest.h" 127 | 128 | static void test_xxx(void) 129 | { 130 | uassert_true(1); 131 | } 132 | 133 | static rt_err_t utest_tc_init(void) 134 | { 135 | return RT_EOK; 136 | } 137 | 138 | static rt_err_t utest_tc_cleanup(void) 139 | { 140 | return RT_EOK; 141 | } 142 | 143 | static void testcase(void) 144 | { 145 | UTEST_UNIT_RUN(test_xxx); 146 | } 147 | UTEST_TC_EXPORT(testcase, "components.utilities.utest.sample.sample_tc", utest_tc_init, utest_tc_cleanup, 10); 148 | ``` 149 | 150 | A basic test case must contain the following: 151 | 152 | - File comment header (Copyright) 153 | 154 | The test case file must contain a file comment header containing `Copyright`, time, author, and description information. 155 | 156 | - utest_tc_init(void) 157 | 158 | The initialization function before the test run is generally used to initialize the environment required for the test. 159 | 160 | - utest_tc_cleanup(void) 161 | 162 | The cleanup function after the test is used to clean up the resources (such as memory, threads, semaphores, etc.) applied during the test. 163 | 164 | - testcase(void) 165 | 166 | The mainly function of testcase, a test case implementation can only contain one testcase function (similar to the main function). Usually this function is only used to run the test unit execution function `UTEST_UNIT_RUN`. 167 | 168 | A testcase can contain multiple test units, each of which is executed by `UTEST_UNIT_RUN`. 169 | 170 | - UTEST_UNIT_RUN 171 | 172 | Test unit execution function. 173 | 174 | - test_xxx(void) 175 | 176 | Test implementation of each functional unit. The user determines the function name and function implementation based on the requirements. 177 | 178 | - uassert_true 179 | 180 | The assertion macro used to determine the test result (this assertion macro does not terminate the program run). Test cases must use the `uassert_xxx` macro to determine the test results, otherwise the test framework does not know if the test passed. 181 | 182 | After all the `uassert_xxx` macros have been passed, the entire test case is passed. 183 | 184 | - UTEST_TC_EXPORT 185 | 186 | Export the test case testcase function to the test framework. 187 | 188 | ## Requirements for running test cases 189 | 190 | The test framework utest exports all test cases to the `UtestTcTab` code segment. The `UtestTcTab` section is not required to be defined in the link script in the IAR and MDK compilers, but it needs to be explicitly set in the link script when GCC is compiled. 191 | 192 | Therefore, in order for test cases to be compiled and run under GCC, the `UtestTcTab` code segment must be defined in the *link script* of GCC. 193 | 194 | In the `.text` of the GCC link script, add the definition of the `UtestTcTab` section in the following format: 195 | 196 | ```c 197 | /* section information for utest */ 198 | . = ALIGN(4); 199 | __rt_utest_tc_tab_start = .; 200 | KEEP(*(UtestTcTab)) 201 | __rt_utest_tc_tab_end = .; 202 | ``` 203 | 204 | ## Running Test Cases 205 | 206 | The test framework provides the following commands to make it easy for users to run test cases on the RT-Thread MSH command line. The commands are as follows: 207 | 208 | ***utest_list* command** 209 | 210 | Lists the test cases supported by the current system, including the name of the test case and the time required for the test. This command has no parameters. 211 | 212 | ***utest_run* command** 213 | 214 | Test case execution command, the format of the command is as follows: 215 | 216 | ```c 217 | utest_run [-thread or -help] [testcase name] [loop num] 218 | ``` 219 | 220 | | utest_run Command Parameters | Description | 221 | | :---- | :----- | 222 | | -thread | Run the test framework in threaded mode | 223 | | -help | Print help information | 224 | | testcase name | Specify the test case name. Using the wildcard `*` is supported, specifying front byte of the test case name is supported. | 225 | | loop num | the number of iterations of test cases | 226 | 227 | **Example of test command usage:** 228 | 229 | ```c 230 | msh />utest_list 231 | [14875] I/utest: Commands list : 232 | [14879] I/utest: [testcase name]:components.filesystem.dfs.dfs_api_tc; [run timeout]:30 233 | [14889] I/utest: [testcase name]:components.filesystem.posix.posix_api_tc; [run timeout]:30 234 | [14899] I/utest: [testcase name]:packages.iot.netutils.iperf.iperf_tc; [run timeout]:30 235 | msh /> 236 | msh />utest_run components.filesystem.dfs.dfs_api_tc 237 | [83706] I/utest: [==========] [ utest ] started 238 | [83712] I/utest: [----------] [ testcase ] (components.filesystem.dfs.dfs_api_tc) started 239 | [83721] I/testcase: in testcase func... 240 | [84615] D/utest: [ OK ] [ unit ] (test_mkfs:26) is passed 241 | [84624] D/testcase: dfs mount rst: 0 242 | [84628] D/utest: [ OK ] [ unit ] (test_dfs_mount:35) is passed 243 | [84639] D/utest: [ OK ] [ unit ] (test_dfs_open:40) is passed 244 | [84762] D/utest: [ OK ] [ unit ] (test_dfs_write:74) is passed 245 | [84770] D/utest: [ OK ] [ unit ] (test_dfs_read:113) is passed 246 | [85116] D/utest: [ OK ] [ unit ] (test_dfs_close:118) is passed 247 | [85123] I/utest: [ PASSED ] [ result ] testcase (components.filesystem.dfs.dfs_api_tc) 248 | [85133] I/utest: [----------] [ testcase ] (components.filesystem.dfs.dfs_api_tc) finished 249 | [85143] I/utest: [==========] [ utest ] finished 250 | msh /> 251 | ``` 252 | 253 | ### Test result analysis 254 | 255 | ![utest log display](./figures/UtestRunLogShow.png) 256 | 257 | As shown in the figure above, the log of the test case run is divided into four columns from left to right, which are `(1) log header information`, `(2) result bar`, `(3) property bar`, and `(4) detail information display bar`. The test case test result (PASSED or FAILED) is identified in the log using the `result` attribute. 258 | 259 | ## Test Case Run Process 260 | 261 | ![Test Case Run Process](./figures/testcase-runflowchart.jpg) 262 | 263 | From the above flow chart you can get the following: 264 | 265 | * The utest framework is a sequential execution of all **test units** in the *testcase* function 266 | * Assert of the previous UTEST_UNIT_RUN macro has occurred, and all subsequent UTEST_UNIT_RUN will skip execution. 267 | 268 | ## NOTE 269 | 270 | - Determine whether the link script has the `UtestTcTab` section added before compiling with GCC. 271 | - Make sure `RT-Thread Kernel -> Kernel Device Object -> (256) the buffer size for console log printf` is at least 256 bytes before compiling. 272 | - The resources (threads, semaphores, timers, memory, etc.) created in the test case need to be released before the test ends. 273 | - A test case implementation can only export a test body function (testcase function) using `UTEST_TC_EXPORT` 274 | - Write a `README.md` document for the your test case to guide the user through configuring the test environment. 275 | --------------------------------------------------------------------------------