Giter VIP home page Giter VIP logo

nthnn / rishka Goto Github PK

View Code? Open in Web Editor NEW
2.0 1.0 0.0 38.81 MB

RISC-V core virtual runtime written in C/C++ (Arduino platform) intended for ESP32-WROVER with PSRAM.

Home Page: https://rishka.vercel.app

License: GNU General Public License v3.0

Assembly 0.62% C 10.34% C++ 82.71% Rust 5.95% Shell 0.38%
arduino arduino-platform arduino-platformio arduino-project esp32 esp32-arduino risc-v risc-v-emulator risc-v-simulator kernel

rishka's Introduction

Rishka

Arduino CI Arduino Lint Rust Build CI SDK Build CI GitHub repo size

Rishka is a RISC-V virtual runtime in C/C++ made for ESP32-WROVER with PSRAM specifically developed as kernel for Jessy OS.

Note

Work in progress.

Rishka running shell example with an ILI9341 TFT LCD and FabGL.

How Does It Work?

The Rishka virtual runtime is a system designed to run special RISC-V binaries smoothly on ESP32-WROVER microcontroller units. Under the hood, the virtual machine serves as the main engine, while the kernel acts as its core component. The kernel handles system calls efficiently, providing a range of interfaces for accessing different system features and services.


Simple comparison of Rishka-based OS and Linux-based OS (with an Ubuntu logo, lol).

These include basic functions like managing files, as well as more complex tasks like controlling GPIO pins, attaching and detaching interrupts, and communication protocols such as I2C and SPI. Additionally, the kernel manages system utilities specific to the Jessy OS, handling tasks like sub-process runtime and memory allocation.

NodeMCU ESP32-WROVER and microSD card adapter where Rishka is being developed.

Installation

Rishka VM

Rishka VM is a lightweight and efficient virtual runtime environment designed for RISC-V binaries on ESP32-WROVER microcontrollers. Follow these steps to integrate Rishka into your Arduino projects:

  1. Clone Rishka to your Arduino libraries, by typing the command below:
cd ~/Arduino/libraries
git clone --depth 1 https://github.com/nthnn/rishka.git
  1. Open your Arduino IDE, then navigate to File > Examples > rishka and select an example suitable for your project.

  2. You're all set! Integrate Rishka into your project and start leveraging its capabilities.

Compiling Examples

Using rishka-cc tool

To use rishka-cc, you can get it from the release page if available or compile it yourself by typing the following on your terminal. Just make sure you have installed Rust compiler and Cargo package manager on your system.

cargo build --release

Alternatively, you can install the rishka-cc tool by typing the following below on your system terminal:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/nthnn/rishka/main/support/install_rishka_cc.sh)"

Before using rishka-cc, you must configure two (2) environment variables, as shown below.

export RISHKA_LIBPATH=<path to sdk library folder>
export RISHKA_SCRIPTS=<path to scripts folder>

The RISHKA_LIBPATH must be a folder where the librishka.h header file is located, while the RISHKA_SCRIPTS should be a folder where both launch.s and the link.ld files are located. For example, assuming Rishka was moved to the libraries folder on Arduino IDE:

export RISHKA_LIBPATH=/Arduino/libraries/rishka/sdk
export RISHKA_SCRIPTS=/Arduino/libraries/rishka/scripts

If no problems occured and was configured as instructed, you can now seamlessly use the rishka-cc.

Manually Compiling

To compile SDK examples provided with Rishka, follow these steps:

  1. If you haven't already, install Qrepo by following the instructions available here.

  2. Ensure you have the RISC-V64 GCC toolchain installed by running:

sudo apt install gcc-riscv64-unknown-elf
  1. Open a terminal and navigate to the directory where you cloned the Rishka repository.

  2. Use Qrepo to compile the examples by executing the following command:

qrepo run compile <source-file> <output-name>

Replace <source-file> with the path to the source file of the example you want to compile and <output-name> with the desired name for the output binary.

Examples:

qrepo run compile examples/sdk/hello.cpp hello
# This will output the binary file to dist/hello.bin

