[Example][EMNIST] Fix APplication build and update wordong in readmes/tutorial

dzakhar · dzakhar · commit e1e96a653728 · 2021-09-14T15:40:30.000+03:00
diff --git a/examples/tutorial_emnist_tflm/CMakeLists.txt b/examples/tutorial_emnist_tflm/CMakeLists.txt
@@ -28,6 +28,7 @@ if (ARC)
         -Hxcheck
         -Hcrt_initbss
     )
+    get_filename_component(TCF_FILE_NAME ${ARC_CFG_TCF_PATH} NAME_WE)
 else()
     set(EXAMPLE_FLAGS)
 endif()
@@ -41,7 +42,7 @@ add_executable(${TARGET}
     ./src/test_samples.cc
 )
 
-target_link_libraries(${TARGET} PUBLIC $ENV{TENSORFLOW_DIR}/tensorflow/lite/micro/tools/make/downloads/arc_mli_$ENV{TCF_FILE_NAME}_mli20/bin/arc/libmli.a)
+target_link_libraries(${TARGET} PUBLIC $ENV{TENSORFLOW_DIR}/tensorflow/lite/micro/tools/make/downloads/arc_mli_${TCF_FILE_NAME}_mli20/bin/arc/libmli.a)
 target_link_libraries(${TARGET} PRIVATE tensorflow-microlite)
 
 target_include_directories(${TARGET} PRIVATE
diff --git a/examples/tutorial_emnist_tflm/Makefile b/examples/tutorial_emnist_tflm/Makefile
@@ -13,20 +13,20 @@ ifeq ($(TENSORFLOW_DIR),)
     $(error cannot find tensorflow -- TENSORFLOW_DIR variable must be set)
 endif
 
+BUILD_TARGET = tutorial_emnist_tflm
 BUILD_SUBDIR = examples$(PS)tutorial_emnist_tflm
 BIN_PATH = $(BUILD_DIR)$(PS)$(BUILD_SUBDIR)$(PS)bin
 
 ifndef TCF_FILE
 	RUN_APP_CMD =
 else
-	RUN_APP_CMD = mdb -cl -nsim -cmd=run -off=cr_for_more -cmd=exit -tcf=$(TCF_FILE)
+	RUN_APP_CMD = mdb64 -cl -nsim -cmd=run -off=cr_for_more -cmd=exit -tcf=$(TCF_FILE)
 	BIN_EXT = .elf
 endif
 
-export TCF_FILE_NAME = $(basename $(notdir $(TCF_FILE)))
 app: build
 
 run:
-	$(RUN_APP_CMD) $(BIN_PATH)$(PS)tutorial_emnist_tflm$(BIN_EXT) $(RUN_ARGS)
+	$(RUN_APP_CMD) $(BIN_PATH)$(PS)$(BUILD_TARGET)$(BIN_EXT) $(RUN_ARGS)
 
 .PHONY: app
diff --git a/examples/tutorial_emnist_tflm/README.md b/examples/tutorial_emnist_tflm/README.md
@@ -1,19 +1,16 @@
-EMNIST Example: Tensorflow Lite Micro Usage
-========================================================================
-This example shows how to use Tensorflow Lite Micro together with embARC MLI application. It consists of two parts:
+# EMNIST Example: Tensorflow Lite Micro Usage
+
+This example shows how to use Tensorflow Lite Micro together with an embARC MLI application. It consists of two parts:
 
 1) Example application. It demonstrates how to use the tflite-micro API and guides you through the building aspects of the application and libraries.
 
 2) Conversion Tutorial. An independent part showing how the NN model for the application was converted into tflite format and adapted to be MLI compatible.
 
-The first part is disclosed in this readme. The details of the conversion tutorial are covered in the separate [readme](/examples/tutorial_emnist_tflm/conversion_tutorial/README.md) in the [*conversion_tutorial*](/examples/tutorial_emnist_tflm/conversion_tutorial) directory. Passing the second part is not necessary to run the example application.
-
+The first part is disclosed in this readme. The details of the conversion tutorial are covered in the separate readme file in the [*conversion_tutorial*](/examples/tutorial_emnist_tflm/conversion_tutorial) directory. Passing the second part is not necessary to run the example application.
 
  **Important notes:**
