# Xilinx 平台配置指南 (HOWTO)

## 目录结构说明

- **build.bat**: 用于在 Windows 系统上运行的批处理脚本，负责自动化构建整个项目；

- **launch.bat**: 用于启动 Xilinx SDK 或 Vitis 的批处理脚本，适用于在 Windows 系统上打开开发环境，加载并查看生成的工程；

- **setenv.bat**: 运行环境配置脚本，用于在 Windows 系统中设置 Xilinx 开发工具的环境变量，通常在构建或启动项目前运行；

- **template.gitignore**: 针对 Xilinx 工具的 `.gitignore` 模板文件，用户可以将其内容复制到实际的 `.gitignore` 文件中；

- **template.json**: 项目的 JSON 配置模板文件，定义了工程的基本配置，具体配置参数请参考[配置文件说明](#配置文件说明)；

- **util.tcl**: 包含一组通用工具命令的 TCL 脚本，用于辅助自动化构建过程。此文件在构建过程中被调用，用于与开发工具交互执行 Xilinx 工具相关的特定操作；

- **xilinx.mk**: 被 [`generic.mk`](../../generic.mk) 定义了 Xilinx 平台的特定的编译规则；

## 配置文件说明

配置文件用于定义 Xilinx 平台项目的构建参数、应用配置和库依赖关系等信息，以便于在 `embedded-autobuild` 项目中自动化生成工程。以下为最小化完整配置示例，包含了所有必填字段，可作为基础配置参考。

```json
{
    "project_name": "demo",
    "version": "0.0.0",
    "hw_design": "demo_v0.0.0.hdf",
    "apps": {
        "demo_app": {
            "sources": ["source/"],
            "target_cpu": "ps7_cortexa9_0",
            "os": "standalone",
            "language": "C",
        }
    }
}
```

如需添加更多配置请详细阅读后续 Xilinx 配置文件各部分的详细说明。

> **注**：以下针对字段的解释中 **加粗** 字段为必须参数，*斜体* 标注的字段为可选参数，可选参数不填写则使用对应 IDE 的默认配置。

### 基本字段

- **project_name**: 项目名称，例如 `"demo"`。
- **version**: 项目版本，例如 `"0.0.0"`。
- **hw_design**: 硬件设计文件（`.hdf` 或 `.xsa` 文件）路径（相对档案工作路径），例如 `"demo_v0.0.0.hdf"`。

### *fsbl_patch* (TODO)

用于配置 `FSBL` (First Stage Bootloader) 的补丁文件。可以包含多个补丁文件以满足自定义的硬件启动需求。

```json
"fsbl_patch": {
    "<patch_target0>": "<patch_file0>",
    "<patch_target1>": "<patch_file1>"
}
```

其基本格式为 `<patch_target>: <patch_file>`，`<patch_target>` 是 FSBL 中需要被替换的文件，`<patch_file>` 为准备好的替换补丁文件。

### *bsps*

该字段用于定义 BSP 或者 Domain 的配置，支持多个 BSP/Domain 配置。

```json
"bsps": {
    "<bsp_name>": {
        "os": "<os_type>",
        "target_cpu": "<cpu_id>",
        "libs": {
            "<lib_name>": {
                "version": "<lib_version>",
                "config": {
                    "<parameter0>": "<value0>",
                    "<parameter1>": "<value1>"
                    ...
                }
            }
            ...
        },
        "config": {
            "<parameter0>": "<value0>",
            "<parameter1>": "<value1>"
            ...
        }
    }
    ...
}
```

- **os**: 操作系统类型，支持的类型有 `standalone`，`freetos`，`linux`[^1]；
- **target_cpu**: 目标 CPU[^2]，例如 "ps7_cortexa9_0" 表示 Zynq-7000 系列的 ARM Cortex-A9 核；
-*libs*: 必要的库及其版本配置[^1]，该配置项下可包含多个 `lib` 配置，默认不添加任何 `lib`；
  - **version**: `lib` 版本 [^1]；
  - *config*: 其他具体 `lib` 设置[^1]，不填写则使用 IDE 默认配置；
-*config*: 其他具体 BSP/Domain 设置[^1]，不填写则使用 IDE 默认配置；

以下配置添加了一个名为 "standalone" 的 BSP/Domain 工程，添加了 `xilffs` 和 `xilrsa` 两个 `lib，其中` `xilffs` 启用了长文件名（use_lfn）以及exFAT（enable_exfat）支持，并设置了标准输入输出为 `ps7_coresight_comp_0`，sleep 计数器使用 `ps7_globaltimer_0`.

```json
"bsps": {
    "standalone": {
        "os": "standalone",
        "target_cpu": "ps7_cortexa9_0",
        "libs": {
            "xilffs": {
                "version": "4.1",
                "config": {
                    "use_lfn": true,
                    "enable_exfat": true
                }
            },
            "xilrsa": {
                "version": "1.5"
            }
        },
        "config": {
            "stdin": "ps7_coresight_comp_0",
            "stdout": "ps7_coresight_comp_0",
            "sleep_timer": "ps7_globaltimer_0"
        }
    }
}
```

### apps

该字段定义应用的具体构建配置，包括目标 CPU、操作系统、内存布局等，编译参数等。

```json
"apps": {
    "<app_name>": {
        "sources": ["dir0", "dir1"],
        "target_cpu": "<cpu_id>",
        "os": "<os_type>",
        "language": "<language>",
        "template": "<app_template>",
        "bsp": "<bsp_name>",
        "bsp_lib": {
            "<lib_name>": {
                "version": "<lib_version>",
                "config": {
                    "<parameter0>": "<value0>",
                    "<parameter1>": "<value1>"
                }
            }
        },
        "bsp_config": {
            "<parameter0>": "<value0>",
            "<parameter1>": "<value1>"
        },
        "mem_layout" : {
            "heap_size": "<heap_size>",
            "stack_size": "<stack_size>"
        },
        "build_config": {
            "<config_name>": {
                "assembler-flags": "<assembler-flags>",
                "compiler-misc": "<compiler-misc>",
                "compiler-optimization": "<compiler-optimization>",
                "linker-misc": "<linker-misc>",
                "linker-script": "<linker-script>",
                "define-compiler-symbols": ["<symbol0>", "<symbol1>"],
                "undef-compiler-symbols": ["<symbol0>", "<symbol1>"],
                "include-path": ["<dir0>", "<dir1>"],
                "libraries": ["<lib0>", "<lib1>"],
                "library-search-path": ["<dir0>", "<dir1>"]
            }
        }
    }
}
```

- **sources**: 源文件列表，可使用通配符。例如，`"src/*"` 会将当前工作路径下的 `src` 文件夹中的所有文件复制或链接到相应工程目录下的 `src` 文件夹中。
- **target_cpu**: 目标 CPU ID[^2]；
- **os**: 操作系统类型[^1]，必须与 BSP/Domain 匹配；
- **language**: 编程语言，"C" 或 "C++"；
- *template*: 所使用的应用模板名称，不指定则默认为对应语言的 “Empty Application”；
- *bsp*: 应用所使用的 BSP 名称，若未指定则会自动创建名为 `<app_name>_bsp` 的 BSP/Domain.
- *bsp_lib*: 针对自动创建的 BSP/Domain 所使用库的配置，与 [bsps](#bsps) 中 `libs` 对应；
- *bsp_config*: 针对自动创建的 BSP/Domain 配置与 [bsps](#bsps) 中 `config` 对应；
- *mem_layout*: 应用内存布局，包括堆栈大小和堆大小等；
  -*heap_size*: 堆大小，必须写为十六进制，例如 "0x80000"；
  -*stack_size*: 栈大小，必须写为十六进制，例如 "0x4000"；
- *build_config*: 编译目标配置，`release` 或 `debug`；
  - `assembler-flags`: 汇编器标志；
  - `compiler-misc`: 其他编译器选项；
  - `compiler-optimization`: 编译优化选项；
  - `linker-misc`: 链接器选项；
  - `linker-script`: 链接脚本路径[^3]；
  - `define-compiler-symbols`: 自定义的编译器宏定义符号列表；
  - `undef-compiler-symbols`: 要取消定义的符号列表；
  - `include-path`: 包含文件路径[^3]；
  - `libraries`: 需要链接的库；
  - `library-search-path`: 库搜索路径[^3]；

以下配置添加了一个名为 `demo_app` 的 Application 工程，该工程没有指定 BSP/Domain 但能够通过 `bsp_lib` 和 `bsp_config` 自动生成一个名为 `standalone_ps7_cortexa9_0` 的 BSP/Domain 工程。

```json
"apps": {
    "demo_app": {
        "sources": ["source/"],
        "target_cpu": "ps7_cortexa9_0",
        "os": "standalone",
        "language": "C",
        "bsp_lib": {
            "xilffs": {
                "version": "5.2",
                "config": {
                    "use_lfn": true,
                    "enable_exfat": true
                }
            }
        },
        "bsp_config": {
            "sleep_timer": "ps7_globaltimer_0",
            "stdin": "ps7_uart_1",
            "stdout": "ps7_uart_1"
        },
        "mem_layout" : {
            "heap_size": "0x80000",
            "stack_size": "0x4000"
        },
        "build_config": {
            "debug": {
                "define-compiler-symbols": ["XILINX_PLATFORM", "_DEBUG_LEVEL_=1"],
                "include-path": ["source/include"],
            },
            "release": {
                "define-compiler-symbols": ["XILINX_PLATFORM"],
                "include-path": ["source/include"],
            }
        }
    }
}
```

[^1]: 具体可配置项取决于对应 IDE 版本；

[^2]: 具体可选 CPU ID 取决于硬件型号；

[^3]: 相对对应工程的文件夹的路径；