One of the challenges I’ve faced in the ZPUDemos project is keeping the various targets up to date.\u00a0 When I add a peripheral to – for example – the SDBootstrap SOC, I have to modify each and every target’s project file to match, and it’s very easy to lose track of which ones have been updated and which ones haven’t.<\/p>\n
ZPUDemos currently supports no fewer than eight different target boards, and contains eleven different projects – that’s a lot of project files!<\/p>\n
In an attempt to make this more manageable, I’ve written some scripts to generate project files automatically, from a list of RTL files, and a board-specific template file.\u00a0 I’ve taken the opportunity to clean up the whole project, too, so the directory structure is more logical.
\nThe directories are now as follows:<\/p>\n
As well as these, each project has its own directory, containing the following:<\/p>\n
The root contains a top level Makefile which, if the ZPU toolchain is correctly installed will generate project files for every board and demo, build each demo’s firmware, and build the demo Apps.<\/p>\n
In writing the scripts to create the project files I learned quite a bit about bash scripting and Makefiles, including some subtleties of escaping and using shell variables within makefiles that I hadn’t encountered before.<\/p>\n
The Scripts directory contains two bash scripts and three makefiles.\u00a0 Of the latter, each project calls the makefile called standard.mak, which in turn calls quartus.mak to build project files for Altera-based boards, and ise.mak to build projects for Xilinx-based boards.\u00a0 The vendor-specific makefiles are called once for each board, in a for loop.<\/p>\n
The first subtlety I encountered was in getting this for loop to work within a makefile.\u00a0 It turns out a new shell is spawned for every command execute by a makefile, which means that no environment is preserved from line to line.\u00a0 Thus the obvious approach…<\/p>\n
for BOARD in $(BOARDS)\r\ndo\r\n do something\r\ndone<\/pre>\n…won’t work, because the four lines will be executed by different shells!\u00a0 To solve this, we use semi-colons after every command, and escape the newlines with a \\ character, to make the loop appear as a single line which will be executed by a single shell, like so:<\/p>\n
for BOARD in $(BOARDS); do \\\r\n do something; \\\r\ndone<\/pre>\nThe second subtlety is in how to pass the BOARD variable to the executed command.\u00a0 Normally you’d just use $BOARD – but if you do that, make will expand the variable, and since it’s not defined until the shell executes the for loop (and never defined in a way that’s visible to make), the parameter doesn’t reach the command.\u00a0 Instead we have to escape the $ with a second $ – so the command inside the loop becomes<\/p>\n
do something with $$BOARD; \\<\/pre>\nThe actual makefile looks like this:<\/p>\n
PROJECT=\r\nMANIFEST=manifest.rtl\r\nBOARDS_ALTERA = # Passed in from parent makefile\r\nBOARDS_XILINX = # Passed in from parent makefile\r\n\r\nALL: fpga\r\n\tmake -C Firmware\r\n\tfor BOARD in ${BOARDS_ALTERA}; do \\\r\n\t\tmake -f ..\/Scripts\/quartus.mak PROJECT=$(PROJECT) MANIFEST=$(MANIFEST) BOARD=$$BOARD; \\\r\n\tdone\r\n\tfor BOARD in ${BOARDS_XILINX}; do \\\r\n\t\tmake -f ..\/Scripts\/ise.mak PROJECT=$(PROJECT) MANIFEST=$(MANIFEST) BOARD=$$BOARD; \\\r\n\tdone\r\n\r\nclean:\r\n\tmake -C Firmware clean\r\n\tfor BOARD in ${BOARDS_ALTERA}; do \\\r\n\t\tmake -f ..\/Scripts\/quartus.mak PROJECT=$(PROJECT) MANIFEST=$(MANIFEST) BOARD=$$BOARD clean; \\\r\n\tdone\r\n\tfor BOARD in ${BOARDS_XILINX}; do \\\r\n\t\tmake -f ..\/Scripts\/quartus.mak PROJECT=$(PROJECT) MANIFEST=$(MANIFEST) BOARD=$$BOARD clean; \\\r\n\tdone\r\n\r\nfpga:\r\n\tmkdir fpga\r\n<\/pre>\nNote that we treat the two vendors separately.\u00a0 Generating a Quartus project file is very easy, since the .qsf file is just a text file that contains (among a great many other things) a list of files with no metadata beyond the file’s type – so we can copy a template .qsf and tack the project’s own files onto the end of it; this is what the expandtemplate_quartus.sh script does, like so:<\/p>\n
#!\/bin\/bash\r\n\r\ncat $1 | while read a; do\r\n\tb=${a,,}\r\n\tif [ \"${b: -4}\" = \".vhd\" ]; then\r\n\t\techo set_global_assignment -name VHDL_FILE ..\/..\/${a}\r\n\tfi\r\n\tif [ \"${b: -4}\" = \".qip\" ]; then\r\n\t\techo set_global_assignment -name QIP_FILE ..\/..\/${a}\r\n\tfi\r\n\tif [ \"${b: -2}\" = \".v\" ]; then\r\n\t\techo set_global_assignment -name VERILOG_FILE ..\/..\/${a}\r\n\tfi\r\ndone\r\n<\/pre>\nThis script loops through the manifest file, line by line, generating file entries for the .qsf file, detecting the file type as it goes. The script is bash-specific, and uses some constructs I’d not come across before until looking for a solution to this particular problem: Firstly, the b=${a,,}, which converts the current line to lower case which makes comparison easier. Secondly, the ${b: -4} which specifies a substring, the last four characters of the line, which we can then compare against “.vhd”, etc.<\/p>\n
Things aren’t so simple for Xilinx chips; the .xise file is also a text file but each file listed within also has some metadata which we can’t easily generate in a shell script. Luckily there’s a shell command as part of ISE, called xtclsh which will execute a tcl script, and we can use this to add files to a template project. The principle is the same – the difference is in the echo commands; instead of emitting file names directly into a project file, the expandtemplate.ise script builds a .tcl script which is subsequently executed using xtclsh. The tcl script, once generated, looks like this:<\/p>\n
project open RS232Bootstrap.xise\r\nxfile add \"..\/..\/..\/RTL\/RAM\/DualPortRAM.vhd\"\r\nxfile add \"..\/..\/..\/RTL\/RAM\/TwoWayCache.v\"\r\n...\r\nxfile add \"..\/..\/Firmware\/RS232Bootstrap_ROM.vhd\"\r\nproject save\r\nproject close\r\n<\/pre>\n","protected":false},"excerpt":{"rendered":"One of the challenges I’ve faced in the ZPUDemos project is keeping the various targets up to date.\u00a0 When I add a peripheral to – for example – the SDBootstrap SOC, I have to modify each and every target’s project … Continue reading