Josip Seketa

What motivated this long and arduous journey

2026-09-12T00:00:00Z

Introduction

Why the fuck did I need this and what it brought upon me?

Problem statement

In search of the architecture

2026-09-12T00:00:00Z

Introduction

Stumbling in the dark, searching for meaning and an architecture that could fulfill the ever changing requirements and optimizations.

Cleware USB Multiplexer 1x8. Photo: Cleware.

USB 3.0 digital multiplexer

Two ways to draw a diagram

2026-08-22T00:00:00Z

Every diagram here is written as plain text. The left column is Mermaid, parsed in your browser. The right is Graphviz, compiled to SVG before the page was built. Same information, two engines, and the differences are the point.

Both are self-hosted, so this page still makes no third-party requests. Mermaid costs 3.4 MB of JavaScript and is opt-in per page — no other post on this site loads it. Graphviz costs nothing at runtime; it runs on my machine and ships a static SVG.

Everything below follows the theme toggle in the header. Mermaid re-renders on a palette change; the Graphviz SVGs are inlined rather than linked, so the same CSS variables that colour this page colour them.

Flowchart

The two-stage login from the OGame scraper.

Mermaidin the browser

flowchart TD
    A[POST credentials] -->|valid| B[200 OK<br/>bearer token]
    A -->|invalid| C[403 Forbidden]
    B --> D[GET accounts]

Graphvizat build time

Graphviz was told to put both outcomes on one rank and to keep the dead branch out of the layout calculation. Mermaid decides for itself.

The Graphviz source says things Mermaid has no syntax for:

{ rank=same; ok; bad }                   // the fork reads as a fork
post -> ok  [label="valid", weight=10];  // straighten the path that matters
post -> bad [constraint=false];          // dead end stops distorting layout
ok:e -> acct:w;                          // exact compass attach points

State machine

The SWJ-DP, and the one-way door into a locked part.

Mermaidin the browser

stateDiagram-v2
    [*] --> JTAG: power-up
    JTAG --> SWD: 0xE79E
    SWD --> JTAG: 0xE73C
    SWD --> Locked: SWJ_CFG=100
    Locked --> SWD: BOOT0 + reset

Graphvizat build time

Mermaid's stateDiagram-v2 knows what a start state is; in Graphviz it is a small filled circle you draw yourself.

Class diagram

Mermaidin the browser

classDiagram
    class Service {
        +String name
        +Number port
        +start()
    }
    class UniverseService {
        +exists(name, lang)
    }
    class AccountService {
        +listForPlayer(token)
    }
    Service <|-- UniverseService
    Service <|-- AccountService

Graphvizat build time

Mermaid has real class semantics. Graphviz is drawing a record shape that happens to look like a class.

That <|-- is worth a note. A shortcode that passes its body through unescaped hands the browser a < followed by a pipe, and the parser has opinions. Escaping it is what makes the class diagram survive.

Entity relationship

Mermaidin the browser

erDiagram
    PLAYER ||--o{ ACCOUNT : owns
    ACCOUNT }o--|| UNIVERSE : "lives in"
    UNIVERSE {
        string name
        string language
        int playerCount
    }
    ACCOUNT {
        string id
        string server
    }

Graphvizat build time

Crow's feet are built into Mermaid. Graphviz needs the cardinality written on the edge as a label.

Commit history

Mermaidin the browser

gitGraph
    commit id: "jekyll"
    branch zola
    checkout zola
    commit id: "port content"
    commit id: "workshop design"
    commit id: "diagrams"

Graphvizat build time

A git graph is a directed acyclic graph, which is the thing Graphviz was built for. This is the one where it is arguably the better fit.

Where Graphviz simply has nothing

Three of the diagram types below have no Graphviz equivalent. Not a harder equivalent — none. Graphviz draws graphs: nodes joined by edges. A sequence diagram is a timeline, a gantt is a calendar, a pie is a proportion, and none of those are graphs.

Sequence

