Add debug name to MemoryMapEntry (#385)

* Add debug name to MemoryMapEntry

This enables value out of range logs to include a control name

* Add debug name for custom module functions

* Use debug name in logs for nil strings

* Update StringAllocation.lua

Scripts/DCS-BIOS/lib/modules/Module.lua

@@ -83,7 +83,7 @@ function Module:defineSetCommandTumb(identifier, device_id, command, arg_number,
 		end
 	end
 
-	local enumAlloc = self:allocateInt(last_n)
+	local enumAlloc = self:allocateInt(last_n, identifier)
 	local strAlloc = nil
 	if output_map then
 		local max_len = 0
@@ -92,7 +92,7 @@ function Module:defineSetCommandTumb(identifier, device_id, command, arg_number,
 				max_len = output_map[i]:len()
 			end
 		end
-		strAlloc = self:allocateString(max_len)
+		strAlloc = self:allocateString(max_len, identifier)
 	end
 
 	self:addExportHook(function(dev0)
@@ -179,7 +179,7 @@ function Module:defineGaugeValue(identifier, arg_number, output_range, category,
 	assert(output_range[1] >= 0)
 
 	local max_value = 65535
-	local alloc = self:allocateInt(max_value)
+	local alloc = self:allocateInt(max_value, identifier)
 	self:addExportHook(function(dev0)
 		alloc:setValue(Module.valueConvert(dev0:get_argument_value(arg_number), { 0, 1 }, output_range))
 	end)
@@ -208,7 +208,7 @@ function Module:defineVariableStepTumb(identifier, device_id, command, arg_numbe
 		GetDevice(device_id):performClickableAction(command, delta)
 	end)
 
-	local alloc = self:allocateInt(max_value)
+	local alloc = self:allocateInt(max_value, identifier)
 
 	local control = Control:new(category, ControlType.variable_step_dial, identifier, description, {
 		VariableStepInput:new(3200, max_value, description),
@@ -235,7 +235,7 @@ end
 --- @return Control control the control which was added to the module
 function Module:defineFloatValue(identifier, arg_number, max_value, limits, category, description)
 	assert_min_max(limits, "limits")
-	local alloc = self:allocateInt(max_value)
+	local alloc = self:allocateInt(max_value, identifier)
 	self:addExportHook(function(dev0)
 		alloc:setValue(Module.valueConvert(dev0:get_argument_value(arg_number), limits, { 0, max_value }))
 	end)
@@ -283,7 +283,7 @@ function Module:define8BitFloatFromGetter(identifier, getter, limits, category,
 	-- same as defineFloat, but only allocates an 8-bit int
 	assert_min_max(limits, "limits")
 	local max_value = 255
-	local alloc = self:allocateInt(max_value)
+	local alloc = self:allocateInt(max_value, identifier)
 
 	self:addExportHook(function()
 		alloc:setValue(Module.valueConvert(getter(), limits, { 0, max_value }))
@@ -326,7 +326,7 @@ end
 --- @param description string additional information about the control
 --- @return Control control the control which was added to the module
 function Module:defineGatedIndicatorLight(identifier, arg_number, min, max, category, description)
-	local alloc = self:allocateInt(1)
+	local alloc = self:allocateInt(1, identifier)
 
 	local control = Control:new(category, ControlType.led, identifier, description, {}, {
 		IntegerOutput:new(alloc, Suffix.none, "0 if light is off, 1 if light is on"),
@@ -389,7 +389,7 @@ function Module:definePotentiometer(identifier, device_id, command, arg_number,
 		GetDevice(device_id):performClickableAction(command, newValue / max_value * intervalLength + limits[1])
 	end)
 
-	local value = self:allocateInt(max_value)
+	local value = self:allocateInt(max_value, identifier)
 
 	self:addExportHook(function(dev0)
 		value:setValue(((dev0:get_argument_value(arg_number) - limits[1]) / intervalLength) * max_value)
@@ -430,7 +430,7 @@ end
 --- @param description string additional information about the control
 --- @return Control control the control which was added to the module
 function Module:defineToggleSwitchToggleOnly(identifier, device_id, command, arg_number, category, description)
-	local alloc = self:allocateInt(1)
+	local alloc = self:allocateInt(1, identifier)
 
 	local control = Control:new(category, ControlType.action, identifier, description, {
 		FixedStepInput:new("switch to previous or next state"),
@@ -491,7 +491,7 @@ function Module:defineRotary(identifier, device_id, command, arg_number, categor
 		GetDevice(device_id):performClickableAction(command, tonumber(value) / max_value)
 	end)
 
-	local value = self:allocateInt(max_value)
+	local value = self:allocateInt(max_value, identifier)
 
 	local control = Control:new(category, ControlType.analog_dial, identifier, description, {
 		VariableStepInput:new(3200, max_value, "turn the dial left or right"),
@@ -605,7 +605,7 @@ end
 --- @param description string additional information about the control
 --- @return Control control the control which was added to the module
 function Module:defineString(identifier, getter, max_length, category, description)
-	local alloc = self:allocateString(max_length)
+	local alloc = self:allocateString(max_length, identifier)
 	self:addExportHook(function(dev0)
 		local value = getter(dev0) --ammo
 		if value == nil then
@@ -636,7 +636,7 @@ end
 --- @param description string additional information about the control
 --- @return Control
 function Module:defineRockerSwitch(identifier, device_id, pos_command, pos_stop_command, neg_command, neg_stop_command, arg_number, category, description)
-	local alloc = self:allocateInt(2)
+	local alloc = self:allocateInt(2, identifier)
 	self:addExportHook(function(dev0)
 		local lut = { [-1] = 0, [0] = 1, [1] = 2 }
 		alloc:setValue(lut[Module.round(dev0:get_argument_value(arg_number))])
@@ -749,7 +749,7 @@ end
 --- @param description string additional information about the control
 --- @return Control control the control which was added to the module
 function Module:defineIntegerFromGetter(identifier, getter, maxValue, category, description)
-	local alloc = self:allocateInt(maxValue)
+	local alloc = self:allocateInt(maxValue, identifier)
 	self:addExportHook(function(dev0)
 		alloc:setValue(getter(dev0))
 	end)
@@ -795,7 +795,7 @@ function Module:defineTumb(identifier, device_id, command, arg_number, step, lim
 	--  also apparently anything with radio wheel
 	--  It's unclear if that should affect allocateInt.maxValue, so we'll leave that for the future
 	local max_value = last_n - (cycle == "skiplast" and 1 or 0)
-	local enumAlloc = self:allocateInt(max_value)
+	local enumAlloc = self:allocateInt(max_value, identifier)
 	local strAlloc = nil
 	if output_map then
 		local max_len = 0
@@ -804,7 +804,7 @@ function Module:defineTumb(identifier, device_id, command, arg_number, step, lim
 				max_len = output_map[i]:len()
 			end
 		end
-		strAlloc = self:allocateString(max_len)
+		strAlloc = self:allocateString(max_len, identifier)
 	end
 	self:addExportHook(function(dev0)
 		local value = dev0:get_argument_value(arg_number)
@@ -899,7 +899,7 @@ end
 --- @param description string additional information about the control
 --- @return Control control the control which was added to the module
 function Module:defineSpringloaded_3PosTumb(identifier, device_id, down_switch, up_switch, arg_number, category, description)
-	local alloc = self:allocateInt(2)
+	local alloc = self:allocateInt(2, identifier)
 	self:addExportHook(function(dev0)
 		local val = dev0:get_argument_value(arg_number)
 		if val == -1 then
@@ -978,16 +978,18 @@ end
 
 --- Allocates space for a string to the memory map of the module
 --- @param max_length integer the maximum length of the string
+--- @param identifier string? the identifier of the control being allocated
 --- @return StringAllocation alloc the space allocated for the string
-function Module:allocateString(max_length)
-	return self.memoryMap:allocateString(max_length)
+function Module:allocateString(max_length, identifier)
+	return self.memoryMap:allocateString(max_length, string.format("%s:%s", self.name, identifier or ""))
 end
 
 --- Allocates space for an integer to the memory map of the module
 --- @param max_value integer the maximum value of the integer
+--- @param identifier string? the identifier of the control being allocated
 --- @return MemoryAllocation alloc the space allocated for the integer
-function Module:allocateInt(max_value)
-	return self.memoryMap:allocateInt(max_value)
+function Module:allocateInt(max_value, identifier)
+	return self.memoryMap:allocateInt(max_value, string.format("%s:%s", self.name, identifier or ""))
 end
 
 --- Adds an export hook to the module

Scripts/DCS-BIOS/lib/modules/aircraft_modules/AJS37.lua

@@ -28,7 +28,7 @@ local AJS37 = Module:new("AJS37", 0x4600, { "AJS37" })
 --- @param description string additional information about the control
 --- @return Control control the control which was added to the module
 function AJS37:defineMissileSelectPushButton(identifier, device_id, command, arg_number, category, description)
-	local alloc = self:allocateInt(1)
+	local alloc = self:allocateInt(1, identifier)
 
 	local control = Control:new(category, ControlType.action, identifier, description, {
 		ActionInput:new(ActionArgument.toggle, "Presses the button"),

Scripts/DCS-BIOS/lib/modules/aircraft_modules/C-101.lua

@@ -32,7 +32,7 @@ function C_101:defineRotaryPlus(identifier, device_id, command2, command1, arg_n
 		device:performClickableAction(command2, (tonumber(value) or 0) / max_value)
 		device:performClickableAction(command1, 0)
 	end)
-	local alloc = self:allocateInt(max_value)
+	local alloc = self:allocateInt(max_value, identifier)
 
 	local control = Control:new(category, ControlType.analog_dial, identifier, description, {
 		VariableStepInput:new(3200, max_value, "turn the dial left or right"),

Scripts/DCS-BIOS/lib/modules/aircraft_modules/Ka-50.lua

@@ -28,7 +28,7 @@ local function definePushButtonLed(self, identifier, arg_number, category, descr
 	end
 
 	local max_value = 1
-	local alloc = self:allocateInt(max_value)
+	local alloc = self:allocateInt(max_value, identifier)
 	assert(alloc.shiftBy ~= nil)
 	self:addExportHook(function(dev0)
 		alloc:setValue(round(dev0:get_argument_value(arg_number) * 10) % 2)

Scripts/DCS-BIOS/lib/modules/aircraft_modules/Mosquito.lua

@@ -15,7 +15,7 @@ local Mosquito = Module:new("Mosquito", 0x7000, { "MosquitoFBMkVI" })
 -- remove Arg# Pilot 500
 
 function Mosquito:define3PosMossi(msg, device_id, command, arg_number, category, description)
-	local alloc = self:allocateInt(2)
+	local alloc = self:allocateInt(2, msg)
 	self:addExportHook(function(dev0)
 		local lut = { [-1] = 0, [0] = 1, [1] = 2 }
 		alloc:setValue(lut[Module.round(dev0:get_argument_value(arg_number))])

Scripts/DCS-BIOS/lib/modules/common_modules/NS430.lua

@@ -60,7 +60,7 @@ local NS430 = Module:new("NS430", 0x0600, ns430_aircraft)
 -- v2.0 by Celemourn
 
 function NS430:defineDoubleCommandButton(identifier, device_id, start_command, stop_command, arg_number, category, description)
-	local alloc = self:allocateInt(1)
+	local alloc = self:allocateInt(1, identifier)
 	self:addExportHook(function(dev0)
 		alloc:setValue(dev0:get_argument_value(arg_number))
 	end)
@@ -86,7 +86,7 @@ function NS430:defineDoubleCommandButton(identifier, device_id, start_command, s
 end
 
 function NS430:defineMomentaryRockerSwitch(identifier, device_id, pos_command, pos_stop_command, neg_command, neg_stop_command, arg_number, category, description)
-	local alloc = self:allocateInt(2)
+	local alloc = self:allocateInt(2, identifier)
 	self:addExportHook(function(dev0)
 		local lut = { [-1] = 0, [0] = 1, [1] = 2 }
 		alloc:setValue(lut[Module.round(dev0:get_argument_value(arg_number))])

Scripts/DCS-BIOS/lib/modules/memory_map/MemoryAllocation.lua

@@ -10,15 +10,17 @@ local Log = require("Log")
 --- @field mask integer TODO
 --- @field shiftBy integer TODO
 --- @field value integer? the current value
+--- @field private debug_name? string the human-readable name to display for this allocation in logs
 local MemoryAllocation = {}
 
 --- Creates a new memory allocation
 --- @param max_value number
 --- @param entry MemoryMapEntry
 --- @param shift_by number
 --- @param bits_required number
+--- @param debug_name string? the human-readable name to display for this allocation in logs
 --- @return MemoryAllocation
-function MemoryAllocation:new(max_value, entry, shift_by, bits_required)
+function MemoryAllocation:new(max_value, entry, shift_by, bits_required, debug_name)
 	--- @type MemoryAllocation
 	local o = {
 		address = entry.address,
@@ -27,6 +29,7 @@ function MemoryAllocation:new(max_value, entry, shift_by, bits_required)
 		multiplier = math.pow(2, shift_by),
 		mask = (math.pow(2, bits_required) - 1) * math.pow(2, shift_by),
 		shiftBy = shift_by,
+		debug_name = debug_name,
 	}
 	setmetatable(o, self)
 	self.__index = self
@@ -52,11 +55,11 @@ function MemoryAllocation:setValue(value)
 
 	value = math.floor(value)
 	if value < 0 then
-		Log:log_error(string.format("Util.lua: value %f is too small for address %d mask %d", value, self.address, self.mask))
+		Log:log_error(string.format("MemoryAllocation.lua: value %f is too small for %s (address %d mask %d)", value, self.debug_name or "n/a", self.address, self.mask))
 		return
 	end
 	if value > self.maxValue then
-		Log:log_error(string.format("Util.lua: value %f is too large for address %d mask %d", value, self.address, self.mask))
+		Log:log_error(string.format("MemoryAllocation.lua: value %f is larger than max %d for %s (address %d mask %d)", value, self.maxValue, self.debug_name or "n/a", self.address, self.mask))
 		return
 	end
 	assert(value >= 0)

Scripts/DCS-BIOS/lib/modules/memory_map/MemoryMap.lua

@@ -127,21 +127,23 @@ end
 
 --- Allocates space for a new integer value
 --- @param max_value integer
+--- @param debug_name string? the human-readable name to display for this allocation in logs
 --- @return MemoryAllocation allocation the newly-created memory allocation
-function MemoryMap:allocateInt(max_value)
-	return self:allocateData(max_value, false, false)
+function MemoryMap:allocateInt(max_value, debug_name)
+	return self:allocateData(max_value, false, false, debug_name)
 end
 
 --- Allocates space for a new string value
 --- @param max_length number the max length of the string
+--- @param debug_name string? the human-readable name to display for this allocation in logs
 --- @return StringAllocation
-function MemoryMap:allocateString(max_length)
+function MemoryMap:allocateString(max_length, debug_name)
 	--- @type MemoryAllocation[]
 	local character_allocations = {}
 
-	character_allocations[1] = self:allocateData(255, true, true)
+	character_allocations[1] = self:allocateData(255, true, true, debug_name)
 	for i = 2, max_length, 1 do
-		character_allocations[i] = self:allocateData(255, true, false)
+		character_allocations[i] = self:allocateData(255, true, false, debug_name)
 	end
 
 	return StringAllocation:new(character_allocations, max_length)
@@ -152,8 +154,9 @@ end
 --- @param max_value integer the maximum integer value stored in the memory allocation
 --- @param is_string_character boolean whether the space is being allocated for a string character
 --- @param first_string_character boolean whether this is the first character of a string
+--- @param debug_name string? the human-readable name to display for this allocation in logs
 --- @return MemoryAllocation
-function MemoryMap:allocateData(max_value, is_string_character, first_string_character)
+function MemoryMap:allocateData(max_value, is_string_character, first_string_character, debug_name)
 	-- allocate space for an integer value from 0 to maxValue in the memory map
 	-- returns a MemoryAllocation object that has a setValue() method
 	-- if is_string_character is true, the allocation will be in a byte-aligned
@@ -175,7 +178,7 @@ function MemoryMap:allocateData(max_value, is_string_character, first_string_cha
 			and ((not is_string_character) or entry:canAllocateStringCharacter(first_string_character)) -- string characters have special rules
 		then
 			-- found an entry that has enough space for the number of bits we want to allocate
-			return entry:allocate(max_value)
+			return entry:allocate(max_value, debug_name)
 		else
 			address = address + 2
 		end

Scripts/DCS-BIOS/lib/modules/memory_map/MemoryMapEntry.lua

@@ -47,12 +47,13 @@ end
 
 --- Allocates space in this entry to store a value which is less than or equal to the provided max value
 --- @param max_value integer the maximum value that will be stored in this space
+--- @param debug_name string? the human-readable name to display for this allocation in logs
 --- @return MemoryAllocation allocation the new memory allocation for the provided value
-function MemoryMapEntry:allocate(max_value)
+function MemoryMapEntry:allocate(max_value, debug_name)
 	assert(self:canAllocate(max_value))
 	local bits_required = MemoryMapEntry.bitsRequiredForValue(max_value)
 	local shift_by = self.allocatedBitCounter
-	local alloc = MemoryAllocation:new(max_value, self, shift_by, bits_required)
+	local alloc = MemoryAllocation:new(max_value, self, shift_by, bits_required, debug_name)
 	self.allocatedBitCounter = self.allocatedBitCounter + bits_required
 	table.insert(self.allocations, alloc)
 	return alloc

Scripts/DCS-BIOS/lib/modules/memory_map/StringAllocation.lua

@@ -6,18 +6,21 @@ local Log = require("Log")
 --- @field address integer the memory address
 --- @field maxLength integer the maximum length of the string
 --- @field characterAllocations MemoryAllocation[] the memory allocations which make up the string
+--- @field debug_name string? the human-readable name to display for this allocation in logs
 local StringAllocation = {}
 
 --- Constructs a new StringAllocation
 --- @param characterAllocations MemoryAllocation[] the memory allocations which make up the string
 --- @param max_length integer the maximum length of the string
+--- @param debug_name string? the human-readable name to display for this allocation in logs
 --- @return StringAllocation
-function StringAllocation:new(characterAllocations, max_length)
+function StringAllocation:new(characterAllocations, max_length, debug_name)
 	--- @type StringAllocation
 	local o = {
 		address = characterAllocations[1].address,
 		maxLength = max_length,
 		characterAllocations = characterAllocations,
+		debug_name = debug_name,
 	}
 	setmetatable(o, self)
 	self.__index = self
@@ -30,7 +33,7 @@ function StringAllocation:setValue(value)
 	local i = 1
 
 	if value == nil then
-		Log:log_error(string.format("Util.lua: item is sending a nil value"))
+		Log:log_error(string.format("StringAllocation.lua: string for %s is sending a nil value", self.debug_name))
 		return
 	end