apps/NXDoom: Initial port of DOOM to NuttX

Documentation/applications/games/nxdoom/index.rst

@@ -0,0 +1,134 @@
+======
+NXDoom
+======
+
+This game is a port of the `Chocolate DOOM
+<https://github.com/chocolate-doom/chocolate-doom>`_ DOOM port to NuttX. The
+original Chocolate DOOM port is highly featured, and also adheres well to the
+vanilla DOOM experience. NXDoom is tailored instead for embedded devices and
+will likely have to forego some features or sacrifice some vanilla DOOM
+experience for better memory/CPU performance.
+
+NXDoom is maintained inside the NuttX source tree because it will diverge
+heavily from the original Chocolate DOOM port in order to target embedded
+devices. It is for this reason that we do not take the approach of downloading
+Chocolate DOOM and apply patches (there would be too many large patches to
+apply).
+
+.. figure:: doom-on-sim.png
+   :figwidth: 60%
+   :align: center
+   :alt: The shareware version of DOOM being played on the NuttX simulator
+
+   The shareware version of DOOM being played on the NuttX simulator
+
+.. warning::
+
+   Not all features are implemented for NXDoom. There is currently no support
+   for game sounds or music, nor does any of the networked logic for multiplayer
+   games work.
+
+   Some code was stripped during the initial port to simplify the port. If those
+   features are needed/desired later, they can be added back. This includes some
+   sound-library interfaces which are not available on NuttX, some input
+   options, etc.
+
+   It is recommended that if you are making any significant changes to the
+   source code, you try compiling with and without the sound/networking feature
+   flags enabled to catch any possible errors.
+
+.. todo::
+
+   This port is a massive work in progress. Any contributions are welcome. Since
+   memory is the primary constraint for many of the embedded devices running
+   NuttX, memory optimizations are particularly welcome.
+
+   Sound support, multiplayer support, support for any of the wide array of
+   input devices NuttX can provide are also highly welcomed.
+
+.. warning::
+
+   Currently, the only supported input device is keyboard input. However,
+   NuttX's keyboard codec is highly non-standard and therefore some things do
+   not work as intended. For instance, pressing CTRL to fire does nothing since
+   NuttX's codec has no concept of CTRL. The keyboard codec will need to be
+   amended before this works properly, but the port is upstreamed in the hopes
+   of encouraging those changes or getting more contributors to add different
+   input devices. The keyboard codec needs to be treated delicately since other
+   things in the kernel depend on it.
+
+Minimum requirements
+--------------------
+
+The minimum requirements for playing NXDoom are:
+
+* A device running NuttX
+* A device with graphics output controlled via a frame buffer driver (320x240
+  screen minimum resolution)
+* Some way of getting sufficient input for up/down/left/right/fire controls
+  (limited out-of-the-box input support is available)
+* A pretty good amount of memory (I haven't verified the total amount required
+  yet, but the original DOOM needed 4MB of RAM and NXDoom isn't much better
+  optimized)
+* Non-volatile memory sufficiently large for the WAD file you choose to play
+
+.. note::
+
+   The NXDoom port was tested using the shareware version of DOOM, whose WAD
+   file is commonly named DOOM1.wad. You may find this online on various sites.
+   Other WAD files are available online but are not guaranteed to work (i.e.,
+   the `OTTAWAU.wad
+   <https://www.doomworld.com/files/file/1651-ottawauwad-ver-09-pre-release/>`_
+   file I tried did not run properly)
+
+
+Playing
+-------
+
+To launch the game, just run:
+
+.. code:: console
+
+   nsh> nxdoom -iwad /path/to/my/iwadfile.wad
+
+and replace the path with your WAD file's path.
+
+Other Notes
+-----------
+
+Translations
+^^^^^^^^^^^^
+
+The game does support different translations via headers with game strings. One
+such example is ``src/doom/d_french``, which was my half-attempt at translating
+the game strings to French (I stopped halfway). The main problem with
+translations is that the game seems unable to render non-ASCII text (i.e. any
+French words with accents have missing letters where the accents were). A way
+around this would be great, and other translations are welcome.
+
+Source Comments
+^^^^^^^^^^^^^^^
+
+I made an effort to preserve all the original comments from the Chocolate DOOM
+source, which in turn seems to have made an effort to preserve the original DOOM
+code comments. Some are quite vulgar.
+
+Optimizations
+^^^^^^^^^^^^^
+
+DOOM uses 32-bit wide, signed fixed-point numbers for calculations. This should
+be entirely compatible with the NuttX fixed-point library. However, in my
+attempt to switch to the NuttX-native library, the textures began to render
+strangely and I experienced periodic crashes. This would be one good
+optimization.
+
+Another useful optimization would be to eliminate the lookup tables used for
+sine, cosine and tangent. These make the game logic fast, but they also take up
+the most amount of memory in the binary. Removing them could save several
+hundred KB. CPUs have come a long way since DOOM was written and the compute hit
+might be worth it for the memory reduction on embedded.
+
+Another good optimization would be to examine the use of 32-bit natural ``int``
+variables and decided if smaller sizes could be used. I imagine this was
+originally done for the native word-size optimizations on the computers of the
+era, but it results in extra memory use on large internal arrays especially.

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

