Multiple Instance Generator Tool ---------------------------------- Original Rev. 21-FEB-2004 Most Recent Rev. 26-FEB-2004 This file describes the function and input file format for the Multiple Instance Generator Tool, aka "MIGT". Purpose ------- This MIGT tool is used to generate separate net list files for multiple instances of a same circuit. It does this by reading in a "User Configuration File" and an "Input Template File" and writing out a separate net list "Output Instance File" for each instance of the circuit. Description ----------- The user configuration file will supply MIGT with all the necessary run time information: The user configuration file will specify the name (and location) of the template file which is to be used to produce the multiple instances output files. The user configuration file will specify the substitutions required to transform the input template file into the multiple instances output files. The user configuration file will specify the directory where the multiple instances output file will be written to. A user configuration file consists of a set of "MIGT Directive" lines No MIGT directive line may ever appear in the template file. MIGT directives may appear in any order. By convention (but not a requirement), the input template file specified in the user configuration is located in the same directory as the confguration file. By convention (but not a requirement), the file name of the input template file contains the character substring "template", and this substring will be replaced to form the file name of the output instance files, e.g. analog_adc_section_template_nets.txt -> analog_adc_section_17_nets.txt All instances of output net list files generated are the same except for: their filename the numeric value that appears in a specified field of some net_names in the net list output file the numeric value that appears in a specified field of some reference designators in the net list output file All lines in the input template file appear in each instance of the output net list files. MIGT will insert a few additional comment lines at the top of each output instance file e.g. to record the creation date and time, the MIGT version number, and the name of the input template file. Running MIGT ------------ MIGT is a python script which needs to read a user configuration file containing all the needed run-time information. There are no additional run-time interactions, interactive or otherwise, between MIGT and the user. There are 3 different ways for MIGT to read a configuration file. MIGT can be executed with no arguments, and it will ask for the name of a configuration file, e.g. $ python migt.py $ ./migt.py MIGT can be passed the name of the script as an argument e.g. $ python migt.py optional_path/my_configuration.migt MIGT can instead be implicitely invoked by directly executing the configuration file, e.g.: $ ./my_configuration.migt This method is explained in more details below To be able to directly execute a MIGT configuration file, the user configuration file must start with this first line: #! /bin/env migt.py which indicates that the shell needs to call the MIGT python script to execute this configuration file. This implies that the migt.py file must be in the same directory as the configuration file, or must be accessible via the user's PATH environment variable definition. Alternatively, the first line of the user configuration file may be modified to provide an explicit path to migt.py. The first line of the MIGT python script is #! /bin/env python which indicates that the shell needs to call the python interpreter to run the MIGT python script. Note that the python interpreter must be accessible via the user's PATH environment variable definition. Alternatively, the first line of migt.py may be modified to provide an explicit path to the python interpreter. When the user executes the configuration file, the first line of the configuration file (specified above) will invoke the MIGT tool while passing it the name of the configuration file as an argument. The MIGT python file will in turn invoke the python interpreter to execute its python code. The MIGT python script (1) starts by defining the functions which implement the MIGT directives, then (2) executes the configuration file where it learns what needs to be done, and (3) produces all requested output file(s). User Configuration File ----------------------- The comment flag allowed in the user configuration file is "#", since this configuration file becomes part of a python script. If a directive needs to be continued on the following line, the backslash "\" (python continuation character) should be used. All MIGT directives take the form of a function call: the name of the directive type is followed by a pair of parenthesis containing one (or more depending on the directive) arguments. For uniformity, all arguments are treated as strings, and should be enclosed in double quotes. As will become apparent below, we make use of python's syntax rules which allows a function call to explicitely repeat the name of the arguments appearing in a python function declaration. There are only three types of MIGT directives "MIGT_input_template" directives provide information about the input template file: name and location "MIGT_output_instances" directives provide information about the output instance files: location, total count, how to generate their names, "MIGT_substitute" directives add entries to the dictionary which MIGT will use when transforming the input template file intou output instance files. The full list of MIGT directives is: MIGT_input_template ( path = "template_file_path" ) This directive specifies the path to use to find the template file. This directive is optional, and by default the input template file is expected to be in the same directory as the user configuration file. Arguments : template_file_path Character string specifying the directory where MIGT will look for the template file This may be an absolute or relative path. MIGT can accept path strings ending or not with a slash. e.g. "../analog" or "/home/user/project/analog" or "analog" or "analog/", etc. MIGT_input_template ( name = "template_file_name" ) This directive specifies the file name for the template file to be parsed and transformed into the multiple output files. This directive is required as MIGT cannot produce any output without an input template file. More than one MIGT_input_template argument may be specified in the same directive line e.g. MIGT_input_template ( path = "analog_section/", \ name = "analog_cell_template.net" ) Arguments : template_file_name Character string specifying the name of the template file. By convention the string "template_file_name" should include the substring "template". Do not include a path in this name (use instead the explicit "path" argument described above), or MIGT will also append it to the output path. MIGT_output_instances ( path = "ouput_instances_path" ) This directive specifies the path to the directory that MIGT will use when creating the output instance files. This directive is optional, and by default the instance files are created in the same directory as the input template file. Arguments : ouput_instances_path Character string specifying the directory where MIGT will write the output instance files MIGT_output_instances ( total = "tot_instances" ) This directive specifies the total number of output instance files that MIGT should generate using the input template file. Arguments : tot_instances Character string representing an integer value which specifies the total number of output instance files to be generated from the input template file. MIGT_output_instances ( key_is = "key_string" ) MIGT_output_instances ( start_at = "start_value" ) MIGT_output_instances ( increment_by = "increment_value" ) These directive specify the substitution to make in the template file name to produce the output instance file names. More than one MIGT_output_instances argument may be specified in the same directive line e.g. MIGT_output_instances ( total="3", start_at = "10", increment_by = "20" ) Arguments : key_string Character string to be taken as a substring of the template_file_name specified separately with a MIGT_input_template directive. This directive is optional, and the default is "template". start_value Character string representing an integer value (e.g. "1" or "50") which specifies the substitution desired for "key_string" and for the first instance of the output files. This directive is optional, and the default is "1". increment_value Character string representing an integer value which specifies the increment desired for "key_string" between successive instances of the output files. This directive is optional, and the default is "1". The filenames of the output net list files will be the same as the filename of the input template file except that the string "template" in the input filename will be replaced by: the characters representing the numeric value "start_value" in the first instance of the output file, by the characters representing the numeric value of "start_value + increment_value" in the 2nd instance of the output net list file, and by the characters representing the numeric value of of "start_value + 2*increment_value" in the 3rd instance of the output net list file, ... MIGT_substitute ( key_is = "key_string", start_at = "start_value", \ increment_by = "increment_value" ) This directive specifies one of the substitutions MIGT will make in the content of the template file to produce the content of the output instance files. A configuration file will typically contain several instances of the MIGT_substitute directive to indicate multiple separate substitutions. All three arguments are always required in every MIGT_substitute directive. There are no default values for any of the arguments. The key names are NOT case sensitive MIGT will detect and NOT accept multiple definitions with the same key name. Arguments : key_string Character string representing a key string (a.k.a. a dictionary entry) that MIGT will be expected to recognize in the template file. The template file will use angle brackets around the instances of all the key substrings (i.e. "", but without the quotes) to emphasize the substitutions within the rest of the lines, and to avoid any ambiguity between key names and fixed text. start_value Character string representing an integer value which specifies the substitution desired for "" for the first instance of the output files. increment_value Character string representing an integer value which specifies the increment to apply to the value "start_at" between successive instances of the output files. The MIGT tool will scan each line of the template file and will look for all instances of the key character strings "" (or "", etc.) In the template file, the key names must always be surrounded with opening and closing angle brackets surrounding the actual key names defined in the user configuration files. These brackets are used to signal the presence of, and delimit the keywords. By convention the key character strings ("key_string", "ijk", etc.) will use lower case characters (or capitalized words, e.g. "FeedbackResistor") to make them easier to locate within the rest of the file following the Mentor Graphics syntax (cf. below). MIGT will however not be case sensitive with respect to the key names. Any printable character may be used in a key name, including underscores (but excluding the opening and closing angle brackets <> which are reserved to delimit keywords). MIGT will warn the user if any translated template line is longer than 100 (?) characters. For lines containing a net name, MIGT will do a best try effort at tabulating the translated output net list lines to have the net name start at character 10 (?) the component-pin field(s) start at character 30 (?) any optional comment field start at character 50 (?). For lines NOT containing a net name, MIGT will not modify the location of any optional comment field. Review of the Mentor Graphics Net List File Format -------------------------------------------------- Comments begin with the character "#" at any point on a line. An active statement has the format: NET 'NET_NAME' REF_1-PIN_1 REF_2-PIN_2 ... typical example: NET 'DATA_LINE_7' U23-17 R56-1 # comment_goes_here This shows that a net with the name DATA_LINE_7 connects pin 17 of component U23 with pin 1 of component R56. Use of all capital characters is normal in the active part of these Mentor Graphics files. Use of the single quotes around the net_name is required. Often in a net statement only a single reference_designator - pin_number pair will appear. When Mentor Graphics builds the design it finds all net statements with the same net_name and puts them together so that it knows all the reference_designator - pin_number pairs that are connected by that net. Lines in the net list files are typically limited to 80 characters and never exceed 100 characters (or some number like that). I.E. the migt program does not need to be able to handle arbitrary length lines. Example Seed File and Output Net List Files ------------------------------------------- Example of an Input Configuration File: #! /bin/env migt.py # # specify template file MIGT_input_template ( name = "analog_section_template_nets.txt" ) # specify number and naming of output net list files MIGT_output_instances ( total="3", start_at="10", increment_by="20" ) # specify substitutions MIGT_substitute ( key_is="ijk", start_at="0", increment_by="5" ) MIGT_substitute ( key_is="lmn", start_at="1", increment_by="2" ) Example of a template file: analog_section_template_nets.txt # Example of Multiple Instance Generation NET 'CH__DATA_LINE_7' U21-3 U9-7 # Data Line signal 7 NET 'REF_VOLTAGE_3' U50-17 # Analog Reference Voltage First Instance Output Net List File: filename analog_section_10_nets.txt # Example of Multiple Instance Generation NET 'CH_0_DATA_LINE_7' U21-3 U19-7 # Data Line signal 7 NET 'REF_VOLTAGE_3' U50-17 # Analog Reference Voltage Second Instance Output Net List File: filename analog_section_30_nets.txt # Example of Multiple Instance Generation NET 'CH_5_DATA_LINE_7' U21-3 U39-7 # Data Line signal 7 NET 'REF_VOLTAGE_3' U50-17 # Analog Reference Voltage Third Instance Output Net List File: filename analog_section_50_nets.txt # Example of Multiple Instance Generation NET 'CH_10_DATA_LINE_7' U21-3 U59-7 # Data Line signal 7 NET 'REF_VOLTAGE_3' U50-17 # Analog Reference Voltage Using the substitution directives below, instead of the ones above, MIGT_substitute ( key_is="ChannelNumber", start_at="0", increment_by="5" ) MIGT_substitute ( key_is="adc_chip", start_at="19", increment_by="20" ) and using the following template file line, NET 'CH__DATA_LINE_7' U21-3 U-7 # Data Line signal 7 would produce the same output as the example above