Builtin Testcases¶

Exports for git testcases¶

class tbot.builtin.git_tasks_exports.GitRepository[source]¶: A meta object representing a git repository. Can be created with git_clean_checkout() or git_dirty_checkout()

Testcases for working with git¶

tbot.builtin.git_tasks.git_apply_patches(tb: tbot.TBot, *, gitdir: tbot.tc.GitRepository, patchdir: pathlib.PurePosixPath) → None[source]¶

Apply patchfiles inside patchdir onto the git repository in gitdir.

Parameters:	gitdir (GitRepository) – The git repositories meta object patchdir (pathlib.PurePosixPath) – Path to the folder containing the patches

tbot.builtin.git_tasks.git_bisect(tb: tbot.TBot, gitdir: tbot.tc.GitRepository, good: str, and_then: typing.Union[str, typing.Callable], params: typing.Union[typing.Dict[str, typing.Any], NoneType] = None) → typing.Union[str, NoneType][source]¶

Perform a git bisect in the git repository at gitdir between HEAD (as the bad commit) and good. Whether a commit is good or bad is decided by calling the and_then testcase.

Parameters:	gitdir (GitRepository) – Meta object of the git repository that is supposed to be bisected good (str) – The good commit and_then (str or typing.Callable) – A testcase that decides whether a commit is good or bad params (dict) – Additional parameters for the `and_then` testcase
Returns:	The first bad commit
Return type:	str

tbot.builtin.git_tasks.git_clean_checkout(tb: tbot.TBot, *, target: pathlib.PurePosixPath, repo: str, rev: typing.Union[str, NoneType] = None) → tbot.tc.GitRepository[source]¶

Checkout a git repo if it does not exist yet and make sure there are no artifacts left from previous builds.

Parameters:	target (pathlib.PurePosixPath) – Where to clone the repository to repo (str) – Where the git repository can be found rev – Revision to checkout (ie. commit-id or branch name)
Returns:	The git repository as a meta object for testcases that need a git repository
Return type:	GitRepository

tbot.builtin.git_tasks.git_dirty_checkout(tb: tbot.TBot, *, target: pathlib.PurePosixPath, repo: str, rev: typing.Union[str, NoneType] = None) → tbot.tc.GitRepository[source]¶

Checkout a git repo if it does not exist yet, but do not touch it if it already exists

Parameters:	target (pathlib.PurePosixPath) – Where to clone the repository to repo (str) – Where the git repository can be found rev – Revision to checkout (ie. commit-id or branch name)
Returns:	The git repository as a meta object for testcases that need a git repository
Return type:	GitRepository

Exports for shell operations¶

class tbot.builtin.shell_tasks_exports.TftpDirectory(root: pathlib.PurePosixPath, subdir: pathlib.PurePosixPath) → None[source]¶

A meta object to represent the tftp directory. Can be created with setup_tftpdir()

Parameters:	root (pathlib.PurePosixPath) – TFTP root directory subdir (pathlib.PurePosixPath) – TFTP sub-directory
Variables:	root – TFTP root directory subdir – TFTP sub-directory, this is what you should use on the board path – Full TFTP path, this is what you should use on the Labhost

Common shell operations¶

tbot.builtin.shell_tasks.retrieve_build_artifact(tb: tbot.TBot, *, buildfile: pathlib.PurePosixPath, buildhost: typing.Union[str, NoneType] = None, scp_flags: typing.Union[str, NoneType] = None, scp_address: typing.Union[str, NoneType] = None) → pathlib.PurePosixPath[source]¶

Copy artifacts from the buildhost to the labhost

Parameters:	buildfile (pathlib.PurePosixPath) – File on the buildhost buildhost (str) – Name of the buildhost if you do not want to use the default scp_flags (str) – SCP flags to be added to scp commands, defaults to `tb.config["build.<name>.scp_flags"]` scp_address (str) – Address of the form `<user>@<host>` of the buildhost, defaults to `tb.config["build.<name>.username"]+"@"+tb.config["build.<name>.hostname"]`
Returns:	Path where the file has been copied
Return type:	pathlib.PurePosixPath

