diff options
| -rw-r--r-- | BUILD.md | 64 | ||||
| -rw-r--r-- | CUSTOMIZE.md | 95 | ||||
| -rw-r--r-- | DEPLOY.md | 82 | ||||
| -rw-r--r-- | README.md | 38 | ||||
| -rw-r--r-- | SETUP.md | 29 | ||||
| -rw-r--r-- | meta-amd-bsp/README.md | 2 |
6 files changed, 306 insertions, 4 deletions
diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 00000000..0c9ce2e0 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,64 @@ +# 2. Setting up and starting a build + +After [setting up the build system](SETUP.md), we can build images or +recipes for a target machine (or BSP). +Running the commands in the instructions below will setup a build for +a selected AMD BSP, and start a build: + +### 2.1. Select a BSP + +Set the environment variable `MACHINE` to one of the +[supported AMD BSPs](meta-amd-bsp/README.md) (change the +`<machine-name>` in the following example accordingly): +```sh +MACHINE="<machine-name>" +``` + +### 2.2. Setup the build environment for selected BSP + +Source the *oe-init-build-env* script: +```sh +source ./oe-init-build-env build-${MACHINE}-warrior +``` + +Set the `MACHINE` and `DISTRO` bitbake environment variables in the +`conf/local.conf` (or `auto.conf`): +```sh +tee conf/auto.conf <<EOF +DL_DIR ?= "\${TOPDIR}/../downloads" +SSTATE_DIR ?= "\${TOPDIR}/../sstate-cache" + +MACHINE = "${MACHINE}" +DISTRO = "poky-amd" +EOF +``` + +Add the required layers to the build configuration: +```sh +bitbake-layers add-layer ../meta-openembedded/meta-oe +bitbake-layers add-layer ../meta-openembedded/meta-python +bitbake-layers add-layer ../meta-openembedded/meta-networking +bitbake-layers add-layer ../meta-dpdk +bitbake-layers add-layer ../meta-amd/meta-amd-distro +bitbake-layers add-layer ../meta-amd/meta-amd-bsp +``` + +### 2.3. Start the build + +Build one of the supported image recipes: +```sh +bitbake <image-name> -k +``` + +###### where `<image-name>` is to be replaced with one of the supported images for the selected AMD BSP. +###### (e.g. `core-image-sato` or `core-image-base`) + +--- +#### What's next + +Continue to "[section 3 - deploy](DEPLOY.md)" for instructions on +booting the target with the newly built image. + +You can also [customize the image](CUSTOMIZE.md) by enabling/disabling +certain configurable features. Make sure to re-build the image before +deploying the customized build. diff --git a/CUSTOMIZE.md b/CUSTOMIZE.md new file mode 100644 index 00000000..f3d8a5dd --- /dev/null +++ b/CUSTOMIZE.md @@ -0,0 +1,95 @@ +# Customizing images with AMD Features + +AMD supports various features and software components that can be +enabled by setting the corresponding configuration variable to a +valid value in the `local.conf`. + +Following is a list of components that can be enabled if you want +them to be installed/available on your image, or can be configured: + +* **VULKAN - Vulkan driver and Loader Layer.** + + It is required to run Vulkan based applications. Vulkan is a new + generation graphics and compute API that provides high-efficiency, + cross-platform access to modern GPUs. + +* **MPV \* - Video player based on MPlayer/mplayer2** + + MPV is a movie player based on MPlayer and mplayer2. It supports a + wide variety of video file formats, audio and video codecs, and + subtitle types. + +* **COMMERCIAL MULTIMEDIA \* - License restricted multimedia components** + + Certain multimedia formats require license restricted codecs and + software components which are not included in build by default. + +* **MULTI DISPLAY - Multiple display support** + + You can connect multiple displays with AMD machines. The display + configuration/arrangement can be configured using this. + +* **ON-TARGET DEVELOPMENT - SDK for on-target development** + + gcc, make, autotools, autoconf, build-essential etc. + +* **ON-TARGET DEBUGGING - tools for on-target debugging** + + gdb, gdbserver, strace, mtrace + +* **ON-TARGET PROFILING - tools for on-target profiling** + + lttng, babeltrace, systemtap, powertop, valgrind + +--- +#### Disclaimer + +\* Using **MPV** & **COMMERCIAL MULTIMEDIA** requires use of +license-restricted algorithms or software. + +\* AMD does not distribute or endorse sources for license-restricted +algorithms or software, and disclaims any liability for their use. + +--- +##### Note + +Please set the required configuration variables as shown below in the +`local.conf` **before building an image or generating an SDK** (that +can be used to develop apps for these components (if applicable)). + +Otherwise they will not be configured, and will not be available on the +target. + +--- + +#### Supported Features + +| Feature | Configuration variable | Configuration values | Default value | Supported BSPs | +|:----------------------|:------------------------------|:---------------------------------------|:--------------|:---------------| +| VULKAN | INCLUDE_VULKAN | yes, no | no | r1000 | +| MPV | INCLUDE_MPV | yes, no | no | r1000 | +| COMMERCIAL MULTIMEDIA | INCLUDE_COMMERCIAL_MULTIMEDIA | yes, no | no | r1000 | +| MULTI DISPLAY | MULTI_DISPLAY_MODE | auto, mirrored, extended-v, extended-h | auto | r1000 | +| ON-TARGET DEVELOPMENT | EXTRA_IMAGE_FEATURES_append | tools-sdk | | r1000 | +| ON-TARGET DEBUGGING | EXTRA_IMAGE_FEATURES_append | tools-debug | | r1000 | +| ON-TARGET PROFILING | EXTRA_IMAGE_FEATURES_append | tools-profile | | r1000 | + +#### Example configuration in local.conf +```sh +INCLUDE_VULKAN = "yes" +INCLUDE_MPV = "yes" +INCLUDE_COMMERCIAL_MULTIMEDIA = "yes" + +MULTI_DISPLAY_MODE = "auto" + +EXTRA_IMAGE_FEATURES_append = " tools-sdk" +EXTRA_IMAGE_FEATURES_append = " tools-debug" +EXTRA_IMAGE_FEATURES_append = " tools-profile" +``` + +--- +#### What's next + +Continue to [section 2 - build](BUILD.md#23-start-the-build) and +restart the image build as `bitbake <image-name>`, and deploy the +new image to see the changes take effect. diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 00000000..ece6d483 --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,82 @@ +# 3. Deploying an image to the target + +After [building an image](BUILD.md), we can deploy it to the target +using a USB Flash Drive or a CD/DVD. The built images can be found in +the `<build-dir>/tmp/deploy/images/<machine-name>` directory to +which we will refer to as the **"Image Deploy Directory"** in this doc. + +--- +##### Note +Change these placeholders in the following instructions according to +the selected BSP and the image built in [section 2 - build](BUILD.md): +* `<machine-name>` +* `<image-name>` +--- + +Change directory to the Image Deploy Directory: +```sh +cd tmp/deploy/images/<machine-name> +``` + +This directory contains `.wic` and `.iso` images for USB and CD/DVD +respectively. Follow the instructions below to make a bootable +USB Flash Drive or a CD/DVD by writing/burning the image to it: + +### 3.1a. Deploy using a USB Flash Drive + +We can use **bmaptool** (from *bmap-tools* package) or **dd** to write +the `<image-name>-<machine-name>.wic` image located in the +Image Deploy Directory to a USB Flash Drive: + +##### Using bmaptool *(recommended)* +```sh +sudo bmaptool copy <image-name>-<machine-name>.wic /dev/<dev-node> +``` + +##### Using dd +```sh +sudo dd if=<image-name>-<machine-name>.wic of=/dev/<dev-node> status=progress +``` + +###### where `<dev-node>` is to be replaced with the device node of the USB Flash Drive. +###### (e.g. `sda`, `sdb` or `sdc` etc.) + +### 3.1b. Deploy using a CD/DVD + +You may use any CD/DVD burning tool to burn the +`<image-name>-<machine-name>.iso` image located in the +Image Deploy Directory onto a writable CD/DVD. + +### 3.2. Booting the target + +Insert the bootable USB or CD/DVD (created in above steps) into the +target machine and power ON the machine. + +--- +##### Note + +You may need to press `Esc` key right after pressing the power ON +button to enter the BIOS setup and set the boot device priority/order +to boot from the inserted USB or CD/DVD. + +--- + +The grub boot menu should appear at this point where you will see +options to `boot` or `install` this image: + +* Select the `boot` option to boot up the target machine. + +* Select the `install` option to install the image onto the target +machine's hard drive. Follow the instructions there to complete the +installation process, and reboot the machine and boot from the +hard drive you selected during the installation process. + +You will be presented with a console (serial or graphical) or a +graphical user interface depending on the image and the target machine. + +--- +#### What's next + +You can also [customize the image](CUSTOMIZE.md) by enabling/disabling +certain configurable features. Make sure to +[re-build the image](BUILD.md) before deploying the customized build. @@ -2,8 +2,40 @@ This is the location for AMD BSP and AMD DISTRO layers. -Please see the README files contained in the meta-amd-bsp layer for -BSP-specific information like dependencies etc. +Please see [AMD BSPs](meta-amd-bsp/README.md) for information about the +supported BSPs and their dependencies, and see +[AMD DISTRO](meta-amd-distro/README.md) for information about the +distro features. + +## Getting started + +Follow these simple steps to get started with setting up the +build system and start building images and recipes for the supported +AMD BSPs, and to deploy the built images on the target: + +### 1. Setup +Please see [SETUP.md](SETUP.md) for instructions on how to setup the +build system and the environment for it. + +### 2. Build + +Please see [BUILD.md](BUILD.md) for instructions on how to setup and +start a build for any of the supported AMD BSPs. + +### 3. Deploy + +Please see [DEPLOY.md](DEPLOY.md) for instructions on how to write/burn +a built image onto a USB/CD/DVD and boot the target machine with it. + +#### What's next + +You can also customize the images according to your requirement. + +Please see [CUSTOMIZE.md](CUSTOMIZE.md) for instructions on how to +customize the build and to enable/disable any of the supported features +and software components to be included into the build. + +## Troubleshoot If you have problems with or questions about a particular BSP, please contact the maintainer of the particular layer as listed in the @@ -30,7 +62,7 @@ submit the bug against the most likely category for the problem - if you're wrong, it's not a big deal and the bug will be recategorized upon triage. -## Contributing +## Contribute Please submit any patches against meta-amd BSPs to the meta-amd mailing list (meta-amd@yoctoproject.org). Also, if your patches are diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 00000000..17b14b01 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,29 @@ +# 1. Setting up the build system + +Running the following commands will setup the build system and will +enable us to build recipes & images for any of the supported AMD BSPs: + +```sh +gitclonecheckout() { + REPO="$1"; NAME="$2"; HASH="$3" + + git clone --single-branch --branch "${YOCTO_BRANCH}" "${REPO}" "${NAME}" + cd "${NAME}" + git checkout --quiet "${HASH}" + cd .. +} + +YOCTO_BRANCH="warrior" + +gitclonecheckout "git://git.yoctoproject.org/poky" "poky-amd" "6d2e12e79211b31cdf5ea824fb9a8be54ba9a9eb" +cd "poky-amd" +gitclonecheckout "git://git.openembedded.org/meta-openembedded" "meta-openembedded" "3bdbf72e3a4bf18a4a2c7afbde4f7ab773aeded9" +gitclonecheckout "git://git.yoctoproject.org/meta-amd" "meta-amd" "HEAD" +gitclonecheckout "git://git.yoctoproject.org/meta-dpdk" "meta-dpdk" "c8c30c2c4e2f36b4a55a69a475fe774015423705" +``` + +--- +#### What's next + +Continue to "[section 2 - build](BUILD.md)" for instructions on how to +setup and start a build for a particular AMD BSP. diff --git a/meta-amd-bsp/README.md b/meta-amd-bsp/README.md index 394edd46..15932e77 100644 --- a/meta-amd-bsp/README.md +++ b/meta-amd-bsp/README.md @@ -8,7 +8,7 @@ to ensure they only apply to expected boards. ## Machines -This layer contains meta-data for the following AMD BSPs: +The supported AMD BSPs are: * r1000 * v1000 |