src/gifs/lainchan/se7en-site.png

# stop: dependency-injected wrapper around the exit() syscall
#
# We'd like to be able to write tests for functions that call exit(), and to
# make assertions about whether they exit() or not in a given situation. To
# achieve this we'll call exit() via a smarter wrapper called 'stop'.
#
# In the context of a test, calling a function X that calls 'stop' (directly
# or through further intervening calls) will unwind the stack until X returns,
# so that we can say check any further assertions after the execution of X. To
# achieve this end, we'll pass the return address of X as a 'target' argument
# into X, plumbing it through to 'stop'. When 'stop' gets a non-null target it
# unwinds the stack until the target. If it gets a null target it calls
# exit().
#
# We'd also like to get the exit status out of 'stop', so we'll combine the
# input target with an output status parameter into a type called 'exit-descriptor'.
#
# So the exit-descriptor looks like this:
#   target: address  # return address for 'stop' to unwind to
#   value: int  # exit status stop was called with
#
# 'stop' thus takes two parameters: an exit-descriptor and the exit status.
#
# 'stop' won't bother cleaning up any other processor state besides the stack,
# such as registers. Only esp will have a well-defined value after 'stop'
# returns. (This is a poor man's setjmp/longjmp, if you know what that is.)
#
# Before you can call any function that may call 'stop', you need to pass in an
# exit-descriptor to it. To create an exit-descriptor use 'tailor-exit-descriptor'
# below. It's not the most pleasant abstraction in the world.
#
# An exit-descriptor's target is its input, computed during 'tailor-exit-descriptor'.
# Its value is its output, computed during stop and available to the test.

== code
#   instruction                     effective address                                                   register    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

# Configure an exit-descriptor for a call pushing 'nbytes' bytes of args to
# the stack.
# Ugly that we need to know the size of args. Don't allocate variables between
# tailor-exit-descriptor and the call it's for.
tailor-exit-descriptor:  # ed: (addr exit-descriptor), nbytes: int
    # . prologue
    55/push-ebp
    89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
    # . save registers
    50/push-eax
    51/push-ecx
    # eax = nbytes
    8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           0/r32/eax   0xc/disp8       .                 # copy *(ebp+12) to eax
    # Let X be the value of esp in the caller, before the call to tailor-exit-descriptor.
    # The return address for a call in the caller's body will be at:
    #   X-8 if the caller takes 4 bytes of args for the exit-descriptor (add 4 bytes for the return address)
    #   X-12 if the caller takes 8 bytes of args
    #   ..and so on
    # That's the value we need to return: X-nbytes-4
    #
    # However, we also need to account for the perturbance to esp caused by the
    # call to tailor-exit-descriptor. It pushes 8 bytes of args followed by 4
    # bytes for the return address and 4 bytes to push ebp above.
    # So ebp at this point is X-16.
    #
    # So the return address for the next call in the caller is:
    #   ebp+8 if the caller takes 4 bytes of args
    #   ebp+4 if the caller takes 8 bytes of args
    #   ebp if the caller takes 12 bytes of args
    #   ebp-4 if the caller takes 16 bytes of args
    #   ..and so on
    # That's ebp+12-nbytes.
    # option 1: 6 + 3 bytes
