1 /* 2 * Copyright (c) 2018-2020 Arm Limited. 3 * 4 * SPDX-License-Identifier: MIT 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in all 14 * copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 22 * SOFTWARE. 23 */ 24 #ifndef ARM_COMPUTE_EXAMPLES_UTILS_COMMON_GRAPH_OPTIONS 25 #define ARM_COMPUTE_EXAMPLES_UTILS_COMMON_GRAPH_OPTIONS 26 27 #include "utils/command_line/CommandLineOptions.h" 28 #include "utils/command_line/CommandLineParser.h" 29 30 #include "arm_compute/graph/TypeLoader.h" 31 #include "arm_compute/graph/TypePrinter.h" 32 #include "arm_compute/runtime/CL/CLTunerTypes.h" 33 34 namespace arm_compute 35 { 36 namespace utils 37 { 38 /* ![Common graph examples parameters] */ 39 /* Common graph parameters 40 * 41 * --help : Print the example's help message. 42 * --threads : The number of threads to be used by the example during execution. 43 * --target : Execution target to be used by the examples. Supported target options: NEON, CL, GC. 44 * --type : Data type to be used by the examples. Supported data type options: QASYMM8, F16, F32. 45 * --layout : Data layout to be used by the examples. Supported data layout options : NCHW, NHWC. 46 * --enable-tuner : Toggle option to enable the OpenCL dynamic tuner. 47 * --enable-cl-cache : Toggle option to load the prebuilt opencl kernels from a cache file. 48 * --fast-math : Toggle option to enable the fast math option. 49 * --data : Path that contains the trainable parameter files of graph layers. 50 * --image : Image to load and operate on. Image types supported: PPM, JPEG, NPY. 51 * --labels : File that contains the labels that classify upon. 52 * --validation-file : File that contains a list of image names with their corresponding label id (e.g. image0.jpg 5). 53 * This is used to run the graph over a number of images and report top-1 and top-5 metrics. 54 * --validation-path : The path where the validation images specified in the validation file reside. 55 * --validation-range : The range of the images to validate from the validation file (e.g 0,9). 56 * If not specified all the images will be validated. 57 * --tuner-file : The file to store the OpenCL dynamic tuner tuned parameters. 58 * --tuner-mode : Select tuner mode. Supported modes: Exhaustive,Normal,Rapid 59 * * Exhaustive: slowest but produces the most performant LWS configuration. 60 * * Normal: slow but produces the LWS configurations on par with Exhaustive most of the time. 61 * * Rapid: fast but produces less performant LWS configurations 62 * 63 * Note that data, image and labels options should be provided to perform an inference run on an image. 64 * Note that validation-file and validation-path should be provided to perform a graph accuracy estimation. 65 * Note GLES target is not supported for most of the networks. 66 * 67 * Example execution commands: 68 * 69 * Execute a single inference given an image and a file containing the correspondence between label ids and human readable labels: 70 * ./graph_vgg16 --data=data/ --target=cl --layout=nhwc --image=kart.jpeg --labels=imagenet1000_clsid_to_human.txt 71 * 72 * Perform a graph validation on a list of images: 73 * ./graph_vgg16 --data=data/ --target=neon --threads=4 --layout=nchw --validation-file=val.txt --validation-path=ilsvrc_test_images/ 74 * 75 * File formats: 76 * 77 * Validation file should be a plain file containing the names of the images followed by the correct label id. 78 * For example: 79 * 80 * image0.jpeg 882 81 * image1.jpeg 34 82 * image2.jpeg 354 83 * 84 * Labels file should be a plain file where each line is the respective human readable label (counting starts from 0). 85 * For example: 86 * 87 * 0: label0_name label0_name 88 * 1: label1_name or label1_name 89 * 2: label2_name label2_name 90 */ 91 /* ![Common graph examples parameters] */ 92 93 /** Structure holding all the common graph parameters */ 94 struct CommonGraphParams 95 { 96 bool help{ false }; 97 int threads{ 0 }; 98 arm_compute::graph::Target target{ arm_compute::graph::Target::NEON }; 99 arm_compute::DataType data_type{ DataType::F32 }; 100 arm_compute::DataLayout data_layout{ DataLayout::NHWC }; 101 bool enable_tuner{ false }; 102 bool enable_cl_cache{ false }; 103 arm_compute::CLTunerMode tuner_mode{ CLTunerMode::NORMAL }; 104 arm_compute::graph::FastMathHint fast_math_hint{ arm_compute::graph::FastMathHint::Disabled }; 105 std::string data_path{}; 106 std::string image{}; 107 std::string labels{}; 108 std::string validation_file{}; 109 std::string validation_path{}; 110 std::string tuner_file{}; 111 unsigned int validation_range_start{ 0 }; 112 unsigned int validation_range_end{ std::numeric_limits<unsigned int>::max() }; 113 }; 114 115 /** Formatted output of the CommonGraphParams type 116 * 117 * @param[out] os Output stream. 118 * @param[in] common_params Common parameters to output 119 * 120 * @return Modified output stream. 121 */ 122 ::std::ostream &operator<<(::std::ostream &os, const CommonGraphParams &common_params); 123 124 /** Common command line options used to configure the graph examples 125 * 126 * The options in this object get populated when "parse()" is called on the parser used to construct it. 127 * The expected workflow is: 128 * 129 * CommandLineParser parser; 130 * CommonOptions options( parser ); 131 * parser.parse(argc, argv); 132 */ 133 class CommonGraphOptions 134 { 135 public: 136 /** Constructor 137 * 138 * @param[in,out] parser A parser on which "parse()" hasn't been called yet. 139 */ 140 CommonGraphOptions(CommandLineParser &parser); 141 /** Prevent instances of this class from being copied (As this class contains pointers) */ 142 CommonGraphOptions(const CommonGraphOptions &) = delete; 143 /** Prevent instances of this class from being copied (As this class contains pointers) */ 144 CommonGraphOptions &operator=(const CommonGraphOptions &) = delete; 145 /** Allow instances of this class to be moved */ 146 CommonGraphOptions(CommonGraphOptions &&) = default; 147 /** Allow instances of this class to be moved */ 148 CommonGraphOptions &operator=(CommonGraphOptions &&) = default; 149 /** Default destructor */ 150 ~CommonGraphOptions() = default; 151 152 ToggleOption *help; /**< Show help option */ 153 SimpleOption<int> *threads; /**< Number of threads option */ 154 EnumOption<arm_compute::graph::Target> *target; /**< Graph execution target */ 155 EnumOption<arm_compute::DataType> *data_type; /**< Graph data type */ 156 EnumOption<arm_compute::DataLayout> *data_layout; /**< Graph data layout */ 157 ToggleOption *enable_tuner; /**< Enable tuner */ 158 ToggleOption *enable_cl_cache; /**< Enable opencl kernels cache */ 159 SimpleOption<arm_compute::CLTunerMode> *tuner_mode; /**< Tuner mode */ 160 ToggleOption *fast_math_hint; /**< Fast math hint */ 161 SimpleOption<std::string> *data_path; /**< Trainable parameters path */ 162 SimpleOption<std::string> *image; /**< Image */ 163 SimpleOption<std::string> *labels; /**< Labels */ 164 SimpleOption<std::string> *validation_file; /**< Validation file */ 165 SimpleOption<std::string> *validation_path; /**< Validation data path */ 166 SimpleOption<std::string> *validation_range; /**< Validation range */ 167 SimpleOption<std::string> *tuner_file; /**< File to load/store the tuner's values from */ 168 }; 169 170 /** Consumes the common graph options and creates a structure containing any information 171 * 172 * @param[in] options Options to consume 173 * 174 * @return Structure containing the common graph parameters 175 */ 176 CommonGraphParams consume_common_graph_parameters(CommonGraphOptions &options); 177 } // namespace utils 178 } // namespace arm_compute 179 #endif /* ARM_COMPUTE_EXAMPLES_UTILS_COMMON_GRAPH_OPTIONS */ 180