Operator Description¶

Main Format¶

LightNet can generate operator defination code from Operator Descriptions automatically, which are JSONs conforming to the following format:

{
    "ops": [
        ...
        {
            "optype": STRING,
            "author": STRING,
            "arch": STRING,
            "autogen": OPTIONAL BOOL
            "extra_privs": OPTIONAL [
                {
                    "type": STRING,
                    "name": STRING,
                },
                ...
            ],
            "tensors_in": [
                {
                    "arg_name": STRING,
                    "mtype": STRING, 
                    "dtype": OPTIONAL STRING, 
                    "ndim": OPTIONAL NUMBER or STRING,
                    "len": OPTIONAL NUMBER or STRING,
                    "sametype": OPTIONAL STRING,
                    "sameshape": OPTIONAL STRING,
                    "static": OPTIONAL BOOL,
                    "check": OPTIONAL STRING,
                    "checks": OPTIONAL [
                        "check": OPTIONAL STRING,
                        ...
                    ],
                    "custom": OPTIONAL STRING,
                    ...
                },
                ...
            ],
            "tensors_out": [
                {
                    "arg_name": STRING,
                    "mtype": STRING,
                    "ndim": OPTIONAL NUMBER or STRING, 
                    "dims": OPTIONAL STRING,
                    "len": OPTIONAL NUMBER or STRING,
                    "dtype": OPTIONAL STRING,
                    "owner": OPTIONAL STRING,
                    "static": OPTIONAL BOOL,
                    "custom": OPTIONAL STRING,
                    "cleanup": OPTIONAL STRING,
                },
                ...
            ],
            "params": [
                {
                    "arg_name": STRING,
                    "ptype": STRING,
                    "realtype": OPTIONAL STRING,
                    "from_func": OPTIONAL STRING,
                    "eq": OPTIONAL NUMBER or STRING,
                    "gt": OPTIONAL NUMBER or STRING,
                    "ge": OPTIONAL NUMBER or STRING,
                    "lt": OPTIONAL NUMBER or STRING,
                    "le": OPTIONAL NUMBER or STRING,
                    "ne": OPTIONAL NUMBER or STRING,
                    "check": OPTIONAL STRING,
                    "checks": OPTIONAL [
                        "check": OPTIONAL STRING,
                        ...
                    ],
                    "custom": OPTIONAL STRING,
                },
                ...
            ],
            "custom": OPTIONAL STRING,
            "static_run": OPTIONAL STRING,
            "run": OPTIONAL STRING,
            "post_run": OPTIONAL STRING,
            "calc_offset": OPTIONAL STRING,
            ...
        },
        ...
    ]
}

An operator description file can contain several operator descriptions that are members of the ops array.

An operator description must contain those fields:

optype: A string that is unique across all operator definations, representing the operator's type.
author: A string of the author's name of this operator description.
arch: A string of the name of the architecture where the operator can run.
tensors_in: An array of the definations of the input tensors.
tensors_out: An array of the definations of the output tensors.
params: An array of the definations of the parameters.

As the operator section has said, an operator has a life cycle, or a state machine that transfered by four functions: pre_run(), static_run(), run() and post_run(). The majority of the pre_run() code are generated by the above fields.

Besides, an operator description may optionally contains those fields:

autogen: A bool that indicates whether this operator description should be used for the generation of the operator defination. Assume true if omitted.
extra_privs: An array of the declarations of extra members of the private structure struct priv_s which has an instance allocated in pre_run(), whose pointer is stored in the priv field of the operator's ln_op_arg. The elements of extra_privs have two fields: type and name. The former is the C data type of the extra member. The latter is the C identifier of the extra member.
custom: A string of custom code the author may append to the end of pre_run().
static_run: A string of the code of static_run(), which will be NULL if this field is omitted.
run: A string of the code of run(), which will be NULL if this field is omitted, and the operator won't execute any runtime calculation, which may be the case of operators like create, or some "abstract" operators like those of none architecture that only exist for the convinence of optimization.
post_run: A string of the code of post_run(), which will be NULL if this field is omitted.
calc_offset: A string of the code of calc_offset(), which will be NULL if this field is omitted.

Input Tensor Defination¶

The elements of tensors_in are the definations of the input tensors, which can be used to generate the code for the sanity checking of input tensors. They must at least contains those fields:

arg_name: A string of the argument name of the tensor in the operator.
mtype: A string of an enum of the memory type of the tensor's data. See memory model for possible memory types.

Optionally, the elements of tensors_in may also contain those fields:

ndim: The number of dimensions of this tensor. This could be a literal constant number, or a C code snnippet that can be evaluated to the number of dimensions.
len: The number of elements of this tensor. This could be a literal constant number, or a C code snnippet that can be evaluated to the number of dimensions.
dtype: A string of an enum of the supported tensor data type. See tensor for all possible data types.
sametype: If this tensor has the same dtype of another tensor, it can set this field as that tensor's arg_name.
sameshape: If this tensor has the same shape of another tensor, it can set this field as that tensor's arg_name.
static: A bool that indicates whether this tensor's data is static, that is, it would not be freed and reused by another tensor. Assume false if omitted.
check: A string of the arguments of the macro ln_opck_satisfy() or ln_opck_satisfy_msg(), depending on the number of the arguments, used as an additional check for this tensor.
checks: An array of additional checks for this tensor, whose elements are of the same usage of check.
custom: A string of custom code the author may append to the code about this tensor.

Output Tensor Defination¶

The elements of tensors_out are the definations of the output tensors, which can be used to generate the code for the sanity checking, shape inference and registration of output tensors. They must contain those fields:

arg_name: A string of the argument name of the tensor in the operator.
mtype: A string of an enum of the memory type of the tensor's data. See memory model for possible memory types.

Optionally, the elements of tensors_out may also contain those fields:

ndim: The number of dimensions of this tensor. This could be a literal constant number, or a C code snnippet that can be evaluated to the number of dimensions.
dims: An array of numbers of the dimensions of this tensor, whose length should be equal with ndim.
len: The number of elements of this tensor. This could be a literal constant number, or a C code snnippet that can be evaluated to the number of dimensions.
dtype: A string of an enum of the supported tensor data type. See tensor for all possible data types.
owner: If this tensor's data memory is shared with another input tensor, it could set this field to that tensor's arg_name. If this tensor's data address (ln_tensor.tensor->data) starts in the middle of another input tensor, the operator should also supply an calc_offset to calculate the start address from that input tensor.
static: A bool that indicates whether this tensor's data is static, that is, it would not be freed and reused by another tensor. Assume false if omitted.

Operator Description¶

Main Format¶

Input Tensor Defination¶

Output Tensor Defination¶

Parameter Defination¶