4507

New helper: compare a null-terminated string (from argv) with a length-prefixed
string (anywhere else).

As long as ex11 continues to pass we can copy the function and its tests
to other programs.

2 files changed, 304 insertions, 0 deletions

diff --git a/subx/examples/ex11 b/subx/examples/ex11
new file mode 100644
index 00000000..fb11d1b6
--- /dev/null
+++ b/subx/examples/ex11
Binary files differdiff --git a/subx/examples/ex11.subx b/subx/examples/ex11.subx
new file mode 100644
index 00000000..460c3430
--- /dev/null
+++ b/subx/examples/ex11.subx
@@ -0,0 +1,304 @@
+## Null-terminated vs length-prefixed ascii strings.
+#
+# By default we create strings with a 4-byte length prefix rather than a null suffix.
+# However, commandline arguments come null-prefixed from the Linux kernel.
+# This example shows a helper that can compare a commandline argument with the
+# (length-prefixed) literal string "target".
+#
+# To run:
+#   $ subx translate ex11.subx ex11
+#   $ subx run ex11  # runs a series of tests
+#   ......  # all tests pass
+#
+# (We can't yet run the tests when given a "test" commandline argument,
+# because checking for it would require the function being tested! Breakage
+# would cause tests to not run, rather than to fail as we'd like.)
+
+== code
+# instruction                     effective address                                                   operand     displacement    immediate
+# op          subop               mod             rm32          base        index         scale       r32
+# 1-3 bytes   3 bits              2 bits          3 bits        3 bits      3 bits        2 bits      2 bits      0/1/2/4 bytes   0/1/2/4 bytes
+
+# main:
+  e8/call  run_tests/disp32  # 'run_tests' is a function created automatically by SubX. It calls all functions that start with 'test_'.
+  # exit(EAX)
+  89/copy                         3/mod/direct    3/rm32/EBX    .           .             .           0/r32/EAX   .               .                 # copy EAX to EBX
+  b8/copy                         .               .             .           .             .           .           .               1/imm32           # copy 1 to EAX
+  cd/syscall  0x80/imm8
+
+# compare a null-terminated ascii string with a more idiomatic length-prefixed byte array
+# reason for the name: the only place we should have null-terminated ascii strings is from commandline args
+argv_equal:  # s : null-terminated ascii string, benchmark : length-prefixed ascii string -> EAX : boolean
+  # pseudocode:
+  #   initialize n = b.length
+  #   initialize s1 = s
+  #   initialize s2 = b.data
+  #   i = 0
+  #   for (i = 0; i < n; ++n)
+  #     c1 = *s1
+  #     c2 = *s2
+  #     if c1 == 0
+  #       return false
+  #     if c1 != c2
+  #       return false
+  #   return *s1 == 0
+
+  # initialize s into EDI
+  8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none  .           7/r32/EDI   8/disp8         .                 # copy *(ESP+8) to EDI
+  # initialize benchmark length n into EDX
+  8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none  .           2/r32/EDX   4/disp8         .                 # copy *(ESP+4) to EDX
+  8b/copy                         0/mod/indirect  2/rm32/EDX    .           .             .           2/r32/EDX   .               .                 # copy *EDX to EDX
+  # initialize benchmark data into ESI
+  8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none  .           6/r32/ESI   4/disp8         .                 # copy *(ESP+4) to ESI
+  81          0/subop/add         3/mod/direct    6/rm32/ESI    .           .             .           .           .               4/imm32           # add 4 to ESI
+  # initialize loop counter i into ECX
+  b9/copy                         .               .             .           .             .           .           .               0/imm32/exit      # copy 1 to ECX
+  # while (i/ECX < n/EDX)
+$argv_loop:
+  39/compare                      3/mod/direct    1/rm32/ECX    .           .             .           2/r32/EDX   .               .                 # compare ECX with EDX
+  74/jump-if-equal  $argv_break/disp8
+    # c1/EAX, c2/EBX = *s, *benchmark
+  b8/copy  0/imm32  # clear EAX
+  8a/copy                         0/mod/indirect  7/rm32/EDI    .           .             .           0/r32/EAX   .               .                 # copy byte at *EDI to lower byte of EAX
+  bb/copy  0/imm32  # clear EBX
+  8a/copy                         0/mod/indirect  6/rm32/ESI    .           .             .           3/r32/EBX   .               .                 # copy byte at *ESI to lower byte of EBX
+    # if (c1 == 0) return false
+  3d/compare                      .               .             .           .             .           .           .               0/imm32           # compare EAX with 0
+  74/jump-if-equal  $argv_fail/disp8
+    # if (c1 != c2) return false
+  39/compare                      3/mod/direct    0/rm32/EAX    .           .             .           3/r32/EBX   .               .                 # compare EAX with EBX
+  75/jump-if-not-equal  $argv_fail/disp8
+    # ++s1, ++s2, ++i
+  41/inc-ECX
+  46/inc-ESI
+  47/inc-EDI
+  # end while
+  eb/jump  $argv_loop/disp8
+$argv_break:
+  # if (*s/EDI == 0) return true
+  b8/copy  0/imm32  # clear EAX
+  8a/copy                         0/mod/indirect  7/rm32/EDI    .           .             .           0/r32/EAX   .               .                 # copy byte at *EDI to lower byte of EAX
+  81          7/subop/compare     3/mod/direct    0/rm32/EAX    .           .             .           .           .               0/imm32           # compare EAX with 0
+  75/jump-if-not-equal  $argv_fail/disp8
+  b8/copy                         .               .             .           .             .           .           .               1/imm32           # copy 1 to EAX
+  c3/return
+  # return false
+$argv_fail:
+  b8/copy                         .               .             .           .             .           .           .               0/imm32           # copy 0 to EAX
+  c3/return
+
+## tests
+
+test_compare_null_argv_with_empty_array:
+  # EAX = argv_equal(Null_argv, "")
+    # push args
+  68/push  Null_argv/imm32
+  68/push  ""/imm32
+    # call
+  e8/call  argv_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add 8 to ESP
+  # call check_ints_equal(EAX, 1)
+  50/push-EAX
+  68/push  1/imm32/true
+  68/push  "F - test_compare_null_argv_with_empty_array"/imm32
+    # call
+  e8/call  check_ints_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add 12 to ESP
+  c3/return
+
+test_compare_null_argv_with_non_empty_array:
+  # EAX = argv_equal(Null_argv, "Abc")
+    # push args
+  68/push  Null_argv/imm32
+  68/push  "Abc"/imm32
+    # call
+  e8/call  argv_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add 8 to ESP
+  # call check_ints_equal(EAX, 0)
+  50/push-EAX
+  68/push  0/imm32/false
+  68/push  "F - test_compare_null_argv_with_non_empty_array"/imm32
+    # call
+  e8/call  check_ints_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add 12 to ESP
+  c3/return
+
+test_compare_argv_with_equal_array:
+  # EAX = argv_equal(Abc_argv, "Abc")
+    # push args
+  68/push  Abc_argv/imm32
+  68/push  "Abc"/imm32
+    # call
+  e8/call  argv_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add 8 to ESP
+  # call check_ints_equal(EAX, 1)
+  50/push-EAX
+  68/push  1/imm32/true
+  68/push  "F - test_compare_argv_with_equal_array"/imm32
+    # call
+  e8/call  check_ints_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add 12 to ESP
+  c3/return
+
+test_compare_argv_with_inequal_array:
+  # EAX = argv_equal(Abc_argv, "Adc")
+    # push args
+  68/push  Abc_argv/imm32
+  68/push  "Adc"/imm32
+    # call
+  e8/call  argv_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add 8 to ESP
+  # call check_ints_equal(EAX, 0)
+  50/push-EAX
+  68/push  0/imm32/false
+  68/push  "F - test_compare_argv_with_equal_array"/imm32
+    # call
+  e8/call  check_ints_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add 12 to ESP
+  c3/return
+
+test_compare_argv_with_empty_array:
+  # EAX = argv_equal(Abc_argv, "")
+    # push args
+  68/push  Abc_argv/imm32
+  68/push  ""/imm32
+    # call
+  e8/call  argv_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add 8 to ESP
+  # call check_ints_equal(EAX, 0)
+  50/push-EAX
+  68/push  0/imm32/false
+  68/push  "F - test_compare_argv_with_equal_array"/imm32
+    # call
+  e8/call  check_ints_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add 12 to ESP
+  c3/return
+
+test_compare_argv_with_shorter_array:
+  # EAX = argv_equal(Abc_argv, "Ab")
+    # push args
+  68/push  Abc_argv/imm32
+  68/push  "Ab"/imm32
+    # call
+  e8/call  argv_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add 8 to ESP
+  # call check_ints_equal(EAX, 0)
+  50/push-EAX
+  68/push  0/imm32/false
+  68/push  "F - test_compare_argv_with_shorter_array"/imm32
+    # call
+  e8/call  check_ints_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add 12 to ESP
+  c3/return
+
+test_compare_argv_with_longer_array:
+  # EAX = argv_equal(Abc_argv, "Abcd")
+    # push args
+  68/push  Abc_argv/imm32
+  68/push  "Abcd"/imm32
+    # call
+  e8/call  argv_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add 8 to ESP
+  # call check_ints_equal(EAX, 0)
+  50/push-EAX
+  68/push  0/imm32/false
+  68/push  "F - test_compare_argv_with_longer_array"/imm32
+    # call
+  e8/call  check_ints_equal/disp32
+    # discard args
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add 12 to ESP
+  c3/return
+
+## helpers
+
+# print msg to stderr if a != b, otherwise print "."
+check_ints_equal:  # (a : int, b : int, msg : (address array byte)) -> boolean
+  # load args into EAX, EBX and ECX
+  8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none  .           0/r32/EAX   0xc/disp8       .                 # copy *(ESP+12) to EAX
+  8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none  .           3/r32/EBX   0x8/disp8       .                 # copy *(ESP+8) to EBX
+  # if EAX == b/EBX
+  39/compare                      3/mod/direct    0/rm32/EAX    .           .             .           3/r32/EBX   .               .                 # compare EAX and EBX
+  75/jump-if-unequal  $check_ints_equal:else/disp8
+    # print('.')
+      # push args
+  68/push  "."/imm32
+      # call
+  e8/call  write_stderr/disp32
+      # discard arg
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add 4 to ESP
+    # return
+  c3/return
+  # else:
+$check_ints_equal:else:
+  # copy msg into ECX
+  8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/ESP  4/index/none  .           1/r32/ECX   4/disp8         .                 # copy *(ESP+4) to ECX
+    # print(ECX)
+      # push args
+  51/push-ECX
+      # call
+  e8/call  write_stderr/disp32
+      # discard arg
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add 4 to ESP
+    # print newline
+      # push args
+  68/push  Newline/imm32
+      # call
+  e8/call  write_stderr/disp32
+      # discard arg
+  81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add 4 to ESP
+  # end
+  c3/return
+
+write_stderr:  # s : (address array byte) -> <void>
+  # save registers
+  50/push-EAX
+  51/push-ECX
+  52/push-EDX
+  53/push-EBX
+  # write(2/stderr, (data) s+4, (size) *s)
+    # fd = 2 (stderr)
+  bb/copy                         .               .             .           .             .           .           .               2/imm32           # copy 2 to EBX
+    # x = s+4
+  8b/copy                         1/mod/*+disp8   4/rm32/SIB    4/base/ESP  4/index/none  .           1/r32/ECX   0x14/disp8      .                 # copy *(ESP+20) to ECX
+  81          0/subop/add         3/mod/direct    1/rm32/ECX    .           .             .           .           .               4/imm32           # add 4 to ECX
+    # size = *s
+  8b/copy                         1/mod/*+disp8   4/rm32/SIB    4/base/ESP  4/index/none  .           2/r32/EDX   0x14/disp8      .                 # copy *(ESP+20) to EDX
+  8b/copy                         0/mod/indirect  2/rm32/EDX    .           .             .           2/r32/EDX   .               .                 # copy *EDX to EDX
+    # call write()
+  b8/copy                         .               .             .           .             .           .           .               4/imm32/write     # copy 1 to EAX
+  cd/syscall  0x80/imm8
+  # restore registers
+  5b/pop-EBX
+  5a/pop-EDX
+  59/pop-ECX
+  58/pop-EAX
+  # end
+  c3/return
+
+== data
+Newline:
+  # size
+  01 00 00 00
+  # data
+  0a/newline
+
+# for argv_equal tests
+Null_argv:
+  00/null
+Abc_argv:
+  41/A 62/b 63/c 00/null
+
+# vim:ft=subx:nowrap:so=0