update top-level gitigore and readme

.gitignore

@@ -46,3 +46,7 @@
 *.dmp
 vivado_pid*
 *~
+
+# vivado workspace files
+xsim.dir/
+xvlog.pb

README.md

@@ -21,97 +21,78 @@ Since the day I joined my lab, managing Vivado projects has always been a pain i
 
 ## How this repository is constructed?
 
-This repository is designed to store Vivado project design sources and Verilog/VHDL files primarily, but it can also hold associated MATLAB files and related documentation explaining how the modules work and things that need to be taken care of when interfacing with the modules.
+This repository is designed to store Vivado project design sources and Verilog/VHDL files primarily, but it can also hold associated MATLAB codes of algorithm verification or data analysis and related documentation explaining how the modules work and things that need to be taken care of when interfacing with the modules.
 
 ### Overview
 
 ``` plain
-vivado-git
+.
-|
 ├── .git
 ├── .gitignore
 ├── README.md
-│
 ├── adi_library/
 │   └── ...
-│
+├── common
+│   ├── adder_tree_ppl.v
+│   └── ...
 ├── custom_ips
+│   └── ...
 ├── modules/
 │   └── xc7k410tffg900-2/
 │       └── tx_qpsk/
+│           ├── project.tcl
 │           ├── constraints
 │           ├── docs
 │           ├── ip/
 │           │   ├── hrc_64_12_025.xcix
-│           │   │
 │           │   ├── coe/
-│           │   │   └──hrc_64_12_025.coe
+│           │   │   └── hrc_64_12_025.coe
-│           │   │
 │           │   └── managed_ip_project/
-│           │       │  managed_ip_project.xpr
-│           │       │
-│           │       └── managed_ip_project.cache/
 │           │       └── ...
-│           │
 │           ├── ipi-bds
-│           ├── project/
+│           │   └── ...
-│           │   └── tx_qpsk/
-│           │       └── tx_qpsk.tcl
-│           │
 │           ├── rtl/
 │           │   └── tx_qpsk.v
-│           │
 │           ├── scripts
 │           └── testbenches/
 │               └── tb_tx_qpsk.v
-│
 ├── projects/
 │   └── datalink_814/
 │       └── dl814_k7/
+│           ├── project.tcl
 │           ├── constraints/
 │           │   └── k7410t_ad9516_2ad9361_physical.xdc
-│           │
 │           ├── docs
 │           ├── ip/
 │           │   ├── sys_clk_gen.xcix
-│           │   │
 │           │   └── managed_ip_project/
 │           │       └── ...
-│           │
 │           ├── ipi-bds/
 │           │   └── system_bd/
 │           │       ├── system_bd.bd
-│           │       │
 │           │       └── hdl/
 │           │           └── system_bd_wrapper.v
-│           │
 │           ├── project/
-│           │   └── dl814_k7_cmos/
+│           │   └── project/
-│           │       ├── dl814_k7_cmos.tcl
+│           │       ├── project.hw/
-│           │       │
+│           │       │      project.lpr
-│           │       ├── dl814_k7_cmos.hw/
+│           │       ├── project.runs/
-│           │       │      dl814_k7_cmos.lpr
-│           │       │
-│           │       ├── dl814_k7_cmos.runs/
 │           │       │   └── impl_1/
-│           │       │       └── system_top.bit
+│           │       │       ├── system_top.bit
-│           │       │
+│           │       │       └── ...
-│           │       └── dl814_k7_cmos.sdk/
+│           │       └── project.sdk/
 │           │           ├── system_top.hdf
-│           │           │
+│           │           ├── dl814_cmos_48m/
-│           │           ├──dl814_cmos_48M/
 │           │           │   └── src
 │           │           │       └── ...
-│           │           │
+│           │           └── dl814_cmos_48m_bsp
-│           │           └── dl814_cmos_48M_bsp
 │           │               └── system.mss
-│           │
+│           ├── rtl
-│           └── rtl/
+│           │   ├── system_top.v
-│               ├── system_top.v
+│           │   └── ...
-│               │
+│           ├── scripts
-│               └── ...
+│           └── testbenches
-│
+└── template
-└── template/
     ├── constraints
     ├── docs
     ├── ip
@@ -120,6 +101,7 @@ vivado-git
     ├── rtl
     ├── scripts
     └── testbenches
+
 ```
 
 ### Top Level
@@ -133,10 +115,12 @@ The organization of the top level structure is shown in the table below.
 | `custom_ips`  | Custom IPs. | Yes | No | No |
 | `modules`     | Verilog/VHDL modules that work with other IPs, thus the modules are FPGA specific and they are managed in project mode. In the future the modules may also be categorised by different Vivado versions. | Yes | No | No |
 | `projects`    | Engineering project or board specific Vivado projects, that can be run on hardware. | Yes | Yes | Yes |
-| `template`    | Git-friendly Vivado project structure initialization template. | N/A | N/A | N/A |
+| `template`    | Git-friendly Vivado project structure initialization template. (However this folder cannot be managed with git since it is empty.) | N/A | N/A | N/A |
 | `.gitignore`  | gitignore file that tells git which files to ignore. | N/A | N/A | N/A |
 | `README.md`   | This readme. | N/A | N/A | N/A |
 
+> All Vivado projects that are managed in project mode is named `project` or `projectxxx`, considering that Windows OS limit the file path length to 260 characters.
+
 ### Basic Vivado Project Structure
 
 As listed above, modules and Vivado projects are managed in project mode, in which Vivado automatically manages the source files, constraints, IPs, run results, and so on. However, the directory structures are not friendly to revision control systems because they contain many redundant files that do not require revision control, such as synthesis and implementation results, and simulation intermediate files.
