.. _native_sim:

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

Overview
********

The native_sim board is an evolution of :ref:`native_posix<native_posix>`.
Just like with :ref:`native_posix<native_posix>` you can build your Zephyr application
with the Zephyr kernel, creating a normal Linux executable with your host tooling,
and can debug and instrument it like any other Linux program.

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

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

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

.. _nativesim_important_limitations:

Important limitations
*********************

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

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

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:

Now you have a Linux executable, ``./build/zephyr/zephyr.exe``, you can use just like any
other Linux program.

You can run, debug, build it with sanitizers or with coverage just like with
:ref:`native_posix <native_posix>`.
Please check :ref:`native_posix's how to<native_posix_how_to_use>` for more info.

32 and 64bit versions
*********************

Just like native_posix, 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_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.

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

Unlike native_posix, 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`.

When building with either :ref:`MINIMAL<c_library_minimal>` or :ref:`PICO<c_library_picolibc>` libC
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>`.

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

:ref:`native_posix's architecture description<native_posix_architecture>` as well as the
:ref:`POSIX architecture description<posix_arch_architecture>` are directly
applicable to native_sim.

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

.. _native_sim_peripherals:

Peripherals, subsystems backends and host based flash access
************************************************************

Today, native_sim supports the exact same
:ref:`peripherals and backends as native_posix<native_posix_peripherals>`,
with the only caveat that some of these 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, userchan, :kconfig:option:`CONFIG_BT_USERCHAN`, host libC
     can, can native posix, :kconfig:option:`CONFIG_CAN_NATIVE_POSIX_LINUX`, host libC
     console backend, POSIX arch console, :kconfig:option:`CONFIG_POSIX_ARCH_CONSOLE`, all
     display, display SDL, :kconfig:option:`CONFIG_SDL_DISPLAY`, all
     entropy, native posix entropy, :kconfig:option:`CONFIG_FAKE_ENTROPY_NATIVE_POSIX`, all
     eprom, eprom emulator, :kconfig:option:`CONFIG_EEPROM_EMULATOR`, host libC
     ethernet, eth native_posix, :kconfig:option:`CONFIG_ETH_NATIVE_POSIX`, host libC
     flash, flash simulator, :kconfig:option:`CONFIG_FLASH_SIMULATOR`, all
     flash, host based flash access, :kconfig:option:`CONFIG_FUSE_FS_ACCESS`, host libC
     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
     log backend, native backend, :kconfig:option:`CONFIG_LOG_BACKEND_NATIVE_POSIX`, all
     rtc, RTC emul, :kconfig:option:`CONFIG_RTC_EMUL`, all
     serial, uart native posix/PTTY, :kconfig:option:`CONFIG_UART_NATIVE_POSIX`, all
     serial, uart native TTY, :kconfig:option:`CONFIG_UART_NATIVE_TTY`, all
     spi, SPI emul, :kconfig:option:`CONFIG_SPI_EMUL`, all
     system tick, native_posix timer, :kconfig:option:`CONFIG_NATIVE_POSIX_TIMER`, all
     tracing, Posix tracing backend, :kconfig:option:`CONFIG_TRACING_BACKEND_POSIX`, all
     usb, USB native posix, :kconfig:option:`CONFIG_USB_NATIVE_POSIX`, host libC