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:

• 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

• 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

• 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
  • 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

• 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

• 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

• 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

• 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

• 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.

zephyr/doc/contribute/documentation/generation.rst

Lines 42 to 66 in af0336e

	.. graphviz::
	:caption: Schematic of the documentation build process
	digraph {
	rankdir=LR
	images [shape="rectangle" label=".png, .jpg\nimages"]
	rst [shape="rectangle" label="restructuredText\nfiles"]
	conf [shape="rectangle" label="conf.py\nconfiguration"]
	rtd [shape="rectangle" label="read-the-docs\ntheme"]
	header [shape="rectangle" label="c header\ncomments"]
	xml [shape="rectangle" label="XML"]
	html [shape="rectangle" label="HTML\nweb site"]
	sphinx[shape="ellipse" label="sphinx +\nbreathe,\ndocutils"]
	images -> sphinx
	rst -> sphinx
	conf -> sphinx
	header -> doxygen
	doxygen -> xml
	xml-> sphinx
	rtd -> sphinx
	sphinx -> html
	}

or

zephyr/doc/security/reporting.rst

Lines 24 to 51 in af0336e

	.. graphviz::
	digraph {
	node [style = rounded];
	init [shape = point];
	New [shape = box];
	Triage [shape = box];
	{
	rank = same;
	rankdir = LR;
	Assigned [shape = box];
	Rejected [shape = box];
	}
	Review [shape = box];
	Accepted [shape = box];
	Public [shape = box];
	init -> New;
	New -> Triage;
	Triage -> Rejected [dir = both];
	Triage -> Assigned;
	Assigned -> Review [dir = both];
	Review -> Accepted;
	Review -> Rejected;
	Accepted -> Public;
	}

[cfriedt]

@aescolar - there is also dma_emul and uart_emul