Emulators & simulators documentation issues

[aescolar]

This is a list of Zephyr device emulators and simulators, as well as native_sim specific drivers which lack documentation, or whose documentation is in a bad state, and other related documentation issues:

• [x] ADC emulator:

  • Has 1 small paragraph in https://docs.zephyrproject.org/latest/hardware/emulator/index.html, a longer description on its own section would be nice.
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_ADC_EMUL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/adc/zephyr,adc-emul.html

• [ ] CAN loopback driver

  • No docs beyond source, no mentions in docs.
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_CAN_LOOPBACK
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/can/zephyr,can-loopback.html

• [ ] CAN native Linux driver (connect to linux host CAN driver)

  • Just a small paragraph in https://docs.zephyrproject.org/latest/boards/posix/native_sim/doc/index.html#peripherals .
  • A longer description like for the BT controller, maybe with a dedicated page for it would be good.
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_CAN_NATIVE_LINUX
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/can/zephyr,native-linux-can.html

• [ ] DMA emulator

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html, a longer description would be nice.
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_DMA_EMUL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/dma/zephyr,dma-emul.html

• [x] EEPROM emulator: (EPROM emulator on a flash partition):

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html, longer description would be nice.
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_EEPROM_EMULATOR
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/mtd/zephyr,emu-eeprom.html

• [x] EEPROM simulator: (EPROM emulated on RAM, or (for native_sim also on a file in the host)):

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html
  • [x] Would be nice to mention it in the native_sim page
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_EEPROM_SIMULATOR
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/mtd/zephyr,sim-eeprom.html

• [ ] eSPI emulator

  • Now just a quick mention in https://docs.zephyrproject.org/latest/hardware/emulator/bus_emulators.html
  • Would be good to at least mention it in https://docs.zephyrproject.org/latest/hardware/emulator/index.html
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_ESPI_EMUL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/espi/zephyr,espi-emul-controller.html

• [x] Flash simulator: (FLASH emulated on RAM, or, for native_sim, on a file in the host):

  • docs:
  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html , a longer description on its own section would be nice.
  • And also mentioned in the context of the native_simulator ~(this ignores that we can use it in any other platform, we should fix that)~
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_FLASH_SIMULATOR
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/flash_controller/zephyr,sim-flash.html)

• [ ] GPIO emulator:

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html, a longer description would be nice
  • References:
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/gpio/zephyr,gpio-emul.html
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_GPIO_EMUL

• [ ] GPIO SDL emulator:

  • No docs
  • At least a section in https://docs.zephyrproject.org/latest/boards/posix/native_sim/doc/index.html#peripherals would be good.
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_GPIO_EMUL_SDL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/gpio/zephyr,gpio-emul-sdl.html

• [x] I2C emulator:

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html and https://docs.zephyrproject.org/latest/hardware/emulator/bus_emulators.html . Maybe enough?
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_I2C_EMUL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/i2c/zephyr,i2c-emul-controller.html#std-dtcompatible-

• [ ] Input SDL touch:

  • Just a small paragraph in https://docs.zephyrproject.org/latest/boards/posix/native_sim/doc/index.html#peripherals
  • A longer description would be good.
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_INPUT_SDL_TOUCH
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/input/zephyr,input-sdl-touch.html

• [x] RTC emulator: Emulates an RTC with a timed workq item

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html ,
  • Got its own section in https://docs.zephyrproject.org/latest/hardware/peripherals/rtc.html#rtc-emulated-device
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_RTC_EMUL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/rtc/zephyr,rtc-emul.html

• [x] SPI emulator:

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html, and https://docs.zephyrproject.org/latest/hardware/emulator/bus_emulators.html maybe enough?
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_SPI_EMUL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/spi/zephyr,spi-emul-controller.html

• [ ] UART emulator:

  • Mentioned in https://docs.zephyrproject.org/latest/hardware/emulator/index.html, a longer description would be nice
  • References:
  • https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_UART_EMUL
  • https://docs.zephyrproject.org/latest/build/dts/api/bindings/serial/zephyr,uart-emul.html

• [x] Emulators general docs:

  • ~The docs seem to refer mostly to bus emulators (I2C/SPI/GPIO) that would then have peripheral emulators, with focus on real peripheral HW emulators, and testing of their drivers~
  • ~But the EPROM emulator (not of this type) and the CAN lopback driver are also mentioned.~
  • ~=> Probably this doc title and the content should be changed so it is clear it refers only to this type of bus emulators and its emulated peripherals.~
  • ~This doc use .pngs with "native_posix" in them => The png should be converted to svg (they seem to be generated drawio), and the text corrected.~

Maintainers: Feel free to correct and add to this list

CC: @kartben @henrikbrixandersen @bjarki-trackunit @Laczen @alexanderwachter @cfriedt @ceolin @jeremybettis @pdgendt @sjg20 @teburd @aaronemassey @fabiobaltieri @fgrandel

Note: Updated 2024/01/05 after #66912 got merged. Note: Updated 2024/01/09 after #67274 got merged.

[kartben]

Note re: PNG diagrams. Recreating them in SVG would certainly be great, it might be even better to have them directly in in-lined Graphviz, assuming getting a similar layout is not overly complicated. See e.g. https://github.com/zephyrproject-rtos/zephyr/blob/af0336ed19228e1350fcc7fe7de4321ffd0ac830/doc/contribute/documentation/generation.rst#L42-L66 or https://github.com/zephyrproject-rtos/zephyr/blob/af0336ed19228e1350fcc7fe7de4321ffd0ac830/doc/security/reporting.rst#L24-L51

[cfriedt]

@aescolar - there is also dma_emul and uart_emul

[aescolar]

CC @alevkoy @niedzwiecki-dawid