Original PDF Flash format Topaz-Guide  


Topaz Guide

Topaz Guide
Plurality
By Omer Medan (omer@plurality.com)
Copyright of Plurality Ltd.
Published by Plurality Ltd. (2008)
First Edition.
i
Table of Contents
1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2
Command Line Arguments . . . . . . . . . . . . . . . . . 2
2.1
Input Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3
Input and Output Files . . . . . . . . . . . . . . . . . . . . 4
3.1
Input Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4
Topaz Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.1
Declaration syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.2
Termination sytnax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.3
Condition syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
4.4
Reset syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5
Simulator Initialization . . . . . . . . . . . . . . . . . . . . . 6
6
Emulator Initialization . . . . . . . . . . . . . . . . . . . . . 7
7
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7.1
Error list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8
Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Chapter 1: Overview
1
Topaz Guide
1 Overview
Topaz is a code generation tool. It reads task map files, and emits a task map which can be
loaded into a simulator, emulator, and real hardware. A task-map file is a text file contains
a Task Oriented Programming, or TOP. The file contains the dependencies between the
tasks, and their boolean conditions. Topaz also emits Hal assembly (if any is written inside
the tasks), and translates it to the task code.
The usual usage of Topaz is to build up assembly programs. Topaz reads the file given
by the user, tests for errors in the task-map, and outputs the loading program to an output
file, which is also given by the user. If no file is defined in output, Topaz defaults the output
to a.out. However, this isn’t a binary file format. The file is a simple text file. It contains
a task map image, and one loading program which loads the program to the chip. This
file needs to be passed to the HAL assembler (hal-elf-as), in order to produce a real binary
program.
If you are not writing an assembly program, you will usually leave the task-map without
any code inside, or even output it from a C/C++ source code by a script, or grep. The idea
is that Topaz’s input is always a task-map in text file, and always outputs as a text file.
The simplest way to run Topaz is by:
Topaz infile.map outfile.map
This command will create an output file called outfile.map which contains a loading
program for the program in infile.map.
Note - the HAL assembler (hal-elf-as) does not recognize TOP instructions.
A simple map file will look like this:
normal task foo ()
exit_task
This example will create a task called foo, which starts after the init task, and does
nothing. (more about the syntax in the TOP chapter). Code for foo task should be between
the declaration and the exit_task instruction.
Chapter 2: Command Line Arguments
2
Topaz Guide
2 Command Line Arguments
Topaz is a command-line tool, and as such it has various options. Options for Topaz start
with ’-’. Long options have ’—’, and short commands only have ’-’ and one letter afterwards.
Other strings inside the command arguments list, are considered as files. Topaz works with
file pairs. Each first file name is considered the input file, and the second is considered its
output file, so you can pass several programs to Topaz at once.
2.1 Input Commands
‘--asm=NAME’ controls the assembler style which Topaz recognizes and can work with. The
default is Plurality assembly.
‘--cemulator’ sets Topaz to output files for C emulator, instead of a loader for ’real’
program. The emulator files are output to the same working dir Topaz was executed. It con-
tains task map files and other header files which should be copied into the emulator/user
directory.
‘--cores-n=[N]’ sets cores number to N. Topaz will now recognize that it has only N
cores to work with, usually controls the stack code.
‘--debugging’ or (-d) outputs various debugging information about Topaz execution. It
should not be used unless you need to see something which shouldn’t happen. The output
log file can be used by Plurality to understand bugs in Topaz.
‘--disable-cores=(BEG,END)’ creates a code in the end of the loader which disables
the usage of the cores starting from BEG until END (including).
‘--enable-ram-ops’ or (-rm) enables RAM ‘ld’ and ‘st’ instructions in loading code.
‘--enable-stack’ or (-es) enables creating stack code. (for code which has stack, usually
C/C++)
‘--favor-frame-size=[N]’ or (-f=) sets the frame size to N
‘--favor-frame-depth=[N]’ or (-fd=) sets the frame depth to N
‘--ld-nops’ tells Topaz to enable loader without optimizations (without delay slot used).
‘--matlab’ sets Topaz to output code for Matlab emulator.
‘--target=[TargetName]’ sets Topaz machine target to TargetName.
Available machines are:
matlab: enables matlab target
pluri_ver_2(default): default machine
fpga_hal_16: fpga target (default)
elf: elf file format. never outputs any code save the map sections
easic_hal_40: Easic machines
‘--ramsize=VAL’ set data ram size to VAL. Real VAL is calculated as 2^VAL.
Chapter 2: Command Line Arguments
3
Topaz Guide
‘--iramsize=VAL’ set instruction ram size to VAL. Real VAL is calculated as 2^VAL.
‘--no-loader’ disables loader creation.
‘--no-topology’ disables a searching for tasks’ dependencies loop.
‘--name-mingling=NAME’ sets Topaz name mingling to NAME.
‘--set-dir=[DIR]’ sets output dir to DIR.
‘--set-macrosfile=NAME’ sets name of marcos file (if enabled) to NAME
‘--set-max-[TYPE]=VAL’ sets maximum allowed tasks in type TYPE to val
‘--enable-old-opcodes’ enables old opcodes macro file.
‘--set-loader-skeleton=NAME’ loads the loader from NAME file instead of internal
loaders list.
‘--topology-save’ saves the task map dependencies in a special file.
‘--task-list’ outputs a task list.
‘--help’ or (-?) outputs an help screen
‘--verbose-topa’ outputs task oriented programming information
‘--version’ displays Topaz version
Chapter 3: Input and Output Files
4
Topaz Guide
3 Input and Output Files
3.1 Input Files
As seen above, there are many ways to change the output files. From Matlab emulator
code to an old simulator loader. But we never change the input file method. The input
file is always the same for every target or machine. The task map is always generic. The
additional code which could be written inside the task map is an assembly code.1
Usually the suffix for a task map file is *.map.
3.2 Comments
For the sense of reading, you can use comments. There are two types of comments:
1. complete line comment
# this is a full line comment
2. end of line comment
foo %r1, %r2 ! this is end of line comment
Topaz supports including of other files into the assembly file, but does not support
including of another task map, yet. It means that the whole task map must be located in
the same file.
1 Topaz does not check for syntax errors in the assembly code, but it do check for instructions keywords.
So if you have an instruction like add %r35, %r11, %r12 Topaz will never tell you it is wrong. If the
op-code is unknown, then it will output an error.
Chapter 4: Topaz Syntax
5
Topaz Guide
4 Topaz Syntax
4.1 Declaration syntax
The syntax for task declare is simple:
normal task foo () ! declares a regular task
interrupt task 1 foo1() ! declares an interrupt task
duplicable task foo2 () ! declares a duplicable tasks
dummy task foo3 () ! declares a dummy task
As in this example:
normal task foo ()
4.2 Termination sytnax
The exit_task instruction is used to indicates task termination.
4.3 Condition syntax
The code inside the () is called the task condition. Tasks can be dependent upon termination
of 3 other tasks.
Syntax examples:
(foo/0): the task will start only if regular task foo will pass a false token
(foo/1): the task will start only if regular task foo will pass a true token
(foo/u): the task will start after regular task foo will terminate regardless of the token
(foo): the task will start after non-regular task foo will terminate
(foo | bar): the task will start after task foo or task bar terminate
(foo & bar): the task will start after task foo and task bar terminate
(foo & (bar | boo)): the task will start after task foo and task bad or task boo ter-
minate
Each regular task must have the token flag next to its name in the condition syntax.
Other types of tasks must omit the token flag.
4.4 Reset syntax
If reset token should be used it should be added after the condition code, as follows:
normal task foo (bar/u & dog/1) reset (cat/u)
The task cat resets the tokens passed from either bar and dog.
Only dummy task can be used as a reset token due to hardware limitations.
Chapter 5: Simulator Initialization
6
Topaz Guide
5 Simulator Initialization
Topaz supports various types of simulators. The usual case is to create a program in which
Topaz builds a loader to load it to the simulator. This isn’t the case in ELF target, however.
Each simulator has its own loader code, installed inside Topaz. User can change the loader
code by using ‘--set-loader-skeleton=NAME’ argument.
The loading phase, usually takes two steps.
‘boot loader’
The boot loader is a program which resides in the ROM of the chip. The usual
boot code loads up the instruction memory from the input port.1
The first word is the size of .text section (instructions) then the entire .text is
written. Afterward the .data section.2
After loading the instructions, the boot loader jumps to the starting address of
the image loader.
‘image loader’
The image loader is the loader which Topaz builds. It knows how to load the
task map into the CSU, and other initializations which must occur before the
program starts. Afterward, it terminates the initialization task and the
’real’ program starts.
1 The memory is formatted in an unoptimized way.It is called ST file. the ST file format is pretty obvious
to read
2 Not valid for any object types
Chapter 6: Emulator Initialization
7
Topaz Guide
6 Emulator Initialization
There are two types of emulators, C/C++ and Matlab
‘Matlab’
the Matlab emulator is an emulator for the task oriented programming for
programs written in Matlab. The output files from Topaz are:
‘TMinit.m’
Initialization of the task map. Acts the same as the loader
‘TMlanuch.m’
Code for launching one task
‘TMsetquota.m’
Code for setting tasks‘ quotas.
‘C’
The C emulator is a powerful tool which helps converting programs to TOP.
The output files from Topaz are:
‘tminit_dummy.h’
Dummy tasks initialization
‘tminit_enabled.h’
Pre-enabled tasks initialization
‘tminit_user.h’
Loads the task map to the emulator
‘user_launch.h’
Code for launching a task
‘user_names.h’
Code for handling names of tasks
‘user_quota.hC’
Code for handling quotas for tasks
‘user_protos.h’
Declaration of tasks function prototypes
Chapter 7: Errors
8
Topaz Guide
7 Errors
Topaz has various error messages, most are listed here. The error message format is:
Topaz: error: (linenumber): error message
7.1 Error list
‘no arguments’
Topaz was executed without any arguments. Nothing happened.
‘unknown argument’
Topaz was executed with an unknown argument. Check your argument list.
‘failed reading memory size’
Topaz cannot read memory size given by user.
‘memory size is larget than 2^32’
Hal does not support memory addresses bigger than 32 bit
‘co-unit target not supported’
Topaz does not recognize the co-processing unit type entered
‘cores number below or equal 0’
The number of cores is below or equals zero.
‘panic exit’
Topaz encountered an internal bug. Please report.
‘files number are too few’
There are too few output files. Check the list of files.
‘no tasks defined in file’
No tasks were defined in current file.
‘can’t generate emulation code’
Topaz cannot generate an emulation code. The reason is written one error
before this error
‘[task type] tasks exceeded maximum limit’
Number of tasks exceeded the maximum limit allowed in current CSU.
‘failed to build task map’
Topaz cannot build a task map
‘no registed used in [task name]’
No register was used in set quota instruction
‘task [task name] has id which already been defined’
The task has same id as already defined task. Same id is used for both tasks
‘task [task name] has 0 id’
The task has id of zero, which is the initialization task.
‘syntax error’
Syntax error in line.
Chapter 7: Errors
9
Topaz Guide
‘can’t add new task’
Topaz cannot add task for some reason.
‘task name undefined. empty name used’
The task name is empty.
‘task name undefined [NAME]’
No task [NAME] is defined.
‘task [NAMEA] can’t receive token from [NAMEB]. type is [TYPE]’
Task NAMEA cannot have condition token from NAMEB, because it is typed
TYPE.
‘unknown keyword’
Unknown assembly keyword.
‘task [NAME] has no exit_task instruction’
Task must be followed by an exit_task instruction.
‘setting quota for none duplicable task [NAME]’
Task NAME is not a duplicable task.
‘task [NAME] has no id’
Interrupt task [NAME] has no id defined.
‘task already defined [NAME]’
Same name for two tasks is not allowed.
Chapter 8: Bugs
10
Topaz Guide
8 Bugs
Please report bugs to support@plurality.com. Thanks

Document Outline