Использование пакета Quartus II в командной строке

Введение

Зачем использовать quartus в командной строке? Несколько лет назад я не смог бы ответить на этот вопрос. Но сейчас, когда количество проектов непревывно растет и все они используют общую библиотеку, я в полной мере оценил плюсы использования quartus в командной строке:

1. чтобы перекомпилировать все проекты, не нужно открывать несколько окон quartus и по очереди запускать компиляцию
2. не нужно дожидаться окончания каждой компиляции и потом "вручную" просматривать результаты
3. не нужно нажимать кучу кнопок для того, чтобы в сотый раз за день переконвертировать прошивку из одного формата в другой
4. стала доступна возможность проводить ночную сборку: раз в сутки все проекты собираются автоматически.

В этой статье я бы хотел поделиться своим опытом с разработчиками ПЛИС, которые используют пакет quartus. Особенно интересно это может быть тем, кто "ведет" большое количество проектов и хочет максимально автоматизировать неизбежные рутинные процессы.

Нужно сразу оговориться, что некоторые подсистемы quartus практически невозможно использовать в командной строке. Например, SignalTap^? или временной симулятор. Ведь при их использовании необходим постоянный визуальный контроль происходящего на экране.

Суть использования quartus в командной строке заключается в следующем. Большинство операций, выполняемых в среде quartus, представлено в виде отдельных программ, которые можно запускать в командной строке с определенными ключами. Каждая из этих программ использует определенные файлы в качестве входных и в ходе выполнения выводит информацию в соответствующие файлы и на экран. Поэтому статья начинается с краткого описания файлов, используемых подпрограммами quartus. Далее будут рассмотрены сами подпрограммы и способы автоматизации компиляции простого проекта.

Файлы, используемые подпрограммами quartus

Подпрограммы используют большое количество типов файлов. Мы рассмотрим только наиболее важные и полезные для работы в командной строке.

qsf - Quartus Settings File

Пожалуй, самый важный файл. Он хранит все настройки проекта в простом текстовом формате. Это единственный файл, необходимый для компиляции, кроме файлов описания схемы (tdf, bdf, ...). Как правило, он содержит следующие настройки:

• головной файл проекта (например my.tdf) и остальные файлы, использованные в проекте
• название проекта (my)
• список пользовательских библиотек
• микросхему, в которой должен быть разведен проект
• распиновку проекта и т.п.

Например:

set_global_assignment -name AHDL_FILE my.tdf
set_global_assignment -name INCLUDE_FILE lib.inc

# Analysis & Synthesis Assignments
# ================================
set_global_assignment -name FAMILY "MAX II"
set_global_assignment -name TOP_LEVEL_ENTITY my
set_global_assignment -name USER_LIBRARIES "D:\\work\\lib

# Fitter Assignments
# ==================
set_global_assignment -name DEVICE EPM570GT100C5
set_global_assignment -name ERROR_CHECK_FREQUENCY_DIVISOR 1

Файл qsf довольно хорошо описан в help quartus'a, поэтому я ограничусь здесь приведенной информацией. Кроме встроенной поддержки в quartus, читатель может самостоятельно изучить настройки, которые хранятся в этом файле, создав и настроив проект в оболочке quartus.

rpt - Report File

Файл отчета. Файлы отчета создаются на каждом этапе компиляции. После mapping'а создается файл .map.rpt, после fitter'a создается файл .fit.rpt и т.д. Эти файлы содержат полную информацию о пройденном этапе. Кроме этих файлов после компиляции создается файл .flow.rpt, который заполняется на каждом этапе компиляции и содержит информацию о всем процессе компиляции и его результатах. Например, после полной компиляции (map + fit + asm) в файле .flow.rpt можно увидеть:

