91 lines
4.1 KiB
Markdown
91 lines
4.1 KiB
Markdown
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).
|
|
|
|
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:
|
|
|
|
$ cat hello.c
|
|
#include <stdio.h>
|
|
|
|
int main()
|
|
{
|
|
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.
|
|
|
|
**NB:** Metaware hostlink requires symbols `__HOSTLINK__` and `_hl_blockedPeek`
|
|
to be present. So stripped binary won't work properly with Metaware hostlink.
|
|
|
|
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
|
|
------------
|
|
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.
|