samskalicky commented on a change in pull request #17486: Update CustomOp doc with changes for GPU support URL: https://github.com/apache/incubator-mxnet/pull/17486#discussion_r378678068
########## File path: example/extensions/lib_custom_op/README.md ########## @@ -28,139 +28,340 @@ Custom operators (CustomOp) enable users to write new operators without compilin ### Have MXNet Ready -First you should install MXNet either from compiling from source code or download from nightly build. It doesn’t matter if the build comes with CUDA or MKLDNN. The custom operator doesn’t interact with the execution of other native MXNet operators. +Custom Operator support was merged (#15921, #17270) and is not available in versions of MXNet prior to v1.7.0. +To access the feature now, please install MXNet by compiling from source using master or using the previously mentioned commits, downloading one of the nightly builds, or from a release of MXNet 1.7.0+. +For running the following example, it doesn’t matter if it is a CUDA, MKLDNN or plain MXNet build; the custom operator doesn’t interact with the execution of other native MXNet operators. +Note that if you want to run GPU examples and write your custom operators running on GPU, you still need an MXNet CUDA build. -### Run An Example: +### Run An Example -You can start getting familiar with custom operators by running some examples provided in the **example/extensions/lib_custom_op** directory. Start with a common linear algebra operator like `gemm` (Generalized Matrix Multiplication). Go to `lib_custom_op` directory and follow these steps: +You can start getting familiar with custom operators by running some examples provided in the `example/extensions/lib_custom_op` directory. Start with a common linear algebra operator like `gemm` (Generalized Matrix Multiplication). Go to `lib_custom_op` directory and follow these steps: 1. Run `make gemm_lib`. The Makefile will generate a dynamic library **libgemm_lib.so** compiled from `gemm_lib.cc`. This is the library you are going to load that contains everything for the custom gemm operator. -2. Run `python test_gemm.py`. It’ll first load the above .so library, find the operators, register them in the MXNet backend, print "Found x operators", then invoke the operator like a regular MXNet operator and output the result. +2. Run `python test_gemm.py`. It’ll first load the library compiled from step 1, find the operators, register them in the MXNet backend, then invoke the operator like a regular MXNet operator and output the result. +Below is the output when running the python `test_gemm.py` command. Notice that it loads 2 operators: `my_gemm` and `state_gemm`. -### Basic Files For Gemm Library: +``` +[19:22:02] ../src/c_api/c_api.cc:286: Found 2 operators in library +[19:22:02] ../src/c_api/c_api.cc:350: Op[0] my_gemm +[19:22:02] ../src/c_api/c_api.cc:350: Op[1] state_gemm +[19:22:02] ../src/c_api/c_api.cc:785: Found 0 partitioners in library +--------start ndarray compute--------- +[[ 50.] + [122.]] +<NDArray 2x1 @cpu(0)> +... +``` + +Note that you can safely ignore the `Found 0 partitioners` info as it is not related to the custom operator. + +### Basic Files For A GeMM Library * **lib_custom_op/gemm_lib.cc**: This file has a source code implementation of all required components of a custom operator, as well as the registration of the custom operator. -* **lib_custom_op/Makefile**: Compile source code to a dynamic shared library, with a header file `include/mxnet/lib_api.h` from MXNet source code. Currently the custom operator is compatible with C++11 onwards. +* **lib_custom_op/Makefile**: This file compiles `gemm_lib.cc` to a dynamic shared library named `libgemm_lib.so`. It includes the header file `include/mxnet/lib_api.h` from MXNet source code. Currently the custom operator APIs require C++11 onwards. * **lib_custom_op/test_gemm.py**: This file calls `mx.library.load(‘libgemm_lib.so’)` to load the library containing the custom operator, invokes the operator using both NDArray and Symbol APIs, and prints outputs of the forward and backward passes. The outputs should be the same as the regular MXNet `gemm` operator. -## Writing Custom Operator Library: +* **include/mxnet/lib_api.h**: This file from MXNet source code is the single header file needed to include all necessary data types and function prototypes for writing a custom operator library. +You can either specify the include path in the `Makefile`, or copy the header file over to `example/extensions/lib_custom_op` folder. +Note that apart from this header, the custom operator library is independent of MXNet source. -For building a library containing your own custom operator, compose a C++ source file like `myop_lib.cc`, include `lib_api.h` header file, and write your custom operator implementation with these essential functions: +## Writing A Custom CPU Operator Library + +To build your own library containing custom CPU operator, compose a C++ source file like `myop_lib.cc`, include `lib_api.h` header file, and write your custom operator implementation with these required functions: - `initialize` - Library Initialization Function - `REGISTER_OP` - Operator Registration Marco Review comment: @rondogency I know you agree with me in appreciating @marcoabreu, but lets call this "Macro" here instead ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
