js/map-maker/imgs/extracted-1688-map/MapParts/hills/50.png

# read-byte-buffered: one higher-level abstraction atop 'read'.
#
# There are many situations where 'read' is a lot to manage, and we need
# to abstract some details away. One of them is when we want to read a file
# character by character. In this situation we follow C's FILE data structure,
# which manages the underlying file descriptor together with the buffer it
# reads into. We call our version 'buffered-file'. Should be useful with other
# primitives as well, in later layers.

== data

# The buffered file for standard input. Also illustrates the layout for
# buffered-file.
Stdin:
    # file descriptor or (address stream)
    0/imm32  # standard input
    # current write index
    0/imm32
    # current read index
    0/imm32
    # length
    8/imm32
    # data
    00 00 00 00 00 00 00 00  # 8 bytes

# TODO: 8 bytes is too small. We'll need to grow the buffer for efficiency. But
# I don't want to type in 1024 bytes here.

== 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

# return next byte value in EAX, with top 3 bytes cleared.
# On reaching end of file, return 0xffffffff (Eof).
read-byte-buffered:  # f : (address buffered-file) -> byte-or-Eof/EAX
    # . prolog
    55/push-EBP
    89/copy                         3/mod/direct    5/rm32/EBP    .           .             .           4/r32/ESP   .               .                 # copy ESP to EBP
    # . save registers
    51/push-ECX
    56/push-ESI
    # ESI = f
    8b/copy                         1/mod/*+disp8   5/rm32/EBP    .           .             .           6/r32/ESI   8/disp8         .                 # copy *(EBP+8) to ESI
    # ECX = f->read
    8b/copy                         1/mod/*+disp8   6/rm32/ESI    .           .             .           1/r32/ECX   8/disp8         .                 # copy *(ESI+8) to ECX
    # if (f->read >= f->write) populate stream from file
    3b/compare                      1/mod/*+disp8   6/rm32/ESI    .           .             .           1/r32/ECX   4/disp8         .                 # compare ECX with *(ESI+4)
    7c/jump-if-lesser  $read-byte-buffered:from-stream/disp8
    # . clear-stream(stream = f+4)
    # . . push args
    8d/copy-address                 1/mod/*+disp8   6/rm32/ESI    .           .             .           0/r32/EAX   4/disp8         .                 # copy ESI+4 to EAX
    50/push-EAX
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . f->read must now be 0; update its cache at ECX
    31/xor                          3/mod/direct    1/rm32/ECX    .           .             .           1/r32/ECX   .               .                 # clear ECX
    # . EAX = read(f->fd, stream = f+4)
    # . . push args
    50/push-EAX
    ff          6/subop/push        0/mod/indirect  6/rm32/ESI    .           .             .           .           .               .                 # push *ESI
    # . . call
    e8/call  read/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
    # if (EAX == 0) return 0xffffffff
    3d/compare-EAX-and  0/imm32
    75/jump-if-not-equal  $read-byte-buffered:from-stream/disp8
    b8/copy-to-EAX  0xffffffff/imm32/Eof
    eb/jump  $read-byte-buffered:end/disp8
$read-byte-buffered:from-stream:
    # read byte from stream
    # AL = f->data[f->read]
    31/xor                          3/mod/direct    0/rm32/EAX    .           .             .           0/r32/EAX   .               .                 # clear EAX
    8a/copy-byte                    1/mod/*+disp8   4/rm32/sib    6/base/ESI  1/index/ECX   .           0/r32/AL    0x10/disp8      .                 # copy byte at *(ESI+ECX+16) to AL
    # ++f->read
    ff          0/subop/increment   1/mod/*+disp8   6/rm32/ESI    .           .             .           .           8/disp8         .                 # increment *(ESI+8)
$read-byte-buffered:end:
    # . restore registers
    5e/pop-to-ESI
    59/pop-to-ECX
    # . epilog
    89/copy                         3/mod/direct    4/rm32/ESP    .           .             .           5/r32/EBP   .               .                 # copy EBP to ESP
    5d/pop-to-EBP
    c3/return

# - tests

test-read-byte-buffered-single:
    # - check that read-byte-buffered returns first byte of 'file'
    # setup
    # . clear-stream(_test-stream)
    # . . push args
    68/push  _test-stream/imm32
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . clear-stream(_test-buffered-file+4)
    # . . push args
    b8/copy-to-EAX  _test-buffered-file/imm32
    05/add-to-EAX  4/imm32
    50/push-EAX
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . write(_test-stream, "Ab")
    # . . push args
    68/push  "Ab"/imm32
    68/push  _test-stream/imm32
    # . . call
    e8/call  write/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
    # read-byte-buffered(_test-buffered-file)
    # . . push args
    68/push  _test-buffered-file/imm32
    # . . call
    e8/call  read-byte-buffered/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # check-ints-equal(EAX, 'A', msg)
    # . . push args
    68/push  "F - test-read-byte-buffered-single"/imm32
    68/push  0x41/imm32
    50/push-EAX
    # . . call
    e8/call  check-ints-equal/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add to ESP
    # . end
    c3/return

test-read-byte-buffered-multiple:
    # - call read-byte-buffered twice, check that second call returns second byte
    # setup
    # . clear-stream(_test-stream)
    # . . push args
    68/push  _test-stream/imm32
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . clear-stream(_test-buffered-file+4)
    # . . push args
    b8/copy-to-EAX  _test-buffered-file/imm32
    05/add-to-EAX  4/imm32
    50/push-EAX
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . write(_test-stream, "Ab")
    # . . push args
    68/push  "Ab"/imm32
    68/push  _test-stream/imm32
    # . . call
    e8/call  write/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
    # read-byte-buffered(_test-buffered-file)
    # . . push args
    68/push  _test-buffered-file/imm32
    # . . call
    e8/call  read-byte-buffered/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # read-byte-buffered(_test-buffered-file)
    # . . push args
    68/push  _test-buffered-file/imm32
    # . . call
    e8/call  read-byte-buffered/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # check-ints-equal(EAX, 'b', msg)
    # . . push args
    68/push  "F - test-read-byte-buffered-multiple"/imm32
    68/push  0x62/imm32
    50/push-EAX
    # . . call
    e8/call  check-ints-equal/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add to ESP
    # . end
    c3/return

test-read-byte-buffered-end-of-file:
    # - call read-byte-buffered on an empty 'file', check that it returns Eof
    # setup
    # . clear-stream(_test-stream)
    # . . push args
    68/push  _test-stream/imm32
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . clear-stream(_test-buffered-file+4)
    # . . push args
    b8/copy-to-EAX  _test-buffered-file/imm32
    05/add-to-EAX  4/imm32
    50/push-EAX
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # read-byte-buffered(_test-buffered-file)
    # . . push args
    68/push  _test-buffered-file/imm32
    # . . call
    e8/call  read-byte-buffered/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # check-ints-equal(EAX, 0xffffffff, msg)
    # . . push args
    68/push  "F - test-read-byte-buffered-end-of-file"/imm32
    68/push  0xffffffff/imm32/Eof
    50/push-EAX
    # . . call
    e8/call  check-ints-equal/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add to ESP
    # . end
    c3/return

test-read-byte-buffered-refills-buffer:
    # - consume buffered-file's buffer, check that next read-byte-buffered still works
    # setup
    # . clear-stream(_test-stream)
    # . . push args
    68/push  _test-stream/imm32
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . clear-stream(_test-buffered-file+4)
    # . . push args
    b8/copy-to-EAX  _test-buffered-file/imm32
    05/add-to-EAX  4/imm32
    50/push-EAX
    # . . call
    e8/call  clear-stream/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # . write(_test-stream, "Abcdefgh")
    # . . push args
    68/push  "Abcdefgh"/imm32
    68/push  _test-stream/imm32
    # . . call
    e8/call  write/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               8/imm32           # add to ESP
    # pretend buffer is full
    # . _test-buffered-file->read = 6  # >= _test-buffered-file->length
    b8/copy-to-EAX  _test-buffered-file/imm32
    c7          0/subop/copy        1/mod/*+disp8   0/rm32/EAX    .           .             .           .           8/disp8         6/imm32           # copy to *(EAX+8)
    # read-byte-buffered(_test-buffered-file)
    # . . push args
    68/push  _test-buffered-file/imm32
    # . . call
    e8/call  read-byte-buffered/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               4/imm32           # add to ESP
    # check-ints-equal(EAX, 'A', msg)
    # . . push args
    68/push  "F - test-read-byte-buffered-refills-buffer"/imm32
    68/push  0x41/imm32
    50/push-EAX
    # . . call
    e8/call  check-ints-equal/disp32
    # . . discard args
    81          0/subop/add         3/mod/direct    4/rm32/ESP    .           .             .           .           .               0xc/imm32         # add to ESP
    # . end
    c3/return

== data

# a test buffered file for _test-stream
_test-buffered-file:
    # file descriptor or (address stream)
    _test-stream/imm32
    # current write index
    0/imm32
    # current read index
    0/imm32
    # length
    6/imm32
    # data
    00 00 00 00 00 00  # 6 bytes

# . . 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 5c 00 00 00 1b 08 06 00 00 00 f1 b2 e8	.PNG........IHDR...\............
0020	8c 00 00 04 cd 49 44 41 54 78 da ed 99 7d 48 14 51 14 c5 77 4b d9 fc c0 52 2a 31 49 30 a9 a8 30	.....IDATx...}H.Q..wK...R*1I0..0
0040	32 14 25 23 29 12 c3 25 28 0a 51 12 a5 a8 3f 0a 23 88 a4 08 25 29 a4 d0 3f 0a 45 14 23 91 44 29	2.%#)..%(.Q...?.#...%)..?.E.#.D)
0060	92 30 0c a3 50 12 c5 48 8c a2 a4 48 2a 0c 8a 0a 0b 8b 8c ca 5a b5 fb e2 b7 f0 9a 76 fd 4c d2 75	.0..P..H...H*.......Z......v.L.u
0080	2e 1c 76 77 de cc ce ce b9 e7 9d 7b df 5b 8b c5 0c 33 fe 43 94 0b ee 09 aa 04 b1 26 1d 93 1b 2b	..vw.......{.[...3.C.......&...+
00a0	05 5f 05 59 82 02 c1 33 93 92 91 09 db 27 38 2f b8 20 a8 14 54 08 4a 05 79 02 bb 20 c0 70 4d 98	._.Y...3.....'8/....T.J.y....pM.
00c0	f6 3e 4e 30 80 b2 33 04 bd 02 ab 36 3e 77 26 91 b9 ce cd 71 6f c1 26 c1 31 48 3a 28 28 14 e4 f3	.>N0..3....6>w&....qo.&.1H:((...
00e0	aa 48 6f 15 7c 10 3c 40 b9 9b 05 d1 82 54 92 91 c2 e7 4c 81 83 7b a9 ef ac e3 1e 11 82 bd 7c ff	.Ho.\|.<@.....T....L..{........\|.
0100	8c 88 5c 41 a3 8b e3 5e 82 1c c1 0b d4 e8 ce 73 57 0b ee 0b 7e 08 7e a2 e2 41 e0 e0 b5 8d d9 d0	..\A...^.......sW...~.~..A......
0120	4b d2 12 04 31 5c 7f 58 d0 23 28 13 cc e3 98 d5 53 c9 9e 43 21 bb ee c2 3e da 48 c6 32 81 8f 36	K...1\.X.#(.....S..C!...>.H.2..6
0140	66 73 f1 3d 4b 05 b5 90 de 22 78 23 f8 2c 78 4b 12 1e 31 ae 0a 66 0d 3e 1e a1 5d 9b 26 f0 f7 64	fs.=K...."x#.,xK..1..f.>..].&..d
0160	55 47 68 ef 33 b1 0c 0b 76 50 84 47 ab 29 1e 64 b8 6e 01 04 b9 8a 62 08 6f 82 d8 87 82 3b 82 0e	UGh.3...vP.G.).d.n....b.o....;..
0180	8e dd 12 3c 11 74 33 5e 81 95 28 b2 d7 0b 66 79 2a d9 b3 0d 9f b7 6a 4a ae 85 94 72 37 d7 86 0a	...<.t3^..(...fy*.....jJ...r7...
01a0	c2 dd 8c 29 ab 78 89 9a ef 42 72 1d 45 b6 92 59 d4 89 ea 95 fa bf 08 be 71 de 31 8a ae c2 0a 66	...).x...Br.E..Y........q.1....f
01c0	91 1f 09 57 e2 d8 c0 58 b2 60 8d 76 cf 29 6f 3d 8a d4 2d 82 24 41 14 0f 52 af f9 ae 52 69 c8 38	...W...X.`.v.)o=..-.$A..R...Ri.8
01e0	bf 3b 10 e2 de 43 bc 05 c2 4b 29 a6 05 90 af 92 59 4d b1 55 f7 1d e2 b5 9f d7 01 bc 7f 00 3b 72	.;...C...K).....YM.U..........;r
0200	68 f5 40 a1 4f 70 8d 22 ad 12 78 71 2a 11 bc 80 2e e1 94 a0 04 25 ab 2e 61 11 6a dd 86 9f 66 70	h.@.Op."..xq*........%..a.j...fp
0220	6c 34 e1 35 cc 98 95 84 2a 1b e9 12 9c 35 8c 2b 5b 39 49 a1 cc 27 21 aa 58 9e 26 11 8d 14 50 67	l4.5....*....5.+[9I..'!.X.&...Pg
0240	d1 75 0a 61 48 4b 86 c2 27 12 a4 2c ec a3 e0 32 36 58 84 45 c6 3b a7 9c 1d 95 c5 d0 bb e6 e0 61	.u.aHK..'..,...26X.E.;.........a
0260	b1 86 a9 32 11 bb 58 45 db 95 cc fd b2 79 a0 a3 90 6d 35 a8 72 ac c5 2a 68 84 71 7f 6c a2 87 15	...2..XE.....y...m5.r..*h.q.l...
0280	65 95 8b 73 f2 51 7e 2d bf 6b 2b 89 ca 24 49 37 98 0d 67 11 4a 0d e7 97 f1 be 59 70 9b d7 3b 74	e..s.Q~-.k+..$I7..g.J.....Yp..;t
02a0	52 4f 28 d8 57 9c 35 e9 1d 03 ce 1f f1 86 02 f2 4a f0 9a 95 97 dd 4d f1 f0 31 7c 0e c1 e3 fc e9	RO(.W.5.........J.....M..1\|.....
02c0	71 f7 b0 28 39 24 78 ca b4 be 29 d8 28 58 e2 c2 b7 27 12 0b 47 d1 f9 5c 46 79 5d 90 5a c2 58 0e	q..(9$x...).(X...'..G..\Fy].Z.X.
02e0	44 36 30 0b 3a 51 e6 6e c4 b0 16 9b 4b e0 f9 5c 2d 8a 6c 28 38 8a 96 74 03 09 3c 20 d8 41 02 77	D60.:Q.n....K..\-.l(8..t..<..A.w
0300	1a 49 b3 1a de fb a1 cc 73 a8 e3 0a d3 bf 92 1f f6 9c e3 cd 10 aa 3a 80 76 7e 78 11 37 4c 67 35	.I......s.............:.v~x.7Lg5
0320	a7 fc 39 f2 1f 93 3c d6 48 83 cc 01 84 d4 c1 6f bf ca 33 16 23 3a e7 02 aa 46 7b a6 0e d4 7b 10	..9...<.H......o..3.#:...F{...{.
0340	32 23 21 77 52 22 90 2a bd 84 ac 2e e6 66 eb b0 1c 65 3d 89 b4 6f b1 b4 68 ea 1a df 29 56 9c 7d	2#!wR".*.....f...e=..o..h...)V.}
0360	21 d3 01 91 ad 90 d8 80 6f b7 31 b3 1f 43 72 27 c5 f0 06 8a 2f 44 a5 4a b1 47 48 54 31 fe 9f cd	!.......o.1..Cr'..../D.J.GHT1...
0380	6c 8e 36 77 5b fe 0c 3b 45 ed 16 5d 45 03 33 b7 1c 45 b7 30 6b 1b f0 e1 3e ba 97 02 8a fc 76 0a	l.6w[..;E..]E.3..E.0k...>.....v.
03a0	fe 71 ae af c2 9e ea 38 27 05 0b 32 83 48 c4 52 14 89 97 50 6f 19 be eb 65 a8 09 fb a9 69 ed d8	.q.....8'..2.H.R...Po...e....i..
03c0	e7 7b bc 3e 85 d9 6e c6 28 22 85 96 ee a6 a6 ce 36 54 7e 1e 7b 08 74 51 d7 ac d4 3b ef 61 b6 12	.{.>..n.("......6T~.{.tQ...;.a..
03e0	cc 70 b3 f2 1c 64 11 d4 84 d2 4b 69 f5 0a 21 3c 95 f6 75 13 9d 87 49 ee 38 23 88 75 86 5a 29 7e	.p...d....Ki..!<..u...I.8#.u.Z)~
0400	a0 b3 aa 27 09 19 f4 dc 09 f8 73 3d bb 8d ad f8 b6 19 63 8c 42 56 92 b9 f4 e3 79 b4 84 df 41 3f	...'......s=......c.BV....y...A?
0420	7e 1e 37 dd 1f d4 86 72 e6 bb d9 43 c9 1a 61 59 3e de f0 33 2c 7a ba e9 bd 9f 52 00 cf b0 30 b3	~.7....r...C..aY>..3,z....R...0.
0440	d3 ca 25 a1 ee 90 e9 4e 78 38 ea 4a a3 87 d5 5b a6 24 a6 6c 0e fb 27 4a 5d cb 47 b1 a2 8c 70 93	..%....Nx8.J...[.$.l..'J].G...p.
0460	40 3d d2 29 90 9b e9 8f 1d f8 76 33 ed 9c 52 fb 4a 4f 9c ca 36 1e 7e 97 56 a0 c2 b4 85 88 ea 5d	@=.)......v3..R.JO..6.~.V......]
0480	bf d2 ef be a5 f7 0d d6 ae 3f 41 12 6c 10 fd 10 0b 78 c0 16 81 71 93 6a 0e 7b 42 d5 6c 5b 38 ed	.........?A.l....x...q.j.{B.l[8.
04a0	c2 01 c9 21 dc 77 b9 e5 cf ff 36 3d 32 7c 86 d9 93 f1 a5 1d 0b 35 8c 45 b3 1f 91 cc 1e 4d 24 33	...!.w....6=2\|.......5.E.....M$3
04c0	25 9f c5 4b 0b b6 14 48 42 9c 3b 90 f1 9c ef c3 77 26 cc b4 a2 95 4a 37 30 9e dd c7 60 cb df ff	%..K...HB.;.....w&....J70...`...
04e0	9e 07 d0 b6 65 68 36 e5 cd fb 48 b3 47 30 e3 77 fc 02 55 78 46 cc 8a 3e 0a 10 00 00 00 00 49 45	....eh6...H.G0.w..UxF..>......IE
0500	4e 44 ae 42 60 82	ND.B`.