5. Class¶

5.1. Builder¶

std::ostream &operator<<(std::ostream &out, std::shared_ptr<builder::Builder> builder)¶: Feed the built IR to the specific output stream.

class builder::Builder : public std::enable_shared_from_this<Builder>¶

#include <hlir_builder_common.h>

This class helps build IR, which consist of Ops.

Public Functions

Builder()¶: Constructor of Builder.

void SetOpCallBack(std::function<bool(Op&)> cb)¶

Set a call back for Op which created by builder Op API. It will been called after the Op API return the created op.

Parameters: cb – call back function, or object.

std::function<bool(Op&)> GetOpCallBack()¶: Get the op call back setted before.

builder::Op CreateInput(const builder::Type &type, const char *func_name = ~~"main"~~)¶

Create an input Op for a Function. You can smiply consider a Function as a C++ function which consist of Ops.

Parameters

type – Type of the input
func_name – Name of the specific Function, default is main

Returns

The created input Op

std::vector<builder::Op> GetInputs(const char *func_name = ~~"main"~~)¶

get inputs Op for a Function.

Parameters: func_name – Name of the specific Function, default is main
Returns: inputs Op

void SetOutput(const std::vector<builder::Op> &outputs, const char *func_name = ~~"main"~~)¶

Set output Ops of a Function.

Parameters

outputs – A vector of output Ops
func_name – Name of the specific Function, default is main

std::shared_ptr<char> GetModuleStr(uint32_t flags = PrintingFlags::None)¶

Get the built IR string.

Parameters: flags – Print flag. Default: PrintingFlags::None.
Returns: Built IR string.

std::shared_ptr<hlir::Module> GetModule()¶

Get built IR as hlir::Module instance.

Returns: Built IR as hlir::Module instance

void *GetModulePtr()¶

Get built IR as a void pointer, caller needs to free it by using FreeModulePtr(void* module_ptr). It is a temporary interface, will be removed in the future.

Returns: Built IR as a void pointer

void FreeModulePtr(void *module_ptr)¶

Free the module pointer got from GetModulePtr(). It is a temporary interface, will be removed in the future.

Returns: Built IR as a void pointer

void AddFunc(const char *name)¶: Add a Function with a specific name to the Builder.

void SetShapeInference(bool enable_flag)¶: Turn on or off shape inference when building an Op.

bool GetShapeInference() const¶: Get the status of on or off for shape inference.

void SetFuncMC(const char *func_name, const std::vector<int64_t> &mc)¶

Add a MC index info to the Func.

Parameters

func_name – The specific name of the Function
mc – MC index info

std::vector<int64_t> GetFuncMC(const char *func_name) const¶

Get MC Info from the Func.

Parameters

func_name – The specific name of the Function
return – MC index info. If threr is no MC in op, return {}

bool HaveFunc(const char *func_name) const¶

Does the function name already exist.

Parameters: func_name – Name of the specific Function
Returns: Returns true if it exists, otherwise returns false

void SetFuncAttribute(const char *func_name, const char *name, const Attribute &value)¶

Set function attribute parameters.

Parameters

func_name – Name of the specific Function
name – attribute name
value – attribute object

void SetFuncAttribute(const char *func_name, const char *name, const std::vector<Attribute> &value)¶

Set function array attribute parameters.

Parameters

func_name – Name of the specific Function
name – attribute name
value – vector of attribute object

Attribute GetFuncAttribute(const char *func_name, const char *name) const¶

get function attribute parameters info.

Parameters

func_name – Name of the specific Function
name – attribute name

Returns

attribute object

void SetModuleAttribute(const char *name, const Attribute &value)¶

Set module attribute parameters.

Parameters

name – attribute name
value – attribute object

void SetModuleAttribute(const char *name, const std::vector<Attribute> &value)¶

Set module array attribute parameters.

Parameters

name – attribute name
value – vector of attribute object

Attribute GetModuleAttribute(const char *name) const¶

get module attribute parameters info.

Parameters: name – attribute name
Returns: attribute object