sequenceDiagram
    participant H as Host
    participant T as Target
    H->>T: 8-bit request
    Note over H,T: turnaround
    T-->>H: 3-bit ACK
    Note over H,T: turnaround
    H->>T: 32 data bits + parity

Mermaid only. The turnaround periods are the part that is easy to miss when reading the SWD spec.

Gantt

gantt
    title Posts, by project
    dateFormat YYYY-MM-DD
    axisFormat %Y
    section STM32
    Setting it all up      :done, 2018-06-02, 90d
    How SWD actually works :active, 2026-08-21, 60d
    section OGame
    Initial design         :done, 2020-08-23, 40d
    Microservices          :done, 2020-09-27, 40d
    section Go
    Golang notes           :done, 2022-10-16, 60d

Mermaid only. The publishing history of this site, including the silences.

Pie

pie showData
    title Code in these posts, by language
    "C" : 96
    "ARM asm" : 34
    "JavaScript" : 88
    "JSON" : 62
    "Makefile" : 44

Mermaid only.

Bars

xychart-beta horizontal
    title "Code in these posts, by language"
    x-axis [C, "ARM asm", JavaScript, JSON, Makefile]
    y-axis "lines" 0 --> 100
    bar [96, 34, 88, 62, 44]

Mermaid only. The same numbers as the pie, with the names on the axis instead of in a legend.

What the comparison actually shows

Mermaid wins on breadth and on effort. It has diagram types Graphviz will never have, the source lives in the post, and there is no build step. It also renders on GitHub, so the markdown is not inert in the repository.

Graphviz wins on control and on weight. rank, weight, constraint, group and compass ports let you insist on an arrangement rather than accept one, and the reader downloads no JavaScript at all. The cost is a separate file per diagram and a script that has to run before the site builds.

The honest split: Mermaid for diagrams where the shape does not carry meaning, Graphviz when it does or when the page should stay free of JavaScript. Neither is the default; the diagram decides.

How SWD actually works

2026-08-21T00:00:00Z

In the first post I wired six pins between the J-Link and the blue pill, typed connect, and the chip answered. That was enough to get a LED blinking, but “it answered” is not an explanation. Two of those six wires do all the work, and I wanted to know what they were actually saying.

Why two wires and not five

JTAG wants TCK, TMS, TDI and TDO, and usually NJTRST as well. On a 48-pin part that is a lot of pins to spend on something you only need while developing.

Serial Wire Debug does the same job with two: SWDIO for data and SWCLK for the clock. On the STM32F103 the two protocols share pins, and the debug block that arbitrates between them is called the SWJ-DP:

Pin	JTAG	SWD
PA13	JTMS	SWDIO
PA14	JTCK	SWCLK
PA15	JTDI	free
PB3	JTDO	TRACESWO
PB4	NJTRST	free

Choosing SWD hands PA15 and PB4 back to you as ordinary GPIO, and leaves PB3 available for trace output if you want it. There is a way to lose all of this permanently, which I get to at the end.

The wire protocol

SWCLK is always driven by the host. SWDIO is bidirectional, and both ends follow the same rule: drive SWDIO on the falling edge of SWCLK, sample it on the rising edge.

Turnaround

Because one line carries both directions, there has to be a moment where nobody drives it while ownership changes. That is the turnaround period, one clock cycle by default, and it happens twice in every transaction: after the host finishes its request, and again after the target finishes its reply.

Drawn out, one whole read looks like this:

A read transaction; P is the parity bit. The two z regions are the turnarounds: neither end is driving, which is what makes a single-wire bidirectional bus possible.

Line states

Two more line states matter:

Line reset — at least 50 clock cycles with SWDIO held high. This puts the debug port into a known state, and is how every session starts.
Idle — clocks with SWDIO low. The target needs these to finish posted work, which turns out to matter more than it sounds like it should.

Bit-banging it

Bit-banging the physical layer is two functions:

swd.c

static void swd_clock_out(int bit)
{
	swclk_low();          /* target samples on the rising edge, so set up now */
	swdio_write(bit);
	delay();
	swclk_high();
	delay();
}

