Rik Lee, the author of today's post, is a PCB Designer with more than 35 years experience in the PCB industry, 25+ of those with the Cadence® Allegro® tools. Currently working with Samtec, he has previously worked for both Cadence and EMA, focusing on back-end PCB layout tool support. 

You come across an issue when using the tools, but you don’t understand why. Being able to troubleshoot an issue, and if needed provide a reproducible testcase to a peer or a Cadence AE, is the first step to resolving the issue.

If you have tried using Tools – Database check and that does not resolve the issue you will need to dig a bit deeper. When debugging the issue make sure it is reproducible. Also, are you on the latest release of the software? You can review the Readme_CCR.txt file to see if a similarly named issue has been resolved. This file can be found on the downloads.cadence.com site for the release that you are using.

Assessing whether this happens in all databases is one of the first steps to take. If needed, there are example databases which you can use for debugging or demonstrating an idea in the \share\pcb\examples\board_design directory of the install hierarchy.

If you can start the tools and see that the issue reproduces, you are well on your way to resolving the issue or helping a peer \ Cadence help you. You can note the steps taken to get to the issue or, even better, record a script that can be used to reproduce the issue. Open the drawing and select File – Script. Add a name for the script and then click Record.

Repeat the steps that show the issue and then stop the script by either clicking Stop in the Scripting dialog or enter stop at the command line. If you would like, you can add prompts to the drawing to describe what you are seeing. By typing at the layout editor command line, for example:

    confirm "Note how the clines spread too far."

Will produce this in the application:

When using this in a script, you will need to edit the script in a text editor to remove the fillin yes statement that follows your confirm statement or the layout editor will close the dialog.

When creating a testcase, leave only the layers that are affected enabled for display and zoom into the area of interest. While you may be intimately familiar with the issue and area of the design, a person that is seeing this for the first time would not be.

If the problem is a crash issue, you can use the journal file allegro.jrl and convert the journal into a script that can be used on the database. To best use this functionality, you should set the environment variable journal_nobuffer which is found in the file_management/journals category of User Preferences Editor before recording the script. Setting this variable changes the output of allegro.jrl to unbuffered. The advantage of unbuffered output is that sometimes with program crashes more lines are written to the journal file. I’d suggest only using this variable when you know you want to use allegro.jrl as a script, as it will slow the tool down.

To convert an allegro.jrl file into a script you can click Generate from the scripting dialog and browse to the allegro.jrl file or, you can open a command window in the directory that the journal file is stored and enter:

    j2script allegro.jrl textcase.scr

You may need to open the script file and remove the last few lines so the layout editor does not exit when replaying the script. Once you have a script that reproduces the problem, the next step would be to verify whether it’s a core tool issue or perhaps something in your environment that is the root cause. There are several methods you can use to perform this step which involves starting the tools without your environment variables.

One method is to rename your pcbenv directory. You can determine where your pcbenv directory is by opening a Windows file manager/Explorer window and at the top in the address line type:

    %home%

This will navigate to your HOME directory. Rename pcbenv to old_pcbenv. Restart the tools and none of your environment settings are used. Once you have finished with the debugging of the issue, you will need to delete the newly created pcbenv and rename old_pcbenv back to pcbenv to restore your environment.

The second method would be to open a command window where the drawing is located and type:

    allegro -safe

This will start the layout editor without any of your environment settings as if it’s was a fresh installation with no need to rename directories.

You then check to see if the issue will reproduce. If it does, you can be confident that others will be able to see the issue and provide a resolution or pass the issue onto Cadence engineering so that they can look into the issue.

What should be included when asking others to review a testcase?

The files below are needed when you are trying to show someone a problem you're having:

1. The Allegro database, zoomed into the area of interest, with only those layers needed to see the issue enabled in the color dialog. If you are concerned with IP, use File – Export – Strip design… (strip_design command) to rename and/or delete items in the database.
2. The allegro.jrl file.
3. The variables for both the operating system (OS) and the layout editor:
   • To retrieve the OS variables, open a command window and type set >OS_env.txt. this will produce an OS_env.txt file.
   • To retrieve the layout editor variables, use the tool and select Tools – Utilities – Env variables. Save the results to a file named allegro_set.txt.
4. Any files that are needed to support the layout editor tools. For example:
   • Artwork: photoplot.log, art_param.txt, and art_aper.txt (if applicable).
   • Import issue: any netlist files, DXF along with the conversion files, IDX, or IDF files.
5. Any screenshots you would like to add. As they say, a picture is worth a thousand words. These can be added to a Word document that describes the issue if you need to provide text for context, or just included as the image files with reasonable names to tell what they show.

Making sure that the person you send the data to can see what you’re seeing gets you an answer much quicker, so taking the few minutes up front can save you hours of back-and-forth time later on when that person needs to come back to you with questions about how to reproduce your problem.

Rik Lee