xipfs: compaction command, test suite and NXFLAT execute-in-place demo

examples/nxflatxip/.gitignore

@@ -0,0 +1,2 @@
+/symtab.c
+/xipmod_bin.h

examples/nxflatxip/CMakeLists.txt

@@ -0,0 +1,29 @@
+# ##############################################################################
+# apps/examples/nxflatxip/CMakeLists.txt
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+#
+# ##############################################################################
+
+# The module and the symbol table it needs are built by module/Makefile, which
+# the CMake build does not drive.  As with apps/examples/nxflat, use the make
+# build for this example.
+
+if(CONFIG_EXAMPLES_NXFLATXIP)
+  nuttx_add_application(NAME nxflatxip SRCS nxflatxip_main.c symtab.c)
+endif()

examples/nxflatxip/Kconfig

@@ -0,0 +1,38 @@
+#
+# For a description of the syntax of this configuration file,
+# see the file kconfig-language.txt in the NuttX tools repository.
+#
+
+config EXAMPLES_NXFLATXIP
+	tristate "NXFLAT execute-in-place from xipfs demo"
+	depends on FS_XIPFS && NXFLAT && LIBC_EXECFUNCS
+	default n
+	---help---
+		Write an NXFLAT module into xipfs at run time, the way a download
+		would, then run two instances of it concurrently.  The module's
+		text is executed directly out of flash and shared between the
+		instances, while each instance gets its own data.
+
+		Subcommands:
+
+		  bench   XIP read throughput before and after a flash write
+		  defrag  fragment the volume, compact it, with a block map
+
+		Building the module needs the mknxflat and ldnxflat host tools
+		from the NuttX toolchain, and the board's Make.defs must name
+		them, exactly as apps/examples/nxflat requires.
+
+if EXAMPLES_NXFLATXIP
+
+config EXAMPLES_NXFLATXIP_MOUNTPT
+	string "xipfs mountpoint"
+	default "/mnt/xipfs"
+
+config EXAMPLES_NXFLATXIP_MTD
+	string "MTD device backing the volume"
+	default "/dev/rpflash"
+	---help---
+		Used only by the defrag subcommand, which remounts the volume to
+		show that what it did survives.
+
+endif # EXAMPLES_NXFLATXIP

examples/nxflatxip/Make.defs

@@ -0,0 +1,25 @@
+############################################################################
+# apps/examples/nxflatxip/Make.defs
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+ifneq ($(CONFIG_EXAMPLES_NXFLATXIP),)
+CONFIGURED_APPS += $(APPDIR)/examples/nxflatxip
+endif

examples/nxflatxip/Makefile

@@ -0,0 +1,54 @@
+############################################################################
+# apps/examples/nxflatxip/Makefile
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+include $(APPDIR)/Make.defs
+
+# NXFLAT execute-in-place from xipfs
+
+CSRCS     = symtab.c
+MAINSRC   = nxflatxip_main.c
+
+# The generated symbol table declares every imported symbol as void *, which
+# the compiler objects to for the ones it knows as builtins.
+
+symtab.c_CFLAGS = -fno-builtin
+
+PROGNAME  = nxflatxip
+PRIORITY  = SCHED_PRIORITY_DEFAULT
+STACKSIZE = $(CONFIG_DEFAULT_TASK_STACKSIZE)
+MODULE    = $(CONFIG_EXAMPLES_NXFLATXIP)
+
+# Both are generated by the module build below
+
+symtab.c: build
+xipmod_bin.h: build
+
+$(MAINSRC): xipmod_bin.h
+
+.PHONY: build
+build:
+	+$(Q) $(MAKE) -C module TOPDIR="$(TOPDIR)" APPDIR="$(APPDIR)" CROSSDEV=$(CROSSDEV)
+
+clean::
+	+$(Q) $(MAKE) -C module TOPDIR="$(TOPDIR)" APPDIR="$(APPDIR)" CROSSDEV=$(CROSSDEV) clean
+
+include $(APPDIR)/Application.mk

examples/nxflatxip/module/.gitignore

