index.html (9612B)
1 <!DOCTYPE html> 2 <html lang="en-US"> 3 4 <head> 5 <meta http-equiv="X-Clacks-Overhead" content="GNU Terry Pratchett" /> 6 <meta charset="utf-8"> 7 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 8 <link rel="shortcut icon" href="https://electrosoup.com/favicon.png" /> 9 <title>The Infamous 'link' Macro | Electrosoup</title> 10 <meta name="title" content="The Infamous 'link' Macro" /> 11 <meta name="description" content="Each word (or function, in other languages) in Forth is stored as an entry in 12 a linked list known as the dictionary. When bootstrapping a Forth from 13 assembly, it is your responsibility to create and maintain this linked list 14 structure. This is a tedious process and is the source of many errors when 15 re-arranging words or defining new words; it’s incredibly easy to turn your 16 list into a graph by mistake." /> 17 <meta name="author" content="" /> 18 <meta name="keywords" content="Forth,Assembly,RISC-V,ARM," /> 19 20 21 22 23 24 25 26 <meta property="og:url" content="https://electrosoup.com/posts/the-infamous-link-macro/"> 27 <meta property="og:site_name" content="Electrosoup"> 28 <meta property="og:title" content="The Infamous 'link' Macro"> 29 <meta property="og:description" content="Each word (or function, in other languages) in Forth is stored as an entry in a linked list known as the dictionary. When bootstrapping a Forth from assembly, it is your responsibility to create and maintain this linked list structure. This is a tedious process and is the source of many errors when re-arranging words or defining new words; it’s incredibly easy to turn your list into a graph by mistake."> 30 <meta property="og:locale" content="en_US"> 31 <meta property="og:type" content="article"> 32 <meta property="article:section" content="posts"> 33 <meta property="article:published_time" content="2024-11-12T13:01:09-08:00"> 34 <meta property="article:modified_time" content="2024-11-12T13:01:09-08:00"> 35 <meta property="article:tag" content="Forth"> 36 <meta property="article:tag" content="Assembly"> 37 <meta property="article:tag" content="RISC-V"> 38 <meta property="article:tag" content="ARM"> 39 40 41 42 43 <meta name="twitter:card" content="summary"> 44 <meta name="twitter:title" content="The Infamous 'link' Macro"> 45 <meta name="twitter:description" content="Each word (or function, in other languages) in Forth is stored as an entry in a linked list known as the dictionary. When bootstrapping a Forth from assembly, it is your responsibility to create and maintain this linked list structure. This is a tedious process and is the source of many errors when re-arranging words or defining new words; it’s incredibly easy to turn your list into a graph by mistake."> 46 47 48 49 50 <meta itemprop="name" content="The Infamous 'link' Macro"> 51 <meta itemprop="description" content="Each word (or function, in other languages) in Forth is stored as an entry in a linked list known as the dictionary. When bootstrapping a Forth from assembly, it is your responsibility to create and maintain this linked list structure. This is a tedious process and is the source of many errors when re-arranging words or defining new words; it’s incredibly easy to turn your list into a graph by mistake."> 52 <meta itemprop="datePublished" content="2024-11-12T13:01:09-08:00"> 53 <meta itemprop="dateModified" content="2024-11-12T13:01:09-08:00"> 54 <meta itemprop="wordCount" content="316"> 55 <meta itemprop="keywords" content="Forth,Assembly,RISC-V,ARM"> 56 57 58 <link href="/herman.min.css" rel="stylesheet"> 59 60 61 62 <link href="/syntax.min.css" rel="stylesheet"> 63 64 65 66 67 68 </head> 69 70 <body> 71 <header><a class="skip-link" href="#main-content">Skip to main content</a> 72 73 <nav> 74 <a href="/">Main</a> 75 76 <a href="/posts/">Posts</a> 77 78 <a href="https://git.electrosoup.com">Code</a> 79 80 <a href="https://christianermann.dev">Resume</a> 81 82 83 84 85 86 87 88 89 90 </nav> 91 </header> 92 <main id="main-content"> 93 94 <h1>The Infamous 'link' Macro</h1> 95 <p class="byline"> 96 97 <time datetime='2024-11-12' pubdate> 98 2024-11-12 99 </time> 100 101 </p> 102 103 <content> 104 <p>Each word (or function, in other languages) in Forth is stored as an entry in 105 a linked list known as the dictionary. When bootstrapping a Forth from 106 assembly, it is your responsibility to create and maintain this linked list 107 structure. This is a tedious process and is the source of many errors when 108 re-arranging words or defining new words; it’s incredibly easy to turn your 109 list into a graph by mistake.</p> 110 <p>In 111 <a href="https://rwmj.wordpress.com/2010/08/07/jonesforth-git-repository/">jonesforth</a>, 112 an x86 implementation of Forth, the assembler supports re-assigning new values 113 to assembler variables. This means an assember variable can be used to store 114 the memory address of the previous entry, and we have the ability to update it 115 or use it whenever we need to. I used this exact strategy in my 116 <a href="https://git.christianermann.dev/forth/log.html">incomplete x86 Forth</a> although 117 I used <a href="https://flatassembler.net/">FASM</a> instead of 118 <a href="https://wiki.osdev.org/GAS">GAS</a>. Unfortunately, GAS doesn’t support this 119 feature for ARM or RISC-V targets. It may be possible to pull this off on ARM 120 with the right set of relocation and/or relaxation parameters, but I was unable 121 to find success with RISC-V.</p> 122 <p>I did come up with an alternative set of macros that achieves the same goal 123 and should be more portable than the <code>jonesforth</code> solution:</p> 124 125 126 127 128 129 <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-GAS" data-lang="GAS"><span class="line"><span class="ln"> 1</span><span class="cl"><span class="na">.macro</span> <span class="no">this_link</span> 130 </span></span><span class="line"><span class="ln"> 2</span><span class="cl"> <span class="na">.globl</span> <span class="no">link_</span><span class="err">\+</span> 131 </span></span><span class="line"><span class="ln"> 3</span><span class="cl"><span class="nf">link_</span><span class="err">\+</span><span class="p">:</span> 132 </span></span><span class="line"><span class="ln"> 4</span><span class="cl"><span class="na">.endm</span> 133 </span></span><span class="line"><span class="ln"> 5</span><span class="cl"> 134 </span></span><span class="line"><span class="ln"> 6</span><span class="cl"><span class="na">.macro</span> <span class="no">prev_link</span> 135 </span></span><span class="line"><span class="ln"> 7</span><span class="cl"> <span class="na">.int</span> <span class="no">link_</span><span class="err">\+</span> 136 </span></span><span class="line"><span class="ln"> 8</span><span class="cl"><span class="na">.endm</span> 137 </span></span><span class="line"><span class="ln"> 9</span><span class="cl"> 138 </span></span><span class="line"><span class="ln">10</span><span class="cl"><span class="na">.macro</span> <span class="no">link</span> 139 </span></span><span class="line"><span class="ln">11</span><span class="cl"> <span class="nf">this_link</span> 140 </span></span><span class="line"><span class="ln">12</span><span class="cl"> <span class="nf">prev_link</span> 141 </span></span><span class="line"><span class="ln">13</span><span class="cl"><span class="na">.endm</span> 142 </span></span><span class="line"><span class="ln">14</span><span class="cl"> 143 </span></span><span class="line"><span class="ln">15</span><span class="cl"><span class="nf">this_link</span></span></span></code></pre></div><p>These macros depend on the special value 144 145 146 147 148 <code class="code-inline language-GAS"><span class="err">\+</span></code>. 149 This value is replaced by the invocation count of the current macro during 150 assembly. Since we want to 151 152 153 154 155 <code class="code-inline language-GAS"><span class="nf">link</span></code> 156 back to the previous word in the dictionary, we need 157 158 159 160 161 <code class="code-inline language-GAS"><span class="nf">prev_link</span></code> 162 to resolve to 1 word before 163 164 165 166 167 <code class="code-inline language-GAS"><span class="nf">this_link</span></code>, 168 which is why we call 169 170 171 172 173 <code class="code-inline language-GAS"><span class="nf">this_link</span></code> 174 once before defining any words.</p> 175 <p>You’ll also need to add this to your linker script to null-terminate your 176 dictionary, otherwise the start of your dictionary will be marked by the 177 address where the 178 179 180 181 182 <code class="code-inline language-GAS"><span class="nf">link_0</span></code> 183 label created by 184 185 186 187 188 <code class="code-inline language-GAS"><span class="nf">this_link</span></code> was stored:</p> 189 190 191 192 193 194 <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-GAS" data-lang="GAS"><span class="line"><span class="ln">1</span><span class="cl"><span class="nf">link_0</span> <span class="err">=</span> <span class="mi">0</span><span class="err">;</span></span></span></code></pre></div> 195 </content> 196 <p> 197 198 <a class="blog-tags" href="/tags/forth/">#forth</a> 199 200 <a class="blog-tags" href="/tags/assembly/">#assembly</a> 201 202 <a class="blog-tags" href="/tags/risc-v/">#risc-v</a> 203 204 <a class="blog-tags" href="/tags/arm/">#arm</a> 205 206 </p> 207 208 209 <p> 210 <a href='mailto:christianermann@gmail.com?subject=Reply%20to%20"The%20Infamous%20%27link%27%20Macro"'> 211 Reply to this post by email ↪ 212 </a> 213 </p> 214 215 216 217 </main> 218 <footer><footer> 219 220 <a href="https://git.electrosoup.com">Code</a>. 221 222 <a href="https://christianermann.dev">Resume</a>. 223 224 <a href='https://electrosoup.com/index.xml'>RSS</a>. 225 <p>Copyright © 2026 Christian Ermann. | Made with <a href="https://github.com/clente/hugo-bearcub">Bear Cub</a></p> 226 </footer> 227 </footer> 228 229 230 </body> 231 232 </html>