+--------------------------------------------------------------------+
; Flow Summary                                                       ;
+-------------------------+------------------------------------------+
; Flow Status             ; Successful - Fri Oct 27 13:24:01 2006    ;
; Quartus II Version      ; 6.0 Build 178 04/27/2006 SJ Full Version ;
; Revision Name           ; my                                       ;
; Top-level Entity Name   ; my                                       ;
; Family                  ; Cyclone                                  ;
; Device                  ; EP1C6T144C8                              ;
; Timing Models           ; Final                                    ;
; Met timing requirements ; N/A                                      ;
; Total logic elements    ; 4,658 / 5,980 ( 78 % )                   ;
; Total pins              ; 57 / 98 ( 58 % )                         ;
; Total virtual pins      ; 0                                        ;
; Total memory bits       ; 20,080 / 92,160 ( 22 % )                 ;
; Total PLLs              ; 2 / 2 ( 100 % )                          ;
+-------------------------+------------------------------------------+

+-------------------------------------+
; Flow Elapsed Time                   ;
+----------------------+--------------+
; Module Name          ; Elapsed Time ;
+----------------------+--------------+
; Analysis & Synthesis ; 00:02:35     ;
; Fitter               ; 00:03:38     ;
; Assembler            ; 00:00:04     ;
; Total                ; 00:06:17     ;
+----------------------+--------------+

qmsg - Quartus Messages File

Файл, в который подпрограммы quartus выводят сообщения. Они хранятся в поддиректории db/ проекта и имеют расширения аналогично rpt - файлам: map.qmsg, asm.qmsg, fit.qmsg, ... В нашем случае эти файлы удобны для просмотра сообщений об ошибках компиляции. Формат этих файлов не удобен для чтения, но при использовании строкового процессора этот недостаток не играет большой роли.

Например, для вывода на консоль всех ошибок, возникших на этапе анализа и синтеза проекта my можно выполнить такую команду (доступно и в Windows):

cat db/my.map.qmsg | grep Error | sed 's/" "/\n/g' | sed 's/} {/\n/g' | grep -e Error: -e Text

pin - Pin-Out File

Файл, в котором в текстовом виде хранится вся распиновка проекта. Создается fitter'ом при компиляции проекта.

summary

Файл, в который подпрограммы quartus выводят окончательный результат своего выполнения. Имена - аналогичны rpt файлам: .fit.summary, .map.summary. Например:

Analysis & Synthesis Status : Successful - Fri Oct 27 13:20:14 2006
Quartus II Version : 6.0 Build 178 04/27/2006 SJ Full Version
Revision Name : my
Top-level Entity Name : my
Family : Cyclone
Total logic elements : 5,737
Total pins : 57
Total virtual pins : 0
Total memory bits : 20,080
Total PLLs : 2

Подпрограммы пакета quartus

Вот неполный список подпрограмм, входящих в состав пакета quartus:

• quartus_map - analysis & synthesys
• quartus_fit - fitter
• quartus_asm - assembler
• quartus_cpf - convert programming files
• quartus_pgm - programmer

Чтобы запустить одну из перечисленных подпрограмм, нужно, чтобы переменная окружения PATH содержала путь к директории исполняемых файлов пакета quartus. Например, в среде Windows: c:\program files\altera\quartus\bin. В среде linux - /opt/altera/quartus/bin.

Каждая из этих программ описана в help'e quartus'a. Кроме того, вызвав каждую программу с ключом '-h' можно получить справку прямо в командной строке. Например:

$ quartus_map -h
Quartus II Assembler
Version 6.0 Build 178 04/27/2006 SJ Full Version
Copyright (C) 1991-2006 Altera Corporation

Usage:
------
quartus_asm [-h | --help[=<option|topic>] | -v]
quartus_asm <project name> [<options>]

Description:
------------
Options:
--------
        -f <argument file>
        -c <revision name> | --rev=<revision name>
        --lower_priority
        --read_settings_files[=on|off]
        --set=<assignment=value>
        --write_settings_files[=on|off]

Help Topics:
------------
        arguments
        makefiles
        return_codes

For more information on specific options, use --help=<option|topic>.

