Sherlock: annotated disassembly

Routines

Prev: A11A Up: Map Next: A1AF
A11C: Allocate A + 3 bytes from the free list, cleared
Walks the free blocks from 9FE3 (each starts with its size and a link) and takes the smallest that is big enough - best fit. If what would be left is under 4 bytes the whole block is unlinked, otherwise it is split. The block is zeroed, its size stored before it, and IX returned on it with NZ. No block big enough: C1D8 (out of memory). Word lists, remarks and orders are built in these blocks; A1AF frees them.
How it works:
1. C = the number of bytes wanted + 3 (the size field and the link).
2. Walk the free list from 9FE3. Each free block begins with its size and a link. Blocks that are too small are passed over.
3. Of those that are big enough, remember the smallest (best fit), and the link that points to it.
4. If none fits, go to the out-of-memory routine at C1D8.
5. If the chosen block would leave 4 bytes or more, split it: the free block keeps the front part and the end is handed out. Otherwise the whole block is taken and unhooked from the free list.
6. Store the size before the block, clear its data and return NZ with IX at the block.
Input
A The number of data bytes wanted (3 more are used for the header)
Output
IX The cleared block
F NZ on success; out of memory ends in $C1D8
A11C PUSH IY Save IY on the stack - Save IY, HL, DE, BC
A11E PUSH HL Save HL on the stack
A11F PUSH DE Save DE on the stack
A120 PUSH BC Save BC on the stack
A121 ADD A,$03 Add $03 to A - C = the size wanted, A + 3
A123 LD C,A Copy A into C
A124 LD B,$00 B bit 0: a block has been chosen
A126 LD HL,($9FE3) Read the heap's free list (9FE3) into HL - HL = the first free block; IY = the link that points to it
A129 LD IY,$9FE3 Point IY at the heap's free list (9FE3)
A12D LD A,L Copy L into A - End of the free list?
A12E OR H Set in A the bits that are set in H
A12F JR Z,$A160 If the result is zero, jump on to A160
A131 LD E,(HL) Read the byte HL points at into E - DE = this block's size; HL on to its link
A132 INC HL Step HL on to the next byte
A133 LD D,(HL) Read the byte HL points at into D
A134 INC HL Step HL on to the next byte
A135 LD A,D Copy D into A - A size over 255 is always big enough
A136 AND A Test A for zero (this leaves A as it was and clears carry)
A137 JR NZ,$A13D If A is not zero, skip ahead to A13D
A139 LD A,E Copy E into A - Under 256: too small for C?
A13A CP C Compare A with C
A13B JR C,$A157 Yes: next block
A13D BIT 0,B Test bit 0 of B - Big enough. Nothing chosen yet?
A13F JR Z,$A14E If bit 0 of B is clear, skip ahead to A14E
A141 PUSH HL Save HL on the stack - Otherwise is it smaller than the chosen block (size at IX-2)?
A142 LD L,(IX-$02) Read byte -2 of the record at IX into L
A145 LD H,(IX-$01) Read byte -1 of the record at IX into H
A148 AND A Clear the carry flag, so that the subtraction that follows is a plain one (a compare)
A149 SBC HL,DE Subtract DE from HL (a compare: carry = HL was smaller, zero = equal)
A14B POP HL Restore HL from the stack
A14C JR C,$A157 No: keep the one we have
A14E PUSH HL Save HL on the stack - Choose it: IX = its link field
A14F POP IX Restore IX from the stack
A151 LD ($A11A),IY Store IY in "A11C: the free-list link before the best block..." (A11A) - and remember the link that points to it
A155 SET 0,B Set bit 0 of B
A157 PUSH HL Save HL on the stack - IY = this block's link field; follow it to the next block
A158 POP IY Restore IY from the stack
A15A LD E,(HL) Read the byte HL points at into E
A15B INC HL Step HL on to the next byte
A15C LD D,(HL) Read the byte HL points at into D
A15D EX DE,HL Swap DE and HL
A15E JR $A12D Go back to A12D
A160 BIT 0,B Test bit 0 of B - End of the list: was anything chosen?
A162 JR Z,$A1AC If bit 0 of B is clear, jump on to A1AC
A164 LD L,(IX-$02) Read byte -2 of the record at IX into L - HL = what would be left of the chosen block after taking C
A167 LD H,(IX-$01) Read byte -1 of the record at IX into H
A16A LD B,$00 Load B with $00
A16C AND A Clear the carry flag, so that the subtraction that follows is a plain one (a compare)
A16D SBC HL,BC Subtract BC from HL (a compare: carry = HL was smaller, zero = equal)
A16F LD A,H Copy H into A
A170 AND A Test A for zero (this leaves A as it was and clears carry)
A171 JR NZ,$A18A If A is not zero, skip ahead to A18A - 256 or more: split it
A173 LD A,L Copy L into A
A174 CP $04 Compare A with $04 - 4 or more: split it
A176 JR NC,$A18A If A is $04 or more, skip ahead to A18A
A178 LD IY,($A11A) Read "A11C: the free-list link before the best block..." (A11A) into IY - Under 4: take the whole block - point the previous link past it
A17C LD A,(IX+$00) Read the first byte of the record at IX into A
A17F LD (IY+$00),A Store A in the first byte of the record at IY
A182 LD A,(IX+$01) Read byte +1 of the record at IX into A
A185 LD (IY+$01),A Store A in byte +1 of the record at IY
A188 JR $A193 Skip ahead to A193
A18A LD (IX-$02),L Store L in byte -2 of the record at IX - Split: the free block keeps the first part, now HL bytes
A18D LD (IX-$01),H Store H in byte -1 of the record at IX
A190 EX DE,HL Swap DE and HL - and IX moves to the part being handed out
A191 ADD IX,DE Add DE to IX
A193 INC IX Step IX on to the next byte - Store the block's size before it
A195 LD (IX-$03),C Store C in byte -3 of the record at IX
A198 PUSH IX Save IX on the stack - Clear the C - 1 bytes of the block
A19A POP HL Restore HL from the stack
A19B DEC HL Step HL back one byte
A19C DEC HL Step HL back one byte
A19D LD B,C Copy C into B
A19E DEC B Subtract one from B
A19F XOR A Clear A to zero (and the carry flag)
A1A0 LD (HL),A Store A at the address HL points to
A1A1 INC HL Step HL on to the next byte
A1A2 DJNZ $A1A0 Count B down and, while it is not zero, go back to A1A0
A1A4 OR $01 Set bit 0 of A - NZ: success, IX = the block
A1A6 POP BC Restore BC from the stack
A1A7 POP DE Restore DE from the stack
A1A8 POP HL Restore HL from the stack
A1A9 POP IY Restore IY from the stack
A1AB RET Return to the caller
A1AC JP $C1D8 Nothing big enough: out of memory
Prev: A11A Up: Map Next: A1AF