tbot.builtin.shell_tasks.setup_tftpdir(tb: tbot.TBot, *, root: typing.Union[pathlib.PurePosixPath, NoneType] = None, subdir: typing.Union[pathlib.PurePosixPath, NoneType] = None) → tbot.tc.TftpDirectory[source]¶

Setup the tftp directory

Parameters:	root (pathlib.PurePosixPath) – Optional path to the TFTP root directory, defaults to `tb.config["tftp.root"]` subdir (pathlib.PurePosixPath) – Optional subdir path inside the TFTP directory (has a default value in `config/tbot.py`)
Returns:	The TFTP directory as a meta object
Return type:	TftpDirectory

Exports for toolchains¶

class tbot.builtin.toolchain_exports.Toolchain(name: str, host: str, cfg: tbot.config.Config) → None[source]¶: A meta object to represent a toolchain. Can be created with toolchain_get()

exception tbot.builtin.toolchain_exports.UnknownToolchainException[source]¶: The toolchain provided was not found in the config

Testcase to setup a toolchain environment¶

tbot.builtin.toolchain.toolchain_env(tb: tbot.TBot, *, toolchain: tbot.tc.Toolchain, and_then: typing.Union[str, typing.Callable], params: typing.Union[typing.Dict[str, typing.Any], NoneType] = None) → None[source]¶

Setup a toolchain environment and call a testcase inside

Parameters:	toolchain (Toolchain) – Which toolchain to use and_then (str or typing.Callable) – What testcase to call inside the env params (dict) – Parameters for the testcase

tbot.builtin.toolchain.toolchain_get(tb: tbot.TBot, *, name: typing.Union[str, NoneType] = None, buildhost: typing.Union[str, NoneType] = None) → tbot.tc.Toolchain[source]¶

Get a toolchain and ensure it exists

Parameters:	name (str) – Name of the toolchain, defaults to `tb.config["board.toolchain"]`
Returns:	The toolchain meta object to be passed to testcases that need a toolchain
Return type:	Toolchain

Exports for U-Boot¶

class tbot.builtin.uboot.uboot_exports.UBootRepository[source]¶: A meta object to represent a checked out version of U-Boot. Can be created with uboot_checkout() or uboot_checkout_and_build()

Testcase to build U-Boot¶

tbot.builtin.uboot.uboot_build.just_uboot_build(tb: tbot.TBot) → None[source]¶: Build U-Boot in the currently existing (possibly dirty) U-Boot tree.

tbot.builtin.uboot.uboot_build.uboot_build(tb: tbot.TBot, *, builddir: tbot.tc.UBootRepository, toolchain: tbot.tc.Toolchain, defconfig: typing.Union[str, NoneType] = None, do_compile: bool = True) → None[source]¶

Build U-Boot

Parameters:	builddir (UBootRepository) – Where to build U-Boot toolchain (Toolchain) – Which toolchain to use defconfig (str) – What U-Boot defconfig to use, defaults to `tb.config["uboot.defconfig"]` do_compile (bool) – Whether we should actually run `make` or skip it

Collection of U-Boot tasks¶

tbot.builtin.uboot.uboot_tasks.check_uboot_version(tb: tbot.TBot, *, uboot_binary: pathlib.PurePosixPath) → None[source]¶

Check whether the version of U-Boot running on the board is the same as the one supplied as a binary file in uboot_bin.

Parameters:	uboot_binary (pathlib.PurePosixPath) – Path to the U-Boot binary

tbot.builtin.uboot.uboot_tasks.uboot_checkout(tb: tbot.TBot, *, clean: bool = True, buildhost: typing.Union[str, NoneType] = None, builddir: typing.Union[pathlib.PurePosixPath, NoneType] = None, patchdir: typing.Union[pathlib.PurePosixPath, NoneType] = None, repo: typing.Union[str, NoneType] = None, rev: typing.Union[str, NoneType] = None) → tbot.tc.UBootRepository[source]¶

Create a checkout of U-Boot on the buildhost

