Merge c2a44dd8a4 into e73f7f7d0e

Documentation/applications/graphics/microwindows/index.rst

@@ -0,0 +1,222 @@
+.. _applications_graphics_microwindows:
+
+Microwindows
+============
+
+Microwindows is a lightweight windowing system for small- to medium-footprint
+embedded systems.  It provides:
+
+- **GDI / Win32 API** -- a low-level C graphics library for direct framebuffer
+  drawing, suitable for tiny single-threaded applications.
+- **mwin** -- a widget toolkit built on the Win32 API, supporting windows,
+  menus, buttons, edit boxes, list boxes, scroll bars, progress bars, and
+  timers.
+- **Nano-X / X11 API** -- an X11-compatible client/server window system (not
+  yet enabled for NuttX; work in progress).
+
+Currently the NuttX integration only enables the GDI / Win32 API and the
+mwin widget toolkit.  The Nano-X server and X11 client libraries are part of
+the upstream project but are not yet wired into the NuttX build.
+
+Quick Start
+===========
+
+Microwindows requires a framebuffer device (``CONFIG_VIDEO_FB=y``).
+
+QEMU x86-64
+-----------
+
+The ``qemu-intel64:mw`` configuration uses the Multiboot2 framebuffer,
+a USB HID keyboard (raw byte stream), and a USB HID mouse::
+
+   cd nuttx
+   tools/configure.sh qemu-intel64:mw
+   make -j$(nproc)
+
+The build produces a flat ``nuttx.elf`` image.  To run it on QEMU you need a
+bootable ISO with GRUB2.  See :doc:`/platforms/x86_64/intel64/index` for the
+step-by-step procedure.  In short:
+
+#. Create the ISO directory structure::
+
+      mkdir -p iso/boot/grub
+
+#. Write ``grub.cfg``::
+
+      echo 'set timeout=0'          > iso/boot/grub/grub.cfg
+      echo 'set default=0'         >> iso/boot/grub/grub.cfg
+      echo 'menuentry "kernel" {'  >> iso/boot/grub/grub.cfg
+      echo '  multiboot2 /boot/nuttx.elf' >> iso/boot/grub/grub.cfg
+      echo '}'                     >> iso/boot/grub/grub.cfg
+
+#. Copy ``nuttx.elf`` and create the ISO::
+
+      cp nuttx.elf iso/boot/
+      grub-mkrescue -o boot.iso iso
+
+#. Run QEMU (omit ``-nographic`` so the framebuffer window opens)::
+
+      qemu-system-x86_64 -cpu host -enable-kvm -m 2G -cdrom boot.iso
+
+The pre-built config sets ``CONFIG_INIT_ENTRYPOINT="mwdemo_main"`` so the
+demo starts immediately.
+
+Simulator
+---------
+
+The ``sim:mw`` configuration uses the virtual keyboard, touchscreen, and
+X11-based framebuffer::
+
+   cd nuttx
+   tools/configure.sh sim:mw
+   make -j$(nproc)
+
+This builds a host-native ``./nuttx`` binary that opens an X11 window.
+Keyboard input goes to the window that has focus; touch events are generated
+by mouse clicks within the window.
+
+See also the respective board documentation for configuration details:
+
+* :doc:`/platforms/sim/sim/boards/sim/index` — ``sim:mw`` configuration
+* :doc:`/platforms/x86_64/intel64/boards/qemu-intel64/index` — ``qemu-intel64:mw`` configuration
+
+Available Configurations
+========================
+
+To enable Microwindows, set ``CONFIG_GRAPHICS_MICROWINDOWS=y``.
+The library is located at ``apps/graphics/microwindows``.
+
+Dependencies
+------------
+
+All configurations require ``CONFIG_VIDEO_FB=y``.
+
+For **qemu-intel64:mw** the following input-related options are required:
+
+  ``CONFIG_USBHOST=y``, ``CONFIG_USBHOST_HIDKBD=y``, ``CONFIG_USBHOST_HIDMOUSE=y``,
+  ``CONFIG_USBHOST_XHCI_PCI=y``, ``CONFIG_USBHOST_WAITER=y``,
+  ``CONFIG_LIBC_KBDCODEC=y``, ``CONFIG_HIDKBD_ENCODED=y``
+
+For **sim:mw** the following input options are required:
+
+  ``CONFIG_INPUT=y``, ``CONFIG_SIM_KEYBOARD=y``, ``CONFIG_SIM_TOUCHSCREEN=y``
+
+Keyboard Drivers
+----------------
+
+``choice`` prompt: ``"Keyboard driver"``
+
+``MICROWINDOWS_KBD_EVENT``
+    Reads ``keyboard_event_s`` events from ``/dev/kbd`` (path configurable).
+    Supports key press/release tracking and modifier keys (Shift, Ctrl, Alt).
+
+    Device path config: ``MICROWINDOWS_KBD_EVENT_PATH`` (default ``/dev/kbd``).
+
+``MICROWINDOWS_KBD_RAW``
+    Reads raw byte stream from ``/dev/kbda`` (path configurable).  Decodes
+    escape sequences via the ``kbd_codec`` library.  Requires
+    ``LIBC_KBDCODEC=y``.  Suitable for USB HID keyboards.
+
+    Device path config: ``MICROWINDOWS_KBD_RAW_PATH`` (default ``/dev/kbda``).
+
+``MICROWINDOWS_KBD_NONE``
+    No keyboard driver is compiled.  Microwindows uses a null driver that
+    never produces input.  Suitable for display-only applications.
+
+``MICROWINDOWS_KBD_CUSTOM``
+    No built-in keyboard driver is compiled.  The application or BSP must
+    provide its own ``kbddev`` symbol and ``KBDDEVICE`` implementation, and
+    add the source file to the build (e.g. via ``CSRCS`` in its Makefile).
+
+Mouse / Touchscreen Drivers
+---------------------------
+
+``choice`` prompt: ``"Mouse/touchscreen driver"``
+
+``MICROWINDOWS_MOUSE_RELATIVE``
+    Reads ``mouse_report_s`` events from ``/dev/mouse0`` (path configurable).
+    Supports three buttons and scroll wheel.
+
+    Device path config: ``MICROWINDOWS_MOUSE_PATH`` (default ``/dev/mouse0``).
+
+``MICROWINDOWS_MOUSE_TS``
+    Reads ``touch_sample_s`` events from ``/dev/input0`` (path configurable).
+    Supports absolute positioning.
+
+    Device path config: ``MICROWINDOWS_TS_PATH`` (default ``/dev/input0``).
+
+``MICROWINDOWS_MOUSE_NONE``
+    No pointing device driver is compiled.  Microwindows uses a null driver
+    that hides the cursor and produces no input.
+
+``MICROWINDOWS_MOUSE_CUSTOM``
+    No built-in pointing device driver is compiled.  The application or BSP
+    must provide its own ``mousedev`` symbol and ``MOUSEDEVICE``
+    implementation, and add the source file to the build.
+
+Framebuffer
+-----------
+
+``MICROWINDOWS_FB_PATH``
+    Path to the NuttX framebuffer device.  Default ``/dev/fb0``.
+
+Microwindows Demo Application
+=============================
+
+Enable with ``CONFIG_EXAMPLES_MICROWINDOWS=y``.  The example is located at
+``apps/examples/microwindows``.
+
+It ports ``mwdemo.c`` from upstream, which exercises the mwin widget toolkit
+(buttons, edit boxes, list boxes, scroll bars, progress bars).  The demo uses
+``GdOpenScreen()`` to initialise the framebuffer and enters a Win32-style
+message loop with ``GetMessage()`` / ``DispatchMessage()``.
+
+.. figure:: mwdemo-sim.png
+   :align: center
+   :alt: The Microwindows mwdemo running on the NuttX simulator.
+
+   The mwdemo application running on the NuttX simulator (``sim:mw``).
+
+``EXAMPLES_MICROWINDOWS_PROGNAME``
+    Program name for the NSH ELF install (default ``"mwexample"``).
+``EXAMPLES_MICROWINDOWS_PRIORITY``
+    Task priority (default ``100``).  For setups where input threads
+    have a lower priority, consider lowering this value.
+
+    .. warning::
+
+       On ``qemu-intel64:mw`` the default USB HID mouse thread priority
+       (``CONFIG_HIDMOUSE_DEFPRIO``, default 50) is lower than the demo
+       application priority (100).  When dragging a window, Microwindows'
+       ``MwSelect`` switches to polling (``select`` with timeout 0), which can
+       starve the USB input thread and make the whole system appear frozen.
+       Raise ``CONFIG_HIDMOUSE_DEFPRIO`` (e.g. to 120), lower
+       ``EXAMPLES_MICROWINDOWS_PRIORITY``, or fix the drag loop to use a small
+       non-zero timeout.
+
+``EXAMPLES_MICROWINDOWS_STACKSIZE``
+    Stack size in bytes (default ``32768``).
+
+Porting to New Hardware
+=======================
+
+The Microwindows source is downloaded at build time from the upstream
+repository.  NuttX-specific screen, keyboard, and mouse drivers live
+in upstream ``src/drivers/`` (``scr_nuttx.c``, ``kbd_nuttx_event.c``,
+``kbd_nuttx_raw.c``, ``mou_nuttx_mouse.c``, ``mou_nuttx_ts.c``).
+
+A board with a working framebuffer and input devices needs:
+
+#. A ``defconfig`` enabling ``CONFIG_VIDEO_FB``, ``GRAPHICS_MICROWINDOWS``,
+   and the appropriate keyboard/mouse driver choice.
+#. For framebuffer-only (display-only) use, select ``KBD_NONE`` and
+   ``MOUSE_NONE``.
+
+If the board's input hardware does not fit the built-in drivers, select
+``KBD_CUSTOM`` and/or ``MOUSE_CUSTOM`` and provide your own driver source.
+
+Resources
+=========
+
+- `Microwindows upstream repository <https://github.com/ghaerr/microwindows>`_
+- `NuttX Discussion Issue #18566 <https://github.com/apache/nuttx/issues/18566>`_

