{"id":18153776,"url":"https://github.com/dlesbre/cephalopode","last_synced_at":"2025-04-07T00:53:41.968Z","repository":{"id":67637663,"uuid":"436574866","full_name":"dlesbre/cephalopode","owner":"dlesbre","description":"The cephalopod IoT processor and the bifrost compiler","archived":false,"fork":false,"pushed_at":"2022-02-04T13:55:48.000Z","size":323,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-13T06:41:12.654Z","etag":null,"topics":["arbitrary-precision-integers","hardware","hardware-description-language","iot"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dlesbre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-09T10:30:20.000Z","updated_at":"2024-04-01T19:58:18.000Z","dependencies_parsed_at":"2023-04-27T15:35:14.099Z","dependency_job_id":null,"html_url":"https://github.com/dlesbre/cephalopode","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlesbre%2Fcephalopode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlesbre%2Fcephalopode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlesbre%2Fcephalopode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlesbre%2Fcephalopode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dlesbre","download_url":"https://codeload.github.com/dlesbre/cephalopode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247574097,"owners_count":20960495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arbitrary-precision-integers","hardware","hardware-description-language","iot"],"created_at":"2024-11-02T03:08:04.871Z","updated_at":"2025-04-07T00:53:41.959Z","avatar_url":"https://github.com/dlesbre.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\n\n\nThis repository contains the source code for the IoTProc processor. IoTProc is a custom processor designed for IoT. It aims to be a very low power hardware device directly aimed at running a high-level functional language.\n\nIoTProc is developed as part of the [Octopi Project](https://octopi.chalmers.se/).\n\nThis repository also contains the Bifröst compiler, a high-level synthesis tool used to create RTL code for IoTProc from the eponymous language.\n\n**Contents:**\n- [Repository description](#repository-description)\n- [Running with Docker](#running-with-docker)\n- [Makefile targets](#makefile-targets)\n- [Manual installation](#manual-installation)\n\t- [Bifröst](#bifröst)\n\t- [IoTProc](#iotproc)\n- [Building docker](#building-docker)\n\n## Repository description\n\nThis repository is organized as follows:\n- `bifrost/` - source for the Bifröst compiler, can be built with `make bifrost`\n- `bifrost/examples/` - small code examples in Bifröst, can be compiled to FL with `make bifrost-examples`\n- `RTL/` - an RTL description of the IoTProc processor written in HFL. A fast example can be run by loading the `cephalopode.fl` main file. (run `make processor`)\n- `RTL/ALU/` - the IoTProc ALU, performs operations on arbitrary-precision integers. It contains some parts in state machine editor FsM (`.fsm` files), some in Bifröst (`.prog` files) as well as their compiled FL code (corresponding `.fsm.fl` and `.prog.fl`)\n\n\tYou can run `make ALU-test` to load the ALU test suite (`RTL/ALU/ALU_test.fl`) then evaluate the relevant test in the interpretor (for instance `TEST_ADD;`). Beware that some of these can be very long.\n\n\tYou can run `make bifrost-alu` to recompile the ALU divider (`RTL/ALU/arith/div.prog`) and multiplier (`RTL/ALU/arith/mul.prog`) with bifrost. Their compiled versions are aldready available in the `.prog.fl` files.\n\n- `compile/` - tools to create ROM images for IoTProc\n- `Makefile` - see `make help` for a list of targets\n\n\n## Running with Docker\n\nYou can download a docker image from the releases. It allows to run bifröst and the processor easily with all dependencies included.\n\nThe docker image is called \"processor\". It is meant to be executed in interactive mode with acces to an X server for the GUI elements. In order to do so:\n\n1. Unzip and load into docker:\n\n\t```\n\tgzip -d docker_image.gz\n\tsudo docker load -i docker_image\n\t```\n\n2. To run the image with acces to the X server on a linux system:\n\n\t```\n\tsudo docker run --rm -it -e DISPLAY=:0 \\\n\t     -v /tmp/.X11-unix:/tmp/.X11-unix \\\n\t     -v \"$(HOME)/.Xauthority:/home/user/.Xauthority\" \\\n\t     processor /bin/bash\n\t```\n\tIt can be run without the X-server with (but fl will not work then):\n\t```\n\tsudo docker run --rm -it processor /bin/bash\n\t```\n\tThis opens a bash shell on a small debian system. For other systems, the best I can do is point you to [this tutorial](https://cuneyt.aliustaoglu.biz/en/running-gui-applications-in-docker-on-windows-linux-mac-hosts/) which helped me set it up in linux.\n\n\tIf running on a remote system, [this other tutorial](https://blog.yadutaf.fr/2017/09/10/running-a-graphical-app-in-a-docker-container-on-a-remote-server/) may help set it up\n\n3. You are now logged in as user \"user\" who has sudo priviledges with password \"password\". User's home folder contains our souce code under `src`. The makefile in `~/src` can be used to quickly launch all our programs. See `make help` for a full list of targets, or below for specific targets.\n\n\tFor convenience, we added the fl interpretor and bifrost compiler to the path. They can be accessed with `fl` and `bifrost`. Note that `fl` requires a connection to the X-server.\n\n## Makefile targets\n\n**For bifrost:**\n* The examples can be compiled with `make bifrost-examples`. The generated files are the same name `.prog.fl` files.\n* The multiplier and divider can be compiled with `make bifrost-alu`. Th\n* Bifrost is precompiled, but can be recompiled from the Haskell source with `make bifrost-clean-exe bifrost`.\n\n**For the ALU:** the small tests are fine but arithmetic test can take a \u003e1h and a \u003e16GB of RAM when running on more than (1,1) chunks. To run the ALU tests:\n1. Run `make ALU-test`. This will open and fl window and define (but not run) the test\n2. To run a test, simply type `TEST_NAME;` in the fl interpretor. Defined tests are\n\t- TEST_EQ, TEST_NEQ, TEST_GT, TEST_GEQ and TEST_COMPARATOR which runs them all. These take less than a minute each.\n\t- TEST_NOT, TEST_AND, TEST_OR, TEST_COND and TEST_LOGICAL which runs them all. These take less than a minute each.\n\t- TEST_ADD, TEST_SUB, TEST_MUL, TEST_DIV and TEST_ARITHMETIC which runs them all. Running TEST_ARITHMETIC can take around 30 minutes.\n\t- TEST_ALU: runs all of the above, takes less then 30 min and 16 GB of RAM\n\t- TEST_ADD_LONG, TEST_SUB_LONG, TEST_MUL_LONG, TEST_DIV_LONG and TEST_ARITHMETIC_LONG. Way more hardware demanding. They take upward of 8 hours and sometime fail due to lack of RAM on my 16 GB pc.\n\t- Explicit tests TEST_ADD_EX, TEST_SUB_EX, TEST_MUL_EX and TEST_DIV_EX, they can be run with\n\n\t\t```\n\t\tTEST_MUL_EX 128 (-1992);\n\t\t```\n\n\t\tThey are much faster than the symbolic evaluation ones. They print the chunk representation of the operands before running.\n\n**For benchmarks:**\n- run `make benchmark1` to run the first benchmark (Adding 10 numbers using 2-chunks). It ends at Time: 20000.\n- run `make benchmark2` to run the second benchmark (Multiplying 10 numbers using 3-chunks). It ends at Time: 20000.\n- run `make benchmark3` to run the third benchmark (Dividing 10 numbers using 2-chunks). It ends at Time: 20000.\n- run `make benchmark4` to run the fourth benchmark (Collection of factorials needing 3 chunks). It ends at Time: 40000.\n- run `make benchmark5` to run the fifth benchmark (Crossproduct of 4 pairs using 5 chunks). It ends at Time: 5000.\n\n\n## Manual installation\n\n### Bifröst\n\nThe Bifröst compiler is written in Haskell. It requires the Haskell platform\n\n\tsudo apt install ghc bnfc\n\nIt can then be built using `make bifrost`. The examples programs in `./bifrost/examples` can be compiled with `make bifrost-examples`.\n\nYou can recompile the ALU multiplier and divider with `make bifrost-alu`.\n\n### IoTProc\n\nBuilding and running IoTProc requires [Voss II](https://github.com/TeamVoss/VossII). To install it:\n\n1. Install Voss II's dependencies:\n\n\t```\n\tsudo apt install tk gcc g++ doxygen flex bison gawk \\\n\t                 libz-dev tcl-dev tk-dev libc6-dev \\\n\t                 clang libreadline-dev python3 imagemagick pandoc\n\t```\n\n2. Clone Voss II's repository with SSH or HTTPS (run only ONE of these!)\n\n\t```\n\tgit clone git@github.com:TeamVoss/VossII.git\n\tgit clone https://github.com/TeamVoss/VossII.git\n\t```\n\n3. Run the makefile to build it:\n\n\t```\n\tcd Voss II\n\tmake -C src install_all_but_yosys\n\t```\n\n4. You can check your install by running the fl interpretor (`.../VossII/bin/fl`). It should open a new window with the fl interpretor.\n\n\tType `load \"ste.fl\";` in the interpretor to verify that you have the HFL library.\n\n5. You're done. For convenience, you can add the fl interpretor (`.../VossII/bin/fl`) to your PATH:\n\n\t```\n\texport PATH=\"path/to/VossII/bin:$PATH\"\n\t```\n\n\tOr replace the first line of the `Makefile` with the relevant path.\n\nAn optionnal dependency is [Stately](https://github.com/popje-chalmers/stately), a custom FSM editor. It is used to read the `.fsm` files and display a visualy editable state machine. The exported versions of these files was also provided as well (with extension `.fsm.fl`). It requires java to run. To install it:\n\n1. Clone the repository with SSH or HTTPS\n\n\t```\n\tgit clone git@github.com:popje-chalmers/stately.git\n\tgit clone https://github.com/popje-chalmers/stately.git\n\t```\n\n2. Build and run\n\n\t```\n\tmake run\n\t```\n\n\tAnd use the interface to navigate to the `.fsm` files.\n\n## Building docker\n\nYou can build the docker image given in the release page from this source code:\n- run `make docker-build` to create the image (can take a while)\n- run `make docker-run` to run it\n- run `make docker-zip` to export it and compress it with gzip\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlesbre%2Fcephalopode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdlesbre%2Fcephalopode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlesbre%2Fcephalopode/lists"}