From 2c46bffba0d2ed0b94af3b82a93a5a853b4725d2 Mon Sep 17 00:00:00 2001 From: Yuriy Kolerov Date: Tue, 20 Aug 2024 15:10:38 +0300 Subject: [PATCH] arc: libgloss: Clean MetaWare hostlink documentation Signed-off-by: Yuriy Kolerov --- libgloss/arc/readme-hostlink.md | 134 ++++++++++++++++---------------- 1 file changed, 67 insertions(+), 67 deletions(-) diff --git a/libgloss/arc/readme-hostlink.md b/libgloss/arc/readme-hostlink.md index 0061be3df..e2e5a7da5 100644 --- a/libgloss/arc/readme-hostlink.md +++ b/libgloss/arc/readme-hostlink.md @@ -1,90 +1,90 @@ -Metaware hostlink IO +MetaWare Hostlink IO ==================== -This directory includes target-side implementation of Metaware hostlink -interface see Contents section. Target program can use Metaware hostlink -interface to send messages to nsim simulator or mdb debugger (it can be -attached to HW or nsim). +Target program can use MetaWare hostlink interface to send messages to nSIM +simulator or MDB debugger. -Quick start +Quick Start ----------- -To link with this version of libgloss please add `-specs=hl.specs` to baremetal -version of ARC gcc (arc-elf32). -Lets build and run simple program: +To link with MetaWare hostlink library use `-specs=hl.specs` with baremetal +version of GCC for ARC processors - `arc-elf32-gcc` for ARCv1/2 targets or +`arc64-elf-gcc` for ARCv3 targets. + +Consider this sample program named `hello.c`: - $ cat hello.c #include int main() { - printf("Hello World!\n"); - - return 0; + printf("Hello, World!\n"); + return 0; } - $ arc-elf32-gcc -mcpu=hs -specs=hl.specs ./hello.c -o hello - $ nsimdrv -prop=nsim_isa_family=av2hs -prop=nsim_hlink_gnu_io_ext=1 ./hello - Hello World! -Where `-mcpu` and `-prop=nsim_isa_family` is specific to your version of ARC CPU. -Option `-prop=nsim_hlink_gnu_io_ext=1` enables GNU IO extension for nSIM which -is used for some system calls. The `nsimdrv` option `-prop=nsim_emt={0,1,2}` -enables trap emulation and should be disabled (removed or set to `0`) to use -Metaware hostlink. +Build and run it for HS3x/4x targets: + + $ arc-elf32-gcc -mcpu=hs -specs=hl.specs hello.c -o hello.elf + $ nsimdrv -tcf $NSIM_HOME/etc/tcf/templates/hs48_full.tcf -p nsim_hostlink=1 hello.elf + Hello, World! + +Build and run it for HS5x targets: + + $ arc64-elf-gcc -mcpu=hs5x -specs=hl.specs hello.c -o hello.elf + $ nsimdrv -tcf $NSIM_HOME/etc/tcf/templates/hs58_full.tcf -p nsim_hostlink=1 hello.elf + Hello, World! -**NB:** Metaware hostlink requires symbols `__HOSTLINK__` and `_hl_blockedPeek` -to be present. So stripped binary won't work properly with Metaware hostlink. +Build and run it for HS6x targets: + + $ arc64-elf-gcc -mcpu=hs6x -specs=hl.specs hello.c -o hello.elf + $ nsimdrv -tcf $NSIM_HOME/etc/tcf/templates/hs68_full.tcf -p nsim_hostlink=1 hello.elf + Hello, World! Contents -------- -* `hl/hl_gw.*` -- Hostlink gateway. This API is used in the `hl_api.*`. - Please use `hl_message()` from `hl_api.*` for hostlink - message exchange. -* `hl/hl_api.*` -- High-level API to send hostlink messages, as well as - functions to work with messages. -* `hl/hl_.*` -- Syscall implementations through hostlink API; -* `arc-timer.*` -- Provides API to access ARC timers. Used by - `hl/hl_clock.c` in `_clock()` implementation. -* `arc-main-helper.c` -- Provides `__setup_argv_and_call_main()`. The function - is called from `__start()` in `crt0.S`. It allows - to setup `argc` and `arvg` as well as some custom - things through `_setup_low_level()`. -* `hl-setup.c` -- Provides `_setup_low_level()` for hostlink case. - It just configures default timer if it exists. Default - timer is used in the hostlink `clock()` - implementation. -* `hl-stub.c` -- Provides functions which are part of newlib but - implemented without hostlink. - e.g. `_kill()` and `_getpid()`. -* `sbrk.c` -- Provides `_sbrk()`. It uses `__start_heap` and - `__end_heap` variables. -* `libcfunc.c` -- Additional C system calls. -* `mcount.c` -- Profiler support. - -How it works + +* `hl/hl_gw.*` - Hostlink gateway. This API is used in the `hl_api.*`. + Please use `hl_message()` from `hl_api.*` for hostlink message exchange. +* `hl/hl_api.*` - High-level API to send hostlink messages, as well as + functions to work with messages. +* `hl/hl_.*` - System calls implementations through hostlink API. +* `arc-timer.*` - Provides API to access ARC timers. Used by `hl/hl_clock.c` + in `_clock()` implementation. +* `arc-main-helper.c` - Provides `__setup_argv_and_call_main()`. The function + is called from `__start()` in `crt0.S`. It allows to setup `argc` and `arvg` + as well as some custom things through `_setup_low_level()`. +* `hl-setup.c` - Provides `_setup_low_level()` for hostlink case. It just + configures default timer if it exists. Default timer is used in the hostlink + `clock()` implementation. +* `hl-stub.c` - Provides functions which are part of newlib but implemented + without hostlink. For example, `_kill()` and `_getpid()`. +* `sbrk.c` - Provides `_sbrk()`. It uses `__start_heap` and `__end_heap` + variables. +* `libcfunc.c` - Additional C system calls. +* `mcount.c` - Profiler support. + +How It Works ------------ + Simulator looks for `__HOSTLINK__` and `_hl_blockedPeek()` symbols. `__HOSTLINK__` is the start of shared structure for message exchange and `_hl_blockedPeek()` is a function to be called when program is waiting for simulator response. When program wants to send a message it should follow: - 1. Fill `__HOSTLINK__.payload` with packed data. - Packing format is following: `{u16 type, u16 size, char data[]}`. - Supported types are `char`, `short`, `int`, `string` and `int64`. - `hl_api` provides high-level API to this. - 2. Fill `__HOSTLINK__.pkt_hdr`. See `hl_pkt_init()` from `hl_gw.c`. - 3. Fill `__HOSTLINK__.hdr`. See `hl_send()` from `hl_gw.c`. - 4. Call `_hl_blockedPeek()` to get response. - At this point message should be delivered to debugger. - Some implementations uses change of `__HOSTLINK__.hdr.target2host_addr` as - a signal that packet is sent and can be processed. Other implementations - wait for `_hl_blockedPeek()` to be called. - - It means that portable implementation must fill - `__HOSTLINK__.hdr.target2host_addr` at the last step and then call - `_hl_blockedPeek()`. - 5. `_hl_blockedPeek()` returns pointer to debugger response which can be - processed on target if needed. Because debugger and target share the same - buffer the function actually returns `__HOSTLINK__.payload` that was - filled with packed data (see step 1) by the debugger. + +1. Fill `__HOSTLINK__.payload` with packed data. Packing format is following: + `{u16 type, u16 size, char data[]}`. Supported types are `char`, `short`, + `int`, `string` and `int64`. `hl_api` provides high-level API to this. +2. Fill `__HOSTLINK__.pkt_hdr`. See `hl_pkt_init()` from `hl_gw.c`. +3. Fill `__HOSTLINK__.hdr`. See `hl_send()` from `hl_gw.c`. +4. Call `_hl_blockedPeek()` to get response. At this point message should be + delivered to debugger. Some implementations uses change of + `__HOSTLINK__.hdr.target2host_addr` as a signal that packet is sent and can + be processed. Other implementations wait for `_hl_blockedPeek()` to be + called. It means that portable implementation must fill + `__HOSTLINK__.hdr.target2host_addr` at the last step and then call + `_hl_blockedPeek()`. +5. `_hl_blockedPeek()` returns pointer to debugger response which can be + processed on target if needed. Because debugger and target share the same + buffer the function actually returns `__HOSTLINK__.payload` that was + filled with packed data (see step 1) by the debugger. -- 2.43.5