[Dexter] Add DexDeclareAddress command and address function

[StephenTozer]

Summary

This patch adds a new Dexter command, DexDeclareAddress, which is used to test the relative values of pointer variables. The motivation for adding this command is to allow meaningful assertions to be made about pointers that go beyond checking variable availability and null equality.

The full explanation and syntax is given in Commands.md, but as an example the following code tests that the pointer foo is equal to bar, and baz is equal to foo + 16:

DexDeclareAddress('my_addr')
DexExpectWatchValue('foo', address('my_addr'))
DexExpectWatchValue('bar', address('my_addr'))
DexExpectWatchValue('baz', address('my_addr', 16))

[Orlando]

In the test you've added cross-project-tests/debuginfo-tests/dexter-tests/address.cpp we have:

// DexDeclareAddress('addr')
// DexExpectWatchValue('a', 0, address('addr'), from_line=8, to_line=10)
// DexExpectWatchValue('b', address('addr'), on_line=10)

Comparing this to:

// DexExpectWatchValue('b == a', True, on_line=10)

Am I right in thinking the main benefit is that addr is captured (on first use in a DexExpectWatchValue) which means we can use the value later, even if a has been optimized out when we want to check the value of b?

I don't particularly like the way of assigning a value to the address variable: "In its first appearance it will match against any valid pointer". I'd prefer a dedicated command (or even rolling it into DexDeclareAddress) because this implicit behaviour is not very obvious when skimming a test. What do you think?

Please can you add some regression tests for the Command? You can take inspiration from the duplicate label test and referencing an undefined label test, plus it would be good to have at least one test in the command tests using it.

cross-project-tests/debuginfo-tests/dexter/dex/command/commands/DexExpectWatchBase.py

62–1

nit: .

71

nit: a address -> an address, and the comment needs a full stop.

cross-project-tests/debuginfo-tests/dexter/dex/heuristic/Heuristic.py

8

Sorry if this is a silly question, why do we need to do this here in the heuristic code?

[StephenTozer]

In D111447#3057619, @Orlando wrote:

Am I right in thinking the main benefit is that addr is captured (on first use in a DexExpectWatchValue) which means we can use the value later, even if a has been optimized out when we want to check the value of b?

Yes - this doesn't necessarily just apply to optimized out variables but to any set of variables in the program, including variables in entirely disjoint scopes, or variables in the same scope at different points in time. This could also include comparing a variable to itself, such as DexExpectValue('a', address('a'), address('a', 4), address('a', 8)) to test that an iterator increments correctly.

I don't particularly like the way of assigning a value to the address variable: "In its first appearance it will match against any valid pointer". I'd prefer a dedicated command (or even rolling it into DexDeclareAddress) because this implicit behaviour is not very obvious when skimming a test. What do you think?

I considered a "declare a specific address once" version, but wasn't sure if it would be preferable, since it means that if the "canonical" address is not available at the point you declare it at then every test using the address would fail - even if every other use of the address is consistent. This is suitable for lit tests where we always expect sucess/failure to be binary, but it seems more brittle in score-based testing, which Dexter ostensibly supports. I'm not necessarily opposed to it, since it would simplify the code and the test syntax in some cases, but I'm not sure whether it's worth making the scoring heuristic less reliable.

[Orlando]

In D111447#3058958, @StephenTozer wrote:

In D111447#3057619, @Orlando wrote:

Am I right in thinking the main benefit is that addr is captured (on first use in a DexExpectWatchValue) which means we can use the value later, even if a has been optimized out when we want to check the value of b?

Yes - this doesn't necessarily just apply to optimized out variables but to any set of variables in the program, including variables in entirely disjoint scopes, or variables in the same scope at different points in time. This could also include comparing a variable to itself, such as DexExpectValue('a', address('a'), address('a', 4), address('a', 8)) to test that an iterator increments correctly.

Cool, that SGTM.

I don't particularly like the way of assigning a value to the address variable: "In its first appearance it will match against any valid pointer". I'd prefer a dedicated command (or even rolling it into DexDeclareAddress) because this implicit behaviour is not very obvious when skimming a test. What do you think?

I considered a "declare a specific address once" version, but wasn't sure if it would be preferable, since it means that if the "canonical" address is not available at the point you declare it at then every test using the address would fail - even if every other use of the address is consistent. This is suitable for lit tests where we always expect sucess/failure to be binary, but it seems more brittle in score-based testing, which Dexter ostensibly supports. I'm not necessarily opposed to it, since it would simplify the code and the test syntax in some cases, but I'm not sure whether it's worth making the scoring heuristic less reliable.

That is a good point and I'm almost convinced. Again, from your test cross-project-tests/debuginfo-tests/dexter-tests/address.cpp: Am I right in thinking that if a is always reported as optimized out then the DexExpectWatchValue for b will always succeed? I wonder if "address name is assigned but never checked" and "address name is never assigned" should be cases for heuristic penalties. OTOH that adds complexity to and already complex command / interaction. What do you think?

[StephenTozer]

In D111447#3060695, @Orlando wrote:

That is a good point and I'm almost convinced. Again, from your test cross-project-tests/debuginfo-tests/dexter-tests/address.cpp: Am I right in thinking that if a is always reported as optimized out then the DexExpectWatchValue for b will always succeed? I wonder if "address name is assigned but never checked" and "address name is never assigned" should be cases for heuristic penalties. OTOH that adds complexity to and already complex command / interaction. What do you think?

It seems reasonable that we could add more specific scoring for these - right now in terms of points, the ranking of the following scenarios is:
Both variables unavailable < One variable unavailable == Both variables available but different < Both variables available

