mirror of
git://sourceware.org/git/newlib-cygwin.git
synced 2025-02-21 00:07:36 +08:00
arc: libgloss: Clean MetaWare hostlink documentation
Signed-off-by: Yuriy Kolerov <ykolerov@synopsys.com>
This commit is contained in:
parent
d7d4fe4f4a
commit
2c46bffba0
@ -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.
|
||||
|
Loading…
x
Reference in New Issue
Block a user