У каждой программы есть ключ --lower_priority, который позволяет запускать программу с пониженным приоритетом. Этот ключ полезно использовать на не очень мощных компьютерах, чтобы процедура компиляции не мешала работе за компьютером.

quartus_map

Analysis & Synthesys - первый этап компиляции проекта, анализ и синтез схемы. Для запуска анализа и синтеза необходимо указать как минимум 2 ключа:

$ quartus_map my -c my

где my - имя проекта, для которого есть файл my.qsf.

Кроме анализа и синтеза эта программа может выполнять еще несколько функций. Рассмотрим несколько таких функций подробнее.

Анализ 1 файла проекта

$ quartus_map my --analyze_file=my.tdf

Анализ проекта

$ quartus_map my --analyze_project

Создание include-файла

$ quartus_map my --generate_inc_file=my.tdf

После выполнения этой команды для файла my.tdf будет создан файл my.inc.

quartus_fit

Fitter - второй этап компиляции, разводка схемы в кристалле. Запускается аналогично quartus_map:

$ quartus_fit my -c my

quartus_asm

Assembler - третий этап компиляции. Генерация файла-прошивки. После выполнения этой программы появятся файлы .pof, .sof для прошивки микросхемы. Запускается quartus_asm аналогично quartus_map & quartus_fit.

quartus_cpf

Convert Programming File - конвертирование прошивок. Эта программа позволяет выполнить конверсию прошивок .pof & .sof в другие форматы. Рассмотрим использование quartus_cpf на примере конверсии прошивки my.pof в my.rpd:

$ quartus_cpf -c my.pof my.rpd

После выполнения этой команды появится файл my.rpd (raw programming data). Аналогично можно выполнить конверсию прошивки в другой формат, например .rbf.

quartus_pgm

Программатор. Запуск этой команды позволяет запрограммировать микросхему, используя один из поддерживаемых кабелей, например ByteBlasterMV^?.

Команда quartus_pgm с ключом -a позволяет посмотреть список микросхем доступных для прошивки (в листинге приведен пример выполнения quartus_pgm в системе linux):

$ quartus_pgm -a
Info: Command: quartus_pgm -a
Info: Using programming cable "ByteBlasterMV [/dev/byteblaster0]"
1) ByteBlasterMV [/dev/byteblaster0]
  020820DD   EP1C6
  170640DD   EPM3064A/7064AE

Info: Quartus II Programmer was successful. 0 errors, 0 warnings
    Info: Processing ended: Thu Mar  9 11:15:10 2006
    Info: Elapsed time: 00:00:01

Как видно из листинга, к цепи JTAG поключены 2 микросхемы:

1. EP1C6 (Cyclone)
2. EPM3064A (Max3000)

Чтобы запрограммировать микросхему Cyclone, нужно запустить команду:

$ quartus_pgm -o p\;test_decoder.sof\@1 -m JTAG
Info: Command: quartus_pgm -o p;test_decoder.sof@1 -m JTAG
Info: Using programming cable "ByteBlasterMV [/dev/byteblaster0]"
Info: Started Programmer operation at Thu Mar  9 11:24:11 2006
Info: Configuring device index 1
Info: Device 1 contains JTAG ID code 0x020820DD
Info: Configuration succeeded -- 1 device(s) configured
Info: Successfully performed operation(s)
Info: Ended Programmer operation at Thu Mar  9 11:24:14 2006
Info: Quartus II Programmer was successful. 0 errors, 0 warnings
    Info: Processing ended: Thu Mar  9 11:24:14 2006
    Info: Elapsed time: 00:00:04

, где:

• строка

  -o p\;my.sof\@1

  означает, что файл (my.sof) должен быть запрограммирован (p) в первую (@1) микросхему из тех, что подключены к JTAG цепи.
• строка

  -m JTAG

  означает, что режим програмирования - JTAG.

Использование утилиты make

