## 1. Project Overview & Quickstart (The-OpenROAD-Project/LICENSE) # LICENSE Open-source repository The-OpenROAD-Project/LICENSE ### Repository Details - **Repository:** [The-OpenROAD-Project/LICENSE](https://github.com/The-OpenROAD-Project/LICENSE) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (The-OpenROAD-Project/docs) ## File: README.md # OpenROAD Flow Documentation The source files that empower [https://docs.theopenroadproject.org](https://docs.theopenroadproject.org) ## How to contribute documentation 1. Fork the repo to your account 2. Install [Sphinx](http://www.sphinx-doc.org/en/master/) using `pip install -U Sphinx` 3. Install YouTube plugin using `pip install sphinxcontrib.youtube` 4. Build the documentation locally using `make html` 5. Read Sphinx [quickstart](http://www.sphinx-doc.org/en/master/usage/quickstart.html) to start editing the documentation. 6. Push to your own fork and then submit a pull request to this repo. ## Questions & Feedback Contact Abdelrahman Hosny (abdelrahman_hosny@brown.edu) --- ## File: .gitlab-ci.yml stages: - build build: stage: build script: - virtualenv .venv - source .venv/bin/activate - pip install sphinx - pip install sphinxcontrib.youtube - make html - cp -r build/html/* /var/www/html/docs tags: - openroad - flow - docs environment: name: docs url: https://docs.theopenroadproject.org --- ## File: source/cloud-flow.rst Cloud Flow =========== To get started using the cloud platform, watch our 3-minute video from the main contributor. It walks you through core features of the platform, with an example on a RISCV design. **Platform Link:** https://flow.theopenroadproject.org .. youtube:: 4WR-QgdsluA :width: 100% In addition to the video, you can directory jump to the web application and follow the step-by-step onboarding guide. Running On Your Own Design --------------------------- Design files (verilog) are stored in a Git repository. In order to prepare your design to be run on OpenROAD flow, follow the below steps: 1. Fork the `template repository`_ to your own GitHub account. 2. Rename the repo to the name of your design 3. Upload your design files in the design folder. 4. Edit the `openroad-flow.yml`. Comments in the file will help you follow the steps. 5. Go to https://flow.theopenroadproject.org. After logging in (or creating an account for the first time), click on the *My Designs* tab on the left. Then, click `Import Design` and enter the name of the design and the GitHub repository link. 6. Run the flow by clicking on `Run on latest version`. What is openroad-flow.yml file? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The `openroad-flow.yml` file tells OpenROAD cloud runners what configurations and parameters to use, given the input design. For example, what software packages to use and what libraries to build for. Example ^^^^^^^^ To see an example of a pre-configured repository, have a look at the `RISCV design`_ repository (which is the example we used in the Getting Started section). .. _`template repository`: https://github.com/The-OpenROAD-Project/openroad-template-design .. _`RISCV design`: https://github.com/The-OpenROAD-Project/cloud-flow-example-riscv Deploying OpenROAD On Private Cloud ------------------------------------ Although the publicly available platform enables our research and offers ease-of-use and latest improvements to users around the world, OpenROAD flow can be independently deployed on a private cloud infrastructure. Platform Architecture ^^^^^^^^^^^^^^^^^^^^^^ .. image:: /.static/img/architecture.svg :width: 100% Deployment Configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^ We list a few important configurations for the different components of the platform here. Storage """"""" Nginx is used to serve flow output files. The following configuration allow access for only the link visible to the user:: location ~ ^/output/(.+)/openroad { autoindex on; autoindex_exact_size off; autoindex_localtime on; } Real-time Database """"""""""""""""""" `Rethinkdb`_ is used to provide real-time monitoring functionality. After deploying, maintain the URL of the database and the username/password for the admin user. It would be used later in both the `flow runner` and the `web application`. .. _`Rethinkdb`: https://www.rethinkdb.com/ Flow Runner """""""""""" The flow runner is deployed with `Docker Compose`_. To build: 1. Copy the `.env-example` file to a new file in the same directory and name it `.env` 2. Modify the contents of `.env` file to include the following configurations .env:: # General DJANGO_SECRET_KEY= DJANGO_ALLOWED_HOSTS=* LOAD_DATA=off BASE_URL=localhost:8000 # Debug & Logging DJANGO_DEBUG=False # Database POSTGRES_USER= POSTGRES_PASSWORD= POSTGRES_DB= # Designs STORAGE_DIR=/storage FLOW_TEMPLATE_DIR= REPOS_TMP_DIR=/tmp/repos # Storage URL STORAGE_URL= # OpenROAD Frontend OPENROAD_URL=/runner-listener # Celery Stuff BROKER_URL=redis://broker CELERY_RESULT_BACKEND=redis://broker # Live Monitoring DB LIVE_MONITORING_URL= LIVE_MONITORING_PASSWORD= 3. `docker-compose build` 4. `docker-compose up -d` .. _`Docker Compose`: https://docs.docker.com/compose/ Email Service """"""""""""""" Subscribe to any email service provider (e.g. AWS Simple Email Service), and maintain the credentials for the records to be used below. Web Application """""""""""""""" The flow runner is deployed with `Docker Compose`_. To build: 1. Copy the `.env-example` file to a new file in the same directory and name it `.env` 2. Modify the contents of `.env` file to include the following configurations .env:: # General DJANGO_SECRET_KEY= DJANGO_ALLOWED_HOSTS=* LOAD_DATA=off BASE_URL=localhost:8000 # Debug & Logging DJANGO_DEBUG=False # Admin ADMIN_NAME= ADMIN_EMAIL= # Database POSTGRES_USER= POSTGRES_PASSWORD= POSTGRES_DB= # Designs DESIGNS_DIR=/designs VALIDATION_TMP_DIR=/validation_tmp # Emails EMAIL_HOST= EMAIL_HOST_USER= EMAIL_HOST_PASSWORD= EMAIL_PORT= EMAIL_USE_SSL= # Celery Stuff BROKER_URL=redis://broker CELERY_RESULT_BACKEND=redis://broker # Runner RUNNER_URL= 3. `docker-compose build` 4. `docker-compose up -d` .. _`Docker Compose`: https://docs.docker.com/compose/ --- ## File: source/contribution-guide.rst Contribution Guide =================== The OpenROAD project is committed to the open source community. We welcome contributions from all groups. Whether you are a professional, a tech hobbiest or a student working within the EDA field, we would like to collaborate with you. How to Start? ---------------- The first step is to dig into the tools that build up the OpenROAD infrastructure. As soon as you get yourself familiar with them, find your interst in a tool(s) that you would like to contribute to. Reach out directly to the current maintainers of the tool and initiate discuss the best possible way to contribute. Most of the time, maintainers keep track of future features and/or algorithm improvments on the roadmap of the tool. To contact maintainers, refer to the :ref:`tools-page` page for more information about individual tools. Coding Guidelines ------------------ In order to maintain our codebase, we have identified some coding standards and practices to follow if you want to contribute to the cloud infrastructure. Commenting & Documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^ You should write comments for your code especially where there is a flow logic. When the text is that obvious, it's not productive to repeat it within comments. You should write doc comments inside methods and functions describing inputs and outputs of that procedure. Indentation ^^^^^^^^^^^^ We adopt the following conventions: - Indentation must be with **SPACES** not tabs. The idea behind this is that tabs may change between different OSes. It may be configured as one tab = 4 spaces on Linux and configured with 8 spaces on Windows. Using spaces will make the source code readable in any platform. - Python, JS, C/C++: should be with **4 SPACES** indentation. - HTML and JSON: should be with **2 SPACES** indentation Blocks ^^^^^^^^ We adopt the following style:: if(x > 1) { } Naming Conventions ^^^^^^^^^^^^^^^^^^^ Variables should be descriptive and contain one or more words. It should be meaningful. We avoid names such as lst, x, y ... etc. There are two ways of naming; camelCase or underscores. Below are how we suggest naming for each language: - JavaScript => camelCase (Variables, Functions, Methods). - Python => underscores (Variables, Functions, Methods). - Classes use a capital letter for each word such as `RuleType`. - Classes **must** be singular. - We favor readability over brevity. - We Avoid using identifiers that conflict with keywords of widely used programming languages. Imports Order -------------- We group imports such that: - Built-in packages are on the top and first section. - Framework related packages comes in the second section. - Your packages, classes and modules comes in the third section. Operators and Line length ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Operators should be surrounded by spaces such that `variables = 12` - No line of code should exceed **79 characters**. Our eyes are more comfortable when reading tall and narrow columns of text. This is precisely the reason why newspaper articles are organized in columns. DRY & DIE Principle ^^^^^^^^^^^^^^^^^^^^^^ DRY stands for *Don't Repeat Yourself*. Also, known as DIE: *Duplication Is Evil*. The principle states that: **Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.** File and Folder Organization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Technically, we could write an entire application code within a single file. But that would prove to be a nightmare to read and maintain. As applications grow, the file also becomes huge and unmaintainable. **We always try to minimize lines of code per file.** No hard-coding ^^^^^^^^^^^^^^^^ We do not hard-code anything that can be changed in the future, rather we try to put it in a separate setting or constant file. - No hard-code URLs. - No hard-code DB connection configuration. - No hard-code email configuration. --- ## File: source/flow-definition.rst Flow Definition =============== Refer to the below document for details on the flow stages, and tools used in each one. .. raw:: html --- ## File: source/getting-started.rst Getting Started =============== This section provides a user guide into using OpenROAD tools and the automated flow. Using Pre-built Binaries ------------------------- To be completed Build On Your Machine ---------------------- To be completed --- ## File: source/index.rst .. OpenROAD Flow documentation master file, created by sphinx-quickstart on Mon Dec 17 14:42:20 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. The OpenROAD Project Documentation =================================== `The OpenROAD Project`_ aims at providing a 24-hour, no-human-in-the-loop layout design for SoC, package and PCB with no Power-Performance-Area (PPA) loss. This page contains all related documentation for the different tools being developed under OpenROAD, in addition to RTL-to- GDS flow automation. Contents ======== .. toctree:: :maxdepth: 3 getting-started tools cloud-flow contribution-guide Project Questions ================== Contact Prof. Andrew B. Kahng at abk-openroad@eng.ucsd.edu .. _`OpenROAD Flow`: https://flow.theopenroadproject.org/ .. _`The OpenROAD Project`: https://theopenroadproject.org/ --- ## File: source/tools.rst .. _tools-page: Tools ====== This section provides general information about tools being maintained by different OpenROAD teams. For more detailed documentation and updates on the tools, refer to the correspnding GitHub repository. Static Timing Analysis ----------------------- To be completed Logic Synthesis ---------------- To be completed Floor Planning ---------------- To be completed Placement ---------- To be completed Routing --------- To be completed Clock Tree Synthesis --------------------- To be completed