static int swd_clock_in(void)
{
	int bit;

	swclk_low();          /* target drives SWDIO here */
	delay();
	swclk_high();
	bit = swdio_read();   /* sample on the rising edge */
	delay();

	return bit;
}

Convincing the chip to speak SWD

After power-up the SWJ-DP may still be listening for JTAG. Switching it over is a fixed incantation:

Line reset: 50 or more clocks, SWDIO high.
Send the 16-bit JTAG-to-SWD select sequence 0xE79E, least significant bit first, so 0111 1001 1110 0111 goes out on the wire.
Line reset again.
Read the DP IDCODE register. A sane value back means you are in SWD.

reset    1111111111 ... 1111111111    (>= 50 cycles, SWDIO high)
select   0111100111100111             (0xE79E, LSB first)
reset    1111111111 ... 1111111111    (>= 50 cycles)
read     DP register 0x00 (IDCODE)

The mirror-image sequence 0xE73C switches back to JTAG, which I have never had a reason to use.

One transaction

Everything after the handshake has the same shape: an 8-bit request from the host, a 3-bit acknowledgement from the target, and a 33-bit data phase, with a turnaround cycle either side of the acknowledgement.

The request

The request, again LSB first:

Bit	Name	Meaning
0	Start	always 1
1	APnDP	0 = debug port, 1 = access port
2	RnW	0 = write, 1 = read
3	A[2]	register address bit 2
4	A[3]	register address bit 3
5	Parity	even parity over bits 1 to 4
6	Stop	always 0
7	Park	always 1

Or as it sits on the wire:

The 8-bit request, least significant bit first.

Building it

Only two address bits, because the register space is deliberately tiny. The SELECT register does the rest of the addressing. Building a request is four lines:

swd.c

static uint8_t swd_request(int ap, int read, uint8_t addr)
{
	int a2 = (addr >> 2) & 1;
	int a3 = (addr >> 3) & 1;
	int parity = ap ^ read ^ a2 ^ a3;

	return (1      << 0)   /* start */
	     | (ap     << 1)
	     | (read   << 2)
	     | (a2     << 3)
	     | (a3     << 4)
	     | (parity << 5)
	     | (0      << 6)   /* stop */
	     | (1      << 7);  /* park */
}

The acknowledgement and the data

The acknowledgement is three bits, LSB first:

Value	Name	What it means
`0b001`	OK	proceed to the data phase
`0b010`	WAIT	busy, retry the same transaction
`0b100`	FAULT	something is wrong; read CTRL/STAT and clear it

Then 32 data bits, LSB first, followed by one even parity bit covering those 32. On a write the host sends them, on a read the target does. Get the parity wrong and the target quietly ignores the write, which is a miserable bug to find.

Reading memory

Two register banks sit behind that interface. The DP, or Debug Port, is the SWD end itself: IDCODE, ABORT, CTRL/STAT, SELECT, RDBUFF. The AP, or Access Port, is the bridge onto the chip’s bus. The one you want is the MEM-AP, and three of its registers matter: CSW for configuration, TAR for the target address, DRW for the data.

Reading a single word goes like this:

1. write DP SELECT   choose AP 0, register bank 0
2. write AP CSW      32-bit access, auto-increment off
3. write AP TAR      0x08000000
4. read  AP DRW      returns the PREVIOUS result, not this one
5. read  DP RDBUFF   the word you actually asked for

Step 4 is the part that catches everyone. AP reads are posted: the transaction kicks off the read and hands back whatever the last one produced. The value you want arrives on the next read, or out of RDBUFF. Write a driver that reads DRW once and trusts it, and you get a plausible-looking word belonging to the previous operation. That is an evening gone.

The number in the log

The first post has this line in it, straight out of J-Link Commander:

Found SWD-DP with ID 0x1BA01477

At the time I copied past it. It decodes cleanly:

Bits	Value	Meaning
31 - 28	`0x1`	version 1
27 - 12	`0xBA01`	part number: Cortex-M3 SW-DP
11 - 1	`0x23B`	designer: ARM (JEP106)
0	`1`	always 1

