EVA (Extensible Versatile Architect)

[H1M4W4R1]

Geneza

Projekt powstał w wyniku mojej niechęci do pisania MakeFile'ów i inspiracji Cargo (narzędzie do Rusta). Chciałem mieć coś wygodnego, w czym mogę napisać sobie buildy do RP Pico. No i tak się zabrałem do pracy...

Jak to ma działać?

Wstępna wersja EVA.

Syntax 

Na początku musiałem opracować składnię języka (przydał się tutaj ANTLR). Problemem było to, by była ona szybka do napisania, więc niekiedy wygląda dziwnie (i czasami dziwnie się zachowuje, ale to kwestia przyzwyczajenia).

Podstawowymi elementami składni są grupy (group), inwokacje (call), szarże (dash'e) oraz przypisania (assign).

Grupy i TLD

[architect]

Grupa definiuje zbiór inwokacji i przypisań. Pierwszym elementem w pliku powinna być grupa nazywana "TLD" z ang. Top Level Definition. Określa ona reprezentację pliku w strukturze obiektowej parsera. Domyślnymi TLD są:

• architect - główny plik języka, zawiera instrukcje stworzone przez użytkownika dla danego projektu
• tool - pliki narzędzi np. dla 'cmake' wraz z grupami
• processor - plik opisujący mikrokontroler / procesor / fpga oraz jego parametry (gdyby ktoś chciał skorzystać)
• debugger - plik zawierający grupę [upload] lub [debug] - pozwala na łatwe używanie konkretnego modelu debuggera bez implementacji grupy [upload] w każdym projekcie
• os (operating_system) - plik zawierający grupy dla danego systemu operacyjnego
• board - plik zawierający grupy i informacje o danej płytce prototypowej np. raspberry_pi_pico.va

Te TLD znajdują się w rozszerzeniu "EVA.Extensions.Core", które jest domyślnie zawsze dostępne.

Wywołania i przypisania zapisane w grupie TLD są wykonywane w momencie utworzenia danego obiektu.

[build]
# Check if build directory exists and move into it.
directory_exists('build') 
	-> !directory_create('build');

# Go to build directory
cwd('build');

# Compile
option_is('C', 'make') -> [compile_make];
option_is('C', 'ninja') -> [compile_ninja];

# No compiler found
err('No `--C` option found. Please use --C option for building with `make` or `ninja`.');
finish('e');

Grupy inne niż TLD to grupy wykonawcze. W momencie wykonywania parsera podajemy mu grupy, które ma wykonać. Przykładowo: 'eva build' wykona powyższą grupę '[build]'.

Instrukcja finish(<status>) powoduje automatyczne zakończenie wykonywania parsingu.

Jeżeli nasz architect implementuje np. płytkę, a płytka ma zdefiniowaną grupę [build] to kolejność wykonywania jest identyczna jak w definicjach. Najpierw wykona się najgłębiej zagnieżdżona grupa (np. arch->processor->board->architect). Jeżeli zagnieżdżenia są na identycznym poziomie to wykonają się zgodnie z kolejnością definicji 'use_<...>'.

Wywołania i DASH'e

use_debugger('black_magic_probe'); # Use BMP as debug utility

Wywołanie jest zbliżone do większości języków programowania. Jest to zwykły identyfikator wraz z argumentami. Argumentem może być stała (liczba, tekst, bool) lub identyfikator zmiennej. Wywołania wywołują funkcje, które są zapisane na stałe w rozszerzeniach do głównego parsera (nie można ich tworzyć dynamicznie).

Przykładowa funkcja:

using EVA.Framework.Execution;
using EVA.Framework.Logging;
using System.Collections.Generic;
using System.IO;
using EVA.Framework.Structure.Attributes;
using EVA.Framework.Structure.Base;
using EVA.Framework.Structure.Base.Enums;

namespace EVA.Extensions.Core.Functions.Common
{
    [Function("cwd", 1)]
    public class CwdFunc : FunctionBase
    {
        protected override EVAFunctionResult _Call(EVA_Object target, List<object> args)
        {
            var a0 = args[0];
            if(a0 is string s)
            {
                // Check if directory is absolute
                if (!Path.IsPathRooted(s))
                {
                    s = Executor.GetCWD() + s;
                }

                // Update directory if exists
                if (Directory.Exists(s))
                {                        
                    Executor.SetCWD(s);
                    return EVAFunctionResult.Ok;
                }
                else
                {
                    Executor.Log(LogLevel.Error, $"Directory `{s}` does not exist.", definitionStash);
                }
            }
            else
            {
                Executor.Log(LogLevel.Error, "`cwd` argument must be string!", definitionStash);
            }

            return EVAFunctionResult.Error;  
        }
    }
}

Wywołania mogą mieć również "szarże" (dash'e). Każda funkcja zwraca jeden z trzech rezultatów - OK, ERROR lub UNKNOWN. Ostatni z nich jest najmniej deskryptywny, bo określa moment, gdy nie wiemy czy funkcja wykonała poprawnie swoje zadanie.

directory_exists('build') 
	-> !directory_create('build');

option_is('C', 'make') -> [compile_make];

Dash zapisujemy między końcowym nawiasem argumentów funkcji, a średnikiem. Rozpoczynamy go od strzałki. Dash może kierować zarówno do innego wywołania, albo do grupy. Gdy kierujemy się do wywołania to zwyczajnie zapisujemy po strzałce kolejne wywołanie. W przypadku grupy zapisujemy jej identyfikator tak samo jak byśmy ją tworzyli.

Dodatkowo przed wywołaniem/grupą może być jeden z "czterech" symboli opisujący warunki.

• brak - dash wykona się tylko jeżeli funkcja bazowa została wykonana poprawnie
• ? - dash wykona się tylko gdy funkcja bazowa zwróciła UNKNOWN
• ! - dash wykona się tylko gdy funkcja bazowa zwróciła ERROR
• * - dash wykona się zawsze niezależnie od wyniku funkcji

Jedna funkcja może mieć kilka DASH'y. Oddzielamy je przecinkiem.

cmake('-G "Unix Makefiles" ../') -> !finish('e'), succ('CMake completed successfully.'); # Prepare build files

Przypisania

debugger_port: '\\.\COM7'; # Debug on COM7

Przypisania ustalają wartość zmiennej. Definiujemy je za pomocą ID i wartości rozdzielonych dwukropkiem. Przypisania mogą zapisywać wyłącznie wartości stałe (liczba, tekst, bool).

Przykładowe instrukcje VA

Rozszerzenia

Program automatycznie wczytuje funkcje i TLD zamieszczone w bibliotekach rozszerzeń (zwykłe biblioteki .DLL stworzone w .NET Core). Umieszczamy je w podfolderze "/extensions" w katalogu z parserem.

Oprócz tego program posiada katalog "lib", który zawiera np. informacje o płytkach, procesorach etc. Pliki .va z katalogu /lib są zawsze dostępne.

Używanie programu

Programu używamy za pomocą konsoli (terminala lub co kto woli). Jeżeli program jest dostępny z poziomu zmiennej środowiskowej (Windows) lub katalogu bin (Unix) to wykonujemy go za pomocą następującej komendy:

eva [task]+ (-[name](value))* (--[name] (value))*

Program musi zawierać minimum jedną grupę do wykonania (może mieć więcej). Oprócz tego program ma ustawienia i opcje. Nie są to terminy zamienne. Ustawienia dotyczą samego parsera jak np. język (WIP), a opcje są przekazywane do plików VA, które są wykonywane. Przykładowo wykonując powyższe przykładowe instrukcje należy zdefiniować opcję kompilatora/buildera (wiem, że nie jest to zamienne, ale brakuje mi słowa).

eva build --C ninja

W ten sposób definiujemy opcję narzędzia, które zbuduje nasz program. Brak definicji opcji C wyrzuci błąd na konsolę i program się zakończy. Zamiast 'ninja' możemy też użyć 'make', a EVA wygeneruje pliki dla make i zbuduje za jego pomocą nasz program.

TL;DR;

• obsługa GDB
• funkcje do obsługi zmiennych (trochę większe pole do popisu)
• porządek w kodzie (chociaż jako-taki już jest)
• naprawić bug z wykonywaniem builda (make/ninja się zawiesza jeżeli pliki nie są jeszcze zbudowane)
• I18N
• IDNK, coś jeszcze się wymyśli 😄 

Tak, wiem, że istnieją inne narzędzia, ale chciałem mieć swoje, które będzie działać tak jak ja chcę (i które łatwo będzie można rozszerzać o kolejne funkcjonalności).

I nie mam nastroju na zrobienie obsługi GDB... Bo samo budowanie już działa (przynajmniej dla testowego projektu).

[H1M4W4R1]

Znalazłem natchnienie o 4:30 w nocy jak nie mogłem zasnąć 😄 

GDB ładnie wgrało Blinka na Pico 😉 

To teraz czas na porządki...

[H1M4W4R1]

Porządek jako-tako zrobiony 😄 Jeszcze nie jestem zadowolony ze struktury, ale już jest "akceptowalna". Przy okazji jakoś przez przypadek naprawił się bug z make... Może to przez przeróbkę obsługi zewnętrznych programów, gdzie komunikacja wyjściowa już nie jest obsługiwana bezpośrednio przez strumienie, a poprzez zdarzenia... W każdym razie mniej błędów to mniej problemów...

Teraz głównie pozostaje dodać kolejne komendy do listy i zastanowić się czy to, że funkcja nie zwraca wartości to był dobry pomysł... Póki jeszcze da się to poprawić 😄 

Aktualny spis funkcji

• Core
  • Common
    • cwd(target: string) -> zmień ścieżkę roboczą
    • finish(status: string) -> zakończ program z danym statusem (error, success, warning)
    • is_set(var_name: string) -> sprawdź czy dana zmienna jest zdefiniowana (nie jest null)
    • software_exists(name: string) -> sprawdź czy oprogramowanie jest zainstalowane (wykonuje komendę z opcją --version)
  • Importing
    • use_architecture(name: string), use_arch(name: string) -> wczytaj plik architektury
    • use_board(name: string) -> wczytaj plik płytki
    • use_debugger(name: string) -> wczytaj plik debuggera
    • use_debugger(name: string) -> wczytaj plik debuggera
    • use_operating_system(name: string), use_os(name: string) -> wczytaj plik systemu operacyjnego
    • use_processor(name: string), use_cpu(name: string), use_mcu(name: string) -> wczytaj plik procesora
    • use_tool(name: string) -> wczytaj plik narzędzia
  • Logging
    • err(msg: string) -> wyświetl błąd w konsoli
    • warn(msg: string) -> wyświetl ostrzeżenie w konsoli
    • succ(msg: string) -> wyświetl sukces w konsoli
    • msg(msg: string) -> wyświetl wiadomość w konsoli
  • Options
    • option_default(id: string, value: ?) -> ustal standardową wartość danej opcji (gdy nie jest zdefiniowana)
    • option_exists(id: string) -> sprawdź czy dana opcja jest zdefiniowana
    • option_is(id: string, value: ?) -> sprawdź czy dana opcja ma ustaloną wartość
• GDB
  • gdb_begin() -> rozpocznij proces GDB
  • gdb_begin(name: string) -> rozpocznij proces GDB dla danego programu np. 'arm-none-eabi-gdb' stosowane do multi-core
  • gdb_tar_ext(name: string) -> podłącz się do zewnętrznego debuggera np. na porcie COM '\\.\COM7'
  • gdb_attach(id: int) -> dołącz GDB do danego rdzenia
  • gdb_load(id: string) -> załaduj dany plik np. '.hex' lub '.elf' do rdzenia
  • gdb_detach() -> odłącz aktualny rdzeń
  • gdb_quit(), gdb_exit() -> zamknij aktualny proces GDB
• IO
  • DirectoryFn
    • directory_create(path: string) -> utwórz katalog
    • directory_delete(path: string) -> usuń katalog
    • directory_exists(path: string) -> sprawdź czy katalog istnieje
  • FileFn
    • \\TODO\\
• Make
  • cmake(opt: string) -> wykonaj CMake z argumentami
  • make(opt: string) -> wykonaj Make z argumentami 
  • ninja(opt: string) -> wykonaj Ninja z argumentami (alternatywa dla Make)

Edytowano Wrzesień 29, 2022 przez H1M4W4R1

[H1M4W4R1]

No i jednak wyszło, że funkcje zwracają wartość 😉 

architect.va

[architect]

# Setup board and debugger settings
use_board('pi_pico');
use_debugger('black_magic_probe');

debugger_port: COM_PORT('COM7');
debugger_core: 1;

black_magic_probe.va

[debugger]
id: 'black_magic_probe';
gdb: 'arm-none-eabi-gdb';

msg('Debugging using Black Magic Probe (GDB)');

[upload]
is_set('debugger_port') -> ![bmp_no_port_specified];
is_set('debugger_core') -> ![bmp_no_target_core_specified];

software_exists(gdb) -> ![bmp_gdb_not_installed];

cwd('build');

msg('Starting GDB');
gdb_begin(gdb) -> ![bmp_gdb_not_installed];
msg('Connecting to Black Magic Probe...');
gdb_target_external(debugger_port) -> ![bmp_probe_not_found];
msg('Attaching to target core...');
gdb_attach(debugger_core) -> ![bmp_attaching_failed];
msg('Loading HEX file...');
gdb_load_ext('.hex') -> ![bmp_load_failed];
gdb_detach();
gdb_quit();
succ('Uploaded successfully.');

[bmp_no_port_specified]
err('No debugger port specified (`debugger_port`).');
finish('e');

[bmp_no_target_core_specified]
warn('No target core (`debugger_core`) was specified. Using `1` as default.');

[bmp_gdb_not_installed]
err('No GDB is not installed or missing from `PATH`.');
finish('e');

[bmp_probe_not_found]
err('Probe does not exist on selected COM Port ');
finish('e');

[bmp_attaching_failed]
err('Attaching to target failed.');
finish('e');

[bmp_load_failed]
err('Cannot load binary onto target. Does your .elf binary exist?');
finish('e');

 

[Polecacz 101]

Produkcja i montaż PCB - wybierz sprawdzone PCBWay!
   • Darmowe płytki dla studentów i projektów non-profit
   • Tylko 5$ za 10 prototypów PCB w 24 godziny
   • Usługa projektowania PCB na zlecenie
   • Montaż PCB od 30$ + bezpłatna dostawa i szablony
   • Darmowe narzędzie do podglądu plików Gerber
Zobacz również » Film z fabryki PCBWay

[H1M4W4R1]

Kiedy człowiek jest leniwy i nie chce dodawać operatorów logicznych do programu:

Zaczyna się robić clusterf-k... 😄 

IMO obsługa poprzez funkcje jest logiczniejsza niż dodawanie kolejnego elementu, to ma być proste, a raczej nikt nie będzie aż tak kombinował z operatorami logicznymi 😄 

[ethanak]

Ty mi nie mów o operatorach logicznych - na razie stwierdziłem, że funkcje nie mają efektów ubocznych i zamiast AND THEN i OR ELSE mam proste AND i OR z obliczeniem obu gałęzi. Ale będę musiał to zmienić...

 

[H1M4W4R1]

3 godziny temu, ethanak napisał:

Ty mi nie mów o operatorach logicznych - na razie stwierdziłem, że funkcje nie mają efektów ubocznych i zamiast AND THEN i OR ELSE mam proste AND i OR z obliczeniem obu gałęzi. Ale będę musiał to zmienić...

Próbuję zrozumieć czy to jest arcywybitna sarkastyczna krytyka poziomu nadmiernego skomplikowania tego narzędzia czy mówisz o jakimś innym języku/narzędziu 😄 

[ethanak]

Mówię o tym o czym wcześniej pisałem (język do opisu sekwencji ruchów dla animka). A chyba problem z operatorami logicznymi jest podobny?

[H1M4W4R1]

21 minut temu, ethanak napisał:

A chyba problem z operatorami logicznymi jest podobny?

Problemem jest tylko lenistwo, bo dodać je mogę w kilka sekund, ale muszę to potem zaimplementować w parsingu, bo używam ANTLR4 i tokenizacji, co powala na poruszanie się po drzewie.

10 godzin temu, H1M4W4R1 napisał:

Rozwija się m/w tak:

Zielone to tokeny, białe to instrukcje, które wykonuje parser. Sorki za jakość, w zał. masz eksport SVG, bo niestety ma styl i konwersja na PNG nie ogarnia 😞  

EVA_SVG_Sample.zip

[ethanak]

To że problemem jest lenistwo to święta prawda. Tyle  ża ja muszę zaimplementować skoki warunkowe jako rezultat kompilacji wyrażeń - a strasznie mi się nie chce 🙂

Tyle ża ja piszę to cholerstwo from scratch, kompilator na kod pośredni w Pythonie, interpreter to C++...

[H1M4W4R1]

6 minut temu, ethanak napisał:

Tyle ża ja piszę to cholerstwo from scratch, kompilator na kod pośredni w Pythonie, interpreter to C++...

Masochista 😄 Pewnie wydajność też nędzna... Jak masz tam ESP32 to pokusiłbym się o spróbowanie ANTLR4, bo z tego co pamiętam masz tam dość prosty język, więc wydajność będzie zbliżona do Twojego kodu. Najdłużej zajmuje wczytanie pliku i tokenizacja, potem chodzi jak marzenie i można sobie skakać po drzewie elementów. Jak to kompilujesz do kodu pośredniego, to wydajność by nie ucierpiała, a byłoby Ci łatwiej pracować (tylko nie polecam mojego opisu, bo jest dość chaotyczny). Lepiej wpaść tutaj: 

 

Obsługę parsera ANTLR4 można pisać w każdym sensownym języku 😄 Python, TS, C#, C++, Java etc., a sama składania jest dość łatwa do ogarnięcia.

Pisanie "kompilatora" (technicznie Twój program kompiluje język X do Pythona) od zera to masochizm w czystej postaci...

[ethanak]

@H1M4W4R1 Wszystko pomieszałeś 🙂

Kompilator jest pisany w Pythonie, działa na pececie a wydajność jest akurat najmniejszym problemem (sekwencje mają z reguły kilka - kilkanaście linii a kompilacja zestawu nie trwa sekundy). Parser jest trywialny i nie ma potrzeby angażowania tu jakichś wymyślnych dodatków, w praktyce ogranicza się do translacji wyrażeń na drzewo (jakieś 150 linii kodu).

Na wyjściu mam albo kod źródłowy w C (zainicjalizowane tablice) albo binarkę przygotowaną do władowania bezpośrednio do EEPROM-u.

ESP robi całą czarną robotę - taką przykładową instrukcją wynikową jest np. "przesuń serwo na pozycję X w ciągu N milisekund z akceleracją".