@@ -0,0 +1,4 @@
+/xipmod
+/xipmod-thunk.S
+/*.r1
+/*.r2

examples/nxflatxip/module/Makefile

@@ -0,0 +1,94 @@
+############################################################################
+# apps/examples/nxflatxip/module/Makefile
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+############################################################################
+
+include $(APPDIR)/Make.defs
+
+# The NXFLAT module the demo downloads into xipfs.  Built exactly the way
+# apps/examples/nxflat builds its test programs, so it needs the same two
+# host tools from the NuttX toolchain: mknxflat and ldnxflat.
+
+BIN       = xipmod
+
+R1SRCS    = $(BIN).c
+R1OBJS    = $(R1SRCS:.c=.o)
+
+R2SRC     = $(BIN)-thunk.S
+R2OBJ     = $(R2SRC:.S=.o)
+
+EXAMPLDIR = $(APPDIR)$(DELIM)examples$(DELIM)nxflatxip
+BINHDR    = $(EXAMPLDIR)$(DELIM)$(BIN)_bin.h
+SYMTAB    = $(EXAMPLDIR)$(DELIM)symtab.c
+
+all: $(BINHDR) $(SYMTAB)
+.PHONY: all clean
+
+$(R1OBJS): %.o: %.c
+	@echo "CC: $<"
+	$(Q) $(CC) -c $(CPICFLAGS) $< -o $@
+
+$(R2OBJ): %.o: %.S
+	@echo "AS: $<"
+	$(Q) $(CC) -c $(CPICFLAGS) $< -o $@
+
+$(BIN).r1: $(R1OBJS)
+	@echo "LD: $<"
+	$(Q) $(LD) $(NXFLATLDFLAGS1) -o $@ $^
+
+$(R2SRC): $(BIN).r1
+	@echo "MK: $<"
+	$(Q) $(MKNXFLAT) -o $@ $^
+
+$(BIN).r2: $(R2OBJ)
+	@echo "LD: $<"
+	$(Q) $(LD) $(NXFLATLDFLAGS2) -o $@ $(R1OBJS) $(R2OBJ)
+
+$(BIN): $(BIN).r2
+	@echo "LD: $<"
+	$(Q) $(LDNXFLAT) $(LDNXFLATFLAGS) -o $@ $^
+
+# Embed the module in the demo.  It is not the demo's own text, it is a
+# payload the demo writes into the filesystem, so a plain byte array is what
+# is wanted.
+
+$(BINHDR): $(BIN)
+	@echo "GEN: $@"
+	$(Q) xxd -i -n g_xipmod $(BIN) | \
+		sed -e "s/^unsigned char/static const unsigned char/" \
+		    -e "s/^unsigned int/static const unsigned int/" >$@.tmp
+	$(Q) $(call TESTANDREPLACEFILE, $@.tmp, $@)
+
+# The symbols the module imports from the firmware.  mknxflat left the list
+# in the thunk file it generated, so that is what is scanned.
+
+$(SYMTAB): $(R2SRC)
+	@echo "GEN: $@"
+	$(Q) $(APPDIR)$(DELIM)tools$(DELIM)mksymtab.sh . g_nxflat >$@.tmp
+	$(Q) $(call TESTANDREPLACEFILE, $@.tmp, $@)
+
+clean:
+	$(call DELFILE, $(BIN))
+	$(call DELFILE, $(R2SRC))
+	$(call DELFILE, *.r1)
+	$(call DELFILE, *.r2)
+	$(call DELFILE, $(BINHDR))
+	$(call DELFILE, $(SYMTAB))
+	$(call CLEAN)

examples/nxflatxip/module/xipmod.c

@@ -0,0 +1,116 @@
+/****************************************************************************
+ * apps/examples/nxflatxip/module/xipmod.c
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * The module the demo downloads into xipfs and runs.
+ *
+ * Given a seed on the command line it fills an array derived from it,
+ * sleeps long enough for a second instance to do the same with a different
+ * seed, checks its own values are untouched, and hands the result to the
+ * firmware.  It reports the address of its own text, which is the point of
+ * the exercise: that address is inside the memory mapped flash window, it
+ * is the same in both instances, and the module is executing from it rather
+ * than from a copy in RAM.
+ *
+ * Two things this module deliberately does not have, both because of what
+ * the ldnxflat in circulation does with them:
+ *
+ *   - No global or static variables.  Those are reached through the GOT,
+ *     and the GOT entries come out pointing into the import table rather
+ *     than into .bss, so the module overwrites the addresses of the
+ *     functions it imports and jumps into nothing on its next call out.
+ *   - No string constants.  With this linker script .rodata lives in the
+ *     text segment and is reached PC-relatively, and the addend already
+ *     in the instruction is dropped when that relocation is resolved, so
+ *     the pointer lands somewhere in the middle of the code.
+ *
+ * Hence the reporting callback: the module passes numbers to the firmware
+ * and the firmware, which has a working printf and a format string, does
+ * the printing.  It also exercises the other direction of the interface --
+ * firmware code entered with the module's data base still in r10.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <stdlib.h>
+#include <unistd.h>
+
+/****************************************************************************
+ * Pre-processor Definitions
+ ****************************************************************************/
+
+#define NVALUES  64
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+/* Exported by the demo in the firmware and imported by this module */
+
+void xipmod_report(int seed, const void *text, const void *stack,
+                   long sum, int errors);
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+int main(int argc, char *argv[])
+{
+  int values[NVALUES];
+  int errors = 0;
+  int seed = 1;
+  long sum = 0;
+  int i;
+
+  if (argc > 1)
+    {
+      seed = atoi(argv[1]);
+    }
+
+  for (i = 0; i < NVALUES; i++)
+    {
+      values[i] = seed * (i + 1);
+    }
+
+  /* Long enough that the other instance has certainly filled its own copy
+   * by the time this one checks.
+   */
+
+  usleep(200000);
+
+  for (i = 0; i < NVALUES; i++)
+    {
+      if (values[i] != seed * (i + 1))
+        {
+          errors++;
+        }
+
+      sum += values[i];
+    }
+
+  xipmod_report(seed, (const void *)main, (const void *)values, sum, errors);
+
+  return errors == 0 ? EXIT_SUCCESS : EXIT_FAILURE;
+}