From patchwork Tue Aug 20 12:10:38 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Yuriy Kolerov X-Patchwork-Id: 96149 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 8963B386D625 for ; Tue, 20 Aug 2024 12:12:55 +0000 (GMT) X-Original-To: newlib@sourceware.org Delivered-To: newlib@sourceware.org Received: from mx0b-00230701.pphosted.com (mx0b-00230701.pphosted.com [148.163.158.9]) by sourceware.org (Postfix) with ESMTPS id BD1013846091 for ; Tue, 20 Aug 2024 12:11:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org BD1013846091 Authentication-Results: sourceware.org; dmarc=pass (p=quarantine dis=none) header.from=synopsys.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=synopsys.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org BD1013846091 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=148.163.158.9 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1724155897; cv=none; b=DKzC5PLCimLK0BO3DSDM7dAE6i5JWLOeVQZ2m1F+8lUe8SONf1L20UygA2D/7O13JLSxTWNEc92tGmdBH9+yxF/PJvO8mDKqkiMeWdMC/+hHh0tmNMWBa4sh8XAiqM3nMzGAMG/ljF8MAT9susrvDnNgMJvUktKEEAEBNr7i9NU= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1724155897; c=relaxed/simple; bh=1HMnYehs1qwZ2azX7LOUsuPiWn/P9FBE4Nwp4vltgEo=; h=DKIM-Signature:DKIM-Signature:From:To:Subject:Date:Message-Id: MIME-Version; b=vt6R25sm9oo+BkNBHQNPgrqCUw3PxhVz7+AeZuTBtD/GPY7XeO564BSo+wjrlY63iUh5t4dIWA9UADhPkXxmiy8an6ANYbvICaceINC1CmFoA8+XEsV0xkdjO74qUdxr46rwVMyzO73EdxNDahKl6GKraNZ8gwRfI7WV5lGgBcs= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from pps.filterd (m0297265.ppops.net [127.0.0.1]) by mx0a-00230701.pphosted.com (8.18.1.2/8.18.1.2) with ESMTP id 47KBaQd9020114 for ; Tue, 20 Aug 2024 05:11:32 -0700 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=synopsys.com; h= cc:content-transfer-encoding:date:from:in-reply-to:message-id :mime-version:references:subject:to; s=pfptdkimsnps; bh=KcSoZLut LPBFZmteAwA2PQ0goyKVmIXnKciT0db5P14=; b=qi5nlnUlaYaTGCqdJmuVal3b AQaXgskeWRqBguwclMs4D2nLJJLIJfqNeHOsy5Y0ZbBVKEY2QmV44lxRd7h1l6yb HTxoL3Upte1nQsqj6jiDCveB20ZdllekEksy9E3bKKieXuPtfsubFXn6jjp7vTa9 FxK4TnQ3YZyrw/qtJE5zFY59+a+Aykdq5Aq+B4bypPVlak7MiSZvEVJDioA0QByq GDttz2i88U8p1w1aS20YkegScW5TRxk3tpUtFtsoSW2FD1WrWAN3foEfNZi646vL xAihKFZhOQr1KPYlprCy62v0Wsdtinkg9CbKH3ZDWSPV+1pAk/mIhhnePtuP5Q== Received: from smtprelay-out1.synopsys.com (smtprelay-out1.synopsys.com [149.117.73.133]) by mx0a-00230701.pphosted.com (PPS) with ESMTPS id 414g8mapvj-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT) for ; Tue, 20 Aug 2024 05:11:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=synopsys.com; s=mail; t=1724155891; bh=1HMnYehs1qwZ2azX7LOUsuPiWn/P9FBE4Nwp4vltgEo=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ccfmcjffzB4vWxEiiljDZEZPIGvdXbcW+z6A4rTQ5ZSLojuPa2O29yTRRjYiD6p19 drum/BKp7a+zZVKXwFr6nMD+5zcfKBECedRtTsl5zK0MKLoEKi0AOAberH4bmnU/aS vrfpJTohIfQSSLfyveOlREtqRJTvcyXMN072fMev9WPQv/ed911qzD78+7zkijzms+ MI5QBYzhGHwsTJkZvIJAjKpP2UOhfYIYkkMoR8uAN+YbNlLJxzm8YCVA/v5Z2hfr+9 VehlF2tZwMsaxj//E6FMFo4xKTTSu+MGisseRdYkctuGg2CAPKqBkARAYnJU7i8cVG zrY+c6Kk22Jew== Received: from mailhost.synopsys.com (eudc-mailhost2.synopsys.com [10.213.161.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "mailhost.synopsys.com", Issuer "SNPSica2" (verified OK)) by smtprelay-out1.synopsys.com (Postfix) with ESMTPS id E8EAF4048B for ; Tue, 20 Aug 2024 12:11:30 +0000 (UTC) Received: from SNPS-HRlPxd6IgG.internal.synopsys.com (snps-hrlpxd6igg.internal.synopsys.com [10.120.15.83]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (Client did not present a certificate) by mailhost.synopsys.com (Postfix) with ESMTPSA id 22828C0CBA; Tue, 20 Aug 2024 12:11:29 +0000 (UTC) X-SNPS-Relay: synopsys.com From: Yuriy.Kolerov@synopsys.com To: newlib@sourceware.org Cc: Yuriy Kolerov Subject: [PATCH 3/8] arc: libgloss: Clean MetaWare hostlink documentation Date: Tue, 20 Aug 2024 15:10:38 +0300 Message-Id: <20240820121043.1605628-4-ykolerov@synopsys.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240820121043.1605628-1-ykolerov@synopsys.com> References: <20240820121043.1605628-1-ykolerov@synopsys.com> MIME-Version: 1.0 X-Authority-Analysis: v=2.4 cv=HYFGTTE8 c=1 sm=1 tr=0 ts=66c487f4 cx=c_pps a=8EbXvwLXkpGsT4ql/pYRAw==:117 a=8EbXvwLXkpGsT4ql/pYRAw==:17 a=yoJbH4e0A30A:10 a=jIQo8A4GAAAA:8 a=Ob3TOZBIjYyB0-eJeHUA:9 a=Lf5xNeLK5dgiOs8hzIjU:22 X-Proofpoint-GUID: MwJid2_nXpgQ-LSv8AQSmlXKVfwjuwMP X-Proofpoint-ORIG-GUID: MwJid2_nXpgQ-LSv8AQSmlXKVfwjuwMP X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1039,Hydra:6.0.680,FMLib:17.12.28.16 definitions=2024-08-20_09,2024-08-19_03,2024-05-17_01 X-Proofpoint-Spam-Details: rule=outbound_active_cloned_notspam policy=outbound_active_cloned score=0 clxscore=1015 priorityscore=1501 malwarescore=0 phishscore=0 bulkscore=0 impostorscore=0 spamscore=0 mlxscore=0 mlxlogscore=882 suspectscore=0 lowpriorityscore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.19.0-2407110000 definitions=main-2408200090 X-Spam-Status: No, score=-11.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, SPF_HELO_NONE, SPF_PASS, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: newlib@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Newlib mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: newlib-bounces~patchwork=sourceware.org@sourceware.org From: Yuriy Kolerov 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.