Documentation/platforms/sim/sim/boards/sim/index.rst

@@ -802,6 +802,13 @@ mtdrwb
 This is the ``apps/examples/mtdrwb`` test using a MTD RAM driver to simulate the
 FLASH part.
 
+mw
+--
+
+Microwindows demo configuration using virtual keyboard (event mode),
+touchscreen, and framebuffer.  See
+:doc:`/applications/graphics/microwindows/index` for details.
+
 nettest
 -------
 

Documentation/platforms/x86_64/intel64/boards/qemu-intel64/index.rst

@@ -228,3 +228,9 @@ fb
 ---
 
 Configuration that enables NuttX framebuffer examples.
+
+mw
+--
+
+Microwindows demo configuration using framebuffer, USB HID keyboard (raw byte stream), and USB HID mouse.  See
+:doc:`/applications/graphics/microwindows/index` for details.

boards/sim/sim/sim/configs/mw/defconfig

@@ -0,0 +1,35 @@
+#
+# This file is autogenerated: PLEASE DO NOT EDIT IT.
+#
+# You can use "make menuconfig" to make any modifications to the installed .config file.
+# You can then do "make savedefconfig" to generate a new defconfig file that includes your
+# modifications.
+#
+CONFIG_ARCH="sim"
+CONFIG_ARCH_BOARD="sim"
+CONFIG_ARCH_BOARD_SIM=y
+CONFIG_ARCH_CHIP="sim"
+CONFIG_ARCH_SIM=y
+CONFIG_DEBUG_SYMBOLS=y
+CONFIG_DRIVERS_VIDEO=y
+CONFIG_EXAMPLES_MICROWINDOWS=y
+CONFIG_FRAME_POINTER=y
+CONFIG_INPUT=y
+CONFIG_SIM_KEYBOARD=y
+CONFIG_SIM_TOUCHSCREEN=y
+CONFIG_EXAMPLES_MICROWINDOWS_PROGNAME="mwdemo"
+CONFIG_GRAPHICS_MICROWINDOWS=y
+CONFIG_MICROWINDOWS_KBD_EVENT=y
+CONFIG_MICROWINDOWS_MOUSE_TS=y
+CONFIG_MICROWINDOWS_MWIN=y
+CONFIG_IDLETHREAD_STACKSIZE=4096
+CONFIG_INIT_ENTRYPOINT="mwdemo_main"
+CONFIG_INIT_STACKSIZE=32768
+CONFIG_SIM_WALLTIME_SIGNAL=y
+CONFIG_SIM_FBHEIGHT=768
+CONFIG_SIM_FBWIDTH=1024
+CONFIG_SIM_X11FB=y
+CONFIG_START_DAY=12
+CONFIG_START_MONTH=6
+CONFIG_START_YEAR=2026
+CONFIG_VIDEO_FB=y

