From 22b97b2d7743006973ed8e6fb423f4b8e4c925f8 Mon Sep 17 00:00:00 2001 From: Max Payne Date: Thu, 17 May 2018 11:53:59 +0300 Subject: [PATCH] docs, examples: migrate hello-world example Host platform fixed to support API similar to other platforms. Example is extended to use STM32 and TM4C platform. Example code is changed to more appropriate (taken from https://github.com/forGGe/theCore/pull/377) --- doc/sphinx/source/examples/blinky.rst | 12 +- .../source/examples/hello-world-host.rst | 50 ------- doc/sphinx/source/examples/hello-world.rst | 127 ++++++++++++++++++ doc/sphinx/source/examples/index.rst | 2 +- doc/sphinx/source/platform/host.rst | 2 +- .../source/platform/ti-tivac-tm4c123g.rst | 1 + examples/CMakeLists.txt | 12 -- examples/host_hello/CMakeLists.txt | 31 ----- examples/host_hello/README.md | 3 - examples/host_hello/host.json | 3 - examples/host_hello/main.cpp | 13 -- platform/host/CMakeLists.txt | 7 + platform/host/templates/generated.in.hpp | 14 ++ 13 files changed, 157 insertions(+), 120 deletions(-) delete mode 100644 doc/sphinx/source/examples/hello-world-host.rst create mode 100644 doc/sphinx/source/examples/hello-world.rst delete mode 100644 examples/host_hello/CMakeLists.txt delete mode 100644 examples/host_hello/README.md delete mode 100644 examples/host_hello/host.json delete mode 100644 examples/host_hello/main.cpp create mode 100644 platform/host/templates/generated.in.hpp diff --git a/doc/sphinx/source/examples/blinky.rst b/doc/sphinx/source/examples/blinky.rst index 990f21b2..dfff4b60 100644 --- a/doc/sphinx/source/examples/blinky.rst +++ b/doc/sphinx/source/examples/blinky.rst @@ -24,8 +24,8 @@ Wiring No special wiring is required. Just connect the board to the powered USB port. -Building -~~~~~~~~ +Preparing +~~~~~~~~~ #. Install theCore (this may take a while):: @@ -40,14 +40,14 @@ Building cd example_blinky -#. Compile: +Building +~~~~~~~~ - * For STM32 Discovery board:: +* For STM32 Discovery board:: - cd example_blinky tcore compile --target stm32f4_disc - * For Tiva TM4C LaunchPad:: +* For Tiva TM4C LaunchPad:: tcore compile --target tiva_tm4c_launchpad diff --git a/doc/sphinx/source/examples/hello-world-host.rst b/doc/sphinx/source/examples/hello-world-host.rst deleted file mode 100644 index 7e5762a6..00000000 --- a/doc/sphinx/source/examples/hello-world-host.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _theCore_host_hello: - -Simple host hello world example -------------------------------- - -:Location: ``examples/host_hello`` -:Target: host -:External HW: none -:Toolchain: gcc/g++ v5.2 or newer -:Additional SW: none - -This example shows theCore running on the host target. -By `host` target is understood an environment capable to both compile and -run theCore applications. - -Application demonstrates a console stream usage and a simple assertion. - -Building -~~~~~~~~ - -#. Complete :ref:`theCore_examples_initial_setup` section. -#. Execute build commands:: - - cd examples/host_hello - mkdir build - cd build - cmake .. - make - -Running -~~~~~~~ - -Execute resulting application:: - - ./hello - -Expected output -~~~~~~~~~~~~~~~ - -:: - - Hello, Host World! - This is an assert demonstration. Application will abort. - hello: main.cpp:7: int main(): Assertion `1 == 0' failed. - Aborted (core dumped) - -Target JSON for Hello World example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. literalinclude:: ../../../../examples/host_hello/host.json diff --git a/doc/sphinx/source/examples/hello-world.rst b/doc/sphinx/source/examples/hello-world.rst new file mode 100644 index 00000000..16c20f59 --- /dev/null +++ b/doc/sphinx/source/examples/hello-world.rst @@ -0,0 +1,127 @@ +.. _theCore_hello_world: + +Simple host hello world example +------------------------------- + +:Location: https://github.com/theCore-embedded/example_hello_world +:External HW: UART-to-USB converter for STM32F4Discovery board + +Supported targets (boards) +~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++---------------------+--------------------------+-----------------------------------+ +| Target name | Configuration file | Description | ++=====================+==========================+===================================+ +| host | host.json | Host target build | ++---------------------+--------------------------+-----------------------------------+ +| stm32f4_disc | stm32f4_discovery.json | STM32F4 discovery board | ++---------------------+--------------------------+-----------------------------------+ +| tiva_tm4c_launchpad | tiva_tm4c_launchpad.json | TM4C123G LaunchPad Evaluation Kit | ++---------------------+--------------------------+-----------------------------------+ + +Wiring +~~~~~~ + +* If you have Tiva TM4C Launchpad - simply connect it to the USB. + +* If you have STM32F4 Discovery board: + + #. Attach any preferable UART-to-USB + converter module (`such as this`_) according to following pinout: + + +-------------------+-----------------+ + | PD8 (USART3 TX) | module's RX | + +-------------------+-----------------+ + | PD9 (USART3 RX) | module's TX | + +-------------------+-----------------+ + | GND | module's GND | + +-------------------+-----------------+ + + #. Connect your STM32 Discovery board to the PC. + +Preparing +~~~~~~~~~ + +#. Install and initialize theCore (if not done previously):: + + pip3 install tcore + tcore bootstrap + +#. Download the example:: + + tcore init --remote https://github.com/theCore-embedded/example_hello_world + +#. Step into the project directory:: + + cd example_hello_world + +Building +~~~~~~~~ + +* For STM32 Discovery board:: + + tcore compile --target stm32f4_disc + +* For Tiva TM4C LaunchPad:: + + tcore compile --target tiva_tm4c_launchpad + +* For host:: + + tcore compile --target host + +Running +~~~~~~~ + +#. If you wish to run the example on the embedded device, launch `minicom` + with device associated with USB <-> UART converter. + (``/dev/ttyUSB0`` here used as an example):: + + # From new terminal + tcore runenv "minicom -D /dev/ttyUSB0" + + Or the same, but with superuser permissions:: + + # From new terminal + tcore runenv --sudo "minicom -D /dev/ttyUSB0" + +#. Run: + + * On TivaC launchpad:: + + tcore --sudo flash + + * For old STM32F407G-DISC boards, with STLINK/V2:: + + tcore --sudo flash + + * For new STM32F407G-DISC1 boards, with STLINK/V2.1:: + + tcore --sudo flash --debugger-config stlink-v2.1 + + * For host target, execute:: + + ./build/host/hello_world + +Expected output +~~~~~~~~~~~~~~~ + +Observe console output (either in current shell if running on host, or using + minicom if running on the embedded device):: + + Welcome to theCore + the_core v0.3.0.307 9ff344b-dirty + Hello World! + + Starting delay demonstration... + + [--] Waiting for 2 seconds + [--] Done waiting 2 seconds + + [----] Waiting for 4 seconds + [----] Done waiting 4 seconds + + [--------] Waiting for 8 seconds + [--------] Done waiting 8 seconds + +.. _such as this: http://www.geekfactory.mx/wp-content/uploads/2013/06/converdidor_usb_ttl_rs232_pl_2303hx_01.jpg diff --git a/doc/sphinx/source/examples/index.rst b/doc/sphinx/source/examples/index.rst index 4bd62e1d..a9204437 100644 --- a/doc/sphinx/source/examples/index.rst +++ b/doc/sphinx/source/examples/index.rst @@ -8,7 +8,7 @@ Examples :includehidden: blinky - hello-world-host + hello-world stm32f4-discovery-htu21d-sensor stm32f4-discovery-cs43l22 stm32f4-discovery-exti diff --git a/doc/sphinx/source/platform/host.rst b/doc/sphinx/source/platform/host.rst index ac2df95c..35b44916 100644 --- a/doc/sphinx/source/platform/host.rst +++ b/doc/sphinx/source/platform/host.rst @@ -22,4 +22,4 @@ For more details on theCore console, check the :ref:`theCore_Console` section. Related references ~~~~~~~~~~~~~~~~~~ -* :ref:`theCore_host_hello` +* :ref:`theCore_hello_world` diff --git a/doc/sphinx/source/platform/ti-tivac-tm4c123g.rst b/doc/sphinx/source/platform/ti-tivac-tm4c123g.rst index f78d585d..41764826 100644 --- a/doc/sphinx/source/platform/ti-tivac-tm4c123g.rst +++ b/doc/sphinx/source/platform/ti-tivac-tm4c123g.rst @@ -51,6 +51,7 @@ Available examples * :ref:`theCore_TM4C_FATFS_SDSPI` * :ref:`theCore_blinky` +* :ref:`theCore_hello_world` Periphery overview ~~~~~~~~~~~~~~~~~~ diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 9a6aa3a7..14197d40 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -18,18 +18,6 @@ set(THECORE_BUILD_THIRDPARTY_DIR "${CMAKE_CURRENT_BINARY_DIR}/thirdparty_worktre # Convinient alias set(ARM_CM4_GNU_TOOLCHAIN ${CMAKE_CURRENT_LIST_DIR}/../toolchains/arm-cm4-gnu.cmake) -################################################################################ -# Hello World host example. -################################################################################ - -ExternalProject_Add(host_hello - SOURCE_DIR ${CMAKE_CURRENT_LIST_DIR}/host_hello - CMAKE_ARGS - -DTHECORE_BUILD_THIRDPARTY_DIR=${THECORE_BUILD_THIRDPARTY_DIR} - -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE} - BUILD_ALWAYS 1 # Allows to rebuild external project if its files changes - INSTALL_COMMAND echo "Install isn't required, skipping...") - ################################################################################ # External interrupt stm32 demo. ################################################################################ diff --git a/examples/host_hello/CMakeLists.txt b/examples/host_hello/CMakeLists.txt deleted file mode 100644 index cfd32888..00000000 --- a/examples/host_hello/CMakeLists.txt +++ /dev/null @@ -1,31 +0,0 @@ -# This Source Code Form is subject to the terms of the Mozilla Public -# License, v. 2.0. If a copy of the MPL was not distributed with this -# file, You can obtain one at http://mozilla.org/MPL/2.0/. - -cmake_minimum_required(VERSION 3.2) - -# theCore framework directory. -set(CORE_DIR ../../) - -# Required. -include(${CORE_DIR}/build_api.cmake) - -# Obvious. -project(host_hello) - -# Our demo sources. -add_executable(hello main.cpp) - -# Obvious -set(CONFIG_RUN_CPPCHECK_DURING_BUILD true) - -# Some dependencies -target_link_libraries(hello the_core) -target_link_libraries(hello core_cpp) -target_link_libraries(hello host) - -# Host configuration parameters -theCore_set_target_config(${CMAKE_CURRENT_LIST_DIR}/host.json) - -# Include theCore into the build process -add_subdirectory(${CORE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/core) diff --git a/examples/host_hello/README.md b/examples/host_hello/README.md deleted file mode 100644 index 75c7b23d..00000000 --- a/examples/host_hello/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# theCore _Hello World_ host example - -This example description and documentation is located in [theCore website](https://forgge.github.io/theCore/examples.html#simple-host-hello-world-example) \ No newline at end of file diff --git a/examples/host_hello/host.json b/examples/host_hello/host.json deleted file mode 100644 index f369e12f..00000000 --- a/examples/host_hello/host.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "platform": { "name" : "host", "console": true } -} diff --git a/examples/host_hello/main.cpp b/examples/host_hello/main.cpp deleted file mode 100644 index 954dd126..00000000 --- a/examples/host_hello/main.cpp +++ /dev/null @@ -1,13 +0,0 @@ -/* This Source Code Form is subject to the terms of the Mozilla Public - * License, v. 2.0. If a copy of the MPL was not distributed with this - * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ - -#include -#include - -int main() -{ - ecl::cout << "Hello, Host World!" << ecl::endl; - ecl_assert_msg(1 == 0, "This is an assert demonstration. Application will abort."); - return 0; -} diff --git a/platform/host/CMakeLists.txt b/platform/host/CMakeLists.txt index bee0f826..e7cb1506 100644 --- a/platform/host/CMakeLists.txt +++ b/platform/host/CMakeLists.txt @@ -24,6 +24,13 @@ configure_file( ${CMAKE_CURRENT_BINARY_DIR}/export/aux/platform_defines.hpp ) +# Platform-generated code + +configure_file( + ${CMAKE_CURRENT_LIST_DIR}/templates/generated.in.hpp + ${CMAKE_CURRENT_BINARY_DIR}/export/aux/generated.hpp +) + target_include_directories(host PUBLIC export export/platform ${CMAKE_CURRENT_BINARY_DIR}/export/) target_link_libraries(host PUBLIC types) diff --git a/platform/host/templates/generated.in.hpp b/platform/host/templates/generated.in.hpp new file mode 100644 index 00000000..1514d230 --- /dev/null +++ b/platform/host/templates/generated.in.hpp @@ -0,0 +1,14 @@ +/* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ + +//! \file +//! \brief Generated definitions template +#ifndef HOST_PLATFORM_GENERATED_ +#define HOST_PLATFORM_GENERATED_ + +// No GPIO on host platform. +extern "C" +inline void gpio_init_generated() { } + +#endif // HOST_PLATFORM_GENERATED_