Итак, мы кратко (в необходимом для примера объеме) рассмотрели программы пакета quartus. Каким образом можно автоматизировать компиляцию и сопуствующие процедуры, используя эти программы? Для этого можно использовать утилиту make, хорошо знакомую пользователям linux [1,2].

Суть использования make проста. В директории, в которой находится проект, должен находиться файл с названием Makefile, в котором прописаны правила выполнения какой-либо операции. Правило может запускать одну или несколько программ (команд). Кроме правил, в Makefile можно описать зависимости между файлами и правилами. При этом отслеживание изменений файлов будет выполнять make: при изменении файла, от которого зависит другой файл, зависимый файл будет обновлен прописанной в Makefile'e командой. Например, если в Makefile прописано правило rule, то для выполнения этого правила нужно вызвать

$ make rule

Правилу можно передавать параметры при вызове make:

$ make rule PARAM=1

Утилиту make можно использовать и в операционной системе windows. Для этого нужно установить систему cygwin [3], включающую в себя - помимо самой make - большое количество GNU-утилит, которые могут помочь обработать данные, выводимые программами пакета quartus. Пример таких GNU-утилит приведен в описании файлов *qmsg выше.

Для автоматизации работы с quartus могут потребоваться следующие программы пакета cygwin: cd, ls, make, cat, grep, tee, sed.

Пример: компиляция проекта с использованием make

Рассмотрим пример совместного использования подпрограмм quartus и утилиты make. Для этого создадим примитивный тестовый проект "test". Проект после компиляции будет размещаться в микросхеме EP1C6T144C8. И допустим, что для прошивки прибора используется файл test.rpd, который получается из test.pof путем конвертирования.

Тестовый проект: test.tdf + test.qsf + Makefile

Вот как выглядит файл test.qsf для данного проекта:

# Project-Wide Assignments
# ========================
set_global_assignment -name AHDL_FILE test.tdf

# Analysis & Synthesis Assignments
# ================================
set_global_assignment -name FAMILY "Cyclone"
set_global_assignment -name TOP_LEVEL_ENTITY test

# Fitter Assignments
# ==================
set_global_assignment -name DEVICE EP1C6T144C8

Программа test.tdf примитивная:

SUBDESIGN test
(
  a, b, c : INPUT;
  d, e, f : OUTPUT;
)
BEGIN
 d = a & b & c;
 e = a;
 f = !b;
END;

Теперь самое главное - Makefile:

PROJECT = test # название нашего проекта
SOURCES = $(PROJECT).tdf # исходный текст проекта, когда этот текст изменяется 
                # должна происходить перекомпиляция проекта

Главная цель сборки нашего проекта - файл test.rpd. Для получения этого файла необходим файл test.pof. Поэтому наш Makefile должен содержать зависимость файла test.rpd от test.pof. А для получения файла test.pof необходимы два файла test.tdf и test.qsf. При любом изменении этих файлов файл test.pof должен создаваться заново.

# когда файл rpd создан, выводим результат компиляции из файла flow.rpt
all: $(PROJECT).rpd
        cat $(PROJECT).flow.rpt | grep -A 16 -B 1 \;\ Flow\ Summary

# зависимость pof от rpd
$(PROJECT).rpd: $(PROJECT).pof
        quartus_cpf -c $< $@

# pof файл зависит от исходных текстов и файла настройки
$(PROJECT).pof: $(SOURCES) $(PROJECT).qsf
        quartus_map $(PROJECT) -c $(PROJECT) 
        quartus_fit $(PROJECT) -c $(PROJECT)
        quartus_asm $(PROJECT) -c $(PROJECT)

Для очистки директории проекта от всех файлов, кроме исходников и настроек, Makefile содержит правило clean.

clean:
        rm -rf $(PROJECT).rpd $(PROJECT)*.rpt $(PROJECT).pof
        rm -rf $(PROJECT)*.pin $(PROJECT)*.qpf  
        rm -rf db/$(PROJECT)* 
        rm -rf $(PROJECT)*.summary $(PROJECT)*smsg