#?     2d/subtract                     3/mod/direct    0/rm32/eax    .           .             .           .           .               8/imm32           # subtract from eax
#?     8d/copy-address                 0/mod/indirect  4/rm32/sib    5/base/ebp  0/index/eax   .           0/r32/eax   .               .                 # copy ebp+eax to eax
    # option 2: 2 + 4 bytes
    f7          3/subop/negate      3/mod/direct    0/rm32/eax    .           .             .           .           .               .                 # negate eax
    8d/copy-address                 1/mod/*+disp8   4/rm32/sib    5/base/ebp  0/index/eax   .           0/r32/eax   0xc/disp8         .               # copy ebp+eax+12 to eax
    # copy eax to ed->target
    8b/copy                         1/mod/*+disp8   5/rm32/ebp    .           .             .           1/r32/ecx   8/disp8         .                 # copy *(ebp+8) to ecx
    89/copy                         0/mod/indirect  1/rm32/ecx    .           .             .           0/r32/eax   .               .                 # copy eax to *ecx
    # initialize ed->value
    c7          0/subop/copy        1/mod/*+disp8   1/rm32/ecx    .           .             .           .           4/disp8         0/imm32           # copy to *(ecx+4)
$tailor-exit-descriptor:end:
    # . restore registers
    59/pop-to-ecx
    58/pop-to-eax
    # . epilogue
    89/copy                         3/mod/direct    4/rm32/esp    .           .             .           5/r32/ebp   .               .                 # copy ebp to esp
    5d/pop-to-ebp
    c3/return

stop:  # ed: (addr exit-descriptor), value: int
    # no prologue; one way or another, we're going to clobber registers
    # eax = ed
    8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/esp  4/index/none  .           0/r32/eax   4/disp8         .                 # copy *(esp+4) to eax
    # if (ed->target == 0) really exit
    81          7/subop/compare     0/mod/indirect  0/rm32/eax    .           .             .           .           .               0/imm32           # compare *eax
    75/jump-if-!=  $stop:fake/disp8
    # . syscall(exit, value)
    8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/esp  4/index/none  .           3/r32/ebx   8/disp8         .                 # copy *(esp+8) to ebx
    b8/copy-to-eax  1/imm32/exit
    cd/syscall  0x80/imm8
$stop:fake:
    # otherwise:
    # ed->value = value+1
    8b/copy                         1/mod/*+disp8   4/rm32/sib    4/base/esp  4/index/none  .           1/r32/ecx   8/disp8         .                 # copy *(esp+8) to ecx
    41/increment-ecx
    89/copy                         1/mod/*+disp8   0/rm32/eax    .           .             .           1/r32/ecx   4/disp8         .                 # copy ecx to *(eax+4)
    # perform a non-local jump to ed->target
    8b/copy                         0/mod/indirect  0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy *eax to esp
$stop:end:
    c3/return  # doesn't return to caller

test-stop-skips-returns-on-exit:
    # This looks like the standard prologue, but is here for different reasons.
    # A function calling 'stop' can't rely on ebp persisting past the call.
    #
    # Use ebp here as a stable base to refer to locals and arguments from in the
    # presence of push/pop/call instructions.
    # *Don't* use ebp as a way to restore esp.
    55/push-ebp
    89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
    # Make room for an exit descriptor on the stack. That's almost always the
    # right place for it, available only as long as it's legal to use. Once this
    # containing function returns we'll need a new exit descriptor.
    # var ed/eax: exit-descriptor
    68/push  0/imm32
    68/push  0/imm32
    89/copy                         3/mod/direct    0/rm32/eax    .           .             .           4/r32/esp   .               .                 # copy esp to eax
    # Size the exit-descriptor precisely for the next call below, to _test-stop-1.
    # tailor-exit-descriptor(ed, 4)
    # . . push args
    68/push  4/imm32/nbytes-of-args-for-_test-stop-1
    50/push-eax
    # . . call
    e8/call  tailor-exit-descriptor/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
    # . _test-stop-1(ed)
    # . . push args
    50/push-eax
    # . . call
    e8/call  _test-stop-1/disp32
    # registers except esp may be clobbered at this point
    # restore args
    58/pop-to-eax
    # check that _test-stop-1 tried to call exit(1)
    # . check-ints-equal(ed->value, 2, msg)  # i.e. stop was called with value 1
    # . . push args
    68/push  "F - test-stop-skips-returns-on-exit"/imm32
    68/push  2/imm32
    # . . push ed->value
    ff          6/subop/push        1/mod/*+disp8   0/rm32/eax    .           .             .           .           4/disp8         .                 # push *(eax+4)
    # . . call
    e8/call  check-ints-equal/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               0xc/imm32         # add to esp
    # . epilogue
    # don't restore esp from ebp; manually reclaim locals
    81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               8/imm32           # add to esp
    5d/pop-to-ebp
    c3/return

_test-stop-1:  # ed: (addr exit-descriptor)
    # . prologue
    55/push-ebp
    89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
    # _test-stop-2(ed)
    # . . push args
    ff          6/subop/push        1/mod/*+disp8   5/rm32/ebp    .           .             .           .           8/disp8         .                 # push *(ebp+8)
    # . . call
    e8/call  _test-stop-2/disp32
    # should never get past this point
$_test-stop-1:dead-end:
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               4/imm32           # add to esp
    # signal test failed: check-ints-equal(1, 0, msg)
    # . . push args
    68/push  "F - test-stop-skips-returns-on-exit"/imm32
    68/push  0/imm32
    68/push  1/imm32
    # . . call
    e8/call  check-ints-equal/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/esp    .           .             .           .           .               0xc/imm32         # add to esp
    # . epilogue
    89/copy                         3/mod/direct    4/rm32/esp    .           .             .           5/r32/ebp   .               .                 # copy ebp to esp
    5d/pop-to-ebp
    c3/return

_test-stop-2:  # ed: (addr exit-descriptor)
    # . prologue
    55/push-ebp
    89/copy                         3/mod/direct    5/rm32/ebp    .           .             .           4/r32/esp   .               .                 # copy esp to ebp
    # . stop(ed, 1)
    # . . push args
    68/push  1/imm32
    ff          6/subop/push        1/mod/*+disp8   5/rm32/ebp    .           .             .           .           8/disp8         .                 # push *(ebp+8)
    # . . call
    e8/call  stop/disp32
    # should never get past this point
$_test-stop-2:dead-end:
    # . epilogue
    89/copy                         3/mod/direct    4/rm32/esp    .           .             .           5/r32/ebp   .               .                 # copy ebp to esp
    5d/pop-to-ebp
    c3/return

# . . vim:nowrap:textwidth=0
ofs	hex dump	ascii
0000	89 50 4e 47 0d 0a 1a 0a 00 00 00 0d 49 48 44 52 00 00 00 f0 00 00 00 3c 08 00 00 00 00 7d 14 68	.PNG........IHDR.......<.....}.h
0020	81 00 00 05 70 49 44 41 54 78 01 ed d9 d5 72 e3 48 14 c6 f1 bd fe 2e 86 99 99 79 96 61 98 99 99	....pIDATx....r.H.........y.a...
0040	99 99 29 cc cc 20 3b ce 64 c2 cc 64 92 74 1e 64 5f 65 d5 89 dc 56 bc 73 86 d9 fa 5d 45 55 5d ce	..)...;.d..d.t.d_e...V.s...]EU].
0060	f7 af 0e e7 a7 7f c3 cb f4 30 0b 9e 1e 66 c1 d3 c3 2c 78 7a 20 98 c2 84 1d 4c 64 07 db c1 76 b0	.........0...f...,xz.....Ld...v.
0080	1d 6c 07 db c1 76 b0 1d 6c 07 db c1 6a dc 8a 0d 19 7a 18 05 47 c1 10 ff 09 82 f5 9a a8 13 2b a6	.l...v..l...j....z..G.........+.
00a0	cd 5d b3 ef f4 bd d4 d2 16 95 38 39 08 11 41 ef 69 21 70 89 de 82 9d a4 cf 87 61 7d eb 47 07 37	.]........89..A.i!p.......a}.G.7
00c0	1d 82 d5 65 fd 9d 83 cf d7 bf 7f f0 9e 4a e2 f1 93 82 c1 af 48 38 08 c3 ad 0f 0a ae 99 0d 4c bf	...e.........J......H8........L.
00e0	95 56 58 9c 9f 7c 63 16 80 03 d5 5f 37 98 9f 14 01 c3 7d 4b f0 e1 ea 0f 08 f6 ae 00 06 25 39 9b	.VX..\|c...._7.....}K.........%9.
0100	3d 9a ae b9 2b 57 7f fd 60 7e 92 ff de 92 5f 6e 17 b7 7e 64 70 2e 80 4d 4a af f9 d4 34 f2 8d c1	=...+W..`~...._n..~dp..MJ...4...
0120	c7 15 29 77 12 10 fb 59 82 f9 49 5a 83 ab b4 99 3e 32 f8 0a 80 1d e5 f2 f1 d6 9b 83 6b e4 43 02	..)w...Y..IZ....>2..........k.C.
0140	b0 59 e9 fe 2c c1 6f 9f f4 31 c1 7b 00 cc 2b 93 8f ce e0 ab fb 8b ef 6f 5f 3a 63 c3 e5 1c cf 6b	.Y..,.o..1.{..+........o_:c....k
0160	82 dd f3 81 d8 72 e6 e4 2a f4 19 43 54 7e 63 c3 b4 95 77 6a 5f 13 5c 15 71 fc af 69 73 37 1f bf	.....r..*..CT~c...wj_.\.q..is7..
0180	9b 56 e9 21 89 9d 64 7d 51 6a 80 45 05 b3 96 0b de 05 c3 69 af 7c ee 50 cc 60 e7 ef 30 2d 2a a2	.V.!..d}Qj.E.......i.\|.P.`..0-*.
01a0	7e ad 8a 0c 4e 02 b6 2a dd cc 49 73 db 08 e5 39 fa a5 86 06 f7 9e 42 d0 0e 95 24 76 92 7c 51 47	~...N..*..Is...9......B...$v.\|QG
01c0	48 70 4c 37 b3 96 09 be 04 61 61 64 75 c8 7b 4d 85 e1 70 4e e1 3d 18 12 29 84 c7 98 1e 57 ce 9e	HpL7.....aadu.{M..pN.=..)....W..
01e0	74 5d eb db 76 0b a6 41 ae 81 c1 da 61 00 d3 1f 67 17 e5 a7 5c 00 56 cb db e4 27 c9 17 15 c1 e4	t]..v..A....a...g...\.V...'.....
0200	56 d6 c1 70 58 11 ba 99 b5 4c 70 26 4c 53 4e c6 94 74 53 c0 2b 18 26 e6 57 fb b5 93 e2 bd 98 83	V..pX....Lp&LSN..tS.+.&.W.......
0220	a5 14 60 9b d2 c3 9f 4c 84 30 22 3a af 20 62 12 0c 27 dc d4 c7 a9 28 22 b8 1c 86 3b ce 76 bf ae	..`....L.0":..b..'....("...;.v..
0240	ba 5f c8 60 66 92 94 28 83 e5 e7 30 bf 96 0d 76 ff 02 8b fd 05 e6 4f 35 3b 61 d8 eb d0 88 f2 60	._.`f..(...0...v......O5;a.....`
0260	d8 ed 26 2b ef 52 20 be 82 3b 29 83 cf 3b 5a 54 ed 7e df 75 d5 92 55 12 0c 37 5b 48 f0 0c 97 c1	..&+.R...;)..;ZT.~.u..U..7[H....
0280	ec 24 3e 98 db c0 07 53 ed 22 58 6d ec 9b 51 07 e1 62 15 11 55 41 28 22 ab 34 60 bb 71 c1 cc 49	.$>....S."Xm..Q..b..UA(".4`.q..I
02a0	19 9c 54 4f 44 05 10 0a ff ff 53 f1 f8 67 fd c5 aa 43 06 73 93 f8 60 76 03 1f 4c ed d7 e6 c0 62	..TOD.....S..g...C.s..`v..L....b
02c0	71 1b 11 65 40 b8 d9 40 44 4d 10 1e 79 ad 17 bc dc bc 60 ee a4 19 5c d0 4b 44 4e 08 59 2a 59 64	q..e@..@DM..y.....`...\.KDN.Y*Yd
02e0	a0 df 5f 8f 9c e2 88 c4 4e 62 83 f9 0d 7c 30 a9 75 f1 57 b6 4f 41 c0 79 bf f9 53 1c ee 88 ef f2	.._.....Nb...\|0.u.W.OA.y..S.....
0300	ad 10 4e b6 0d dc bb c3 bc 60 e6 64 df b6 41 8a 46 44 25 10 32 7d 64 d1 36 18 01 c3 af 35 92 c4	..N......`.d..A.FD%.2}d.6....5..
0320	4f 62 82 f9 0d 7c b0 a0 77 37 96 67 3c 3a 30 02 c2 9c 3a a2 07 08 b1 a3 96 24 df af 40 42 05 09	Ob...\|..w7.g<:0...:......$..@B..
0340	cc 49 73 9b 42 c1 60 6f e8 17 3d 69 50 1a 49 ec 24 26 98 dd c0 07 4b ba a7 ad 64 37 84 3c a2 17	.Is.B.`o..=iP.I.$&....K...d7.<..
0360	08 b1 a2 62 c0 57 d1 5d e6 05 33 27 e5 36 2e 98 f2 37 20 a8 94 24 6e 12 13 cc 6e e0 83 93 11 4b	...b.W.]..3'.6...7...$n...n....K
0380	52 d7 64 18 32 fc 94 06 e1 b6 12 f4 52 1e f2 ff 01 24 56 9a 0f cc 49 36 58 ea ce bb b7 77 12 fa	R.d.2.......R....$V...I6X....w..
03a0	5d 75 93 c4 4d 62 82 f9 0d 7c f0 ef f5 24 1d 80 21 df 4b 35 10 2e 99 3f a9 d7 03 c1 5e ca 06 76	]u..Mb...\|...$..!.K5...?....^..v
03c0	cb 1f ed 99 93 7c 70 90 a7 b5 3c e9 28 84 63 8d 24 71 93 42 82 0f cb 60 6e 03 1f 8c 67 ba 7c 5a	.....\|p...<.(.c.$q.B...`n...g.\|Z
03e0	05 60 ad a2 92 b6 1a 86 2d 0d 81 5f 14 a6 e4 77 ca 0b fe db 7a c1 cc c9 b7 04 67 a0 80 04 bd 67	.`......-.._...w....z.....g....g
0400	1b 0c 67 6b 48 e2 26 85 04 9f 81 f9 7b f2 05 c4 33 1b f8 e0 f1 b9 64 2a 86 e1 e9 ab c0 5b c8 24	..gkH.&.....{...3.....d*.....[.$
0420	a1 65 1a ae 38 35 cb 2f 6f 7b e4 05 33 27 df 1e fc 8f 79 87 a7 60 78 26 2f 94 9f 14 12 fc 08 86	.e..85./o{..3'....y..`x&/.......
0440	4d 55 a4 af c0 e3 46 66 2d 1b 0c 9c 2f ed 54 75 4f dd 8b 21 00 4e 29 ed 64 b8 0b c3 bc 9c 5e dd	MU....Ff-.../.TuO..!.N).d.....^.
0460	ed f8 1b 6b 0b 1b c9 a4 ae 00 92 e4 05 33 27 df 1e 8c 95 05 9d aa bf 35 0a 86 95 85 1d 24 71 93	...k.........3'........5.....$q.
0480	42 82 1d 30 8c ca f4 a5 61 68 56 fb eb 37 30 c1 be 94 ed 83 10 34 ef 81 62 7e 49 8f 9a 86 80 83	B..0....ahV..70......4..b~I.....
04a0	79 65 1a 99 f2 80 bd f2 82 99 93 ab 10 a0 3b 10 90 3c 30 38 68 6b 76 99 4e 12 3b 69 d5 80 2f ea	ye............;..<08hkv.N.;i../.
04c0	ea 1e 98 ae 3a 7c ec 5a 6b b0 a4 b5 97 44 5c da f3 fb ac a1 53 96 6e 3b 17 59 58 d2 4a a6 fa 47	....:\|.Zk....D\.....S.n;.YX.J..G
04e0	87 ff 98 39 6a c1 a6 8b 89 4a 95 2a 2f 78 0d 90 54 45 26 e6 64 70 5b 71 30 f8 46 13 49 9a eb c9	...9j....J.*/x..TE&.dp[q0.F.I...
0500	b9 1d ab 16 8c 98 b2 7c c7 e5 78 a5 c2 4f 12 3f 29 f8 a2 11 9d 44 e4 7b bc 73 f1 98 31 cb 0e 44	.......\|..x..O.?)....D.{.s..1..D
0520	28 8d dc 5a 26 58 54 74 36 54 96 96 38 9c ae 8a fa 2e 8d 24 b5 ad fa a5 d3 51 52 de 60 bd 50 dd	(..Z&XTt6T..8......$.....QR.`.P.
0540	a5 28 6e 32 71 27 8d 33 26 bd 43 be 69 09 26 dd d3 5e 5f 51 d6 f7 2e 1b 7b 48 62 26 85 be a8 08	.(n2q'.3&.C.i.&..^_Q....{Hb&....
0560	26 ad a5 d2 e5 70 b8 aa 3a f9 b5 f6 bf 5a ec 60 3b d8 0e b6 83 ed 60 3b d8 0e b6 83 ed 60 3b d8	&....p..:....Z.`;.....`;.....`;.
0580	0e 7e 1b 3b 78 7a 18 11 c1 d3 c3 2c 78 7a 98 05 4f 0f 2f ff 01 db d3 7c 09 bd ff cb cf 00 00 00	.~.;xz.....,xz..O./....\|........
05a0	00 49 45 4e 44 ae 42 60 82	.IEND.B`.