0xBA01 is the serial wire debug port; the JTAG one is 0xBA00. So that line is the chip confirming the protocol switch worked — which is exactly the thing I had assumed rather than checked.

SWO, the optional third wire

The wiring list in the first post has SWCLK and SWDIO, and then SWO going to PB3. That one is not part of SWD at all.

SWO is Serial Wire Output: a one-way trace channel from the ITM, through the TPIU, out on PB3. It gives you a printf-shaped debug channel without spending a USART on it, and without the timing damage a breakpoint does. It is independent of the two-wire protocol above — SWD runs perfectly well with PB3 unconnected, which is how I had it for a long time before wiring it.

How to lock yourself out

The SWJ-DP configuration lives in AFIO_MAPR, in the SWJ_CFG[2:0] field:

Value	Effect
`000`	full SWJ: JTAG and SWD both available (reset state)
`001`	full SWJ, but NJTRST released as GPIO
`010`	JTAG disabled, SWD enabled: frees PA15, PB3, PB4
`100`	JTAG and SWD both disabled

010 is the useful one. 100 is how you brick a development board: the moment that write lands the debugger has no way in, and it lands again a few milliseconds after every reset.

The way out is BOOT0. Pulling it high and resetting starts the factory bootloader, which never touches AFIO_MAPR, so the debug port stays alive long enough to erase the flash. Connect-under-reset does the same job by grabbing the port in the gap before your code runs. Neither is enjoyable at midnight, so it is worth knowing before you write to that field rather than after.

Where the real answers are

Two documents, and they disagree with nobody:

ARM Debug Interface Architecture Specification, ADIv5 (IHI0031) — the protocol itself: framing, parity, and the DP and AP register maps.
RM0008, the STM32F103 reference manual — the chip-specific half: pin mapping, AFIO_MAPR, and what the trace hardware will do.

None of this is anything the datasheets do not already say. It just took me longer than I expected to find where they said it.

Golang notes

2022-10-16T00:00:00Z

Introduction

Installing the Go environment has never been easier: download the executable, run it, and you have a working installation.

Go is an open source programming language from Google, originally developed for Google’s own needs — large codebases, many engineers, slow builds.

First program

Every Go program starts in package main, with a main function as the entry point. The fmt package (short for formatting) handles input and output.

hello.go

package main

import "fmt"

func main() {
	fmt.Println("Hello world!")
}

Run it directly with go run hello.go, or compile a binary with go build.

Microservices

2020-09-27T00:00:00Z

Checking if the universe exists with test cases and code coverage.

ROUTE: /universe/exists

METHOD: POST

NAME: Universe exists

PORT: 4000

Description:

accepted arguments
- name
- language
returns
- if server exists return server data as json
- if server does not exist return error message

ERRORS:

server not reachable
server not found

Example server data:

{
"language":"ar",
"number":117,
"name":"Quantum",
"playerCount":1005,
"playersOnline":20,
"opened":"2016-05-06T11:15:08+0000",
"startDate":"2016-05-06T11:15:08+0000",
"endDate":null,
"serverClosed":0,
"prefered":0,
"signupClosed":0,
"settings":{
	"aks":1,
	"fleetSpeed":2,
	"wreckField":1,
	"serverLabel":"empty",
	"economySpeed":7,
	"planetFields":30,
	"universeSize":6,
	"serverCategory":"miner",
	"espionageProbeRaids":0,
	"premiumValidationGift":8000,
	"debrisFieldFactorShips":50,
	"researchDurationDivisor":2,
	"debrisFieldFactorDefence":0
	}
}

Allowing only the POST method in expressjs:

app.route('/universe/exists')
.post(function(req, res) {
	if (req.headers['content-type'] === 'application/json') {
		queryObj = {
			name: req.body.name,
			language: req.body.language,
		};

		universe.exists(queryObj)
		.then(result => res.status(result.status).send(result.body));	
	};
	if (req.headers['content-type'] !== 'application/json') {
		res.status(400).send('Only accepting Content-Type: application/json');
	};
	
})
.all(function(req, res) {
	res.header('Access-Control-Allow-Methods', 'POST');
	res.status(405).send();
});

