I don't know if this will be useful, but my own Micro-C compiler has a TSR
function built into it's 8086/PC library.

In this last year, as part a "Retirement project", I've released the source
code to Micro-C which includes full source code to the library (which contains
TSR.ASM)

You can access my 40+ years worth of source code project (incl. the above)
via my web site.

Here is the (trimmed for brevity) description of the TSR function within the
Micro-C library documentation:

1PROTOTYPE:
2  tsr(&func, int hotkey, int alloc)
3
4ARGUMENTS:
5  func    - Address of function to execute
6  hotkey  - POP-UP activation hotkeys
7  alloc   - Memory allocation
8
9RETURN VALUE:
10  Function normally never returns, but if it does, an
11  operating system error code is passed back.
12
13DESCRIPTION:
14     The TSR function terminates the MICRO-C  program,  but  leaves  it
15  resident in memory. When the specified "HOT KEYS" are detected on the
16  IBM PC keyboard, the context of whatever program is running is saved,
17  and the specified MICRO-C function  is  called.  When  that  function
18  returns, the interrupted program is resumed.
19
20     When activated this way,  THE  "func"  FUNCTION MUST NOT TERMINATE
21  WITH "exit"  or one of its related functions  (abort etc.).  THE ONLY
22  WAY IT MAY TERMINATE IS TO "return" NORMALLY.
23     The meaning of "hotkey" is defined in the "tsr.h" header file.
24
25     The  "alloc"  parameter specifies how much extra memory is  to  be
26  retained in the TSR image for use  by  the  MICRO-C  stack  and  heap
27  memory allocation functions.  The "func" function(s) must insure that
28  the total amount of memory used by the stack and  calls  to  "malloc"
29  does not exceed this value.
30
31     NOTE:  "malloc"  will fail if the heap grows to within 1K  of  the
32  stack pointer.
33
34     All memory used by  code,  global  variables,  string  space,  and
35  "malloc"  calls prior to the use of "tsr"  is automatically retained,
36  and should not be included in the "alloc" value.
37
38     TSR programs which perform screen I/O should take care to save and
39  restore the screen contents when popping up and down.
40
41
42EXAMPLES:
43   tsr(&popup_func, ALT+L_SHIFT, 1024);

i need assembler - the result should become a example for a reverse engineering test, the behavior of the TSR should be just visible but minimal

The TSR.ASM mentioned in the afore mention library source code is assembler - and I mentioned it mainly in case
an example of a working general purpose TSR function would be helpful, not so much expecting you to use it "as is".

llm wrote on 2025-03-29, 13:02:

[…]
Show full quote

Copy code to clipboard

1run_original:
2	jmp cs:[tsr_info.old_interrupt_21h]		; jump to original int 21h

I have not used WASM a lot, back in the day I would use MASM, then TASM, and now NASM - so I'm not 100% sure about this, but shouldn't that jump be explicitly far? As in, "jmp far cs:[...]". The way you have it now it might be coded as near jump, except with memory argument.

Deunan wrote on 2025-03-29, 20:23:

llm wrote on 2025-03-29, 13:02:

[…]
Show full quote

Copy code to clipboard

1run_original:
2	jmp cs:[tsr_info.old_interrupt_21h]		; jump to original int 21h

I have not used WASM a lot, back in the day I would use MASM, then TASM, and now NASM - so I'm not 100% sure about this, but shouldn't that jump be explicitly far? As in, "jmp far cs:[...]". The way you have it now it might be coded as near jump, except with memory argument.

thanks i fixed that - also my linker statement was not fully correct

i fixes serveral bugs and now install/uintstall seems to work - updated first post accordingly

so the TSR install/uninstall and just forwarding to the old int 21h handler is working flawless (according to my dosbox debugger checks) - right before calling the old int 21h my ds:dx buffer is correct but the call prints nothing and just hangs until i press a key

im not sure if calling the old int 21h handler is correct that way - and if i needs sti/cli somewere - and if the push/pop savings are good that way
the string char replacing itself works

my current code

1far_ptr_t struc
2  offs dw 0
3  segm dw 0
4far_ptr_t ends
5
6tsr_info_t struc
7  signature dw 0CAFEh
8  old_interrupt_21h far_ptr_t<0,0>
9  load_segment dw 0
10tsr_info_t ends
11
12.model tiny
13
14.code
15
16org 100h ; this is a COM program
17
18start:
19  jmp   setup         ; jump to TSR installation
20
21int21h_handler proc far
22  cmp ah,9 ; is it print
23  jne run_original
24
25  ; ---------------------------------
26  ; copy string with $
27  ; search for 'l' and replace with 'X'
28
29  push es
30  push ds
31  push si
32  push di
33  push ax
34  push cx
35  push dx
36
37  ; print parameter = ds:dx = string+$
38  mov si,dx ; source is ds:si
39
40  ; es:di is dest
41  mov ax,cs
42  mov es,ax
43  mov di,offset buffer
44
45  mov cx, 16-1 ; max 15
46copy_loop:
47  lodsb
48  cmp al, '$'
49  je done
50  cmp al, 'l'
51  jne not_l
52  mov al, 'X'
53not_l:
54  stosb
55  loop copy_loop
56done:
57  mov al,'$'
58  stosb
59
60  mov ax,cs

