xref: /Zephyr-latest/boards/native/native_sim/doc/index.rst

.. _native_sim:

Native simulator - native_sim
#############################

.. contents::
   :depth: 1
   :backlinks: entry
   :local:

Overview
********

The ``native_sim`` board is a :ref:`POSIX architecture<Posix arch>` based board.
With it, a Zephyr application can be compiled together with
the Zephyr kernel, and libraries, creating a normal Linux executable.

``native_sim`` is based on the
`native simulator <https://github.com/BabbleSim/native_simulator/>`_
and the :ref:`POSIX architecture<Posix arch>`.

This board does not intend to simulate any particular HW, but it provides
a few peripherals such as an Ethernet driver, display, UART, etc., to enable
developing and testing application code which would require them.
See `Peripherals`_ for more information.

.. note::

   | ``native_sim`` is an evolution of its predecessor ``native_posix``.
   | Some components, code, options names, and documentation will still use the old native_posix
     names. But all components which worked with native_posix will work with native_sim.

Host system dependencies
************************

Please check the
:ref:`Posix Arch Dependencies<posix_arch_deps>`

.. _nativesim_important_limitations:

Important limitations and unsupported features
**********************************************

``native_sim`` is based on the :ref:`POSIX architecture<Posix arch>`, and therefore
:ref:`its limitations <posix_arch_limitations>` and considerations apply to it.

Similarly, it inherits the POSIX architecture
:ref:`unsupported features set <posix_arch_unsupported>`.

Note that some drivers may have limitations, or may not support their whole driver API optional
functionality.

.. _native_sim_how_to_use:

How to use it
*************

Compiling
=========

To build, simply specify the ``native_sim`` board as target:

.. zephyr-app-commands::
   :zephyr-app: samples/hello_world
   :host-os: unix
   :board: native_sim
   :goals: build
   :compact:

Running
=======

The result of the compilation is an executable (``zephyr.exe``) placed in the
``zephyr/`` subdirectory of the ``build`` folder.
Run the ``zephyr.exe`` executable as you would any other Linux console application.

.. code-block:: console

   $ ./build/zephyr/zephyr.exe
   # Press Ctrl+C to exit

This executable accepts several command line options depending on the
compilation configuration.
You can run it with the ``--help`` command line switch to get a list of
available options.

.. code-block:: console

   $ ./build/zephyr/zephyr.exe --help

Note that the Zephyr kernel does not actually exit once the application is
finished. It simply goes into the idle loop forever.
Therefore you must stop the application manually (Ctrl+C in Linux).

Application tests using the :ref:`ztest framework<test-framework>` will exit after all
tests have completed.

If you want your application to gracefully finish when it reaches some point,
you may add a conditionally compiled (:kconfig:option:`CONFIG_ARCH_POSIX`) call to
``nsi_exit(int status)`` at that point.

.. _native_sim_debug:

Debugging
=========

Since the Zephyr executable is a native application, it can be debugged and
instrumented as any other native program. The program is compiled with debug
information, so it can be run directly in, for example, ``gdb`` or instrumented
with ``valgrind``.

Because the execution of your Zephyr application is normally deterministic
(there are no asynchronous or random components), you can execute the
code multiple times and get the exact same result. Instrumenting the
code does not affect its execution.

To ease debugging you may want to compile your code without optimizations
(e.g., ``-O0``) by setting :kconfig:option:`CONFIG_NO_OPTIMIZATIONS`.

For ease of debugging consider using an IDE as GUI for your debugger.

.. _native_sim_asan:

Address Sanitizer (ASan)
========================

You can also build Zephyr with the `Address Sanitizer`_. To do this, set
:kconfig:option:`CONFIG_ASAN`, for example, in the application project file, or in the
``west build`` or ``cmake`` command line invocation.

Note that you will need the ASan library installed in your system.
In Debian/Ubuntu this is ``libasan1``.

.. _Address Sanitizer:
   https://github.com/google/sanitizers/wiki/AddressSanitizer

Undefined Behavior Sanitizer (UBSan)
====================================

You can also build Zephyr with the `Undefined Behavior Sanitizer`_. To do this, set
:kconfig:option:`CONFIG_UBSAN`, for example, in the application project file, or in the
``west build`` or ``cmake`` command line invocation.