Initial design

2020-08-23T00:00:00Z

I would like the take the very first paragraph to get the logical basics down. Programming implementation down the road is “just” a question of a language syntax.

Before I wrote anything there was reconnaisance to be made. With the help of the Chrome Developer tools I recorded the steps needed to login to the overview page (automatic redirect).

Firstly I needed to set the minimum goal. The goal was to successfully login to the game and just output the pure html; if successful I would get the wall of text in the console, otherwise just a short piece of redirect code (HTTP 301¹).

Using apitester.com for quick and dirty test.

If successful, the post request should return the token, among other things.

Request url:

https://gameforge.com/api/v1/auth/thin/sessions

Request method:

POST

Request body:

identity=YOUR_EMAIL&password=YOUR_PASSWORD&locale=de_DE&gfLang=de&platformGameId=1dfd8e7e-6e1a-4eb1-8c64-03c3b62efd2f&gameEnvironmentId=0a31d605-ffaf-43e7-aa02-d06df7116fc8&autoGameAccountCreation=false

Request valid response body:

{"token":"e9f942cc-b714-462b-91bb-ef91b40f08d1",
"isPlatformLogin":true,
"isGameAccountMigrated":false,
"platformUserId":"95ddac3a-d1b6-4160-9a5b-2a623f8d94de",
"isGameAccountCreated":false,
"hasUnmigratedGameAccounts":false}

Request invalid response body:

{"error":{"message":"Forbidden"}}

The whole flow, then, is one POST that forks:

flowchart LR
    A[POST credentials] -->|valid| B[200 OK<br/>bearer token]
    A -->|invalid| C[403 Forbidden]
    B --> D[GET accounts<br/>for this player]

The POST either yields a bearer token or it does not; only the token branch continues.

Let’s see how the first step looks like. Used library: request-promise ² Success criteria: fetch all the accounts bound to the user/player

const rp = require('request-promise')
var user_agent = 'Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.132 Safari/537.36';
const tough = require('tough-cookie');
var jar = rp.jar();

var links = {
	post: 'https://gameforge.com/api/v1/auth/thin/sessions',
	accounts: 'https://lobby.ogame.gameforge.com/api/users/me/accounts'
};

login_post_options = {
			method: 'POST',
			uri: links.post,
			headers: {'User-Agent': user_agent},
			form: {				
				'identity': process.env.OGAME_EMAIL,
				'password': process.env.OGAME_PASSWORD,
				'locale': 'de_DE',
				'gfLang': 'de',
				'platformGameId': '1dfd8e7e-6e1a-4eb1-8c64-03c3b62efd2f',
				'gameEnvironmentId': '0a31d605-ffaf-43e7-aa02-d06df7116fc8',
				'autoGameAccountCreation': 'false'
			},
			jar: jar,
			resolveWithFullResponse: true,
			json: true
};

get_options = {
	accounts: {
		method: 'GET',
		uri: links.accounts,
		headers: {
			'User-Agent': user_agent,
			'Authorization': null
			},
		followAllRedirects: false,
		jar: jar,
		resolveWithFullResponse: true,
		json: true
	}
};

async function set_authorization_token(token) {
	get_options.accounts.headers.Authorization = 'Bearer ' + token;
};

async function get_accounts () {
try {
	//first post request - 1st step login
	let post = await rp(login_post_options)
	set_authorization_token(post.body.token);
	//get all the accounts
	let account = await rp(get_options.accounts);
	return account.body;
	}
	catch (error) {
		console.log(error);
	};
};

get_accounts().then(result => console.dir(result,{depth: null}));

More on HTTP codes: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

https://github.com/request/request-promise, deprecated as of 1st of April 2020

Setting it all up

2018-06-02T00:00:00Z

Introduction

After some time sifting through code and making/breaking things, I decided to put stuff in writing.

Beginning was with an IDE. I migrated since to command line compiling and linking tools to better understand the background and how the things work.