@@ -162,9 +146,10 @@ The table below outlines the git-friendly Vivado project structure. It is import
 | `ipi-bds`     | The IP Integrator block design source file (.bd), along with IP subdirectory including IP source files and output products. |
 | `testbenches` | Simulation test benches and stimulus files. |
 | `constraints` | All XDC constraint files and Tcl commands used as constraints. |
-| `project`     | Vivado projects, stored in subdirectories, with each subdirectory containing a single Vivado project **and the script used to recreate the associated Vivado project**. Note that **even if there is only one Vivado project, it should be included in a subdirectory so that the .gitignore file can correctly identify unwanted files**. |
+| `project`     | Vivado project directory. For single project mode, there is not project subdirectories needed; for multi project mode, each project is stored in a subdirectory containing a single Vivado project. It should be noted that the `.gitignore` is different for single project mode and multi project mode, because the directory depth are not the same. Therefore, `.gitignore` should always be checked before the first commit. |
 | `scripts`     | Run scripts used to compile the design including any pre and post scripts used when launching runs, along with any other custom scripts such as MATLAB scripts. |
 | `docs`        | Any design related documentations, specifications, reports, etc. |
+| `project.tcl` | The script used to recreate the associated Vivado project. |
 
 ## Demos
 
@@ -172,9 +157,13 @@ The table below outlines the git-friendly Vivado project structure. It is import
 
 1. Initialize project directory structure
 
-   Copy the `./template/` folder to target engineering project folder (`./projects/<engProj>/`). Then rename the folder to `<gitProj>`.
+   Copy the `./template` folder to target engineering project folder (`./projects/<engProj>`). Then rename the folder to `<gitProj>`.
 
-2. Create Vivado RTL Project named `<vivadoProj>` in `./projects/<engProj>/<gitProj>/project/` with option `Create project subdirectory` *checked* . The location of the Vivado project should be `./projects/<engProj>/<gitProj>/project/<vivadoProj>/`.
+2. Create Vivado RTL Project
+
+   - For **single project mode**, create Vivado RTL Project named `project` in `./projects/<engProj>/<gitProj>/project` with option `Create project subdirectory` *unchecked* . The location of the Vivado project should be `./projects/<engProj>/<gitProj>/project`.
+
+   - For **multi project mode**, create Vivado RTL Project named `<vivadoProj>` in `./projects/<engProj>/<gitProj>/project` with option `Create project subdirectory` *checked* . The location of the Vivado project should be `./projects/<engProj>/<gitProj>/project/<vivadoProj>`.
 
 3. Add RTL sources
 
@@ -186,7 +175,7 @@ The table below outlines the git-friendly Vivado project structure. It is import
 
    - **Add** existing IP (e.g. `./projects/<engProj>/<gitProj>/ip/<ipName>.xcix`) via **File -> Add Sources -> Add or create design sources -> Add Files** with option `Copy sources into project` *unchecked*.
 
-   - **Create** new IP. First, create Manage IP project with `IP location` at `./projects/<engProj>/<gitProj>/ip/`. Then, use the Manage IP project to customize and manage IP, and generate output products. Finally, add IP `./projects/<engProj>/<gitProj>/ip/<ipName>.xcix` via **ile -> Add Sources -> Add or create design sources -> Create File** to the Vivado project with option `Copy sources into project` *unchecked*. Several subdirectories can be created to group IPs with distinct functions.
+   - **Create** new IP. First, create Manage IP project with `IP location` at `./projects/<engProj>/<gitProj>/ip`. Then, use the Manage IP project to customize and manage IP, and generate output products. Finally, add IP `./projects/<engProj>/<gitProj>/ip/<ipName>.xcix` via **ile -> Add Sources -> Add or create design sources -> Create File** to the Vivado project with option `Copy sources into project` *unchecked*. Several subdirectories can be created to group IPs with distinct functions.
 
 5. Add IPI Block Design
 
@@ -216,7 +205,7 @@ The table below outlines the git-friendly Vivado project structure. It is import
 
 10. Generate Project Recreation Script
 
-    Create new script used to recreate the Vivado project via **File -> Project -> Write Tcl** with all checkbox set as default, set `Output File` to be `./projects/<engProj>/<gitProj>/project/<vivadoProj>.tcl`.
+    Create new script used to recreate the Vivado project via **File -> Project -> Write Tcl** with all checkbox set as default, set `Output File` to be `./projects/<engProj>/<gitProj>/project.tcl`.
 
 11. (Optional) Archive Project
 
@@ -228,16 +217,16 @@ The table below outlines the git-friendly Vivado project structure. It is import
 
 2. Source the Project Script
 
-   Open Vivado. In Tcl Console, change current working directory to `./projects/<engProj>/<gitProj>/project/`.
+   Open Vivado. In Tcl Console, change current working directory to `./projects/<engProj>/<gitProj>`.
 
    ``` tcl
-   cd ./projects/<engProj>/<gitProj>/project/
+   cd ./projects/<engProj>/<gitProj>
    ```
 
    Make sure all files included the script header are present, then source the script.
 
    ``` tcl
-   source ./<vivadoProj>.tcl
+   source ./project.tcl
    ```
 
    > Xilinx recommends sourcing the Tcl script from the same directory in which the project was created, to maintain the relative path between the current working directory and the source files.

projects/datalink_814/dl814_k7_cal_coarse/xsim.dir/work/work.rlx

@@ -1,5 +0,0 @@
-0.6
-2019.1
-Sep  4 2019
-09:47:21
-/home/josh/Workspace/vivado-git/projects/duifei/duifei_cal_coarse/rtl/system_top.v,1680765293,verilog,,,,system_top,,,,,,,,