.. _Undefined Behavior Sanitizer:
   https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html

Coverage reports
================

See
:ref:`coverage reports using the POSIX architecture<coverage_posix>`.


.. _native_sim32_64:

32 and 64bit versions
=====================

native_sim comes with two targets: A 32 bit and 64 bit version.
The 32 bit version, ``native_sim``, is the default target, which will compile
your code for the ILP32 ABI (i386 in a x86 or x86_64 system) where pointers
and longs are 32 bits.
This mimics the ABI of most embedded systems Zephyr targets,
and is therefore normally best to test and debug your code, as some bugs are
dependent on the size of pointers and longs.
This target requires either a 64 bit system with multilib support installed or
one with a 32bit userspace.

The 64 bit version, ``native_sim/native/64``, compiles your code targeting the
LP64 ABI (x86-64 in x86 systems), where pointers and longs are 64 bits.
You can use this target if you cannot compile or run 32 bit binaries.

.. _native_sim_Clib_choice:

C library choice
****************

native_sim may be compiled with a choice of C libraries.
By default it will be compiled with the host C library (:kconfig:option:`CONFIG_EXTERNAL_LIBC`),
but you can also select to build it with :kconfig:option:`CONFIG_MINIMAL_LIBC` or with
:kconfig:option:`CONFIG_PICOLIBC`.
If you select some feature which are not compatible with the host C library,
:ref:`Picolibc <c_library_picolibc>` will be selected by default instead.

When building with either :ref:`minimal <c_library_minimal>` or :ref:`Picolibc<c_library_picolibc>`
you will build your code in a more similar way as when building for the embedded target,
you will be able to test your code interacting with that C library,
and there will be no conflicts with the :ref:`POSIX OS abstraction<posix_support>` shim,
but, accessing the host for test purposes from your embedded code will be more
difficult, and you will have a limited choice of
:ref:`drivers and backends to chose from<native_sim_peripherals_c_compat>`.

Rationale for this port and comparison with other options
*********************************************************

The native_sim board shares the overall
:ref:`intent of the POSIX architecture<posix_arch_rationale>`,
while being a HW agnostic test platform which in some cases utilizes the host
OS peripherals.
It does not intend to model any particular HW, and as such can only be used
to develop and test application code which is far decoupled from the HW.

For developing and testing SW which requires specific HW, while retaining the
benefits of the POSIX architecture other solutions like the
:ref:`bsim boards<bsim boards>`
should be considered.

Check the :ref:`POSIX architecture comparison <posix_arch_compare>`
with other development and test options for more insights.

.. _native_sim_architecture:

Architecture
************

This board is based on the POSIX architecture port of Zephyr and shares
:ref:`its basic architecture<posix_arch_architecture>` regarding threading
and CPU/HW scheduling.

If you are interested on the inner workings of the native simulator itself, you can check
`its documentation <https://github.com/BabbleSim/native_simulator/blob/main/docs/README.md>`_.

This board does not try to emulate any particular embedded CPU or SOC.
The code is compiled natively for the host system (typically x86).

About time in native_sim
========================

Normally simulated time runs fully decoupled from the real host time
and as fast as the host compute power would allow.
This is desirable when running in a debugger or testing in batch, but not if
interacting with external interfaces based on the real host time.

The Zephyr kernel is only aware of the simulated time as provided by the
HW models. Therefore any normal Zephyr thread will also know only about
simulated time.

The only link between the simulated time and the real/host time, if any,
is created by the clock and timer model.

This model can be configured to slow down the execution of native_sim to
real time.
You can do this with the ``--rt`` and ``--no-rt`` options from the command line.
The default behavior is set with
:kconfig:option:`CONFIG_NATIVE_SIM_SLOWDOWN_TO_REAL_TIME`.

Note that all this model does is wait before raising the
next system tick interrupt until the corresponding real/host time.
If, for some reason, native_sim runs slower than real time, all this
model can do is "catch up" as soon as possible by not delaying the
following ticks.
So if the host load is too high, or you are running in a debugger, you will
see simulated time lagging behind the real host time.
This solution ensures that normal runs are still deterministic while
providing an illusion of real timeness to the observer.