@@ -946,6 +946,17 @@ Of course, this configuration can only be used in environments that support X11!
       -CONFIG_EXAMPLES_NXTERM=n
       +CONFIG_EXAMPLES_NXTERM=y
 
+nxdoom
+------
+
+Play :doc:`NXDoom </applications/games/nxdoom/index>` on the Simulator using X11
+keyboard input and graphics. Read the docs for NXDoom to see how to play.
+
+.. warning::
+
+   X11 keyboard codes are not perfectly translated to the NuttX codec currently,
+   so some controls will not work properly.
+
 nxffs
 -----
 

boards/sim/sim/sim/configs/nxdoom/defconfig

@@ -0,0 +1,85 @@
+#
+# 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_NSH_CMDOPT_HEXDUMP is not set
+CONFIG_ALLOW_GPL_COMPONENTS=y
+CONFIG_ARCH="sim"
+CONFIG_ARCH_BOARD="sim"
+CONFIG_ARCH_BOARD_SIM=y
+CONFIG_ARCH_CHIP="sim"
+CONFIG_ARCH_SIM=y
+CONFIG_BOARDCTL_APP_SYMTAB=y
+CONFIG_BOARDCTL_POWEROFF=y
+CONFIG_BOARD_LOOPSPERMSEC=0
+CONFIG_BOOT_RUNFROMEXTSRAM=y
+CONFIG_BUILTIN=y
+CONFIG_COVERAGE_ALL=y
+CONFIG_COVERAGE_TOOLCHAIN=y
+CONFIG_CRYPTO=y
+CONFIG_DEBUG_ASSERTIONS=y
+CONFIG_DEBUG_ASSERTIONS_EXPRESSION=y
+CONFIG_DEBUG_FEATURES=y
+CONFIG_DEBUG_SYMBOLS=y
+CONFIG_DEV_GPIO=y
+CONFIG_DEV_LOOP=y
+CONFIG_DRIVERS_VIDEO=y
+CONFIG_ETC_FATDEVNO=2
+CONFIG_ETC_ROMFS=y
+CONFIG_ETC_ROMFSDEVNO=1
+CONFIG_FAT_LCNAMES=y
+CONFIG_FAT_LFN=y
+CONFIG_FS_BINFS=y
+CONFIG_FS_FAT=y
+CONFIG_FS_HOSTFS=y
+CONFIG_FS_PROCFS=y
+CONFIG_FS_RAMMAP=y
+CONFIG_FS_ROMFS=y
+CONFIG_GAMES_NXDOOM=y
+CONFIG_GAMES_NXDOOM_ENDOOM=y
+CONFIG_GAMES_NXDOOM_KBDPATH="/dev/kbd"
+CONFIG_GPIO_LOWER_HALF=y
+CONFIG_HAVE_CXXINITIALIZE=y
+CONFIG_IDLETHREAD_STACKSIZE=4096
+CONFIG_INIT_ENTRYPOINT="nsh_main"
+CONFIG_INPUT=y
+CONFIG_IOEXPANDER=y
+CONFIG_IOEXPANDER_DUMMY=y
+CONFIG_LIBC_ENVPATH=y
+CONFIG_LIBC_EXECFUNCS=y
+CONFIG_LIBC_LOCALE=y
+CONFIG_LIBC_LOCALE_CATALOG=y
+CONFIG_LIBC_LOCALE_GETTEXT=y
+CONFIG_LIBC_MAX_EXITFUNS=1
+CONFIG_LIBC_NUMBERED_ARGS=y
+CONFIG_NDEBUG=y
+CONFIG_NSH_BUILTIN_APPS=y
+CONFIG_NSH_FILE_APPS=y
+CONFIG_NSH_READLINE=y
+CONFIG_PATH_INITIAL="/bin"
+CONFIG_PIPES=y
+CONFIG_PSEUDOFS_ATTRIBUTES=y
+CONFIG_PSEUDOFS_FILE=y
+CONFIG_PSEUDOFS_SOFTLINKS=y
+CONFIG_READLINE_TABCOMPLETION=y
+CONFIG_SCHED_BACKTRACE=y
+CONFIG_SCHED_EVENTS=y
+CONFIG_SCHED_HAVE_PARENT=y
+CONFIG_SCHED_WAITPID=y
+CONFIG_SIM_FBHEIGHT=1200
+CONFIG_SIM_FBWIDTH=1920
+CONFIG_SIM_FRAMEBUFFER_COUNT=1
+CONFIG_SIM_HOSTFS=y
+CONFIG_SIM_KEYBOARD=y
+CONFIG_SIM_TOUCHSCREEN=y
+CONFIG_SIM_WALLTIME_SIGNAL=y
+CONFIG_SIM_X11FB=y
+CONFIG_START_MONTH=6
+CONFIG_START_YEAR=2008
+CONFIG_SYSTEM_DUMPSTACK=y
+CONFIG_SYSTEM_GCOV=y
+CONFIG_SYSTEM_NSH=y
+CONFIG_VIDEO_FB=y