bool IsDynamicShape(const char *func_name = ~~"main"~~)¶

Judge if the function is of dynamic shape.

Parameters

func_name – the specified function name, default is main

Returns

Judge result

Returns

true – the inputs of the specified func is of dynamic shape
false – the inputs of the specified func is of static shape

void SetState(const char *name, const Attribute &value, const char *mode = ~~"copy"~~)¶

Set a cached attribute for the ops to be built after.

Parameters

name – the specified attribute name
value – the specified attribute value
mode – options: default is “copy” “copy” will copy the attr; “derive” will add postfix of “_$index” for string attr; “clean” will cancel the state.

void Print(std::ostream &out, uint32_t flags = PrintingFlags::None) const¶

Print the built IR to the specific output stream.

Parameters

out – Output stream
flags – Print flag

void Dump() const¶: Print the built IR to stdout.

std::shared_ptr<Impl> GetImpl() const¶

Get the inner implementation object pointer.

Returns: The inner implementation object pointer

Friends

friend std::shared_ptr<builder::Builder> SequentialMergeBuilder(std::vector<std::shared_ptr<builder::Builder>> builders)¶

Sequential merger TWO builders, ONLY support merger 1st builder with one output, and 2nd builder with one input.

Notice:

This API is used to merge two modules, the input parameter builders and the output builder only represent modules. The following APIs of the Builder class are not available here:

Builder::AddFunc, Builder::HaveFunc Builder::SetFuncAttribute, Builder::GetFuncAttribute Builder::SetFuncMC, Builder::GetFuncMC

If users need to continue modifying the module based on the return builder object by the Builder class methods, please modify the modules of the input builders in advance. The return builder, that is, the module no longer supports the modification through the Builder class API. It can only be used for calling GetModule() API and passed to topsGraphCompiler.
The API implementation principle is to copy the module from the first builder parameter, and then append the op contained in the second builder parameter, so the second parameter’s module-level attributes will not be included in the returned object.
This API is an experimental API and will be deprecated in about 6 months, that is, on October 1, 2023.

Parameters: builders – the two builders which will been merged.
Returns: The new merged builder.

5.2. Type¶

std::ostream &operator<<(std::ostream &out, Type type)¶: Feed the Type information to the specific output stream.

class builder::Type¶

#include <hlir_builder_common.h>

This represents the output type of an Op. It contains the information of both the shape and the primitive type.

Public Functions

explicit Type(PrimitiveType primitive_type = builder::PrimitiveType::NONE())¶

Constructor of an scalar Type.

Parameters: primitiveType – Data type of the scalar

Type(const std::vector<int64_t> &shape, const PrimitiveType &primitive_ype)¶

Constructor of an tensor Type.

Parameters

shape – Shape of the tensor
primitiveType – Data type of the tensor

Type(const std::vector<std::vector<int64_t>> &shape, const std::vector<PrimitiveType> &primitive_type)¶

Constructor of an tuple Type.

Parameters

shape – Shape of the tuple
primitiveType – Data type of the tuple

explicit Type(const std::vector<Type*> &types)¶

Constructor of an tuple Type.

Parameters: types – Vector of Type pointers

bool operator==(const Type &type) const¶

Overloaded operator “==” to judge if 2 Type are the same.

Parameters

type – another Type instance

Returns

Judge result

Returns

true – shape and primitive type are the same
false – otherwise

bool operator!=(const Type &type) const¶

Overloaded operator “!=” to judge if 2 Type are different.

Parameters

type – another Type instance

Returns

Judge result

Returns

true – shape or primitive type is different
false – otherwise

bool IsEmpty() const¶

Judge if it’s empty, i.e. with empty shape and NONE data type.

Returns

Judge result

Returns

true – Empty Type
false – Scalar, Tensor or Tuple Type

bool IsDynamic() const¶

Judge if it’s dynamic, i.e. with unknown dim shape or unrank.

Returns

Judge result

Returns

true – Dynamic shape
false – Static shape