When locked to real time, simulated time can also be set to run faster or
slower than real time.
This can be controlled with the ``--rt-ratio=<ratio>`` and ``-rt-drift=<drift>``
command line options. Note that both of these options control the same
underlying mechanism, and that ``drift`` is by definition equal to
``ratio - 1``.
It is also possible to adjust this clock speed on the fly with
:c:func:`native_rtc_adjust_clock()`.

In this way if, for example, ``--rt-ratio=2`` is given, the simulated time
will advance at twice the real time speed.
Similarly if ``--rt-drift=-100e-6`` is given, the simulated time will progress
100ppm slower than real time.
Note that these 2 options have no meaning when running in non real-time
mode.

How simulated time and real time relate to each other
-----------------------------------------------------

Simulated time (``st``) can be calculated from real time (``rt``) as

.. math::
  st = (rt - last\_rt) \times ratio + last\_st

And vice-versa:

.. math::
  rt = (st - last\_st) / ratio + last\_rt

Where ``last_rt`` and ``last_st`` are respectively the real time and the
simulated time when the last clock ratio adjustment took place.

All times are kept in microseconds.

.. _native_sim_peripherals:

Peripherals
***********

The following peripherals are currently provided with this board:

**Interrupt controller**
  A simple yet generic interrupt controller is provided. It can nest interrupts
  and provides interrupt priorities. Interrupts can be individually masked or
  unmasked. SW interrupts are also supported.

