<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Julio Vidaurre on Medium]]></title>
        <description><![CDATA[Stories by Julio Vidaurre on Medium]]></description>
        <link>https://medium.com/@julio.vidaurre?source=rss-548808e7edf7------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Stories by Julio Vidaurre on Medium</title>
            <link>https://medium.com/@julio.vidaurre?source=rss-548808e7edf7------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 16:08:00 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@julio.vidaurre/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[How torrents work (by making one)]]></title>
            <link>https://medium.com/@julio.vidaurre/how-torrents-work-by-making-one-eac59c8d93eb?source=rss-548808e7edf7------2</link>
            <guid isPermaLink="false">https://medium.com/p/eac59c8d93eb</guid>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[c-programming-language]]></category>
            <category><![CDATA[torrent]]></category>
            <dc:creator><![CDATA[Julio Vidaurre]]></dc:creator>
            <pubDate>Fri, 25 Apr 2025 00:20:48 GMT</pubDate>
            <atom:updated>2025-04-25T00:20:48.001Z</atom:updated>
            <content:encoded><![CDATA[<p>I download many things using torrents and sometimes it’s faster than direct downloads. For a long time it makes me wonder how it works.</p><p>I will explain how a make a very (very) simple torrent client to download the debian-net iso (not small but no more than 1GB).</p><p>I decided to use C for this project (is the only way to learn a language, right?) and do everything from scratch (except the networking; decided to use libcurl for that). I’m not going to post whole pieces of the code here, just explain several thing I had to consider. The complete code is hosted on <a href="https://github.com/juliovr/torrent-client">Github</a>.</p><h3>Scope</h3><p>I will only limit this tiny project to download only torrents that contain 1 file and that are done via TCP (Bittorrent has it’s own protocol <a href="https://www.bittorrent.org/beps/bep_0029.html">uTP</a>).</p><h3>Steps to download a file</h3><ol><li>Decode the torrent file to extract the data of where to get “the file”.</li><li>Get the peers.</li><li>Connect to the peers and download the file’s pieces.</li></ol><h3>1. Torrent file and Bencoding</h3><p>The .torrent is a binary file that contains information about the file(s) that can be download. Here is an example screenshot of the content:</p><figure><img alt="Content of a .torrent file" src="https://cdn-images-1.medium.com/max/1024/1*xu2pfFaYXSE7gDLsfvTcow.png" /></figure><p>The content is in a format called “Bencoding”. Imagine it like a JSON but with a different structure. This encoding can be made of 4 types of values:</p><ul><li>Strings are length-prefixed base ten followed by a colon and the string. For example 4:spam corresponds to ‘spam’.</li><li>Integers are represented by an ‘i’ followed by the number in base 10 followed by an ‘e’. For example i3e corresponds to 3 and i-3e corresponds to -3. Integers have no size limitation. i-0e is invalid. All encodings with a leading zero, such as i03e, are invalid, other than i0e, which of course corresponds to 0.</li><li>Lists are encoded as an ‘l’ followed by their elements (also bencoded) followed by an ‘e’. For example l4:spam4:eggse corresponds to [‘spam’, ‘eggs’].</li><li>Dictionaries are encoded as a ‘d’ followed by a list of alternating keys and their corresponding values followed by an ‘e’. For example, d3:cow3:moo4:spam4:eggse corresponds to {‘cow’: ‘moo’, ‘spam’: ‘eggs’} and d4:spaml1:a1:bee corresponds to {‘spam’: [‘a’, ‘b’]}. Keys must be strings and appear in sorted order (sorted as raw strings, not alphanumerics).</li></ul><p>The important thing about the torrent file is that the first value is always a dictionary (that’s why the first character in the example screenshot is a “d”).</p><h4>(Ben)Decode</h4><p>Here is my approach for decoding the torrent file:</p><ol><li>As C does not have inheritance, we can use <a href="https://en.wikipedia.org/wiki/Type_punning">type punning</a> to emulate inheritance. By defining a base struct Bencode that contains the type, we can declare that field in every other struct and we are able to cast it to the specific type.</li></ol><pre>#define MAX_KEYS 128<br><br>typedef enum BencodeType {<br>    TYPE_DICTIONARY,<br>    TYPE_LIST,<br>    TYPE_NUMBER,<br>    TYPE_STRING,<br>} BencodeType;<br><br>typedef struct Bencode {<br>    BencodeType type;<br>    u8 *bencode_chars;<br>    int bencode_size;<br>} Bencode;<br><br>typedef struct BencodeDictionary {<br>    Bencode bencode;<br>    int n;<br>    Bencode *keys[MAX_KEYS];<br>    Bencode *values[MAX_KEYS];<br>} BencodeDictionary;<br><br>typedef struct BencodeList {<br>    Bencode bencode;<br>    int n;<br>    Bencode *values[MAX_KEYS];<br>} BencodeList;<br><br>typedef struct BencodeNumber {<br>    Bencode bencode;<br>    u64 value;<br>} BencodeNumber;<br><br>typedef struct BencodeString {<br>    Bencode bencode;<br>    string str;<br>} BencodeString;</pre><p>The decode module is done by this simple function that just call the specific decode for the types:</p><pre>Bencode *decode(Tokenizer *tokenizer)<br>{<br>    char c = *tokenizer-&gt;current;<br>    switch (c) {<br>        case &#39;d&#39;: return decode_dictionary(tokenizer);<br>        case &#39;l&#39;: return decode_list(tokenizer);<br>        case &#39;i&#39;: return decode_number(tokenizer);<br>        case &#39;0&#39;:<br>        case &#39;1&#39;:<br>        case &#39;2&#39;:<br>        case &#39;3&#39;:<br>        case &#39;4&#39;:<br>        case &#39;5&#39;:<br>        case &#39;6&#39;:<br>        case &#39;7&#39;:<br>        case &#39;8&#39;:<br>        case &#39;9&#39;:<br>            return decode_string(tokenizer);<br>        default:<br>            return NULL;<br>    }<br>}</pre><p>As the first type is a dictionary, the first call will return the complete parsed dictionary back to the caller.</p><p>Here is the code to decode a dictionary:</p><pre>static Bencode *decode_dictionary(Tokenizer *tokenizer)<br>{<br>    BencodeDictionary *dictionary = (BencodeDictionary *)malloc(sizeof(BencodeDictionary));<br>    dictionary-&gt;bencode.type = TYPE_DICTIONARY;<br>    dictionary-&gt;n = 0;<br><br>    u8 *start = tokenizer-&gt;current;<br>    <br>    advance(tokenizer); // Skip &#39;d&#39;<br>    <br>    while (tokenizer-&gt;size &gt; 0 &amp;&amp; *tokenizer-&gt;current != &#39;e&#39;) {<br>        Bencode *key = decode(tokenizer);<br>        if (key-&gt;type != TYPE_STRING) {<br>            fprintf(stderr, &quot;ERROR: key must be string.\n&quot;);<br>            exit(1);<br>        }<br><br>        Bencode *value = decode(tokenizer);<br><br>        dictionary-&gt;keys[dictionary-&gt;n] = key;<br>        dictionary-&gt;values[dictionary-&gt;n] = value;<br><br>        dictionary-&gt;n++;<br>    }<br>    if (!match(tokenizer, &#39;e&#39;)) {<br>        fprintf(stderr, &quot;ERROR: Miss &#39;e&#39;\n&quot;);<br>        exit(1);<br>    }<br><br>    dictionary-&gt;bencode.bencode_chars = start;<br>    dictionary-&gt;bencode.bencode_size = tokenizer-&gt;current - start;<br><br>    return (Bencode *)dictionary;<br>}</pre><p>Note that inside it calls again the decode() to get the data to construct the dictionary itself. We only have to validate that the key is a String (the specification says so) and the value could be any type (even another dictionary).</p><p>To get values from the dictionary, we use this helper function that iterates over the keys to check whether exists or not and return the corresponding value; NULL for non-existence.</p><pre>Bencode *get_by_key(BencodeDictionary *dictionary, char *search_key)<br>{<br>    if (dictionary) {<br>        for (int i = 0; i &lt; dictionary-&gt;n; ++i) {<br>            BencodeString *key = (BencodeString *)dictionary-&gt;keys[i];<br>            if (strncmp(key-&gt;str.chars, search_key, key-&gt;str.length) == 0) {<br>                return dictionary-&gt;values[i];<br>            }<br>        }<br>    }<br><br>    return NULL;<br>}</pre><p>There are 2 things to pay attention:</p><ol><li>The “info” dictionary:</li><li>The “pieces” string:</li></ol><h4>2. Get peers</h4><p>The torrent is a P2P network, so we need to know whom we can connect with to exchange data. This is obtained by making a HTTP GET request to the announce URL given in the torrent file.</p><pre>typedef struct Peer {<br>    string peer_id;<br>    string ip;<br>    int port;<br>} Peer;<br><br>typedef struct PeersList {<br>    Peer peers[128];<br>    int n;<br>} PeersList;<br><br>PeersList get_peers(Torrent *torrent)<br>{<br>    char *url = (char *)malloc(MAX_URL_LENGTH);<br>    snprintf(url, MAX_URL_LENGTH, &quot;%.*s?info_hash=%.*s&amp;peer_id=%.*s&amp;port=%d&amp;uploaded=0&amp;downloaded=0&amp;left=%ld&quot;,<br>        torrent-&gt;announce.length, torrent-&gt;announce.chars, <br>        (int)strlen(torrent-&gt;info_hash_string), torrent-&gt;info_hash_string, <br>        (int)sizeof(torrent-&gt;peer_id_string), torrent-&gt;peer_id_string,<br>        6881, torrent-&gt;length);<br><br>    printf(&quot;Making GET request to: %s\n&quot;, url);<br><br>    curl_global_init(CURL_GLOBAL_DEFAULT);<br>    <br>    PeersList result = {0};<br><br>    CURL *curl = curl_easy_init();<br>    if (curl) {<br>        curl_easy_setopt(curl, CURLOPT_URL, url);<br>        curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L);<br>        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);<br>        curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);<br><br>        Response response;<br>        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, response_callback);<br>        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &amp;response);<br><br>        CURLcode res = curl_easy_perform(curl);<br>        if (res != CURLE_OK) {<br>            fprintf(stderr, &quot;curl_easy_perform() failed: %s\n&quot;, curl_easy_strerror(res));<br>        }<br><br>        Tokenizer tokenizer = create_tokenizer(response.body, response.size);<br>        <br>        Bencode *bencode_response = decode(&amp;tokenizer);<br>        BencodeString *failure_reason = (BencodeString *)get_by_key((BencodeDictionary *)bencode_response, &quot;failure reason&quot;);<br>        if (failure_reason != NULL) {<br>            fprintf(stderr, &quot;ERROR: failure_reason: %.*s\n&quot;, failure_reason-&gt;str.length, failure_reason-&gt;str.chars);<br>            exit(1);<br>        }<br><br>        // Parse peers<br>        BencodeList *peers_list = (BencodeList *)get_by_key((BencodeDictionary *)bencode_response, &quot;peers&quot;);<br>        if (peers_list) {<br>            for (int i = 0; i &lt; peers_list-&gt;n; ++i) {<br>                BencodeDictionary *peer_entry = (BencodeDictionary *)peers_list-&gt;values[i];<br>                if (peer_entry) {<br>                    BencodeString *bencode_peer_id = ((BencodeString *)get_by_key(peer_entry, &quot;peer_id&quot;));<br>                    Peer peer = {<br>                        .peer_id = (bencode_peer_id == NULL) ? create_string(&quot;&quot;, 0) : bencode_peer_id-&gt;str,<br>                        .ip = ((BencodeString *)get_by_key(peer_entry, &quot;ip&quot;))-&gt;str,<br>                        .port = ((BencodeNumber *)get_by_key(peer_entry, &quot;port&quot;))-&gt;value,<br>                    };<br>                    result.peers[i] = peer;<br>                    result.n++;<br>                }<br>            }<br>        }<br><br>        curl_easy_cleanup(curl);<br>    }<br><br>    curl_global_cleanup();<br><br>    return result;<br>}</pre><h3>3. Download file’s pieces</h3><p>Once we have the list of peers we can connect to them to request the file. But how? The way torrents work is by download pieces of the file and, once we get all the pieces, just merge them in the correct order and voila!, you just construct the entire file.</p><p>The last value of the torrent file is a giant string called “pieces” (see the image below), whose length is a multiple of 20. It is to be subdivided into strings of length 20, each of which is the SHA1 hash of the piece at the corresponding index, i.e. the first 20 bytes is the hash for the first piece, the next 20 bytes for the second piece, etc.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*hJUXAwmIVdpZM7mjfk1DAw.jpeg" /></figure><p>This is very important because is the way to know where to store each pieces and to verify that the piece was downloaded successfully, and gives the ability to download the pieces in any order you want (and can).</p><p>To speed up this tiny program (and to add more fun), let’s download the pieces with multiple threads. This is the code I used to create as many threads as cores the machine has:</p><pre>int main(int argc, char **argv)<br>{<br>    // ...<br><br>    int ncores = (int)sysconf(_SC_NPROCESSORS_CONF);<br>    printf(&quot;Using ncores: %d\n&quot;, ncores);<br>    <br>    pthread_t *threads = (pthread_t *)malloc(ncores * sizeof(pthread_t));<br>    <br>    for (int i = 0; i &lt; ncores; ++i) {<br>        ThreadArgs args = {<br>            .file = file,<br>            .torrent = &amp;torrent,<br>            .peers_list = &amp;peers_list,<br>            .queue = &amp;queue,<br>            .absolute_peer_index = i * 2, // Use the index as the first index to look for. If it does not have it, look in the next one.<br>        };<br>        int res = pthread_create((threads + i), NULL, attempt_download_thread, &amp;args);<br>        if (res != 0) {<br>            fprintf(stderr, &quot;ERROR: Could not create thread %d\n&quot;, i);<br>        }<br>    }<br><br>    for (int i = 0; i &lt; ncores; ++i) {<br>        int res = pthread_join(threads[i], NULL);<br>        if (res != 0) {<br>            fprintf(stderr, &quot;ERROr: Could not join thread\n&quot;);<br>        }<br>    }<br><br>    // ...<br>}</pre><p>Each thread will run the function <em>attempt_download_thread. </em>Each TCP connection to the peers is hold in the TCPClient struct and do not close until all the pieces we want are downloaded or anything else happen.</p><pre>typedef struct TCPClient {<br>    CURL *curl;<br>    char *url;<br>    bool connected;<br>    int sockfd;<br>    fd_set ready_set;<br>    bool choked;<br>    u8 *bitfield;<br>    int bitfield_size;<br>} TCPClient;<br><br>void *attempt_download_thread(void *arg)<br>{<br>    ThreadArgs *args = (ThreadArgs *)arg;<br>    FILE *file = args-&gt;file;<br>    Torrent *torrent = args-&gt;torrent;<br>    WorkQueue *queue = args-&gt;queue;<br>    PeersList *peers_list = args-&gt;peers_list;<br>    <br>    int peer_index = args-&gt;absolute_peer_index;<br><br>    do {<br>        Peer *peer = peers_list-&gt;peers + (peer_index % peers_list-&gt;n);<br>        <br>        // char url[MAX_URL_LENGTH];<br>        // snprintf(url, MAX_URL_LENGTH, &quot;%.*s:%d&quot;, peer-&gt;ip.length, peer-&gt;ip.chars, peer-&gt;port);<br>        char url[100];<br>        snprintf(url, 100, &quot;%.*s:%d&quot;, peer-&gt;ip.length, peer-&gt;ip.chars, peer-&gt;port);<br><br>        HandshakeData handshake_data = create_handshake_data(torrent-&gt;info_hash, torrent-&gt;peer_id);<br>    <br>        TCPClient client = new_tcp_client(url);<br>        tcp_client_connect(&amp;client);<br>        if (client.connected) {<br>            Message *bitfield_message = make_handshake(&amp;client, &amp;handshake_data);<br>            if (bitfield_message != NULL) {<br>                send_unchoke(&amp;client);<br>                send_interested(&amp;client);<br>                <br>                for (int attempt = 0; attempt &lt; 3; ++attempt) {<br>                    int piece_index;<br>                    while (dequeue(queue, &amp;piece_index)) {<br>                        int downloaded_err = 1;<br>                        if (peer_has_piece(bitfield_message, piece_index)) {<br>                            client.bitfield = bitfield_message-&gt;payload;<br>                            client.bitfield_size = bitfield_message-&gt;payload_size;<br>                            <br>                            downloaded_err = download_piece(&amp;client, torrent, file, piece_index);<br>                        }<br>                        <br>                        if (downloaded_err) {<br>                            enqueue(queue, piece_index);<br>                            break;<br>                        }<br>                    }<br>                }<br>            }<br>        }<br>        tcp_client_cleanup(&amp;client);<br><br>        // If all the pieces from the peer was downloaded, or the connection/handshake failed, change the peer to continue the work.<br>        peer_index++;<br>    } while (queue-&gt;count &gt; 0);<br><br>    return (void *)0;<br>}</pre><p>To avoid downloading the same piece, the pieces indices are stored in a Queue that are guarded by a mutex.</p><pre>typedef struct QueueNode {<br>    int data;<br>    struct QueueNode *next;<br>} QueueNode;<br><br>typedef struct WorkQueue {<br>    QueueNode *first;<br>    QueueNode *last;<br>    int count;<br>    pthread_mutex_t mutex;<br>} WorkQueue;</pre><p>The protocol works by sending messages with specific structures in the following way:</p><ol><li>After connecting, make the handshake with the specific format(see the spec to know how it’s arrange; or the code).</li><li>If the handshake is correct, the peer could return a bitfield message (in this project we will assume it always return it). The bitfield is a series of bytes that specify which pieces the peer has. For example, a bitfield 0xF1 (binary 0b11110001) means the peer has the pieces 0, 1, 2, 3 and 7 (all the setted bits). We use that to know which piece we can request from the peers.</li><li>Send “unchoke” and “interested” messages. The protocol works with a choke/unchoke process. Data transfer takes place whenever one side is interested and the other side is not choking.</li><li>Request the piece. Send the “request” message to get a piece given by an index.</li><li>Receive the piece and checksum. We receive a “piece” message, decode it, hash and compare it against the hash in the torrent file. If it match the piece was download successfully and we can proceed to store the block of data into the file at the specified offset, which is pretty straightforward to calculate. From the previous point we know the index of the piece we requested, giving: <strong>piece_index * piece_length = offset in the entire file.</strong></li><li>Send “have” message. After the piece is download we let the peer to know we get it successfully.</li></ol><pre>int download_piece(TCPClient *client, Torrent *torrent, FILE *file, int piece_index)<br>{<br>    int result = 1;<br><br>    CURLcode res;<br>    int length = 13;<br>    int piece_length = get_piece_length(torrent, piece_index);<br>    <br>    int remaining = piece_length;<br>    int downloaded = 0;<br>    u8 *piece_buf = (u8 *)malloc(piece_length);<br>    Message *message = NULL;<br>    <br>    while (remaining &gt; 0) {<br>        int byte_offset = downloaded;<br>        int piece_request_size = MAX_REQUEST_SIZE;<br>        if (!client-&gt;choked) {<br>            u8 data[17];<br>            *((u32 *)data) = TO_BIG_ENDIAN(length);<br>            data[4] = MESSAGE_ID_REQUEST;<br>            *((u32 *)(data + 5)) = TO_BIG_ENDIAN(piece_index);<br>            *((u32 *)(data + 9)) = TO_BIG_ENDIAN(byte_offset);<br>            *((u32 *)(data + 13)) = TO_BIG_ENDIAN(piece_request_size);<br>        <br>            res = send_data(client, data, sizeof(data));<br>            if (res != CURLE_OK) {<br>                fprintf(stderr, &quot;ERROR: (%d) could not send request\n&quot;, res);<br>                goto download_piece_cleanup;<br>            }<br>        }<br><br>        message = receive_message(client);<br>        if (message == NULL) {<br>            // Keep-alive<br>            goto download_piece_cleanup;<br>        }<br>        <br>        switch (message-&gt;id) {<br>            case MESSAGE_ID_CHOKE: {<br>                client-&gt;choked = true;<br>            } break;<br>            case MESSAGE_ID_UNCHOKE: {<br>                client-&gt;choked = false;<br>            } break;<br>            case MESSAGE_ID_PIECE: {<br>                if (message-&gt;payload_size &lt; 8) {<br>                    goto download_piece_cleanup;<br>                }<br>                int index = FROM_BIG_ENDIAN(*((int *)(message-&gt;payload + 0)));<br>                int begin = FROM_BIG_ENDIAN(*((int *)(message-&gt;payload + 4)));<br>                u8 *block = message-&gt;payload + 8;<br>                int block_size = message-&gt;payload_size - 8;<br>                piece_index = index;<br>                remaining -= block_size;<br>                downloaded += block_size;<br>                memcpy(piece_buf + begin, block, block_size);<br>            } break;<br>        }<br>    }<br>    u8 expected_hash[SHA_DIGEST_LENGTH];<br>    memcpy(expected_hash, torrent-&gt;piece_hashes + (piece_index * SHA_DIGEST_LENGTH), SHA_DIGEST_LENGTH);<br>    u8 hash_piece[SHA_DIGEST_LENGTH];<br>    SHA1(piece_buf, piece_length, hash_piece);<br>    if (memcmp(expected_hash, hash_piece, SHA_DIGEST_LENGTH) != 0) {<br>        fprintf(stderr, &quot;ERROR: piece hash does not match the expected hash from torrent\n&quot;);<br>        return result;<br>    }<br>    send_have(client, piece_index);<br>    fseek(file, piece_index * torrent-&gt;piece_length, SEEK_SET);<br>    fwrite(piece_buf, 1, downloaded, file);<br>    result = 0;<br>    <br>download_piece_cleanup:<br>    free_message(message);<br>    if (piece_buf) free(piece_buf);<br>    <br>    return result;<br>}</pre><p>Hope this article suits you well into exploring other things. I know it’s not perfect, but it’s very rewarding to be able to download a file with your own program. You should definitely try it out.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=eac59c8d93eb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Making a GBA emulator]]></title>
            <link>https://medium.com/@julio.vidaurre/making-a-gba-emulator-fbf91b85979a?source=rss-548808e7edf7------2</link>
            <guid isPermaLink="false">https://medium.com/p/fbf91b85979a</guid>
            <dc:creator><![CDATA[Julio Vidaurre]]></dc:creator>
            <pubDate>Sun, 23 Mar 2025 23:46:09 GMT</pubDate>
            <atom:updated>2025-03-23T23:46:09.350Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gIBrAy9mzOb4tKlwY6KFZg.jpeg" /></figure><p>An emulator of a game console is an interesting programming project, especially if you have some long memories with it. It is an adventure to deep dive into low-level programming, hands-on a real project (useful to learn or solidify your knowledge on a particular programming language) and fun!.</p><p>This is quite of a personal challenge, to prove myself I can build some thing only by reading the documentation, without using any tutorials (the only way to walking away from tutorials hell). I choose GBA because I played with it a lot when I was a kid (specially Pokemon), so it is a perfect personal motivator.</p><p>I’m not trying to make a whole GBA emulator (there already exists <a href="https://mgba.io/">mGBA</a>), but to be able to simulate a great deal of the CPU and display some image. For this I use a demo-game I made a while ago (following GBADEV) using Mode 3 (video mode to treat VRAM as a bitmap, the easiest mode).</p><p>I decided to use C for this project. I’m not going to post whole pieces of the code here, just explain several thing I had to consider. The complete code is hosted on <a href="https://github.com/juliovr/gba_emu">Github</a>.</p><h3>The CPU</h3><p>The GBA uses a ARM7TDMI processor, which has 2 instruction set: ARM and Thumb. ARM instructions are made of 4 bytes, while Thumb’s of 2 bytes (being able to pack more instructions in cartridge). That add an extra work for the emulator because the are more instructions to decode.</p><p>ARM7TDMI is a pipelined processor with following steps:</p><pre>Fetch      Instruction fetched from memory<br>  |<br>  v<br>Decode     Decoding of registers used in instructions<br>  |<br>  v<br>Execute    Register(s) read from register bank<br>           Perform shift and ALU operations<br>           Write register(s) back to register bank</pre><p>At the beginning I thought it would not be important for the emulation perspective, but it is important when the CPU does branches calculation because it accounts for the prefetched-incremented PC. So, the easiest thing I came up with was to execute the stages in “reverse order”, i.e. call execute(), decode() and fetch(). Doing so, when reaches execute(), the PC is already 2 instructions ahead, exactly what the ARM specification states when doing branches or any other calculation that involves the PC.</p><p>To avoid executing or decoding an instruction when no instruciton has been fetched, just add an if at the beginning of each function to check if there is something to process.</p><pre>static void run()<br>{<br>    execute();<br>    decode();<br>    fetch();<br>}<br><br>static void execute()<br>{<br>    // If no instruction has been fetched, just return.<br>    if (decoded_instruction.type == INSTRUCTION_NONE) return;<br><br>    // ...<br>}<br><br>static void decode()<br>{<br>    // If no instruction has been fetched, just return.<br>    if (current_instruction == 0) return;<br><br>    // ...<br>}<br><br></pre><h3>Fetch</h3><p>Fetch is fairly simple; just take the instruction at the PC.</p><pre>static void fetch()<br>{<br>    if (in_thumb_mode()) {<br>        current_instruction = *(u16 *)get_memory_at(&amp;memory, cpu-&gt;pc);<br>        cpu-&gt;pc += 2;<br>    } else {<br>        current_instruction = *(u32 *)get_memory_at(&amp;memory, cpu-&gt;pc);<br>        cpu-&gt;pc += 4;<br>    }<br>}</pre><h3>Decode</h3><p>I implemented the decode as a series of if statements to check if the mask match with the fetched instruction and assign it to a global variable (there is only 1 instruction decoded at a time).</p><pre>#define INSTRUCTION_FORMAT_BRANCH                 (0b101 &lt;&lt; 25)<br>#define INSTRUCTION_FORMAT_SINGLE_DATA_TRANSFER   (1 &lt;&lt; 26)<br>#define INSTRUCTION_FORMAT_BLOCK_DATA_TRANSFER    (1 &lt;&lt; 27)<br><br>if ((current_instruction &amp; INSTRUCTION_FORMAT_BRANCH) == INSTRUCTION_FORMAT_BRANCH) {<br>    decoded_instruction = (Instruction) {<br>        .type = INSTRUCTION_B,<br>        .offset = current_instruction &amp; 0xFFFFFF,<br>        .L = (u8)((current_instruction &gt;&gt; 24) &amp; 1),<br>    };<br>}<br>else if ((current_instruction &amp; INSTRUCTION_FORMAT_BLOCK_DATA_TRANSFER) == INSTRUCTION_FORMAT_BLOCK_DATA_TRANSFER) {<br>    int opcode = (current_instruction &gt;&gt; 20) &amp; 1;<br>    InstructionType type = 0;<br>    switch (opcode) {<br>        case 0: type = INSTRUCTION_STM; break;<br>        case 1: type = INSTRUCTION_LDM; break;<br>    }<br><br>    decoded_instruction = (Instruction) {<br>        .type = type,<br>        .P = (current_instruction &gt;&gt; 24) &amp; 1,<br>        .U = (current_instruction &gt;&gt; 23) &amp; 1,<br>        .S = (current_instruction &gt;&gt; 22) &amp; 1,<br>        .W = (current_instruction &gt;&gt; 21) &amp; 1,<br>        .L = (current_instruction &gt;&gt; 20) &amp; 1,<br>        .rn = (current_instruction &gt;&gt; 16) &amp; 0xF,<br>        .register_list = current_instruction &amp; 0xFFFF,<br>    };<br><br>    if (decoded_instruction.S) {<br>        decoded_instruction.W = 0; // NOTE: Setting bit 21 (the W bit) has UNPREDICTABLE results, so let&#39;s force to 0.<br>    }<br><br>    // NOTE: R15 should not be used as the base register in any LDM or STM instruction.<br>    assert(decoded_instruction.rn != 15);<br><br>    // NOTE: Any subset of the registers, or all the registers, may be specified. The only restriction is that the register list should not be empty.<br>    assert(decoded_instruction.register_list &gt; 0);<br>}<br>else if ((current_instruction &amp; INSTRUCTION_FORMAT_SINGLE_DATA_TRANSFER) == INSTRUCTION_FORMAT_SINGLE_DATA_TRANSFER) {<br>    int opcode = (current_instruction &gt;&gt; 20) &amp; 1;<br>    InstructionType type = 0;<br>    switch (opcode) {<br>        case 0: type = INSTRUCTION_STR; break;<br>        case 1: type = INSTRUCTION_LDR; break;<br>    }<br><br>    decoded_instruction = (Instruction) {<br>        .type = type,<br>        .I = (current_instruction &gt;&gt; 25) &amp; 1,<br>        .P = (current_instruction &gt;&gt; 24) &amp; 1,<br>        .U = (current_instruction &gt;&gt; 23) &amp; 1,<br>        .B = (current_instruction &gt;&gt; 22) &amp; 1,<br>        .W = (current_instruction &gt;&gt; 21) &amp; 1,<br>        .L = (current_instruction &gt;&gt; 20) &amp; 1,<br>        .rn = (current_instruction &gt;&gt; 16) &amp; 0xF,<br>        .rd = (current_instruction &gt;&gt; 12) &amp; 0xF,<br>        .offset = current_instruction &amp; 0xFFF,<br>    };<br>}</pre><p>Needless to say that each instruction has its own format and has different encoded values.</p><h3>Execute</h3><p>With the instruction already decoded, the execute can be done with a switch statement. Here is an example of the main switch with 2 cases, one for branches and the other for data processing instructions, i.e. arithmentic and logic operations done on registers (the things that the ALU is responsible for). The latter has a lot of logic depending on the instructions, e.g. some of them states that a value should be shifted or rotated or stay the same.</p><p>The branch instructions (and every other instruction that modifies the PC) should invalidate the current fetched instruction. Otherwise, after the execute() will run the decode() with an instruction that it’s no longer valid because the PC was change to somewhere else.</p><pre>InstructionCategory category = instruction_categories[decoded_instruction.type];<br>switch (category) {<br>    case INSTRUCTION_CATEGORY_BRANCH: {<br>        process_branch();<br>    } break;<br>    case INSTRUCTION_CATEGORY_DATA_PROCESSING: {<br>        process_data_processing();<br>    } break;<br>}<br><br>static void<br>process_branch()<br>{<br>    switch (decoded_instruction.type) {<br>        case INSTRUCTION_B: {<br>            if (decoded_instruction.L) {<br>                cpu-&gt;lr = cpu-&gt;pc - 4;<br>                assert(cpu-&gt;pc - 4 == decoded_instruction.address + 4);<br>            }<br><br>            u32 offset = left_shift_sign_extended(decoded_instruction.offset, 24, 2);<br>            cpu-&gt;pc += offset;<br><br>            current_instruction = 0;<br><br>            cpu-&gt;cycles += 3;<br>        } break;<br><br>        case INSTRUCTION_BX: {<br>            cpu-&gt;pc = *get_register(cpu, decoded_instruction.rn) &amp; (-2); // NOTE: PC must be 16-bit align. This clears out the lsb (-2 is 0b1110).<br>            current_instruction = 0;<br><br>            u8 thumb_mode = *get_register(cpu, decoded_instruction.rn) &amp; 1;<br>            set_control_bit_T(thumb_mode);<br><br>            cpu-&gt;cycles += 3;<br>        } break;<br><br>        default: {<br>            assert(!&quot;Invalid instruction type for category&quot;);<br>        }<br>    }<br>}<br><br>static void<br>process_data_processing()<br>{<br>    u8 extra_cpu_cycles = 0;<br><br>    u8 carry = 0;<br>    u32 second_operand = 0;<br>    if (decoded_instruction.I) {<br>        // Immediate with rotate right<br><br>        u8 imm = decoded_instruction.second_operand &amp; 0xFF;<br>        u32 rotate = (decoded_instruction.second_operand &gt;&gt; 8) &amp; 0xF;<br>        // NOTE: This value is zero extended to 32 bits, and then subject to a rotate right by twice the value in the rotate field.<br>        rotate *= 2;<br><br>        second_operand = rotate_right(imm, rotate, 32);<br>        if (rotate == 0) {<br>            carry = CONDITION_C;<br>        } else {<br>            carry = (second_operand &gt;&gt; 31) &amp; 1;<br>        }<br>    } else {<br>        // From register<br><br>        u8 rm_n = decoded_instruction.second_operand &amp; 0xF;<br>        u32 rm = *get_register(cpu, rm_n);<br>        u8 shift = (decoded_instruction.second_operand &gt;&gt; 4) &amp; 0xFF;<br>        ShiftType shift_type = (ShiftType)((shift &gt;&gt; 1) &amp; 0b11);<br>        if (shift &amp; 1) {<br>            // Shift register<br>            extra_cpu_cycles++;<br><br>            u8 rs = (shift &gt;&gt; 4) &amp; 0xF; // Register to the value to shift.<br>            u8 shift_value = (u8)(*get_register(cpu, rs));<br>            <br>            switch (shift_type) {<br>                case SHIFT_TYPE_LOGICAL_LEFT: {<br>                    if (shift_value == 0) {<br>                        second_operand = rm;<br>                        carry = CONDITION_C;<br>                    } else if (shift_value &lt; 32) {<br>                        second_operand = rm &lt;&lt; shift_value;<br>                        carry = (rm &gt;&gt; (32 - shift_value)) &amp; 1;<br>                    } else if (shift_value == 32) {<br>                        second_operand = 0;<br>                        carry = rm &amp; 1;<br>                    } else {<br>                        second_operand = 0;<br>                        carry = 0;<br>                    }<br>                } break;<br>                case SHIFT_TYPE_LOGICAL_RIGHT: {<br>                    if (shift_value == 0) {<br>                        second_operand = rm;<br>                        carry = CONDITION_C;<br>                    } else if (shift_value &lt; 32) {<br>                        second_operand = rm &gt;&gt; shift_value;<br>                        carry = (rm &gt;&gt; (shift_value - 1)) &amp; 1;<br>                    } else if (shift_value == 32) {<br>                        second_operand = 0;<br>                        carry = (rm &gt;&gt; 31) &amp; 1;<br>                    } else {<br>                        second_operand = 0;<br>                        carry = 0;<br>                    }<br>                } break;<br>                case SHIFT_TYPE_ARITHMETIC_RIGHT: {<br>                    if (shift_value == 0) {<br>                        second_operand = rm;<br>                        carry = CONDITION_C;<br>                    } else if (shift_value &lt; 32) {<br>                        second_operand = arithmetic_shift_right(rm, shift_value);<br>                        carry = (rm &gt;&gt; (shift_value - 1)) &amp; 1;<br>                    } else {<br>                        if (((rm &gt;&gt; 31) &amp; 1) == 0) {<br>                            second_operand = 0;<br>                            carry = (rm &gt;&gt; 31) &amp; 1;<br>                        } else {<br>                            second_operand = 0xFFFFFFFF;<br>                            carry = (rm &gt;&gt; 31) &amp; 1;<br>                        }<br>                    }<br>                } break;<br>                case SHIFT_TYPE_ROTATE_RIGHT: {<br>                    if (shift_value == 0) {<br>                        second_operand = rm;<br>                        carry = CONDITION_C;<br>                    } else if ((shift_value &amp; 0xF) == 0) {<br>                        second_operand = rm;<br>                        carry = (rm &gt;&gt; 31) &amp; 1;<br>                    } else {<br>                        second_operand = rotate_right(rm, shift_value &amp; 0xF, 32);<br>                        carry = (rm &gt;&gt; ((shift_value &amp; 0xF) - 1)) &amp; 1;<br>                    }<br>                } break;<br>            }<br><br>        } else {<br>            // Shift immediate 5-bit value<br><br>            u8 shift_value = (shift &gt;&gt; 3) &amp; 0b11111;<br>            <br>            switch (shift_type) {<br>                case SHIFT_TYPE_LOGICAL_LEFT: {<br>                    if (shift_value == 0) {<br>                        second_operand = rm;<br>                        carry = CONDITION_C;<br>                    } else {<br>                        second_operand = rm &lt;&lt; shift_value;<br>                        carry = (rm &gt;&gt; (32 - shift_value)) &amp; 1;<br>                    }<br>                } break;<br>                case SHIFT_TYPE_LOGICAL_RIGHT: {<br>                    if (shift_value == 0) {<br>                        second_operand = 0;<br>                        carry = (rm &gt;&gt; 31) &amp; 1;<br>                    } else {<br>                        second_operand = rm &gt;&gt; shift_value;<br>                        carry = (rm &gt;&gt; (shift_value - 1)) &amp; 1;<br>                    }<br>                } break;<br>                case SHIFT_TYPE_ARITHMETIC_RIGHT: {<br>                    if (shift_value == 0) {<br>                        if (((rm &gt;&gt; 31) &amp; 1) == 0) {<br>                            second_operand = 0;<br>                            carry = (rm &gt;&gt; 31) &amp; 1;<br>                        } else {<br>                            second_operand = 0xFFFFFFFF;<br>                            carry = (rm &gt;&gt; 31) &amp; 1;<br>                        }<br>                    } else {<br>                        second_operand = arithmetic_shift_right(rm, shift_value);<br>                        carry = (rm &gt;&gt; (shift_value - 1)) &amp; 1;<br>                    }<br>                } break;<br>                case SHIFT_TYPE_ROTATE_RIGHT: {<br>                    if (shift_value == 0) {<br>                        second_operand = (CONDITION_C &lt;&lt; 31) | (rm &gt;&gt; 1);<br>                        carry = rm &amp; 1;<br>                    } else {<br>                        second_operand = rotate_right(rm, shift_value, 32);<br>                        carry = (rm &gt;&gt; (shift_value - 1)) &amp; 1;<br>                    }<br>                } break;<br>            }<br>        }<br>    }<br><br><br>    int store_result = false;<br>    u32 result = 0;<br><br>    u32 rn = *get_register(cpu, decoded_instruction.rn);<br>    u32 *rd = get_register(cpu, decoded_instruction.rd);<br>    <br>    switch (decoded_instruction.type) {<br>        case INSTRUCTION_ADD: {<br>            result = rn + second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C((result &lt; second_operand) ? 1 : 0);<br>                set_overflow_addition(rn, second_operand, result);<br>            }<br>        } break;<br>        case INSTRUCTION_AND: {<br>            result = rn &amp; second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br>        case INSTRUCTION_EOR: {<br>            result = rn ^ second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br>        case INSTRUCTION_SUB: {<br>            result = rn - second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(second_operand &lt;= rn ? 1 : 0);<br>                set_overflow_subtract(rn, second_operand, result);<br>            }<br>        } break;<br>        case INSTRUCTION_RSB: {<br>            result = second_operand - rn;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(second_operand &lt;= rn ? 1 : 0);<br>                set_overflow_subtract(second_operand, rn, result);<br>            }<br>        } break;<br>        case INSTRUCTION_ADC: {<br>            // result = rn &amp; second_operand + carry;<br>            result = rn + second_operand + CONDITION_C;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C((result &lt; second_operand) ? 1 : 0);<br>                set_overflow_addition(rn, second_operand + CONDITION_C, result);<br>            }<br>        } break;<br>        case INSTRUCTION_SBC: {<br>            // result = rn - second_operand + carry - 1;<br>            result = rn - second_operand - ~(CONDITION_C);<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(second_operand &lt;= rn ? 1 : 0);<br>                set_overflow_subtract(rn, second_operand - ~(CONDITION_C), result);<br>            }<br>        } break;<br>        case INSTRUCTION_RSC: {<br>            // result = second_operand - rn + carry - 1;<br>            result = second_operand - rn - ~(CONDITION_C);<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(second_operand &lt;= rn ? 1 : 0);<br>                set_overflow_subtract(second_operand, rn - ~(CONDITION_C), result);<br>            }<br>        } break;<br>        case INSTRUCTION_TST: {<br>            result = rn &amp; second_operand;<br>            store_result = false;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br>        case INSTRUCTION_TEQ: {<br>            result = rn ^ second_operand;<br>            store_result = false;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br>        case INSTRUCTION_CMP: {<br>            result = rn - second_operand;<br>            store_result = false;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(second_operand &lt;= rn ? 1 : 0);<br>                set_overflow_subtract(rn, second_operand, result);<br>            }<br>        } break;<br>        case INSTRUCTION_CMN: {<br>            result = rn + second_operand;<br>            store_result = false;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C((result &lt; second_operand) ? 1 : 0);<br>                set_overflow_addition(rn, second_operand, result);<br>            }<br>        } break;<br>        case INSTRUCTION_ORR: {<br>            result = rn | second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br>        case INSTRUCTION_MOV: {<br>            result = second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br>        case INSTRUCTION_BIC: {<br>            result = rn &amp; ~second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br>        case INSTRUCTION_MVN: {<br>            result = ~second_operand;<br>            store_result = true;<br><br>            if (decoded_instruction.S == 1 &amp;&amp; decoded_instruction.rd == 15) {<br>                cpu-&gt;cpsr = *get_spsr_current_mode(cpu);<br>            } else if (decoded_instruction.S == 1) {<br>                set_condition_Z(result == 0);<br>                set_condition_N(result &gt;&gt; 31);<br>                set_condition_C(carry);<br>            }<br>        } break;<br><br>        default: {<br>            assert(!&quot;Invalid instruction type for category&quot;);<br>        }<br>    }<br><br>    if (store_result) {<br>        *rd = result;<br><br>        if (decoded_instruction.rd == 15) {<br>            current_instruction = 0;<br>            <br>            extra_cpu_cycles += 2;<br>        }<br>    }<br><br>    cpu-&gt;cycles += 1 + extra_cpu_cycles;<br>}</pre><h3>Memory</h3><p>Here is an interesting thing about the console in general. The GBA has several “blocks” of memory which serves a specific purporse (could be group as General Internal memory, Internal Display memoryand Game pak (cartridge).</p><pre>General Internal Memory<br><br>  00000000-00003FFF   BIOS - System ROM         (16 KBytes)<br>  00004000-01FFFFFF   Not used<br>  02000000-0203FFFF   WRAM - On-board Work RAM  (256 KBytes) 2 Wait<br>  02040000-02FFFFFF   Not used<br>  03000000-03007FFF   WRAM - On-chip Work RAM   (32 KBytes)<br>  03008000-03FFFFFF   Not used<br>  04000000-040003FE   I/O Registers<br>  04000400-04FFFFFF   Not used<br><br>Internal Display Memory<br><br>  05000000-050003FF   BG/OBJ Palette RAM        (1 Kbyte)<br>  05000400-05FFFFFF   Not used<br>  06000000-06017FFF   VRAM - Video RAM          (96 KBytes)<br>  06018000-06FFFFFF   Not used<br>  07000000-070003FF   OAM - OBJ Attributes      (1 Kbyte)<br>  07000400-07FFFFFF   Not used<br><br>External Memory (Game Pak)<br><br>  08000000-09FFFFFF   Game Pak ROM/FlashROM (max 32MB) - Wait State 0<br>  0A000000-0BFFFFFF   Game Pak ROM/FlashROM (max 32MB) - Wait State 1<br>  0C000000-0DFFFFFF   Game Pak ROM/FlashROM (max 32MB) - Wait State 2<br>  0E000000-0E00FFFF   Game Pak SRAM    (max 64 KBytes) - 8bit Bus width<br>  0E010000-0FFFFFFF   Not used<br><br>Unused Memory Area<br><br>  10000000-FFFFFFFF   Not used (upper 4bits of address bus unused)</pre><p><em>(from </em><a href="https://problemkaputt.de/gbatek.htm#gbamemorymap"><em>GBATEK</em></a><em>)</em></p><p>The processor being a 32-bit, it can address up to 2³² = 4GB of memory and the GBA indeed has mapping to some high-addresses to memory, but that doesn’t mean it used all of it (as you can see, there are a lot of unused mapping there).</p><p>Reading through the documentation, the unused parts of memory are in fact “mirror” from the previous parts, i.e. for the CPU point of view, is the same memory. That’s why it’s a good idea to access the memory using a method instead of directly on the array type.</p><p>Here is an example:</p><pre>typedef struct GBAMemory {<br>    // General Internal Memory<br>    u8 bios_system_rom[16*KILOBYTE];<br>    u8 ewram[256*KILOBYTE];<br>    u8 iwram[32*KILOBYTE];<br>    u8 io_registers[1*KILOBYTE];<br><br>    // Internal Display Memory<br>    u8 palette_ram[1*KILOBYTE];<br>    u8 vram[96*KILOBYTE];<br>    u8 oam_obj_attributes[1*KILOBYTE];<br><br>    // External Memory (Game Pak)<br>    u8 game_pak_rom[32*MEGABYTE];<br>    u8 game_pak_ram[64*MEGABYTE];<br>} GBAMemory;<br><br>u8 * get_memory_at(GBAMemory *gba_memory, u32 at)<br>{<br>    // General Internal Memory<br>    if (at &lt;= 0x00003FFF) return (gba_memory-&gt;bios_system_rom + (at - 0x00000000));<br>    if (at &lt;= 0x01FFFFFF) assert(!&quot;Invalid memory&quot;);<br><br>    // The BIOS has no replication.<br><br><br><br>    // EWRAM goes from 0x02000000 to 0x0203FFFF<br>    if (at &lt;= 0x0203FFFF) return (gba_memory-&gt;ewram + (at - 0x02000000));<br><br>    // But the next sections of memory also refers to the EWRAM (repeats every 256KB block, the size of EWRAM).<br>    if (at &lt;= 0x02FFFFFF) {<br>        at &amp;= 0xFFFFF; // Just consider the last 256KB of the value.<br>        at %= 0x40000; // Get rid of high parts of the value (refered to the replication block).<br><br>        return (gba_memory-&gt;ewram + at);<br>    }</pre><h3>Condition flags</h3><p>Every processor has condition flags to make logic afterwards, like the Z (Zero) flag, which is set when the previous operation yields zero, as an subtraction, compare (for an if statement, for example), etc. I had many errors dealing with the differences between C (Carry) and V (Overflow) flags. Here are the key differences:</p><ul><li>C flag: Deals with unsigned arithmetic. It is set when there is an overflow in an unsigned sense (carry out of the register). In other words, if the new value does not fit in the register size, this flag is set.</li><li>V flag: Deals with signed arithmetic. See <a href="https://teaching.idallen.com/dat2343/10f/notes/040_overflow.txt">https://teaching.idallen.com/dat2343/10f/notes/040_overflow.txt</a> for complete reference.</li></ul><h3>From BIOS to the game</h3><p>I did not intended to reverse engineered the BIOS, so I download one from <a href="https://archive.org/details/gba_bios_202206">internet</a>. The main problem was that once I implemented a big portion of ARM (and Thumb) instructions, the game does not boot up. In fact, the emulation just run into an infinite loop.</p><p>This was a headache that got me stuck for several days and even looking for the dissasembly I could not figured out how to make it work. One day, while viewing the recommendations on youtube, there was a video on reverse engineering with <a href="https://ghidra-sre.org/">GHIDRA</a>, so I thought maybe I could use it (nothing to lose, right?).</p><p>Fortunately, It was a lifesaver. The output were more clear than other tools I used to dissasembly the BIOS. There wasn’t just one problem, but the one that got stuck in an infinite loop was related to screen synchronization (the check if all scanlines were done).</p><pre>     LAB_00001774<br>00001774 81  79           ldrb       r1 ,[r0 ,#offset  DAT_04000006 ]<br>00001776 9f  29           cmp        r1 ,#0x9f<br>00001778 fc  d1           bne        LAB_00001774      ; Loop until the current scanline is not 159 (the last VDraw).</pre><p>So, after implement the interrupts to update the internal “registers” of the count of scanlines (they are not CPU registers, just values in memory that holds IO configurations), the game finally boot up.</p><pre>#define IO_DISPSTAT             ((u16 *)get_memory_at(&amp;memory, 0x4000004))<br>#define IO_VCOUNT               ((u16 *)get_memory_at(&amp;memory, 0x4000006))<br><br>#define CYCLES_HDRAW            960<br>#define CYCLES_HBLANK           272<br>#define CYCLES_SCANLINE         (CYCLES_HDRAW + CYCLES_HBLANK)<br>#define CYCLES_VDRAW            160*CYCLES_SCANLINE<br>#define CYCLES_VBLANK           68*CYCLES_SCANLINE<br>#define MAX_SCANLINE            228<br>#define CPU_CYCLES_PER_FRAME    (280896)<br><br>static u8 current_scanline;<br><br>static void set_lcd_io()<br>{<br>    u32 cycles_current_frame = (cpu-&gt;cycles % CPU_CYCLES_PER_FRAME);<br>    u32 cycles_current_scanline = (cycles_current_frame / CYCLES_SCANLINE);<br><br>    u8 scanline = cycles_current_scanline % MAX_SCANLINE;<br>    if (scanline != current_scanline) {<br>        current_scanline = scanline;<br>        *IO_VCOUNT = current_scanline;<br>    }<br><br>    *IO_DISPSTAT &amp;= 0xFFFC; // Clear last 2 bits<br>    <br><br>    // These 2 conditions update the internal registers for completed scanlines.<br><br>    if (cycles_current_frame &gt; CYCLES_VDRAW &amp;&amp; cycles_current_frame &lt;= CYCLES_VBLANK) {<br>        *IO_DISPSTAT |= 1; // Set bit 0<br>    }<br><br>    if (cycles_current_scanline &gt; CYCLES_HDRAW &amp;&amp; cycles_current_scanline &lt;= CYCLES_HBLANK) {<br>        *IO_DISPSTAT |= 0b10; // Set bit 1<br>    }<br>}<br><br><br>// Changed<br>static void run()<br>{<br>    execute();<br>    set_lcd_io(); // Update here<br>        <br>    decode();<br>    fetch();<br>}</pre><p>It is important to take a look at the interrupts because several functions depends on it.</p><h3>Too slow</h3><p>So far so good, but the program runs extremely slow that makes no sense for a modern computer. The problem? It was emulating 1 instruction and render the screen. Consider that the GBA runs at almost 60 fps, this is a huge processing cost.</p><pre>while (!WindowShouldClose()) {<br>    run();     // Run the CPU pipeline<br>    <br>    render();  // Render the VRAM to the screen.<br>}</pre><p>The correct way is to render ONLY after the GBA has completed the cycles of 1 frame. This means wrap the content of the run() function inside a loop until the count cycles emulated is greater than the CPU’s cycles considered in 1 frame.</p><pre>static u32 current_frame = 0;<br><br>static void run()<br>{<br>    while (cpu-&gt;cycles / CPU_CYCLES_PER_FRAME &lt;= current_frame) {<br>        execute();<br>        set_lcd_io();<br>        <br>        decode();<br>        fetch();<br>    }<br>    <br>    current_frame++;<br>}</pre><h3>Final result</h3><p>The tested game is just a dot (a plane) flying around the screen. Had to add debug text to the screen to see many things that wasn’t working.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fcgwF5EKkwkFUvcBFMTynQ.jpeg" /></figure><p>These are some things I had to do to make the first jump into emulating a GBA. Some errors were a real pain (I still have a lot) and have to re-read the documentation available.</p><p>Next steps are trying to display a game in tile mode, i.e. the VRAM stores the tiles bitmap and how they are layout into the screen (saving a lot of memory) instead of using the VRAM as a bitmap where 2 bytes is 1 pixel in the screen (very easy to display, but use a lot of memory).</p><h3>References</h3><ul><li><a href="https://problemkaputt.de/gbatek.htm">GBATEK</a></li><li><a href="https://www.cs.rit.edu/~tjh8300/CowBite/CowBiteSpec.htm">CowBite</a></li><li><a href="https://ww1.microchip.com/downloads/en/DeviceDoc/DDI0029G_7TDMI_R3_trm.pdf">ARM7TDMI Reference Manual</a></li><li><a href="https://www.intel.com/programmable/technical-pdfs/654202.pdf">ARM Architecture Reference Manual</a></li><li><a href="https://www.dwedit.org/files/ARM7TDMI.pdf">ARM7TDMI Data Sheet</a></li><li><a href="https://gbadev.net/tonc/hardware.html">GBADEV: tutorials to make games</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fbf91b85979a" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>