- * Example is supported only for VPX configurations with guard bits. For EM/HS, please use [MLI 1.1 release version](https://github.com/foss-for-synopsys-dwc-arc-processors/embarc_mli/tree/Release_1.1/examples/tutorial_emnist_tflm).
 
-
-# Building and Running
+* Example is supported only for VPX configurations with guard bits. For EM/HS, please use [MLI 1.1 release version](https://github.com/foss-for-synopsys-dwc-arc-processors/embarc_mli/tree/Release_1.1/examples/tutorial_emnist_tflm).
 
 ## Generate Tensorflow Lite Micro Library
 
@@ -23,40 +20,36 @@ Tensorflow Lite for Microcontrollers is a separate project with specific set of
 
     git clone https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro.git
 
-The fork has been updating periodically from the [upstream repo](https://github.com/tensorflow/tflite-micro) using states that are stable in relation to ARC target: 
+The fork has been updating periodically from the [upstream repo](https://github.com/tensorflow/tflite-micro) using states that are stable in relation to ARC target.
 
-Please first familiarize yourself with [TFLM ARC specific details](https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro/blob/main/tensorflow/lite/micro/tools/make/targets/arc/README.md) and make sure that your environment is set up appropriately. 
+Please first familiarize yourself with [TFLM ARC specific details](https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro/blob/main/tensorflow/lite/micro/tools/make/targets/arc/README.md) and make sure that your environment is set up appropriately.
 
-Important information is listed inside [make tool section](https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro/tree/main/tensorflow/lite/micro/tools/make/targets/arc#make-tool) of the referred document. 
-The main message is that native *nix environment is required to build the TFLM library. 
-For Windows users there are no officially supported flow. 
+Important information is listed inside [make tool section](https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro/tree/main/tensorflow/lite/micro/tools/make/targets/arc#make-tool) of the referred document.
+The main message is that native *nix environment is required to build the TFLM library.
+For Windows users there are no officially supported flow.
 You still may consider projects like [WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) at your own risk.
 
-To build **tflite-micro** library please find the corresponding section in documentation specified for a [custom ARC platform](https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro/tree/main/tensorflow/lite/micro/tools/make/targets/arc#Custom-ARC-EMHSVPX-Platform).  You need to copy the generated library to the *third_party* directory of this example and rename it to *libtensorflow-microlite.a* (see the same documentation on where the generated library can be found). 
-
+To build **tflite-micro** library please find the corresponding section in documentation specified for a [custom ARC platform](https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro/tree/main/tensorflow/lite/micro/tools/make/targets/arc#Custom-ARC-EMHSVPX-Platform).  You need to copy the generated library to the *third_party* directory of this example and rename it to *libtensorflow-microlite.a* (see the same documentation on where the generated library can be found).
 
-## Building and running example
+For the following example application build you should set ``TENSORFLOW_DIR``
+environment variable to point to the cloned tflite-micro repository:
 
-Before building the application you should set ``TENSORFLOW_DIR`` environment variable to point to your Tensorflow top folder:
+    # For Windows
+    set TENSORFLOW_DIR=<your-path-to-tflite-micro>
 
-```bash
-# For Windows
-set TENSORFLOW_DIR=\{your-path-to-tflite-micro\}
+    # For Linux
+    export TENSORFLOW_DIR=<your-path-to-tflite-micro>
 
-# For Linux
-export TENSORFLOW_DIR=\{your-path-to-tflite-micro\}
-```
+## Building and Running Example
 
-After that you need to configure and build the library project for the desired VPX 
-configuration. 
-Please read the corresponding section on [building the package](/README.md#building-the-package). 
-
- **Known Issue:** To successfully build this example you need to invoke build process from the */examples/tutorial_emnist_tflm* folder.
+After you've passed ["Generate Tensorflow Lite Micro Library"](#generate-tensorflow-lite-micro-library) step
+you need to configure and build the library project for the desired VPX
+configuration. Please read the corresponding section on [building the package](/README.md#building-the-package). **Also make sure you didn't forget to set ``TENSORFLOW_DIR`` environment variable.**
 
 Build artifacts of the application are stored in the `/obj/<project>/examples/tutorial_emnist_tflm` directory where `<project>` is defined according to your target platform.  
 
-After you've built and configured the whole library project, you can proceed with the following steps. 
-You need to replace `<options>` placeholder in commands below with the same options list you used for the library configuration and build. 
+After you've built and configured the whole library project, you can proceed with the following steps.
+You need to replace `<options>` placeholder in commands below with the same [build configuration options](README.md#build-configuration-options) list you used for the library configuration and build.
 
 1. Open command line in the root of the embARC MLI repo and change working directory to './examples/tutorial_emnist_tflm/'
 
@@ -66,51 +59,36 @@ You need to replace `<options>` placeholder in commands below with the same opti
 
        gmake <options> clean
 
-3. Build the example. This is an optional step as you may go to the next step which automatically invokes the build process. 
+3. Build the example. This is an optional step as you may go to the next step which automatically invokes the build process.
 
        gmake <options> build
 
 4. Run the example
 
        gmake <options> run
 
-##  ARC VPX Build Process Example
+## ARC VPX Build Process Example
 
-Assuming your environment satisfies all build requirements for ARC VPX platform, you can use the following script to build and run application using the nSIM simulator.
+Assuming you've already built and copied *libtensorflow-microlite.a* and your environment satisfies all build requirements for ARC VPX platform, you can use the following script to build and run the application using the nSIM simulator.
 The first step is to open a command line and change working directory to the root of the embARC MLI repo.
 
 1. Clean all previous artifacts for all platforms
-    ```bash
-    gmake cleanall 
-    ```
-
-2. Generate recommended  TCF file for VPX
-    ```bash
-    tcfgen -o ./hw/vpx5_integer_full.tcf -tcf=vpx5_integer_full -iccm_size=0x80000 -dccm_size=0x40000
-    ```
-
-3. Change working directory and build project using generated TCF and appropriate built-in runtime library for it. Use multithreaded build process (4 threads):
-    ```bash
-    cd ./examples/tutorial_emnist_tflm
-    gmake TCF_FILE=../../hw/vpx5_integer_full.tcf BUILDLIB_DIR=vpx5_integer_full JOBS=4 build
-    ```
-
-4. Build the example:
-    ```bash
-    gmake TCF_FILE=../../hw/vpx5_integer_full.tcf BUILDLIB_DIR=vpx5_integer_full build
-    ```
-
-5. Run the example w/o input arguments for all supported data types:
-    ```bash
-    gmake TCF_FILE=../../hw/vpx5_integer_full.tcf BUILDLIB_DIR=vpx5_integer_full run 
-    ```
-<!--
-Now you can build the example using MetaWare Development Tools:
-```bash
-gmake app TCF_FILE=<path_to_vpx_tcf_file>
-```
-And run the example with DesignWare ARC nSIM simulator:
-```bash
-gmake run TCF_FILE=<path_to_vpx_tcf_file>
-```
--->
+
+       gmake cleanall
+
+1. Generate recommended  TCF file for VPX
+
+       tcfgen -o ./hw/vpx5_integer_full.tcf -tcf=vpx5_integer_full -iccm_size=0x80000 -dccm_size=0x40000
+
+1. Build project using generated TCF and appropriate built-in runtime library for it. Use multithreaded build process (4 threads):
+
+       gmake TCF_FILE=../../hw/vpx5_integer_full.tcf BUILDLIB_DIR=vpx5_integer_full JOBS=4 build
+
+1. Change working directory and build the example:
+
+       cd ./examples/tutorial_emnist_tflm
+       gmake TCF_FILE=../../hw/vpx5_integer_full.tcf BUILDLIB_DIR=vpx5_integer_full build
+
+1. Run the example:
+
+       gmake TCF_FILE=../../hw/vpx5_integer_full.tcf BUILDLIB_DIR=vpx5_integer_full run
diff --git a/examples/tutorial_emnist_tflm/conversion_tutorial/README.md b/examples/tutorial_emnist_tflm/conversion_tutorial/README.md
@@ -1,45 +1,39 @@
-Model Conversion Tutorial for EMNIST Example
-========================================================================
-This tutorial shows how to convert EMNIST Tensorflow model into Tensorflow Lite Micro format to furhter usage in application together with embARC MLI.
+# Model Conversion Tutorial for EMNIST Example
+
+This tutorial shows how to convert EMNIST Tensorflow model into Tensorflow Lite Micro format for further usage in application together with embARC MLI.
 
 ## Requirements
 
-The following dependencies must be installed in your environment. 
+The following dependencies must be installed in your environment:
+
 * Python 3.7
 * Dependencies from the [requirements.txt](/examples/tutorial_emnist_tflm/conversion_tutorial/requirements.txt) file
-    * NumPy 1.19.2
-    * Matplotlib
-    * Jupyter Lab / Notebook
-    * TensorFlow 2.5.1
-    * Keras
-    * emnist 
+  * NumPy 1.19.2
+  * Matplotlib
+  * Jupyter Lab / Notebook
+  * TensorFlow 2.5.1
+  * Keras
+  * emnist
 
-If you are looking for instruction to set-up a compatible environment, then consider the comprehended guide on [TensorFlow](https://www.tensorflow.org/install) installation. We recommend to follow ["Install TensorFlow with pip"](https://www.tensorflow.org/install/pip) and not ignore recommendation on usage of the virtual environment.
+If you are looking for instruction to set-up a compatible environment, then consider the comprehensive guide on [TensorFlow](https://www.tensorflow.org/install) installation. We recommend to follow ["Install TensorFlow with pip"](https://www.tensorflow.org/install/pip) and not ignore recommendation on usage of the virtual environment.
 
 Make sure you have installed required version of dependencies listed in the *requirements.txt* file. In case you followed our recommendation on install TensorFlow with pip, for [step 3](https://www.tensorflow.org/install/pip#3.-install-the-tensorflow-pip-package) you can use the following commands instead the proposed ones. First change working directory in terminal to the [conversion_tutorial](/examples/tutorial_emnist_tflm/conversion_tutorial).
 
-```bash
-pip3 install -r ./requirements.txt
-python3 -c "import emnist; emnist.ensure_cached_data();"
-```
+    pip3 install -r ./requirements.txt
+    python3 -c "import emnist; emnist.ensure_cached_data();"
 
 ## Running Conversion Tutorial
 
-To convert the model, run the Jupyter Notebook:
+To convert the model, run the Jupyter Notebook (change working directory in terminal to the [conversion_tutorial](/examples/tutorial_emnist_tflm/conversion_tutorial) if you haven't done it):
 
-```bash
-jupyter notebook conversion_tutorial/model_conversion.ipynb
-```
+    jupyter notebook model_conversion.ipynb
 
-After completing the tutorial you should have model and test samples generated. 
+After completing the tutorial, you should have model and test samples generated.
 
 Please make sure you don't forget to use [Model Adaptation Tool](https://github.com/foss-for-synopsys-dwc-arc-processors/tflite-micro/blob/main/tensorflow/lite/micro/tools/make/targets/arc/adaptation_tool.py) to convert `emnist_model_int8.tflite` you got before saving it as C array.
 
 ## Using Converted Model in Application
 
-See [EMNIST example part](/examples/tutorial_emnist_tflm) on how a converted model might be used in application together with TFLM and embARC MLI. It already contains converted model, hence this ste is optional.
-
-To use generated models in the example you need to copy */examples/tutorial_emnist_tflm/conversion_tutorial/generated/model.h* and */examples/tutorial_emnist_tflm/conversion_tutorial/generated/test_samples.cc* to */examples/tutorial_emnist_tflm/src* folder. Make sure that name of buffers and constants in copied files are aligned with the former ones and change them if not. Afterward you can clean, beald and run example application according to instructions. 
-
-
+See [EMNIST example part](/examples/tutorial_emnist_tflm) on how a converted model might be used in application together with TFLM and embARC MLI. The example already contains converted model, hence this step is optional.
 
+To use generated models in the example you need to copy */examples/tutorial_emnist_tflm/conversion_tutorial/generated/model.h* and */examples/tutorial_emnist_tflm/conversion_tutorial/generated/test_samples.cc* to */examples/tutorial_emnist_tflm/src* folder. Make sure that names of buffers and constants in copied files are aligned with the former ones and change them if not. Afterward you can clean, build and run example application according to instructions.
diff --git a/examples/tutorial_emnist_tflm/conversion_tutorial/model_conversion.ipynb b/examples/tutorial_emnist_tflm/conversion_tutorial/model_conversion.ipynb

Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,7 @@ if (ARC)`
`28`	`28`	`-Hxcheck`
`29`	`29`	`-Hcrt_initbss`
`30`	`30`	`)`
	`31`	`+ get_filename_component(TCF_FILE_NAME ${ARC_CFG_TCF_PATH} NAME_WE)`
`31`	`32`	`else()`
`32`	`33`	`set(EXAMPLE_FLAGS)`
`33`	`34`	`endif()`
`@@ -41,7 +42,7 @@ add_executable(${TARGET}`
`41`	`42`	`./src/test_samples.cc`
`42`	`43`	`)`
`43`	`44`
`44`		`-target_link_libraries(${TARGET} PUBLIC $ENV{TENSORFLOW_DIR}/tensorflow/lite/micro/tools/make/downloads/arc_mli_$ENV{TCF_FILE_NAME}_mli20/bin/arc/libmli.a)`
	`45`	`+target_link_libraries(${TARGET} PUBLIC $ENV{TENSORFLOW_DIR}/tensorflow/lite/micro/tools/make/downloads/arc_mli_${TCF_FILE_NAME}_mli20/bin/arc/libmli.a)`
`45`	`46`	`target_link_libraries(${TARGET} PRIVATE tensorflow-microlite)`
`46`	`47`
`47`	`48`	`target_include_directories(${TARGET} PRIVATE`