docs/GettingStarted.md - sw/cantrip/userland - Git at Google


 ## Getting started with repo & the build system.

 CantripOS includes a multi-platform build framework.
 This framwork leverages make, cmake, and cargo.
 To get started follow these steps:

 1. Clone the Sparrow project from GitHub using the
    [repo tool](https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md)
    We assume below this lands in a top-level directory named "sparrow".
 2. Download, build, and boot the system to the Cantrip shell prompt.
    For now the only target platform that works is "rpi3"
    (for a raspi3b machine running in simulation on qemu).

 ``` shell
 mkdir sparrow
 cd sparrow
 repo init -u https://github.com/AmbiML/sparrow-manifest -m sparrow-manifest.xml
 repo sync -j$(nproc)
 export PLATFORM=rpi3
 source build/setup.sh
 m prereqs
 m simulate
 ```

 [Beware that if your repo tool is out of date you may need to supply `-b main`
 to the init request as older versions of repo only check for a `master` branch.]

 ### Prerequisites.

 Note the above assumes you have the follow prerequisites installed on your system
 and **in your shell's search path**:
 1. Gcc (or clang) for the target architecture
 2. Rust; any nightly build >=nightly-2021-11-05 should work. A default version is set
    in the build/setup.sh script; if that is not what you are using either edit the shell
    script or export `CANTRIP_RUST_VERSION` in each shell where you work.
    Beware that we use various nightly-only features that are not supported by stable
    versions of Rust (e.g. to override the default TLS model).
 3. Whichever simulator seL4 expects for your target architecture; e.g. for aarch64 this
    is qemu-system-aarch64.

 The `m prereqs` step installs required python packages using the `pip`
 tool. At the moment this mostly sets up a virtual environment for the
 project.

 Because Shodan is a CAmkES project you also need
 [CAmkES dependencies](https://docs.sel4.systems/projects/buildsystem/host-dependencies.html#camkes-build-dependencies).

 ### First time setup.

 Sparrow uses [repo](https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md)
 to download and piece together Sparrow git repositories as well as dependent projects /
 repositories such as [seL4](https://github.com/seL4).

 ``` shell
 $ repo init -u https://github.com/AmbiML/sparrow-manifest -m sparrow-manifest.xml
 Downloading Repo source from https://gerrit.googlesource.com/git-repo

 repo has been initialized in <your-directory>/sparrow/
 If this is not the directory in which you want to initialize repo, please run:
    rm -r <your-directory>/sparrow//.repo
 and try again.
 $ repo sync -j12
 Fetching: 100% (23/23), done in 9.909s
 Garbage collecting: 100% (23/23), done in 0.218s
 Checking out: 100% (23/23), done in 0.874s
 repo sync has finished successfully.
 $ export PLATFORM=rpi3
 $ export CANTRIP_RUST_VERSION=nightly
 $ source build/setup.sh
 ========================================
 ROOTDIR=/<your-directory>/sparrow
 OUT=/<your-directory>/sparrow/out
 PLATFORM=rpi3
 PYTHON_SPARROW_ENV=<your-directory>/sparrow/cache/rpi3-venv
 ========================================

 Type 'm [target]' to build.

 Targets available are:

 ...
 cantrip cantrip-build-debug-prepare cantrip-build-release-prepare cantrip-builtins
 cantrip-builtins-debug cantrip-builtins-release cantrip-bundle-debug cantrip-bundle-release
 cantrip-clean cantrip-clean-headers cantrip-clippy cantrip-component-headers
 ...
 $ m prereqs
 <your-directory>/sparrow/scripts/install-prereqs.sh \
         -p "<your-directory>/sparrow/scripts/python-requirements.txt \
                  " \
         -a ""
 Installing apt package dependencies...
 Installing python package dependencies...
 Creating virtual python environment <your-directory>/sparrow/cache/rpi3-venv
 ...
 Installation complete.
 $ m simulate
 ...
 info: component 'rust-std' for target 'aarch64-unknown-none' is up to date
 loading initial cache file <your-directory>/sparrow/cantrip/projects/camkes/settings.cmake
 -- Set platform details from PLATFORM=rpi3
 --   KernelPlatform: bcm2837
 --   KernelARMPlatform: rpi3
 -- Setting from flags KernelSel4Arch: aarch64
 -- Found seL4: <your-directory>/sparrow/kernel
 -- The C compiler identification is GNU 11.2.1
 ...
 [291/291] Generating images/capdl-loader-image-arm-bcm2837
 ...
 qemu-system-aarch64 -machine raspi3b -nographic -serial null -serial mon:stdio -m size=1024M -s \
 -kernel /<your-directory>/sparrow/out/cantrip/aarch64-unknown-elf/release/capdl-loader-image \
 --mem-path /<your-directory>/sparrow/out/cantrip/aarch64-unknown-elf/release/cantrip.mem

 ELF-loader started on CPU: ARM Ltd. Cortex-A53 r0p4
   paddr=[8bd000..fed0ff]
 No DTB passed in from boot loader.
 Looking for DTB in CPIO archive...found at 9b3ef8.
 Loaded DTB from 9b3ef8.
    paddr=[23c000..23ffff]
 ELF-loading image 'kernel' to 0
   paddr=[0..23bfff]
   vaddr=[ffffff8000000000..ffffff800023bfff]
   virt_entry=ffffff8000000000
 ELF-loading image 'capdl-loader' to 240000
   paddr=[240000..4c0fff]
   vaddr=[400000..680fff]
   virt_entry=4009e8
 Enabling MMU and paging
 Jumping to kernel-image entry point...

 Warning:  gpt_cntfrq 62500000, expected 19200000
 Bootstrapping kernel
 Booting all finished, dropped to user space
 cantrip_os_rootserver::Bootinfo: (1969, 131072) empty slots 1 nodes (15, 83) untyped 131072 cnode slots
 cantrip_os_rootserver::Model: 1821 objects 1 irqs 0 untypeds 2 asids
 cantrip_os_rootserver::capDL spec: 0.39 Mbytes
 cantrip_os_rootserver::CAmkES components: 5.85 Mbytes
 cantrip_os_rootserver::Rootserver executable: 1.07 Mbytes
 <<seL4(CPU 0) [decodeARMFrameInvocation/2137 T0xffffff80004c7400 "rootserver" @44373c]: ARMPageMap: Attempting to remap a frame that does not belong to the passed address space>>
 ...
 <<seL4(CPU 0) [decodeCNodeInvocation/107 T0xffffff80009a3400 "rootserver" @4268a0]: CNode Copy/Mint/Move/Mutate: Source slot invalid or empty.>>
 ...
 CANTRIP> builtins
 autostart.repl 336
 hello.app 1084
 keyval.app 32276
 logtest.app 26948
 panic.app 25688
 timer.app 33060
 CANTRIP> install hello.app
 cantrip_memory_manager::Global memory: 0 allocated 130543360 free, reserved: 2273280 kernel 1359872 user
 Collected 1084 bytes of data, crc32 5b847193
 Application "hello" installed
 CANTRIP> start hello
 Bundle "hello" started.
 CANTRIP> install keyval.app

 I am a C app!
 Done, sleeping in WFI loop
 Collected 32276 bytes of data, crc32 bcf05273
 Application "keyval" installed
 CANTRIP> start keyval
 Bundle "keyval" started.
 ...
 CANTRIP> mstats
 48 bytes in-use, 130543312 bytes free, 720512 bytes requested, 1359872 overhead
 2 objs in-use, 196 objs requested
 CANTRIP> EOF
 ```

 The `m simulate` command can be run repeatedly. If you need to reset
 your setup just remove the build tree and re-run `m simulate`; e.g.

 ``` shell
 $ cd sparrow
 $ m clean
 $ m simulate
 ```

 ### Build system: primer.

 The setup procedure required:

 ``` shell
 $ export PLATFORM=rpi3
 $ export CANTRIP_RUST_VERSION=nightly  # force use of "nightly" channel
 $ source build/setup.sh
 ```

 This defined various shell functions/aliases for working with CantripOS. In particular
 the `m` command is the primary mechanism for building and running simulations.
 The default target command is `simulate` so these are equivalent:

 ``` shell
 $ m simulate
 $ m               # default target is simulate
 ```

 As seen above, another useful target is `m simulate-debug` which builds a debug version
 of the system and starts up a simulator. In this case the simulator (platform-dependent)
 supports connecting GDB with scripts/kgdb.sh in a separate window/terminal. For more
 information on using GDB with seL4 check [here](CantripGdbUserSpaceDebugging.md).

 There is tab completion for build targets depending on your shell; e.g.

 ``` shell
 $ m <TAB>
 cargo_test_debugconsole_zmodem            kata-gen-headers
 cargo_test_kata                           keyval_debug
 cargo_test_kata_os_common_logger          keyval_release
 cargo_test_kata_os_common_slot_allocator  logtest_debug
 cargo_test_kata_proc_interface            logtest_release
 cargo_test_kata_proc_manager              matcha_tock_clean
 clean                                     matcha_tock_debug
 collate_kata_rust_toolchain               matcha_tock_release
 collate_matcha_rust_toolchain             minisel_debug
 collate_rust_toolchains                   minisel_release
 elfconvert                                multihart_boot_rom
 fibonacci_debug                           multihart_boot_rom_clean
 fibonacci_release                         panic_debug
 flatbuffers                               panic_release
 flatbuffers-clean                         prereqs
 ...
 ```

 There is also a `hmm`
 command that can display help information for a build target. For example,

 ``` shell
 $ hmm sel4test

 sel4test: (defined in build/platforms/shodan/sim_sel4test.mk)
  C-based libsel4 syscall api wrappers. The result is run under Renode.
 ```

 ### Build system: multi-platform support.

 The build system supports multiple target platforms. But at the moment there are
 only two platforms--shodan & rpi3--so this is less exciting. The current
 platform is kept in your shell's environmnet so after a default setup you will see:

 ``` shell
 $ source build/setup.sh
 $ printenv PLATFORM
 shodan
 ```

 But this also means that you need to `source build/setup.sh` in each shell
 where you work on the software.

 To switch the current platform use the `set-platform` shell function:

 ``` shell
 $ set-platform rpi3
 $ printenv PLATFORM
 rpi3
 ```

 There is also a `list-platforms` shell function that you can use in lieu of
 tab completion with the `set-platform` command.

 ### Build system: cleaning build artifacts

 Most of the time `m simulate` or `m simulate-debug` is all you need to do work:
 make dependencies will cause only necessary operations to be done.
 But sometimes it's necessary to remove build artifacts (e.g. because depeencies
 are incorrect or the dependencies are overly conservative resulting in excessive
 build steps).
 Therre are many targets that selectively clear out unwanted artifacts but most
 of the time you will just want to use:

 ``` shell
 $ m cantrip-clean
 ```

 which removes all build artifacts for the current platform, or

 ```shell
 $ m clean
 ```

 which removes all build artifacts for all platforms.

 ### [Next Section: CantripOS software organization](SourceCrates.md)

	## Getting started with repo & the build system.

	CantripOS includes a multi-platform build framework.
	This framwork leverages make, cmake, and cargo.
	To get started follow these steps:

	1. Clone the Sparrow project from GitHub using the
	[repo tool](https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md)
	We assume below this lands in a top-level directory named "sparrow".
	2. Download, build, and boot the system to the Cantrip shell prompt.
	For now the only target platform that works is "rpi3"
	(for a raspi3b machine running in simulation on qemu).

	``` shell
	mkdir sparrow
	cd sparrow
	repo init -u https://github.com/AmbiML/sparrow-manifest -m sparrow-manifest.xml
	repo sync -j$(nproc)
	export PLATFORM=rpi3
	source build/setup.sh
	m prereqs
	m simulate
	```

	[Beware that if your repo tool is out of date you may need to supply `-b main`
	to the init request as older versions of repo only check for a `master` branch.]

	### Prerequisites.

	Note the above assumes you have the follow prerequisites installed on your system
	and in your shell's search path:
	1. Gcc (or clang) for the target architecture
	2. Rust; any nightly build >=nightly-2021-11-05 should work. A default version is set
	in the build/setup.sh script; if that is not what you are using either edit the shell
	script or export `CANTRIP_RUST_VERSION` in each shell where you work.
	Beware that we use various nightly-only features that are not supported by stable
	versions of Rust (e.g. to override the default TLS model).
	3. Whichever simulator seL4 expects for your target architecture; e.g. for aarch64 this
	is qemu-system-aarch64.

	The `m prereqs` step installs required python packages using the `pip`
	tool. At the moment this mostly sets up a virtual environment for the
	project.

	Because Shodan is a CAmkES project you also need
	[CAmkES dependencies](https://docs.sel4.systems/projects/buildsystem/host-dependencies.html#camkes-build-dependencies).

	### First time setup.

	Sparrow uses [repo](https://gerrit.googlesource.com/git-repo/+/refs/heads/master/README.md)
	to download and piece together Sparrow git repositories as well as dependent projects /
	repositories such as [seL4](https://github.com/seL4).

	``` shell
	$ repo init -u https://github.com/AmbiML/sparrow-manifest -m sparrow-manifest.xml
	Downloading Repo source from https://gerrit.googlesource.com/git-repo

	repo has been initialized in <your-directory>/sparrow/
	If this is not the directory in which you want to initialize repo, please run:
	rm -r <your-directory>/sparrow//.repo
	and try again.
	$ repo sync -j12
	Fetching: 100% (23/23), done in 9.909s
	Garbage collecting: 100% (23/23), done in 0.218s
	Checking out: 100% (23/23), done in 0.874s
	repo sync has finished successfully.
	$ export PLATFORM=rpi3
	$ export CANTRIP_RUST_VERSION=nightly
	$ source build/setup.sh
	========================================
	ROOTDIR=/<your-directory>/sparrow
	OUT=/<your-directory>/sparrow/out
	PLATFORM=rpi3
	PYTHON_SPARROW_ENV=<your-directory>/sparrow/cache/rpi3-venv
	========================================

	Type 'm [target]' to build.

	Targets available are:

	...
	cantrip cantrip-build-debug-prepare cantrip-build-release-prepare cantrip-builtins
	cantrip-builtins-debug cantrip-builtins-release cantrip-bundle-debug cantrip-bundle-release
	cantrip-clean cantrip-clean-headers cantrip-clippy cantrip-component-headers
	...
	$ m prereqs
	<your-directory>/sparrow/scripts/install-prereqs.sh \
	-p "<your-directory>/sparrow/scripts/python-requirements.txt \
	" \
	-a ""
	Installing apt package dependencies...
	Installing python package dependencies...
	Creating virtual python environment <your-directory>/sparrow/cache/rpi3-venv
	...
	Installation complete.
	$ m simulate
	...
	info: component 'rust-std' for target 'aarch64-unknown-none' is up to date
	loading initial cache file <your-directory>/sparrow/cantrip/projects/camkes/settings.cmake
	-- Set platform details from PLATFORM=rpi3
	-- KernelPlatform: bcm2837
	-- KernelARMPlatform: rpi3
	-- Setting from flags KernelSel4Arch: aarch64
	-- Found seL4: <your-directory>/sparrow/kernel
	-- The C compiler identification is GNU 11.2.1
	...
	[291/291] Generating images/capdl-loader-image-arm-bcm2837
	...
	qemu-system-aarch64 -machine raspi3b -nographic -serial null -serial mon:stdio -m size=1024M -s \
	-kernel /<your-directory>/sparrow/out/cantrip/aarch64-unknown-elf/release/capdl-loader-image \
	--mem-path /<your-directory>/sparrow/out/cantrip/aarch64-unknown-elf/release/cantrip.mem

	ELF-loader started on CPU: ARM Ltd. Cortex-A53 r0p4
	paddr=[8bd000..fed0ff]
	No DTB passed in from boot loader.
	Looking for DTB in CPIO archive...found at 9b3ef8.
	Loaded DTB from 9b3ef8.
	paddr=[23c000..23ffff]
	ELF-loading image 'kernel' to 0
	paddr=[0..23bfff]
	vaddr=[ffffff8000000000..ffffff800023bfff]
	virt_entry=ffffff8000000000
	ELF-loading image 'capdl-loader' to 240000
	paddr=[240000..4c0fff]
	vaddr=[400000..680fff]
	virt_entry=4009e8
	Enabling MMU and paging
	Jumping to kernel-image entry point...

	Warning: gpt_cntfrq 62500000, expected 19200000
	Bootstrapping kernel
	Booting all finished, dropped to user space
	cantrip_os_rootserver::Bootinfo: (1969, 131072) empty slots 1 nodes (15, 83) untyped 131072 cnode slots
	cantrip_os_rootserver::Model: 1821 objects 1 irqs 0 untypeds 2 asids
	cantrip_os_rootserver::capDL spec: 0.39 Mbytes
	cantrip_os_rootserver::CAmkES components: 5.85 Mbytes
	cantrip_os_rootserver::Rootserver executable: 1.07 Mbytes
	<<seL4(CPU 0) [decodeARMFrameInvocation/2137 T0xffffff80004c7400 "rootserver" @44373c]: ARMPageMap: Attempting to remap a frame that does not belong to the passed address space>>
	...
	<<seL4(CPU 0) [decodeCNodeInvocation/107 T0xffffff80009a3400 "rootserver" @4268a0]: CNode Copy/Mint/Move/Mutate: Source slot invalid or empty.>>
	...
	CANTRIP> builtins
	autostart.repl 336
	hello.app 1084
	keyval.app 32276
	logtest.app 26948
	panic.app 25688
	timer.app 33060
	CANTRIP> install hello.app
	cantrip_memory_manager::Global memory: 0 allocated 130543360 free, reserved: 2273280 kernel 1359872 user
	Collected 1084 bytes of data, crc32 5b847193
	Application "hello" installed
	CANTRIP> start hello
	Bundle "hello" started.
	CANTRIP> install keyval.app

	I am a C app!
	Done, sleeping in WFI loop
	Collected 32276 bytes of data, crc32 bcf05273
	Application "keyval" installed
	CANTRIP> start keyval
	Bundle "keyval" started.
	...
	CANTRIP> mstats
	48 bytes in-use, 130543312 bytes free, 720512 bytes requested, 1359872 overhead
	2 objs in-use, 196 objs requested
	CANTRIP> EOF
	```

	The `m simulate` command can be run repeatedly. If you need to reset
	your setup just remove the build tree and re-run `m simulate`; e.g.

	``` shell
	$ cd sparrow
	$ m clean
	$ m simulate
	```

	### Build system: primer.

	The setup procedure required:

	``` shell
	$ export PLATFORM=rpi3
	$ export CANTRIP_RUST_VERSION=nightly # force use of "nightly" channel
	$ source build/setup.sh
	```

	This defined various shell functions/aliases for working with CantripOS. In particular
	the `m` command is the primary mechanism for building and running simulations.
	The default target command is `simulate` so these are equivalent:

	``` shell
	$ m simulate
	$ m # default target is simulate
	```

	As seen above, another useful target is `m simulate-debug` which builds a debug version
	of the system and starts up a simulator. In this case the simulator (platform-dependent)
	supports connecting GDB with scripts/kgdb.sh in a separate window/terminal. For more
	information on using GDB with seL4 check [here](CantripGdbUserSpaceDebugging.md).

	There is tab completion for build targets depending on your shell; e.g.

	``` shell
	$ m <TAB>
	cargo_test_debugconsole_zmodem kata-gen-headers
	cargo_test_kata keyval_debug
	cargo_test_kata_os_common_logger keyval_release
	cargo_test_kata_os_common_slot_allocator logtest_debug
	cargo_test_kata_proc_interface logtest_release
	cargo_test_kata_proc_manager matcha_tock_clean
	clean matcha_tock_debug
	collate_kata_rust_toolchain matcha_tock_release
	collate_matcha_rust_toolchain minisel_debug
	collate_rust_toolchains minisel_release
	elfconvert multihart_boot_rom
	fibonacci_debug multihart_boot_rom_clean
	fibonacci_release panic_debug
	flatbuffers panic_release
	flatbuffers-clean prereqs
	...
	```

	There is also a `hmm`
	command that can display help information for a build target. For example,

	``` shell
	$ hmm sel4test

	sel4test: (defined in build/platforms/shodan/sim_sel4test.mk)
	C-based libsel4 syscall api wrappers. The result is run under Renode.
	```

	### Build system: multi-platform support.

	The build system supports multiple target platforms. But at the moment there are
	only two platforms--shodan & rpi3--so this is less exciting. The current
	platform is kept in your shell's environmnet so after a default setup you will see:

	``` shell
	$ source build/setup.sh
	$ printenv PLATFORM
	shodan
	```

	But this also means that you need to `source build/setup.sh` in each shell
	where you work on the software.

	To switch the current platform use the `set-platform` shell function:

	``` shell
	$ set-platform rpi3
	$ printenv PLATFORM
	rpi3
	```

	There is also a `list-platforms` shell function that you can use in lieu of
	tab completion with the `set-platform` command.

	### Build system: cleaning build artifacts

	Most of the time `m simulate` or `m simulate-debug` is all you need to do work:
	make dependencies will cause only necessary operations to be done.
	But sometimes it's necessary to remove build artifacts (e.g. because depeencies
	are incorrect or the dependencies are overly conservative resulting in excessive
	build steps).
	Therre are many targets that selectively clear out unwanted artifacts but most
	of the time you will just want to use:

	``` shell
	$ m cantrip-clean
	```

	which removes all build artifacts for the current platform, or

	```shell
	$ m clean
	```

	which removes all build artifacts for all platforms.

	### [Next Section: CantripOS software organization](SourceCrates.md)