Parameters:	clean (bool) – Whether an existing repository should be cleaned buildhost (str) – Which buildhost should U-Boot be built on? builddir (pathlib.PurePosixPath) – Where to checkout U-Boot to, defaults to `tb.config["uboot.builddir"]` patchdir (pathlib.PurePosixPath) – Optional U-Boot patches to be applied ontop of the tree, defaults to `tb.config["uboot.patchdir"]`, supply a nonexistent path to force ignoring the patches repo (str) – Where to get U-Boot from, defaults to `tb.config["uboot.repository"]` rev (str) – Revision from the repo to be checked out, defaults to `tb.config["uboot.revision", None]`
Returns:	The U-Boot checkout as a meta object for other testcases
Return type:	UBootRepository

tbot.builtin.uboot.uboot_tasks.uboot_checkout_and_build(tb: tbot.TBot, *, builddir: typing.Union[pathlib.PurePosixPath, NoneType] = None, patchdir: typing.Union[pathlib.PurePosixPath, NoneType] = None, repo: typing.Union[str, NoneType] = None, rev: typing.Union[str, NoneType] = None, toolchain: typing.Union[tbot.tc.Toolchain, NoneType] = None, defconfig: typing.Union[str, NoneType] = None) → tbot.tc.UBootRepository[source]¶

Checkout U-Boot and build it

Parameters:	builddir (pathlib.PurePosixPath) – Where to checkout U-Boot to, defaults to `tb.config["uboot.builddir"]` patchdir (pathlib.PurePosixPath) – Optional U-Boot patches to be applied ontop of the tree, defaults to `tb.config["uboot.patchdir"]`, supply a nonexistent path to force building without patches repo (str) – Where to get U-Boot from, defaults to `tb.config["uboot.repository"]` rev (str) – Revision from the repo to be checked out, defaults to `tb.config["uboot.revision", None]` toolchain (Toolchain) – What toolchain to use, defaults to `tb.config["board.toolchain"]` defconfig (str) – What U-Boot defconfig to use, defaults to `tb.config["uboot.defconfig"]`
Returns:	The U-Boot checkout as a meta object for other testcases
Return type:	UBootRepository

tbot.builtin.uboot.uboot_tasks.uboot_checkout_and_prepare(tb: tbot.TBot, *, builddir: typing.Union[pathlib.PurePosixPath, NoneType] = None, patchdir: typing.Union[pathlib.PurePosixPath, NoneType] = None, repo: typing.Union[str, NoneType] = None, toolchain: typing.Union[tbot.tc.Toolchain, NoneType] = None, defconfig: typing.Union[str, NoneType] = None) → tbot.tc.UBootRepository[source]¶

Checkout U-Boot and prepare for building it (ie in an interactive session using interactive_build)

Parameters:	builddir (pathlib.PurePosixPath) – Where to checkout U-Boot to, defaults to `tb.config["uboot.builddir"]` patchdir (pathlib.PurePosixPath) – Optional U-Boot patches to be applied ontop of the tree, defaults to `tb.config["uboot.patchdir"]`, supply a nonexistent path to force building without patches repo (str) – Where to get U-Boot from, defaults to `tb.config["uboot.repository"]` toolchain (Toolchain) – What toolchain to use, defaults to `tb.config["board.toolchain"]` defconfig (str) – What U-Boot defconfig to use, defaults to `tb.config["uboot.defconfig"]`
Returns:	The U-Boot checkout as a meta object for other testcases
Return type:	UBootRepository

Run U-Boot tests inside the sandbox¶

tbot.builtin.uboot.uboot_sandbox.uboot_sandbox(tb: tbot.TBot, *, repo: typing.Union[str, NoneType] = None, builddir: typing.Union[pathlib.PurePosixPath, NoneType] = None, patchdir: typing.Union[pathlib.PurePosixPath, NoneType] = None) → None[source]¶

Run U-Boot tests inside the sandbox

Parameters:

repo (str) – URI of the U-Boot repository, defaults to tb.config["uboot.repository"]
builddir (pathlib.PurePosixPath) – Where to build U-Boot, defaults to tb.config["tbot.workdir"] / "uboot-sandbox"
patchdir (pathlib.PurePosixPath) – Optional directory of patches to be applied. If this parameter is not given, tb.config["uboot.patchdir"] will be used (If this is also empty, no patches will be applied). Supply a nonexistent directory to force building without patches.

