electrosoup.com

git clone git://git.electrosoup.com/electrosoup.com
Log | Files | Refs

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 &#39;link&#39; Macro | Electrosoup</title>
     10 <meta name="title" content="The Infamous &#39;link&#39; 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&rsquo;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 &#39;link&#39; 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 &#39;link&#39; 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 &#39;link&#39; 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 &#39;link&#39; 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&rsquo;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&rsquo;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&rsquo;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 &copy; 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>