Skip to content

Commit

Permalink
Revise Tutorial.md (Samsung#1204)
Browse files Browse the repository at this point in the history 
* DRAFT: Revise Tutorial.md

This revises Tutorial.md.

ONE-vscode-DCO-1.0-Signed-off-by: Hyun Sik Yoon <[email protected]>

* fix. add ToC. modify image.

* Articles

* fix default toolchain section
  • Loading branch information
@hyunsik-yoon
hyunsik-yoon authored Aug 10, 2022
1 parent b39d21a commit e6b0f23
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 39 deletions.
76 changes: 37 additions & 39 deletions docs/Tutorial.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@
# Tutorial

<!-- Candidate order
## Table of Contents
- Installing ONE-vscode and backend extensions
- Screen layout
- Opening a folder
- Installing a toolchain
- Compiling a model
- Profiling a model
-->
- [How to install ONE-vscode](#how-to-install-one-vscode)
- [Screen layout](#screen-layout)
- [Workspace](#workspace)
- [Install a toolchain](#install-a-toolchain)
- [Set default toolchain](#set-default-toolchain)
- [Prepare a model and a config file](#prepare-a-model-and-a-config-file)
- [Compile a model](#compile-a-model)
- [Profile a model](#profile-a-model)
- [Contact](#contact)

## How to install ONE-vscode

Expand All @@ -24,7 +23,7 @@ ONE-vscode supports one of the following development environments:
1. A single Ubuntu machine (to run vscode and ONE toolchains)
2. A Windows machine (to run vscode) and a Ubuntu machine (to run ONE toolchains), connected with SSH extension

A Ubuntu machine is mandatory because [ONE](https://github.com/Samsung/ONE) is officially released on Ubuntu. If your development environment is vscode on Windows, you need additional Ubuntu machine to run ONE toolchain. In additon, you need to [install SSH extension in vscode](https://code.visualstudio.com/docs/remote/ssh-tutorial).
A Ubuntu machine is mandatory because [ONE](https://github.com/Samsung/ONE) is officially released on Ubuntu. If your development environment is vscode on Windows, you need additional Ubuntu machine to run ONE toolchain. In addition, you need to [install SSH extension in vscode](https://code.visualstudio.com/docs/remote/ssh-tutorial).

### Install ONE-vscode extension

Expand All @@ -51,64 +50,63 @@ ONE-vscode has 6 screen components.
1. `ONE icon`
- Clicking this will load ONE-vscode extension into vscode
2. `ONE Explorer view`
- This shows tree view containing models and related files.
- This shows a tree view containing models and related files.
- Model files (e.g., *.tflite, *.pb, *.onnx, etc) are shown in the directory structure.
- Under each model file, ONE *.cfg that accepts the model file as input will be shown.
- Under each *.cfg file, any files generated by running `onecc` with the *.cfg will be shown. For example, *.circle file and files after backend codegen.
- Under each *.cfg file, any files generated by running `onecc` with the *.cfg will be shown. For example, `*.circle` file and files after backend codegen.
3. `Toolchain view`
- This shows installed toolchain.
- This shows a tree view of installed toolchains.
- You can also install a new toolchain or uninstall an existing toolchain.
4. `Target Device view`
- This shows tree view of devices or simulators that can run for inference.
- This shows a tree view of devices or simulators that can run for inference.
5. `ONE cfg editor`
- This provides easier way to edit ONE cfg file.
- This provides easier way to edit a ONE cfg file.
6. `ONE-vscode Log`
- This shows logs. You can check detailed reason of error or warning.

<!-- Rearrange content below -->

## Workspace

You need to open a folder (`File > Open Folder` menu) to start with ONE-vscode. After opening a folder, a [_workspace_ is constructed by vscode.](https://code.visualstudio.com/docs/editor/workspaces).

The folder for ONE-vscode needs to have the following files:
- Your model files
- Tensorflow model file(*.pb, saved model or Keras model)
- Tensorflow Lite model (*.tflite)
- Onnx model (*.onnx)
- TensorFlow model file(*.pb, saved model or Keras model)
- TensorFlow Lite model (*.tflite)
- ONNX model (*.onnx)
- ONE *.cfg files (You can create this file later)

## Install the toolchain
## Install a toolchain

You need the ONE toolchain. Let's install the ONE toolchain. (You should install the in-house backend to follow this.)
A toolchain contains [ONE command tools](https://github.com/Samsung/ONE/tree/master/compiler/one-cmds) and other backend-specific tools. Developers or vendors of backend can distribute backend-specific toolchain and put installation feature inside their backend extension.

<img src="https://user-images.githubusercontent.com/7223627/174947559-71ab213c-68c4-4700-bcec-e55f6a2203bf.gif" width=600 />
To install a backend-specific toolchain, you first need to install the backend extension. Then, click `+` icon on the Toolchain view. You can also easily remove installed toolchain by clicking `X` icon in the Toolchain view.

## Set default toolchain

To compile model using ONE toolchain, you must specify the default toolchain. Default toolchain refers to which toolchain you will use to run ONE related tools. To specify a default toolchain, if you mouse up the toolchain item you want to use in Toolchain view, :heavy_check_mark: icon appears. Click this icon to specify it as default toolchain. If toolchain is specified as default toolchain, the icon changes.
You can install multiple instances of toolchains. For example, some backend supports multiple versions of toolchain to be installed. Or you might installed more than one backend extensions installed and installed one or more toolchain per backend extension.

To execute a toolchain with a config file in the ONE explorer to, e.g., compile a model, you need to specify the default toolchain. Default toolchain refers to which toolchain you will use to run ONE related tools. To specify a default toolchain, if you mouse up the toolchain item you want to use in the Toolchain view, :heavy_check_mark: icon appears. Click this icon to specify it as default toolchain.

| Toolchain | Default Toolchain |
|-----------|-------------------|
| <img src="https://user-images.githubusercontent.com/7223627/177962615-71e64f52-e684-432d-a053-07896a20a479.png" width=300 /> | <img src="https://user-images.githubusercontent.com/7223627/177963453-d22998a0-be21-4531-a70b-9057a204e7eb.png" width=300 /> |
## Prepare a model and a config file

## Prepare a NN model and a config file
Now, let's try to compile a model (TensorFlow Lite, TensorFlow, or ONNX).

You need a NN model and a config file to run compiling. Now you can get one from [res/modelDir/truediv](../res/modelDir/truediv/). Add it to your workspace. Now you can see a model and a config.
Just like you might write _Makefile_ for C program, you need ONE `*.cfg` file to compile a model. ONE cfg file is a file that describes steps and options of compilation.
One example you can get is in [res/modelDir/truediv](../res/modelDir/truediv/). You may want to copy and modify the cfg file to your workspace. After modifying the cfg file to have your model file as input model, you will see the cfg file below your model file in ONE explorer.

<img src="https://user-images.githubusercontent.com/10216715/174798969-eee44fea-bd71-4e6a-8e2c-9e1de37ad74a.gif" width=600 />
You can also edit the cfg file with GUI cfg editor.

## Compile models
<img src="one-explorer-cfg-editor.gif"/>

Last, you can compile the model by pushing Run button.
## Compile a model

Depends on backend, you may be able to infer or profile a model by 'running config'.
Now, you can compile the model by clicking `▶` icon on a cfg file. Below a cfg file in ONE explorer, you can find generated files by compilation, e.g., various `*.circle` file and the final target file compiled for your backend.

<img src="https://user-images.githubusercontent.com/10216715/174796457-4dae4a77-04e1-4e5c-9453-77ebfb65182a.gif" width=600 />
## Profile a model

## Trouble-shooting
You can add `Profile` step into a cfg file, which will generate a json file in Chrome Tracing format, which has timeline data.
You can find the json file below the cfg file in ONE explorer. ONE-vscode provides embedded GUI viewer to see the json file.

How to watch log?
- View -> output -> ONE-vscode
## Contact

<img src="https://user-images.githubusercontent.com/10216715/174795531-9868f1e0-25ab-4ae3-bf65-fe8385a7ba76.gif" width=600 />
When you encounter any bug or problem, feel free to write a post in [issue page of ONE-vscode](https://github.com/Samsung/ONE-vscode/issues). Any idea or suggestion that could enhance ONE-vscode will also be welcome!
Binary file added docs/one-explorer-cfg-editor.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit e6b0f23

Please sign in to comment.