Some Assembly Required: An approachable introduction to assembly

It was so fun working with Hack Clubbers on this project!<p>Hack Club is a group of teenagers from all over the world, and we decided to learn assembly together from scratch and see what happened.<p>We ended up making this guide as we learned, since a lot of the resources we were working with weren&#x27;t the easiest to parse.<p>Happy to answer any questions :)

My favorite part is the heavily commented code examples. Those are much more useful for increasing my understanding than most other resources. To me, that level of information density just works better for my brain than articles or sites that try to explain things.<p>Something about being _in the code_ while stepping through lines one by one with explanations is just so much easier to follow. I wish more learning resources took this approach.

I basically learned C++ and assembly programmer at the same time when I was 16 by just watching the output of gcc.godbolt.org (yes ok zoomer)

I&#x27;d like to share an old Dylan Cuthbert blog post on his hypothesis that Assembly is actually easier for kids to learn programming.<p><a href="https:&#x2F;&#x2F;www.gamesindustry.biz&#x2F;articles&#x2F;2011-03-30-machine-code-is-for-kids-article" rel="nofollow">https:&#x2F;&#x2F;www.gamesindustry.biz&#x2F;articles&#x2F;2011-03-30-machine-co...</a>

This is making me wonder just how raw Sawyer’s code for Rollercoaster Tycoon was. The source doesn’t seem to be out there but a page on his site (<a href="http:&#x2F;&#x2F;www.chrissawyergames.com&#x2F;faq3.htm" rel="nofollow">http:&#x2F;&#x2F;www.chrissawyergames.com&#x2F;faq3.htm</a>) says he used “MS Macro Assembler V6.11c” so it’s probably safe to assume he didn’t type out every single instruction in the game by hand. Depending on how many macros he’d built up at this point in his career it might have felt more like programming in C, except with a lower conceptual barrier to switching to inline assembly functions when stuff needed to be optimized.

Assembly language is actually simple stuff. You just need to read the datasheet. No difficult type systems to deal with.<p>In the old days programming assembly language was nasty because one mistake could mean your computer had to be rebooted and you lost your work. Not anymore.

I was worried this was only going to be a discussion of x86 assembly. Pleasantly surprised it included 6502 and RISC-V. It&#x27;s worth reading even if you&#x27;re not a teenager.

Good stuff. A fine reminder that illustrations go a long way; well-done on those, and the guide as a whole.

This is amazing! Love the simplicity and the art used to explain things.

&gt; <i>why the Rollercoaster Tycoon creator would write 99% of the game in it</i><p>Not sure how true it is, but I heard that keeping track of a lot of objects required plenty of optimization, and apparently such levels of detail may have not been in games before. RCT was the second Tycoon game by Chris Sawyer, after Transport Tycoon from 1994—which is also in assembly and which keeps track of buses and trucks each with its own parameters, trains with each car, signals on the roads; of every passenger and every batch of goods: where it&#x27;s from, how long it&#x27;s on the way, etc. (At least if OpenTTD recreates the mechanics faithfully.) You can also pop up several windows with views to different parts of the map or following various vehicles.

This is great!<p>As a developer who didn&#x27;t learn via a scholastic setting, taking the time to sit down and learn a bit of assembly was something I see as a critical point in my career.<p>Starting with a high level scripting language, my brain had a hard time dealing with so much abstraction and taking what felt like a crazy amount of axioms as given.<p>I took a few months to sit down and go through the excellent book Programming From the Ground Up. After doing some bit twiddling, writing a basic allocator, and a handful of the other exercises from the book, I felt way more prepared to handle abstractions higher up.<p>Anything that I couldn&#x27;t infer based on the underlying knowledge was something I could google, then quickly form the missing links between starting from the bottom.<p>I feel like learning C could give the same benefits, though I do hear some struggle with pointers, and in assembly you get to look face first at what they actually are. Everyone has different levels of abstraction that they&#x27;re comfortable with as well. Assembly was enough to fill the seeming void of knowledge that I felt was holding me back, but for others it may be higher depending on which aspects are puzzling (memory management, intermediate representations, etc).<p>I also appreciate how much information modern VM authors publish about the inner workings of their platforms. It helps a lot in the same manner to reason about the systems (v8, JVM, CLR, etc).

Having started my career at Bell Labs in 1984, the fact that you included AT&amp;T X86 syntax cracked me up.<p>If you are still interested in learning more, ARM and PowerPC are also both interesting assembly targets.<p>Prior to Bell Labs (college) my assembly experience was 8085 bare metal (no OS) or Z80 under CP&#x2F;M and MP&#x2F;M. I wrote a couple console management applications for MP&#x2F;M that had to dig into BIOS&#x2F;BDOS routines. It was fun, and that was the thing that made my EE self realize that I wanted to work on software in embedded systems.

Love this! Must admit, my favourite part of doing a CS degree was creating a CPU core from scratch (a cut down ARM, running on a FPGA), then writing asm to run on it. So satisfying knowing I made the actual CPU (at gate level) and ran my own code on it. I’d be happy to do a YouTube series covering how to do this if anyone is interested.

So probably a really dumb question, but given that assembly has a limited number of operations and a limited number of registers, what are processors doing with the ever growing number of transistors added to them? What is processed with billions of transistors that can&#x27;t be done with thousands?

I enjoyed learning assembly in college -- to me, many of the non-intuitive aspects of abstract languages make more sense when you know something like C, and C makes a lot of sense once you know assembly. It all sort of clicks in a very satisfying way.

They mentioned Z80 but do not have the examples of Z80; maybe in future might be added.<p>I have used some assembly language stuff, including 6502, Knuth&#x27;s MIX and MMIX, and virtual codes such as Z-code and Glulx.<p>I have written small amounts of old x86 assembly code (for the older 16-bit PC), too. (I think that the new x86 is too messy and too complicated, compared with the old x86 which is not bad.)<p>I have been trying to learn TRON assembly code too, although I cannot find enough information. I found some documents, but they are in Japanese and some important diagrams seem to be missing. There is some English documentation too but it does not explain much.

Great work, very methodical!<p>In using assembler I find the hardest part is to represent the task at hand into a form of a sequence of elementary operations over the dynamic set of data pieces and their locations.<p>Perhaps, when the problem scope is on a lower level with a limited sets of data and operations, this maps easier. But when the task is on a macro level, that extra step of mapping the context onto a lower level scope is just too much effort.<p>In a way, in a higher level scope the programmers create their specific &#x27;assembler&#x27; with a different set of registers and opcodes and sequences of operation, and even busses.

There was a coding competition at a local podunk BBS back in ~’91. I figured I would use it as an excuse to learn some assembly. The goal of the challenge i entered was to find all of the prime numbers between one and a million. Of course my goal with the assembly approach was speed and executable size. In both of those I smoked the competition by 3 to 4 orders of magnitude.<p>But the scoring mechanism was heavily weighted towards lines of code and the turbo Pascal entry one even though it took about six minutes to complete.<p>That pissed me off so much I never really messed with assembly again.

I think Pico-8 recently added support for editing assembly operations.<p>Also there is a book called Programming from the Ground Up that starts with assembly and moves up to C and beyond.

Great work! There’s a typo on the 6502 page, DNC should be DEC for the Accumulator. Started coding asm on the c64 as 10 year old kid. Would have loved resources like this!<p><a href="https:&#x2F;&#x2F;github.com&#x2F;hackclub&#x2F;some-assembly-required&#x2F;tree&#x2F;main&#x2F;code&#x2F;6502#common-instructions-explained" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;hackclub&#x2F;some-assembly-required&#x2F;tree&#x2F;main...</a>

Thank you!! Just yesterday I was googling trying to find a good introduction to learning assembly and today here it is!!!

This is fantastic!<p>I’m definitely not an assembly guy, but it would be fun if there was a REPL to play with this. Not sure if that would accidentally invert the universe or it’s too low level for a REPL, but conceptually it would be fun to play with in a sandbox.

Learning assembly has been on my wishlist forever. . . excited to give this repo a look see.

Thanks for good resources about Assembly, I’m learning source code of AsmBB [1] - a forum written in assembly x86 :D<p>[1] <a href="https:&#x2F;&#x2F;board.asm32.info&#x2F;" rel="nofollow">https:&#x2F;&#x2F;board.asm32.info&#x2F;</a>

The most proud of assembly program I made was Voracity game (2008). The learning process was so smooth because there are only few things to use. Mind blowing moment is when I made chain jump to workaround out of range jump.

Pardon, but the assembly code on the &quot;Loop de Loop&quot; chapter currently seems broken. &quot;rax&quot; is acting as all three variables somehow.

very nice! I wouldnt give this to a programming novice but its very nice for people who know their stuff and just havent done asm yet.

Good job. Some constructive criticism:<p>There&#x27;s quite a big difficulty spike so to speak in the later section as you go towards the code examples. The beginning explains relatively simple concepts like binary, then basically jmps into an instruction table which won&#x27;t make sense to anyone who hasn&#x27;t done some form of programming (they would know binary then, right?).<p>The tone is also a bit off putting, although I might be out of touch with today&#x27;s teenagers. When I was learning asm as a teen I learned it from grungy 1337 h4x0r sites (well, they didn&#x27;t actually use 1337speak except ironically, much like today) which were at least a great deal.. meaner? less nice?.. than the tone of the article.<p>From what I wrote I gather my main criticism is that it doesn&#x27;t know its audience. However, it seemingly _was_ produced by an actual group of teenager as per the author&#x27;s HN comment:<p>&gt; Hack Club is a group of teenagers from all over the world, and we decided to learn assembly together from scratch and see what happened.<p>Although it probably means a trained adult was lightly helped by some teenagers in producing it.<p>I hope this didn&#x27;t sound too harsh, the effort is very good and so are the illustrations. It needs some fleshing and perhaps a little less &quot;yay!!&quot;. Learning assembly is not actually that fun, it&#x27;s rather painful. It&#x27;s what you do with it that is fun.

Those illustrations are gorgeous.

Very cool! Amazing work you all!

Wonderful. Love the rich comments in the code.

&quot;Since forever ago, I&#x27;ve wanted to try writing assembly, even if just to understand why the Rollercoaster Tycoon creator would write 99% of the game in it. To be fair, even after all of this, I still don&#x27;t understand why they did that.&quot;<p>Hubris?

this is damn cool!

Finished?

this is really cool