Chip of choice is STM32F103C8 commonly known as the blue pill, named so after a size factor and PCB color.

Tools of choice: open source and widely used. GNU gcc for ARM microcontroller and GNU ld linker. For flashing the chip I use JLink for uploading the hex file.

Why does binary file format suck? When you need to put variables at exact memory address in address space, binary file format fills everything with blank space up until the declared variable, and that can grow to a quite big size. When I discovered this, I was perplexed why my binary file was cca 1 GB in size, instead of a few KBs. That’s why I switched to Intel hex format, or more popularly called just hex. JLink flash utility supports binary AND hex formats, amongst others.

A little background about the tools needed. Compiler transforms source code to object files, and linker pieces the bits together to produce one ouput file, which is then ready to be uploaded to the chip with a flash tool.

We’re going to start with the simplest possible example. Blinking the led inaccurately and with an uninitialized clock source, which defaults to 8 MHz internal RC clock.

What does it tell us? That the linker, compiler and uploader work correctly. With a proper stepping stone, we are always free to break and make things, for example “code refactoring”, fancy name for rewriting code because you don’t like it, think it’s ugly or it’s a depressing Saturday afternoon.

Entry to the main program

After compiler and linker together make a salad, where does it start? Does it start in a random chunk of memory, and if not, how can I tell them where to exactly start?

For that we have a global start function as an entry to the program. If a global directive is missing for a symbol, that symbol will not be placed in the object code’s export table, so linker has no way of knowing about the symbol. We also need to put the address of the stacktop right at the beginning of memory space. After that comes the reset address, where the microcontroller ALWAYS ends up first after resetting.

After we have defined global entry in the program (for the linker) and reset entry, we can add a path that leads to our main function (entry to our c part of the program).

startup.s

.global _start
_start:
stacktop: .word 0x20001000
.word reset
.word hang

reset:
	bl notmain
	b hang
.thumb_func
hang:   b .

Recommendation

I can also recommend a really good github repository from dwelch67 that got me on the right track. dwelch67’s repository

Majority of code during this post will be explaining the code that can be found in the link above, with simplifications and modifications.

I am not going to say to copy all from somebody else. But for the beginning I recommend it because they made it work, and it should also work when compiled and flashed. After we have that working base example, then comes the creativity and design choices in question.

Functions for direct register access

We are going to need a function to directly access registers and also fill them with data. Functions used are assembler functions PUT32 and GET32. Assembler functions can be used directly in C program code and first four registers are filled with function paramaters. That means that the r0 registers will be filled with the first function parameter up until r3. Square brackets signify that the value in the register is meant as an address. .globl keyword signifies that the function is global and accessible anywhere.

startup.s

.globl PUT32
PUT32:
	str r1,[r0]
	bx lr

.globl GET32
GET32:
	ldr r0,[r0]
	bx lr
	
.globl dummy
	dummy:
	bx lr

Getting the led up and running

Bluepill board has a led light connected to the PC13 pin. We need to enable clock for port C, initialize the pin as a push pull output, then toggle the pin.

programentry.c

void PUT32 ( unsigned int, unsigned int );
unsigned int GET32 ( unsigned int );
void dummy ( unsigned int );

//define address base for port C
#define GPIOCBASE 0x40011000
//define address base for clock control
#define RCCBASE 0x40021000

//our entry point into the program, defined in our assembler file
int notmain ( void )
{
	unsigned int ra;
	unsigned int rx;

	ra=GET32(RCCBASE+0x18);
	ra|=1<<4; //enable port c
	PUT32(RCCBASE+0x18,ra);
	//config
	ra=GET32(GPIOCBASE+0x04);
	ra&=~(3<<20);   //PC13
	ra|=1<<20;      //PC13
	ra&=~(3<<22);   //PC13
	ra|=0<<22;      //PC13
	PUT32(GPIOCBASE+0x04,ra);

	for(rx=0;;rx++)
	{
		PUT32(GPIOCBASE+0x10,1<<(13+0));
		for(ra=0;ra<200000;ra++) dummy(ra);
		PUT32(GPIOCBASE+0x10,1<<(13+16));
		for(ra=0;ra<200000;ra++) dummy(ra);
	}
	return(0);
}

