====== Setting up the computing environment ======

[ __[[vlsi:home|Home]]__ ]
[ __[[vlsi:workbook|Design WorkBook]]__ ]
[ __[[vlsi:workbook:computing#contents|Back to index]]__ ]

== Contents ==

   * [[vlsi:workbook:computing:setup#introduction|Introduction]]
   * [[vlsi:workbook:computing:setup#first_login|First login]]
   * [[vlsi:workbook:computing:setup#bash_and_tcsh_shells|Bash and tcsh shells]]
   * [[vlsi:workbook:computing:setup#create_a_scratch_area_and_a_working_directory|Create a scratch area and a working directory]]
   * [[vlsi:workbook:computing:setup#set_up_your_working_directory|Set up your working directory]]
   * [[vlsi:workbook:computing:setup#link_the_pdk_directory|Link the PDK directory]]
   * [[vlsi:workbook:computing:setup#unix_permissions|UNIX permissions]]
   * [[vlsi:workbook:computing:setup#disk_quotas|Disk quotas]]
   * [[vlsi:workbook:computing:setup#check_your_technology_permissions|Check your technology permissions]]
   * [[vlsi:workbook:computing:setup#create_a_.cshrc_file|Create a .cshrc file]]
   * [[vlsi:workbook:computing:setup#cad_tools_setup_files|CAD tools setup files]]

**Keywords:** working area, initialization files, .cshrc, .cdsinit, .cdsenv, cds.lib, bindkeys




===== Introduction =====

In this chapter we describe all the necessary steps for setting up your
computing environment before you can start using any VLSI design tools. 

Follow these steps to create a **working area** from where you will run the applications 
and further standard directories required to organize the design activity 
and keep your projects and the associated environment 
in good order. UNIX permissions, policies for using disk space and how to customize the UNIX environment 
are discussed as well. \\
If you don't have any experience with UNIX/Linux, please read the introductory 
UNIX tutorial provided in the __[[|Appendix]]__ or any other online 
tutorial to familarize with UNIX basic commands. 

Instructions on this page assume that you already have obtained a
__[[vlsi:workbook:computing:accounts#getting_a_vlsi_account|VLSI computing account]]__. 

Next the most important setup files related to the UNIX environment are introduced. 

===== First login =====

A VLSI account includes login credentials and a fresh home directory created on a machine 
part of the VLSI computing cluster. The system administrator will provide the machine
name and your login credentials (username and a temporary password).

You are not required to physically work in front of a VLSI machine. 
All VLSI machines are visible from within the INFN computing networks, 
as well as from university computers. Thus you can always access your account 
remotely using the **[[http://en.wikipedia.org/wiki/Secure_Shell|Secure Shell (SSH)]]** 
connection protocol.

To connect remotely from a Linux or a Mac computer 
open a terminal application and use the ''ssh'' command:  

<code>
ssh [-X] username@eltXXX.to.infn.it
</code>

\\
You will be prompted to enter the username and the temporary password provided by the system administrator.
Use the ''-X'' option to enable X forwarding, which is required to open graphical windows remotely. If you are using 
a Mac computer use ''ssh -Y'' indeed, because Mac's operating systems are stricter about X forwarding compared 
to Linux. If you are working on a Windows system and for more details about remote working, please refer to the 
documentation contained in __[[computing_remote|Accessing computing resources remotely]]__. 
If you face any problems with X forwarding due to permission issues, please contact the VLSI system administrator ([[mazza@NOSPAMto.infn.it]], remove NOSPAM in the address). 


The first time you login in your VLSI machine please **change your temporary password**. 
Enter ''passwd'' at the command prompt:

<code>
passwd
Changing password for user <username>.
Changing password for <username>.
(current) UNIX password: ******** 
New password: ********
Retype new password: ******** 
passwd: all authentication tokens updated successfully.
</code>

\\
Your home directory is ''/users/<username>''. It should already contain some
default sub directories (e.g. ''Documents/'', ''Pictures/'' etc). 
Most important, all users' home directores are exported by NFS as 
''/export/eltxxxx/disk0/users/<username>'' and shared between the other 
VLSI machines through symbolik links,

<code>
ls -l /users
</code> 

\\
This is a very useful setup that allows to quickly share files among VLSI users.

===== Bash and tcsh shells =====

Almost anything will be done using this terminal screen, from navigating to other directories (folders) 
to running software like Cadence. You will need to be comfortable with using Terminal commands.

You will use the shell to organize your files, perform basic file operations 
and launch the VLSI application.

The default shell used to work with the VLSI design tools is **tcsh**. 
Please, check this setting using 

<code>
echo $SHELL
</code> 

at the command prompt. The output should be ''/bin/tcsh''.  If you want to use **bash** you are 
free to change the default login shell using the ''chsh'' command.
Enter your password when required, then logout and login again to make changes effective:

<code>
chsh -s /bin/bash
Changing shell for <username>.
Password: ******** 
Shell changed.
</code>

\\
Bear in mind that all default UNIX and Cadence environment setups are based on csh scripts.
If you plan to use bash you will have to temporarily change to tcsh whenever you want to run 
a VLSI software (simply type ''tcsh'' in the terminal). Otherwise you may have to set the environment by hand.  

We strongly recommend to keep using the default tcsh.

===== Create a scratch area and a working directory =====  

A quick list of basic commands to work with directories can be found 
[[http://www.ece.rice.edu/~cavallar/cadence/tutorial/unix.html|here]].

you must create a directory in which you can save your Cadence projects
Before you start using any licensed VLSI design tool create in your home 
directory a new directory ''~/scratch'' which will contain all your research work. 

Open a terminal and type:

<code>
mkdir ~/scratch
</code>

\\
The ''~/scratch'' area is a good place in which link general documentation about tools, 
sample configuration files, scripts etc. Of course you can use whatever name you prefer, 
another popular choice is simply ''~/projects/''.

At this point it is a good practice to create a new directory //<tech_dir>// for each 
**technology** you plan to work with. This helps you to keep your technology-dependent
setup files in good order and to avoid conflicts between different technologies:

<code>
cd ~/scratch
mkdir <tech_dir>
</code>

\\
For instance create under ''~/scratch'' a new ''ibm130nm'' directory or similar if you will 
design with the IBM 130 nm technology. For more details about any technology environment setup 
please refer to the documentation contained in the __[[vlsi:private:home|VLSI protected area]]__.
If you are new to Cadence and you want to start with the WorkBook tutorials create a ''~/scratch/tutorials''
directory indeed. 

''~/scratch/<tech_dir>'' or ''~/scratch/tutorials'' represent your **working directory** (which will be referred to 
as ''./'' in the WorkBook). The working directory is where you will start all Cadence executables. 
Never launch an executable from your home, because each tool creates many extra files and directories 
that would clutter it! Always start Cadence executables in your working directory!

===== Set up your working directory =====

Change your current directory to ''~/scratch'' (or whatever you called the main directory for your projects).

a few guidelines about setting up your working directory

organize your files, perform basic file maintenance, 
and launch the Cadence application.

keep your work for different projects separate

It is best to organize your work into multiple directories with each directory being dedicated to a specific class or research project. We will create a new directory where all of our libraries will be stored.

In the working directory you will put all the required Cadence initialization files and 
all the technology-related files. source code (e.g. Verilog/VHDL code), SKILL and OCEAN scripts, user libraries,
simulation results, technology documentation 
Create in the technology work area some additional directories which can be useful in order to better organize your design environment:

Actually feel free to create

Of course each user is free to create any custom directory on your demand.

Consider following directories hints and guidelins and always feel free 
to create new directories or to use different names according to your needs.

<code>
cd ~/scratch/<tech_dir>
mkdir assura calibre config data doc lib logs models skill src tmp 
</code>


**doc/**  \\
Create in your working directory a ''doc/'' directory in which put or link 
all the **technology-related documentation**. Such documentation is specific 
to the particular technology you are working with, hence you should keep it 
separate from the tools documentation, which you can actually put or link into 
a ''~/scratch/doc'' directory.

**tmp/**   \\
Anytime a local temporary directory ''tmp/'' or ''temp/'' is useful to hold files and 
directories for short periods of time.

**config/**, **setup/**   \\
Each user should exploit as much as possible customizations and setups which can be made 
in the local area. You can create a ''config/'' or ''setup/'' directory in which put custom 
configuration files, scripts, local copies of setup scripts provided by the VLSI
system administrator as well as sample configuration files that come with the fabrication technology.

**lib/**, **LibDir**   \\
If you deal with analog or mixed-mode design a ''lib/'' or ''libs/'' directory in your working directory 
is a must. According to a hierarchical approach, your designs will consist of building 
blocks grouped into custom **user libraries**. A library will contain the **cells** used in your circuits 
and cells will contain components from other user libraries or from technology libraries. 
Furthermore, each cell typically has different **cell views** (schematic view, symbol view, layout view etc.) 
depending on the purpose. \\
A ''lib/'' or ''libs/'' directory is used to save your designs in form of user libraries, cells and cell views. 
Another popular choice is ''LibDir/'' as well.



**sim/**, **SimDir/**  \\
If you deal with analog or mixed-mode design you should create in your working directory a main 
**simulation results directory**. Such directory will contain for each cell the various simulation 
files automatically generated by the circuit simulator, in particular **netlists**, **analysis directives** 
and **simulated data**. By default, Cadence IC creates a ''~/simulation'' directory in the home directory, but you can
change this default on your needs as described in 
__[[vlsi:workbook:analog:howtos#how_to_change_the_default_simulation_results_and_saved_states_directories|How to change the default simulation results and saved states directories]]__. Another popular choice is ''SimDir/'' as well.

**scripts/**   \\
Scripting languages are widely used in EDA softwares. 
Cadence Design Systems has been developed its own scripting languages 
**SKILL** and **OCEAN**. As a matter of fact, most of Cadence tool configuration 
files are SKILL files, whereas more experienced users can use OCEAN scripts to 
automatisize simulations and perform advanced simulations in analog and mixed-mode design. \\
Digital design requires the usage of **TCL** (Tool Command Language) scripts to perform
**RTL synthesys** and automatically generated layout (**place-and-route**). PCB design 
with Cadence SPB (Allegro) requires TCL as well. \\
You may create a main ''scripts/'' directory in your working directory and further ''skill/'', 
''ocean/'' or ''tcl/'' sub directories in which put your scripts, but feel free to create such 
directories in the working directory itself. 

**logs/**   \\
Each VLSI tool automatically generates a **log file** (''.log'') which keeps trace of everything you do,
along with reports, error and warning messages. By default, log files are created in the same directory 
where you launch a tool executable, but you can also create your own **log directory**.  
You can always specify a custom log directory in which put log files, generally using a command line option 
when you launch a tool executable or setting a new default into a local configuration file.   
You can create a generic ''log/'' or ''logs/'' as well as ''log_<username>/'' or ''log_<tool_name>/'' directories.

e.g.

<code>
virtuoso -log ./log/CDS.log
</code>





**models/**   \\
Create a new ''models/'' directory in which put **simulation models**. 
It is a good practice to use this directory to link default model files 
which come with the PDK installation as well as modified local copies such 
as custom corner files.

**data/**  \\
In order to save disk space, simulation results placed in the simulation results directory 
are just temporary files which are deleted when you quit a tool. 
Of course you are always asked if you want to save simulation data as well as which data 
you want to be saved and where you want to save them. Although default directories already exists 
(for instance the hidden directory ''./.artist_states'' in Cadence IC 6.1.x) 
a ''data/'' directory in your working directory could be better place for this purpose.

**src/**   \\
A ''src/'' directory is a good place in which put 
**hardware description languages (HDLs) source code**. 
If you deal with analog or mixed-mode design you may need to create 
analog behavioral models using the **Verilog-A** and **Verilog-AMS** 
hardware description languages, as well as if you want to do modern digital 
IC design, which is based on **Verilog** or  **VHDL** hardware description languages.
According to your needs you may create different sub directories, such as 
''vhdl/'' or ''verilog/''.

**assura/**, **calibre/**   \\
Analog and digital **layout** requires stressing **physical verification** procedures
to minimize failure probabilities in the final chip production phase. At first, layouts must verify 
specific geometric rules fixed by the technology known as **design rules**, requiring preliminary    
**design rule checking (DRC)** procedures. Then, a layout should be compared with the circuit schematic
to ensure that the intended functionality is implemented. This is done with a 
**layout-versus-schematic (LVS)** check. Finally, a **parasitic extraction (PEX)** tool is used to obtain 
a netlist including all layout parasitics, and a final post-layout simulations are compared 
to schematic-level simulations. \\
Different physical verification tools are available and Cadence //Assura// and Mentor Graphics //Calibre//
''assura/'' or ''calibre/''

Since
Under assura you can create different directories ''drc/'', ''lvs/'' and ''pex'' 
for physical layout verification with Cadence //Assura// tool

''AssuraDRC/'', ''AssuraLVS/'' or ''AssuraPEX/'' ''AssuraQRC''

link default **rule files** wich come with the PDK installation as well as custom
local copies.
//Calibre// is another tool to perform layout 
As for Assura for physical verification with Mentor Graphics //Calibre// tool


''CalibreDRC/'' ''CalibreLVS'' ''CalibrePEX/''


**lec/**   \\
In digital design, used for ???? 

**syn/**, **pnr/**  \\
If you deal with digital design, create ''syn/'' and ''pnr/'' directories in your working 
directory to perform **RTL synthesys** and **place-and-route** (automatically generated layout).

**gdsII/**   \\
The final layout of a project to be transferred to a foundry for chip production
**Graphic Database System II (GDSII)**

===== Link the PDK directory =====

VLSI design platforms are completely general and can support different **fabrication technologies**. 
When a particular technology is selected a set of configuration and technology-related files 
is integrated in the environment. 
This set of files is commonly referred to as **process design kit (PDK)** or **foundry design kit (FDK)**. 

It is a good idea to create in the working directory to create a symbolic link e.g. ''PDK_dir''  
to the PDK installation directory,

<code>
ln -s /path/to/PDK/install/dir PDK_dir 
</code>

===== Define proper UNIX permissions and create a public =====


, each UNIX system has a system temporary ''/tmp'' with write
permissions set for all users.
With a standard VLSI account you have **write privileges** only inside your home directory 
and in the system temporary ''/tmp''. Therefore each user should exploit as much as possible customizations 
which can be made inside the local area.

No root privileges! Neither ''sudo'' is not available!



If you want to change permissions to your home directory and protect your reseach work use:

<code>
chmod 711 $HOME/
</code>


Create a ''public'' in your home with ''755'' permission 
to share resources within collegues, 

<code>
mkdir ~/public
chmod 755 public
</code>

La cosa migliore e' avere permesso di attraversamento per la home, ''<nowiki>rwx--x--x</nowiki>'' (711)
e poi ''<nowiki>rwxr--r--</nowiki>'' (744) per la ''~/scratch'', cosi' un collega puo' listare la mia
area di lavoro ma non la mia home


see also how to __[[vlsi:workbook:computing:local|build your own development environment]]__



===== Disk quotas =====

At present no quota limits have been set for users on VLSI machines, 
so please be careful about runaway processes filling this up. 
In order to save disk space please **don't make unnecessary hard 
copies of pdf files** in your local area, use **symbolic links** 
(soft links) indeed. The space taken by a symbolic link does not 
depend on the space taken by the target. 

If you need to deal with large files, please consider to store them 
in the system temporary ''/tmp''.

it is important that you keep only relevant files in your home. 

===== Check your technology permissions ======

All VLSI users can work with AMS and IBM technologies. The access to other technologies is 
very restricted and it depends on the user membership to a specific **technology group** 
defined by the system administrator. You can check yourself the technology you are allowed to use 
with the ''id'' command, which prints username and groups:

<code>
id <username>
uid=xyz(user name) gid=600(user group) groups=xyz(group name) context=user_u:system_r:unconfined_t
</code>


<code>
id -n -G
</code>

You can also inspect the ''/etc/group'' configuration file with

<code>
more /etc/group
</code>




===== Create a .cshrc file =====

The default behavior of a **tcsh** shell is defined by ''/etc/csh.cshrc'' 
and ''/etc/csh.login'' files. ''.cshrc'' and ''.login'' are hidden files (dot files) 
located in your home directory used to configure the user and applications UNIX environment.
The ''.login'' is read every time you login to the system (//login shell//), while the ''.cshrc'' 
is read each time you open a new terminal (//interactive shell//). These files are only relevant 
if you are using tcsh, which is also the default shell used to run the VLSI tools. 
If you are using **bash** please refer to some ''.bashrc'' and ''.profile'' documentation.

''.cshrc'' and ''.login'' are commonly used to set **local variables** and **environment variables**
(e.g. modify the default system search path) and define command **alias**.  
Please note that these files are not automatically created when the system administrator 
creates a new account,  so it's up to the user to write them using a simple text editor. 
You can create just one (e.g. ''.cshrc'') or both of them. 

A well commented ''.cshrc'' sample file comes with the Cadence IC installation
in the ''/usr/cadence/IC_6.1.x/tools/dfII/cdsuser/'' directory (the last software release
is 6.1.5). You can copy it to your local area and make customizations which fit your environment:
 
<code>
cp /usr/cadence/IC_6.1.5/tools/dfII/cdsuser/.cshrc ~/cshrc.sample
</code>

Here an example of the typical content of a ''.cshrc'' file:

<code>
# .cshrc file
echo "Loading ~/.cshrc file"

# create new files with rw-rw-r--(664) permissions 
# and new directories with rwxrwxr-x (775) permissions
umask 022

# default editor
setenv EDITOR /usr/bin/nedit

##   Cadence environment variables   ## 
setenv IC_DIR   /usr/cadence/IC_6.1.5
setenv IUS_DIR  /usr/cadence/Incisive_10.20 
setenv CDS_Netlisting_Mode Analog
setenv CDS_LOAD_ENV addCWD          # load the working directory ./.cdsenv file 
                                    # after the home ~/.cdsenv one

# user alias
alias ll                'ls -althr'
alias xterm             'xterm -fg black -bg grey -geometry 120x30' 
alias virtuoso_help     '$IC_DIR/tools/bin/cdnshelp'
alias incisive_help     '$IUS_DIR/tools/bin/cdnshelp'
</code>


\\
<code>
if ( -r ~/.cshrcVLSI ) then
        source ~/.cshrcVLSI
else
    	if ( -r /usr/local/config/.cshrcVLSI ) then
                source /usr/local/config/.cshrcVLSI
        else
            	echo "No cshrc VLSI definition on `hostname`"
        endif
endif
</code>


\\
Each time you modify the ''.cshrc'' don't forget to run

<code>
source ~/.cshrc
</code>

to make changes effective, otherwise you have to close the current terminal and open another one.
Remind that //environment variables// are automatically transferred to a new shell when one is created
and are passed on to any program you run. On the other hand //local variables// do not get automatically 
transferred to a new shell when it is created, because they are used by the shell itself, not by other applications.


===== CAD tools setup files =====

Depending on which design platform or standalone tool you plan to work with, 
specific **initialization and configuration files** placed into your **home** and 
**working directories** are used to define the proper environment (technology setups, user preferences etc.) 
that will be loaded in the session work. For instance, a ''cds.lib'' file is used to
define //libraries// in Cadence IC (Virtuoso) and is loaded when the main ''virtuoso'' 
executable is launched.
A key to successfully run the VLSI tools is to know which are the most important setup 
files and how the system administrator has planned them to be used. 
Furthermore, a basic knowledge about these files is fundamental in helping users to fix 
the most common problems by themselves.

Since these files are generally specific to a platform or a tool, they will be discussed 
when related tools for analog and digital design will be introduced in the WorkBook.

If you need some quick links, please refer to:

   * __[[vlsi:workbook:analog:cdsenv|Cadence environment and setup files]]__ for full-custom analog design with Cadence IC (Virtuoso)
   * __[[vlsi:workbook:digital:cdsenv|Cadence environment and setup files]]__ for digital design

====== ======
\\
----

Last update: [[pacher@NOSPAMto.infn.it|Luca Pacher]] - Apr 28, 2013

~~NOTOC~~