If we add the suggested "address name assigned but never checked" penalty, "One variable unavailable" would give a worse score than "Both variables available but different". Alternatively if we added an additional penalty for an address that was "successful" but didn't match elsewhere, then we would have "Both variables available but different" would be worse. Which do you think would be best?

[Orlando]

In D111447#3060849, @StephenTozer wrote:

In D111447#3060695, @Orlando wrote:

That is a good point and I'm almost convinced. Again, from your test cross-project-tests/debuginfo-tests/dexter-tests/address.cpp: Am I right in thinking that if a is always reported as optimized out then the DexExpectWatchValue for b will always succeed? I wonder if "address name is assigned but never checked" and "address name is never assigned" should be cases for heuristic penalties. OTOH that adds complexity to and already complex command / interaction. What do you think?

It seems reasonable that we could add more specific scoring for these - right now in terms of points, the ranking of the following scenarios is:
Both variables unavailable < One variable unavailable == Both variables available but different < Both variables available

If we add the suggested "address name assigned but never checked" penalty, "One variable unavailable" would give a worse score than "Both variables available but different". Alternatively if we added an additional penalty for an address that was "successful" but didn't match elsewhere, then we would have "Both variables available but different" would be worse. Which do you think would be best?

IMO "both variables available but different" should be treated as worse (higher penalty, lower desirability) than "one variable available". This fits the assumption that an incorrect value is more damaging to debugging experience than a missing one.

[Orlando]

In D111447#3061202, @Orlando wrote:

IMO "both variables available but different" should be treated as worse (higher penalty, lower desirability) than "one variable available". This fits the assumption that an incorrect value is more damaging to debugging experience than a missing one.

Then again, treating "one variable available" as "better" isn't good if the value that is available is incorrect, so it's a tricky situation.

[StephenTozer]

Fixed up comments, and moved address_resolution map creation/assignment into parsing (from heuristic).

[StephenTozer]

In D111447#3061237, @Orlando wrote:

Then again, treating "one variable available" as "better" isn't good if the value that is available is incorrect, so it's a tricky situation.

But also, if we only see the value a single time, we have no way of knowing whether or not it's correct - since the value is essentially arbitrarily determined at runtime, it may be accurate to say that the relationship between the values is the only thing that matters (which may be an argument against using DexExpectWatchBase as a framework), so if we only have a single value it's hard to assign a "correctness" score to that value. A way to extend this reasoning might be to say, what if we check the same address in 3 different variables. In this case, there are 7 possibilities, using the format (num_variables_available, num_unique_address_values): (0, 0), (1, 1), (2, 2), (2, 1), (3, 3), (3, 2), (3, 1).

Going on current default penalty values, the penalty for the (3, 3) case would be 14, as there would be 2 incorrect values worth 7 points each. The penalty for the (0, 0) case on the other hand is somewhere from 9-18, depending on whether the values are recorded as "optimized out", "missing", or some other failure. In this case, the penalty amount also depends on the order that the evaluation happens in: if we have the variables (a, b, c) and a == b, a != c, then the penalty will depend on whether we encounter c first or not - if c is the first, then we have 2 incorrect variables, otherwise we have 1. I originally wanted to prevent this by having the heuristic attempt to find the best scoring value for each address and using that, but I thought it might be too "clever" an approach for a test framework. However, it might be the case that this is necessary for getting somewhat consistent scorin, and if we can't get it to have consistent scoring, then maybe we should just bite the bullet and have a single declared value that we assume is correct - at least that way it's clear to the user.

This is basically a fairly long-winded way of saying that I'm not sure what the answer is, but the options seem to be:

1. Leave it as is and accept that it's going to be inconsistent in its penalties sometimes
2. Have a single point for the value declared upfront, and leave it to the user to make sure that the value isn't incorrect or unavailable
3. Make the heuristic try to select address values to maximize the program's score
4. Use a different scoring system entirely, most likely making this completely separate to DexExpectWatchValue

I think I'm actually leaning more towards 2 now, since it makes it easier for the user to pick a value that they're sure is correct, potentially by modifying the source to guarantee that the correct value is accessible somewhere, although doing so could also affect the validity of the test. Option 1 does simplify things for common cases, but may not be worth the potential for inconsistent scoring - WDUT?

[Orlando]

In D111447#3062189, @StephenTozer wrote:

In D111447#3061237, @Orlando wrote:

Then again, treating "one variable available" as "better" isn't good if the value that is available is incorrect, so it's a tricky situation.

But also, if we only see the value a single time, we have no way of knowing whether or not it's correct - since the value is essentially arbitrarily determined at runtime, it may be accurate to say that the relationship between the values is the only thing that matters (which may be an argument against using DexExpectWatchBase as a framework), so if we only have a single value it's hard to assign a "correctness" score to that value. A way to extend this reasoning might be to say, what if we check the same address in 3 different variables. In this case, there are 7 possibilities, using the format (num_variables_available, num_unique_address_values): (0, 0), (1, 1), (2, 2), (2, 1), (3, 3), (3, 2), (3, 1).

Going on current default penalty values, the penalty for the (3, 3) case would be 14, as there would be 2 incorrect values worth 7 points each. The penalty for the (0, 0) case on the other hand is somewhere from 9-18, depending on whether the values are recorded as "optimized out", "missing", or some other failure. In this case, the penalty amount also depends on the order that the evaluation happens in: if we have the variables (a, b, c) and a == b, a != c, then the penalty will depend on whether we encounter c first or not - if c is the first, then we have 2 incorrect variables, otherwise we have 1. I originally wanted to prevent this by having the heuristic attempt to find the best scoring value for each address and using that, but I thought it might be too "clever" an approach for a test framework. However, it might be the case that this is necessary for getting somewhat consistent scorin, and if we can't get it to have consistent scoring, then maybe we should just bite the bullet and have a single declared value that we assume is correct - at least that way it's clear to the user.

