Integrate rvctl with rv32i and host debug profiles
This commit is contained in:
mpabi
+97
-100
@@ -1,156 +1,153 @@
|
||||
# Containers
|
||||
# Kontenery i debug
|
||||
|
||||
Ten dokument opisuje docelowy model komend `rvctl` do uruchamiania
|
||||
środowiska programistycznego w kontenerach.
|
||||
`rvctl` integruje workspace z narzędziem `rv32i-hazard3-student-env`.
|
||||
Środowisko ma dwa profile kontenerów:
|
||||
|
||||
## Zasada
|
||||
- `rv32i` - docelowe środowisko RISC-V/Hazard3 z `nvim`, `tmux`,
|
||||
`gdb-multiarch`, toolchainem RISC-V i symulatorem Hazard3.
|
||||
- `host` - natywne środowisko na architekturze hosta z `clang`, `gcc`, `gdb`,
|
||||
opcjonalnie `lldb`, `valgrind`, `nvim` i `tmux`.
|
||||
|
||||
Kontener jest środowiskiem pracy dla wybranej karty, opcjonalnie zawężonym do
|
||||
konkretnego zadania. `rvctl` uruchamia je przez sesję `tmux`, tak aby terminal
|
||||
z kontenerem był łatwy do ponownego podłączenia.
|
||||
|
||||
Używamy namespace `containers`, a nie `container`, bo jest spójny z pluralnymi
|
||||
namespace'ami `tokens`, `cards` i `tasks`.
|
||||
Profile są uruchamiane jako oddzielne usługi `docker compose`, więc zależności
|
||||
RISC-V i zależności natywnego debugowania nie mieszają się ze sobą.
|
||||
|
||||
## Szybki przepływ
|
||||
|
||||
Typowy przepływ pracy:
|
||||
|
||||
```bash
|
||||
./rvctl tokens compare
|
||||
./rvctl series cards show inf bss
|
||||
./rvctl series cards tasks list inf bss
|
||||
./rvctl containers show inf bss
|
||||
./rvctl containers start inf bss --session rv-inf-bss --attach
|
||||
./rvctl containers list
|
||||
./rvctl containers stop rv-inf-bss
|
||||
./rvctl env list
|
||||
./rvctl env sync
|
||||
./rvctl env build rv32i
|
||||
./rvctl env build host
|
||||
|
||||
./rvctl debug rv32i inf bss 1
|
||||
./rvctl debug host inf bss 1
|
||||
./rvctl run host inf bss 1
|
||||
./rvctl shell rv32i inf bss
|
||||
./rvctl shell host inf bss
|
||||
```
|
||||
|
||||
## Model
|
||||
Jeżeli `workspace.json` ma ustawione domyślne wartości `defaults.series`,
|
||||
`defaults.card` i `defaults.task`, można używać krótszych komend:
|
||||
|
||||
Docelowo komendy `containers` pracują na trzech warstwach:
|
||||
```bash
|
||||
./rvctl debug rv32i
|
||||
./rvctl debug host
|
||||
./rvctl debug rv32i 4
|
||||
./rvctl debug host 4
|
||||
```
|
||||
|
||||
- karta pracy, np. `inf bss`
|
||||
- opcjonalne zadanie, np. `--task task1`
|
||||
- instancja środowiska, np. `--instance shell`
|
||||
## `env list`
|
||||
|
||||
Domyślne wartości pochodzą z `workspace.json`:
|
||||
Pokazuje dostępne profile i bieżący katalog narzędzia:
|
||||
|
||||
```bash
|
||||
./rvctl env list
|
||||
```
|
||||
|
||||
Typowy wynik:
|
||||
|
||||
```text
|
||||
defaults.series
|
||||
defaults.card
|
||||
defaults.task
|
||||
defaults.instance
|
||||
defaults.tmux_session
|
||||
defaults.tmux_window
|
||||
profile service image status purpose
|
||||
rv32i env edu-inf/rv32i-hazard3-env:latest ready RV32I/Hazard3 nvim + gdb-multiarch
|
||||
host host edu-inf/rv32i-hazard3-host-env:latest ready native host clang/gcc + gdb/lldb
|
||||
```
|
||||
|
||||
## Komendy
|
||||
## `env sync`
|
||||
|
||||
### `containers show [SERIES] [CARD]`
|
||||
|
||||
Pokazuje plan uruchomienia środowiska bez tworzenia sesji `tmux`.
|
||||
|
||||
```bash
|
||||
./rvctl containers show inf bss
|
||||
./rvctl containers show inf/bss --task task1
|
||||
```
|
||||
|
||||
Typowe pola:
|
||||
Klonuje albo aktualizuje repo środowiska do:
|
||||
|
||||
```text
|
||||
selector inf/bss
|
||||
task task1
|
||||
card_path ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack
|
||||
task_path ~/dev/workspace/rv/series/inf/lab-rv32i-strlen-bss-data-stack/task1
|
||||
tools_root ~/dev/workspace/rv/tools/rv32i-hazard3-env
|
||||
session rv-inf-bss
|
||||
window rv
|
||||
instance shell
|
||||
~/dev/workspace/rv/tools/rv32i-hazard3-student-env
|
||||
```
|
||||
|
||||
Ta komenda jest odpowiednikiem obecnego trybu:
|
||||
Komenda:
|
||||
|
||||
```bash
|
||||
./rvctl tmux-container inf bss --dry-run
|
||||
./rvctl env sync
|
||||
./rvctl env sync --dry-run
|
||||
```
|
||||
|
||||
### `containers start [SERIES] [CARD]`
|
||||
Jeżeli tego repo jeszcze nie ma w workspace, `rvctl` używa fallbacku z
|
||||
`~/dev/edu/repos/rv/rv32i-hazard3-env`, o ile jest dostępny.
|
||||
|
||||
Uruchamia sesję `tmux` i kontener dla wybranej karty.
|
||||
## `env build`
|
||||
|
||||
Buduje wybrany profil kontenera:
|
||||
|
||||
```bash
|
||||
./rvctl containers start inf bss
|
||||
./rvctl containers start inf/bss --session rv-inf-bss
|
||||
./rvctl containers start inf bss --task task1 --instance shell --attach
|
||||
./rvctl env build rv32i
|
||||
./rvctl env build host
|
||||
```
|
||||
|
||||
Przełączniki:
|
||||
|
||||
- `--task TASK`
|
||||
Wybiera zadanie w karcie. Bez tego `rvctl` używa domyślnego zadania z
|
||||
`workspace.json` albo pracuje na katalogu karty.
|
||||
- `--session NAME`
|
||||
Nadpisuje nazwę sesji `tmux`.
|
||||
- `--window NAME`
|
||||
Nadpisuje nazwę okna `tmux`.
|
||||
- `--instance NAME`
|
||||
Ustawia wariant środowiska, np. `shell`.
|
||||
- `--attach`
|
||||
Po uruchomieniu od razu podłącza terminal do sesji.
|
||||
|
||||
### `containers list`
|
||||
|
||||
Listuje aktywne środowiska uruchomione przez `rvctl`.
|
||||
Wariant `--dry-run` pokazuje dokładną komendę bez uruchamiania Dockera:
|
||||
|
||||
```bash
|
||||
./rvctl containers list
|
||||
./rvctl env build host --dry-run
|
||||
```
|
||||
|
||||
Przykładowy wynik:
|
||||
## `debug`
|
||||
|
||||
```text
|
||||
session selector task instance window
|
||||
-------- -------- ----- -------- ------
|
||||
rv-inf-bss inf/bss task1 shell rv
|
||||
```
|
||||
|
||||
### `containers attach SESSION`
|
||||
|
||||
Podłącza terminal do istniejącej sesji.
|
||||
Uruchamia debugowanie zadania w wybranym profilu.
|
||||
|
||||
```bash
|
||||
./rvctl containers attach rv-inf-bss
|
||||
./rvctl debug rv32i inf bss 1
|
||||
./rvctl debug host inf bss 1
|
||||
```
|
||||
|
||||
Technicznie odpowiada to:
|
||||
W profilu `rv32i` startuje środowisko Hazard3: symulator, `gdb-multiarch` i
|
||||
`nvim` w sesji `tmux`.
|
||||
|
||||
W profilu `host` wybrane źródło C jest kompilowane natywnie z debug info, a
|
||||
potem uruchamiane w `gdb` obok `nvim`.
|
||||
Ten profil jest przeznaczony dla tasków C z funkcją `main`; taski czysto
|
||||
asemblerskie nadal debugujemy w profilu `rv32i`.
|
||||
|
||||
Przydatne warianty:
|
||||
|
||||
```bash
|
||||
tmux attach -t rv-inf-bss
|
||||
./rvctl debug rv32i bss 4
|
||||
./rvctl debug host bss 4
|
||||
./rvctl debug host 4 --editor vim
|
||||
./rvctl debug host 4 --instance host-bss-t4
|
||||
./rvctl debug host 4 --dry-run
|
||||
```
|
||||
|
||||
### `containers stop SESSION`
|
||||
## `run`
|
||||
|
||||
Zamyka sesję `tmux`, a razem z nią uruchomiony w niej proces kontenera.
|
||||
Na razie `run` jest wdrożone dla profilu `host`. Buduje wybrany task natywnie i
|
||||
uruchamia wynikowy program:
|
||||
|
||||
```bash
|
||||
./rvctl containers stop rv-inf-bss
|
||||
./rvctl run host inf bss 1
|
||||
./rvctl run host 4
|
||||
```
|
||||
|
||||
Technicznie odpowiada to:
|
||||
Dla profilu `rv32i` używamy obecnie `debug rv32i`, bo przepływ RISC-V zakłada
|
||||
symulator Hazard3 i GDB.
|
||||
|
||||
## `shell`
|
||||
|
||||
Otwiera shell w wybranym profilu kontenera z podmontowaną kartą:
|
||||
|
||||
```bash
|
||||
tmux kill-session -t rv-inf-bss
|
||||
./rvctl shell rv32i inf bss
|
||||
./rvctl shell host inf bss
|
||||
```
|
||||
|
||||
## Aliasowanie Starej Komendy
|
||||
## Selektory
|
||||
|
||||
Stara komenda może zostać jako alias kompatybilności:
|
||||
Komendy `debug`, `run` i `shell` używają tych samych skrótów co `tasks`:
|
||||
|
||||
```text
|
||||
tmux-container inf bss --dry-run -> containers show inf bss
|
||||
tmux-container inf bss --session NAME -> containers start inf bss --session NAME
|
||||
tmux-container inf/bss --attach -> containers start inf/bss --attach
|
||||
```bash
|
||||
./rvctl debug host 1
|
||||
./rvctl debug host bss 1
|
||||
./rvctl debug host inf bss 1
|
||||
```
|
||||
|
||||
Dokumentacja i nowe przykłady powinny promować namespace `containers`.
|
||||
`rvctl` rozwiązuje `1` do właściwego zadania, na przykład
|
||||
`task1_bss`, na podstawie plików w `src/tasks`.
|
||||
|
||||
## Starsza komenda
|
||||
|
||||
`tmux-container` zostaje jako alias kompatybilności dla starszego trybu
|
||||
shellowego. Nowe przykłady powinny używać `debug`, `run`, `shell` i `env`.
|
||||
|
||||
@@ -220,6 +220,12 @@ Komendy:
|
||||
- `series cards tasks list SERIES CARD`
|
||||
- `series cards tasks show SERIES CARD TASK`
|
||||
- `series cards tasks switch SERIES CARD TASK`
|
||||
- `env list`
|
||||
- `env sync`
|
||||
- `env build rv32i|host`
|
||||
- `debug rv32i|host [TASK|CARD TASK|SERIES CARD TASK]`
|
||||
- `run host [TASK|CARD TASK|SERIES CARD TASK]`
|
||||
- `shell rv32i|host [CARD|SERIES CARD]`
|
||||
- `tasks list [CARD|SERIES CARD]`
|
||||
- `tasks show TASK|CARD TASK|SERIES CARD TASK`
|
||||
- `tasks switch TASK|CARD TASK|SERIES CARD TASK`
|
||||
@@ -560,6 +566,84 @@ Ta komenda działa tak samo jak pełna forma:
|
||||
./rvctl series cards tasks switch inf bss 4
|
||||
```
|
||||
|
||||
## `env list`
|
||||
|
||||
Pokazuje profile środowiska kontenerowego obsługiwane przez `rvctl`.
|
||||
|
||||
```bash
|
||||
./rvctl env list
|
||||
```
|
||||
|
||||
Profile:
|
||||
|
||||
- `rv32i` - RISC-V/Hazard3, `nvim`, `tmux`, `gdb-multiarch`
|
||||
- `host` - natywny kontener z `clang`, `gcc`, `gdb`, opcjonalnie `lldb`
|
||||
|
||||
## `env sync`
|
||||
|
||||
Klonuje albo aktualizuje repo `rv32i-hazard3-student-env` do katalogu
|
||||
`~/dev/workspace/rv/tools/rv32i-hazard3-student-env`.
|
||||
|
||||
```bash
|
||||
./rvctl env sync
|
||||
./rvctl env sync --dry-run
|
||||
```
|
||||
|
||||
## `env build rv32i|host`
|
||||
|
||||
Buduje wybrany profil `docker compose`.
|
||||
|
||||
```bash
|
||||
./rvctl env build rv32i
|
||||
./rvctl env build host
|
||||
./rvctl env build host --dry-run
|
||||
```
|
||||
|
||||
## `debug rv32i|host`
|
||||
|
||||
Uruchamia debugowanie zadania w kontenerze. Selektor może być pełny albo krótki.
|
||||
|
||||
```bash
|
||||
./rvctl debug rv32i inf bss 1
|
||||
./rvctl debug host inf bss 1
|
||||
./rvctl debug rv32i 4
|
||||
./rvctl debug host 4
|
||||
```
|
||||
|
||||
`rv32i` uruchamia symulator Hazard3, `gdb-multiarch` i `nvim`. `host` kompiluje
|
||||
zadanie natywnie i otwiera `gdb` obok `nvim`. Profil `host` jest przeznaczony
|
||||
dla tasków C z funkcją `main`; taski czysto asemblerowe debugujemy w profilu
|
||||
`rv32i`.
|
||||
|
||||
Przełączniki:
|
||||
|
||||
- `--task TASK` - nadpisuje zadanie z selektora albo z `workspace.json`
|
||||
- `--instance NAME` - ustawia nazwę instancji kontenera/tmuxa
|
||||
- `--editor nvim|vim` - wybiera edytor w kontenerze
|
||||
- `--dry-run` - pokazuje komendę bez uruchamiania Dockera
|
||||
|
||||
## `run host`
|
||||
|
||||
Buduje i uruchamia wybrane zadanie natywnie w kontenerze `host`.
|
||||
|
||||
```bash
|
||||
./rvctl run host inf bss 1
|
||||
./rvctl run host 4
|
||||
```
|
||||
|
||||
Profil `rv32i` pracuje obecnie przez `debug rv32i`, bo wymaga symulatora
|
||||
Hazard3 i połączenia GDB.
|
||||
|
||||
## `shell rv32i|host`
|
||||
|
||||
Otwiera shell w wybranym profilu kontenera z podmontowaną kartą.
|
||||
|
||||
```bash
|
||||
./rvctl shell rv32i inf bss
|
||||
./rvctl shell host inf bss
|
||||
./rvctl shell host --dry-run
|
||||
```
|
||||
|
||||
## `list-series`
|
||||
|
||||
Alias kompatybilności dla `series list`.
|
||||
|
||||
Reference in New Issue
Block a user