Improve Host make run behaviour (#1736)

* Launch telnet sessions automatically as required for `run` target

* Don't run emulator for `flash` target, and remove `telnet` target

* Update `execute` target for `HostTests`

* When running `make gdb` for host, enable required uart servers and pause

* Add `HOST_UART_OPTIONS`, `HOST_NETWORK_OPTIONS` and `HOST_FLASH_OPTIONS` so emulator settings can be specified separately for each Component.

* Update Host readme.md with changes to option passing and default UART behaviour

* Make `SMING_TARGET_OPTIONS` an internal variable, and revise so Components add their own settings to it.

* Rename `SMING_TARGET_OPTIONS` -> `CLI_TARGET_OPTIONS`

Sming/Arch/Host/Components/driver/component.mk

@@ -3,16 +3,20 @@ COMPONENT_INCDIRS	+= $(ESP8266_COMPONENTS)/driver $(ESP8266_COMPONENTS)/driver/i
 
 ##@Tools
 
-DEBUG_VARS	?= UARTID
-UARTID		?= 0
+# Starting IP port number for uart servers
+CACHE_VARS			+= HOST_UART_PORTBASE
+HOST_UART_PORTBASE	?= 10000
 
-TELNET_CMDLINE	= telnet localhost $$((10000 + $(UARTID)))
+# List of UART IDs to run servers for
+CACHE_VARS			+= ENABLE_HOST_UARTID
+ENABLE_HOST_UARTID	?=
 
-.PHONY: telnet
-telnet: ##Run telnet to connect to a virtual serial port, specified by UARTID
-ifeq ($(UNAME),Windows)
-	start $(TELNET_CMDLINE)
-else
-	$(TELNET_CMDLINE) &
-endif
+# Options to add when running emulator
+CACHE_VARS			+= HOST_UART_OPTIONS
+HOST_UART_OPTIONS	?= $(addprefix --uart=,$(ENABLE_HOST_UARTID))
+CLI_TARGET_OPTIONS += $(HOST_UART_OPTIONS)
 
+# $1 -> Uart ID
+define RunHostTerminal
+$(call DetachCommand,telnet localhost $$(($(HOST_UART_PORTBASE) + $1)))
+endef

Sming/Arch/Host/Components/esp_wifi/component.mk

@@ -1,3 +1,8 @@
+# Options to add for configuring host network behaviour
+CACHE_VARS				+= HOST_NETWORK_OPTIONS
+HOST_NETWORK_OPTIONS	?=
+CLI_TARGET_OPTIONS	+= $(HOST_NETWORK_OPTIONS)
+
 COMPONENT_VARS		:= ENABLE_WPS
 ifeq ($(ENABLE_WPS),1)
    GLOBAL_CFLAGS	+= -DENABLE_WPS=1

Sming/Arch/Host/Components/gdbstub/component.mk

@@ -1,3 +1,3 @@
 # Full GDB command line
 GDBSTUB_DIR := $(COMPONENT_PATH)
-GDB_CMDLINE = trap '' INT; $(GDB) -x $(GDBSTUB_DIR)/gdbcmds --args $(TARGET_OUT_0) $(SMING_TARGET_OPTIONS)
+GDB_CMDLINE = trap '' INT; $(GDB) -x $(GDBSTUB_DIR)/gdbcmds --args $(TARGET_OUT_0) $(CLI_TARGET_OPTIONS) --pause

Sming/Arch/Host/Components/vflash/component.mk

@@ -17,6 +17,11 @@ FLASH_BIN			?= $(FW_BASE)/flash.bin
 CONFIG_VARS			+= SPI_SIZE
 SPI_SIZE			?= 4M
 
+# Options to add when running emulator
+CACHE_VARS			+= HOST_FLASH_OPTIONS
+HOST_FLASH_OPTIONS	?= --flashfile=$(FLASH_BIN) --flashsize=$(SPI_SIZE)
+CLI_TARGET_OPTIONS += $(HOST_FLASH_OPTIONS)
+
 # Write data to flash
 # $1 -> Start offset
 # $2 -> File containing data to write

Sming/Arch/Host/app.mk

@@ -13,15 +13,6 @@ LDFLAGS = \
 # Executable
 TARGET_OUT_0			:= $(FW_BASE)/$(APP_NAME)$(TOOL_EXT)
 
-# Command-line options passed to executable
-CACHE_VARS				+= SMING_TARGET_OPTIONS
-SMING_TARGET_OPTIONS	?= \
-	--flashfile=$(FLASH_BIN) \
-	--flashsize=$(SPI_SIZE) \
-	--uart=0 \
-	--uart=1 \
-	--pause=5
-
 # Target definitions
 
 .PHONY: application
@@ -41,9 +32,16 @@ ifneq ($(DISABLE_SPIFFS), 1)
 FLASH_SPIFFS_CHUNKS	:= $(RBOOT_SPIFFS_0)=$(SPIFF_BIN_OUT)
 endif
 
+
+RUN_SCRIPT := $(FW_BASE)/run.sh
+
 .PHONY: run
 run: all ##Run the application image
-	$(TARGET_OUT_0) $(SMING_TARGET_OPTIONS)
+	$(Q) echo > $(RUN_SCRIPT); \
+	$(foreach id,$(ENABLE_HOST_UARTID),echo '$(call RunHostTerminal,$(id))' >> $(RUN_SCRIPT);) \
+	echo '$(TARGET_OUT_0) $(CLI_TARGET_OPTIONS)' >> $(RUN_SCRIPT); \
+	chmod +x $(RUN_SCRIPT); \
+	$(RUN_SCRIPT)
 
 .PHONY: flashfs
 flashfs: $(SPIFF_BIN_OUT) ##Write just the SPIFFS filesystem image
@@ -54,12 +52,7 @@ else
 endif
 
 .PHONY: flash
-flash: all flashfs ##Write the SPIFFS filesystem image then run the application
-ifeq ($(ENABLE_GDB), 1)
-	$(GDB_CMDLINE)
-else
-	$(TARGET_OUT_0) $(SMING_TARGET_OPTIONS)
-endif
+flash: all flashfs ##Write all images to (virtual) flash
 
 .PHONY: flashinit
 flashinit: | $(FW_BASE) ##Erase all flash memory

Sming/Arch/Host/build.mk

@@ -26,3 +26,14 @@ OUT_BASE	:= out/$(SMING_ARCH)/$(UNAME)/$(if $(SMING_RELEASE),release,debug)
 
 # => Tools
 MEMANALYZER = size
+
+# Command-line options passed to executable - Components add their own settings to this
+CLI_TARGET_OPTIONS =
+
+# Run a command in a new terminal window
+# $1 -> Command to execute
+ifeq ($(UNAME),Windows)
+DetachCommand = start $1
+else
+DetachCommand = gnome-terminal -- bash -c "sleep 1; $1"
+endif

Sming/Arch/Host/readme.md

@@ -34,45 +34,48 @@ cd $SMING_HOME/../samples/Basic_Serial
 make SMING_ARCH=Host
 ```
 
-This builds the application as an executable in `out/firmware/app`.
-Various command-line options are supported, use `--help` for details.
+This builds the application as an executable in, for example, `out/Host/Windows/firmware/app.exe`. Various command-line options are supported, use `--help` for details.
 
-Use `make run` to execute the application. Command-line parameters are passed in `SMING_TARGET_OPTIONS` so you can customise this via environment or application makefile thus:
-
-`export SMING_TARGET_OPTIONS="--pause --uart=0"`
+The easiest way to run the emulator is via `make run`. Variables are used to pass the appropriate options and are discussed below under [Features](#features).
 
 To find out what options are in force, use `make list-config`.
 
 ## Features
 
 ### Flash memory
 
-This is emulated using a backing file. By default, it's in `flash.bin` in the current directory.
+This is emulated using a backing file. By default it's in `flash.bin` in the firmware directory, you can change it by setting `FLASH_BIN`. The size of the flash memory is set via `SPI_SIZE`.
+
+* `make flashinit` to clear and reset the file.
+* `make flashfs` to copy the generated SPIFFS image into the backing file.
+* `make flash` writes out all required images to the backing file. For now, this is the same as `make flashfs` but that will change when support is added for custom user images.
 
-Use `make flashinit` to clear and reset the file.
-Use `make flashfs` to copy the generated SPIFFS image into the backing file. `make flash` does the same then runs the application.
-Use `make flash` to do a `flashfs` then a `run`
 
 ### UART (serial) ports
 
-Multiple serial terminals are supported via raw TCP network sockets.
+Multiple serial terminals are supported via raw TCP network sockets, so telnet can be used to provide terminal capability.
 
-For example, start the `Basic_Serial` sample application we build above, with support for both UARTs using the following options:
+`make run` starts the emulator with any required telnet sessions. By default, no serial ports are enabled, however any output from UART0 is redirected to the console. No input is possible.
 
-`out/firmware/app --pause --uart=0 --uart=1`
+If your project requires proper terminal access, set `ENABLE_HOST_UARTID` to the UART numbers required. Typically this would be added to the project's `component.mk` file. For example, the `Basic_Serial` sample specifies `ENABLE_HOST_UARTID=0 1` to enable emulation for both `UART0` and `UART1`.
+
+Set `HOST_UART_PORTBASE` if you want to change the base port number used to communicate with the emulator.
 
-Note: if you don't specify the `pause` option then the Sming application will start running immediately and any serial output will be discarded.
 
-In separate command windows, start two telnet sessions (a terminal for each serial port):
+Alternatively, you can run the application manually like this:
+
+`out/firmware/app --pause --uart=0 --uart=1`
+
+Now start a telnet session for each serial port, in separate command windows:
 
 ```
 telnet localhost 10000
 telnet localhost 10001
 ```
 
-In the application window, press Enter.
+In the application window, press Enter. This behaviour is enabled by the `pause` option, which stops the emulator after initialisation so telnet can connect to it. Without `pause` you'll lose any serial output at startup.)
 
-Note: For Windows users, `putty` is generally a better choice. For example, you can configure it to implicitly perform carriage-return for linefeed (i.e. "\n" -> "\r\n"). Run using:
+Note: For Windows users, `putty` is a good alternative to telnet. It has options to for things like carriage-return/linefeed translation ("\n" -> "\r\n"). Run using:
 
 ```
 putty telnet://localhost:10000
@@ -117,7 +120,13 @@ By default, the first valid network adapter will be used, with address assigned
 
 If the adapter is wrong, get a list thus:
 
-	out\firmware\app --ifname=?
+	out\Host\Windows\debug\firmware\app --ifname=?
+
+or
+
+	make run HOST_NETWORK_OPTIONS=--ifname=?
+
+produces a listing:
 
 	...
 
@@ -134,27 +143,16 @@ If the adapter is wrong, get a list thus:
 	- 6: {0F649280-BAC2-4515-9CE3-F7DFBB6A1BF8} - Kaspersky Security Data Escort Adapter
 	        10.102.37.150 / 255.255.255.252
 
-Then use the appropriate number:
-
-	out\firmware\app --ifname=5
-
-You can also specify by GUID, or a part of it:
+Then use the appropriate number (or GUID), with the gateway IP address - an address will be assigned via DHCP:
 
-	out\firmware\app --ifname={530640FF
-
-The network adapter may be autodetected from a provided ip address, but you must also give the network gateway must also be provided. For example:
-
-	out\firmware\app --ipaddr=192.168.1.10 --gateway=192.168.1.254
+	make run HOST_NETWORK_OPTIONS="--ifname=5 --gateway=192.168.1.254"
 
 You can find gateway addresses using the `ipconfig` command.
 
-We can then run using
-
-`out/firmware/app --ifname=4 --gateway=192.168.1.254 --ipaddr=192.168.1.10`
+If you want to use a specific IP address, the appropriate adapter will be selected but you still need to specify the gateway address:
 
-To use these settings for a `make run`, do this:
+	make run HOST_NETWORK_OPTIONS="--ipaddr=192.168.1.10 --gateway=192.168.1.254"
 
-`set SMING_TARGET_OPTIONS="--ifname=4 --gateway=192.168.1.254 --ipaddr=192.168.1.10"`
 
 ## todo
 
@@ -166,4 +164,4 @@ Development platforms with SPI or I2C (e.g. Raspberry Pi) could be supported.
 
 Are there any generic device emulators available? For example, to simulate specific types of SPI slave.
 
-All code is intended to run on either Windows (MinGW) or Linux as simply as possible, without requiring any additional dependencies. If things get more complicated then we might need to consider using external libraries, such as Boost.
+All code is intended to run on either Windows (MinGW) or Linux as simply as possible, without requiring any additional dependencies.

samples/Basic_DateTime/component.mk

@@ -1 +1,4 @@
 DISABLE_SPIFFS = 1
+
+# Emulate UART 0
+ENABLE_HOST_UARTID := 0

samples/Basic_Serial/component.mk

@@ -6,3 +6,7 @@ CUSTOM_TARGETS	:= files/Readme.md
 files/Readme.md: $(SMING_HOME)/../Readme.md
 	$(Q) mkdir -p $(@D)
 	$(Q) cp $< $@
+
+
+# Emulate both serial ports
+ENABLE_HOST_UARTID := 0 1

samples/Basic_rBoot/component.mk

@@ -32,3 +32,6 @@ SPIFF_SIZE			?= 65536
 ## (spiffs location defaults to the mb after the rom slot on 4mb flash)
 #RBOOT_SPIFFS_0		?= 0x100000
 #RBOOT_SPIFFS_1		?= 0x300000
+
+# Emulate UART 0
+ENABLE_HOST_UARTID := 0

samples/LiveDebug/component.mk

@@ -11,3 +11,7 @@ all:
 	$(warning WARNING! Enabling the GDB console may interfere with visual debuggers, like eclipse)
 	$(warning If required, please build with `make ENABLE_GDB_CONSOLE=0`)
 endif
+
+
+# Emulate UART 0
+ENABLE_HOST_UARTID := 0

tests/HostTests/component.mk

@@ -3,4 +3,4 @@ DEBUG_VERBOSE_LEVEL = 3
 SPI_SIZE = 4M
 
 .PHONY: execute
-execute: flash
+execute: flash run