Bits that interest us:

RCC_APB2ENR	…	bit 4	…
0x018 offset	…	IOPCEN	…

Taken from page 153 of the manual. We are putting 1 into the bit 4 of the APB2 clock enable register to turn on the clock for the port C peripherals.

Link for creating the tables: https://ozh.github.io/ascii-tables/

GPIO configuration registers are split into two registers: Low and High. Low register contain the pins from 0 to 7 and High contain pins from 8 to 15.

Bits that interest us:

GPIOx_CRH	…	Bits 23-22	Bits 21-20	…
0x04 offset	…	CNF13[1:0]	MODE13[1:0]	…

Taken from page 188 of the manual. We are setting the values in the bits 20-21 for the pin mode and 22-23 for the configuration mode of the pin.

On the page 167 we may read about valid bit combos for those four bits.

CNFy[1:0]	In input mode (MODE[1:0]=00)	In output mode(MODE[1:0]>00)
for CRH	00: Analog mode	00: General purpose output Push-pull
y = 8…15	01: Floating input	01: General purpose output Open-drain
for CRL	10: Input with pull-up / pull-down	10: Alternate function output Push-pull
y = 0…7	11: Reserved state	11: Alternate function output Open-drain

MODEy[1:0]
for CRH	00: Input mode (reset state)
y = 8…15	01: Output mode, max speed 10 MHz
for CRL	10: Output mode, max speed 2 MHz
y = 0…7	11: Output mode, max speed 50 MHz

For writing your own library, you will need to familiarize yourself with the datashet of the microcontroller, in this case STM32F103C8 RM0008 Reference Manual. The datasheet will be extensively used throughout the posts.

Up until now we have two files: startup.s and programentry.c. Now we need to setup an environment for compiling, linking and flashing.

Linker file

Linker file looks like this:

	MEMORY
	{
		rom : ORIGIN = 0x08000000, LENGTH = 0x1000
		ram : ORIGIN = 0x20000000, LENGTH = 0x1000
	}

	SECTIONS
	{
		.text : { *(.text*) } > rom
		.rodata : { *(.rodata*) } > rom
		.bss : { *(.bss*) } > ram
	}

MEMORY keyword tells us how the memory is organized and how big it is. SECTIONS keyword defines where the types of program data should go. In this example we tell the linker that .text and .rodata should go in ROM part of the memory, and .bss data in the RAM part of the memory. (.bss) => segment for uninitialized data. (.data) => segment for initialized data here by default. (.rodata) => segment for constant data.

I am using GNU ld linker, as a good open source choice widely used. I am not trying to use black magic or obscure tools.

Makefile

Minimum unix tools required are make and rm, both used in the makefile.

Let’s go through the makefile. Here, we are just declaring some variables to make the makefile more readable.

ARMGNU = arm-none-eabi

AOPS = --warn --fatal-warnings -mcpu=cortex-m3
COPS = -Wall -Werror -O2 -nostdlib -nostartfiles -ffreestanding -mcpu=cortex-m0

Here is the first “recipe” in linker terminology, that can be invoked with “make all” or just “make”. Invoking only “make” will execute the first found recipe.

	all : output.hex

Here is the second recipe which is used for a cleanup of produced files, leaving only the source files intact.

clean:
	rm -f *.bin
	rm -f *.o
	rm -f *.elf
	rm -f *.list
	rm -f *.bc
	rm -f *.opt.s
	rm -f *.norm.s
	rm -f *.hex

We are defining rules for compilation of our two source files. startup.o needs startup.s and that’s why we are declaring .s file on the right side as a dependency, and building the file with an assembler (-as, or full blown command arm-linux-gnueabi-as)

startup.o : startup.s
	$(ARMGNU)-as $(AOPS) startup.s -o startup.o

