1 /* 2 * Copyright (c) 2018-2021 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, CLVK. 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 * 66 * Example execution commands: 67 * 68 * Execute a single inference given an image and a file containing the correspondence between label ids and human readable labels: 69 * ./graph_vgg16 --data=data/ --target=cl --layout=nhwc --image=kart.jpeg --labels=imagenet1000_clsid_to_human.txt 70 * 71 * Perform a graph validation on a list of images: 72 * ./graph_vgg16 --data=data/ --target=neon --threads=4 --layout=nchw --validation-file=val.txt --validation-path=ilsvrc_test_images/ 73 * 74 * File formats: 75 * 76 * Validation file should be a plain file containing the names of the images followed by the correct label id. 77 * For example: 78 * 79 * image0.jpeg 882 80 * image1.jpeg 34 81 * image2.jpeg 354 82 * 83 * Labels file should be a plain file where each line is the respective human readable label (counting starts from 0). 84 * For example: 85 * 86 * 0: label0_name label0_name 87 * 1: label1_name or label1_name 88 * 2: label2_name label2_name 89 */ 90 /* ![Common graph examples parameters] */ 91 92 /** Structure holding all the common graph parameters */ 93 struct CommonGraphParams 94 { 95 bool help{ false }; 96 int threads{ 0 }; 97 int batches{ 1 }; 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 std::string mlgo_file{}; 112 unsigned int validation_range_start{ 0 }; 113 unsigned int validation_range_end{ std::numeric_limits<unsigned int>::max() }; 114 }; 115 116 /** Formatted output of the CommonGraphParams type 117 * 118 * @param[out] os Output stream. 119 * @param[in] common_params Common parameters to output 120 * 121 * @return Modified output stream. 122 */ 123 ::std::ostream &operator<<(::std::ostream &os, const CommonGraphParams &common_params); 124 125 /** Common command line options used to configure the graph examples 126 * 127 * The options in this object get populated when "parse()" is called on the parser used to construct it. 128 * The expected workflow is: 129 * 130 * CommandLineParser parser; 131 * CommonOptions options( parser ); 132 * parser.parse(argc, argv); 133 */ 134 class CommonGraphOptions 135 { 136 public: 137 /** Constructor 138 * 139 * @param[in,out] parser A parser on which "parse()" hasn't been called yet. 140 */ 141 CommonGraphOptions(CommandLineParser &parser); 142 /** Prevent instances of this class from being copied (As this class contains pointers) */ 143 CommonGraphOptions(const CommonGraphOptions &) = delete; 144 /** Prevent instances of this class from being copied (As this class contains pointers) */ 145 CommonGraphOptions &operator=(const CommonGraphOptions &) = delete; 146 /** Allow instances of this class to be moved */ 147 CommonGraphOptions(CommonGraphOptions &&) = default; 148 /** Allow instances of this class to be moved */ 149 CommonGraphOptions &operator=(CommonGraphOptions &&) = default; 150 /** Default destructor */ 151 ~CommonGraphOptions() = default; 152 153 ToggleOption *help; /**< Show help option */ 154 SimpleOption<int> *threads; /**< Number of threads option */ 155 SimpleOption<int> *batches; /**< Number of batches */ 156 EnumOption<arm_compute::graph::Target> *target; /**< Graph execution target */ 157 EnumOption<arm_compute::DataType> *data_type; /**< Graph data type */ 158 EnumOption<arm_compute::DataLayout> *data_layout; /**< Graph data layout */ 159 ToggleOption *enable_tuner; /**< Enable tuner */ 160 ToggleOption *enable_cl_cache; /**< Enable opencl kernels cache */ 161 SimpleOption<arm_compute::CLTunerMode> *tuner_mode; /**< Tuner mode */ 162 ToggleOption *fast_math_hint; /**< Fast math hint */ 163 SimpleOption<std::string> *data_path; /**< Trainable parameters path */ 164 SimpleOption<std::string> *image; /**< Image */ 165 SimpleOption<std::string> *labels; /**< Labels */ 166 SimpleOption<std::string> *validation_file; /**< Validation file */ 167 SimpleOption<std::string> *validation_path; /**< Validation data path */ 168 SimpleOption<std::string> *validation_range; /**< Validation range */ 169 SimpleOption<std::string> *tuner_file; /**< File to load/store the tuner's values from */ 170 SimpleOption<std::string> *mlgo_file; /**< File to load the MLGO heuristics from */ 171 }; 172 173 /** Consumes the common graph options and creates a structure containing any information 174 * 175 * @param[in] options Options to consume 176 * 177 * @return Structure containing the common graph parameters 178 */ 179 CommonGraphParams consume_common_graph_parameters(CommonGraphOptions &options); 180 } // namespace utils 181 } // namespace arm_compute 182 #endif /* ARM_COMPUTE_EXAMPLES_UTILS_COMMON_GRAPH_OPTIONS */ 183