Run U-Boot tests on real hardware¶

tbot.builtin.uboot.uboot_test.just_uboot_tests(tb: tbot.TBot, *, buildhost: typing.Union[str, NoneType] = None) → None[source]¶

Run U-Boot tests on the currently existing (possibly dirty) U-Boot tree.

Parameters:	buildhost (str) – The buildhost where U-Boot can be build AND tested. Usually this is a ‘local’ buildhost, which means, U-Boot is built on the labhost.

tbot.builtin.uboot.uboot_test.uboot_tests(tb: tbot.TBot, *, buildhost: typing.Union[str, NoneType] = None, builddir: tbot.tc.UBootRepository, toolchain: tbot.tc.Toolchain, test_config: typing.Union[pathlib.PurePosixPath, NoneType] = None, test_hooks: typing.Union[pathlib.PurePosixPath, NoneType] = None, test_boardname: typing.Union[str, NoneType] = None, test_maxfail: typing.Union[int, NoneType] = None) → None[source]¶

Run U-Boot tests on real hardware

Parameters:

buildhost (str) – The buildhost where U-Boot can be build AND tested. Usually this is a ‘local’ buildhost, which means, U-Boot is built on the labhost.
builddir (UBootRepository) – The U-Boot checkout that should be tested. Must be a UBootRepository meta object
toolchain (Toolchain) – What toolchain to use (The testsuite rebuilds the U-Boot binary)
test_config (pathlib.PurePosixPath) – An optional config file for the testsuite, defaults to tb.config["uboot.test.config"]
test_hooks (pathlib.PurePosixPath) – Path to the U-Boot python testsuite hooks for the currently selected board, defaults to tb.config["uboot.test.hooks"]
test_boardname (str) – Name of the board, usually the name of the defconfig minus the "_defconfig", defaults to tb.config["uboot.test.boardname"]
test_maxfail (int) – Maximum number of failed tests before aborting, defaults to tb.config["uboot.test.maxfail"]

Exports for Linux¶

class tbot.builtin.linux.linux_exports.LinuxRepository[source]¶: A meta object to represent a checked out version of Linux. Can be created with linux_checkout()

Testcase to build Linux¶

tbot.builtin.linux.linux_build.just_linux_build_clean(tb: tbot.TBot) → None[source]¶

Build Linux in the currently existing (possibly dirty) Linux tree.

Cleans all previous build artifacts before building

tbot.builtin.linux.linux_build.just_linux_build_noclean(tb: tbot.TBot) → None[source]¶

Build Linux in the currently existing (possibly dirty) Linux tree.

Does not clean building

tbot.builtin.linux.linux_build.linux_build(tb: tbot.TBot, *, builddir: tbot.tc.LinuxRepository, toolchain: tbot.tc.Toolchain, defconfig: typing.Union[str, NoneType] = None, image_type: typing.Union[str, NoneType] = None, do_compile: bool = True) → None[source]¶

Build Linux

Parameters:	builddir (LinuxRepository) – Where to build Linux toolchain (Toolchain) – Which toolchain to use defconfig (str) – What Linux defconfig to use, defaults to `tb.config["linux.defconfig"]` image_type (str) – What type of image should be build (eg. `uImage` or `zImage`) do_compile (bool) – Whether we should actually run `make` or skip it

Collection of Linux tasks¶

tbot.builtin.linux.linux_tasks.check_linux_version(tb: tbot.TBot, *, vmlinux: pathlib.PurePosixPath, buildhost: typing.Union[str, NoneType] = None) → None[source]¶

Check whether the version of Linux running on the board is the same as the one supplied as a binary file in vmlinux (on the buildhost).

Parameters:	vmlinux (pathlib.PurePosixPath) – Path to the U-Boot binary buildhost (str) – Optional, which buildhost to use