boards/x86_64/qemu/qemu-intel64/configs/mw/defconfig

@@ -0,0 +1,65 @@
+#
+# This file is autogenerated: PLEASE DO NOT EDIT IT.
+#
+# You can use "make menuconfig" to make any modifications to the installed .config file.
+# You can then do "make savedefconfig" to generate a new defconfig file that includes your
+# modifications.
+#
+# CONFIG_ARCH_PVHBOOT is not set
+CONFIG_16550_ADDRWIDTH=16
+CONFIG_16550_UART0=y
+CONFIG_16550_UART0_BASE=0x3f8
+CONFIG_16550_UART0_CLOCK=1843200
+CONFIG_16550_UART0_IRQ=36
+CONFIG_16550_UART0_RXBUFSIZE=16
+CONFIG_16550_UART0_SERIAL_CONSOLE=y
+CONFIG_16550_UART0_TXBUFSIZE=16
+CONFIG_16550_UART=y
+CONFIG_ARCH="x86_64"
+CONFIG_ARCH_BOARD="qemu-intel64"
+CONFIG_ARCH_BOARD_INTEL64_QEMU=y
+CONFIG_ARCH_CHIP="qemu"
+CONFIG_ARCH_CHIP_INTEL64_QEMU=y
+CONFIG_ARCH_INTEL64_CORE_FREQ_KHZ=2600000
+CONFIG_ARCH_SIZET_LONG=y
+CONFIG_ARCH_X86_64=y
+CONFIG_BOOT_RUNFROMEXTSRAM=y
+CONFIG_DEFAULT_TASK_STACKSIZE=65536
+CONFIG_DRIVERS_VIDEO=y
+CONFIG_EXAMPLES_MICROWINDOWS=y
+CONFIG_EXAMPLES_MICROWINDOWS_PROGNAME="mwdemo"
+CONFIG_GRAPHICS_MICROWINDOWS=y
+CONFIG_MICROWINDOWS_KBD_RAW=y
+CONFIG_MICROWINDOWS_MOUSE_RELATIVE=y
+CONFIG_MICROWINDOWS_MWIN=y
+CONFIG_IDLETHREAD_STACKSIZE=4096
+CONFIG_INIT_ENTRYPOINT="mwdemo_main"
+CONFIG_MULTBOOT2_FB=y
+CONFIG_PCI=y
+CONFIG_PTHREAD_STACK_MIN=4096
+CONFIG_RAM_SIZE=268435456
+CONFIG_SCHED_HPWORK=y
+CONFIG_SCHED_LPWORK=y
+CONFIG_SCHED_TICKLESS=y
+CONFIG_START_DAY=12
+CONFIG_START_MONTH=6
+CONFIG_START_YEAR=2026
+CONFIG_USBHOST=y
+CONFIG_USBHOST_HIDKBD=y
+CONFIG_USBHOST_HIDMOUSE=y
+CONFIG_USBHOST_WAITER=y
+CONFIG_USBHOST_XHCI_PCI=y
+CONFIG_USEC_PER_TICK=1
+CONFIG_VIDEO_FB=y
+CONFIG_PCI_MSIX=y
+CONFIG_HIDKBD_STACKSIZE=10240
+CONFIG_HIDMOUSE_STACKSIZE=10240
+CONFIG_HIDMOUSE_XMAX=1024
+CONFIG_HIDMOUSE_YMAX=768
+CONFIG_DEV_SIMPLE_ADDRENV=y
+CONFIG_LIBM=y
+CONFIG_DEBUG_SYMBOLS=y
+CONFIG_INIT_PRIORITY=20
+CONFIG_LIBC_KBDCODEC=y
+CONFIG_HIDKBD_ENCODED=y
+# CONFIG_ARCH_INTEL64_HAVE_PCID is not set