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.