All Alogic source files use the .alogic file extension. Every source file
contains an optional list of type definitions, followed by the definition of a
single design entity in curly braces:
<optional type definitions>
<entity keyword> <entity name> {
<entity description>
}
If the entity name is foo, the source file must be named foo.alogic. The compiler relies on this to find entity definitions and will produce an error if there is a mismatch.
Compilation of a complete Alogic design (one or more entities) into its Verilog representation is done in one step, with a single invocation of the Alogic compiler. Internally, there are 2 stages (although no intermediate files are created), as follows:
When the compiler reads a source file, first it applies the built-in preprocessor to the source text. This is a purely text based transformation. The preprocessor uses the syntax of the standard C preprocessor (#include, #ifdef etc), though with a significantly reduced feature set. The main intention is to allow sharing of type definitions using include files and to enable minimal conditional compilation for debugging, and compile time parametrization through macros. See the preprocessor page for the supported preprocessor directives.
To compile a complete Alogic design (one or more entities), the top-level
entities must be compiled together with any instantiated entities. The compiler
is typically invoked with a list of top level entity names, together with a list
of search directories specified with the -y option. At this point the compiler
will read in, preprocess and parse all source files required for the design,
based on the entities instantiated by the design hierarchy below the specified
top level entities. The design then undergoes a successive list of
transformations, at the end of which a set of output files are written into the
output directory specified with the -o option.
For example, in order to compile a design with a top level entity called
foo, invoke the compiler using:
alogic -o rtl -y src foo
- The compiler seeks to compile the top-level entity
foo - -y src: the compiler searches for source files in the directory
src - -o rtl: the output is placed in the directory
rtl
See alogic --help for more command line options.
After running the Alogic compiler to compile the Alogic language files into their synthesized Verilog representation, the generated Verilog files can be used for RTL simulation and implementation as any other Verilog source file. The synthesized Verilog is independent of its corresponding Alogic source and can be released as the canonical implementation without the Alogic sources. There is no guarantee about the structure of the generated Verilog implementation between compiler versions, and therefore we advise against external modifications to generated source files. Verilog module interfaces corresponding to file scope design entities should have stable module interfaces across compiler versions.
Verilog implementations synthesized from Alogic language sources utilize a
single clock domain. Any logic generated by the compiler uses only rising edge
sensitive D flip-flops as sequential elements. The name of the clock signal in
the emitted Verilog is clk.
The only reset style currently supported by the compiler is active low
asynchronous reset. The name of the reset signal in the emitted Verilog is
rst_n.
Note that Alogic supports including arbitrary target language source text in any design entity using verbatim blocks. These verbatim contents are of course not required to follow the restrictions about clocking and reset described above.
The aim of Alogic is not to replace Verilog as the sole design language. There are cases where a direct Verilog description of a component is more appropriate, and therefore interfacing modules synthesized from an Alogic language description with other Verilog modules should be straight forward. Every Alogic port on a design entity has a well defined translation into usually multiple interface signals on the corresponding generated Verilog module. These translations and other Verilog interoperability considerations are described in their own page on Verilog interoperability
During development, the designer runs RTL simulations of the generated Verilog. Given the medium level of abstraction between Alogic and the corresponding Verilog, mapping issues back from the Verilog source locations to the corresponding Alogic source should be relatively simple in most cases. Where there is ambiguity due to reusing variable names in disjoint lexical scopes, the compiler tries to emit sensibly differentiated names, for example by appending the source line number to variable instances.