Merge branch 'arc-dev' into arc-staging

Author: synopsys-arcoss-auto

doc/baremetal/hostlink.rst

@@ -20,31 +20,78 @@ in the case of simplest applications that do not use system IO, there is still
 a need to provide implementation of ``_exit()`` either through linking with some
 libgloss implementation or by implementing it right in the application.
 
-Because libgloss implementation is often specific to a particular chip (nee
-:abbr:`BSP (board support package)`), Synopsys provides only two libgloss
-implementation as of now - libnsim, that supports nSIM GNU IO Hostlink and
-libnosys, which is really an architecture-agnostic implementation, that simply
-provides empty stubs for a few of the most used system functions - this is
-enough to link an application, however it may not function as expected.
+libgloss implementation is often specific to a particular chip and runtime
+configuration and it is not possible to cover them all in the toolchain
+distribution. However, Synopsys provides several libgloss implementations
+to cover as much usecases as possible. The libgloss implementation can be
+selected with the ``--specs`` gcc option. Consider three most useful libgloss
+implementations.
+
+1. ``nsim.specs`` implements nSIM GNU IO Hostlink. It works via software
+exceptions, just like the syscalls in real OS - when target application needs
+something to be done by the hostlink, it causes a software exception with
+parameters that specify what action is required. nSIM intercepts those
+exceptions and handles them. The advantage of this approach is that same
+application binary can be used with other execution environments, which also
+handle software exceptions - unlike the case where a system function
+implementation is really baked inside the application binary. To use nSIM GNU
+IO hostlink in an application, add option ``--specs=nsim.specs`` to gcc options
+when linking - library ``libnsim.a`` will be linked in and will provide
+implementations to those system level functions. For example, consider simple
+program ``hello.c``:
+
+.. code-block:: c
+
+   #include <stdio.h>
+   int main()
+   {
+       printf("Hello World!\n");
+       return 0;
+   }
+
+Let's build it for ARC HS with nSIM GNU IO Hostlink support and run in nSIM:
+
+.. code-block:: text
 
-nSIM GNU IO Hostlink works via software exceptions, just like the syscalls in
-real OS - when target application needs something to be done by the hostlink,
-it causes a software exception with parameters that specify what action is
-required. nSIM intercepts those exceptions and handles them. The advantage of
-this approach is that same application binary can be used with other execution
-environments, which also handle software exceptions - unlike the case where a
-system function implementation is really baked inside the application binary.
+   $ arc-elf32-gcc -mcpu=hs --specs=nsim.specs ./hello.c -o hello
+   $ nsimdrv -prop=nsim_isa_family=av2hs -prop=nsim_emt=1 ./hello
+   Hello World!
 
-To use hostlink in application, add option ``--specs=nsim.specs`` to gcc options
-when linking - library libnsim.a will be linked in and will provide
-implementations to those system level functions
+Please note ``-prop=nsim_emt=1`` (emulate traps) option which enables nSIM GNU IO
+Hostlink in nSIM. More details can be found in nSIM documentation.
+
+2. ``hl.specs`` implements Metaware Hostlink. It works via memory mailbox named
+``__HOSTLINK__``. The running application fills this mailbox and then debugger
+or simulator executes requested system call. The advantage of this approach is
+that the binary can be executed in the real hardware under Metaware Debugger.
+If ``__HOSTLINK__`` symbol is not available (binary is stripped, debugger
+connects to the running target) correct address can be passed to Metaware
+Debugger ``mdb`` through ``-prop=__HOSTLINK__=address`` option. To use Metaware
+Hostlink, add option ``--specs=hl.specs`` to the linker. Let’s build and run
+our ``hello.c`` with Metaware Hostlink:
+
+.. code-block:: text
+
+   $ 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!
+
+Please note ``-prop=nsim_hlink_gnu_io_ext=1`` option which enables some
+additional system calls support in nSIM. Also make sure that ``-prop=nsim_emt``
+option is disabled in nSIM, because only one Hostlink type can be used at the
+same time.
+
+3. ``nosys.specs``, which is really an architecture-agnostic implementation, that
+simply provides empty stubs for a few of the most used system functions - this is
+enough to link an application, however it may not function as expected.
 
 To use a generic libnosys library, add option ``--specs=nosys.specs`` to gcc
 options when linking. Note that one of the important distinction between
-libnsim and libnosys is that ``_exit()`` implementation in libnosys is an
-infinite loop, while in libnsim it will halt the CPU core. As a result, at the
-end of an execution, application with libnosys will spin, while application
-with libnsim will halt.
+hostlink libraries and ``libnosys`` is that ``_exit()`` implementation in
+``libnosys`` is an infinite loop, while in hostlink implementations it will halt
+the CPU core. As a result, at the end of an execution, application with
+``libnosys`` will spin, while application with hostlink will halt. This spec file
+is the default option.
 
 If you are a chip and/or OS developer it is likely that you would want to
 provide a libgloss implementation appropriate for your case, because libnsim.a

release.mk

@@ -572,7 +572,7 @@ $O/.stamp_elf_le_built: $(TOOLS_ALL_DEPS-y) | $(TOOLS_ALL_ORDER_DEPS-y)
 	touch $@
 
 $O/.stamp_elf_be_built: $(TOOLS_ALL_DEPS-y) | $(TOOLS_ALL_ORDER_DEPS-y)
-	$(call copy_prebuilt,arc-arc700-linux-uclibc,$(TOOLS_ELFBE_HOST_DIR))
+	$(call copy_prebuilt,arceb-multilib-elf32,$(TOOLS_ELFBE_HOST_DIR))
 	$(call copy_pdf_doc_file,$O/$(TOOLS_ELFBE_HOST_DIR))
 	touch $@
 
@@ -764,7 +764,7 @@ linux-images: $O/$(LINUX_IMAGES_DIR)/$(LINUX_AXS103_ROOTFS_TAR)
 # Native toolchain build
 #
 $O/.stamp_glibc_le_hs_native_built: $(TOOLS_ALL_DEPS-y) | $(TOOLS_ALL_ORDER_DEPS-y)
-	$(call copy_prebuilt,arceb-archs-linux-gnu,$(TOOLS_GLIBC_LE_HS_NATIVE_DIR))
+	$(call copy_prebuilt,arc-archs-native-gnu,$(TOOLS_GLIBC_LE_HS_NATIVE_DIR))
 	$(call copy_pdf_doc_file,$O/$(TOOLS_GLIBC_LE_HS_NATIVE_DIR))
 	touch $@