GettingStarted.md - docs - Git at Google

 # What is this?

 This is Project Shodan, a project to research the fusion of novel hardware and
 software architectures to produce a low-power, ambient AI core. For more
 information, see our internal site at
 [sites/cerebrahardware/shodan](https://sites.google.com/corp/google.com/cerebrahardware/shodan).

 ## Developing in this Codebase

 We've stored our code in Gerrit, and like the Android developers before us, we
 use `repo` to manage the projects in our Gerrit repositories.

 To get started, first make sure you have a Git login for all our projects
 by going to [googlesource.com/new-password](https://www.googlesource.com/new-password)
 and pasting the provided script into a terminal.

 Now you need to pull down a copy of the `repo`
 tool from our public facing sites and add it to your path:

 ```bash
 mkdir -p bin
 export PATH=$PATH:$HOME/bin
 curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
 chmod a+x ~/bin/repo
 ```

 Make sure you've initialized git with your name and email address, and have
 configured it properly for fetching the sources:

 ```bash
 git config --global user.name "Your Name"
 git config --global user.email "you@example.com"
 ```

 Once you've done this, you're actually ready to check out the sources. Make a
 new directory where you'd like it to live, and initialize `repo` with the
 current release branch.

 ```bash
 repo init -u https://spacebeaker.googlesource.com/shodan/manifest -g default,internal
 repo sync -j$(nproc)
 ```

 ## System Setup for Development

 Development for shodan requires that the necessary tools and prerequisites be
 installed.

 To setup the build system:

 ```bash
 source build/setup.sh
 ```

 Install the prerequisites:

 ```bash
 m prereqs
 ```

 Install the RISCV toolchain:

 ```bash
 m tools
 ```

 Install the instruction set simulator:

 ```bash
 m sim
 ```

 ## Day-to-day Development Workflow

 In general, working with repo is relatively simple:

   1. Create a working topic branch to make changes on with `repo start
      ${TOPICNAME}`
   2. Make your changes to the files. Add them with `git add -A` and commit with
      `git commit`.
   3. Upload your changes with `repo upload --re ${REVIEWER} --cc ${CC_LIST}`
   4. Go to the URL repo spits out to read and reply to comments.
   5. Eventually your reviewer will give you a +2 LGTM on your change. To submit,
      click the "SUBMIT" button on the change in the web interface.
   6. Run `repo sync -j$(nproc)` to update.
   7. Run `repo prune` to remove your topic branch.

 For more information on how to use repo and git effectively, take a look at the
 [official documentation](https://source.android.com/setup/create/coding-tasks).

 ### How to sync my local copy with latest?

 ```bash
 repo sync -j$(nproc)
 ```

 Then if you have any outstanding branches, a `repo rebase` will help.

 ### How to send code for review?

 To upload a branch to gerrit for review, do this:

 ```bash
 repo upload --re reviewer1,reviewer2 --cc email@host.com,email2@host2.com
 ```

 Reviewers can be specified as usernames or full email addresses, likewise for
 `--cc`.

 Repo will then output a URL for you to visit that allows you to make comments
 and abandon and merge the changes into the repository. To make changes during
 the review process, make your changes to the files, then:

 ```bash
 git add -A                                    # To add the files you've changed
 git commit --amend                            # To update the previous change
 repo upload -t --re ${REVIEWER} --cc ${CC_LIST} # To upload the change to Gerrit for review
 ```

 ## Repository Layout

 Our layout is pretty simple:

 ### hw/

 Contains all of the source code and RTL required to build the Shodan
 hardware, as well as simulate it in Verilator.

 ### build/

 Contains build scripts for the whole tree. This is effectively just an
 orchestration layer to make building the whole shebang easier. Each subtree may
 have its own build systems and have their own ways of building.

 ### cache/

 The cached cross-compilation toolchain, including rust and RISC-V GCC/LLVM
 toolchain.

 ### cicd/

 Contains continuous integration scripts and tooling for Jenkins, our CI/CD tool.

 ### docs/

 Lots of extra documentation (we hope) about how the repo is laid out, how the
 build system works, code reviews, licensing, etc.

 ### manifest/

 The repo manifest used to glue all the git repositories together.

 ### scripts/

 Contains utility scripts to help automate a few things.

 ### sim/

 Contains tools and src for simulation of the shodan hw.

 ### toolchain/

 Contains the src to build the RISCV QEMU emulator, and
 [IREE](https://github/com/google/iree) toolchain for ML models.

 ## Start a simulation

 The simulator used for Shodan is [Renode](https://renode.io/).
 After building and installing the simulator it can be run
 by using the alias `renode`.

 This alias is equivalent to the command:

 ```bash
 mono cache/renode/Renode.exe
 ```

 The configuration for the Shodan SoC is `sim/config/shodan.repl`,
 and an example of running zephyr on Shodan can be run as below:

 ```bash
 include @sim/config/shodan_zephyr.resc
 start
 ```

 ## Build and test ML artifacts

 The ML executable is built with [IREE](https://github.com/google/iree) workflow,
 targeted to RISCV 32-bit bare-metal config.

 To retrieve the IREE RISC-V toolchain and Renode emulator:

 ```bash
 m tools
 ```

 To build the IREE targets:

 ```bash
 m iree
 ```

 The IREE compiler sits in `out/host/iree_compiler`, while the runtime library/example
 sits in `out/springbok_iree`.
 To run the toy example (four-element vector element-wise multiplication) for
 testing:

 ```bash
 sim_springbok out/springbok_iree/iree/iree/samples/simple_embedding/simple_embedding_embedded_sync
 ```

 The output should be shown as:

 ```bash
 (machine-0) 18:05:23.6463 [INFO] cpu2: simprint: "simple_embedding done", 0 (0x0)
 18:05:23.6475 [INFO] cpu2: simprint: "main returned: ", 0 (0x0)
 ```

 (Enter quit to exit the Renode simulation)

 ## More Information

 - [Information on how to use repo](https://go/repo)
	# What is this?

	This is Project Shodan, a project to research the fusion of novel hardware and
	software architectures to produce a low-power, ambient AI core. For more
	information, see our internal site at
	[sites/cerebrahardware/shodan](https://sites.google.com/corp/google.com/cerebrahardware/shodan).

	## Developing in this Codebase

	We've stored our code in Gerrit, and like the Android developers before us, we
	use `repo` to manage the projects in our Gerrit repositories.

	To get started, first make sure you have a Git login for all our projects
	by going to [googlesource.com/new-password](https://www.googlesource.com/new-password)
	and pasting the provided script into a terminal.

	Now you need to pull down a copy of the `repo`
	tool from our public facing sites and add it to your path:

	```bash
	mkdir -p bin
	export PATH=$PATH:$HOME/bin
	curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
	chmod a+x ~/bin/repo
	```

	Make sure you've initialized git with your name and email address, and have
	configured it properly for fetching the sources:

	```bash
	git config --global user.name "Your Name"
	git config --global user.email "you@example.com"
	```

	Once you've done this, you're actually ready to check out the sources. Make a
	new directory where you'd like it to live, and initialize `repo` with the
	current release branch.

	```bash
	repo init -u https://spacebeaker.googlesource.com/shodan/manifest -g default,internal
	repo sync -j$(nproc)
	```

	## System Setup for Development

	Development for shodan requires that the necessary tools and prerequisites be
	installed.

	To setup the build system:

	```bash
	source build/setup.sh
	```

	Install the prerequisites:

	```bash
	m prereqs
	```

	Install the RISCV toolchain:

	```bash
	m tools
	```

	Install the instruction set simulator:

	```bash
	m sim
	```

	## Day-to-day Development Workflow

	In general, working with repo is relatively simple:

	1. Create a working topic branch to make changes on with `repo start
	${TOPICNAME}`
	2. Make your changes to the files. Add them with `git add -A` and commit with
	`git commit`.
	3. Upload your changes with `repo upload --re ${REVIEWER} --cc ${CC_LIST}`
	4. Go to the URL repo spits out to read and reply to comments.
	5. Eventually your reviewer will give you a +2 LGTM on your change. To submit,
	click the "SUBMIT" button on the change in the web interface.
	6. Run `repo sync -j$(nproc)` to update.
	7. Run `repo prune` to remove your topic branch.

	For more information on how to use repo and git effectively, take a look at the
	[official documentation](https://source.android.com/setup/create/coding-tasks).

	### How to sync my local copy with latest?

	```bash
	repo sync -j$(nproc)
	```

	Then if you have any outstanding branches, a `repo rebase` will help.

	### How to send code for review?

	To upload a branch to gerrit for review, do this:

	```bash
	repo upload --re reviewer1,reviewer2 --cc email@host.com,email2@host2.com
	```

	Reviewers can be specified as usernames or full email addresses, likewise for
	`--cc`.

	Repo will then output a URL for you to visit that allows you to make comments
	and abandon and merge the changes into the repository. To make changes during
	the review process, make your changes to the files, then:

	```bash
	git add -A # To add the files you've changed
	git commit --amend # To update the previous change
	repo upload -t --re ${REVIEWER} --cc ${CC_LIST} # To upload the change to Gerrit for review
	```

	## Repository Layout

	Our layout is pretty simple:

	### hw/

	Contains all of the source code and RTL required to build the Shodan
	hardware, as well as simulate it in Verilator.

	### build/

	Contains build scripts for the whole tree. This is effectively just an
	orchestration layer to make building the whole shebang easier. Each subtree may
	have its own build systems and have their own ways of building.

	### cache/

	The cached cross-compilation toolchain, including rust and RISC-V GCC/LLVM
	toolchain.

	### cicd/

	Contains continuous integration scripts and tooling for Jenkins, our CI/CD tool.

	### docs/

	Lots of extra documentation (we hope) about how the repo is laid out, how the
	build system works, code reviews, licensing, etc.

	### manifest/

	The repo manifest used to glue all the git repositories together.

	### scripts/

	Contains utility scripts to help automate a few things.

	### sim/

	Contains tools and src for simulation of the shodan hw.

	### toolchain/

	Contains the src to build the RISCV QEMU emulator, and
	[IREE](https://github/com/google/iree) toolchain for ML models.

	## Start a simulation

	The simulator used for Shodan is [Renode](https://renode.io/).
	After building and installing the simulator it can be run
	by using the alias `renode`.

	This alias is equivalent to the command:

	```bash
	mono cache/renode/Renode.exe
	```

	The configuration for the Shodan SoC is `sim/config/shodan.repl`,
	and an example of running zephyr on Shodan can be run as below:

	```bash
	include @sim/config/shodan_zephyr.resc
	start
	```

	## Build and test ML artifacts

	The ML executable is built with [IREE](https://github.com/google/iree) workflow,
	targeted to RISCV 32-bit bare-metal config.

	To retrieve the IREE RISC-V toolchain and Renode emulator:

	```bash
	m tools
	```

	To build the IREE targets:

	```bash
	m iree
	```

	The IREE compiler sits in `out/host/iree_compiler`, while the runtime library/example
	sits in `out/springbok_iree`.
	To run the toy example (four-element vector element-wise multiplication) for
	testing:

	```bash
	sim_springbok out/springbok_iree/iree/iree/samples/simple_embedding/simple_embedding_embedded_sync
	```

	The output should be shown as:

	```bash
	(machine-0) 18:05:23.6463 [INFO] cpu2: simprint: "simple_embedding done", 0 (0x0)
	18:05:23.6475 [INFO] cpu2: simprint: "main returned: ", 0 (0x0)
	```

	(Enter quit to exit the Renode simulation)

	## More Information

	- [Information on how to use repo](https://go/repo)