Xilinx Machines
===============

Xilinx uses an inheritence model to define defaults in a heirarchical
model.  This allows for machines to include other machines and then
override defaults.

For example, a carrier board with a system on module using a zynqmp ev
can be implements as:

k26_kv -> k26 -> zynqmp-ev-generic -> zynqmp-generic

The above needs to result MACHINEOVERRIDES and PACKAGE_ARCHS that include
all 4 machines.  This facilitates sstate-cache and binary distribution
package re-use.

To accomplish this, each machine.conf file should contain the following
preamble and postamble.  This ensures that the machine overrides and
package archs can be extended by another machine configuration file.

#### Preamble
MACHINEOVERRIDES =. "${@['', '<machine>:']['<machine>' != '${MACHINE}']}"
#### Regular settings follow


#### No additional settings should be after the Postamble
#### Postamble
PACKAGE_EXTRA_ARCHS:append = "${@['', ' <machine_arch>']['<machine>' != "${MACHINE}"]}"


Between the Preamble and Postamble, you should "require" the machine
configuration that your machine is based on.  After the 'require' is where
most variables should be defined.  (See variable requirements at the end
of this document.)  This will allow you to extend other configurations
to match your specific requirements.  Values should be set using = and
+=, but not :append or :prepend.  This allows a machine inheriting your
machine file to add or overwrite the value easily.  Such as:

Typical case example (my-example.conf):

#### Preamble
MACHINEOVERRIDES =. "${@['', 'my-example:']['my-example' != '${MACHINE}']}"
#### Regular settings follow

require conf/machine/zynqmp-generic.conf

HDF_MACHINE = "zcu102-zynqmp"
MACHINE_FEATURES += "pci"

#### No additional settings should be after the Postamble
#### Postamble
PACKAGE_EXTRA_ARCHS:append = "${@['', ' my_example']['my-example' != "${MACHINE}"]}"


A few variable must be set BEFORE the requires, DEFAULTTUNE for example.
(See variable requirements at the end of this document.)  Usually ?= is the
correct way to set these, as the machine inheriting your machine may need
to override the value.

Example of defaulttune override:

#### Preamble
MACHINEOVERRIDES =. "${@['', 'my-example:']['my-example' != '${MACHINE}']}"
#### Regular settings follow

DEFAULTTUNE ?= "aarch64"

require conf/machine/zynqmp-generic.conf

HDF_MACHINE = "zcu102-zynqmp"
MACHINE_FEATURES += "pci"

#### No additional settings should be after the Postamble
#### Postamble
PACKAGE_EXTRA_ARCHS:append = "${@['', ' my_example']['my-example' != "${MACHINE}"]}"


Additionally, for microblaze you may need to define a specific microblaze
tune-features.  Like DEFAULTTUNE, this needs to be set before the require line.

Example of microblaze tune override:

#### Preamble
MACHINEOVERRIDES =. "${@['', 'my-example:']['my-example' != '${MACHINE}']}"
#### Regular settings follow

TUNE_FEATURES:tune-microblaze ?= "microblaze v8.50 barrel-shift reorder pattern-compare divide-hard multiply-high fpu-hard"

require conf/machine/microblaze-generic.conf

HDF_MACHINE = "ml605"
SERIAL_CONSOLE = "115200,ttyUL0"

#### No additional settings should be after the Postamble
#### Postamble
PACKAGE_EXTRA_ARCHS:append = "${@['', ' my_example']['my-example' != "${MACHINE}"]}"


Variable Requirements
=====================

The question has been raised why we don't use ?= or ??= for all default
values, instead we rely on specific ordering of the override components?

This is done intentionally, as it forces the user to create a new machine
configuration file to extend their system.  In the past, it was common
for people to just set values in their local.conf file, but this lead to
problems reproducing success and failures, as well as trying to support
the overall configuration.  Moving to a model where most variables must
be added to, or replaced after the require has simplified this model.
There are a few exception, these will be covered first.

The following variables must be set using ?= BEFORE the 'require' line
of the inherited base machine .conf file.  This is due to them being
used to control inclusion of tune data.

DEFAULTTUNE - Default Tune for this machine

TUNEFILE[<tune>] - The tune file, based on DEFAULTTUNE, to load

For DEFAULTTUNE, see the Yocto Project documentation.  For
TUNEFILE[<tune>] see include/soc-tune-include.inc for the defined ones.


The following variables should be set using ?= BEFORE the 'require' line
of the inherited base machine .conf file, if the user may override them.
If the values are fixed, then it should be set after the requires per
the next section.

These are common values a user may want to override and will let the user
easiy make a local change, if allowed by the machine .conf:

UBOOT_MACHINE - The defconfig for u-boot.  (Note, this may be an error TBD).

SOC_VARIANT - See include/soc-*.inc (Note, most machines this is fixed).


