# The document describes a format of an intrinsics configuration file

An intrinsics config is a YAML file consisting of the following main elements:

- intrinsics_namespace
- intrinsics

(see [irtoc/intrinsics.yaml](../irtoc/intrinsics.yaml) as an example)

## intrinsics_namespace

C++ namespace used for intrinsics located in this file.

Example: ```intrinsics_namespace: irtoc```

## intrinsics

A sequence of configuration records (one per intrinsic).
A record starts with ```- name: name_of_intrinsic``` and typically includes the following properties:

  - [class_name](#class_name)
  - [method_name](#method_name)
  - [space](#space)
  - [static](#static)
  - [codegen_arch](#codegen_arch)
  - [codegen_func](#codegen_func)
  - [codegen_virt](#codegen_virt)
  - [llvm_codegen_func](#llvm_codegen_func)
  - [signature](#signature)
  - [impl](#impl)
  - [clear_flags](#clear_flags)
  - [set_flags](#set_flags)
  - [safe_intrinsic](#safe_intrinsic)
  - [description](#description)
    
### class_name

A name of a class to which a corresponding method will be attributed to.

Example: ```class_name: Irtoc```

### method_name

A name of a method. Usually both [class_name](#class_name) and [method_name](#method_name) are used  
to form ```class_name::method_name```,  which corresponds to a particular plugin (language) implementation  
(e.g. ArkTS plugin: ```std.math.ETSGLOBAL::sin```).  

In case of Irtoc intrinsics [method_name](#method_name) should be empty.

Example: ```method_name: sin```

### space

This property used to group intrinsics and control which intrinsics are loaded during startup.  
By default only ```core``` space is loaded.

Example: ```space: core```

### static

If it is set to ```true```, then there will be no implicit ```this``` argument passed to the intrinsic.  
By default it is ```false```.

### codegen_func

A name of a codegen method emitting a corresponding FastPath call (e.g. Irtoc implementation)  
or encoding the intrinsic explicitly by means of an arch-specific encoder.  
The method declaration is autogenerated, but you have to provide its definition (implementation).  
Depending on specified [space](#space) (and [class_name](#class_name) in some situations)  
a method definition should be placed into the corresponding plugin-specific codegen file, e.g.:

```space: core``` - [compiler/optimizer/code_generator/codegen.cpp](../compiler/optimizer/code_generator/codegen.cpp)  
```space: core``` and ```class_name: Irtoc``` - [irtoc/backend/compiler/codegen_fastpath.cpp](../irtoc/backend/compiler/codegen_fastpath.cpp)  
```space: ets```  - [plugins/ets/compiler/codegen_intrinsics_ets.cpp](../plugins/ets/compiler/codegen_intrinsics_ets.cpp)

Example: ```codegen_func: EmitSlowPathEntryIntrinsic```

### codegen_virt

If it is set to ```true```, then the method will be declared as ```virtual```.  
This allows overriding the method in classes inherited from ```Codegen``` (e.g. ```CodegenFastPath```).

By default it is ```false```.

Note, that this property has an effect iff [codegen_func](#codegen_func) is specified.

### codegen_arch

A list of supported target architectures.

Example: ```codegen_arch: [amd64, arm64, arm32]```

Note, that this property has an effect iff [codegen_func](#codegen_func) is specified.

### llvm_codegen_func

A name of LLVMIrConstructor method lowering the intrinsic to a corresponding LLVM IR  
(see [libllvmbackend/lowering/llvm_ir_constructor.cpp](../libllvmbackend/lowering/llvm_ir_constructor.cpp)) 

Example: ```llvm_codegen_func: EmitSlowPathEntry```

### signature

This property represents method signature, which consists of the following entries:
- ```ret:``` - method return type
- ```args:``` - method argument types

Example:  
```
signature:
  ret: void*
  args: [ u16, u16* ]
```

For a list of possible type values see ```get_type_for_cpp()``` in [irtoc/lang/instructions.rb](../irtoc/lang/instructions.rb)  
Note that currently Irtoc intrinsics' signatures are not checked and used for code generation,  
but it is recommended to provide a correct one (for reference).

### impl

A full name of a corresponging C++ function implementing the intrinsic.

Example: ```ark::ets::intrinsics::StdCoreDoubleIsFinite```

### set_flags

A list of flags, which will be explicitly set for the intrinsic.  
Possible flag values and their meaning are listed in [compiler/optimize/ir/instructions.yaml](../compiler/optimize/ir/instructions.yaml)

Example: ```set_flags: [require_state, can_throw, heap_inv]```

See ```opcode: Intrinsic``` in [compiler/optimizer/ir/instructions.yaml](../compiler/optimizer/ir/instructions.yaml) for a list of flags,  
which are set by default.

### clear_flags

A list of flags, which will be explicitly cleared for the intrinsic.  
Possible flag values and their meaning are listed in [compiler/optimize/ir/instructions.yaml](../compiler/optimize/ir/instructions.yaml)

Example: ```clear_flags: [require_state, can_throw, heap_inv]```

### safe_intrinsic

If it is set to ```true```, then the following *unsafe* flags will be cleared:  
```no_dce, no_hoist, no_cse, barrier, require_state, runtime_call, heap_inv, can_throw```

*Unsafe* means that an intrinsic may violate the conditions, which are necessary  
to correctly perform some compiler optimizing transformations.

### description

It is just a description.