Reference ¶

Contents

Reference

Command line flags ¶

$ karuta <command> [Files]

Commands(optional)
- run - starts runnable threads (same as –run)
- compile - compiles objects for specified files (same as –compile)
- sim - same as sim and also with self contained shell (same as –compile and –with_shell)
Debug options
- -db debug byte code compiler
- -dp debug parser
- -ds debug scanner
- -dt debug types
-l
- Enables info logging.
- Comma separated list of modules to enable for specific files.
–compile
- Compiles the file object and writes to a Verilog file.
- Calls compile() and writeHdl(name.v) at the end of execution.
–duration
- Maximum duration of the simulation.
–iroha_binary [binary]
- Specifies an alternative iroha binary.
–module_prefix=[mod]
- Module name prefix.
- File name without suffix (“a” for “a.v”) will be used if this is not specified.
- This can be used to get fixed module name for testing.
–output_marker=[marker]
- Marker string to be output before output file name.
- Karuta server uses this to generate links from output log.
–flavor=[flavor]
- Sets a specific flavor to the generated HDL files.
- e.g. –flavor=vivado-axi
–print_exit_status
- Shows exit status at the end of execution.
- Test uses this to check if karuta isn’t aborted.
–root
- Prefix for file output name.
- Karuta server uses this to isolate each run.
–run
- Runs every runnable threads in the source file.
- Calls run() at the end of execution.
–timeout
- Timeout of karuta command execution.
- Avoid infinite loop to run forever for test or Karuta server.
–vanilla
- Doesn’t read lib/default-isynth.karuta.
–vcd
- Generates vcd from generated verilog file.
–version
- Print version number.
–with_shell
- Generates a top level module to feed clock and reset.

Program structure ¶

A program is comprised of top level environment and method environment. Methods and various things can be declared only in top level environment.

// * Top level environment
// Modifying objects by declaring member variables.
//
func f() {
  // * Method environment
  // Object modification is not allowed (hence synthesizable).
}

Methods ¶

A method is declared as a member of an object. If no object name is given in the declaration, the method will belong to the current file object.

// This method belong to the current file object.
func f() {
}

@Annotation(key1="value1", key2="value2")
func mod.f(x, y #32) (#16, #16) {
  return (0, 0)
}

A declaration can have an argument list and return value list. A declaration begin with a keyword either func or process.

Variable declaration ¶

Syntax to declare a variable is:: [variable type] [name] [data type] e.g. ram a int[16]

Variable type	Data type	Note
shared	scalar or array	Equivalent to ram or reg
ram	array	BRAM/SRAM
reg	scalar	reg
mailbox	scalar	mailbox
channel	scalar	channel
var	scalar	Local variable

Data types of a scalar variable are:

int - 32 bits
#0 - boolean
#10 - 10 bits
#T - User define type T
object, module - Object

A vector type is declared by [scalar type][length] like int[16].

// top level local variable.
var x int
// member variable.
reg y int
reg self.z int

func f() {
  // method local variable
  var a int
  a = y + z
}

Basic Syntax ¶

Comments

// Comment
/* Comment too */
# is alloed at the beginning of a file. This is for #! for shells.

Literals

// Just a number.
123
0xf00d
0b1010
// A number with explicit width
123#32
// string
"abc"

Method definition

// func name(arguments) (return values) { ... }
// (return values) can be omitted if there is no arguments.
func funcName(arg1, arg2 #16, arg3 int) (int, int) {
  return arg1, arg3
}

Declarations

//
var x int
var x #32
var x #MyType
var x object
//
var x, y int
var x int = 0
//
channel c int
mailbox m int
//
var s string = "abc"
// var for an array is not allowed
shared a int[32]
shared m.a #16[4] = {1,2,3,4}

Expressions

//
name
__name // reserved for the implementation
//
a + b
a - b
a * b
a = b
a, b
(a)
f(x)
a = f(x,y)
(a, b) = f(x,y)
obj.a
obj.f()

Operators

a + b
a - b
a * b
// TODO: Describe the limitations
a / b
// shift amount should be constant
a >> b
a << b
// bit concat
a :: b
// range should be constant
a[l:r]

Statements

if a > b {
} else {
}

for var x = 0; x < 10; ++x {
}

Control

if cond {
}

for init; cond; update {
}

TODO: switch/case statement

module block

module {
  shared obj object = new()
  func bar() {
    obj.x[0] = 0
    obj.foo()
  }
}

module obj {
  // same as obj.foo()
  func foo() {
  }
  // same as obj.x
  shared x int[16]
}

Built in objects and methods ¶

Objects ¶

Object
- Array - Internal SRAM
- Env - Profiling
- Global - Placeholder for global variables
- Kernel - Base object for user’s design
- Memory - External SRAM
- Numerics - Registry for user defined types.

Built in methods ¶

Object.clone()
Object.dump()
Object.run()
Object.bool
Object.false
Object.true
Object.Object
Kernel.assert()
Kernel.abort()
Kernel.compile()
Kernel.exit()
Kernel.new()
Kernel.print()
Kernel.runIroha()
Kernel.setDump()
Kernel.setIROutput()
Kernel.setIrohaPath()
Kernel.setSynthParam()
Kernel.synth()
Kernel.wait()
Kernel.widthof()
Kernel.writeHdl()
Kernel.yield()
Kernel.Kernel_
Kernel.Object
Kernel.Module
Kernel.parent
Kernel.self
Kernel.Array
Kernel.Env
Kernel.Global
Kernel.Memory
Kernel.Numerics
Env.gc()
Env.clearProfile()
Env.disableProfile()
Env.enableProfile()
Env.isMain()
Array axiLoad, axiStore, waitAccess, notifyAccess, saveImage, loadImage, read, write
Memory setWidth
Channel write, writeFast, read
Mailbox width, put, notify, get, wait
.$compiled_module
.$dump_file_name
setIrohaPath(p string)
setIROuput(p string)
runIroha(opts string)
- e.g. runIroha(“-v -S -o x.v”)

Synthesis parameters ¶

When compilation is requested by calling compile() method, the synthesizer takes a snapshot of the object and generates IR from the structure and computation.

setSynthParam("resetPolarity", 0) // set negative reset (e.g. rst_n).
setSynthParam("maxDelayPs", 10000) // 10ns
setSynthParam("platformFamily", "generic-platform")
setSynthParam("platformName", "generic")

Annotations ¶

// Annotation for a method
@ThreadEntry() @ProcessEntry() @Process()
@SoftThreadEntry() @SoftProcess() @Soft()
@ExtEntry()
@ExtStub()
@ExtIO()
@ExtCombinational()
@DataFlowEntry()  // Might be removed
@ExtFlowStub()  // Might be removed
// Annotation for an array
@AxiMaster() @AxiMaster64() @AxiMaster32()
@AxiSlave() @AxiSlave64() @AxiSlave32()
@ThreadLocal() @ProcessLocal() @Local()
// channel parameters
depth=
// object parameters
distance=
// thread number
num=