61  mov ds,ax
62  mov dx,offset buffer
63
64  pushf
65  call far ptr cs:[tsr_info.old_interrupt_21h]
66
67  pop cx
68  pop dx
69  pop ax
70  pop di
71  pop si
72  pop ds
73  pop es
74
75  iret
76
77  ; ----------------------------------
78
79run_original:
80  jmp far ptr cs:[tsr_info.old_interrupt_21h]   ; jump to original int 21h
81
82  ; local buffer
83  buffer db 16 dup('#')
84int21h_handler endp
85
86; tsr data
87tsr_info TSR_info_t<>
88
89resident_end: ; also contains PSP at start due to "org 100h"
90
91TSR_INFO_OFFSET = offset tsr_info - offset int21h_handler;
92
93current_load_seg dw 0
94
95setup:
96  mov bx,ds
97  mov current_load_seg,bx
98
99  ; ds == cs
100
101  mov ax,3521h              ; get int 21h
102  int 21h
103
104  mov di,bx
105  add di,TSR_INFO_OFFSET
106
107  mov ax,es:[di+TSR_info_t.signature]
108  cmp ax,0CAFEh
109  je uinstall
110
111  ; install
112
113  ; save current int 21h handler
114  mov [tsr_info.old_interrupt_21h.offs],bx
115  mov [tsr_info.old_interrupt_21h.segm],es
116
117  ; save load-segment for uninstall
118  mov ax,current_load_seg
119  mov [tsr_info.load_segment],ax
120
121  mov ax,2521h              ; set interrupt vector
122  mov dx,offset int21h_handler
123  int 21h
124
125  mov ax,3100h
126  mov dx,offset resident_end
127  mov cl,4
128  shr dx,cl
129  inc dx
130  int 21h
131
132uinstall:
133  push ds
134  mov ax,es:[di+TSR_info_t.old_interrupt_21h.segm]
135  mov ds,ax
136  mov dx,es:[di+TSR_info_t.old_interrupt_21h.offs]
137  mov ax,2521h
138  int 21h
139  pop ds
140
141  mov ax,es:[di+TSR_info_t.load_segment]
142  mov es,ax
143  mov ah,49h
144  int 21h
145
146  mov ax,4c00h
147  int 21h
148
149END start

llm wrote on 2025-03-30, 08:21:

[…]
Show full quote

Copy code to clipboard

1  push cx
2  push dx
3  ...
4  pop cx
5  pop dx

First, correct the push/pop sequence. Second you should consider jumping on AH=9 to your code, rather than jumping twice on AH!=9 to old address. It's not a huge issue, the 21h handler is not that fast, but I like doing things properly for performance reasons - like when you have to write your own high frequency interrupt (HSYNC or doing DAC with PC speaker). Every cycle counts then.

Lastly consider moving the data structures between jmp setup and the handler code. Why? This way you can have the signature very close to the new handler and only need to adjust the pointer a few bytes at most to check if the program is already resident. Simply much easier to calculate and code it.

EDIT: BTW you need CLD somewhere before you start using string instructions. It might just work like this since most programs will have these instructions set to forward/increment mode but it's not a good idea to assume that.
And there's another bug, you call the old interrupt to print out your string but you've destroyed AX by moving the segment registers around. Either set AH=9 or change the push/pop sequence to restore AX first, before you make that jump.

First, correct the push/pop sequence.

stupid me - thx

Second you should consider jumping on AH=9 to your code, rather than jumping twice on AH!=9 to old address.

i don't jump twice/or getting called twice - the call after string-replace only calls the original handler
can you explain differently?

Lastly consider moving the data structures between jmp setup and the handler code. Why?
This way you can have the signature very close to the new handler and only need to adjust the pointer a few bytes at most to check if the program is already resident. Simply much easier to calculate and code it.

because at setup time im inside the com executable segment and on uninstall time i need to use the interrupt ptr to find the information for uninstall, isn't the calculation already very easy?
can you explain what you would change in detail?

you need CLD somewhere before you start using string instructions.

facepalm - yepp thanks again

you call the old interrupt to print out your string but you've destroyed AX by moving the segment registers around. Either set AH=9 or change the push/pop sequence to restore AX first, before you make that jump.

that was my "i need a keypress" behavior - works now

so it seems to work now fully - my int 21h/9h string get replaced at 'l' with 'X' no crashes so far - but im still interested in getting more feedback

current code