File programentry.c is being compiled here with a gcc compiler. It is also being specified that we are using thumb instruction set (-mthumb), cpu Cortex-M3 (-mcpu=cortex-m3), architecture ARMv7 (armv7-m), that the input file is programentry.c and output file should be programentry.o.

programentry.o : programentry.c	
	$(ARMGNU)-gcc $(COPS) -mthumb -mcpu=cortex-m3 -march=armv7-m -c programentry.c -o programentry.o

Here is the build of the final output file that is going to be flashed on the chip. Our final output file depends on three files. Linker file linker.ld and two object files startup.o and programentry.o compiled from the source files. the source files

	output.hex : linker.ld startup.o programentry.o

Here are the objects linked according to linker file linker.ld and output is an elf file.

		$(ARMGNU)-ld -o output.elf -T linker.ld startup.o programentry.o

Object dump (objdump) is used to dump the contents from an .elf file to the .list file.

		$(ARMGNU)-objdump -D output.elf > output.list

Finally, from the .elf file we get the final output file with objcopy.

		$(ARMGNU)-objcopy output.elf output.hex -O ihex

Hardware used for flashing the chip

I am using Segger’s J-link to flash the chip via the SWD (Single Wire Debugging) interface and am also using JLink v5.10u, an older version of the flashing software. If it works, there’s no reason to continuously update.

Hardware connections are as follows:

J-link Pin 1 = VCCref => Pin 1 SWD Connector
J-link Pin 7 = SWDIO => SWDIO Pin
J-link Pin 9 = SWCLK => SWCLK Pin
J-link Pin 13 = SWO => PB3 Pin
J-link Pin 19 = Target power supply => 3v3 pin of the microcontroller
J-link Pin 4 = Ground Pin => connect to any GND pin of the microcontroller

To enable the J-link to power the target, the following command must be input through the J-link command line: “power on perm”.

To connect to the microcontroller, I run the J-link flash program through the command line. Here is the output.

J-Link Commander

	Microsoft Windows [Version 6.1.7601]
	Copyright (c) 2009 Microsoft Corporation.  All rights reserved.

	C:\Users\Bunny>jlink
	SEGGER J-Link Commander V5.10u (Compiled Mar 17 2016 18:57:13)
	DLL version V5.10u, compiled Mar 17 2016 18:56:47

	Connecting to J-Link via USB...O.K.
	Firmware: J-Link ARM V8 compiled Nov 28 2014 13:44:46
	Hardware version: V8.00
	S/N: 58001139
	License(s): RDI,FlashDL,FlashBP,JFlash
	VTref = 4.801V


	Type "connect" to establish a target connection, '?' for help
	J-Link>connect
	Please specify device / core. <Default>: STM32F103C8
	Type '?' for selection dialog
	Device>
	Please specify target interface:
	  J) JTAG (Default)
	  S) SWD
	TIF>s
	Specify target interface speed [kHz]. <Default>: 4000 kHz
	Speed>
	Device "STM32F103C8" selected.


	Found SWD-DP with ID 0x1BA01477
	Found SWD-DP with ID 0x1BA01477
	Found Cortex-M3 r1p1, Little endian.
	FPUnit: 6 code (BP) slots and 2 literal slots
	CoreSight components:
	ROMTbl 0 @ E00FF000
	ROMTbl 0 [0]: FFF0F000, CID: B105E00D, PID: 001BB000 SCS
	ROMTbl 0 [1]: FFF02000, CID: B105E00D, PID: 001BB002 DWT
	ROMTbl 0 [2]: FFF03000, CID: B105E00D, PID: 000BB003 FPB
	ROMTbl 0 [3]: FFF01000, CID: B105E00D, PID: 001BB001 ITM
	ROMTbl 0 [4]: FFF41000, CID: B105900D, PID: 001BB923 TPIU-Lite
	Cortex-M3 identified.
	J-Link>power on perm
	J-Link>

We are using the “loadfile” command to load the hex file onto the chip. After flashing the chip, we issue “r” for reset and “g” for go command. The led should inaccurately, but happily blink.