Now you have successfully compiled the example and can proceed with using the generated binary file.

Dumping Raw Binaries

Dumping raw binary files can be helpful in debugging programs, traditionally. Hence, a simple script in Qrepo is available to dump instructions from a raw binary file of Rishka. You can utilize it by typing the following:

qrepo run dump <filename>

Example

This example demonstrates the usage of Rishka virtual machine on an ESP32-WROVER microcontroller. It initializes serial communication and SD card, waits for user input via serial port, loads the specified file into the Rishka VM, executes it, and then waits for the next input.

#include <fabgl.h>
#include <rishka.h>
#include <SD.h>
#include <SPI.h>

#define TFT_CS     5            // TFT SPI select pin
#define TFT_SCK    18           // TFT SPI clock pin
#define TFT_MOSI   23           // TFT SPI MOSI pin
#define TFT_DC     15           // TFT data/command pin
#define TFT_RESET  4            // TFT reset pin
#define TFT_SPIBUS VSPI_HOST    // TFT SPI bus

#define SD_CS      2            // SD card chip select pin
#define SD_SCK     14           // SD card SPI clock pin
#define SD_MOSI    13           // SD card SPI MOSI pin
#define SD_MISO    12           // SD card SPI MISO pin

// TFT display controller and Terminal instance
fabgl::ILI9341Controller DisplayController;
fabgl::Terminal Terminal;

// SPI instance for SD card
SPIClass sdSpi(HSPI);

void setup() {
    // Initialize TFT display
    DisplayController.begin(TFT_SCK, TFT_MOSI, TFT_DC, TFT_RESET, TFT_CS, TFT_SPIBUS);
    DisplayController.setResolution("\"TFT_320x240\" 320 240");

    // Initialize terminal
    Terminal.begin(&DisplayController);
    Terminal.loadFont(&fabgl::FONT_8x14);
    Terminal.enableCursor(true);

    // Initialize SD card
    sdSpi.begin(SD_SCK, SD_MISO, SD_MOSI, SD_CS);
    if(!SD.begin(SD_CS, sdSpi, 80000000)) {
        Terminal.println("Card \e[94mMount\e[97m Failed");
        return;
    }

    // Rishka virtual machine instance
    RishkaVM* vm = new RishkaVM();
    // Initialize Rishka VM
    vm->initialize(&Terminal);

    if(!vm->loadFile("/sysinfo.bin"))
        vm->panic("Failed to \e[94mload\e[97m specified file.");

    // Run loaded program
    vm->run(0, NULL);
    // Reset VM after program execution
    vm->reset();
}

void loop() {
    // Delay to prevent continuous execution
    vTaskDelay(10);
}

Contributing

Contributions to Rishka are highly encouraged and appreciated! To contribute new features, bug fixes, or enhancements, please adhere to the following guidelines:

  1. Fork the Rishka repository.
  2. Create a new branch for your changes: git checkout -b feature-name.
  3. Implement your changes and commit them: git commit -m "Added new feature".
  4. Push your changes to the branch: git push origin feature-name.
  5. Submit a pull request for review and inclusion.

License

Rishka is distributed under the GNU General Public License v3.0. For further details, refer to the LICENSE file.

This program is free software: you can redistribute it and/or modify  
it under the terms of the GNU General Public License as published by  
the Free Software Foundation, version 3.

This program is distributed in the hope that it will be useful, but 
WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
General Public License for more details.

You should have received a copy of the GNU General Public License 
along with this program. If not, see <http://www.gnu.org/licenses/>.

rishka's People

Contributors

nthnn avatar

Stargazers

 avatar  avatar

Watchers

 avatar

rishka's Issues

Suggest batching data for writes in rishka_perror; loose fatherly advice to batch data in general

for(int i = 0; i < len; i++)

I've not called out every occurrence of this in the code and I know that in panic()-style code it's tempting to handle byte writes as robotically as possible so you get every dying breath of debug info out, but generally you want to reduce the overhead of round-tripping to any system below you.

This code, for example, might benefit from

https://www.arduino.cc/reference/en/language/functions/communication/serial/write/

So