The following variables must be set AFTER the 'require' line, using '='
or '+='/'=+' as required.  Using ':append', ':prepend', or ':remove' will
prevent an inheriting machine from overriding that value.  Similarly
you should not use :<machine> override values for the same reason.  Note,
not every machine file will have all of these variables, only the ones
you need to override should be set.

Variables set before required inclusion file:
Variables that changes based on hw design or board specific requirement must be
set before required inclusion file else pre-expansion value defined in generic
machine conf will be set. This way user can also override these variables from
local.conf

System wide setting:
TUNE_FEATURES:tune-<tune> - Specific tune features

external-hdf recipe from meta-xilinx-tools:
HDF_MACHINE - Machine to load from reference defign xsa using hdf-examples recipe
HDF_EXT - Only ".xsa" externsion is supported, legacy variable.
HDF_BASE - Download protocol (file://, git://, http:// or https://) protocol if
    not using the default external-hdf repository.
HDF_PATH - Path to the repository or XSA file

fs-boot recipe from meta-xilinx-tools:
YAML_SERIAL_CONSOLE_STDIN:pn-fs-boot - YAML based uart stdin configuration for
MicroBlaze. Example: axi_uartlite_0 or axi_uart16550_0 etc,.
YAML_SERIAL_CONSOLE_STDOUT:pn-fs-boot - YAML based uart stdout configuration for
MicroBlaze. Example: axi_uartlite_0 or axi_uart16550_0 etc,.
YAML_MAIN_MEMORY_CONFIG:pn-fs-boot - YAML based DDR4 or MIG configuration for
MicroBlaze. Example: DDR4_0 or MIG_7SERIES_0 etc,.
YAML_FLASH_MEMORY_CONFIG:pn-fs-boot - YAML based flash configuration for
MicroBlaze. Example: axi_emc_0 or axi_quad_spi_0 etc,.
XSCTH_PROC:pn-fs-boot - Processor IP used while configuring embeddedsw compoments.
Example: microblaze_0 or microblaze_1 etc,.

fsbl-firmware recipe from meta-xilinx-tools:
YAML_SERIAL_CONSOLE_STDIN:pn-fsbl-firmware - YAML based FSBL uart stdin configuration
for Zynq-7000 and ZynqMP devices.
YAML_SERIAL_CONSOLE_STDOUT:pn-fsbl-firmware - YAML based FSBL uart stdout configuration
for Zynq-7000 and ZynqMP devices.

pmu-firmware recipe from meta-xilinx-tools:
YAML_SERIAL_CONSOLE_STDIN:pn-pmu-firmware - YAML based PMUFW uart stdin configuration
for ZynqMP devices.
YAML_SERIAL_CONSOLE_STDOUT:pn-pmu-firmware - YAML based PMUFW uart stdout configuration
for ZynqMP devices.

plm-firmware recipe from meta-xilinx-tools:
YAML_SERIAL_CONSOLE_STDIN:pn-plm-firmware - YAML based PLM uart stdin configuration
for Versal devices.
YAML_SERIAL_CONSOLE_STDOUT:pn-fplmsbl-firmware - YAML based PLM uart stdout
configuration for Versal devices.

device-tree recipe from meta-xilinx-tools:
YAML_CONSOLE_DEVICE_CONFIG:pn-device-tree - YAML based uart console configuration
for all device families. Example: axi_uartlite_0 or psu_uart_0 etc,.
YAML_MAIN_MEMORY_CONFIG:pn-device-tree - YAML based memory configuration for all
device families. Example: DDR4_0 or PS7_DDR_0 or PSU_DDR_0 etc,.
XSCTH_PROC:pn-device-tree - Processor IP used while configuring device-tree
compoments. Example: microblaze_0 or microblaze_1 etc,.
YAML_DT_BOARD_FLAGS:pn-device-tree - YAML based configuration for setting eval
board specific dtsi files available in DTG repo.

arm-trusted-firmware recipe from meta-xilinx-core:
ATF_CONSOLE - Uart console configuration for all aarch64 device families.
Example: pl011 or cadence or cadence1 etc,.
TFA_BL33_LOAD - BL33 preloadded base address to EXTRA_OEMAKE for aarch64.

u-boot-xlnx recipe from meta-xilinx-core:
UBOOT_MACHINE - Name of the defconfig to use
HAS_PLATFORM_INIT - List of defconfig files available for u-boot only for SPL boot.

u-boot-xlnx-scr recipe from meta-xilinx-core:
DDR_BASEADDR - Base address for DDR used for loading the images from u-boot env.
SKIP_APPEND_BASEADDR - Skip appending ${DDR_BASEADDR} for image offsets.

Varibable set after required inclusion file:
Varibables that does not intend to change must be set before required inclusion
file.

external-hdf recipe from meta-xilinx-tools:
HDF_MACHINE - Used by the  recipe to find the correct XSA
HDF_EXT - only xsa is supported, legacy variable
HDF_BASE - protocol if not using the default external-hdf repository
HDF_PATH - path to the repository or XSA file

...and more...