ReFlEx 1.0---A Demonstration Prototype of a Code Generation Tool ================================================================ Copyright (c) 1995, 1996 by Helsinki University of Technology, Digital Systems Laboratory. All rights reserved. ReFlEx can be freely used for non-commercial purposes. There is absolutely no warranty whatsoever. Maintenance is not guaranteed. Current source code release: ReFlEx 1.0.1 Date of the current source code release: Nov 27, 1996 Date of this document: Nov 27, 1996 Author of this document: Eero Lassila (eero.lassila@hut.fi) You can reach the latest revision of this document through the World Wide Web or via anonymous ftp. It is located as ftp://saturn.hut.fi/pub/reflex/ReFlEx-1 We would greatly appreciate any bug reports, questions, comments, or suggestions. Contact person: Eero Lassila Helsinki University of Technology Digital Systems Laboratory Otakaari 1 FIN-02150 Espoo Finland Telefax: +358 9 451 3369 Internet: reflex@saturn.hut.fi Contents of this document: 1. Introduction to ReFlEx 2. Up-to-date ReFlEx documentation 3. Obtaining the ReFlEx program package 4. Compiling the ReFlEx program 5. On ReFlEx exception messages 6. Sample ReFlEx rule files 7. An exercise for interested ReFlEx users 8. Source code release history 1. Introduction to ReFlEx ------------------------- Code generation for embedded special-purpose processors is usually a difficult task for compiler writers as well as for assembly language programmers. ReFlEx 1.0 is an experimental demonstration prototype of a code generation tool. ReFlEx is a retargetable assembly-code-level macro expander capable of program flow analysis. The main advantage offered by ReFlEx is its strong support for macro hierarchy. The enhanced modularity provided by hierarchical macro libraries can make the code (produced either by the compiler writer or by the assembly language programmer) more easily readable, maintainable, and reusable. Still, a program description written in the macro language retains its machine-specificity and, consequently, its efficiency. 2. Up-to-date ReFlEx documentation ---------------------------------- The full ReFlEx documentation can be found in the report Eero Lassila. ReFlEx---an experimental tool for special- purpose processor code generation. Helsinki University of Technology, Digital Systems Laboratory, Series B: Technical Reports, No. 15. ISBN 951-22-2993-5 (ISSN 0783-540X). 79 pp. Espoo (Finland), March 1996. A postscript version of this report (similarly to several other ReFlEx-related publications) is available through Internet. The downloading procedure is described in file ftp://saturn.hut.fi/pub/reflex/README After the report was published, some inaccuracies have been found in its text. Thus, the following corrections should be made: p. 25: In Section 5.4, each one of the lists of integer, cell, and label references is incomplete: on the right- hand side of a rigid compound form definition, all the form parameters are valid not only as integer references but even as cell and label references. 3. Obtaining the ReFlEx program package --------------------------------------- The ReFlEx program package file is available as ftp://saturn.hut.fi/pub/reflex/reflex.tar.Z It can be reached via anonymous ftp (binary transfer mode should be selected). The transferred file should be unpacked by the following command sequence: uncompress reflex.tar.Z tar xvf reflex.tar The former unpacking command converts the `reflex.tar.Z' file into the `reflex.tar' file. The latter unpacking command creates a subdirectory called `reflex' that contains the unpacked files. 4. Compiling the ReFlEx program ------------------------------- The `reflex/source' directory contains the following source files: g_msg.h i_tab.h r_tab.h reflex.h rfl_auto.h rfl_cnf.h rfl_dbg.h rfl_in.h i_tab.c lex_yy.c lex_zz.c r_tab.c alias.cxx autonom.cxx block.cxx cbuffer.cxx check.cxx color.cxx context.cxx debug.cxx encode.cxx eqlabel.cxx evaluate.cxx expand.cxx flexible.cxx freelist.cxx g_msg.cxx graph.cxx iface.cxx input.cxx lcheck.cxx map.cxx match.cxx message.cxx output.cxx parse.cxx proc.cxx program.cxx reduce.cxx reflex.cxx task.cxx token.cxx Of the files above, `i_tab.h', `r_tab.h', and all the *.c's are C files; the others are C++ files. If you use a GNU C++ compiler (i.e. `g++'), for instance, you can compile ReFlEx simply as follows: g++ *.c *.cxx -o reflex We have compiled ReFlEx using releases 2.5.8, 2.6.3, and 2.7.2 of GNU `g++'. The code should be portable onto various platforms. Additionally, the `reflex/parser' directory contains the following files: input.l input.y reflex.l reflex.y You may ignore these files, but, on the other hand, you might also like to know that we used them as specifications for some automatically generated ReFlEx source files. Our tools were the `flex' (2.5.2) lexical analyzer generator and the GNU `bison' (1.22) parser generator. We used the following command sequences: flex -Pzz input.l mv lex.zz.c lex_zz.c bison -d -v -p zz input.y mv input.tab.h i_tab.h mv input.tab.c i_tab.c flex reflex.l mv lex.yy.c lex_yy.c bison -d -v reflex.y mv reflex.tab.h r_tab.h mv reflex.tab.c r_tab.c 5. On ReFlEx exception messages ------------------------------- The `reflex/doc/g_msg.txt' file contains a computer-generated listing of all the ReFlEx exception messages. In addition to the information given at run-time when an exception is encountered, the listing provides many messages with a pointer to the appropriate section of the above-mentioned report. If you have troubles with the exception messages, do contact us (see the address above). 6. Sample ReFlEx rule files --------------------------- The `reflex/sample/reflex.m' file is a valid ReFlEx rule file; moreover, it is the same file as listed in Appendix C of the above-mentioned report. The `reflex/sample/reflex.s' file is a companion to the rule file. It consists of sample expansion sources, which can be run either as a batch reflex reflex.m -s ' prompt of ReFlEx): reflex reflex.m -r:reflex.s > 3 Additionally, the `reflex/sample/simple.m' file is the rule file dealt with in the tutorial section of the above-mentioned report. 7. An exercise for interested ReFlEx users ------------------------------------------ Once you have become familiar with ReFlEx, you might be interested in trying to solve a non-trivial ReFlEx macro writing exercise as a diagnostic self-test. So, we ask you to extend the `reflex/sample/reflex.m' rule file as follows. Exercise: Write a macro `left_shift(s,n > d)' that transfers data from an arbitrary source `s' into an arbitrary destination `d' and, most of all, simultaneously shifts the data to the left by `n' bit positions (you can require that `n' represents a non-negative integer, and not a cell). In other words, the macro should implement the C language expression `d = s << n'. We would be pleased to answer any questions concerning this exercise. 8. Source code release history ------------------------------ 1.0 (Mar 7, 1996) Initial release. 1.0.0.1 (Mar 25, 1996) Code polished by removing most of the messy points for which GNU `g++' 2.7.2 produced warnings. All these warnings were superfluous. 1.0.1 (Nov 27, 1996) A minor bug fixed. The bug was in error recovery during the initial rule file checking.