**Clock, timer and system tick model**
  This model provides the system tick timer. By default
  :kconfig:option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC` configures it to tick every 10ms.

  Please refer to the section `About time in native_sim`_ for more
  information.

**UART/Serial**
   Two optional native UART drivers are available:

   **PTY driver (UART_NATIVE_PTY)**
      With this driver, Zephyr UART devices can be created. These
      can be connected to the Linux process stdin/stdout or a newly created
      pseudo-tty. For more information refer to the section `PTY UART`_.

   **TTY driver (UART_NATIVE_TTY)**
      An UART driver for interacting with host-attached serial port devices
      (eg. USB to UART dongles). For more information refer to the section
      `TTY UART`_.

**Real time clock**
  The real time clock model provides a model of a constantly powered clock.
  By default this is initialized to the host time at boot.

  This RTC can also be set to start from time 0 with the ``--rtc-reset`` command
  line option.

  It is possible to offset the RTC clock value at boot with the
  ``--rtc-offset=<offset>`` option,
  or to adjust it dynamically with the function :c:func:`native_rtc_offset`.

  After start, this RTC advances with the simulated time, and is therefore
  affected by the simulated time speed ratio.
  See `About time in native_sim`_ for more information.

  The time can be queried with the functions :c:func:`native_rtc_gettime_us`
  and :c:func:`native_rtc_gettime`. Both accept as parameter the clock source:

  - ``RTC_CLOCK_BOOT``: It counts the simulated time passed since boot.
    It is not subject to offset adjustments
  - ``RTC_CLOCK_REALTIME``: RTC persistent time. It is affected by
    offset adjustments.
  - ``RTC_CLOCK_PSEUDOHOSTREALTIME``: A version of the real host time,
    as if the host was also affected by the clock speed ratio and offset
    adjustments performed to the simulated clock and this RTC. Normally
    this value will be a couple of hundredths of microseconds ahead of the
    simulated time, depending on the host execution speed.
    This clock source should be used with care, as depending on the actual
    execution speed of native_sim and the host load,
    it may return a value considerably ahead of the simulated time.

  Note this device does not yet have an :ref:`RTC API compatible driver <rtc_api>`.

.. _nsim_per_entr:

**Entropy device**
  An entropy device based on the host :c:func:`random` API.
  This device will generate the same sequence of random numbers if initialized
  with the same random seed.
  You can change this random seed value by using the command line option:
  :samp:`--seed={<random_seed>}` where the value specified is a 32-bit integer
  such as 97229 (decimal),  0x17BCD (hex), or 0275715 (octal).

.. _nsim_per_ethe:

**Ethernet driver**
  A simple TAP based ethernet driver is provided. The driver expects that the
  **zeth** network interface already exists in the host system. The **zeth**
  network interface can be created by the ``net-setup.sh`` script found in
  the `net-tools`_ zephyr project repository. User can communicate with the
  Zephyr instance via the **zeth** network interface. Multiple TAP based
  network interfaces can be created if needed. The IP address configuration
  can be specified for each network interface instance.

  Note that this device can only be used with Linux hosts.

.. _`net-tools`: https://github.com/zephyrproject-rtos/net-tools

.. _nsim_per_offloaded_sockets:

**Offloaded sockets driver**
  This driver is an alternative to the :ref:`TAP based ethernet driver
  <nsim_per_ethe>`. Instead of using a virtual network in the Linux side, this
  driver utilizes Linux's standard BSD socket API. With this, multiple Zephyr
  applications can communicate over the Linux loopback interface.
  The benefit of this approach is that root privileges are not required and
  that the process is connected to the same interface as other Linux processes
  instead of a virtual network, facilitating testing without the need for extra
  setup in the host. The drawback is that the L2 layer of Zephyr's networking
  stack is not exercised.

.. _nsim_bt_host_cont:

**Bluetooth controller**
  It's possible to use the host's Bluetooth adapter as a Bluetooth
  controller for Zephyr. To do this the HCI device needs to be passed as
  a command line option to ``zephyr.exe``. For example, to use ``hci0``,
  use ``sudo zephyr.exe --bt-dev=hci0``. Using the device requires root
  privileges (or the CAP_NET_ADMIN POSIX capability, to be exact) so
  ``zephyr.exe`` needs to be run through ``sudo``. The chosen HCI device
  must be powered down and support Bluetooth Low Energy (i.e. support the
  Bluetooth specification version 4.0 or greater).

  Another possibility is to use a HCI TCP server which acts as a
  :ref:`virtual Bluetooth controller<bluetooth_virtual_posix>` over TCP.
  To connect to a HCI TCP server its IP address and port number must
  be specified. For example, to connect to a HCI TCP server with IP
  address 127.0.0.0 and port number 1020 use ``zephyr.exe --bt-dev=127.0.0.1:1020``.
  This alternative option is mainly aimed for testing Bluetooth connectivity over
  a virtual Bluetooth controller that does not depend on the Linux Bluetooth
  stack and its HCI interface.

.. _nsim_per_usb:

**USB controller**
  It's possible to use the Virtual USB controller working over USB/IP
  protocol. More information can be found in
  :ref:`Testing USB over USP/IP in native_sim <testing_USB_native_sim>`.

.. _nsim_per_disp_sdl:

**Display driver**
  A display driver is provided that creates a window on the host machine to
  render display content.

  When building for the default 32bit ``native_sim`` target this driver requires a 32-bit version of
  the `SDL2`_ development library on the host machine. For
  :ref:`64bit native_sim<native_sim32_64>` builds you need to have the 64bit version installed.
  You may also need to set ``pkg-config`` to correctly pickup the SDL2 install path.

  On Ubuntu the package is ``libsdl2-dev`` whose 64bit version is likely installed by default.
  On an Ubuntu 18.04 host system, you can install the ``pkg-config`` and the 32bit
  ``libsdl2-dev:i386`` packages, and configure the pkg-config search path with these commands:

  .. code-block:: console

     $ sudo dpkg --add-architecture i386
     $ sudo apt update
     $ sudo apt-get install pkg-config libsdl2-dev:i386
     $ export PKG_CONFIG_PATH=/usr/lib/i386-linux-gnu/pkgconfig

.. _SDL2:
   https://www.libsdl.org

.. _nsim_per_flash_simu:

**EEPROM simulator**
  The EEPROM simulator can also be used in the native targets. In these, you have the added feature
  of keeping the EEPROM content on a file on the host filesystem.
  By default this is kept in the file :file:`eeprom.bin` in the current working directory, but you
  can select the location of this file and its name with the command line parameter ``--eeprom``.
  Some more information can be found in :ref:`the emulators page <emul_eeprom_simu_brief>`.

**Flash simulator**
  The flash simulator can also be used in the native targets. In this you have the option to keep
  the flash content in a binary file on the host file system or in RAM. The behavior of the flash
  device can be configured through the native_sim board devicetree or Kconfig settings under
  :kconfig:option:`CONFIG_FLASH_SIMULATOR`.

  By default the binary data is located in the file :file:`flash.bin` in the current
  working directory. The location of this file can be changed through the
  command line parameter ``--flash``. The flash data will be stored in raw format
  and the file will be truncated to match the size specified in the devicetree
  configuration. In case the file does not exists the driver will take care of
  creating the file, else the existing file is used.

  Some more information can be found in :ref:`the emulators page <emul_flash_simu_brief>`.

  The flash content can be accessed from the host system, as explained in the
  `Host (FUSE) filesystem access`_ section.

**Input events**
  Two optional native input drivers are available:

  **evdev driver**
    A driver is provided to read input events from a Linux evdev input device and
    inject them back into the Zephyr input subsystem.

    The driver is automatically enabled when :kconfig:option:`CONFIG_INPUT` is
    enabled and the devicetree contains a node such as:

    .. code-block:: dts

       evdev {
         compatible = "zephyr,native-linux-evdev";
       };

    The application then has to be run with a command line option to specify
    which evdev device node has to be used, for example
    ``zephyr.exe --evdev=/dev/input/event0``.

  **Input SDL touch**
    This driver emulates a touch panel input using the SDL library. It can be enabled with
    :kconfig:option:`CONFIG_INPUT_SDL_TOUCH` and configured with the device tree binding
    :dtcompatible:`zephyr,input-sdl-touch`.

    More information on using SDL and the Display driver can be found in
    :ref:`its section <nsim_per_disp_sdl>`.

**CAN controller**
  It is possible to use a host CAN controller with the native SocketCAN Linux driver. It can be
  enabled with :kconfig:option:`CONFIG_CAN_NATIVE_LINUX` and configured with the device tree binding
  :dtcompatible:`zephyr,native-linux-can`.

  It is possible to specify which CAN interface will be used by the app using the ``--can-if``
  command-line option. This option overrides **every** Linux SocketCAN driver instance to use the specified
  interface.

.. _native_ptty_uart:

PTY UART
=========

This driver is automatically enabled when devicetree contains nodes with the
``"zephyr,native-pty-uart"`` compatible property and ``okay`` status and
:kconfig:option:`CONFIG_SERIAL` is set.
By default one ready UART of this type is setup in DTS, but any number can be enabled as desired.

Normally these UARTs are connected to new pseudoterminals PTYs, i.e. :file:`/dev/pts{<nbr>}`,
but it is also possible to map one of them to the executable's ``stdin`` and ``stdout``.
This can be done in two ways, either with the command line option ``--<uart_name>_stdinout``
(where ``<uart_name>`` is the UART DTS node name), or, for the first PTY UART instance by chosing
:kconfig:option:`CONFIG_UART_NATIVE_PTY_0_ON_STDINOUT` instead of the default
:kconfig:option:`CONFIG_UART_NATIVE_PTY_0_ON_OWN_PTY`.
For interactive use with the :ref:`shell_api`, it is recommended to choose the PTY option.
The ``STDINOUT`` option can be used for automated testing, such as when piping other processes'
output to control it. This is because the shell subsystem expects access to a raw terminal,
which (by default) a normal Linux terminal is not.

When a UART is connected to a new PTY, the name of the newly created UART pseudo-terminal will be
displayed in the console.
If you want to interact with it manually, you should attach a terminal emulator to it.
This can be done, for example with the command:

.. code-block:: console

   $ xterm -e screen /dev/<ptyn> &
   # Or if you prefer gnome-terminal:
   $ gnome-terminal -- screen /dev/<ptyn> &

where :file:`/dev/{<ptyn>}` should be replaced with the actual PTY device.

You may also chose to automatically attach a terminal emulator to any of these UARTs.
To automatically attach one to all these UARTs, pass the command line option ``-attach_uart`` to the
executable. To automatically attach one to a single UART use ``-<uart_name>_attach_uart``
The command used for attaching to the new shell can be set for all UARTs with the command line
option ``-attach_uart_cmd=<"cmd">``, or for each individual UART with
``-<uart_name>_attach_uart_cmd``. Where the default command is given by
:kconfig:option:`CONFIG_UART_NATIVE_PTY_AUTOATTACH_DEFAULT_CMD`.
Note that the default command assumes both ``xterm`` and ``screen`` are installed in the system.

This driver only supports poll mode. Interrupt and async mode are not supported.
Neither runtime configuration or line control are supported.

.. _native_tty_uart:

TTY UART
========

With this driver an application can use the polling and interrupt based UART APIs to write and read
characters to and from a connected serial port device.

This driver is automatically enabled when a devicetree contains a node
with ``"zephyr,native-tty-uart"`` compatible property and ``okay`` status, such
as one below.

.. code-block:: dts

   uart {
     status = "okay";
     compatible = "zephyr,native-tty-uart";
     serial-port = "/dev/ttyUSB0";
     current-speed = <115200>;
   };

Interaction with serial ports can be configured in several different ways:

* The default serial port and baud rate can be set via the device tree
  properties ``serial-port`` and ``current-speed`` respectively.  The
  ``serial-port`` property is optional.
* Serial port and baud rate can also be set via command line options ``X_port``
  and ``X_baud`` respectively, where ``X`` is a name of a node. Command line
  options override values from the devicetree.
* The rest of the configuration options such as number of data and stop bits,
  parity, as well as baud rate can be set at runtime with ``uart_configure``.
* This driver can emulate an interrupt-driven UART by enabling
  :kconfig:option:`CONFIG_UART_INTERRUPT_DRIVEN`.

Multiple instances of such uart drivers are supported.

The :zephyr:code-sample:`uart-native-tty` sample app provides a working example of the
driver.

This driver only supports poll mode and interrupt mode. Async mode is not
supported.
It has runtime configuration support, but no line control support.

.. _native_sim_backends:

Subsystems backends
*******************

Apart from its own peripherals, the native_sim board also has some dedicated
backends for some of Zephyr's subsystems. These backends are designed to ease
development by integrating more seamlessly with the host operating system:

.. _nsim_back_console:

**Console backend**:
  A console backend which by default is configured to
  redirect any :c:func:`printk` write to the native host application's
  ``stdout``.

  This driver is selected by default if no UART driver is compiled in.
  Otherwise :kconfig:option:`CONFIG_UART_CONSOLE` will be set to select the UART as
  console backend.

.. _nsim_back_logger:

**Logger backend**:
  A backend which prints all logger output to the process ``stdout``.
  It supports timestamping, which can be enabled with
  :kconfig:option:`CONFIG_LOG_BACKEND_FORMAT_TIMESTAMP`; and colored output which can
  be enabled with :kconfig:option:`CONFIG_LOG_BACKEND_SHOW_COLOR` and controlled
  with the command line options ``--color``, ``--no-color`` and
  ``--force-color``.

  In native_sim, by default, the logger is configured with
  :kconfig:option:`CONFIG_LOG_MODE_IMMEDIATE`.

  This backend can be selected with :kconfig:option:`CONFIG_LOG_BACKEND_NATIVE_POSIX`
  and is enabled by default.

.. _nsim_back_trace:

**Tracing**:
  A backend/"bottom" for Zephyr's CTF tracing subsystem which writes the tracing
  data to a file in the host filesystem.
  More information can be found in :ref:`Common Tracing Format <ctf>`

Emulators
*********

All :ref:`available HW emulators <emulators>` can be used with native_sim.

.. _native_fuse_flash:

Host (FUSE) filesystem access
*****************************

When building Zephyr with a filesystem, the device partitions can be exposed through the host file
system by enabling :kconfig:option:`CONFIG_FUSE_FS_ACCESS`. This option enables a FUSE
(File system in User space) layer that mounts the simulated embedded filesystem in the host
filesystem, maps the Zephyr file system calls to the required UNIX file system calls, and provides
access to its partitions with normal operating system commands such as ``cd``, ``ls`` and ``mkdir``.

By default the partitions are exposed through the directory :file:`flash/` in the
current working directory. This directory can be changed via the command line
option ``--flash-mount``.

On exit, the native_sim board application will take care of unmounting the
directory. In the unfortunate case that the native_sim board application
crashes, you can cleanup the stale mount point by using the program
``fusermount``:

.. code-block:: console

   $ fusermount -u flash

Note that this feature requires a 32-bit version of the FUSE library, with a
minimal version of 2.6, on the host system and ``pkg-config`` settings to
correctly pickup the FUSE install path and compiler flags.

On a Ubuntu 22.04 host system, for example, install the ``pkg-config`` and
``libfuse-dev:i386`` packages, and configure the pkg-config search path with
these commands:

.. code-block:: console

   $ sudo dpkg --add-architecture i386
   $ sudo apt update
   $ sudo apt-get install pkg-config libfuse-dev:i386
   $ export PKG_CONFIG_PATH=/usr/lib/i386-linux-gnu/pkgconfig

.. _native_sim_peripherals_c_compat:

Peripherals and backends C library compatibility
************************************************

Today, some native_sim peripherals and backends are, so far, only available when compiling with the
host libC (:kconfig:option:`CONFIG_EXTERNAL_LIBC`):

.. csv-table:: Drivers/backends vs libC choice
   :header: Driver class, driver name, driver kconfig, libC choices

     ADC, ADC emul, :kconfig:option:`CONFIG_ADC_EMUL`, All
     Bluetooth, :ref:`Userchan <nsim_bt_host_cont>`, :kconfig:option:`CONFIG_BT_USERCHAN`, Host and pico libC
     CAN, CAN native Linux, :kconfig:option:`CONFIG_CAN_NATIVE_LINUX`, All
     Console backend, :ref:`POSIX arch console <nsim_back_console>`, :kconfig:option:`CONFIG_POSIX_ARCH_CONSOLE`, All
     Display, :ref:`Display SDL <nsim_per_disp_sdl>`, :kconfig:option:`CONFIG_SDL_DISPLAY`, All
     Entropy, :ref:`Native simulator entropy <nsim_per_entr>`, :kconfig:option:`CONFIG_FAKE_ENTROPY_NATIVE_SIM`, All
     EEPROM, EEPROM simulator, :kconfig:option:`CONFIG_EEPROM_SIMULATOR`, All
     EEPROM, EEPROM emulator, :kconfig:option:`CONFIG_EEPROM_EMULATOR`, All
     Ethernet, :ref:`Eth native_tap <nsim_per_ethe>`, :kconfig:option:`CONFIG_ETH_NATIVE_TAP`, All
     Flash, :ref:`Flash simulator <nsim_per_flash_simu>`, :kconfig:option:`CONFIG_FLASH_SIMULATOR`, All
     FUSE, :ref:`Host based filesystem access <native_fuse_flash>`, :kconfig:option:`CONFIG_FUSE_FS_ACCESS`, All
     GPIO, GPIO emulator, :kconfig:option:`CONFIG_GPIO_EMUL`, All
     GPIO, SDL GPIO emulator, :kconfig:option:`CONFIG_GPIO_EMUL_SDL`, All
     I2C, I2C emulator, :kconfig:option:`CONFIG_I2C_EMUL`, All
     Input, Input SDL touch, :kconfig:option:`CONFIG_INPUT_SDL_TOUCH`, All
     Input, Linux evdev, :kconfig:option:`CONFIG_NATIVE_LINUX_EVDEV`, All
     Logger backend, :ref:`Native backend <nsim_back_logger>`, :kconfig:option:`CONFIG_LOG_BACKEND_NATIVE_POSIX`, All
     Offloaded sockets, :ref:`nsim_per_offloaded_sockets`, :kconfig:option:`CONFIG_NET_NATIVE_OFFLOADED_SOCKETS`, All
     RTC, RTC emul, :kconfig:option:`CONFIG_RTC_EMUL`, All
     Serial, :ref:`UART native PTY <native_ptty_uart>`, :kconfig:option:`CONFIG_UART_NATIVE_PTY`, All
     Serial, :ref:`UART native TTY <native_tty_uart>`, :kconfig:option:`CONFIG_UART_NATIVE_TTY`, All
     SPI, SPI emul, :kconfig:option:`CONFIG_SPI_EMUL`, All
     System tick, Native_sim timer, :kconfig:option:`CONFIG_NATIVE_SIM_TIMER`, All
     Tracing, :ref:`Posix tracing backend <nsim_back_trace>`, :kconfig:option:`CONFIG_TRACING_BACKEND_POSIX`, All
     USB, :ref:`USB native posix <nsim_per_usb>`, :kconfig:option:`CONFIG_USB_NATIVE_POSIX`, Host libC