diff --git a/fpga/lib/psmake/.gitignore b/fpga/lib/psmake/.gitignore new file mode 100644 index 000000000..c976eaec8 --- /dev/null +++ b/fpga/lib/psmake/.gitignore @@ -0,0 +1,5 @@ +# generic intermediate and editor backup files +*.swp +*.~ +.#* +*~ diff --git a/fpga/lib/psmake/LICENSE.txt b/fpga/lib/psmake/LICENSE.txt new file mode 100644 index 000000000..f433b1a53 --- /dev/null +++ b/fpga/lib/psmake/LICENSE.txt @@ -0,0 +1,177 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS diff --git a/fpga/lib/psmake/README.md b/fpga/lib/psmake/README.md new file mode 100644 index 000000000..b53591824 --- /dev/null +++ b/fpga/lib/psmake/README.md @@ -0,0 +1,1064 @@ + + +# Processing System Makefiles + +This repository bundles convenience Makefiles for developing software targeting +the embedded processors of SoC FPGAs or soft cores embedded in a programmable +logic (PL) design – so called Processing Systems (PS). It features the +following components: + +* PetaLinux wrapper Makefile +* Xilinx Software Development Kit (XSDK) convenience Makefile +* Xilinx Vitis convenience Makefile + + +## PetaLinux Wrapper Makefile + +`petalinux.mk` is a Makefile for PetaLinux projects. It acts as convenience +wrapper script around the PetaLinux toolchain and adds additional +functionality. + + +### Supported Platforms + +PetaLinux is supported from v2018.1 to v2019.1 (i.e. the last four releases). +The Makefile should run on all underlying OSs supported by PetaLinux; however +testing is only conducted on Ubuntu 18.04 LTS (Bionic Beaver) as of now. + + +### Setup + +In your PetaLinux project directory, create a symlink named `Makefile` to the +`petalinux.mk` file: + + $ ln -s /petalinux.mk Makefile + +Then, execute: + + $ make HDF= + +to import a Hardware Description File (HDF) or a XSA file and build the +PetaLinux project. + + +### Usage + +The following Makefile targets are provided: + +`gethdf` +: Initialize the project with a Hardware Description File (HDF) or a XSA +file. You must provide a HDF or XSA file via the `HDF` variable. + +`config` +: Configure system-level options. + +`config-kernel` +: Configure the Linux kernel. + +`config-rootfs` +: Configure the root filesystem. + +`build` (default) +: Build the system. + +`sdk` +: Build the Software Development Kit (SDK). + +`package-boot` +: Package boot image. You can provide different binaries from the default ones +for bitstream, FSBL, ATF, PMU firmware and U-Boot via the `BIT`, `FSBL`, `ATF`, +`PMUFW` and `UBOOT` variables, respectively. To skip packaging bitstream, FSBL, +ATF or PMU firmware, set the respective variable to `no`. Additional boot +arguments can be specified with `BOOT_ARG_EXTRA`; run `petalinux-package --boot +--help` for a list of options. The output path can be changed with the `BOOT` +variable. + +`package-prebuilt` +: Copy built artifacts to pre-built directory. + +`package-bsp` +: Package Board Support Package (BSP). The BSP file name must be given with the +`BSP` variable. + +`dts` +: Decompile the device tree. + +`reset-jtag` +: Reset board via JTAG. The hardware server URL must be provided via the +`HW_SERVER_URL` variable. + +`boot-jtag-u-boot` +: Boot board into U-Boot via JTAG. The hardware server URL must be provided via +the `HW_SERVER_URL` variable. + +`boot-jtag-kernel` +: Boot board and upload Linux kernel via JTAG. The hardware server URL must be +provided via the `HW_SERVER_URL` variable. + +`boot-jtag-psinit-uboot` +: Boot board into U-Boot via JTAG, but run `ps*_init.tcl` script instead of +downloading and running FSBL. This can be inconvenient if the FSBL is doing +boot mode specific jobs, e.g. loading a boot image from QSPI flash memory when +in QSPI boot mode, although one does NOT want the FSBL to do that. The +hardware server URL must be provided via the `HW_SERVER_URL` variable. Only +available on Zynq-7000 as of now. + +`boot-qemu` +: Boot into QEMU. + +`flash-boot` +: Flash boot image onto board via JTAG. The hardware server URL must be +provided via the `HW_SERVER_URL` variable. The flash type must be specified +with the `FLASH_TYPE` variable if it deviates from the default. The FSBL used +for flashing, the boot image and the flash offset can be changed with the +`FSBL_ELF`, `BOOT_BIN` and `BOOT_BIN_OFF` variables respectively. + +`flash-kernel` +: Flash kernel image onto board via JTAG. The hardware server URL must be +provided via the `HW_SERVER_URL` variable. The flash type must be specified +with the `FLASH_TYPE` variable if it deviates from the default. The FSBL used +for flashing, the kernel image and the flash offset can be changed with the +`FSBL_ELF`, `KERNEL_IMG` and `KERNEL_IMG_OFF` variables respectively. + +`flash` +: Flash boot and kernel image onto board via JTAG. + +`mrproper` +: Clean all build artifacts. If this target is invoked with `CLEAN_HDF=1`, the +HDF is deleted as well (i.e. all files in folder `project-spec/hw-description` +except file `metadata`). + + +### Networkless Builds + +In some circumstances, it might be desirable to perform builds without any +network access; notably, +- to provide long-term reproducibility in case of package sources being + not available online anymore. +- to perform builds in corporate environments with restricted internet access. + + +#### Setup + +A number of PetaLinux configuration options have to be changed to enable +networkless builds; run `make config` and, + +- in Yocto Settings -> Add pre-mirror url, set the `pre-mirror url path` to + your local source mirror, e.g `file://${PROOT}/source-mirror` (or set + `CONFIG_PRE_MIRROR_URL` in `project-spec/configs/config`). +- in Yocto Settings, uncheck `Enable Network sstate feeds` + (or unset `CONFIG_YOCTO_NETWORK_SSTATE_FEEDS` in + `project-spec/configs/config`). +- in Yocto Settings, check `Enable BB NO NETWORK` + (or set `CONFIG_YOCTO_BB_NO_NETWORK` in `project-spec/configs/config`). + + +#### Usage + +All sources that are not part of the PetaLinux installation will be stored in +the local source mirror. To update the source mirror, run: + + $ make UPDATE_MIRROR=1 + +The local source mirror must be updated each and every time a package is added +to the image. Notably, sources are only added to the source mirror, but never +removed; so multiple revisions or entirely different PetaLinux projects can +share a mirror. Cleanup of the source mirror should be performed manually when +required. + + +### Image Buildinfo + +Add the following snippet to `project-spec/meta-user/conf/petalinuxbsp.conf` in +order to write build information to the target filesystem on `/etc/build`: + + INHERIT += "image-buildinfo" + IMAGE_BUILDINFO_VARS_append = " DATETIME" + +`/etc/build` contains the build configuration as defined by the list of BitBake +variables in `IMAGE_BUILINFO_VARS` and the Git revisions (branch/tag, commit ID +and dirty flag) of all Yocto layers. + +Appending variables to `IMAGE_BUILDINFO_VARS` is optional; however the build +time `DATETIME` is recommended. A list of common variables can be found in the +[Variables Glossary of the Yocto Reference +Manual](https://docs.yoctoproject.org/ref-manual/variables.html). + + +### Image Version + +It is recommended to add image versioning information via +[os-release](https://www.freedesktop.org/software/systemd/man/os-release.html) +using the `IMAGE_ID` and `IMAGE_VERSION` variables. + +Add the `os-release` package to your root filesystem and extend it via +`project-spec/meta-user/recipes-core/os-release/os-release.bbappend`. The +following example will add the variables `BUILD_ID` (build timestamp), +`IMAGE_ID` and `IMAGE_VERSION` to `/etc/os-release` on the target filesystem, +identifying the image as `mle-example` and reading the semantic version from +`version.txt` in the PetaLinux root directory. + + OS_RELEASE_FIELDS += "BUILD_ID IMAGE_ID IMAGE_VERSION" + + IMAGE_ID = "mle-example" + + python do_compile_prepend () { + with open(d.getVar("TOPDIR") + "/../version.txt") as f: + major, minor, patch = f.readline().rstrip().split(".") + + d.setVar("MAJOR_VERSION", major) + d.setVar("MINOR_VERSION", minor) + d.setVar("PATCH_VERSION", patch) + d.setVar("IMAGE_VERSION", "{}.{}.{}".format(major, minor, patch)) + } + + +### Open Source License Compliance + +There are three main areas of concern for [open source license +compliance](http://docs.yoctoproject.org/dev-manual/common-tasks.html#maintaining-open-source-license-compliance-during-your-product-s-lifecycle). + +1. Source code must be provided. + +2. License text for the software must be provided. + +3. Compilation scripts and modifications to the source code must be provided. + +The first two points can be adressed by running: + + $ make source-release SOURCE_RELEASE= MANIFESTS= + +This will create tarballs for packages that require the release of source code +(i.e. GPL) in the directory `SOURCE_RELEASE` (defaulting to `source-release`). + +In addition, a license manifest is stored in directory `MANIFESTS` (defaulting +to `manifests`) to assist with audits. + +Some licenses require the license text to accompany the binary. You can achieve +this by adding the following to your +`project-spec/meta-user/conf/petalinuxbsp.conf` file: + + COPY_LIC_MANIFEST = "1" + COPY_LIC_DIRS = "1" + LICENSE_CREATE_PACKAGE = "1" + + +### Extending + +If you need additional functionality in your project, put it into a file named +`local.mk`. + + +## XSDK Makefile + +The XSDK Makefile provides a declarative wrapper around the Xilinx Software +Command-Line Tool (XSCT) and Bootgen to streamline the build of Xilinx Software +Development Kit (XSDK) projects. + + +### Supported Platforms + +XSDK is supported from v2018.1 to v2019.1 (i.e. the last four releases). The +Makefile should run on all underlying Linux OSs supported by XSDK, but not +Windows. However, testing is only conducted on Ubuntu 18.04 LTS (Bionic Beaver) +as of now. + + +### Build Configuration Syntax + +The XSDK Makefile is configured via a custom syntax as documented in the +following sections. + + +#### Hardware Platform Specification + +The Hardware Platform Specification captures all the information from a +hardware design that is required to write, debug and deploy software +applications for that hardware. In the XSDK Makefile, there is exactly one +hardware platform specification called `hw` by default [^1]. The hardware +platform specification is derived from the Hardware Description File (HDF) +imported during build (see section Usage) and does not need to be configured. + +[^1]: The hardware platform specification name can be changed with the `HW_PRJ` + variable if necessary. + +#### Repositories + +A software repository is a directory that holds third-party software +components, as well as custom drivers, libraries, and operating systems. You +can register repositories in the workspace by adding the respective path to the +`REPOS` variable. + +#### Board Support Packages + +A Board Support Package (BSP) is a collection of libraries and drivers that +form the basis of software applications (see section "Applications"). + +BSPs are registered by adding their name to the `BSP_PRJS` list. They can then +be configured by prefixing the corresponding option with their name: + + BSP_PRJS += fsbl_bsp + fsbl_bsp_PROC = psu_cortexa53_0 + fsbl_bsp_IS_FSBL = yes + fsbl_bsp_LIBS = xilffs xilsecure xilpm + fsbl_bsp_POST_CREATE_TCL = configbsp -bsp fsbl_bsp use_strfunc 1 + + BSP_PRJS += gen_bsp + gen_bsp_PROC = psu_cortexa53_0 + gen_bsp_STDOUT = psu_uart_1 + +The following BSP options are available: + +`OS` +: Operating system type. Optional, defaults to `standalone`. Run `repo -os` in +XSCT to get a list of all OSs. + +`PROC` +: Processor instance. Run `toolchain` in XSCT to get a list of supported +processor types. + +`ARCH` +: Processor architecture. Can be 32 or 64 bit. Valid only for processors +supporting multiple architectures (e.g. A53). + +`PATCH` +: List of space-separated patch file entries. Patches are applied in the base +directory of the respective BSP project. A patch file list entry has the format +`[;stripnum]`, where `stripnum` is the optional number of leading +slashes to be stripped from each file name found in the patch file (default is +1). + +`SED` +: List of space-separated file entries to be transformed with sed (stream +editor). Sed is run in the base directory of the respective BSP project. A sed +list entry has the format `;`, where `` is the file +to be transformed and `` the sed script file. + +`IS_FSBL` +: If `yes`, apply non-default BSP settings for FSBL. + +`EXTRA_CFLAGS` +: Additional compiler flags (default `-g -Wall -Wextra`). The default +optimization level of `-O2` can be overriden with this variable. + +`STDIN` +: Select UART for standard input. + +`STDOUT` +: Select UART for standard output. + +`LIBS` +: List of libraries to be added to the BSP. Run `repo -lib` in XSCT to get a +list of available libraries. + +`POST_CREATE_TCL` +: Hook for adding extra Tcl commands after the BSP has been created. Can be +used to configure BSP settings (via the `configbsp` command) not available in +the XSDK Makefile. + + +#### Applications + +Software application projects are your final application containers. They can +either be derived from a template or contain your own source files. Each +application project must be linked to exactly one BSP. + +Application projects are registered by adding their name to the `APP_PRJS` +list. They can then be configured by prefixing the corresponding option with +their name: + + APP_PRJS += fsbl + fsbl_TMPL = Zynq MP FSBL + fsbl_BSP = fsbl_bsp + fsbl_CPPSYMS = FSBL_DEBUG_DETAILED + + APP_PRJS += helloworld + helloworld_TMPL = Hello World + helloworld_BSP = gen_bsp + helloworld_BCFG = Debug + helloworld_PATCH = helloworld.patch + helloworld_SED = platform.c;baud_rate.sed + helloworld_LIBS = helloworldlib + +The following application project options are available: + +`TMPL` +: Name of the template to base the application project on. Run `repo -apps` in +XSCT to get a list of available application templates. + +`PROC` +: Processor instance. Run `toolchain` in XSCT to get a list of supported +processor types. + +`LANG` +: Programming language. Can be either `c` (default) or `c++`. + +`BSP` +: Reference to BSP. Required. + +`SRC` +: List of space-separated source files to be added to the application. For each +list entry, a symlink in the `src` directory of the respective application +project will be created that points towards the corresponding source file. + +`PATCH` +: List of space-separated patch file entries. Patches are applied in the `src` +directory of the respective application project. A patch file list entry has +the format `[;stripnum]`, where `stripnum` is the optional number of +leading slashes to be stripped from each file name found in the patch file +(default is 1). + +`SED` +: List of space-separated file entries to be transformed with sed (stream +editor). Sed is run in the `src` directory of the respective application +project. A sed list entry has the format `;`, where +`` is the file to be transformed and `` the sed script file. + +`BCFG` +: Build configuration. Can either be `Release` (default) or `Debug`. + +`OPT` +: Compiler optimization level. Can either be `None (-O0)`, `Optimize (-O1)`, +`Optimize more (-O2)` (default), `Optimize most (-O3)`, `Optimize for size +(-Os)`. + +`CPPSYMS` +: List of preprocessor symbols (e.g. `MYSYMBOL=1`). + +`LIBS` +: List of library projects the application depends on. The libraries are added +to the include and library search paths and linked against the application. + +`POST_CREATE_TCL` +: Hook for adding extra Tcl commands after the application project has been +created. Can be used to set application project configuration parameters (via +the `configapp` command) not available in the XSDK Makefile. + + +#### Libraries + +Software library projects are collections of commonly used functions for your +applications. Library projects are independent of the hardware platform +specification. + +Library projects are registered by adding their name to the `LIB_PRJS` list. +They can then be configured by prefixing the corresponding option with their +name: + + LIB_PRJS += helloworldlib + helloworldlib_PROC = psu_cortexa53 + helloworldlib_BCFG = Debug + helloworldlib_SRC = helloworldlib.c libhelloworld.h + +The following library project options are available: + +`TYPE` +: Library type. Can be either `static` (default) or `shared`. Type `shared` can +only be used in combination with operating system type `linux`. + +`PROC` +: Processor type. Can be either `ps7_cortex9`, `microblaze`, `psu_cortexa53` or +`psu_cortexr5`. Required. + +`OS` +: Operating system type. Can be either `standalone` (default) or `linux`. Type +`linux` can only be used in combination with library type `shared`. + +`LANG` +: Programming language. Can be either `c` (default) or `c++`. + +`ARCH` +: Processor architecture. Can be 32 or 64 bit. Valid only for processors +supporting multiple architectures (e.g. A53). + +`SRC` +: List of space-separated source files to be added to the library. For each +list entry, a symlink in the `src` directory of the respective library project +will be created that points towards the corresponding source file. + +`BCFG` +: Build configuration. Can either be `Release` (default) or `Debug`. + +`OPT` +: Compiler optimization level. Can either be `None (-O0)`, `Optimize (-O1)`, +`Optimize more (-O2)` (default), `Optimize most (-O3)`, `Optimize for size +(-Os)`. + +`CPPSYMS` +: List of preprocessor symbols (e.g. `MYSYMBOL=1`). + +`POST_CREATE_TCL` +: Hook for adding extra Tcl commands after the library project has been +created. Can be used to set library project configuration parameters (via +the `configapp` command) not available in the XSDK Makefile. + +Since XSDK does not support building Linux apps, the combination of library +type `shared` and operating system type `linux` is not officially supported by +the XSDK Makefile. + + +#### Bootgen + +Bootgen is a Xilinx tool that merges build artifacts into a boot image +according to a Boot Image Format (BIF) file. The XSDK Makefile can generate BIF +files and invoke Bootgen subsequently. + +Bootgen projects are registered by adding their name to the `BOOTGEN_PRJS` +list. They can then be configured by prefixing the corresponding option with +their name: + + BOOTGEN_PRJS += bootbin + bootbin_BIF_ARCH = zynqmp + +The following Bootgen project options are available: + +`BIF_ARCH` +: Device architecture. Run `bootgen` and see description of `-arch` option for +a list of supported architectures. + +`BIF_ARGS_EXTRA` +: Add additional Bootgen arguments for special operations like key generation. + +`NO_OUTPUT` +: If `yes`', do not write a boot image file. Required for certain operations +like key generation. + +`FLASH_TYPE` +: Flash memory type. Run `program_flash` and see description of option +`-flash_type` to get a list of supported memory types. Only needed for `flash` +target (see section "Usage"). + +`FLASH_FSBL` +: FSBL used for flashing. Only needed for `flash` target (see section "Usage"). + +`FLASH_OFF` +: Offset within the flash memory at which the image should be written. Only +needed for `flash` target (see section "Usage"). + +BIF attributes are then registered by adding their name to the `BIF_ATTRS` +list. They can then be configured by prefixing the `BIF_ATTR` and `BIF_FILE` +variables with the Bootgen project name and BIF attribute name: + + bootbin_BIF_ATTRS = fsbl helloworld + bootbin_fsbl_BIF_ATTR = bootloader, destination_cpu=a53-0 + bootbin_fsbl_BIF_FILE = fsbl/$(fsbl_BCFG)/fsbl.elf + bootbin_helloworld_BIF_ATTR = destination_cpu=a53-0 + bootbin_helloworld_BIF_FILE = helloworld/$(helloworld_BCFG)/helloworld.elf + +This example is translated to the following BIF file: + + bootbin: + { + [bootloader, destination_cpu=a53-0] fsbl/Release/fsbl.elf + [destination_cpu=a53-0] helloworld/Debug/helloworld.elf + } + +Prerequisites to all `BIF_FILE`s are added to the corresponding BIF generation +rules. If, however, the concerning file is created instead of consumed by +Bootgen (e.g. key generation) or is not a file at all, one must set the +`BIF_FILE_NO_DEP` variable to `yes`. For example: + + ... + generate_pem_BIF_ARGS_EXTRA = -p zu9eg -generate_keys pem + ... + generate_pem_pskfile_BIF_ATTR = pskfile + generate_pem_pskfile_BIF_FILE = generate_pem/psk0.pem + generate_pem_pskfile_BIF_FILE_NO_DEP = yes + ... + +The file name of a bitstream depends on the Vivado design and is often not +known before the HDF has been extracted. In these cases, by convention, one +should point the corresponding `BIF_FILE` option to a variable named like +`BIT`: + + bootbin_bit_BIF_ATTR = destination_device=pl + bootbin_bit_BIF_FILE = $(BIT) + +The `BIT` variable must then be provided on invocation: + + $ make HDF= BIT=hw/.bit + +Optionally, one can provide a default as well: + + BIT ?= hw/design_1_wrapper.bit + + +### Setup + +Create a symlink named `Makefile` to the `xsdk.mk` file: + + $ ln -s /xsdk.mk Makefile + +Add the `build` directory to your `.gitignore`. + +By default, the XSDK Makefile looks for the build configuration in +`./default.mk`. If you choose a different file name (or like to have multiple +build configurations), you can specify the path with the `CFG` variable. + +Write your build configuration as documented in section "Makefile syntax". +Instead of writing the build configuration from scratch, you can also copy +`templates/default.mk` into your working directory. + + +### Usage + +Import a HDF and build all projects by executing: + + $ make HDF= + +The XSDK Makefile creates a new XSDK workspace as a subfolder in directory +`build` named `_-