bool IsTuple() const¶

Judge if it’s a tuple type.

Returns

Judge result

Returns

true – tuple
false – others

int64_t GetRank() const¶

Get the rank.

Returns: the rank

uint64_t GetSize() const¶

Get the total elemnent number.

Returns: the total elemnent number.

void SetShape(const std::vector<int64_t> &shape)¶

Set the shape.

Parameters: shape – the shape

std::vector<int64_t> GetShape() const¶

Get the shape.

Returns: the shape

void AddDimSize(int64_t size)¶

Add a dimension at the back of the shape.

Parameters: size – the size to be added

void SetDimSize(int index, int64_t size)¶

Set the size of the specified dimension.

Parameters

index – the index of the specified dimension
size – the size of the specified dimension

int64_t GetDimSize(int index) const¶

Get the size of the specified dimension.

Parameters: index – the index of the specified dimension
Returns: the size of the specified dimension

void SetPrimitiveType(const PrimitiveType &prim_type)¶

Set the data type.

Parameters: prim_type – the data type

PrimitiveType GetPrimitiveType() const¶

Get the data type.

Returns: the data type

int64_t GetTupleSize() const¶

Get the element number for the TUPLE type.

Returns: 0 if it is not a TUPLE, else the element number for the TUPLE

std::vector<std::vector<int64_t>> GetTupleShapes() const¶

Get the shapes or the TUPLE type.

Returns: the shapes

std::vector<PrimitiveType> GetTuplePrimitiveTypes() const¶

Get the data types or the TUPLE type.

Returns: the data types

void Print(std::ostream &out) const¶

Print the Type information to the specific output stream.

Parameters: out – Output stream

void Dump() const¶: Print the Type information to stdout.

std::shared_ptr<Impl> GetImpl() const¶

Get the inner implementation object pointer.

Returns: The inner implementation object pointer

5.3. Attribute¶

std::ostream &operator<<(std::ostream &out, Attribute attr)¶: Feed the Attribute information to the specific output stream.

class builder::Attribute¶

Public Functions

Attribute()¶: Constructor of an empty attribute.

explicit Attribute(const char *value)¶

Constructor of an attribute of type string.

Parameters: value – Incoming information data

explicit Attribute(bool value)¶

Constructor of an attribute of type bool.

Parameters: value – Incoming information data

explicit Attribute(int32_t value)¶

Constructor of an attribute of type int32_t.

Parameters: value – Incoming information data

explicit Attribute(int64_t value)¶

Constructor of an attribute of type int64_t.

Parameters: value – Incoming information data

explicit Attribute(float value)¶

Constructor of an attribute of type float.

Parameters: value – Incoming information data

explicit Attribute(double value)¶

Constructor of an attribute of type double.

Parameters: value – Incoming information data

Attribute(Type data_type, void *data)¶

Constructor of an attribute of type Dense.

Parameters

data_type – tensor type
data – Data address

Attribute(Type data_type, std::shared_ptr<void> data_ptr)¶

Constructor of an attribute of type Dense.

Parameters

data_type – tensor type
data_ptr – shared_ptr data

Type GetType() const¶

Get the attribute Type.

Returns: The attribute Type

double GetValueAsDouble() const¶

Get the attribute value.

Returns: If it is float and double type, return value, otherwise return 0.0

int64_t GetValueAsInt() const¶

Get the attribute value.

Returns: If it is integer type, return value, otherwise return 0

bool GetValueAsBool() const¶

Get the attribute value.

Returns: If it is bool type, return value, otherwise return 0

const char *GetValueAsString() const¶

Get the attribute value.

Returns: If it is string type, return value, otherwise return nullptr.

std::shared_ptr<void> GetValueAsDataPtr() const¶

Get the attribute value.

Returns: If it is dense type, return value, otherwise return 0

void Print(std::ostream &out) const¶

Print the Attribute information to the specific output stream.

Parameters: out – Output stream

void Dump() const¶: Print the Attribute information to stdout.

5.4. Op¶

