libs/newlib-cygwin
libs/newlib-cygwin
4
0
Fork 0
mirror of git://sourceware.org/git/newlib-cygwin.git synced 2025-02-21 00:07:36 +08:00
Code Issues Projects Releases Wiki Activity

arc: libgloss: Clean MetaWare hostlink documentation

Browse Source 
Signed-off-by: Yuriy Kolerov <ykolerov@synopsys.com>
This commit is contained in:
Yuriy Kolerov 2024-08-20 15:10:38 +03:00 committed by Jeff Johnston
parent d7d4fe4f4a
commit 2c46bffba0
1 changed files with 65 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
libgloss/arc/readme-hostlink.md
View File

@ -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 <stdio.h>
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:
**NB:** Metaware hostlink requires symbols `__HOSTLINK__` and `_hl_blockedPeek`
to be present. So stripped binary won't work properly with Metaware hostlink.
$ 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!
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>.*` -- 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_<syscall>.*` - 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.