void rishka_perror(const char* msg, uintptr_t len, bool flush) {
    if(len > 0 && msg)
        for(int i = 0; i < len; i++)
            Serial.write(msg[i]);

    if(flush) {
        Serial.println();
        Serial.flush();
    }
}

might become

void rishka_perror(const char* msg, uintptr_t len, bool flush) {
if (flush)
  Serial.println(str);
  Serial.flush();
} else {
  Serial.write(msg.len);
}

If this is in a templatable environment and flush is a constant (it almost always is) the optimizer may be able to remove the runtime test of flush totally and just replace your perror() with a calle to Serial.write(msg, len) so the correct message is passed through, though you might find the flexibility of making it more of a printf() call that evaluates arguments instead of a raw write() call that can potentially just load up a few pointers to the DMA engine and let your DMAC move it out.

But this specific call is a bit of overkill/distraction. The reaching point is that you want to batch those calls and deal in single calls with large (larger than a single byte) arguments instead of individual call/return sequences. Think "puts()" instead of "putc()". If the String returned by readString() already has a fast member that knows the length, don't get the c_str() and then traverse THAT looking for that terminator. (In some buffering system, getting the c_str itself can be costly if the buffers have to be coalesced.) If write() is just doing a store (what about flow control?) this kind of thing is probably not totally hideous, but if you're packetizing that into a debug protocol by building up a remote debug packet or programming a DMA transfer for a UART or ethernet packet, it can easily be a thousand or more times the overhead.

Optimizing a crash error message on its own is dumb, but there were enough places in the code that processed data a byte at a time to make it seem worth typing this. When emulating a CPU, misspent clock cycles can sneak up on you quickly!

Save the pounds ounces at a time. If you're not from Myanmar, Liberia, or other Metric-impaired world, just translate that cliché from using "a lot" and "a little". :-) Try to make function calls with batched values (std::spans, vector, etc.) instead of individual member/byte-level data if you at all can.

Cool project - carry on!

rishka_virtual_machine and others could benefit from a bit more C++ seasoning, IMO.

for(uint8_t i = 0; i < 32; i++)

If rishka_virtual_machine were a class had a constructor or init style class that initialized it to a guaranteed sane state, you might be able to save yourself some maintenance/synchronization grief.

The zeroing of registers[], for example, could probably reduce to a memset, probably inlined. Then if you were targeting, say, RV32E that had half as many RV registers, you wouldn't need to special-case that '32', the ctor would just set the appropriate registers.

This is very nice code, but don't let your structures be afraid to blossome out into classes with all the convenience and performance that goes with that. In fact, elsewhere in the code, it shows that you're not afraid of C++..., so don't be afraid to let your C++-flag fly freely!

I'd default running to false, zero-initialize registers[] (and provide accessors for things like debuggers or viewers...), ensure that stream*'s life cycle is always appropriate, etc.

You don't have to include something from every chapter of https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines in order just to prove you're worthy (you've produced a meaningful base of code - you're clearly worthy!) but don't be afraid to let the C++ bits poke through. and take advantage of th safety and performance that's available to you. Let rishka_syscall (and the rest of instructions*) be class enums for better type safety and so your own debugging code can offer more introspective views, etc.

It's clean and nifty code, but it looks like C code without the type safety and promises allowed by "Modern C++".

(And if you're tired of my opinionated bullshit, feel free to justcan all of these suggestions... :-) )

rishka_double_to_long and rishka_long_to_double could probably disappear

int64_t rishka_double_to_long(double d) {

You could probably make these specializations of an overload and really help the optimizer just pull these inline without the overhead of a function call. You're seemingly using type punning here to make your deal with the optimizer clear and keep alignment, etc. OK (a lovely approach!) but making it an overloaded operator, you really could make this a zero-cost abstraction.

For some reason, code of this type (including my own) always tends to look more like C with a salting of C++ that sometimes forgets to take advantage of all the things that C++ can offer. Don't forget about things like constexpr and overloads that can really help the readability to both you and teh optimizer.

These might even reduce to a lowly cast if you have control of the memory layout of both the input and outut here...

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.