std::ostream &operator<<(std::ostream &out, Op op)¶: Feed the Attribute information to the specific output stream.

class builder::Op¶

#include <hlir_builder_common.h>

This represents an instruction that has been enqueued using the Builder.

Public Functions

Op(std::shared_ptr<Builder> builder, std::shared_ptr<Impl> impl)¶

Constructor of Op.

Parameters

builder – A Builder shared pointer
impl – A Impl shared pointer

std::shared_ptr<Builder> GetBuilder() const¶

Get the Builder shared pointer.

Returns: The Builder shared pointer

Type GetType() const¶

Get the op Type.

Returns: The op Type

const char *GetName() const¶

Get the op name.

Returns: The op name, which is a constant char literal.

std::shared_ptr<void> GetConstDataPtr() const¶

Get data pointer of ConstOp.

Returns: The data pointer of ConstOp, nullptr for other Ops

bool IsValid() const¶

Judge if it’s a valid op.

Returns

Judge result

Returns

true – a valid op which has been inited.
false – otherwise

bool IsNull() const¶

Judge if it’s a null op. ONLY used for op which want to set attribute.

Returns

Judge result

Returns

true – a null op which doesn’t have a background hlir op.
false – otherwise

bool IsConstant() const¶

Judge if it’s a constant op.

Returns

Judge result

Returns

true – constant op
false – otherwise

bool IsDynamic() const¶

Judge if it’s dynamic shape.

Returns

Judge result

Returns

true – dynamic shape
false – static shape

bool IsUnknownRank() const¶

Judge if its shape is unknown rank.

Returns

Judge result

Returns

true – unknown rank
false – otherwise

template<typename T> inline std::vector<T> GetConstData() const¶

Get vector contains data of ConstOp. Error occurs for other Ops.

Returns: A vector contains data of ConstOp

std::shared_ptr<Impl> GetImpl() const¶

Get the Impl shared pointer.

Returns: The Impl shared pointer

void AddAccessory(Op &accessory)¶

Add an accessory op to this op. It means this op is composed of accessory ops.

Parameters: an – accessory op to be added to this op

void SetAttribute(const char *name, const Attribute &value, const char *mode = "")¶

Set op attribute parameters.

Parameters

name – attribute name
value – attribute object
mode – mode of setting attribute of accessories. Options: “”: do not set the attribute for accessories. “copy”: copy the attribute for accessories. “derive”: derive the attribute for accessories with postfix “_index”, where index starts with 0. Only work for string.

void SetAttribute(const char *name, const std::vector<Attribute> &value)¶

Set op array attribute parameters.

Parameters

name – attribute name
value – vector of attribute object

Attribute GetAttribute(const char *name) const¶

get op attribute parameters info.

Parameters: name – attribute name
Returns: attribute object

void SetMC(const std::vector<int64_t> &mc)¶

Set op MC index info.

Parameters: mc – the MC index info

std::vector<int64_t> GetMC() const¶

Get op MC index info.

Returns: the MC index info If threr is no MC in op, return {}

void SetAlias(Op operand)¶

Set the Alias object of this op to operand. The param operand and current this op both can’t been tuple op with more than 1 element ops.

Parameters: operand – the source operand to be alias

void Dump() const¶: Dump op info.

void Print(std::ostream &out, uint32_t flags = PrintingFlags::None) const¶

Print the Op IR to the specific output stream.

Parameters

out – Output stream
flags – Print flag

5.5. Structs¶

class ConvDimensionNumbers¶: #include <hlir_builder_structs.h>

Structure of dimension information for conv op.

class DimensionsLayout¶: #include <hlir_builder_structs.h>

Structure of dimension information for layout.

class DotDimensionNumbers¶: #include <hlir_builder_structs.h>

Structure of dimension information for dot product.

class GatherDimensionNumbers¶: #include <hlir_builder_structs.h>

Structure of dimension information for gather.

class ScatterDimensionNumbers¶: #include <hlir_builder_structs.h>

Structure of dimension information for scatter.