Запускаем

Итак, мы создали простой проект, состоящий из двух файлов: test.qsf и test.tdf. Для сборки проекта и получения файла test.rpd мы имеем Makefile. Что нужно, чтобы провести компиляцию? Ответ прост: нужно запустить make в директории, где лежат указанные три файла.

$ make

Если компиляция пройдет успешно, то в результате выполнения команды будет получен такой результат:

+--------------------------------------------------------------------+
; Flow Summary                                                       ;
+-------------------------+------------------------------------------+
; Flow Status             ; Successful - Tue Oct 31 18:19:57 2006    ;
; Quartus II Version      ; 6.0 Build 178 04/27/2006 SJ Full Version ;
; Revision Name           ; test                                     ;
; Top-level Entity Name   ; test                                     ;
; Family                  ; Cyclone                                  ;
; Device                  ; EP1C6T144C8                              ;
; Timing Models           ; Final                                    ;
; Met timing requirements ; N/A                                      ;
; Total logic elements    ; 1 / 5,980 ( < 1 % )                      ;
; Total pins              ; 6 / 98 ( 6 % )                           ;
; Total virtual pins      ; 0                                        ;
; Total memory bits       ; 0 / 92,160 ( 0 % )                       ;
; Total PLLs              ; 0 / 2 ( 0 % )                            ;
+-------------------------+------------------------------------------+

В директории будет лежать файл test.rpd. Всю необходимую информацию о скомпилированном проекте, распиновке и т.п. можно узнать из вышеописанных файлов, которые появятся в директории после компиляции.

Что необходимо сделать, чтобы очистить директорию от файлов отчета? Запустить:

$ make clean

rm -rf test.rpd test*.rpt test.pof
rm -rf test*.pin test*.qpf  
rm -rf db/test* 
rm -rf test*.summary test*smsg

Расширение возможностей

Допустим, что для файла test.tdf нужно создавать include файл test.inc. Для этого в Makefile нужно добавить зависимость:

%.inc: %.tdf
        quartus_map $(PROJECT) --generate_inc_file=$<

Тогда, вызвав в командной строке:

$ make test.inc

quartus_map test --generate_inc_file=test.tdf
Info: Command: quartus_map test --generate_inc_file=test.tdf
Info: Quartus II Analysis & Synthesis was successful. 0 errors, 0 warnings
    Info: Processing ended: Tue Oct 31 18:27:00 2006
    Info: Elapsed time: 00:00:01

Мы получим test.inc в директории проекта. Здесь необходимо заметить, что при увеличении количества файлов в проекте описанная зависимость не будет изменяться, поскольку она описывает "закон преобразования файлов".

Заключение

Большинство рутинных операций, которые многие пользователи quartus выполняют в графической оболочке, доступны для выполнения в командной строке в виде подпрограмм. Использование утилиты make делает использование этих подпрограмм прозрачным, удобным и интеллектуальным. В чем плюсы такого подхода? Их несколько:

• отсутствие графической оболочки: это облегчает процесс сборки большого количества проектов
• make позволяет автоматически отслеживать построенные зависимости и обновлять необходимые файлы
• make позволяет автоматически после успешной сборки проекта конвертировать файлы прошивок
• у разработчика появляется больше времени на творчество

Надеюсь, что данная статья поможет облегчить и без того не легкий труд аппаратчиков - плисоводов

Павел Курочкин, НТЦ Метротек, Санкт-Петербург.

Литература, ссылки

1. Перевод Makefile Mini HOWTO (make), http://www.opennet.ru/base/dev/mini_make.txt.html
2. Мини-руководство по созданию Makefile-ов, http://gazette.linux.ru.net/lg83/heriyanto.html
3. http://www.cygwin.com

Тексты тестового проекта

• Makefile: Makefile тестового проекта
• test.qsf: Quartus Settings File для тестового проекта
• test.tdf: Text Design File тестового проекта