1far_ptr_t struc
2  offs dw 0
3  segm dw 0
4far_ptr_t ends
5
6tsr_info_t struc
7  signature dw 0CAFEh
8  old_interrupt_21h far_ptr_t<0,0>
9  load_segment dw 0
10tsr_info_t ends
11
12.model tiny
13
14.code
15
16org 100h ; this is a COM program
17
18start:
19  jmp   setup         ; jump to TSR installation
20
21int21h_handler proc far
22  cmp ah,9 ; is it print
23  jne run_original
24
25  ; ---------------------------------
26  ; copy string with $
27  ; search for 'l' and replace with 'X'
28
29  push ds
30  push es
31  push di
32  push si
33  push ax
34  push cx
35  push dx
36
37  ; print parameter = ds:dx = string+$
38  mov si,dx ; source is ds:si
39
40  ; es:di is dest
41  mov ax,cs
42  mov es,ax
43  mov di,offset buffer
44
45  cld
46  mov cx, 16-1 ; max 15
47copy_loop:
48  lodsb
49  cmp al, '$'
50  je done
51  cmp al, 'l'
52  jne not_l
53  mov al, 'X'
54not_l:
55  stosb
56  loop copy_loop
57done:
58  mov al,'$'
59  stosb
60

61  mov ax,cs
62  mov ds,ax
63  mov dx,offset buffer
64  mov ah,9
65
66  pushf
67  call far ptr cs:[tsr_info.old_interrupt_21h]
68
69  pop dx
70  pop cx
71  pop ax
72  pop si
73  pop di
74  pop es
75  pop ds
76
77  iret
78
79  ; ----------------------------------
80
81run_original:
82  jmp far ptr cs:[tsr_info.old_interrupt_21h]   ; jump to original int 21h
83
84  ; local buffer
85  buffer db 16 dup('#')
86int21h_handler endp
87
88; tsr data
89tsr_info TSR_info_t<>
90
91resident_end: ; also contains PSP at start due to "org 100h"
92
93TSR_INFO_OFFSET = offset tsr_info - offset int21h_handler;
94
95current_load_seg dw 0
96
97setup:
98  mov bx,ds
99  mov current_load_seg,bx
100
101  ; ds == cs
102
103  mov ax,3521h              ; get int 21h
104  int 21h
105
106  mov di,bx
107  add di,TSR_INFO_OFFSET
108
109  mov ax,es:[di+TSR_info_t.signature]
110  cmp ax,0CAFEh
111  je uinstall
112
113  ; install
114
115  ; save current int 21h handler
116  mov [tsr_info.old_interrupt_21h.offs],bx
117  mov [tsr_info.old_interrupt_21h.segm],es
118
119  ; save load-segment for uninstall
120  mov ax,current_load_seg
121  mov [tsr_info.load_segment],ax
122
123  mov ax,2521h              ; set interrupt vector
124  mov dx,offset int21h_handler
125  int 21h
126
127  mov ax,3100h
128  mov dx,offset resident_end
129  mov cl,4
130  shr dx,cl
131  inc dx
132  int 21h
133
134uinstall:
135  push ds
136  mov ax,es:[di+TSR_info_t.old_interrupt_21h.segm]
137  mov ds,ax
138  mov dx,es:[di+TSR_info_t.old_interrupt_21h.offs]
139  mov ax,2521h
140  int 21h
141  pop ds
142
143  mov ax,es:[di+TSR_info_t.load_segment]
144  mov es,ax
145  mov ah,49h
146  int 21h
147
148  mov ax,4c00h
149  int 21h
150
151END start

llm wrote on 2025-03-30, 14:31:

i don't jump twice/or getting called twice - the call after string-replace only calls the original handler
can you explain differently?

What I mean is AH=9 is just one of many functions of int 21h. Consider this approach:

1  cmp ah,9 ; is it print
2  je run_print
3  jmp far ptr cs:[tsr_info.old_interrupt_21h]   ; jump to original int 21h
4run_print:
5  ...

This way the default path, every function except 09h, is a conditional jump not taken. No prefetch flush, faster execution. Again this is not going to do much here because it's an OS call and is slow on its own. I just figured I'd point this out in case you want to write something more time critical in future.

llm wrote on 2025-03-30, 14:31:

because at setup time im inside the com executable segment and on uninstall time i need to use the interrupt ptr to find the information for uninstall, isn't the calculation already very easy?
can you explain what you would change in detail?

You calculate this using assembler pointer arithmetic at compile time: TSR_INFO_OFFSET = offset tsr_info - offset int21h_handler;
If you ever create another version of this program, with some code changes, this value will also change. So now your newly compiled TSR can't uninstall the previous version(s) because it will be looking for the signature in the wrong place. Obviously it's your personal program so you probably don't care - but for public release it's not good enough. People might be keeping different versions because of bugs, or memory usage, or whatever, and be annoyed they have to keep track of what version was installed to uninstall it.

Consider this solution:

1signature dw 0CAFEh
2int21h_handler proc far
3  ...

Now when you fetch the interrupt pointer you can easily, and with always the same constant, check for the presence of your code:

1  mov ax,3521h              ; get int 21h
2  int 21h
3
4  cmp word ptr es:[bx-2],0CAFEh
5  je uinstall

Now these are just suggestions, you don't have to do it this way if you'd rather stick to a known working solution. BTW shouldn't this topic be in Software rather than Hardware? That being said I don't visit other sections of the forums as often as I visit here...

thanks for the detailed descriptions - sensefull but i keep it as is - its just an example - nothing that should reach version 2.0 😀