This is basically a fairly long-winded way of saying that I'm not sure what the answer is, but the options seem to be:

1. Leave it as is and accept that it's going to be inconsistent in its penalties sometimes
2. Have a single point for the value declared upfront, and leave it to the user to make sure that the value isn't incorrect or unavailable
3. Make the heuristic try to select address values to maximize the program's score
4. Use a different scoring system entirely, most likely making this completely separate to DexExpectWatchValue

I think I'm actually leaning more towards 2 now, since it makes it easier for the user to pick a value that they're sure is correct, potentially by modifying the source to guarantee that the correct value is accessible somewhere, although doing so could also affect the validity of the test. Option 1 does simplify things for common cases, but may not be worth the potential for inconsistent scoring - WDUT?

I considered mentioned something along the lines of this (3) but thought it seemed too much - too "clever" as you said - especially given the fact that we know the heuristic score is quite wonky already. I agree that either 1 or 2 is good. I like 2 because it makes the tests less magic, easier to interpret, but I'm not sure which is "better". It might be something we just have to experiment with (I will happily LGTM either 1 or 2)?

cross-project-tests/debuginfo-tests/dexter/dex/command/commands/DexExpectWatchBase.py

71

You've gone too far the other way! 😄 nit: ans address -> an address. Plus there're a couple of comments that need full stops still.

[StephenTozer]

FIrst pass implementation of the discussed change to DexDeclareAddress.

[Orlando]

The new tactic, code, and doc changes all SGTM (one nit inline).

I'll hold off my LGTM just for now though as I think it'd be good to have regression tests for the new command. You can take inspiration from the duplicate label test and referencing an undefined label test, plus it would be good to have at least one test in the command tests directory using it. To that end, the test you have at the moment (cross-project-tests/debuginfo-tests/dexter-tests/address.cpp) makes more sense as a command regression test IMO (see inline comment).

cross-project-tests/debuginfo-tests/dexter-tests/address.cpp

3–4 ↗

