June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 1 | # What is this? |
| 2 | |
| 3 | This is Project Shodan, a project to research the fusion of novel hardware and |
| 4 | software architectures to produce a low-power, ambient AI core. For more |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 5 | information, see our |
| 6 | [internal site](https://sites.google.com/corp/google.com/cerebrahardware/projects/current-projects/shodan). |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 7 | |
| 8 | ## Developing in this Codebase |
| 9 | |
| 10 | We've stored our code in Gerrit, and like the Android developers before us, we |
| 11 | use `repo` to manage the projects in our Gerrit repositories. |
| 12 | |
| 13 | To get started, first make sure you have a Git login for all our projects |
| 14 | by going to [googlesource.com/new-password](https://www.googlesource.com/new-password) |
| 15 | and pasting the provided script into a terminal. |
| 16 | |
| 17 | Now you need to pull down a copy of the `repo` |
| 18 | tool from our public facing sites and add it to your path: |
| 19 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 20 | ```bash |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 21 | mkdir -p bin |
| 22 | export PATH=$PATH:$HOME/bin |
| 23 | curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo |
| 24 | chmod a+x ~/bin/repo |
| 25 | ``` |
| 26 | |
| 27 | Make sure you've initialized git with your name and email address, and have |
| 28 | configured it properly for fetching the sources: |
| 29 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 30 | ```bash |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 31 | git config --global user.name "Your Name" |
| 32 | git config --global user.email "you@example.com" |
| 33 | ``` |
| 34 | |
| 35 | Once you've done this, you're actually ready to check out the sources. Make a |
| 36 | new directory where you'd like it to live, and initialize `repo` with the |
| 37 | current release branch. |
| 38 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 39 | ```bash |
Cindy Liu | 73984b0 | 2021-09-09 13:46:41 -0700 | [diff] [blame] | 40 | repo init -u https://spacebeaker.googlesource.com/shodan/manifest -g default,internal --no-use-superproject |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 41 | repo sync -j$(nproc) |
| 42 | ``` |
| 43 | |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 44 | ## System Setup for Development |
| 45 | |
| 46 | Development for shodan requires that the necessary tools and prerequisites be |
| 47 | installed. |
| 48 | |
| 49 | To setup the build system: |
| 50 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 51 | ```bash |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 52 | source build/setup.sh |
| 53 | ``` |
| 54 | |
Julian Mullings-Black | 1b83319 | 2022-07-19 00:47:15 +0000 | [diff] [blame] | 55 | For non-gLinux systems: Add the bazel apt repository to your machines sources. |
| 56 | Instructions @ https://bazel.build/install/ubuntu#add-dis-uri |
| 57 | |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 58 | Install the prerequisites: |
| 59 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 60 | ```bash |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 61 | m prereqs |
| 62 | ``` |
| 63 | |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 64 | Install the tools used for development: |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 65 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 66 | ```bash |
Jonas Larsson | b490c4e | 2022-11-09 11:03:33 -0800 | [diff] [blame] | 67 | m tools -j$(nproc) |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 68 | ``` |
| 69 | |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 70 | ## Day-to-day Development Workflow |
| 71 | |
June Tate-Gans | 0ff4789 | 2020-06-25 17:11:03 -0500 | [diff] [blame] | 72 | In general, working with repo is relatively simple: |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 73 | |
| 74 | 1. Create a working topic branch to make changes on with `repo start |
| 75 | ${TOPICNAME}` |
| 76 | 2. Make your changes to the files. Add them with `git add -A` and commit with |
| 77 | `git commit`. |
June Tate-Gans | 0ff4789 | 2020-06-25 17:11:03 -0500 | [diff] [blame] | 78 | 3. Upload your changes with `repo upload --re ${REVIEWER} --cc ${CC_LIST}` |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 79 | 4. Go to the URL repo spits out to read and reply to comments. |
| 80 | 5. Eventually your reviewer will give you a +2 LGTM on your change. To submit, |
| 81 | click the "SUBMIT" button on the change in the web interface. |
| 82 | 6. Run `repo sync -j$(nproc)` to update. |
| 83 | 7. Run `repo prune` to remove your topic branch. |
| 84 | |
| 85 | For more information on how to use repo and git effectively, take a look at the |
| 86 | [official documentation](https://source.android.com/setup/create/coding-tasks). |
| 87 | |
June Tate-Gans | e8c4a09 | 2022-04-18 20:35:57 +0000 | [diff] [blame] | 88 | ### A Note on Code Review Policies |
| 89 | |
| 90 | In the Shodan project, we follow a "sticky +2" policy. |
| 91 | |
| 92 | What this means is that you *must* get a +2 Code Review from a peer, or a TL. |
Cindy Liu | 9b2a2c1 | 2022-05-02 14:56:13 -0700 | [diff] [blame] | 93 | Gerrit will automatically pass any +2 Code Review scores you receive when you |
| 94 | upload a patchset with minor changes. This policy is in place so that we can |
| 95 | quickly get through code review and get our code submitted without requiring |
| 96 | lots of round-trips with your reviewers. |
June Tate-Gans | e8c4a09 | 2022-04-18 20:35:57 +0000 | [diff] [blame] | 97 | |
| 98 | If you change significant parts of the CL post-+2, please ask for additional |
| 99 | review from your peers in a reply. Note: two +1s does *not* count as a +2! |
| 100 | |
Cindy Liu | 9b2a2c1 | 2022-05-02 14:56:13 -0700 | [diff] [blame] | 101 | You can't self-+2 your own CL, no matter the urgency or how simple the |
| 102 | change is! This policy ensures the code change is peer reviewed, and prevent us |
| 103 | from getting in trouble with security/compliance. If you don't know who to send |
| 104 | a CL to, put one of the TLs on the review list, and they'll redirect it |
| 105 | appropriately, or review your change. |
June Tate-Gans | e8c4a09 | 2022-04-18 20:35:57 +0000 | [diff] [blame] | 106 | |
Cindy Liu | 9b2a2c1 | 2022-05-02 14:56:13 -0700 | [diff] [blame] | 107 | As a reviewer, please use good judgement to help the team keep the good |
| 108 | momentum: If you provide a +1 score, please note in your comment who should |
| 109 | provide the +2; if your comments are minor changes about style, format, etc., |
| 110 | and not related to the functionality of the code, please provide +2 so the code |
| 111 | owner can address the comments and submit the code without further review. |
June Tate-Gans | e8c4a09 | 2022-04-18 20:35:57 +0000 | [diff] [blame] | 112 | |
| 113 | ### Who are the TLs? |
| 114 | |
| 115 | At the time of this writing, the TLs are: |
| 116 | |
| 117 | Cindy Liu <hcindyl@> |
| 118 | June Tate-Gans <jtgans@> |
| 119 | Bangfei Pan <pbf@> |
| 120 | Steve Xu <stevexu@> |
| 121 | |
| 122 | Finally, if you can't get one of the above people, please put Kai Yick |
| 123 | <kingkai@> on the review line. |
| 124 | |
| 125 | *Special note if you're listed above*: you still must get your +2 from someone |
| 126 | else -- we need the TLs to lead by example and demonstrate the appropriate |
| 127 | behavior. |
| 128 | |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 129 | ### How to sync my local copy with latest? |
| 130 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 131 | ```bash |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 132 | repo sync -j$(nproc) |
| 133 | ``` |
| 134 | |
| 135 | Then if you have any outstanding branches, a `repo rebase` will help. |
| 136 | |
| 137 | ### How to send code for review? |
| 138 | |
| 139 | To upload a branch to gerrit for review, do this: |
| 140 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 141 | ```bash |
June Tate-Gans | 0ff4789 | 2020-06-25 17:11:03 -0500 | [diff] [blame] | 142 | repo upload --re reviewer1,reviewer2 --cc email@host.com,email2@host2.com |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 143 | ``` |
| 144 | |
June Tate-Gans | 0ff4789 | 2020-06-25 17:11:03 -0500 | [diff] [blame] | 145 | Reviewers can be specified as usernames or full email addresses, likewise for |
| 146 | `--cc`. |
| 147 | |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 148 | Repo will then output a URL for you to visit that allows you to make comments |
| 149 | and abandon and merge the changes into the repository. To make changes during |
| 150 | the review process, make your changes to the files, then: |
| 151 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 152 | ```bash |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 153 | git add -A # To add the files you've changed |
| 154 | git commit --amend # To update the previous change |
June Tate-Gans | 0ff4789 | 2020-06-25 17:11:03 -0500 | [diff] [blame] | 155 | repo upload -t --re ${REVIEWER} --cc ${CC_LIST} # To upload the change to Gerrit for review |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 156 | ``` |
| 157 | |
June Tate-Gans | 31cd1c0 | 2022-08-23 15:33:50 -0500 | [diff] [blame] | 158 | ### Help! I'm on a limited-bandwidth connection, and need to stop downloading tooling! |
| 159 | |
| 160 | There's an environment variable you can set called `PIN_TOOLCHAINS` to prevent |
| 161 | download attempts for various toolchains in the system. The format is a |
| 162 | space-delimited list of words that includes which toolchains you wish to prevent |
| 163 | downloading automatically during a build. |
| 164 | |
| 165 | At the moment, this environment variable can be set to any of the following |
| 166 | words: |
| 167 | |
| 168 | `renode` - prevents downloading of the latest Renode binary build. |
| 169 | |
| 170 | `iree` - prevents downloading of the latest IREE compiler toolchain. |
| 171 | |
| 172 | Ie: |
| 173 | |
| 174 | ```bash |
| 175 | export PIN_TOOLCHAINS="renode iree" |
| 176 | ``` |
| 177 | |
| 178 | *Note well*: if you set this variable, the output or behavior of any of the |
| 179 | preceding toolchains may be bad or incorrect. Please do not file bugs against |
| 180 | these components if you have this variable set! |
| 181 | |
| 182 | ### Help! IREE, Renode, or another toolchain is misbehaving! |
| 183 | |
| 184 | Did you set `PIN_TOOLCHAINS`? If so, please unset this environment variable and |
| 185 | retry your build. |
| 186 | |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 187 | ## Repository Layout |
| 188 | |
| 189 | Our layout is pretty simple: |
| 190 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 191 | ### build/ |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 192 | |
| 193 | Contains build scripts for the whole tree. This is effectively just an |
| 194 | orchestration layer to make building the whole shebang easier. Each subtree may |
| 195 | have its own build systems and have their own ways of building. |
| 196 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 197 | ### cache/ |
| 198 | |
| 199 | The cached cross-compilation toolchain, including rust and RISC-V GCC/LLVM |
| 200 | toolchain. |
| 201 | |
| 202 | ### cicd/ |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 203 | |
| 204 | Contains continuous integration scripts and tooling for Jenkins, our CI/CD tool. |
| 205 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 206 | ### docs/ |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 207 | |
| 208 | Lots of extra documentation (we hope) about how the repo is laid out, how the |
| 209 | build system works, code reviews, licensing, etc. |
| 210 | |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 211 | ### hw/ |
| 212 | |
| 213 | Contains all of the source code and RTL required to build the Shodan |
| 214 | hardware, as well as simulate it in Verilator. |
| 215 | |
| 216 | #### opentitan |
| 217 | |
| 218 | Security core. |
| 219 | |
| 220 | #### ibex |
| 221 | |
| 222 | System management controller (SMC). |
| 223 | |
| 224 | #### springbok |
| 225 | |
| 226 | Vector core for ML acceleration. |
| 227 | |
June Tate-Gans | 280f414 | 2022-11-21 12:54:01 -0600 | [diff] [blame^] | 228 | ### cantrip/ |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 229 | |
Cindy Liu | 73984b0 | 2021-09-09 13:46:41 -0700 | [diff] [blame] | 230 | Operating system software for the SMC; including seL4 kernel & CAmkES framework, |
June Tate-Gans | 280f414 | 2022-11-21 12:54:01 -0600 | [diff] [blame^] | 231 | and custom CAmkES components that support Shodan (or maybe CantripOS) applications. |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 232 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 233 | ### manifest/ |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 234 | |
| 235 | The repo manifest used to glue all the git repositories together. |
| 236 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 237 | ### scripts/ |
June Tate-Gans | 63e0787 | 2020-06-25 16:23:28 -0500 | [diff] [blame] | 238 | |
| 239 | Contains utility scripts to help automate a few things. |
| 240 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 241 | ### sim/ |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 242 | |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 243 | Contains tools and src for simulators (Renode and Verilator) of the shodan system. |
| 244 | |
| 245 | ### sw/ |
| 246 | |
| 247 | Contains the source code of applications running in all shodan cores. |
| 248 | |
| 249 | #### libtock-rs |
| 250 | |
| 251 | **TODO**: add more details |
| 252 | |
| 253 | #### multihart_boot_rom |
| 254 | |
Cindy Liu | 73984b0 | 2021-09-09 13:46:41 -0700 | [diff] [blame] | 255 | Bootstrap for System Management Controller, Security Core, and Vector Core. This |
| 256 | is the first software to run after reset; it does low-level hardware setup and |
| 257 | starts TockOs (SC) and seL4 (SMC). |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 258 | |
| 259 | #### pigweed |
| 260 | |
| 261 | pigweed frameworks. Currently it is used for vector core functional tests. |
| 262 | |
| 263 | #### tock |
| 264 | |
| 265 | The operating system running on the Security Core. |
| 266 | |
| 267 | #### vec |
| 268 | |
| 269 | Springbok BSP, as well as the RVV instruction functional tests. |
| 270 | |
| 271 | #### vec_iree |
| 272 | |
Cindy Liu | 73984b0 | 2021-09-09 13:46:41 -0700 | [diff] [blame] | 273 | Springbok IREE application. It builds IREE runtime applications for ML models |
| 274 | using IREE libraries and Spingbok BSP. |
Henry Herman | 0c341b4 | 2020-09-23 11:56:26 -0700 | [diff] [blame] | 275 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 276 | ### toolchain/ |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 277 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 278 | Contains the src to build the RISCV QEMU emulator, and |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 279 | [IREE](https://github/com/google/iree) toolchain for ML models. |
| 280 | |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 281 | ## Build and Test ML Artifacts |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 282 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 283 | The ML executable is built with [IREE](https://github.com/google/iree) workflow, |
| 284 | targeted to RISCV 32-bit bare-metal config. |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 285 | |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 286 | To build the IREE targets: |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 287 | |
| 288 | ```bash |
Shaked Flur | 1b7191a | 2022-11-02 08:52:38 +0000 | [diff] [blame] | 289 | m iree_no_wmmu |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 290 | ``` |
| 291 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 292 | The IREE compiler sits in `out/host/iree_compiler`, while the runtime library/example |
Shaked Flur | 1b7191a | 2022-11-02 08:52:38 +0000 | [diff] [blame] | 293 | sits in `out/springbok_iree_no_wmmu`. |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 294 | To run the toy example (four-element vector element-wise multiplication) for |
| 295 | testing: |
| 296 | |
| 297 | ```bash |
Shaked Flur | 1b7191a | 2022-11-02 08:52:38 +0000 | [diff] [blame] | 298 | sim_springbok out/springbok_iree_no_wmmu/springbok_iree/samples/simple_vec_mul/simple_int_vec_mul_bytecode_static |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 299 | ``` |
| 300 | |
| 301 | The output should be shown as: |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 302 | |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 303 | ```bash |
Cindy Liu | 0532042 | 2021-09-29 21:31:10 -0700 | [diff] [blame] | 304 | 21:27:11.0241 [INFO] cpu2: simprint: "INFO |simple_vec_mul finished successfully", 0 (0x0) |
| 305 | 21:27:11.0248 [INFO] cpu2: simprint: "main returned: ", 0 (0x0) |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 306 | ``` |
Cindy Liu | d9b324e | 2021-08-12 18:21:43 -0700 | [diff] [blame] | 307 | |
Cindy Liu | 0532042 | 2021-09-29 21:31:10 -0700 | [diff] [blame] | 308 | (Enter `quit` or `q` to exit the Renode simulation) |
Cindy Liu | 1f238fa | 2021-03-17 10:59:05 -0700 | [diff] [blame] | 309 | |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 310 | ## Running The Full Shodan System Simulation |
| 311 | |
Cindy Liu | 73984b0 | 2021-09-09 13:46:41 -0700 | [diff] [blame] | 312 | The simulator used for Shodan is [Renode](https://renode.io/). The configuration |
Henry Herman | 2288915 | 2022-01-06 22:03:58 +0000 | [diff] [blame] | 313 | for the Shodan system is `sim/config/platforms/shodan.repl`, while and starting script |
| 314 | is in `sim/config/shodan.resc` |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 315 | |
| 316 | To run the full system simulation, build the default target: |
| 317 | |
| 318 | ```bash |
| 319 | m |
| 320 | ``` |
| 321 | |
Cindy Liu | 73984b0 | 2021-09-09 13:46:41 -0700 | [diff] [blame] | 322 | After all the artifacts are bulit, the Renode simulation session automatically |
| 323 | starts, and you should see the secured core and SMC booted |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 324 | |
| 325 | ```bash |
Cindy Liu | 1337cf7 | 2022-06-23 10:27:03 -0700 | [diff] [blame] | 326 | 10:11:43.1993 [INFO] uart5: init_kernel() |
| 327 | 10:11:43.2012 [INFO] uart5: Init local IRQ |
| 328 | 10:11:43.2018 [INFO] uart5: Bootstrapping kernel |
| 329 | 10:11:43.2053 [INFO] uart5: Initialing PLIC... |
| 330 | 10:11:43.2830 [INFO] uart5: Booting all finished, dropped to user space |
| 331 | 10:11:43.2978 [INFO] uart5: kata_os_rootserver::Bootinfo: 130550 empty slots 1 nodes 56 untyped 131072 cnode slots |
| 332 | 10:11:43.3008 [INFO] uart5: kata_os_rootserver::Model: 3750 objects 32 irqs 0 untypeds 2 asids |
| 333 | 10:11:43.3123 [INFO] uart5: kata_os_rootserver::capDL spec: 0.33 Mbytes |
| 334 | 10:11:43.3142 [INFO] uart5: kata_os_rootserver::CAmkES components: 1.02 Mbytes |
| 335 | 10:11:43.3191 [INFO] uart5: kata_os_rootserver::Rootserver executable: 0.40 Mbytes |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 336 | ``` |
| 337 | |
| 338 | At this point, you should be able to connect to the SMC debug console. |
| 339 | |
| 340 | ### Setting Up Debug Console Communication |
| 341 | |
| 342 | Install socat to your machine |
| 343 | |
| 344 | ```bash |
| 345 | sudo apt install socat |
| 346 | ``` |
| 347 | |
| 348 | In a new shell session, launch the debug console with |
| 349 | |
| 350 | ```bash |
| 351 | scripts/kshell.sh |
| 352 | ``` |
| 353 | |
June Tate-Gans | 280f414 | 2022-11-21 12:54:01 -0600 | [diff] [blame^] | 354 | You will see the CantripOS prompt showing up when you hit `enter`. Use `ctrl-c` to leave the console. |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 355 | |
| 356 | ### Connecting to Renode Console |
| 357 | |
| 358 | Renode has its own console to control the emulation environment. You can connect to it by |
| 359 | |
| 360 | ```bash |
| 361 | telnet localhost 1234 |
| 362 | ``` |
| 363 | |
| 364 | For example, you can check the core status |
| 365 | |
| 366 | ```bash |
| 367 | (matcha) cpu1 IsHalted |
| 368 | False |
| 369 | ``` |
| 370 | |
| 371 | or stop the whole emulation with |
| 372 | |
| 373 | ```bash |
| 374 | (matcha) quit |
| 375 | ``` |
| 376 | |
| 377 | ### Launch ML Job on the Vector Core |
| 378 | |
| 379 | You can launch the ML workload execution by communicating through the debug console |
| 380 | |
Cindy Liu | 1337cf7 | 2022-06-23 10:27:03 -0700 | [diff] [blame] | 381 | Check existing builtin applications |
| 382 | |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 383 | ```bash |
Cindy Liu | 1337cf7 | 2022-06-23 10:27:03 -0700 | [diff] [blame] | 384 | KATA> builtins |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 385 | ``` |
| 386 | |
Cindy Liu | 1337cf7 | 2022-06-23 10:27:03 -0700 | [diff] [blame] | 387 | Install the embedded ML model app; for example, |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 388 | |
| 389 | ```bash |
Cindy Liu | 1337cf7 | 2022-06-23 10:27:03 -0700 | [diff] [blame] | 390 | KATA> install mobilenet_v1_emitc_static.model |
| 391 | ``` |
| 392 | |
| 393 | and you should see model installed with a bundle ID issued. |
| 394 | |
| 395 | ```bash |
| 396 | KATA> Bundle "fake.26" installed |
| 397 | ``` |
| 398 | |
| 399 | You can then launch the ML job with `test_mlexecute <bundle ID> <model name>` |
| 400 | |
| 401 | ```bash |
| 402 | KATA> test_mlexecute fake.26 mobilenet_v1_emitc_static.model |
| 403 | ``` |
| 404 | |
| 405 | with the Renode console log printed as |
| 406 | |
| 407 | ```bash |
| 408 | 15:17:59.9864 [INFO] uart5: kata_ml_coordinator::Load successful. |
Cindy Liu | 73984b0 | 2021-09-09 13:46:41 -0700 | [diff] [blame] | 409 | ... |
Cindy Liu | b650f67 | 2021-10-12 15:49:23 -0700 | [diff] [blame] | 410 | 15:18:02.6868 [INFO] cpu2: simprint: "main returned: ", 0 (0x0) |
| 411 | |
Cindy Liu | c1485e7 | 2021-08-25 19:39:36 -0700 | [diff] [blame] | 412 | ``` |
| 413 | |
June Tate-Gans | 4447d0e | 2020-06-25 14:31:51 -0500 | [diff] [blame] | 414 | ## More Information |
| 415 | |
Cindy Liu | 1337cf7 | 2022-06-23 10:27:03 -0700 | [diff] [blame] | 416 | For more available Shodan build targets, please see [Build target lists](./BuildTargetsExplained.md), |
| 417 | or use the in-project command of `hmm` and `hmm <target name>`. |
Cindy Liu | 9acf552 | 2021-09-20 19:46:45 -0700 | [diff] [blame] | 418 | |
| 419 | Also, [Information on how to use repo](https://go/repo) |