tbot.builtin.linux.linux_tasks.linux_checkout(tb: tbot.TBot, *, clean: bool = True, buildhost: typing.Union[str, NoneType] = None, builddir: typing.Union[pathlib.PurePosixPath, NoneType] = None, patchdir: typing.Union[pathlib.PurePosixPath, NoneType] = None, repo: typing.Union[str, NoneType] = None, rev: typing.Union[str, NoneType] = None) → tbot.tc.LinuxRepository[source]¶

Create a checkout of Linux on the buildhost

Parameters:	clean (bool) – Whether an existing repository should be cleaned buildhost (str) – Which buildhost should U-Boot be built on? builddir (pathlib.PurePosixPath) – Where to checkout Linux to, defaults to `wd / tb.config["linux.builddir"]` patchdir (pathlib.PurePosixPath) – Optional Linux patches to be applied ontop of the tree, defaults to `tb.config["linux.patchdir"]`, supply a nonexistent path to force ignoring the patches repo (str) – Where to get Linux from, defaults to `tb.config["linux.repository"]` rev (str) – Revision from the repo to be checked out, defaults to `tb.config["linux.revision", None]`
Returns:	The Linux checkout as a meta object for other testcases
Return type:	LinuxRepository

tbot.builtin.linux.linux_tasks.linux_checkout_and_build(tb: tbot.TBot, *, builddir: typing.Union[pathlib.PurePosixPath, NoneType] = None, patchdir: typing.Union[pathlib.PurePosixPath, NoneType] = None, repo: typing.Union[str, NoneType] = None, rev: typing.Union[str, NoneType] = None, toolchain: typing.Union[tbot.tc.Toolchain, NoneType] = None, defconfig: typing.Union[str, NoneType] = None, image_type: typing.Union[str, NoneType] = None) → tbot.tc.LinuxRepository[source]¶

Checkout Linux and build it

Parameters:	builddir (pathlib.PurePosixPath) – Where to checkout Linux to, defaults to `wd / tb.config["linux.builddir"]` patchdir (pathlib.PurePosixPath) – Optional patches to be applied ontop of the tree, defaults to `tb.config["linux.patchdir"]`, supply a nonexistent path to force building without patches repo (str) – Where to get Linux from, defaults to `tb.config["linux.repository"]` rev (str) – Revision from the repo to be checked out, defaults to `tb.config["linux.revision", None]` toolchain (Toolchain) – What toolchain to use, defaults to `tb.config["board.toolchain"]` defconfig (str) – What defconfig to use, defaults to `tb.config["linux.defconfig"]`
Returns:	The Linux checkout as a meta object for other testcases
Return type:	LinuxRepository

Interactive testcases for debugging & development¶

tbot.builtin.interactive.interactive_build(tb: tbot.TBot, *, builddir: typing.Union[str, NoneType] = None, toolchain: typing.Union[tbot.tc.Toolchain, NoneType] = None) → None[source]¶

Open an interactive shell on the buildhost with the toolchain enabled.

Parameters:	builddir (pathlib.PurePosixPath) – Where U-Boot is located, defaults to `tb.config["uboot.builddir"]` toolchain (Toolchain) – Which toolchain to use, defaults to `tb.config["board.toolchain"]`

tbot.builtin.interactive.interactive_build_linux(tb: tbot.TBot) → None[source]¶: Open an interactive shell on the buildhost in the Linux builddir with the toolchain enabled.

tbot.builtin.interactive.interactive_build_uboot(tb: tbot.TBot) → None[source]¶: Open an interactive shell on the buildhost in the U-Boot builddir with the toolchain enabled.

tbot.builtin.interactive.interactive_linux(tb: tbot.TBot) → None[source]¶: Open an interactive Linux prompt on the board

tbot.builtin.interactive.interactive_uboot(tb: tbot.TBot) → None[source]¶: Open an interactive U-Boot prompt on the board

tbot.builtin.interactive.ishell(channel: paramiko.channel.Channel, *, setup: typing.Union[typing.Callable[[paramiko.channel.Channel], NoneType], NoneType] = None, abort: typing.Union[str, NoneType] = None) → None[source]¶

An interactive shell

Parameters:	channel (paramiko.channel.Channel) – Channel to use setup – An additional setup procedure to eg set a custom prompt abort (str) – A character that should not be sent to the remote but instead trigger closing the interactive session