(On Diff #381078)

Imo this test should be a regression test in the dexter/feature_tests directory, and this RUN line should become:

// RUN: %dexter_regression_test -- %s

IIRC this substitution should allow the test to run on all systems, so you can also remove REQUIRES: system-windows.

wdyt?

cross-project-tests/debuginfo-tests/dexter/dex/command/ParseCommand.py

41

I wonder if there's a better way of sharing access to the address_resolutions dict? This doesn't feel quite right but (unhelpfully) no suggestion comes to mind.

[StephenTozer]

Add a set of feature tests for DexDeclareAddress; also fix a minor error that would appear if the address was never resolved.

Before merging, I'm also going to add a bit more useful output to the test - in particular making the penalty cases more clear: if a declared address never resolves to a value this should be explicitly stated in the output (in verbose mode if not by default), and if a variable has a missing value that was an address (i.e. the variable is never seen holding the address value) then the user should see which address was missing, rather than just the resolved value of that address. This should come with a couple of new tests, and should also resolve Orlando's inline comment about the address resolutions map (as this will need to be referenced in a proper context object in order for this feature to work).

[StephenTozer]

cross-project-tests/debuginfo-tests/dexter/dex/command/commands/DexExpectWatchBase.py

31

Aforementioned minor fix is here: the addition of resolutions[self.name] is None is needed to catch an address which is validly declared but does not have a resolved value (which should be because the line it was declared for was never stepped on). This results in a 'missing value' result for the variable that references it.

[StephenTozer]

Move the generation of the address resolution map to Heuristic (None initialized on command objects until the heuristic runs). Added address information to the verbose output (only prints additional info if DexDeclareAddress is actually present), and always print the name of the address in the "missing values" and "encountered expected values" output (implementation for misordered values is more complex, and has been ignored). Also, removed some unused functions in DexExpectWatchBase.

Adds a test for the penalty of a missing address, and also a test for all the aforementioned printing behaviour.

[StephenTozer]

Add 1 more test for the hit_count argument.

[Orlando]

I've looked at the two changes since my SGTM comment, which I'll now happily upgrade to a LGTM.

The regression tests look great! Most of them have REQUIRES: system-linux. I assume this is because they rely on the conditional controller, and dbgeng wrapper doesn't support it. Is that right? If so, I wonder if there's anything stopping them working on system-darwin. Perhaps these should instead be XFAIL: system-windows instead?

I enjoy the small refactor, and the improved verbose output looks good. Thanks!

cross-project-tests/debuginfo-tests/dexter/dex/command/commands/DexExpectWatchBase.py

29

nit: this comment needs updating after the latest change

31

SGTM

cross-project-tests/debuginfo-tests/dexter/feature_tests/subtools/test/address_printing.cpp

6–9 ↗

(On Diff #386587)

I don't think it should block the feature either way but I'm curious about why this is?

[StephenTozer]

cross-project-tests/debuginfo-tests/dexter/feature_tests/subtools/test/address_printing.cpp

6–9 ↗

(On Diff #386587)

The short summary is that the misordered result array is constructed by a function that does not trivially convert to the address/resolution logic; at least, that was my assessment when I looked at it - I'll take another look before merging to see if it isn't actually reasonable.

cross-project-tests/debuginfo-tests/dexter/Commands.md

 # Dexter commands
 
 * [DexExpectProgramState](Commands.md#DexExpectProgramState)
 * [DexExpectStepKind](Commands.md#DexExpectStepKind)
 * [DexExpectStepOrder](Commands.md#DexExpectStepOrder)
 * [DexExpectWatchType](Commands.md#DexExpectWatchType)
 * [DexExpectWatchValue](Commands.md#DexExpectWatchValue)
 * [DexUnreachable](Commands.md#DexUnreachable)
 * [DexLimitSteps](Commands.md#DexLimitSteps)
 * [DexLabel](Commands.md#DexLabel)
 * [DexWatch](Commands.md#DexWatch)
+* [DexDeclareAddress](Commands.md#DexDeclareAddress)
 * [DexDeclareFile](Commands.md#DexDeclareFile)
 * [DexFinishTest](Commands.md#DexFinishTest)
 
 ---
 ## DexExpectProgramState
     DexExpectProgramState(state [,**times])
 
     Args:
arithmetic operators to get offsets from labels:
     DexExpectWatchValues(..., on_line=ref('my_line_name') + 3)
     DexExpectWatchValues(..., on_line=ref('my_line_name') - 5)
 
 
 ### Heuristic
 This command does not contribute to the heuristic score.
 
 ----
+## DexDeclareAddress
+    DexDeclareAddress(declared_address, expr, **on_line[, **hit_count])
+
+    Args:
+        declared_address (str): The unique name of an address, which can be used
+                                in DexExpectWatch-commands.
+        expr (str): An expression to evaluate to provide the value of this
+                    address.
+        on_line (int): The line at which the value of the expression will be
+                       assigned to the address.
+        hit_count (int): If provided, reads the value of the source expression
+                         after the line has been stepped onto the given number
+                         of times ('hit_count = 0' gives default behaviour).
+
+### Description
+Declares a variable that can be used in DexExpectWatch- commands as an expected
+value by using the `address(str[, int])` function. This is primarily
+useful for checking the values of pointer variables, which are generally
+determined at run-time (and so cannot be consistently matched by a hard-coded
+expected value), but may be consistent relative to each other. An example use of
+this command is as follows, using a set of pointer variables "foo", "bar", and
+"baz":
+
+    DexDeclareAddress('my_addr', 'bar', on_line=12)
+    DexExpectWatchValue('foo', address('my_addr'), on_line=10)
+    DexExpectWatchValue('bar', address('my_addr'), on_line=12)
+    DexExpectWatchValue('baz', address('my_addr', 16), on_line=14)
+
+On the first line, we declare the name of our variable 'my_addr'. This name must
+be unique (the same name cannot be declared twice), and attempting to reference
+an undeclared variable with `address` will fail. The value of the address
+variable will be assigned as the value of 'bar' when line 12 is first stepped
+on.
+
+On lines 2-4, we use the `address` function to refer to our variable. The first
+usage occurs on line 10, before the line where 'my_addr' is assigned its value;
+this is a valid use, as we assign the address value and check for correctness
+after gathering all debug information for the test. Thus the first test command
+will pass if 'foo' on line 10 has the same value as 'bar' on line 12.
+
+The second command will pass iff 'bar' is available at line 12 - even if the
+variable and lines are identical in DexDeclareAddress and DexExpectWatchValue,
+the latter will still expect a valid value. Similarly, if the variable for a
+DexDeclareAddress command is not available at the given line, any test against
+that address will fail.
+
+The `address` function also accepts an optional integer argument representing an
+offset (which may be negative) to be applied to the address value, so
+`address('my_addr', 16)` resolves to `my_addr + 16`. In the above example, this
+means that we expect `baz == bar + 16`.
+
+### Heuristic
+This command does not contribute to the heuristic score.
+
+----
 ## DexDeclareFile
     DexDeclareFile(declared_file)
 
     Args:
         name (str): A declared file path for which all subsequent commands
           will have their path attribute set too.
 
 ### Description

cross-project-tests/debuginfo-tests/dexter/dex/command/ParseCommand.py

 from copy import copy
 from pathlib import PurePath
 from collections import defaultdict, OrderedDict
 
 from dex.utils.Exceptions import CommandParseError
 
 from dex.command.CommandBase import CommandBase
 from dex.command.commands.DexDeclareFile import DexDeclareFile
+from dex.command.commands.DexDeclareAddress import DexDeclareAddress
 from dex.command.commands.DexExpectProgramState import DexExpectProgramState
 from dex.command.commands.DexExpectStepKind import DexExpectStepKind
 from dex.command.commands.DexExpectStepOrder import DexExpectStepOrder
 from dex.command.commands.DexExpectWatchType import DexExpectWatchType
 from dex.command.commands.DexExpectWatchValue import DexExpectWatchValue
+from dex.command.commands.DexExpectWatchBase import AddressExpression, DexExpectWatchBase
 from dex.command.commands.DexLabel import DexLabel
 from dex.command.commands.DexLimitSteps import DexLimitSteps
 from dex.command.commands.DexFinishTest import DexFinishTest
 from dex.command.commands.DexUnreachable import DexUnreachable
 from dex.command.commands.DexWatch import DexWatch
 from dex.utils import Timer
 from dex.utils.Exceptions import CommandParseError, DebuggerException
 
 def _get_valid_commands():
     """Return all top level DExTer test commands.
 
     Returns:
         { name (str): command (class) }
     """
     return {
+      DexDeclareAddress.get_name() : DexDeclareAddress,
       DexDeclareFile.get_name() : DexDeclareFile,
       DexExpectProgramState.get_name() : DexExpectProgramState,
       DexExpectStepKind.get_name() : DexExpectStepKind,
       DexExpectStepOrder.get_name() : DexExpectStepOrder,
       DexExpectWatchType.get_name() : DexExpectWatchType,
       DexExpectWatchValue.get_name() : DexExpectWatchValue,
       DexLabel.get_name() : DexLabel,
       DexLimitSteps.get_name() : DexLimitSteps,
Returns:
         { name (str): command (class) }
     """
     subcommands = valid_commands[command_name].get_subcommands()
     if subcommands:
         return { **valid_commands, **subcommands }
     return valid_commands
 
 
-def _build_command(command_type, labels, raw_text: str, path: str, lineno: str) -> CommandBase:
+def _build_command(command_type, labels, addresses, raw_text: str, path: str, lineno: str) -> CommandBase:
     """Build a command object from raw text.
 
     This function will call eval().
 
     Raises:
         Any exception that eval() can raise.
 
     Returns:
         A dexter command object.
     """
     def label_to_line(label_name: str) -> int:
         line = labels.get(label_name, None)
         if line != None:
             return line
         raise format_unresolved_label_err(label_name, raw_text, path, lineno)
 
+    def get_address_object(address_name: str, offset: int=0):
+        if address_name not in addresses:
+            raise format_undeclared_address_err(address_name, raw_text, path, lineno)
+        return AddressExpression(address_name, offset)
+
     valid_commands = _merge_subcommands(
         command_type.get_name(), {
             'ref': label_to_line,
+            'address': get_address_object,
             command_type.get_name(): command_type,
         })
 
     # pylint: disable=eval-used
     command = eval(raw_text, valid_commands)
     # pylint: enable=eval-used
     command.raw_text = raw_text
     command.path = path
def format_unresolved_label_err(label: str, src: str, filename: str, lineno) -> CommandParseError:
     err = CommandParseError()
     err.src = src
     err.caret = '' # Don't bother trying to point to the bad label.
     err.filename = filename
     err.lineno = lineno
     err.info = f'Unresolved label: \'{label}\''
     return err
 
+def format_undeclared_address_err(address: str, src: str, filename: str, lineno) -> CommandParseError:
+    err = CommandParseError()
+    err.src = src
+    err.caret = '' # Don't bother trying to point to the bad address.
+    err.filename = filename
+    err.lineno = lineno
+    err.info = f'Undeclared address: \'{address}\''
+    return err
 
 def format_parse_err(msg: str, path: str, lines: list, point: TextPoint) -> CommandParseError:
     err = CommandParseError()
     err.filename = path
     err.src = lines[point.line].rstrip()
     err.lineno = point.get_lineno()
     err.info = msg
     err.caret = '{}<r>^</>'.format(' ' * (point.char))
if label.eval() in labels:
         err.filename = cmd_path
         err.src = label.raw_text
         # Don't both trying to point to it since we're only printing the raw
         # command, which isn't much text.
         err.caret = ''
         raise err
     labels[label.eval()] = label.get_line()
 
+def add_address(addresses, address, cmd_path, cmd_lineno):
+    # Enforce unique address variables.
+    address_name = address.get_address_name()
+    if address_name in addresses:
+        err = CommandParseError()
+        err.info = f'Found duplicate address: \'{address_name}\''
+        err.lineno = cmd_lineno
+        err.filename = cmd_path
+        err.src = address.raw_text
+        # Don't both trying to point to it since we're only printing the raw
+        # command, which isn't much text.
+        err.caret = ''
+        raise err
+    addresses.append(address_name)
 
 def _find_all_commands_in_file(path, file_lines, valid_commands, source_root_dir):
     labels = {} # dict of {name: line}.
+    addresses = [] # list of addresses.
+    address_resolutions = {}
     cmd_path = path
     declared_files = set()
     commands = defaultdict(dict)
     paren_balance = 0
     region_start = TextPoint(0, 0)
 
     for region_start.line in range(len(file_lines)):
         line = file_lines[region_start.line]
for region_start.line in range(len(file_lines)):
                 break  # Read next line.
 
             # Parens are balanced, we have a full command to evaluate.
             raw_text = "".join(cmd_text_list)
             try:
                 command = _build_command(
                     valid_commands[command_name],
                     labels,
+                    addresses,
                     raw_text,
                     cmd_path,
                     cmd_point.get_lineno(),
                 )
             except SyntaxError as e:
                 # This err should point to the problem line.
                 err_point = copy(cmd_point)
                 # To e the command start is the absolute start, so use as offset.
                 err_point.line += e.lineno - 1 # e.lineno is a position, not index.
                 err_point.char += e.offset - 1 # e.offset is a position, not index.
                 raise format_parse_err(e.msg, path, file_lines, err_point)
             except TypeError as e:
                 # This err should always point to the end of the command name.
                 err_point = copy(cmd_point)
                 err_point.char += len(command_name)
                 raise format_parse_err(str(e), path, file_lines, err_point)
             else:
                 if type(command) is DexLabel:
                     add_line_label(labels, command, path, cmd_point.get_lineno())
+                elif type(command) is DexDeclareAddress:
+                    add_address(addresses, command, path, cmd_point.get_lineno())
+                    command.address_resolutions = address_resolutions
                 elif type(command) is DexDeclareFile:
                     cmd_path = command.declared_file
                     if not os.path.isabs(cmd_path):
                         source_dir = (source_root_dir if source_root_dir else
                                       os.path.dirname(path))
                         cmd_path = os.path.join(source_dir, cmd_path)
                     # TODO: keep stored paths as PurePaths for 'longer'.
                     cmd_path = str(PurePath(cmd_path))
                     declared_files.add(cmd_path)
+                elif isinstance(command, DexExpectWatchBase):
+                    command.address_resolutions = address_resolutions
                 assert (path, cmd_point) not in commands[command_name], (
                     command_name, commands[command_name])
                 commands[command_name][path, cmd_point] = command
 
     if paren_balance != 0:
         # This err should always point to the end of the command name.
         err_point = copy(cmd_point)
         err_point.char += len(command_name)

cross-project-tests/debuginfo-tests/dexter/dex/command/commands/DexDeclareAddress.py

+# DExTer : Debugging Experience Tester
+# ~~~~~~   ~         ~~         ~   ~~
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+"""Commmand sets the path for all following commands to 'declared_file'.
+"""
+
+import os
+
+from dex.command.CommandBase import CommandBase, StepExpectInfo
+
+class DexDeclareAddress(CommandBase):
+    def __init__(self, addr_name, expression, **kwargs):
+
+        if not isinstance(addr_name, str):
+            raise TypeError('invalid argument type')
+
+        self.addr_name = addr_name
+        self.expression = expression
+        self.on_line = kwargs.pop('on_line')
+        self.hit_count = kwargs.pop('hit_count', 0)
+
+        self.address_resolutions = None
+
+        super(DexDeclareAddress, self).__init__()
+
+    @staticmethod
+    def get_name():
+        return __class__.__name__
+
+    def get_watches(self):
+        return [StepExpectInfo(self.expression, self.path, 0, range(self.on_line, self.on_line + 1))]
+
+    def get_address_name(self):
+        return self.addr_name
+
+    def eval(self, step_collection):
+        assert os.path.exists(self.path)
+        self.address_resolutions[self.get_address_name()] = None
+        for step in step_collection.steps:
+            loc = step.current_location
+
+            if (loc.path and os.path.exists(loc.path) and
+                os.path.samefile(loc.path, self.path) and
+                loc.lineno == self.on_line):
+                if self.hit_count > 0:
+                    self.hit_count -= 1
+                    continue
+                try:
+                    watch = step.program_state.frames[0].watches[self.expression]
+                except KeyError:
+                    pass
+                else:
+                    hex_val = int(watch.value, 16)
+                    self.address_resolutions[self.get_address_name()] = hex_val
+                    break

cross-project-tests/debuginfo-tests/dexter/dex/command/commands/DexExpectWatchBase.py

 import abc
 import difflib
 import os
 from collections import namedtuple
 
 from dex.command.CommandBase import CommandBase, StepExpectInfo
 from dex.command.StepValueInfo import StepValueInfo
 
-
+class AddressExpression(object):
+    def __init__(self, name, offset=0):
+        self.name = name
+        self.offset = offset
+
+    def is_resolved(self, resolutions):
+        return self.name in resolutions
+
+    # Given the resolved value of the address, resolve the final value of
+    # this expression.
+    def resolved_value(self, resolutions):
+        if not self.name in resolutions or resolutions[self.name] is None:
+            return None
+        # Technically we should fill(8) if we're debugging on a 32bit architecture?
+        return "0x" + hex(resolutions[self.name] + self.offset)[2:].zfill(16)
+
+    # Given the final value of this expression, determine the resolved value of
+    # the address that would produce that value.
+    def inverse_resolve(self, resolved_value):
+        return int(resolved_value, 16) - self.offset
+
+def resolved_value(value, resolutions):
+    return value.resolved_value(resolutions) if isinstance(value, AddressExpression) else value
+
+def describe_value(value):
+    if isinstance(value, AddressExpression):
+        offset = ""
+        if value.offset > 0:
+            offset = f"+{value.offset}"
+        elif value.offset < 0:
+            offset = str(value.offset)
+        return f"address '{value.name}'{offset}"
+    return value
 
 class DexExpectWatchBase(CommandBase):
     def __init__(self, *args, **kwargs):
         if len(args) < 2:
             raise TypeError('expected at least two args')
 
         self.expression = args[0]
-        self.values = [str(arg) for arg in args[1:]]
+        self.values = [arg if isinstance(arg, AddressExpression) else str(arg) for arg in args[1:]]
         try:
             on_line = kwargs.pop('on_line')
             self._from_line = on_line
             self._to_line = on_line
         except KeyError:
             self._from_line = kwargs.pop('from_line', 1)
             self._to_line = kwargs.pop('to_line', 999999)
         self._require_in_order = kwargs.pop('require_in_order', True)
         if kwargs:
             raise TypeError('unexpected named args: {}'.format(
                 ', '.join(kwargs)))
 
         # Number of times that this watch has been encountered.
         self.times_encountered = 0
 
         # We'll pop from this set as we encounter values so anything left at
         # the end can be considered as not having been seen.
         self._missing_values = set(self.values)
 
def __init__(self, *args, **kwargs):
         # List of StepValueInfos for any watch that is encountered that has an
         # expected value.
         self.expected_watches = []
 
         # List of StepValueInfos for any watch that is encountered that has an
         # unexpected value.
         self.unexpected_watches = []
 
+        # List of StepValueInfos for all observed watches that were not
+        # invalid, irretrievable, or optimized out (combines expected and
+        # unexpected).
+        self.observed_watches = []
+
+        # dict of address names to their final resolved values, None until it
+        # gets assigned externally.
+        self.address_resolutions = None
+
         super(DexExpectWatchBase, self).__init__()
 
 
     def get_watches(self):
         return [StepExpectInfo(self.expression, self.path, 0, range(self._from_line, self._to_line + 1))]
 
     @property
     def line_range(self):
         return list(range(self._from_line, self._to_line + 1))
 
     @property
     def missing_values(self):
-        return sorted(list(self._missing_values))
+        return sorted(list(describe_value(v) for v in self._missing_values))
 
     @property
     def encountered_values(self):
-        return sorted(list(set(self.values) - self._missing_values))
+        return sorted(list(set(resolved_value(v, self.address_resolutions) for v in set(self.values) - self._missing_values)))
+
+    @property
+    def unresolved_addresses(self):
+        return [value for value in self.values if isinstance(value, AddressExpression) and value.name not in self.address_resolutions]
+
+    @property
+    def used_address_names(self):
+        return [value.name for value in self.values if isinstance(value, AddressExpression)]
 
     @abc.abstractmethod
     def _get_expected_field(self, watch):
         """Return a field from watch that this ExpectWatch command is checking.
         """
 
     def _handle_watch(self, step_info):
         self.times_encountered += 1
 
         if not step_info.watch_info.could_evaluate:
             self.invalid_watches.append(step_info)
             return
 
         if step_info.watch_info.is_optimized_away:
             self.optimized_out_watches.append(step_info)
             return
 
         if step_info.watch_info.is_irretrievable:
             self.irretrievable_watches.append(step_info)
             return
 
-        if step_info.expected_value not in self.values:
+        # Check to see if this value matches with a resolved address.
+        matching_address = None
+        for v in self.values:
+            if (isinstance(v, AddressExpression) and
+                    v.name in self.address_resolutions and
+                    v.resolved_value(self.address_resolutions) == step_info.expected_value):
+                matching_address = v
+                break
+
+        # If this is not an expected value, either a direct value or an address,
+        # then this is an unexpected watch.
+        if step_info.expected_value not in self.values and matching_address is None:
             self.unexpected_watches.append(step_info)
             return
 
         self.expected_watches.append(step_info)
+        value_to_remove = matching_address if matching_address is not None else step_info.expected_value
         try:
-            self._missing_values.remove(step_info.expected_value)
+            self._missing_values.remove(value_to_remove)
         except KeyError:
             pass
 
     def _check_watch_order(self, actual_watches, expected_values):
         """Use difflib to figure out whether the values are in the expected order
         or not.
         """
         differences = []
def eval(self, step_collection):
             # A list of all watches where the value has changed.
             value_change_watches = []
             prev_value = None
             for watch in self.expected_watches:
                 if watch.expected_value != prev_value:
                     value_change_watches.append(watch)
                     prev_value = watch.expected_value
 
+            resolved_values = [resolved_value(v, self.address_resolutions) for v in self.values]
             self.misordered_watches = self._check_watch_order(
                 value_change_watches, [
-                    v for v in self.values if v in
+                    v for v in resolved_values if v in
                     [w.expected_value for w in self.expected_watches]
                 ])

cross-project-tests/debuginfo-tests/dexter/dex/heuristic/Heuristic.py

 # DExTer : Debugging Experience Tester
 # ~~~~~~   ~         ~~         ~   ~~
 #
 # Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 # See https://llvm.org/LICENSE.txt for license information.
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 """Calculate a 'score' based on some dextIR.
 Assign penalties based on different commands to decrease the score.
 1.000 would be a perfect score.
 0.000 is the worst theoretical score possible.
 """
 
 from collections import defaultdict, namedtuple, Counter
 import difflib
 import os
 from itertools import groupby
def __init__(self, context, steps):
 
         worst_penalty = max([
             self.penalty_variable_optimized, self.penalty_irretrievable,
             self.penalty_not_evaluatable, self.penalty_incorrect_values,
             self.penalty_missing_values, self.penalty_unreachable,
             self.penalty_missing_step, self.penalty_misordered_steps
         ])
 
+        # Before evaluating scoring commands, evaluate address values.
+        try:
+            for command in steps.commands['DexDeclareAddress']:
+                command.eval(steps)
+        except KeyError:
+            pass
+
         # Get DexExpectWatchType results.
         try:
             for command in steps.commands['DexExpectWatchType']:
                 command.eval(steps)
                 maximum_possible_penalty = min(3, len(
                     command.values)) * worst_penalty
                 name, p = self._calculate_expect_watch_penalties(
                     command, maximum_possible_penalty)

cross-project-tests/debuginfo-tests/dexter/feature_tests/commands/perfect/dex_declare_address/address_after_ref.cpp

+// Purpose:
+//      Test that a \DexDeclareAddress value can have its value defined after
+//      the first reference to that value.
+//
+// REQUIRES: system-linux
+//
+// RUN: %dexter_regression_test -- %s | FileCheck %s
+// CHECK: address_after_ref.cpp
+
+int main() {
+    int *x = new int(5);
+    int *y = x; // DexLabel('first_line')
+    delete x; // DexLabel('last_line')
+}
+
+// DexDeclareAddress('y', 'y', on_line=ref('last_line'))
+// DexExpectWatchValue('x', address('y'), on_line=ref('first_line'))

cross-project-tests/debuginfo-tests/dexter/feature_tests/commands/perfect/dex_declare_address/expression_address.cpp

+// Purpose:
+//      Test that a \DexDeclareAddress value can be used to compare the
+//      addresses of two local variables that refer to the same address.
+//
+// REQUIRES: system-linux
+//
+// RUN: %dexter_regression_test -- %s | FileCheck %s
+// CHECK: expression_address.cpp
+
+int main() {
+    int x = 5;
+    int &y = x;
+    x = 3; // DexLabel('test_line')
+}
+
+// DexDeclareAddress('x_addr', '&x', on_line=ref('test_line'))
+// DexExpectWatchValue('&x', address('x_addr'), on_line=ref('test_line'))
+// DexExpectWatchValue('&y', address('x_addr'), on_line=ref('test_line'))

cross-project-tests/debuginfo-tests/dexter/feature_tests/commands/perfect/dex_declare_address/identical_address.cpp

+// Purpose:
+//      Test that a \DexDeclareAddress value can be used to compare two equal
+//      pointer variables.
+//
+// REQUIRES: system-linux
+//
+// RUN: %dexter_regression_test -- %s | FileCheck %s
+// CHECK: identical_address.cpp
+
+int main() {
+    int *x = new int(5);
+    int *y = x;
+    delete x; // DexLabel('test_line')
+}
+
+// DexDeclareAddress('x', 'x', on_line=ref('test_line'))
+// DexExpectWatchValue('x', address('x'), on_line=ref('test_line'))
+// DexExpectWatchValue('y', address('x'), on_line=ref('test_line'))

cross-project-tests/debuginfo-tests/dexter/feature_tests/commands/perfect/dex_declare_address/multiple_address.cpp

+// Purpose:
+//      Test that multiple \DexDeclareAddress references that point to different
+//      addresses can be used within a single \DexExpectWatchValue.
+//
+// REQUIRES: system-linux
+//
+// RUN: %dexter_regression_test -- %s | FileCheck %s
+// CHECK: multiple_address.cpp
+
+int main() {
+    int *x = new int(5);
+    int *y = new int(4);
+    int *z = x;
+    *z = 0; // DexLabel('start_line')
+    z = y;
+    *z = 0;
+    delete x; // DexLabel('end_line')
+    delete y;
+}
+
+// DexDeclareAddress('x', 'x', on_line=ref('start_line'))
+// DexDeclareAddress('y', 'y', on_line=ref('start_line'))
+// DexExpectWatchValue('z', address('x'), address('y'), from_line=ref('start_line'), to_line=ref('end_line'))
+// DexExpectWatchValue('*z', 5, 0, 4, 0, from_line=ref('start_line'), to_line=ref('end_line'))

cross-project-tests/debuginfo-tests/dexter/feature_tests/commands/perfect/dex_declare_address/offset_address.cpp

+// Purpose:
+//      Test that a \DexDeclareAddress value can be used to compare two pointer
+//      variables that have a fixed offset between them.
+//
+// REQUIRES: system-linux
+//
+// RUN: %dexter_regression_test -- %s | FileCheck %s
+// CHECK: offset_address.cpp
+
+int main() {
+    int *x = new int[5];
+    int *y = x + 3;
+    delete x; // DexLabel('test_line')
+}
+
+// DexDeclareAddress('x', 'x', on_line=ref('test_line'))
+// DexExpectWatchValue('x', address('x'), on_line=ref('test_line'))
+// DexExpectWatchValue('y', address('x', 12), on_line=ref('test_line'))

cross-project-tests/debuginfo-tests/dexter/feature_tests/commands/perfect/dex_declare_address/self_comparison.cpp

+// Purpose:
+//      Test that a \DexDeclareAddress value can be used to check the change in
+//      value of a variable over time, relative to its initial value.
+//
+// REQUIRES: system-linux
+//
+// RUN: %dexter_regression_test -- %s | FileCheck %s
+// CHECK: self_comparison.cpp
+
+int main() {
+    int *x = new int[3];
+    for (int *y = x; y < x + 3; ++y)
+      *y = 0; // DexLabel('test_line')
+    delete x;
+}
+
+// DexDeclareAddress('y', 'y', on_line=ref('test_line'))
+// DexExpectWatchValue('y', address('y'), address('y', 4), address('y', 8), on_line=ref('test_line'))

cross-project-tests/debuginfo-tests/dexter/feature_tests/subtools/test/err_duplicate_address.cpp

+// Purpose:
+//      Check that declaring duplicate addresses gives a useful error message.
+//
+// RUN: not %dexter_regression_test -v -- %s | FileCheck %s --match-full-lines
+
+
+int main() {
+    int *result = new int(0);
+    delete result; // DexLabel('test_line')
+}
+
+// CHECK: parser error:{{.*}}err_duplicate_address.cpp([[# @LINE + 4]]): Found duplicate address: 'oops'
+// CHECK-NEXT: {{Dex}}DeclareAddress('oops', 'result', on_line=ref('test_line'))
+
+// DexDeclareAddress('oops', 'result', on_line=ref('test_line'))
+// DexDeclareAddress('oops', 'result', on_line=ref('test_line'))

cross-project-tests/debuginfo-tests/dexter/feature_tests/subtools/test/err_undeclared_addr.cpp

+// Purpose:
+//      Check that using an undeclared address gives a useful error message.
+//
+// RUN: not %dexter_regression_test -v -- %s | FileCheck %s --match-full-lines
+
+
+int main() {
+    int *result = new int(0);
+    delete result; // DexLabel('test_line')
+}
+
+
+// CHECK: parser error:{{.*}}err_undeclared_addr.cpp([[# @LINE + 3]]): Undeclared address: 'result'
+// CHECK-NEXT: {{Dex}}ExpectWatchValue('result', address('result'), on_line=ref('test_line'))
+
+// DexExpectWatchValue('result', address('result'), on_line=ref('test_line'))