Lizard-Spock

Skill or MCP tool? A rule of thumb for Claude integrations

2026-09-13T00:00:00+01:00

The question

While extending my SecondBrain /morning briefing, I wanted to add a couple of small daily extras: a "Daily Stoic" quote, and a "daily knot" tip. Both are just: look up today's entry from a fixed, pre-compiled dataset. The question was whether these belonged in the skillbook (as SKILL.md procedures) or as tools on the SecondBrain MCP server.

It turned out I'd already answered this once without noticing — get_daily_stoic already exists as an MCP tool, not a skill. That accident turned out to be the right call, and thinking through why gave a rule of thumb worth writing down.

The distinction: lookup vs. reasoning

The deciding factor isn't whether the feature calls an external API. It's whether the work being done is lookup or reasoning.

MCP tool — a fixed dataset (say, a JSON or markdown table keyed by date) behind a thin function that does a deterministic lookup. No model judgment is involved in producing the content itself; the same input always returns the same output.
Skill — a procedure the model follows using judgment: formatting rules, what to prioritize, how to phrase things, what to omit. My existing daily-summary skill is a good example — it reasons over goals, actions, and due dates fresh each time, and that reasoning is the value it adds.

A "daily knot" or "daily quote" is a lookup, not a procedure. Building it as a skill would mean stuffing a reference file into context every time the briefing runs and asking the model to "pick today's entry" — non-deterministic, token-heavy, and re-deriving the same answer every session for no benefit.

The practical shape this takes

Curate the data once. For something like knots, that's a one-time content pass — pull entries from reference books into a small structured file (knots.json or similar), living wherever the Stoic dataset already lives on the MCP server. This is content curation, not a recurring skill invocation.
Add a matching tool. A get_daily_knot tool mirroring get_daily_stoic's signature — optional date param in, name/use-case/steps/source out.
Let the skill stay thin. The /morning skill just calls both tools and renders the results under a small section, alongside calendar, actions, and reminders. The skill layer keeps doing what it's good at (formatting, prioritization); the MCP layer keeps doing what it's good at (deterministic data serving).

Why this matters beyond one feature

Keeping lookups out of skills has a few compounding benefits:

Determinism. A tool call returns the same thing for the same date, every time, regardless of which client or model is asking.
Reusability. An MCP tool is available to any MCP client, not just a Claude session with the skillbook loaded.
Cheaper composition. No need to re-read a big reference file into context on every invocation — the skill only pays for the small rendered result.

The one design question this doesn't answer on its own: should a lookup like this rotate by calendar date (fixed 365-entry cycle, like the Stoic quote) or independently (random-but-non-repeating, needing far fewer entries plus a rotation pointer)? That's a smaller decision, but worth making explicitly before building the dataset — it changes how much content curation is actually required up front.

Rule of thumb: if adding the feature means writing a SKILL.md that just tells the model "here's a list, pick today's one" — it's not a skill. Put the list behind a tool, and let the skill call the tool.

Knife Steels Explained: Hardness, Toughness, and Edge Retention

2026-09-12T00:00:00+01:00

Choosing a grind shapes how a blade cuts, but the steel it's made from decides how long that edge lasts, how it fails under stress, and how much upkeep it needs. This is a follow-up to the piece on knife grinds, looking at steel instead of geometry, and at how the two choices work together for bushcraft and general outdoor use.

What actually determines performance

A steel's behaviour comes down to its alloy composition (carbon, chromium, vanadium, molybdenum content) and how it's heat treated. Two knives in the "same" steel can behave differently if one is heat treated to a higher hardness than the other. With that caveat, five properties are worth tracking when comparing steels:

Hardness – resistance to deforming under load, measured on the Rockwell C scale (HRC). Higher hardness generally supports better edge retention but tends to reduce toughness.
Edge retention / wear resistance – how long the edge stays sharp under abrasive use. Driven mainly by hard carbides (vanadium, chromium, molybdenum) embedded in the steel matrix.
Toughness / chip resistance – ability to absorb impact and lateral stress without chipping or cracking. Usually trades off against hardness and wear resistance.
Ease of sharpening – how much work it takes to raise a new edge. Steels with dense, hard carbides resist the sharpening stone as much as they resist the material being cut.
Corrosion resistance – how well the steel resists rust and staining, driven mostly by chromium content (roughly 12%+ for "stainless").

The science underneath

All of the steels here are iron with carbon dissolved in it, plus alloying elements. Heat treatment takes the steel above its transformation temperature so carbon goes into solution, then quenches it fast enough that the carbon has nowhere to go. The result is martensite: a hard, strained crystal structure that gives a blade its hardness. Tempering afterwards relieves some of that strain and trades a little hardness for toughness.

Whatever carbon does not dissolve into the matrix combines with chromium, vanadium, molybdenum, or niobium to form carbides: ceramic-hard particles suspended in the softer steel around them. Carbides are why a steel resists abrasion, and also why it fights the sharpening stone. Their size and distribution matters as much as how many there are, which is the single idea that explains most of what follows.

Why stainless resists rust

Chromium does not protect steel by being tough. It protects by oxidising first. Chromium dissolved in the steel matrix reacts with air to form a chromium-oxide film a few nanometres thick, dense and tightly bonded, and that passive layer blocks oxygen and water from reaching the iron underneath. Scratch it and it reforms almost instantly.

The threshold is around 10.5 to 11% chromium in solution, and that qualifier does the real work. Chromium locked into chromium carbides is not available to form the passive layer. A traditional stainless like 440C carries 17% chromium on the datasheet, but a large share of it is tied up in coarse chromium carbides, so the steel behaves as though it has considerably less. Worse, those carbide particles create local chemistry differences at their boundaries, which is exactly where pitting corrosion starts. High chromium on paper does not automatically mean high corrosion resistance in the hand.

Why carbon steel got its reputation for strength

Simple carbon steels like 1095 or O1 contain almost no chromium, so nearly all their carbon is either in solution or in fine iron carbides. No coarse chromium carbides means a fine, even microstructure, and a fine microstructure means toughness: the steel can absorb impact and lateral load without a crack finding an easy path through a large brittle particle.

That is the real basis for the bushcraft preference. Carbon steel takes a very keen edge because there are no large carbides to interrupt the apex, holds up to batoning without chipping, and sharpens quickly on a basic stone because there is little abrasion-resistant material to remove. It is not stronger in any absolute sense. It is tougher and finer-grained at a given hardness, which for tasks involving wood and impact matters more than raw wear resistance.

The price is rust. With no passive layer, the iron oxidises directly, and a wet knife left in a sheath overnight shows it.

Why modern carbon steels cope better with moisture

It is worth being precise here: carbon steel has not become stainless. What changed is that the gap between the two families filled in.

The middle ground is occupied by semi-stainless tool steels such as CPM CruWear and Vanadis 4E, which carry around 7.5% chromium. That is below the passivation threshold, so they will still patina and can still rust, but corrosion happens far more slowly than with 1095, while toughness stays close to carbon-steel levels. Alongside that, powder metallurgy gave even the low-alloy steels a cleaner, finer structure with fewer inclusions to act as corrosion initiation sites, and practical measures help too: a forced patina of stable black iron oxide, nitrided surfaces, and DLC or Cerakote coatings all buy real-world resistance without changing the alloy.

A modern semi-stainless blade left damp overnight will usually show a grey haze where a 1095 blade would show orange. That is the honest version of the claim.

Why modern stainless caught up on strength

Three developments closed the gap from the other direction.

Powder metallurgy. Conventional ingot steel solidifies slowly, and chromium carbides grow coarse as it does, sometimes tens of microns across. In PM production the molten alloy is gas-atomised into fine powder, each droplet freezing almost instantly, then consolidated under heat and pressure. The carbides never get the chance to grow. The same alloy with carbides an order of magnitude smaller is markedly tougher, takes a finer edge, and is easier to sharpen.

Better carbide chemistry. Vanadium and niobium carbides are harder than chromium carbides and naturally form much smaller particles. Building wear resistance from vanadium and niobium instead of chromium gives better edge retention and leaves the chromium free in solution to do corrosion work.

MagnaCut as the worked example. Larrin Thomas designed CPM MagnaCut around exactly that idea: chromium dropped to about 10.7%, carbon balanced at 1.15% so no chromium carbides form at all, with vanadium, niobium, and 0.2% nitrogen supplying the wear resistance. Every carbide in the finished steel is vanadium or niobium, every atom of chromium is in solution, and the usual pitting initiation sites simply are not there. The result behaves like a tough low-alloy steel that also happens to be properly stainless, which is why it turns up as the reference point in every comparison written since.

The old triangle of edge retention, toughness, and corrosion resistance has not been abolished. It has been pushed outward, and the trade-offs that remain are milder than they were twenty years ago.

Comparison table

Steel	Type	Hardness (HRC)	Edge Retention	Toughness / Chip Resistance	Ease of Sharpening	Corrosion Resistance
1095	High-carbon	56–58	Low–Medium	High	Very Easy	Low (needs oiling/drying)
O1	Carbon tool steel	58–61	Medium	High	Easy	Low
A2	Carbon tool steel	58–62	Medium–High	High	Moderate	Low–Medium
420HC	Budget stainless	55–58	Low	Medium–High	Very Easy	High
AUS-8	Stainless	57–59	Low–Medium	Medium–High	Easy	High
440C	Stainless	56–59	Medium	Medium	Easy	High
VG-10	Stainless	59–61	Medium–High	Medium	Moderate	High
CPM S30V	Premium PM stainless	58–61	High	Medium–High	Moderate–Hard	High
CPM S35VN	Premium PM stainless	58–61	High	High	Moderate	High
CPM-154	Premium PM stainless	58–61	High	High	Moderate	High
Elmax	Premium PM stainless	58–62	High	High	Moderate	Very High
M390	Super steel (PM)	60–62	Very High	Medium–High	Hard	Very High
CPM S90V	Super steel (PM)	59–64	Very High (best-in-class)	Medium	Very Hard	High
CPM MagnaCut	Modern balanced PM	60–62	High–Very High	High	Moderate	Very High

PM = powder metallurgy, a manufacturing process that produces a finer, more evenly distributed carbide structure than traditional ingot steel, generally improving toughness and sharpenability for a given hardness.

Notes on the standouts

Elmax (Bohler-Uddeholm) is often picked as an all-rounder among premium powder-metallurgy steels: strong wear resistance, good toughness, and excellent corrosion resistance, without being as punishing to sharpen as the very top edge-retention steels. It's a sensible choice for a folder or fixed blade that needs to handle both cutting chores and the odd knock without chipping.

CPM S90V sits at the wear-resistance extreme. Its very high vanadium carbide content gives it edge retention that outperforms most other stainless steels by a wide margin, but that same carbide density makes it slow and demanding to sharpen — diamond or CBN abrasives are close to essential — and it gives up some toughness compared to Elmax or S35VN. It rewards knives that get used hard between sharpenings (hunting, processing) rather than ones sharpened frequently by hand.

CPM MagnaCut is newer and worth flagging here even though it's not in the original list: it was designed specifically to balance toughness, corrosion resistance, and edge retention rather than maximise any single property, and it's becoming a common reference point against older "super steels" like S90V and M390.

Carbon steels (1095, O1) remain relevant for bushcraft use: lower wear resistance is offset by being genuinely easy to touch up in the field with a simple stone, at the cost of needing more corrosion care.

What the familiar brands actually use

Four brands most people already own something from, and why each choice makes sense for the knife it is in.

Brand	Steel	Type	Hardness (HRC)	What it optimises for
Leatherman	420HC	Budget stainless	~55–58	Corrosion resistance, easy field sharpening
Leatherman	154CM	Premium stainless	~58–61	Edge retention on upgrade models
Leatherman	CPM MagnaCut	Modern PM stainless	~60–62	Everything at once, at flagship price
Opinel	Carbone XC90	High carbon (~0.9% C)	~55–57	Keen edge, effortless sharpening, low cost
Opinel	Inox 12C27 Mod	Stainless (~0.6% C, ~13.5% Cr)	~56–58	Rust resistance with no upkeep
Victorinox	X55CrMo14 (1.4110)	Martensitic stainless	~56	Toughness in thin blades, easy resharpening
Fallkniven	Laminated VG-10	Stainless core, 420J2 sides	59 core	Edge retention plus lateral strength
Fallkniven	3G (SGPS core, VG2 sides)	Laminated PM stainless	62 core	Hard core, chip resistance from soft flanks
Fallkniven	CoS (Cobalt Special)	Laminated cobalt alloy	~60–61 core	Fine grain, exceptional sharpening response
Fallkniven	Elmax	Monosteel PM stainless	61–62	Wear and corrosion resistance without lamination

Leatherman runs a deliberate three-tier ladder. 420HC on the Wave+, Surge, Signal, Wingman, and Sidekick is a low-carbon stainless that no enthusiast would specify for a dedicated knife, and it is the right call here anyway: a multitool lives in a pocket or on a belt in the rain, gets used for whatever is in front of it, and gets sharpened by someone without a diamond plate. Corrosion resistance and easy sharpening beat edge retention in that job. The Skeletool CX and Charge Plus step up to 154CM for people using the blade as their main knife, and the flagship Arc and Wave Alpha carry CPM MagnaCut, which genuinely beats both on all three axes rather than trading one for another. Note that the tool components, pliers, drivers, and cutters, are a separate engineering problem: they need toughness and fatigue resistance, not edge retention, so blade steel choice tells you nothing about them.

Opinel offers the clearest carbon-versus-stainless comparison available, because you can buy the same knife either way. Carbone XC90 sits at roughly 0.9% carbon, in the same territory as 1095, and it is a superb value proposition: takes a screaming edge on any stone, sharpens in seconds, patinas within a week of cutting fruit, and rusts if you fold it away wet. The Inox version uses Sandvik 12C27 Modified at about 0.6% carbon and 13.5% chromium, a fine-grained stainless run slightly harder than the carbon version in Opinel's heat treatment. The carbon blade is nicer to sharpen and takes a finer edge; the stainless blade forgives neglect. For a knife that lives in a rucksack or gets handed to a cub, the stainless one is the sensible answer.

Victorinox uses a proprietary variant of X55CrMo14 (material number 1.4110), around 0.52% carbon, 15% chromium, and 0.5% molybdenum, hardened at 1040 °C and tempered to an average of 56 HRC. Enthusiasts sometimes dismiss it as soft, which misses the design brief. Swiss Army knife blades are thin, the knives get used as scissors, screwdrivers, and pry bars by people who will never sharpen them properly, and a harder blade in that geometry would chip rather than roll. At 56 HRC the steel is tough, essentially rustproof in normal use, and can be brought back to sharp on a kitchen steel or the bottom of a mug. It is optimised for recoverability, not retention.

Fallkniven takes a different route entirely: laminated blades, where a hard high-performance core is hot-rolled between softer stainless outer layers. The classic F1 and similar models use a VG-10 core at 59 HRC between 420J2 sides, which Fallkniven credits with roughly 20% greater lateral strength than the same blade in solid VG-10. The premium 3G version raises the core to Super Gold Powder Steel at 62 HRC flanked by VG2, and the CoS models use a cobalt-alloyed core, about 1.1% carbon, 16% chromium, 2.5% cobalt, at around 60 to 61 HRC. The principle is the same one that makes a Japanese kitchen knife work: put the hardness exactly where the cutting happens and let the softer flanks absorb bending and impact, so the blade can run a harder core than a monosteel of the same geometry would survive.

Fallkniven also sells several models in Elmax as a monosteel, notably the F1x and S1x in the X-series, hardened to 61–62 HRC, with black tungsten-carbide-coated variants alongside the bare ones. That is the tidiest illustration of the argument in this post: lamination exists to let a hard core sit behind tough flanks, and a powder stainless with fine, evenly distributed vanadium carbides is tough enough at 62 HRC that the blade no longer needs the flanks. Elmax also brings better corrosion resistance than the VG-10 core it replaces. The classic F1 is offered in an Elmax version too, so as with Opinel you can compare construction philosophies in the same knife shape.

Seen together, the pattern is that none of these brands is choosing a "better" or "worse" steel. Leatherman optimises for neglect, Opinel for sharpenability and price, Victorinox for toughness in thin stock, and Fallkniven for putting maximum hardness at the apex without giving up a robust blade. The steel follows the use case.

Pairing steel with grind

A high-wear-resistance steel like S90V on a full flat grind suits controlled, precise cutting where the edge needs to last. The same steel on a scandi grind for bushcraft carving work would be harder to maintain in the field than a tougher, easier-sharpening steel like Elmax or CPM-154 — grind and steel should be chosen together against the actual task, not independently.

Next up: a look at sharpening approaches for these different steel families, including when diamond stones or ceramic rods actually earn their keep.

Sources

E-Shape Open Chord Variations

2026-09-01T00:00:00+01:00

E major is the full six-string open shape, and the same shape barred at any fret becomes the movable "E-shape" chord used throughout the I-IV-V fretboard map. This post closes the open-chord series started with A and D. Each diagram shows the fingering on the left and the intervals that fingering spells on the right.

Base shape: E major

All six strings sound, so with only three distinct notes in the triad there is plenty of doubling. The G string carries the third, and the D string carries a doubled root. Those two strings take almost every variation below.

Suspended: sus4

The G string third moves up one fret to A, the fourth. An open Esus2 is not practical in standard tuning without muting or a stretch that defeats the point of an open chord, so sus4 is the one suspension that stays in the family of easy moves.

Minor and minor seventh

Em lifts the index finger and the open G string gives the minor third. Em7 then releases the doubled root on the D string as well, adding the flat seventh: one fretted note and five open strings, the simplest full chord shape on the guitar.

Dominant seventh and major seventh

E7 makes the same D string move against the major third: release the doubled root to the open D for the flat seventh. It is the I chord in a blues in E (see the 12-bar blues post). Emaj7 takes that string down only one fret instead, to D#, a half step below the root.

Sixth and add9

E6 is the one variation that leaves both the third and the doubled root alone. It adds the pinky on the B string at the second fret, so a fifth becomes C#, the sixth. Eadd9 goes back to the D string and stretches it up to the fourth fret, turning the doubled root into F#, the ninth.

Summary table

Chord	Frets (low to high)	Change from E major
E	022100	base shape
Esus4	022200	G string: 3rd -> 4th
Em	022000	G string: 3rd -> b3 (open)
Em7	020000	Em, plus D string: doubled root -> b7 (open)
E7	020100	D string: doubled root -> b7 (open)
Emaj7	021100	D string: doubled root -> maj7
E6	022120	B string: 5th -> 6th
Eadd9	024100	D string: doubled root -> 9th

From open shape to movable barre

Barre the whole E major shape at any fret and the root moves with it while every relationship above stays intact. An F major barre at the first fret is the open E shape shifted up one. This is the shape behind the "E-shape root on the 6th string" reference in the I-IV-V fretboard map: learn the variations here and the same finger patterns are available anywhere on the neck once barred.

D-Shape Open Chord Variations

2026-08-31T00:00:00+01:00

D major only uses four strings, which makes it the easiest open shape to hear a single finger move clearly against the others. This post works through the same set of variations as the A-shape post, applied to D. Each diagram shows the fingering on the left and the intervals that fingering spells on the right.

Base shape: D major

The D shape splits its work neatly across two strings. The top E string carries the third, so every suspension and the minor happen there. The B string carries a doubled root, so every seventh, the sixth and the add9 happen there instead.

Suspended: sus2 and sus4

Both suspensions move the top string alone, the string carrying the third in the base shape. Lift the ring finger and the open E gives the second; slide that same finger up one fret instead and G gives the fourth.

Minor and minor seventh

Dm takes that same top string down one fret to F, the minor third. Dm7 then moves the B string doubled root down two frets to C, the flat seventh, which puts both fretted notes on the first fret under a single index finger.

Dominant seventh and major seventh

D7 makes the same B string move against the major third: doubled root down to C, the flat seventh. It is the shape most players learn first for a dominant chord, useful as the V in a blues in G (see the 12-bar blues post). Dmaj7 stops one fret higher at C#, a half step below the root.

Sixth and add9

D6 opens the B string, so the doubled root becomes the sixth and the third on the top string stays. Dadd9 moves that same B string the other way, from fret 3 to fret 5, turning the doubled root into the ninth. Both keep the third, which is what separates an add chord from a suspension.

Summary table

Chord	Frets (low to high)	Change from D major
D	xx0232	base shape
Dsus2	xx0230	top E: 3rd -> 2nd (open)
Dsus4	xx0233	top E: 3rd -> 4th
Dm	xx0231	top E: 3rd -> b3
Dm7	xx0211	Dm, plus B string: doubled root -> b7
D7	xx0212	B string: doubled root -> b7
Dmaj7	xx0222	B string: doubled root -> maj7
D6	xx0202	B string: doubled root -> 6th (open)
Dadd9	xx0252	B string: doubled root -> 9th

Next in the series: the E-shape open chord variations.

A-Shape Open Chord Variations

2026-08-30T00:00:00+01:00

The open A shape is one of the first chords most guitarists learn, and one of the most flexible: almost every common variation is a single finger moving from the base triad. Each diagram below shows the fingering on the left and the intervals that fingering spells on the right.

Base shape: A major

A major is the 1-3-5 triad: root, major third, perfect fifth. Four notes sound across five strings, so two of them are doubled. The B string carries the third, and the G string carries a doubled root. Those two strings are where every variation below happens.

Suspended: sus2 and sus4

Suspended chords replace the third with the second or fourth -- no major or minor quality, just tension resolving back to the triad. Both moves happen on the B string. Lift the ring finger and the open B gives the second; slide that same finger up one fret and D gives the fourth.

Minor and minor seventh

Am takes the B string third down one fret to C, the minor third. Am7 then releases the doubled root on the G string to the open G, adding the flat seventh -- one finger fewer than the major shape, not more.

Dominant seventh and major seventh

A7 makes the same move on the G string but against the major third: lift the middle finger, let the G ring open, and the doubled root becomes the flat seventh. The rest of the A major hand does not move. It is the V chord in a blues in D (see the 12-bar blues post). Amaj7 takes that string down only one fret instead, to G#, a half step below the root, for a jazzier and unresolved colour.

Sixth and add9

A6 is the one exception to the single-finger rule. Barre the second fret across the D, G, B and top E strings, and the open high E, a fifth, becomes F#, the sixth. Aadd9 goes back to the G string and stretches it up to the fourth fret, turning the doubled root into B, the ninth. Both keep the third, which is what separates an add chord from a suspension.

Summary table

Chord	Frets (low to high)	Change from A major
A	x02220	base shape
Asus2	x02200	B string: 3rd -> 2nd (open)
Asus4	x02230	B string: 3rd -> 4th
Am	x02210	B string: 3rd -> b3
Am7	x02010	Am, plus G string: doubled root -> b7 (open)
A7	x02020	G string: doubled root -> b7 (open)
Amaj7	x02120	G string: doubled root -> maj7
A6	x02222	top E: 5th -> 6th, barre at fret 2
Aadd9	x02420	G string: doubled root -> 9th

Next in the series: the same treatment for the D-shape and E-shape open chords.

Supports that peel off: a Bambu Studio profile that stops fighting back

2026-08-30T00:00:00+01:00

The print finished four hours ago and it is still in the vice. One pair of pliers has already slipped and put a bright crescent scar across the face of the part. The support block is coming off in flakes, and every flake takes a little of the model surface with it.

Nothing went wrong. The stock support profile is tuned to hold overhangs up reliably, and holding up reliably and letting go cleanly are opposite requirements.

Below is the profile I have settled on in Bambu Studio, printing PLA on an A1 Mini with a 0.4mm nozzle at 0.16mm layer height. The settings map straight across to OrcaSlicer, which shares the same support engine.

The 0.16mm profile

Setting	Panel	Stock	This profile
Enable support	Support	off	on
Style	Support	Default	Tree Slim
On build plate only	Support	off	on
Support critical regions only	Support	off	on
Support wall loops	Advanced	-1 (auto)	0
Top Z distance	Advanced	0.16mm	0.25mm
Base pattern	Advanced	Default	Hollow
Top interface spacing	Interface	0.5mm	0.8mm
Support/object XY distance	Interface	0.35mm	0.65mm

Stock values are for the 0.16mm Optimal profile. Any setting absent from the table is left exactly as Bambu ships it.

Top Z distance by layer height

Top Z distance is the only value here that depends on layer height. Bambu's own stock value tracks the layer height until it caps at 0.20mm:

Layer height	0.08	0.12	0.16	0.20	0.24	0.28
Top Z, stock	0.08	0.12	0.16	0.20	0.20	0.20
Top Z, this profile	0.17	0.21	0.25	0.29	0.29	0.29

The rule is stock plus about 0.09mm. Only the 0.16mm column has been print tested, so treat the rest as a starting point.

Why the gap is the whole game

A support touches the model in two places: the top of the column against the underside of the overhang, and the bottom of the column against whatever it stands on. Everywhere else it stands in open air. All the effort of removal goes into those two interfaces, and a gap you set in the slicer governs both.

At a gap of zero the interface extrusion lands on solid plastic that is still warm, and it welds. Pliers cannot separate a weld, so the model surface tears instead of the support.

At too large a gap the interface has nothing under it, sags into the void, and the overhang above prints onto a wavy surface. Removal is easy because the support barely worked.

Every value below lands between those two failures, or reduces how much support gets generated at all.

What each setting does

Enable support: on. Stock leaves it off, and the rest of the list only matters once it is on.

Style: Tree Slim. The type is already tree (auto) at stock, so only the style changes. Tree supports touch the model at discrete points rather than under the whole projected footprint, and less contact area is less to break. Tree Slim keeps the branches thin instead of thickening them into the plate-filling structures Tree Strong produces. One caveat: Bambu Studio has an open bug where tree support ignores a threshold angle below 20 degrees and supports everything at 70 degrees and above instead. Stock threshold is 25 at 0.16mm so this profile never touches it, but stock falls to 20 at 0.12mm and 15 at 0.08mm. At finer layer heights, hold the threshold at 20 or above.

On build plate only: on. Supports landing on the model leave the worst marks, because you pry against a printed surface rather than against the plate. Anything that would need a support standing on the model now gets none, so this is a constraint on how you orient the part.

Support critical regions only: on. Prunes support down to the places that genuinely fail without it. Small isolated overhangs bridge fine.

Support wall loops: 0. A wall loop wraps the support body in a continuous perimeter, turning loose infill lines into a rigid tube. The setting runs from -1 to 2, where -1 is the stock auto and 0 permits infill-only support wherever the body stands without a wall. That covers most tree branches, so the support crumbles under a thumb.

Top Z distance: 0.25mm. The air gap under the model, and the number that decides between a fingernail job and a pliers job. Stock 0.16mm is one whole layer, which welds. See the table above for other layer heights.

Base pattern: Hollow. A sparse support body, again in the service of weakness.

Top interface spacing: 0.8mm. The surprise of the set. Stock 0.5mm approaches a solid sheet directly under the overhang: best surface finish, hardest thing in the world to remove. At 0.8mm with a 0.4mm nozzle the interface lines sit roughly a line width apart, so contact with the model above is a series of ridges rather than a plane. Surface finish drops slightly. Removal changes character completely, because the break now has somewhere to start.

Support/object XY distance: 0.65mm. Horizontal clearance where a support runs alongside a vertical wall. Too small and the support fuses to the side of the part. Stock is 0.35mm and most published advice sits at 0.35 to 0.40, so 0.65 is deliberately generous. If your parts have narrow slots that supports must reach into, come back down towards 0.4.

Why 0.25mm is available at all

0.25mm is not a multiple of 0.16mm, and that is the point.

A support printed on the model's layer grid can only leave an air gap of a whole number of layers. At 0.16mm the choices are 0.16mm, which welds, or 0.32mm, which sags. The value you want sits between them and stays unreachable. Hence all the tuning advice that ends in "try one layer, then try two", and why neither ever quite works.

Independent support layer height removes the constraint, and Bambu turns it on by default, so it is not on the list above. The support uses its own layer heights and stops wherever it needs to in order to leave the gap you asked for. The gap becomes a real dimension in millimetres.

The option is ignored when the prime tower is enabled. Turn on a multi-colour print and the supports go back on the model's layer grid, which puts you back to choosing between 0.16mm and 0.32mm.

A part to test it on

Tuning a gap 0.01mm at a time needs something small to tune against. A real part takes hours and only has the overhangs it happens to have.

Download the test coupon (3mf), or the OpenSCAD source to change the dimensions.

It is an inverted L, 32 by 14 by 22mm, printing in under half an hour:

The arm cantilevers 22mm over nothing, so the slicer supports 308mm² of flat ceiling from the plate. That underside is the surface to inspect.
The post beside the support column puts a vertical wall next to the support, where too small an XY distance shows up as fusing.
At 18mm the column is tall enough to get a fingernail under.

The coupon has a label parameter in the source. Set it to the value under test, print one per candidate, and a row of them stays readable a week later. The 3mf carries geometry only, so apply your own profile after opening.

If you change one thing

Change the top Z distance, and change it by 0.01mm at a time.

Every other value shifts the result a little. That one decides whether the support comes off in your hand or comes off with a scalpel, and on a 0.4mm nozzle 0.24mm and 0.26mm are genuinely different prints. Get it right for your filament, then leave the rest alone.

Digital Design 03: Metastability

2026-08-29T00:00:00+01:00

Series: Digital Design Fundamentals | Article 3

The board runs for six days. On the seventh, the status register reports a state the state machine cannot reach, the firmware takes a branch that was never meant to execute, and the watchdog resets the part. Simulation has run the same sequence ten million times and never produced it. Attaching a scope to the suspect net makes the fault stop for a fortnight.

This article explains where that state came from. Two routes lead to it: an input from another clock domain, and a synchronous path that failed timing closure. Both end at the same condition, a setup or hold requirement that was not met at the sampling edge. It is for anyone who writes register transfer level code and has been told to put two flip-flops on an asynchronous input without being told what the second flip-flop is for.

A decision with no margin

A flip-flop is a decision element with gain. At the sampling edge it captures the difference between its input and its own switching threshold, then amplifies that difference until the output reaches a rail.

The captured difference sets how long the amplification takes. An input that settled a nanosecond early presents almost the full supply, and one pass through the internal loop is enough. An input that moved a few picoseconds before the edge presents a few millivolts, and the same loop needs several passes to build those millivolts up to a rail.

That difference has no lower limit. Data crossing the threshold close enough to the clock edge leaves the flip-flop microvolts to amplify, or less, and the amplification then starts from microvolts.

Distance from the threshold grows as V0 e^(t / tau), where V0 is the captured margin and tau is the settling time constant. Time to reach a rail therefore depends on the logarithm of the margin, so a margin ten times smaller costs only about 2.3 more time constants. Waiting buys a great deal and never buys certainty.

While the output is still climbing it sits between the rails. That is metastability. Not a broken circuit, but an amplifier part way through a decision.

Where the clock edge lands

Setup time and hold time describe a window around the clock edge in which the input has to be stable. An input that changes inside that window is the input that leaves almost no margin to amplify.

Two situations put a real design in that window. The first is a signal with no fixed relationship to the sampling clock: another clock domain, a button, a sensor. The second is a fully synchronous path that failed timing closure, where static timing analysis has already reported a violated setup or hold requirement.

The two look different in a report and identical at the flip-flop. Both are the same condition, a setup or hold requirement not met at the sampling edge.

One wire, two answers

Settling time is not the only hazard, and the next one does not depend on it at all. A flip-flop output is a wire, and a wire goes to more than one place.

While the output sits near mid rail, every gate on that net is reading it. Each has its own switching threshold, set by the ratio of its pull-up and pull-down networks, and those thresholds are not identical. Process variation moves them, different cell types have different ones by design, and different loads mean the reads do not happen at the same instant.

One node, one instant, two answers. Neither gate is faulty and neither reading is wrong. The wire did not carry a logic value for them to agree about.

That is the failure, and metastability by itself is not. A flip-flop sitting at mid rail with nothing reading it costs some current and resolves. The damage starts when that voltage reaches two places and the two places disagree.

Downstream registers then hold values that cannot occur together. A one-hot state machine ends a cycle with two bits high, so two decodes match at once. A handshake ends with both ends believing the other holds the token. None of those states appear in the encoding, in the assertions or in the coverage report. The register transfer level model cannot represent a wire that two readers disagree about, so simulation never produces them.

The bug that results is rare, random, and moves when observed. A scope probe adds capacitance and shifts the timing. Temperature and supply voltage move switching thresholds. Rebuilding the design changes placement, so the wire delays that produced the divergence are gone and a fresh set arrives elsewhere.

Two flip-flops, and why not one

The fix follows from the exponential. Give the metastable node a full clock period to settle before anything reads it.

The first flip-flop absorbs the risk, and its output goes nowhere except the second flip-flop, so a divergent read has nothing to diverge into. The single-load rule matters as much as the second stage. Fanning the first stage out to anything else recreates the divergence the structure exists to prevent.

Putting a number on it

Mean time between failures, or MTBF, follows from the settling time constant and two frequencies:

MTBF = e^(t_r / tau) / (T0 x f_clk x f_data)

t_r is the settling time allowed, T0 is the width of the aperture, f_clk is the destination clock frequency and f_data is the rate of input changes. Only t_r sits in the exponent, so it dominates everything else.

Liberty timing files do not carry tau or T0. They model a cell as a deterministic table of setup, hold and clock-to-Q, and metastability is a probability distribution with an exponential tail. The parameters have to come from transistor-level simulation instead. Measuring them on sky130_fd_sc_hd__dfxtp_1, the real 24-transistor SkyWater cell, gives this:

Corner	Setup	tau	T0
ss slow	45.6 ps	116.8 ps	67.4 ps
tt typical	28.6 ps	43.8 ps	492.2 ps
ff fast	20.5 ps	21.8 ps	1872 ps

tau varies by 5.4 times across the corners, and it sits in an exponent. Characterise at the slow corner, because that is where the latch resolves most slowly.

Take the slow corner and put the synchroniser somewhere demanding. The destination clock f_clk is 400 MHz, so its period is 2.5 ns. The asynchronous input f_data changes at 10 MHz. The first stage gets half a period to settle, and each stage after it adds a full period.

Stages	Settling allowed	In time constants	MTBF
1	1.25 ns	11	0.16 seconds
2	3.75 ns	32	10 years
3	6.25 ns	54	2.0e10 years

A single flip-flop fails six times a minute. The second stage moves that to about ten years, which is a product lifetime and not a comfortable margin. The third stage moves it to twenty billion years. Each stage is worth roughly nine orders of magnitude, because each one adds 2.5 ns of settling and that is 21 time constants.

Slow the clock to 100 MHz and the same two-stage synchroniser reports 2.8e43 years. That is the number most designers meet, and it is why two flip-flops is treated as automatic. The rule is safe at 100 MHz and marginal at 400 MHz, and nothing about the flip-flop changed.

Two stages is a convention, not a law. It holds only while tau stays small against the clock period. Raise the same cell to 1 GHz and two stages give half a second, three give under an hour, and it takes five to reach 2500 years. A 130 nm cell has no business running at 1 GHz, and a process built for that speed has a tau of a few picoseconds.

The measurement and the code behind those tables are at github.com/morganp/flipflop-mtbf.

Closing

For any signal entering a clock domain from outside it, three questions:

Does it pass through two flip-flops before anything else reads it?
Does the first of those flip-flops drive exactly one load?
Does anything else cross alongside it that has to stay consistent with it?

The second question is the one this article adds. A synchroniser with a fanned out first stage looks correct in a schematic review and fails in the same way as no synchroniser at all.

The third question is a different problem. Two flip-flops protect one bit, and they promise nothing about a multi-bit bus, about related control signals synchronised separately, or about a synchronous path that failed timing closure. Those need handshakes, Gray coding, or a fix in the path itself.

Previous: Digital Design 02: Pull-up and pull-down networks

Multi-tool or separate tools

2026-08-29T00:00:00+01:00

The nut on the garden tap has seized again. The Leatherman comes out of the pocket, the pliers swing open, and the jaws close on air either side of a 22 mm flat. The tool that has ridden in that pocket every day for a year cannot grip the one thing it was carried for.

This post compares a Leatherman Wave+ against three separate tools that cover the same jobs, and asks whether an uncompromised set costs more weight or more money. It is for anyone who carries a multi-tool daily and has started to wonder what the alternatives are. The comparison uses published weights and UK street prices throughout.

Where the weight sits

A multi-tool is a plier frame with implements stored in it. The Wave+ weighs 241 g, and the plier head, the two handle channels and the pivots account for most of that. Take the blades, the saw, the file and the scissors out of a Wave+ and the empty frame still weighs more than a whole Opinel.

The frame does two jobs at once. It works the pliers, and it stores and supports every other tool. Both jobs push the design in the same direction: more steel. The frame needs stiffness to transmit grip force, and it needs walls thick enough to carry a pivot pin for every folding implement.

Every implement then pays rent on that frame. The knife blade contributes perhaps 20 g of steel and carries a share of the frame that lets it fold away. Counting eighteen tools and dividing 241 g by eighteen gives a flattering number. The honest division puts most of the mass in the box rather than in the tools.

What folding costs each tool

The frame costs weight. Folding costs capability, and it costs it three separate times.

The pliers lose leverage. Handle length sets the torque a hand can apply, and the handles have to be short enough to carry in a pocket. They also have to be hollow, because the other tools live inside them. The Wave+ jaws will not reach a 22 mm nut, and plenty of fittings under a sink are larger than that.

The blade loses grind. A folding blade has to fit inside the handle channel alongside its neighbours, so its thickness and its profile are set by clearance rather than by cutting. The Wave+ blade sits in a channel it shares with a saw and a file. The result cuts, and it does not cut like a knife whose only design constraint is cutting.

The bit driver loses grip and bit choice. It folds out in line with the handle, so the closed tool is held like a stubby screwdriver. The hand closes on a flat steel channel with two square edges, not on a barrel the palm can bear down on. Torque stops at the pressure the fingers can pinch. The Wave+ takes Leatherman's own flattened bits rather than standard 1/4 inch hex, so an existing bit collection needs the Bit Driver Extender accessory before it fits. The tool carries one reversible bit, which is two tips.

The three-part kit

Three tools cover the same three jobs, and none of them shares a handle. The Opinel folds, but its handle carries one blade and nothing else. Each tool is built around its own job, with nothing given up to storing the others: solid handles, a blade shaped only for cutting, a barrel the palm can bear down on. An uncompromised set costs either weight or money, or it costs neither.

Knipex Cobra XS

The Cobra XS weighs 62 g and measures 100 x 30 x 10 mm. It costs about £25. The jaws take pipes to 28 mm diameter and nuts to 24 mm across the flats, which is larger than the Wave+ manages with handles 65 mm longer.

Water pump pliers achieve that range by moving the pivot rather than opening the jaws. A push button steps the pivot along a slotted track, so the handles stay at a comfortable angle whatever the jaw opening. The jaws self-lock under load, which means grip force comes from the workpiece pushing back rather than from the hand squeezing harder.

The handles are solid, because nothing lives inside them. A solid 100 mm handle is stronger than a hollow 165 mm one, and it grips larger nuts.

Opinel No 08

The Opinel No 08 in carbon steel weighs 45 g and costs about £12. The blade is 8.5 cm, the handle is beech, and the Virobloc collar locks the blade open and closed.

Nothing about the blade is set by clearance. It is thin behind the edge because a thin edge cuts, and the taper runs the full height of the blade rather than stopping at a shoulder. XC90 carbon sharpens on almost anything and takes an edge in a couple of minutes on a stone.

The handle matters as much as the steel. A wooden handle fills the palm, warms to the hand and gives a grip that does not depend on finger pressure. The alternative is holding two hollow steel channels edge-on while cutting.

PB Swiss 6460 Insider

The PB Swiss 6460 Insider weighs 89 g including eight 1/4 inch C6 bits stored in the handle. It costs about £56, and it is the expensive part of the kit.

The handle is the point. It is a round screwdriver handle the palm can bear down on, so grip force does not stop at what the fingers can pinch. The bit magazine slides out of the tail and locks, so the bits travel inside the tool rather than in a separate pouch. The bits are standard 1/4 inch C6, so hex, Phillips and Pozidriv come out of any bit set already in the drawer.

There is no ratchet. That is a deliberate choice and not only a weight saving. A ratchet adds a pawl, a spring and a direction lever, and each is a part that can fail under load in a pocket-carried tool. A fixed driver has nothing to strip.

The numbers

The weights land close together. The prices do not, because the driver sets them apart.

Item	Weight	Price
Knipex Cobra XS 87 00 100	62 g	£25
Opinel No 08 carbon	45 g	£12
PB Swiss 6460 Insider, 8 bits	89 g	£56
Kit total	196 g	£93
SabreCut MRSC01K1, 4 pieces	99 g	£16
Kit total with the SabreCut	206 g	£53
Leatherman Wave+	241 g	£98

The first kit saves 45 g and £5. Neither number matters on its own. A 19% weight saving is inside the noise of whatever else is in the pocket, and £5 on a hundred is a rounding error.

For 45 g and £5 less, the kit grips a 24 mm nut, cuts with a knife-shaped knife and drives a screw with a handle the palm can push. The weight of a multi-tool does not buy capability. It buys the convenience of one object, and the capability pays for it.

A cheaper driver

The PB Swiss is 60% of the kit price. Pliers and knife together come to £37, and the driver alone comes to £56.

The SabreCut MRSC01K1 covers the same job for £15.99. The kit holds a stainless ratchet of 58 g and 85 mm, a 60 mm magnetic bit holder, PH2 and PZ2 impact bits and a pouch, and the four pieces together weigh 99 g. The gear is chrome-molybdenum with 72 teeth, rated to 52 Nm. The body drives in line with the screw or turns across it as a ratchet.

Swapping it in brings the kit to 206 g and £53, so the second kit costs 10 g more and £40 less. It also changes the driver in two ways that pull in opposite directions. It gains a ratchet, which turns a screw in a recess too tight for a full swing. It loses the handle, because 85 mm of stainless steel is a body the fingers turn rather than a barrel the palm bears down on. Hex bits are not in the box and add about 3.5 g each.

Neither kit is the right answer for everyone. The PB Swiss kit is the lighter one and drives the stiffest screws. The SabreCut kit comes in at £45 under the Wave+, a little over half the price, and reaches into places neither of the others will.

The lighter Leatherman

The Wave+ is not the lightest Leatherman that covers these three jobs. The Skeletool carries pliers, one combination blade and a bit driver, and little else. It weighs 142 g, measures 100 mm closed, and costs about £76.

That undercuts both kits. The PB Swiss kit gives away 54 g to it and the SabreCut kit gives away 64 g. Anyone choosing on weight alone should buy the Skeletool.

The three compromises survive the diet. The jaws are needle-nose and narrower than the ones on the Wave+, so they reach nothing like 24 mm. The blade still folds into a handle channel. The driver still takes Leatherman's flattened bits, and the tool carries two double-ended bits, so four tips in total.

The Skeletool wins on weight and the kit keeps the capability. Price runs the other way again, since the SabreCut kit at £53 lands £23 under it.

What you give up

The kit loses four tools outright. There is no saw, no file, no scissors and no awl. Anyone who uses the Wave+ scissors weekly keeps the Wave+.

It also costs pocket space in a way the total weight hides. Three objects need three places, or a pouch, and a pouch is another thing to carry. Three objects are three things to lose, and the Opinel is the one that walks off.

Deployment splits two ways. The Wave+ carries its blades on the outside, so a blade opens one-handed, and the Opinel needs two hands and a twist of the collar. The pliers go the other way, because the Wave+ handles have to swing apart before the jaws are usable, and the Cobra XS is already a pair of pliers. The kit also costs a moment of reaching for the right pocket.

When the Wave+ still wins

Unpredictable work favours the multi-tool. A day when the next job is unknown is a day for carrying eighteen adequate tools rather than three good ones.

Belt carry favours it too. One sheath on a belt is comfortable, and three pouches are not. Anyone who works from a belt rather than a pocket is already carrying the frame for free.

Lending favours it. Handing a colleague a Wave+ solves whatever they have. Handing them one third of a kit solves a third of it.

Closing

Weigh and price whatever is in the pocket now. Then count the tools actually used in the last month, not the tools on the packaging.

If that list is pliers, knife and screwdriver, the frame holding the other fifteen costs 45 g and £5 against the PB Swiss kit, and 35 g and £45 against the SabreCut kit. If the list has scissors on it, keep the Wave+.

SoC Intermediate 04: RTL synthesis and timing closure

2026-08-28T00:00:00+01:00

Series: Intermediate SoC Design | Article 4 of 10

The report was green

Sign-off timing passed. Worst negative slack across every corner was positive, by a comfortable margin on setup and a thin margin on hold. It had been the hardest block in the project, and it was finally done. Somebody put a chart in the review deck showing the slack climbing out of the red over six weeks.

The chip came back and mostly worked. In the cold chamber, one part in a few hundred returned bad data from a configuration register, but only when the register was written while a particular unrelated interface was active. Nobody could reproduce it in simulation, because in simulation the design is exactly as correct as the day it was signed off.

This article is about synthesis and timing closure: what the tools genuinely prove, what they only appear to prove, and where the gap between the two usually opens up. It targets engineers writing register transfer level (RTL) code that has to meet a frequency target, and anybody who has inherited a constraint file and is wondering how much of it to trust.

What synthesis is being asked to do

Synthesis maps RTL onto standard cells from a technology library: flip-flops and latches, combinational gates, arithmetic structures, clock gating cells, and in low-power flows the isolation and retention cells that survive a powered-down domain.

It does that mapping while trying to satisfy your constraints and minimise area, power, and delay. The word to notice is your. The tool has no independent notion of what the design is supposed to do at speed. It optimises against the constraint file, and if the constraint file is wrong it will produce an efficient, well-optimised implementation of the wrong intent.

Two stages on that path are marked in purple because they are the only two that read the constraints. Everything downstream inherits whatever those two were told.

What static timing analysis proves

Static timing analysis (STA) checks every path in the design without simulating a single input vector. It builds a graph from register clock pins, combinational arcs through cells, net delays extracted after routing, clock tree delays and skew, library setup and hold requirements, and your constraints.

For a path to work, the data launched by one edge has to arrive and settle before the edge that captures it:

launch edge + clock-to-Q + data path delay + setup time
    <=
capture edge + useful skew - uncertainty

Both terms above assume the launch and capture flip-flops see the same clock edge at the same moment, which is what a balanced clock tree is built to deliver. Article 07 covers clock tree synthesis and the H-tree that equalises the paths. Real trees land within tens of picoseconds rather than at zero, and useful skew unbalances them deliberately, which is where the skew term earns its place.

Assume a balanced tree for the moment, and setup needs only two edges of one clock:

Hold is the same relationship read from the other end, and it is not a next-edge check at all. The data must not arrive so early that it overwrites the value the capture flip-flop is still reading from the edge that just fired. Launch and capture are the same edge:

The two failures have opposite personalities, and each is worst at the corner that is kindest to the other.

Failure	Meaning	Worst at	Common fixes
Setup	Data arrives too late	Slow silicon, low voltage, high temperature	Reduce logic depth, resize cells, pipeline, improve placement
Hold	Data arrives too early	Fast silicon, high voltage, low temperature	Add delay cells, adjust clock skew, correct the constraint

Setup failures are a performance problem: run the part slower and they go away. Hold failures are not. A hold violation is broken at every frequency, including zero, which is why a hold bug in silicon is usually a respin and a setup bug is usually a de-rated data sheet.

The constraint file is the specification

Most ASIC and FPGA flows describe timing intent in Synopsys Design Constraints (SDC) syntax. A minimal block might start like this:

# Primary clock: 1 GHz
create_clock -name core_clk -period 1.000 [get_ports core_clk]

# External interface timing, relative to that clock
set_input_delay  0.250 -clock core_clk [get_ports rx_data*]
set_output_delay 0.300 -clock core_clk [get_ports tx_data*]

# Jitter and analysis margin
set_clock_uncertainty 0.050 [get_clocks core_clk]

# Asynchronous reset assertion is not a functional timing path
set_false_path -from [get_ports reset_n]

Five commands, and every one of them is a claim about the world outside the block. The period claims what the clock generator will produce. The input delay claims when the upstream block launches. The uncertainty claims how much jitter the phase-locked loop contributes. The false path claims that reset assertion never needs to be captured on a specific edge.

None of those claims are checked by anything. They are inputs.

That is the reason a constraint file deserves the same review a piece of RTL gets: an owner, a version history, a comment on every non-obvious line, and a reviewer who is allowed to ask "how do you know?".

Exceptions, and the damage they hide

Three SDC commands exist to tell STA to relax. All three are legitimate. All three are also the standard way to make a report turn green without changing a gate.

A false path says the path is not real and should not be analysed. A configuration register that only changes during reset, a scan-mode path that is inactive functionally, a test observation output nobody samples at speed.

A multicycle path says the path is real but has more than one clock period to complete.

# Data launched by stage_a is captured by stage_b two cycles later
set_multicycle_path 2 -setup \
    -from [get_cells stage_a_reg*] \
    -to   [get_cells stage_b_reg*]

# The hold check has to move with it
set_multicycle_path 1 -hold \
    -from [get_cells stage_a_reg*] \
    -to   [get_cells stage_b_reg*]

That second command gets left out, and leaving it out is worse than not writing the exception at all. A setup relaxation without the matching hold adjustment tells the tool the data may arrive a cycle late, while still requiring it not to arrive early relative to the original edge. The tool will happily insert delay to satisfy a hold check that was never the real requirement, or fail to insert it where it was.

A multicycle constraint is only true if the destination register genuinely cannot capture every cycle. That means an enable, and the enable has to be provably sparse:

If a later revision adds a bypass mode that asserts capture_en every cycle, the RTL change is one line, the constraint is still in the file, and the timing report still passes.

A clock group says two clocks have no known phase relationship:

set_clock_groups -asynchronous \
    -group [get_clocks cpu_clk] \
    -group [get_clocks periph_clk]

This is the most misread of the three. It does not make the crossing safe. It does not add a synchroniser. It tells STA to stop analysing a relationship that was never meaningful, and the correctness of the crossing is now entirely the job of clock domain crossing (CDC) analysis and the synchronisers in the RTL. Declaring the group and skipping the CDC review removes the only check that was looking.

The gap

Static timing analysis never tells you whether the chip works. It tells you whether the implementation matches the constraints. Those are the same statement only to the extent that the constraints are true, and nothing in the flow verifies that they are.

Read the failure at the top of the article again with that in mind. The configuration register had a set_false_path on it, added early, when the register really was written only during reset. Two years later a feature landed that reprogrammed it at runtime while the interface was live. The RTL review covered the new write path. Nothing in the flow re-examined the exception, because an exception is not code, it produces no warning, and it fails silently by making a real path invisible.

That is the shape of nearly every timing bug that reaches silicon. Not a path the tool got wrong, but a path the tool was told not to look at.

Which is why the useful question during a closure review is not "what is the worst negative slack". It is "how many paths are we not analysing, who decided that, and is the reason still true".

# Worth running, and reviewing line by line, before every sign-off
report_exceptions -ignored
report_disable_timing
report_clock_properties

An exception with no comment and no owner should be treated as a bug until somebody re-derives the argument for it.

Reading a report

When a path genuinely fails, the report tells you what kind of problem it is, provided you read past the slack number.

Startpoint: u_decode/op_reg[3]
Endpoint:   u_execute/alu_result_reg[17]
Path group: core_clk
Slack:      -0.083 ns

  clock-to-Q              0.061
  decode mux              0.142
  compare                 0.188
  operand mux             0.221
  adder                   0.364
  route                   0.177
  setup                   0.043
  required                1.000

The distribution matters more than the total. Here the logic dominates and no single cell is pathological, which means this is a microarchitecture problem and cell sizing will not save it. A different failure profile would call for a different response:

What dominates	What it usually means	Where to fix it
Many small logic stages	Logic depth	RTL: split the chain, add a stage
One large cell delay	Weak drive, high fanout	Tools: sizing, buffering, cloning
Routing delay	Placement or floorplan	Physical: placement constraints, partitioning
Clock skew or uncertainty	Clock tree or margin	Clock tree synthesis, useful skew
Required time surprises you	The constraint is wrong	The SDC

Check that last row first. It is the cheapest to fix and the most embarrassing to find late. If the required time is not the number you expected, stop looking at the data path.

Fixing it in RTL

The fixes available in RTL are the ones that change how much work sits between two registers:

Register the output of a wide multiplexer rather than the input of the next stage's logic.
Split long add, compare, and select chains, especially where a comparison result selects an operand for an addition in the same cycle.
Avoid the accidental priority encoder. A case with overlapping conditions or a long if / else if chain in a datapath synthesises into a serial structure, and one-hot control costs area but flattens the delay.
Duplicate a high-fanout control register into local copies near its consumers, rather than asking the tool to buffer one signal across the block.
Move work across an existing stage boundary before adding a new one, since the free rebalance is always better than the stage that costs a cycle of latency.

The pattern behind all five is the same: timing closure is easy when the microarchitecture already has clean stage boundaries, and the earlier article on pipeline hazards is the reason those boundaries are not free to add later.

Fixing it in the tools

Implementation tools have their own set of moves: cell sizing, buffer insertion, logic restructuring, register retiming, placement constraints, useful skew, and clock tree adjustment.

They are genuinely powerful, and retiming in particular can rebalance logic across register boundaries in ways that would be tedious by hand. But they all work within the structure the RTL gave them. No amount of sizing will fit two cycles of logic into a one-cycle budget, and a path that needs a microarchitecture change will keep coming back on every run, slightly differently each time, consuming a week per iteration.

The tell is a path that oscillates. Fix it, and it closes, and something adjacent opens. That is not a tool failure. That is a design that has no slack anywhere in a region, and the tool is moving a fixed shortage around.

Every corner, every mode

A single timing run is one point in a space the chip has to survive all of.

Slow silicon, low voltage, high temperature   -> setup worst case
Fast silicon, high voltage, low temperature   -> hold worst case
Functional, scan, retention, low-power modes  -> different constraints each

Multiply the process, voltage, and temperature corners by the operating modes and the analysis views multiply with them. The sign-off question is not "does the design meet timing", it is "does every mode meet timing at every corner it can be in".

Two practical consequences. First, a corner nobody enabled is a corner nobody checked, so the list of analysis views is itself a review item. Second, low-temperature inversion means the fast corner is not simply "everything is quicker": at modern nodes some cells get slower at low voltage as temperature drops, so the intuition that cold silicon is fast silicon is not reliable and the corner list has to come from the library characterisation, not from reasoning.

The ECO loop

Late fixes go in as an engineering change order: a small, surgical patch to a design that is otherwise finished.

The purple node carries the risk. An ECO is small in the netlist and unbounded in what it can invalidate: timing on adjacent paths, logical equivalence against the RTL, CDC structures, power intent, and any software-visible behaviour that verification signed off weeks earlier. Every ECO needs the full check set re-run, and the discipline that makes late ECOs survivable is keeping them small enough that the re-run is credible.

Closure checklist

Give the constraint file an owner and a version history, and review it like RTL.
List every exception in the design with a one-line justification and the name of the person who made the argument.
Re-derive those justifications whenever the RTL around them changes, because nothing else will.
Pair every -setup multicycle with its matching -hold, and prove the capture enable is as sparse as the constraint claims.
Treat set_clock_groups -asynchronous as a note to STA, never as a CDC solution, and check the synchronisers separately.
Track worst negative slack and total negative slack per path group, since a single bad path and a thousand marginal ones need different responses.
Confirm the analysis view list covers every corner and mode the part can actually be in, including the ones only test or retention can reach.
Re-run lint, CDC, logical equivalence, and STA after every ECO, without exception, however small the patch.

Ask what is not being analysed

The number at the top of the timing report tells you how the paths under analysis are doing. It says nothing at all about the paths that were removed from analysis, and those are the ones with a history of reaching silicon.

Before the next sign-off, dump the exception list and read it end to end. On a mature design it will be longer than you expect, and some fraction of it will be constraints written by people who have left, against RTL that has since changed, for reasons nobody recorded. That fraction is your actual risk, and it is countable in an afternoon.

Previous: Article I-03: Pipeline design and hazards Next: Intermediate Article 05, Clock domain crossing techniques

Digital Design 02: Pull-up and pull-down networks

2026-08-19T00:00:00+01:00

Series: Digital Design Fundamentals | Article 2

The AND gate that was not there

You wrote assign y = a & b;, ran synthesis, and opened the gate-level netlist to check something unrelated. There is no AND gate in it. There is a NAND2 feeding an inverter.

Look up both cells in the library databook and it gets stranger. The NAND2 is four transistors. The AND2, which exists, is six, and it is slower. The synthesiser did nothing unusual. It used the AND2 cell, and the AND2 cell is a NAND2 followed by an inverter, because in static CMOS there is no other way to build one.

This article is about why. It covers the two transistors as switches, the pull-down and pull-up networks made from them, why those networks always produce an inverting function, how NAND and NOR fall out of series and parallel arrangements, and why the two are not equally good. It targets anyone who has been handed a standard cell library and wants to know what the numbers in it mean, and anyone learning digital design who wants gates to stop being symbols on a page. It follows on from Digital Design 01, which built the transistors these gates are made of and showed how a gate voltage forms the channel that makes one conduct.

A 1 is a voltage

One thing to settle before any of the schematics make sense: a logic value is not an abstraction sitting on top of the circuit. It is a voltage on a wire.

A digital 1 is the supply voltage, VDD. A digital 0 is ground, 0 V. In these schematics the rail marked VDD and the value 1 are the same thing, and the rail marked GND and the value 0 are the same thing. Saying a gate "outputs a 1" and saying it "connects its output to VDD" describe one event.

VDD is whatever the process runs at, and it has fallen steadily with each node: 5 V in the 1980s, 3.3 V, 1.8 V, and around 0.7 to 0.9 V on a modern logic process. The logic does not care about the number. It cares that there are two rails, that every output can be tied to one of them, and that the receiving gate can tell which.

Real circuits leave margin around both values. Anything above roughly 70 per cent of VDD reads as a 1, anything below roughly 30 per cent reads as a 0, and the band between is the noise margin. A "weak" or "degraded" level later in this article means a voltage that has drifted towards that middle band, where the next gate has to work harder to decide.

Two switches, each good at one thing

The metal-oxide-semiconductor field-effect transistor (MOSFET) has three terminals that matter here: gate, source and drain. Voltage on the gate controls whether current can flow between source and drain. No current flows into the gate itself; it is a capacitor plate over an insulator. That is the whole reason complementary metal-oxide-semiconductor (CMOS) logic can drive thousands of inputs without a power budget for it.

There are two flavours, and they are opposites.

	nMOS	pMOS
Conducts when the gate is	high	low
Turns on at	gate above source by the threshold voltage	gate below source by the threshold voltage
Passes a good	0	1
Passes a poor	1, stopping a threshold below the supply	0, stopping a threshold above ground
Carrier	electrons	holes
Speed for the same width	faster	slower, by roughly two to three times

The two rows in the middle of that table are the ones everything else is built on.

Try to pull an output up to the supply through an nMOS. The output rises, and as it rises the gate-to-source voltage falls, because the source is the rising node. When the output gets within one threshold voltage of the gate, the transistor stops conducting. The output sits at roughly the supply minus a threshold: a 1 that is a few hundred millivolts short of VDD, eating into the noise margin above and leaking current in the gate it feeds. The pMOS has the mirror-image problem pulling down to ground.

So the transistors get used the way they are good:

nMOS transistors connect the output to ground. They form the pull-down network, and their job is producing a solid 0.
pMOS transistors connect the output to the supply. They form the pull-up network, and their job is producing a solid 1.

Every static CMOS gate is those two networks, sharing the same inputs, sharing the same output node, and arranged so exactly one of them conducts for any combination of inputs. That last property is what "complementary" means, and it has a consequence: when the output is settled, there is no path from supply to ground, so a settled gate draws no current beyond leakage. CMOS burns power when it switches, not when it sits.

The inverter, in full

One nMOS, one pMOS, gates tied together as the input, drains tied together as the output.

Input low: the pMOS conducts and the nMOS is off, so the output is connected to the supply and pulled to a solid 1. Input high: the nMOS conducts and the pMOS is off, so the output is connected to ground and pulled to a solid 0. Each transistor is used only in the direction it is good at, and in neither state is there a path from supply to ground.

A	pMOS	nMOS	Output
0	on	off	1
1	off	on	0

Two practical points come straight out of the picture.

The pMOS is drawn wider than the nMOS. Holes are slower than electrons by about a factor of two to three, so a pMOS of the same width delivers less current and pulls up more slowly than the nMOS pulls down. Cell libraries compensate by making the pMOS roughly twice the width, which balances rise and fall times at the cost of area and input capacitance. Look at any standard cell layout and the top row of transistors is visibly fatter than the bottom row.

Drive strength is width. An INVX4 is not a different circuit from an INVX1. It is the same two transistors, four times as wide, sourcing four times the current into whatever it drives, and presenting four times the capacitance to whatever drives it. That trade is the entire content of buffer insertion during synthesis: pay input capacitance here to gain drive strength there.

Series and parallel are AND and OR

Now build a network out of more than one transistor. Two rules, and they are the whole of it, because a transistor is a switch and switches in series and in parallel behave the way you would expect.

In series: the path conducts only if both transistors conduct.
In parallel: the path conducts if either transistor conducts.

Take the pull-down network, made of nMOS, so each transistor conducts when its input is high. Then:

Pull-down arrangement	Conducts when
A in series with B	A AND B
A in parallel with B	A OR B

And here is the step that decides the shape of every gate that follows. The pull-down network pulls the output low. So when the network conducts, the output is 0, and when it does not, the pull-up has it at 1:

output  =  NOT ( function the pull-down network conducts for )

The pull-down network computes AND and OR of its inputs, and then the output node inverts the answer, because conducting means pulling low. There is no arrangement of nMOS transistors between the output and ground that produces a non-inverting function. Pulling the output down is the only thing such a network can do.

The pull-up network has to be the complement, so that exactly one network conducts at a time. Since pMOS transistors conduct on a low input, the complement comes out as the series-parallel dual: wherever the pull-down has transistors in series, the pull-up has them in parallel, and the other way round. That is De Morgan's theorem drawn as wiring rather than written as algebra.

The recipe for any static CMOS gate is now mechanical:

Write the function you want as an inverted expression, y = NOT(f).
Build f in nMOS between output and ground: AND becomes series, OR becomes parallel.
Build the dual of that network in pMOS between output and supply: series becomes parallel, parallel becomes series.
Count the transistors. Two per input, always.

NAND2 and NOR2

Apply the recipe to the two simplest cases and the standard cell library appears.

NAND2 is y = NOT(A AND B). AND becomes two nMOS in series to ground. The dual is two pMOS in parallel to the supply.

NOR2 is y = NOT(A OR B). OR becomes two nMOS in parallel to ground. The dual is two pMOS in series to the supply.

A	B	NAND2 pull-down	NAND2 out	NOR2 pull-down	NOR2 out
0	0	off	1	off	1
0	1	off	1	on	0
1	0	off	1	on	0
1	1	on	0	on	0

Four transistors each, symmetric on paper. They are not symmetric in silicon.

In NAND2 the slow transistors, the pMOS pair, are in parallel, so either one alone can pull the output up, and each can stay near the minimum practical width that balances the gate. The nMOS pair is in series, so two channel resistances add on the pull-down, and each nMOS is roughly doubled in width to compensate. Electrons are cheap to widen.

In NOR2 it is the other way round, and the arrangement falls the wrong way. The pMOS pair is in series, so two already-slow devices add their resistances, and getting a rise time to match the fall time means widening each of them by something like four times the nMOS width. That is a bigger cell, more input capacitance presented to whatever drives it, and a worse delay for the same logical work.

This is why libraries and synthesis are NAND-heavy. Given a choice between two logically equivalent structures, the one built from NAND2 and inverters is usually smaller and faster than the one built from NOR2. It is also why a four-input NOR is rare, and a four-input NAND uncommon: stacking four pMOS in series produces a cell whose pull-up is several times slower than its pull-down, and stacking any four devices runs into the body effect, where transistors part-way up a stack see a raised source voltage, an effectively higher threshold, and less current than the one at the bottom. Practical libraries stop at three or four inputs and let synthesis build trees from there.

Where the AND gate's extra transistors went

Back to the netlist that started this. The recipe produces y = NOT(f), always. The output node is pulled low by a conducting network, and there is no way to arrange switches so that conducting pulls it high while still using nMOS below and pMOS above. A single-stage static CMOS gate is inverting by construction.

So AND2 is NAND2 plus an inverter: 4 + 2 = 6 transistors, two stages of delay rather than one. OR2 is NOR2 plus an inverter, and inherits the NOR2 pull-up problem as well. A buffer is two inverters, for the same reason. Nothing in the library is non-inverting for free.

NAND and NOR are not "universal gates" because of a tidy algebraic fact about being able to express everything with them. They are the gates the libraries are built from because a pull-down network and its dual produce them naturally, and AND and OR are the compound cells, sold at a two-transistor and one-stage premium. The Boolean operators you write in a hardware description language are the abstraction. The inverting cells are the hardware.

Two habits follow from it.

Push the inversions around instead of paying for them. De Morgan says a NAND with inverted inputs is an OR, and a NOR with inverted inputs is an AND. An inverter that cancels another inverter is free once the netlist is optimised, and a bubble that moves to a place where something else already inverts costs nothing at all. Synthesis does this automatically, which is why the netlist so rarely resembles the RTL structurally.

Compound functions can stay in one stage. The recipe never said the network had to be two transistors. y = NOT((A AND B) OR C) is an and-or-invert gate, AOI21: two nMOS in series for the AND, that pair in parallel with a third for the OR, and the dual above it. Six transistors, one stage of delay, and it does the work of an AND2 feeding a NOR2, which would have cost ten transistors and three stages.

Libraries carry a whole family of these: AOI21, AOI22, OAI21, OAI221 and more. Technology mapping during synthesis is largely the business of spotting where one of them fits, and it is a large part of why hand-instantiated gate-level logic so seldom beats the tool.

The two things static CMOS is bad at

Two functions resist the recipe, and both are common enough that libraries solve them another way.

The multiplexer. Selecting between two inputs as a static CMOS gate is an AOI22 at eight transistors, one inverter to make the complement of the select and another to restore the polarity: twelve transistors for a function that only has to connect one of two wires to an output. The alternative is a transmission gate: an nMOS and a pMOS in parallel, driven by complementary select signals, acting as a switch that passes a full-strength signal in either direction. The nMOS covers the low end, the pMOS covers the high end, and between them the weak-1 and weak-0 problems cancel. Two transmission gates and an inverter make a clean two-way multiplexer.

Exclusive-OR. In pure static CMOS, XOR needs both inputs and their complements and lands at ten to twelve transistors. Built from transmission gates it comes down to six or eight. Since XOR is the core of every adder and every parity tree, that saving justifies the library carrying special cells for it, and it is why an adder's transistor count never quite matches the figure the gate count suggests.

The catch with transmission gates is that they pass signals rather than drive them. A chain of them accumulates resistance quadratically and has no gain to restore a degraded edge, so a buffer has to appear every couple of stages. Transmission-gate logic is a local optimisation inside a cell, not a style for building a whole design.

Reading a cell library like a circuit

The next time a databook is open, the numbers have physical meanings.

Transistor count, or the area column standing in for it: two per input for a simple gate, plus two for every inversion the function needs at the output. A six-transistor two-input cell is a compound gate with an inverter on it.
Input capacitance differs per pin on the same cell. In a NAND2 the input nearest the output in the nMOS stack switches faster than the one nearest ground, which is why the timing model gives per-pin arcs and why synthesis cares which signal lands on which pin.
A NOR2 that is larger than the NAND2 of the same drive strength is the series pMOS stack, sized up. If a design is NOR-heavy, that is showing up in both area and timing.
Drive strength suffixes are transistor width. More output current, more input capacitance, no change to the logic.
Rise and fall times that differ mean the pull-up and pull-down networks are not balanced, either by design or because the cell was optimised for area.

Every one of those numbers is a pull-up network and a pull-down network, drawn as polygons on the masks from the previous article, and the standard cell layout is where the two articles meet: the p-type row along the top under a supply rail, the n-type row along the bottom over a ground rail, polysilicon stripes crossing both to form the gates, and metal 1 stitching the drains together into the output.

From here the series splits, and the two branches do not depend on each other.

One branch wires these cells into a loop and asks what happens when the loop holds neither a 0 nor a 1: metastability, and the unreproducible bugs that follow when two gates read the same undecided wire and disagree.

The other branch keeps the cells combinational and starts combining them: Boolean algebra as a tool for restructuring logic before it ever reaches a transistor.

Previous: Digital Design 01: Mask sets, and how a transistor gets built Next: Digital Design 03: Metastability

Lashing a tripod

2026-08-19T00:00:00+01:00

Camp gadgets stand on tripods. Three points of contact define a plane, so three feet sit solid on whatever ground they are put on. Add a fourth and one leg can end up on a different plane from the other three, which is the rocking you have met on a pub table or a chair on an uneven floor.

This post ties three poles into a tripod with one lashing, starting with the clove hitch it begins and ends on.

Tying the clove hitch

Both ends of the lashing are clove hitches, so that knot comes first. It is two turns round the pole, the second crossing the first, with the working end tucked under the crossing. Tie it in place, on the pole, without needing to reach an end.

Take the working end up the front of the pole, over the top, and down the back.
Bring it out underneath. That is one full turn, and on its own it will slide.
Cross back over the front and round again the same way, so the second turn lies diagonally across the first.
Feed the working end under that diagonal.
Pull both ends until the turns bed down against the pole.

Step 4 is the whole knot. The two turns trap each other against the pole, so the harder the lashing pulls, the harder the hitch grips. Miss the tuck and you have a round turn, which shakes loose as soon as you let go.

The finished hitch has the standing part leaving on one side and the working end on the other. If both come out the same side you have tied a cow hitch, which slides along the pole under load. That is the one check worth making before you start wrapping.

Where the top of the pole is clear, there is a faster way: make two loops the same way round, stack the second behind the first, and drop both over the end. It gives the identical knot and it works in gloves, but it needs a free end, so it is no use partway along a standing spar.

Tying the lashing

The tripod lashing goes by three names for the same tie. Scouting books call it a figure-of-eight lashing, riggers call it a gyn lashing, and most people call it a tripod lashing. All three describe a set of turns woven between the poles rather than wrapped around the outside of them.

A cut pole tapers along its length. The thick end, the one that grew nearest the root, is the butt; the thin end is the tip. Lay all three butts the same way and the bundle comes out fat at one end and thin at the other, so the wraps grip hard on one side and slackly on the other.

So lay the three poles side by side on the ground, with the middle one reversed end for end. The butts then alternate and the bundle stays even in diameter. Everything happens about 200 mm down from the tops.

Clove hitch on the left-hand pole, about 200 mm from the top. Pull it snug and tuck the short tail alongside the standing part so the wraps trap it.
Four wrapping turns, woven over and under: over the left pole, under the middle, over the right, then back over the right, under the middle, over the left. Keep them loose enough to slip a finger under. This is the part everybody gets wrong.
Two frapping turns in each gap. Take the working end down between the left and middle poles, around the wraps, and back up. Twice. Then the same in the gap between the middle and right poles. Frapping turns run at right angles to the wraps and pull the whole bundle together sideways.
Clove hitch on the right-hand pole to finish, tied exactly as the first one, and dress the tail back under the frapping so nothing hangs loose.
Stand the bundle up and walk the two outer legs out. Each pole turns a quarter turn inside the wraps, every wrapping turn shortens as it takes up that rotation, and the lashing pulls itself tight.

Reading bark and leaves

2026-08-19T00:00:00+01:00

For half the year a British wood has no leaves on it. From the end of October to the middle of April, the field guide in your pocket is mostly photographs of things that are not currently present. The wood stays perfectly identifiable through January, and the people doing it cannot always tell you how.

This is a key for ten common trees, built on the features available all year, with leaf shape as confirmation rather than the starting point. It is aimed at anyone who takes a group into a wood and gets asked what that one is.

Branching first, leaf second

Before looking at a single leaf, look at how the twigs come off the branch. Either they sit in pairs directly opposite each other, or they alternate up the twig one at a time.

Almost every British tree has alternate branching. The opposite-branching ones are a short list: maples including sycamore and field maple, ash, dogwood, the Caprifoliaceae including elder and honeysuckle, and horse chestnut. Scouting books teach it as MADCap Horse, and it is the single most useful thing to check first, because it removes most of a wood in one look and it works in December.

Most of that list is shrubs. Dogwood, elder and honeysuckle sit at shoulder height and never form a canopy. So when the opposite branching belongs to a full sized tree, the candidates come down to four: ash, sycamore, field maple and horse chestnut.

What the leaf is made of

A leaf answers two questions in order. Is the blade one piece or several, and if several, how are they arranged.

Simple leaves are one blade on one stalk. Oak, beech, birch, hazel, holly and sycamore are all simple, however deeply the edge is cut. A sycamore leaf has five lobes but the blade never separates, so it stays one leaf.

Compound leaves are divided into separate leaflets, each with its own small stalk. Pinnate compound means leaflets ranged along a central stalk like a feather, which is ash. Palmate compound means leaflets radiating from one point like fingers, which is horse chestnut.

The trap is telling a compound leaf from a twig bearing simple leaves. The test is the bud: a leaflet has no bud where it joins the stalk, and a leaf always has one where it joins the twig. Follow the stalk back until you find a bud, and everything beyond that point is a single leaf.

Then the margin, which separates the simple leaves from each other. Entire means smooth, serrate means toothed, doubly toothed means large teeth carrying smaller teeth of their own, and lobed means the edge cuts deeply toward the midrib without ever reaching it.

Why bark cracks at all

A trunk gets thicker every year. A thin sleeve of living tissue, the vascular cambium, lays down new wood on its inner face and new phloem on its outer face, so the wood you can see is only the outside of a stack that has been growing outward for decades.

Outside that sits the bark, and the outer part of the bark is dead. It is made by a second sleeve, the cork cambium, and once a layer of cork is finished it has no way of growing. So a trunk expanding underneath a rigid dead skin has two options, and different species take different ones.

Beech, holly and hornbeam keep the original cork cambium alive. It expands with the trunk year after year, so the surface stays continuous and smooth for the life of the tree. A beech at 200 years old has the same grey skin it had at twenty, stretched.

Oak, ash, pine and most other trees abandon it. New cork cambiums form in successive arcs deeper inside the bark, and each one cuts off the tissue outside it, which dies. That accumulating dead layer is the rhytidome, and it cannot stretch, so it splits. Where it splits is set by the species, and the pattern is consistent enough to name a tree from thirty metres away.

Birch does something in between. Its cork cambium makes broad flexible sheets loaded with betulin, the white waterproof compound that gives the bark its colour and lets it burn when soaking wet. The sheets part along the lenticels, the horizontal pores the trunk breathes through, which is why birch peels in horizontal strips and never vertical ones.

The ten trees

Each plate has the leaf on the left and the bark on the right.

Oak

Alternate branching. The leaf is widest above the middle, with four or five rounded lobes a side, almost no stalk, and two small ear shaped lobes where the blade meets the stalk. The bark carries deep vertical fissures cross linked into short blocks. Pedunculate oak has long stalked acorns and near stalkless leaves; sessile oak reverses both.

Ash

Opposite branching. One leaf is a slender stalk carrying five or six pairs of toothed leaflets and a terminal one, so a single ash leaf can be 300 mm long. The bark is pale grey with shallow ridges meeting in a lattice of diamonds. In winter the buds are sooty black, and nothing else in Britain has them.

Beech

Alternate branching. The leaf is a plain oval with a pointed tip, the margin gently wavy and never toothed, with straight parallel side veins running out to each wave and a fringe of silky hairs when young. The bark is smooth silvery grey and stays smooth for the life of the tree.

Sycamore

Opposite branching. One blade, five lobes cut about halfway to the centre, coarse blunt teeth, on a long stout stalk. The bark is grey with a pink tinge, flaking away in irregular rounded plates that leave paler patches behind. The seeds are the familiar winged pairs.

Silver birch

Alternate branching. A small triangular leaf with a broad base and doubly toothed margin, large teeth carrying smaller teeth of their own. The bark is white and papery, peeling in horizontal strips, marked with dark lenticel lines and breaking into rough black diamonds near the base. The twigs are warty and hairless, which separates it from downy birch.

Hazel

Alternate branching. Almost circular, with an abrupt short point, a heart shaped base, and a soft downy surface puckered by impressed veins. The bark is smooth coppery brown with pale horizontal lenticels and no fissures at all. Hazel usually stands multi stemmed from old coppice, and carries catkins from January.

Horse chestnut

Opposite branching. Five to seven leaflets radiate from one point at the top of a stout stalk, each widest near its tip. The bark is grey brown and breaks into coarse scaly plates that lift at the edges. The buds are large and sticky. It is not native, and arrived here around 1600.

Holly

Alternate branching, and evergreen. Stiff, glossy, very dark green, with spines at the crest of each wave in the margin. Those spines are a response to browsing, so above the height a deer can reach the same tree often carries smooth edged leaves with no spines at all. The bark is smooth pale grey with scattered warty bumps. Berries appear on female trees only.

Scots pine

Needles in pairs, 40 to 70 mm, blue green and twisted, each pair joined at the base by a small brown sheath. Counting the needles in a bundle is the test: two means Scots pine, and Britain has no other native pine. The bark runs orange pink and papery high on the trunk and grey brown in deep fissured slabs at the base.

Yew

Needles single and flat, set in two ranks so the whole spray lies flat, and soft enough to run a hand along. The bark is red brown, peeling in thin flakes, over a trunk that is fluted and often made of several fused stems. Yew carries red arils rather than cones, and every part of the tree except the flesh of the aril is poisonous.

The reframe

The field guides do not say this plainly. Bark pattern is not a portrait of a species. It is the record of how a dead outer layer failed under the strain of the trunk growing, and the species only sets the rule for the failure.

Age sets how far that rule has run. A young oak is nearly smooth, because it has not yet grown enough girth to break its own bark into blocks. An old silver birch is black and coarsely fissured at the base while it is still white and papery at head height, because the base has been expanding for eighty years and the upper trunk for twenty. Growth rate matters too: the same species on a wet fertile site cracks deeper than one on a dry exposed ridge, because the strain arrives faster.

So read two places on the same tree, not one. The base and the crown of a Scots pine disagree, and the disagreement is itself the identification.

Running the key

Winter, when there is nothing to pick

Buds are as diagnostic as leaves and they are on the tree from October. Six of these ten are settled in a second by the bud alone.

Tree	Bud
Ash	sooty black and velvety, in opposite pairs. Nothing else in Britain is black
Beech	long, slender, sharply pointed, copper coloured, held out at an angle from the twig
Horse chestnut	large, fat, sticky to the touch, red brown
Sycamore	green with dark scale edges, opposite
Oak	small and clustered together at the very tip of the twig
Hazel	small, oval, blunt, green flushed red, and catkins hanging from January

Silver birch keeps its warty hairless twigs, which separates it from downy birch. Holly, yew and Scots pine keep their leaves, so they need no winter test at all.

Ash is the sad case. Ash dieback, caused by the fungus Hymenoscyphus fraxineus, has been through most of the country, and many of the ash you find now are dead or dying with sparse crowns and diamond-shaped lesions on the bark. The black buds are still the giveaway.

What the timber is for

Naming a tree matters more once you want to cut something from it.

Ash is the handle wood. Straight grained, tough and shock resistant, it takes repeated impact without splitting, which is why axe handles, tent pegs and tool shafts are ash. It steam bends well and seasons quickly.

Hazel is the greenwood staple. It grows multi-stemmed from coppice, cleaves cleanly along its length, and bends almost double when green without breaking. Hurdles, spars, bean poles and walking sticks all come from hazel, and a coppiced stool will keep producing for centuries.

Sycamore is pale, close grained and completely odourless, so it goes into anything that touches food. Spoons, bowls, butter pats and dairy equipment are traditionally sycamore for that reason.

Birch turns beautifully and plywoods well, but it rots fast in contact with the ground. The bark is the real prize: peel a loose strip from a fallen trunk and it lights from a spark even after rain.

Oak is the structural timber, durable outdoors for decades, and it comes with a warning. Oak is full of tannin, tannin reacts with iron, and the reaction both corrodes the fastener and stains the wood black around it. Use brass, copper or stainless in oak, and keep steel clamps off wet oak.

Beech turns and steam bends as well as anything, which made it the chair wood of the Chilterns, but it has almost no durability outdoors. Keep it indoors and dry.

Yew gives the classic self bow, because a stave cut across the boundary between heartwood and sapwood gets a compression-strong belly and a tension-strong back in one piece with no glue. Every part of the tree except the flesh of the aril is poisonous, and the dust is an irritant, so wear a mask when you sand it.

Scots pine is the construction softwood, and a resin-soaked stump left in the ground for years becomes fatwood, which shaves into the most reliable natural firelighter available in Britain.

Horse chestnut and holly are the two to leave standing. Horse chestnut timber is soft and weak with almost no use. Holly is white and dense enough for inlay, and it dyes black as a substitute for ebony, but the tree grows slowly enough that felling one for the sake of it is a waste.

The two-minute routine

Branching. Opposite or alternate. That is your first cut.
Leaf. One blade or several leaflets, and how the edge is cut.
Bark, twice. Once at chest height, once as high up the trunk as you can see.
The ground. Acorns, conkers, nut shells, winged seeds and old leaf litter are all still there in February.
Buds, if the tree is bare.

Get into the habit of naming the tree before you look at a leaf. It is slower for the first month and much faster afterwards, and it is the only version that works in winter.

Digital Design 01: Mask sets, and how a transistor gets built

2026-08-18T00:00:00+01:00

Series: Digital Design Fundamentals | Article 1

The forty pence chip

A small microcontroller in a reel of three thousand costs about forty pence. It holds a processor, flash, RAM, a handful of timers and a bootloader, and the supplier will happily sell you one.

The set of photomasks used to make it cost somewhere north of a quarter of a million pounds, paid once, years ago, before a single working part existed. Nothing about the forty pence recovers that. The forty pence is glass, gas, electricity, packaging and test, spread over tens of millions of parts. The quarter of a million was the price of being allowed to start.

This article is about that gap. It covers the photomask itself, the sequence of masks that builds a metal-oxide-semiconductor field-effect transistor (MOSFET) out of a blank wafer, why the number of masks keeps rising, the approximate cost of a mask set at each process geometry, and what a respin costs when the first attempt is wrong. It targets anyone learning digital design who has been told "the transistor is a switch" and would like to know where the switch comes from, and anyone weighing a custom chip against a field-programmable gate array (FPGA).

A mask is a stencil, and there is one per patterned layer

A chip is not carved. It is built up in layers, and every layer that needs a pattern gets that pattern from a photomask: a flat plate of fused silica, usually a 6 inch square a quarter of an inch thick, carrying an opaque chrome image of the shapes for that one layer. Fused silica is amorphous silicon dioxide, chosen because it is transparent at the exposure wavelength and barely expands when the plate warms up. In the trade it is often called a quartz plate, though it is not quartz: quartz is crystalline, fused silica is not. The mask is glass. The wafer it prints onto is single-crystal silicon. They are not the same material.

Three facts about the mask decide most of the economics that follow.

It is not the same size as the chip. In a modern scanner the mask, called a reticle, is drawn four times larger than the pattern it prints. The optics demagnify the image by four on its way to the wafer, so a 1 micrometre chrome feature on the plate prints a 250 nanometre feature in resist. Making the plate is therefore easier than making the chip, which is the only reason the plate can be made at all.

One exposure covers a small area. The reticle field is roughly 26 mm by 33 mm at the wafer. A 300 mm wafer holds a few hundred of those fields, and the scanner steps across the wafer exposing them one at a time. A die larger than the reticle field cannot be printed in one shot, which is a hard ceiling on single-die size and one of the arguments for chiplets.

One mask means one layer, one shot. The mask has no adjustments. Every change to the design, however small, on whatever layer, means a new plate for that layer. This is why a bug found after tape-out is expensive in a way that software bugs are not.

The resolution the scanner can print follows the Rayleigh relation:

smallest half-pitch  =  k1 x wavelength / numerical aperture

with k1 a process factor around 0.3 in practice. Deep ultraviolet immersion lithography uses 193 nm light and a numerical aperture of about 1.35, giving roughly a 40 nm half-pitch in a single exposure. That number is the wall the industry has been climbing over since 2005, and the way it climbed over is the reason mask counts exploded. More on that below.

Building an inverter's transistors, one mask at a time

The complementary metal-oxide-semiconductor (CMOS) process needs two kinds of transistor: an nMOS, which conducts when its gate is high, and a pMOS, which conducts when its gate is low. Both are built simultaneously on the same wafer, and the sequence below produces one of each.

The starting material is a polished slice of single-crystal silicon, lightly doped p-type, 300 mm across and under a millimetre thick.

1. n-well (mask 1). A pMOS needs to sit in n-type silicon. The n-well mask opens windows where phosphorus or arsenic is implanted and driven in, creating tubs of n-type material inside the p-type wafer. Every pMOS on the chip lives in one of these.

2. Isolation (mask 2). Trenches are etched between the regions that will become transistors and filled with oxide. This is shallow trench isolation, and it stops neighbouring devices leaking into each other. The mask defines the active areas, meaning everywhere a trench is not.

3. Gate oxide. A thin insulating layer is grown over the whole active area, a few atoms thick at modern nodes. No mask: it is grown everywhere and removed later where it is not wanted. This layer is the "oxide" in MOSFET, and the capacitor it forms lets a voltage on the gate control the silicon underneath without any current flowing into the gate.

4. Gate (mask 3). Polysilicon is deposited over the whole wafer, then patterned. What survives is the gate electrode. The width of that stripe where it crosses an active area is the channel length, historically the number a process is named after: the 130 nm process drew a 130 nm gate.

This is the most critical mask in the set. Channel length sets drive current and switching speed, so its dimensional control drives the entire process.

5. Source and drain (masks 4 and 5). Dopant is implanted on both sides of the gate: n-type for the nMOS regions, p-type for the pMOS regions, so two masks, each blocking the areas the other one implants. The gate itself blocks the implant from the silicon directly beneath it, so the source and drain end up self-aligned to the gate rather than aligned by the scanner. That trick, introduced around 1970, removed alignment tolerance from the most sensitive dimension on the chip and is the reason the polysilicon gate replaced the earlier aluminium one.

At this point there are transistors, and they are connected to nothing.

6. Contacts (mask 6). Oxide is deposited over everything and holes are etched down to each source, drain and gate, then filled with tungsten. These are the plugs the wiring connects to.

7. Metal 1 (mask 7), via 1 (mask 8), metal 2 (mask 9), and so on. Each metal layer is a mask, and each layer of vias joining two metals is another mask. Modern logic processes stack ten to fifteen metal layers: the lowest are thin and dense for wiring inside a standard cell, the highest are thick and wide for power distribution and long-distance signals.

8. Passivation and pads (final masks). A protective layer over the whole die, with openings where bond pads or bumps need to make contact with the outside world.

Counting: two masks before the transistors exist, three to make them, one for contacts, and then two per metal level for the rest. A simple two-metal process lands around twelve masks. A fifteen-metal modern logic process is already past forty before any of the complications below.

How the switch actually switches

The masks have produced a structure. Nothing so far explains why a voltage on a plate of metal sitting over an insulator should control a current flowing underneath it, several nanometres away, through material the plate never touches.

Start with the device at rest. The source and drain are islands of n-type silicon in a p-type substrate, which makes two diodes back to back. Put a voltage across them and one of the two is always reverse biased, so no useful current flows between source and drain no matter what the drain voltage does. The transistor is off, and it is off because there is nothing joining the two islands.

Now raise the gate. The gate, the oxide and the silicon underneath form a capacitor: two conductors separated by an insulator. Charge on the gate therefore pulls an equal and opposite charge to the silicon surface, without a single electron crossing the oxide.

That induced charge arrives in two stages.

Below the threshold, the surface merely empties. A positive gate repels the holes that a p-type substrate is full of, pushing them down and away. What is left behind is a depleted layer, carrying no mobile charge at all. There is still no path from source to drain.

Above the threshold, the surface changes type. Push harder and the gate starts attracting electrons rather than just repelling holes. They gather in a thin sheet at the oxide interface, and where there was p-type silicon there is now a film of n-type silicon a few nanometres thick. That film is the channel, and it joins the source island to the drain island. The gate voltage at which this happens is the threshold voltage, and it is one of the numbers a process is built around.

Once the channel exists, a voltage between drain and source moves electrons along it. More gate voltage pulls in more electrons, which lowers the channel resistance and raises the current. The transistor is not a mechanical contact being closed. It is a resistor whose value is set by a voltage on a capacitor plate.

Four consequences run through everything in this series.

The gate draws no steady current. It is one plate of a capacitor, so a finished logic gate can hold its inputs at a value forever and spend nothing doing it. Only the transitions cost energy, because each one charges or discharges that capacitance. This is why complementary metal-oxide-semiconductor logic displaced the alternatives, and why power scales with switching activity.

Thin oxide means a stronger grip. Bring the plate closer and the same voltage induces more charge, so the device switches at a lower voltage and carries more current. Hence gate oxides a handful of atoms thick, and hence the industry moving to hafnium-based insulators once silicon dioxide could get no thinner without leaking outright.

Short channels are fast and leaky. A shorter channel is a shorter distance for electrons to cross, so the device is quicker, which is the whole point of shrinking. It also means the drain sits closer to the source and starts influencing the channel that the gate is supposed to control alone. Every structure in the modern device list, from FinFETs to gate-all-around nanosheets, exists to wrap the gate further around the channel and win that argument back.

Off is not zero. Below the threshold the current falls exponentially rather than to nothing, so several billion transistors that are all switched off still add up to a measurable leakage current. Standby battery life is largely a fight with that number.

The pMOS works the same way with every sign reversed. It sits in the n-well from mask 1, its source and drain are p-type, and pulling the gate below its source attracts holes to the surface to form a p-type channel. An nMOS conducts when its gate is high; a pMOS conducts when its gate is low.

That pair of sentences is the entire input to the next article. Two switches, each closed by the opposite condition, each with an insulated gate that costs nothing to hold. Everything in a logic library is built by wiring those two kinds of switch into networks.

What one masking step actually involves

Every one of those numbered steps expands into the same loop. The mask count multiplies its cost and its yield risk.

Photoresist is a polymer whose solubility changes where light hits it. Expose, develop, and the mask pattern now exists in resist on the wafer. Etch, and it exists in the film underneath. Strip the resist, and the layer is finished.

Two consequences fall out of the loop.

A wafer visits the scanner once per mask, and the scanner is the most expensive tool in the fab. Mask count therefore drives cycle time and wafer cost together, not just the one-off cost of the plates. A forty-mask flow takes six to eight weeks of processing; an eighty-mask flow takes three months or more.

Every step is an opportunity to lose the die. A single particle in one exposure kills the chips it lands on. With eighty steps, per-step yield has to be extraordinary before the product of them is usable, which is why fabs are obsessive about contamination and why defect density, not lithography, usually limits how large a die can economically be.

Why the mask count keeps climbing

Single-exposure 193 nm immersion lithography stops at roughly 40 nm half-pitch, and the industry reached that around the 32 nm node. The features kept shrinking anyway. Three mechanisms did it, and all three cost masks.

Multiple patterning. Split one dense layer into two or more sparser layers, each printable on its own, and superimpose them. Litho-etch-litho-etch (LELE) turns one mask into two, LELELE into three. Self-aligned double and quadruple patterning (SADP, SAQP) print a sparse grid and use deposited spacers to halve the pitch, then need cut masks to remove the unwanted segments. A single logical layer such as metal 1 can consume four or five plates at 10 nm and 7 nm.

More structure per transistor. A planar transistor is a stripe of poly over a flat active area. A FinFET is a set of vertical fins, needing a fin-definition mask and fin-cut masks. A gate-all-around nanosheet device stacks channels vertically and adds its own patterning steps. Extra masks buy tighter electrostatic control of the channel, which keeps the switch behaving like a switch at these dimensions.

Extreme ultraviolet lithography pushes the other way. EUV uses 13.5 nm light prints in a single exposure a pattern that deep ultraviolet needed three or four exposures to build up, so it removes masks from the critical layers even as it raises the cost per mask sharply. It also abandons the quartz plate. Nothing is usefully transparent at 13.5 nm, so an EUV mask is a mirror rather than a stencil: a low-expansion glass blank, about forty alternating molybdenum and silicon layers to reflect the light, and a tantalum-based absorber patterned on top. That construction is a large part of an EUV plate's price. It also explains why 7 nm and 5 nm did not carry on doubling their mask counts: EUV collapsed several of the worst multi-patterned layers back into one plate each.

Node	Typical mask count	Metal layers	Masks in the metal stack	What is driving it
250 nm	20 to 24	4 to 5	8 to 10	Planar, aluminium wiring, single exposure everywhere
180 nm	24 to 28	5 to 6	10 to 12	More metal layers
130 nm	28 to 32	6 to 8	12 to 16	Copper interconnect arrives
90 nm	32 to 36	7 to 9	14 to 18	Strained silicon
65 nm	36 to 40	8 to 10	16 to 20	Immersion lithography arrives
40 nm	40 to 45	9 to 11	18 to 22	Immersion at the limit, more resolution enhancement
28 nm	45 to 50	10 to 12	20 to 25	Last node before multiple patterning is unavoidable
16 nm	55 to 65	11 to 13	24 to 32	FinFET, and double patterning on the lower metals
7 nm	75 to 85	13 to 15	32 to 42	Multi-patterning at its worst, early EUV
5 nm	80 to 90	14 to 16	34 to 44	EUV on many critical layers, extra device-level masks
3 nm	85 to 100	15 to 18	36 to 48	More EUV layers, gate-all-around structures

The metal stack is the reason the totals climb so steadily. Each metal level needs a mask for the wires and another for the vias beneath them, so a level costs two plates, and the lowest two or three levels need multiple patterning at 16 nm and below. Roughly half of a modern mask set is wiring.

Treat these as ranges, not specifications. Every foundry has several flavours of each node, and options such as extra metal layers, embedded flash, high-voltage devices or radio-frequency passives add masks on top.

Mask set cost, in round numbers

Mask cost is not published in any consistent way, and real quotes are covered by non-disclosure. What follows are the orders of magnitude generally cited in the public literature and in multi-project wafer programme pricing. Use them for deciding which node to think about, and never for a purchase order.

Node	Full mask set (A0)	Metal-only spin (A1)	Per-plate feel
250 nm	£50k to £120k	£15k to £40k	A few thousand each, no resolution enhancement
180 nm	£100k to £250k	£30k to £80k	Still cheap plates, more of them
130 nm	£200k to £400k	£60k to £140k	Optical proximity correction starts to matter
90 nm	£400k to £800k	£120k to £250k	Correction on most layers, phase shift on critical ones
65 nm	£700k to £1.5M	£200k to £450k	Heavy resolution enhancement
40 nm	£1.5M to £3M	£400k to £900k	Critical plates cost tens of thousands each
28 nm	£2M to £4M	£600k to £1.2M	The value node, still popular for exactly this reason
16 nm	£4M to £8M	£1.2M to £2.5M	FinFET plus double patterning
7 nm	£8M to £15M	£2.5M to £5M	Mask count and plate cost rise together
5 nm	£12M to £25M	£4M to £8M	EUV plates alone are six figures each
3 nm	£20M to £40M	£6M to £12M	Where "who is this for" becomes the real question

Two things drive the climb. The plates get more numerous, as the previous table shows. And each critical plate gets more expensive, because the chrome pattern is no longer a copy of the drawn layout: optical proximity correction deliberately distorts it, adding serifs, hammerheads and scattering bars so that the diffracted image on the wafer comes out the shape you wanted. Those corrections are computed for every polygon on the layer, which is why a single advanced critical mask can take days of compute and a six-figure sum before it is written.

And the mask set is only one line in the total. Design tool licences, intellectual property blocks, engineering time, packaging, test development and qualification are usually larger. A 28 nm project is commonly quoted in the tens of millions all-in; a 5 nm one in the hundreds of millions. The mask set is the part that is easiest to point at, not the part that dominates.

Not every project buys a set. A multi-project wafer run shares one reticle between many customers, each taking a few square millimetres, and splits the mask cost accordingly. University and small-company shuttles at 180 nm or 130 nm come in at low tens of thousands, and open-source shuttles on a 130 nm process have put a small design on real silicon for a few hundred. You get a few tens of packaged parts, not a product, but for learning, for research, and for proving an idea, prototyping never touches a full mask set.

A0, A1, B0: the price of being wrong

Silicon revisions are named by a convention borrowed from the processor vendors, and it encodes exactly the distinction the two columns above draw.

A stepping name is a letter and a digit. The letter counts base layer revisions, meaning the transistors themselves. The digit counts metal revisions on top of those base layers.

Stepping	Meaning	Letter	Digit	Masks needed
A0	First silicon	A, the first	0, no metal revisions yet	Full set, every layer
A1	Metal-only spin	A, unchanged	increments to 1	Metal and via layers only
B0	All-layer spin	increments to B	resets to 0	Full set again

The digit climbs while the transistors stay as they are: A0, A1, A2. The moment a fix needs a different transistor rather than a different wire, the letter increments, the digit resets, and the part becomes B0 at full mask set cost. Metal spins on the new base layers then start again at B1.

A metal-only spin works because the fault is in the connections, not the devices. The fab holds partly processed wafers at the point where the transistors are finished and the wiring has not started, a stage usually called the wafer bank. A new set of metal and via plates goes on top of banked material, so an A1 pays for a fraction of the plates and skips a fraction of the processing.

Two consequences follow, and both are decisions taken long before the bug exists.

It has to be designed for. A metal fix can only rewire gates that are already on the die. Teams scatter spare cells across the floorplan, or use a gate-array style fabric, precisely so that an engineering change order has something to connect. Without that, every fix is a B0.

The time matters more than the money. An all-layer spin repeats the full flow: ten to fourteen weeks at an advanced node, six to eight at a mature one, before packaged parts come back. A metal-only spin starts from banked wafers and turns around in three to six weeks. In a market with a launch date, the schedule usually decides the argument, not the several million pounds.

This is the real reason verification budgets look the way they do. The alternative to finding a bug in simulation is a number from one of those two columns, plus a quarter of a year.

The thing the price tag is actually measuring

The natural reading of that table is that advanced silicon is expensive. Turned around, it says something closer to the truth.

Cost per transistor has fallen for fifty years. Cost per design has risen for the same fifty years. The mask set is not the price of a chip. It is the price of the decision to make a chip that is different from every other chip, paid before you know whether the design is correct.

Every structural feature of the industry follows from those two curves crossing. System on chip integration exists because once you are paying for a mask set, adding more function to the same die is nearly free, while a second die means a second set. FPGAs exist because someone else already paid for the mask set and sells you a share of it. Chiplets exist because splitting a system lets the parts that need 3 nm go there while the parts that do not stay on 28 nm and keep their cheap masks. Mature nodes stay busy for decades because a design that fits in 130 nm has no reason to pay 5 nm mask costs. The forty pence microcontroller is a mask set from years ago, fully amortised, still printing.

Before you pick a node

A short checklist for the moment this stops being theory.

Work out the mask cost per unit at your expected volume first. A £3M mask set over 10,000 parts is £300 per part before anything else. Over 10 million it is 30 pence.
Ask whether you need the density. If the design fits comfortably in 130 nm or 65 nm, the cheap masks and the mature yield are worth more than the transistor count.
Check whether a multi-project wafer covers your prototype. Two shuttle runs and a full set afterwards is usually cheaper than getting a full set wrong.
Count your metal layers. They are two masks each, they are around half the set, and an over-generous stack is a quiet line item.
Decide before tape-out whether you want the option of a metal-only spin, and put the spare cells in to support it. That choice separates a three week A1 from a three month B0.
Treat tape-out as irreversible. There is no patch. Everything the verification and sign-off effort costs is being compared against the numbers in that table.

The masks make transistors. The next article wires two kinds of transistor into the smallest useful circuits: the inverter, the NAND and the NOR, and the pull-up and pull-down networks that decide why those three are the gates the libraries are built from.

Next: Digital Design 02: Pull-up and pull-down networks

SoC Intermediate 03: Pipeline design and hazards

2026-08-16T00:00:00+01:00

Series: Intermediate SoC Design | Article 3 of 10

The stage that made it slower

The timing report said the execute stage was the critical path. You split it in two, added a pipeline register, and closed timing at 1.3 GHz instead of 1.2. An extra eight per cent of clock, for one register stage and a week of work.

Three of the four benchmarks gained around eight per cent, exactly as the frequency did. The fourth, a pointer-heavy workload full of branches that go whichever way the data feels like, lost four per cent. Same RTL, same compiler, same test, faster clock, less work done.

This article is about pipeline hazards: the conflicts that appear the moment instructions overlap, the hardware that resolves them, and the reason stage count is such a fraught number. It targets engineers designing or verifying a processor pipeline, and anyone reading a microarchitecture manual and wondering why nobody simply builds a forty-stage machine.

What overlapping actually buys

Classic reduced instruction set computer (RISC) pipelines are usually explained with five stages, and the explanation is worth keeping because every later complication attaches to one of them.

Stage	Name	Work
IF	Instruction fetch	Read instruction memory or the instruction cache
ID	Decode and register read	Decode the opcode, read the register file
EX	Execute	Arithmetic logic unit operation or address calculation
MEM	Memory	Data memory or data cache access
WB	Write back	Write the result to the register file

A single instruction still takes five cycles from fetch to writeback. Nothing about pipelining makes one instruction faster. What it changes is how many instructions can be in progress at the same time.

Latency is five cycles. Throughput approaches one instruction per cycle. Every stage boundary you add shortens the critical path between registers, which is why the timing report kept suggesting more of them.

The diagram above is also a lie of omission. It shows four instructions that have nothing to do with each other. Real code is not like that.

Three ways instructions collide

An instruction in a pipeline is no longer isolated. It may need a value, a decision, or a piece of hardware that an older instruction has not finished with. Those conflicts are pipeline hazards, and they come in three kinds.

Data hazards. An instruction needs a value that is not available yet.
Control hazards. The next program counter depends on a branch or an exception that has not resolved yet.
Structural hazards. Two stages want the same piece of hardware in the same cycle.

Everything else in this article is the disciplined handling of those three, without producing wrong results and without stalling more than necessary.

Data hazards and the bypass network

Take the shortest dependent pair in any instruction set:

add x3, x1, x2     // x3 = x1 + x2
sub x5, x3, x4     // needs x3 immediately

The add writes x3 in WB, in cycle 4. The sub reads its operands in ID, in cycle 2, and needs them in EX in cycle 3. Left alone, the sub reads the old value of x3 and quietly computes the wrong answer.

Waiting is one answer, and it costs three cycles on a pattern that appears in almost every basic block. The better answer is that the value already exists. It sits in the EX/MEM pipeline register at the end of cycle 3, fully computed. It is simply not in the register file yet.

Forwarding, also called bypassing, routes that result straight back to the input of the execute stage instead of waiting for writeback.

Each execute-stage operand becomes a multiplexer choosing between three sources: the register file value, the result of the immediately preceding instruction sitting in EX/MEM, and the result of the instruction before that sitting in MEM/WB. Priority matters. If both bypass sources match, the younger one wins, because it holds the more recent value.

With those two paths in place, back-to-back arithmetic dependencies cost nothing at all. This is the single highest-value structure in an in-order pipeline, and it is why a naive stall-on-dependency design performs so badly by comparison.

The one it cannot fix

Forwarding works because the value exists somewhere earlier than the register file. Loads break that assumption.

lw  x3, 0(x1)
add x5, x3, x4

The load data arrives from the data cache at the end of MEM, in cycle 3. The dependent add wants it in EX, also in cycle 3, and no wire runs backwards in time. One cycle of stall is unavoidable.

The pipeline holds IF and ID in place for a cycle and injects a bubble into EX. After the stall, the ordinary MEM/WB bypass path delivers the value and the add proceeds.

Detecting it is a comparison between the instruction in ID and the load already in EX:

assign load_use_hazard =
    ex_is_load &&
    (ex_rd != 5'd0) &&
    ((ex_rd == id_rs1) || (ex_rd == id_rs2));

assign stall_if          = load_use_hazard;
assign stall_id          = load_use_hazard;
assign insert_bubble_ex  = load_use_hazard;

The ex_rd != 5'd0 term earns its place. On RISC-V, register x0 reads as zero and discards writes, so a load into x0 produces no value anybody can depend on. Without the check, every discarded load stalls a following instruction that reads x0, which is a common idiom. Whatever your instruction set, find its equivalent and prove it does not create phantom hazards.

Compilers know about this stall and schedule an independent instruction into the gap when they can find one. When they cannot, the cost is real, and it scales with how many cycles late the load data is.

Control hazards and the cost of guessing

A branch changes the program counter, and the pipeline has already fetched past it. In a five-stage design the condition resolves in EX, by which point two younger instructions are in flight.

Waiting for the branch is the honest option and the slow one. It costs two cycles on roughly one instruction in five. Resolving the branch earlier in ID helps, at the price of a comparator on the critical path and a new forwarding problem for the values being compared.

Every high-performance pipeline takes the third option: guess, and clean up when the guess is wrong.

Two fetched instructions become bubbles. Note what determines that number: it is the distance between the fetch stage and the stage where the branch resolves. Not the total pipeline depth, and not the branch itself.

Predictors, and why two bits

A static predictor guesses from the instruction alone. Backward branches are assumed taken and forward branches not taken, which is a decent guess because backward branches are usually loops. It costs almost nothing and is right about two thirds of the time.

Dynamic prediction learns from what the branch did before. The smallest useful structure is a two-bit saturating counter per branch.

The second bit is the whole point. A loop that runs a hundred times and exits once would, with a one-bit predictor, mispredict twice per execution of the loop: once on the exit, and once again on the next entry, because the single bit was flipped by that exit. The two-bit counter absorbs the anomaly, drops from strong to weak, and keeps predicting taken.

Real branch prediction units go much further, with global history, tagged geometric-length tables, branch target buffers, and return address stacks. They all rest on the same trade: storage and complexity in exchange for a lower misprediction rate, because misprediction is the thing that costs cycles.

When the guess is wrong, the younger instructions have to disappear:

assign flush_if_id = branch_resolved && branch_mispredict;
assign flush_id_ex = branch_resolved && branch_mispredict;
assign next_pc     = branch_mispredict ? branch_target : pc_plus_4;

A flush turns wrong-path instructions into bubbles. It must also suppress every side effect they could have had: register writes, memory writes, control and status register updates, and any outstanding request already issued to a multi-cycle unit. A flush that clears the valid bit but leaves a store enable asserted is a memory corruption bug, and it will only appear when the branch and the store line up in one specific way.

What the extra stage actually bought

Now the opening result. Return to that pointer-heavy benchmark, and put numbers against the two designs.

Cycles per instruction (CPI) starts at 1.0 for a full pipeline and gets worse from there. On this workload, a quarter of instructions are branches, a fifth of those branches are mispredicted because the data decides them, and loads feed a dependent instruction immediately about half the time.

Contribution	Five-stage	Six-stage
Base	1.00	1.00
Branch mispredict penalty	3 cycles, 0.15	5 cycles, 0.25
Load-use stall	1 cycle, 0.075	2 cycles, 0.15
Cache misses and other	0.10	0.10
CPI	1.325	1.50
Clock	1.2 GHz	1.3 GHz
Instructions per second	906 M	867 M

The extra register stage did exactly what it was asked to do. It shortened the critical path and the clock went up. It also moved branch resolution one stage further from fetch and put the load data one cycle further from the consumer, so every mistake got more expensive at the same time.

Here is the reframe. A pipeline stage costs nothing while the pipeline is right, and costs the entire pipeline when it is wrong. You are not buying throughput with depth. You are buying frequency, and paying for it with the penalty on every event that discards work.

That explains the split in the results. The three benchmarks that gained were predictable ones, where the pipeline is right almost all the time and depth is nearly free. The one that lost was the one that is wrong constantly, where depth is charged on every mistake.

It also explains the shape of the industry. The deepest commercial pipelines appeared alongside the most elaborate branch predictors ever built, and that is not a coincidence. Depth is only affordable if you are right.

Structural hazards

The third class is the most mundane and the easiest to design out, if you find it before tape-out. A structural hazard is hardware oversubscription: two stages wanting one resource in one cycle.

The classic examples:

One memory port serving both instruction fetch and data access, so every load or store stalls a fetch. This is the reason for separate instruction and data caches.
A single register-file write port with two instructions completing at once, which happens as soon as any operation has a different latency from the rest.
A shared multiplier still busy with a multi-cycle operation.
Cache miss handling resources, such as miss status holding registers, already fully allocated.

The remedies are duplication, banking, arbitration, or stalling one user. Choosing to stall is legitimate, and choosing it by accident is not. Every resource with more than one potential claimant needs a documented arbitration policy, including what happens when the loser is starved.

Units that take their time

Multipliers, dividers, and floating-point units do not fit the one-cycle execute model. They need their own small state machine, and the pipeline needs to know when the result is coming.

The amber edge is the one that gets forgotten. If a branch flush or an exception can kill an operation while the unit is mid-calculation, the unit needs a valid bit or a transaction tag so a stale result cannot commit three cycles later against a program counter that no longer exists. Divider results arriving after the flush that should have killed them is a bug class of its own, and it is invisible until a divide happens to sit just before an unpredictable branch.

Precise exceptions

Software expects an exception to look instantaneous: every older instruction complete, no younger instruction having changed any architectural state, and a program counter that says exactly where to resume. The hardware, meanwhile, has five instructions in flight and has been speculating for the last three cycles.

Even an in-order pipeline has to work at this:

A faulting load must not be followed by a younger register write.
Wrong-path instructions must not perform stores.
Control and status register writes must be ordered with respect to exceptions.
The flush must clear every side-effect enable, not just the valid bits.
If two instructions fault in the same cycle, the older one wins, always.

Out-of-order processors solve this with a reorder buffer and an explicit commit stage. In-order pipelines solve it with valid bits and a clearly designated point past which effects become visible. The mechanism differs, the rule does not: pick one place where speculation ends, and let nothing escape it early.

Design checklist

Settle these before writing the datapath, because retrofitting any of them is painful:

Put a valid bit beside every pipeline register and treat it as the only thing that makes a stage's contents real.
Name the exact stage that commits register writes, memory writes, and control register side effects. Write it in the specification.
Add forwarding paths only where the value genuinely exists in time, and check each one against the timing report before committing to it.
Prove the zero register, and any other write-discarding destination, cannot create a false hazard.
Treat branch flush, exception flush, and debug halt as three cases of one mechanism, and verify all three.
Give every multi-cycle unit a kill path, and test that a result cannot commit after the instruction that produced it was flushed.
Test the interactions, not the cases: a stall and a flush arriving in the same cycle, a load-use pair straddling a mispredicted branch, an exception on the instruction directly behind a stalled load.

Count the penalties before adding the stage

The design question is never "how deep should the pipeline be". It is "what does this stage add to the branch resolution distance and the load-use distance, and what is that worth on the code we actually run".

Both numbers are countable on a whiteboard before any RTL exists. Multiply each by how often the event happens in your workload, add them to the base CPI, and divide the new clock frequency by the result. If that number is not comfortably larger than the old one, the stage is not worth the week.

Point 7 of the checklist is where the real bugs live, and it is the point most often skipped. Stall-and-flush in the same cycle is one line in a verification plan and, judging by errata sheets, several months of somebody's life.

Previous: Article I-02: Cache coherency protocols Next: Article I-04: RTL synthesis and timing closure

Building a folding bucksaw

2026-08-06T00:00:00+01:00

A bow saw cuts firewood faster than a folding pruning saw, with less effort, and anyone who has used both in the same afternoon knows it within about three strokes. The frame holds the blade in tension, so the blade can be thin. The thinner the blade, the thinner the kerf, and the less material removed per stroke, which makes for an easier cut. Yet the saw most people actually carry is the folding one, because it is more compact and more convenient to pack.

This is a dimensioned build for a bucksaw that collapses into a bundle the length of its own blade, sized around a standard 610 mm (24 inch) blade. It is aimed at anyone with a saw, a chisel and a drill.

Tension is the whole point

A panel saw resists buckling by being thick. Push a thin steel strip through a cut and it folds sideways on the return stroke, so a saw meant to be used unsupported needs a plate stiff enough to hold itself straight. That stiffness has to be paid for with metal, and every extra thousandth of plate thickness is more wood turned into dust on every stroke.

A bow saw cheats. Stretch a thin blade between two points hard enough and it cannot buckle, because it is never in compression. All the straightness comes from the frame. That is why a bow saw blade can be 0.7 mm thick when a comparable hand saw plate is nearer 0.9 mm, and why the same log takes noticeably fewer strokes.

So the frame has exactly one job: pull the two ends of the blade apart and keep pulling while you work. Everything else in the design is in service of that.

The mechanism is a windlass. A cord runs between the tops of the two arms. Push a stick through the cord, twist it, and the cord shortens as it winds on itself. The arms pivot about the stretcher between them, so pulling their tops together drives their bottoms apart, and the blade pinned across those bottoms comes taut. The stretcher is the fulcrum. The whole frame is a pair of levers sharing a beam.

Making it fold without losing anything

The failure mode of a takedown saw is not breakage. It is a small metal part in leaf litter at dusk. Wing nuts, cotter pins and separate blade pins all work beautifully on a bench and all eventually get dropped in a wood.

So the rule for this build is that nothing on the saw comes off in the field. The blade attaches with a captive pin: a 4 mm pin driven permanently through each arm near its toe, spanning a slot cut down the middle of the arm. The blade eyelet drops over the pin from inside that slot and stays there for the life of the blade. Slacken the cord and the blade goes loose but does not detach. There is no fastener to undo, nothing to unthread, and it works in gloves.

Which means the blade and the two arms are permanently one assembly. To pack it, the arms have to fold with the blade still attached, and the only thing they can rotate about is the pin the blade already sits on.

Swing each arm ninety degrees about its own pin and it lies flat along the blade. One arm covers the left half, the other covers the right. The blade ends up sheathed inside the slots in its own arms, which is exactly where you want a set of exposed teeth to be.

The dimension you do not get to choose

Here is the part that reorganises the rest of the build.

If both arms fold down onto the blade and lie end to end, then together they can be no longer than the blade span. Each arm gets half. A 610 mm blade has roughly 597 mm between eyelet centres, so each arm can be about 300 mm above its pin and no more. Go longer and the two arms collide in the middle before either has finished folding.

The arm length is therefore fixed by the blade, not chosen by you. And the arm length is what the stretcher position is measured against, and the stretcher position is what sets the throat, the clear gap between blade and stretcher that decides the fattest log the saw will pass through.

You do not pick the throat depth of a folding bucksaw. The blade picked it, at the moment you decided the saw should fold.

For comparison, the classic non-folding H-frame uses 400 mm arms with the stretcher at mid height, and gets around 200 mm of throat from the same blade. Folding costs roughly a third of that. Worth knowing before you cut anything, because if you mostly saw thick rounds, the right answer is a saw that does not fold.

Throat against leverage

Given a 315 mm arm, the only remaining freedom is where the stretcher sits on it, and that is a straight trade.

Put the stretcher at mid height and the lever arms above and below the fulcrum are about equal, so the cord carries roughly the same tension as the blade. Comfortable to tension, but the throat comes out around 115 mm.

Slide the stretcher up to about sixty per cent of the arm height and the throat grows to 146 mm, which is the difference between passing a 115 mm round and a 145 mm round. The cost is leverage: the cord now sits 111 mm above the fulcrum while the blade hangs 169 mm below it, so the cord has to carry about one and a half times the blade tension for the same result. In practice that means a couple more turns on the toggle and a slightly beefier cord.

This build takes the throat.

Where the slot and the stretcher fight

One detail nearly sinks the design, and it is worth understanding rather than discovering.

The blade slot has to run the full length of the arm, because the folded blade needs somewhere to go along its whole half. It also has to be deep, because the blade is 25 mm wide, so the slot goes 35 mm into a 45 mm arm and opens on the inner face. That is the same face the stretcher wants to seat against. A conventional mortise cut there would break straight into the slot.

The fix is to stop treating it as a mortise. Cut a pocket instead: 20 mm along the arm, 10 mm deep, 19 mm across, opening on the inner face. Because the slot is only 1.5 mm wide and the pocket is far wider, the pocket does not cross the slot, it simply widens its mouth for 20 mm. The stretcher end drops in, tension holds it there, and the folded blade passes through the same space with room to spare. Leaving 3 mm of wood on each side of the pocket stops the stretcher wandering sideways.

Two things about that slot are worth stating because they look alarming and are not.

It costs almost nothing in strength. The arm bends in the plane of the frame, and a 1.5 mm cut straddling the neutral axis removes about three and a half per cent of the second moment of area. The arm is essentially as stiff as it was.

But it must stay full section at the pocket. The pocket sits at the fulcrum, which is where the bending moment peaks. Taper the arms above and below it if you want to lose weight, and leave the wood alone within about 40 mm either side.

Cut list

Ash is the right wood: tough, springy, and it takes the repeated tension cycles without setting. Beech and hickory both work. Avoid softwood, which crushes at the pocket.

Part	Qty	Length	Width	Thickness
Arm	2 (mirror pair)	315 mm	45 mm	25 mm
Stretcher	1	572 mm	38 mm	19 mm
Toggle	1	200 mm	19 mm	6 mm
Pin	2	25 mm	4 mm diameter	-

Plus a 610 mm bow saw blade and about 1.4 m of 550 paracord.

The blade used here is the Bahco 23-24, a 24 inch raker tooth hard point bowsaw blade, sold as 600 mm at Axminster and also stocked on Amazon. Raker tooth is the pattern to want for green wood: the rakers clear the sawdust out of the kerf instead of packing it in. Note that suppliers describe the same 24 inch blade as either 600 mm or 610 mm, which is another reason to measure the eyelet spacing on the blade in your hand rather than trusting the listing.

The arms are a mirror pair, not two identical parts. The slot opens on the inner face of each, so they are handed. Mark them before you cut.

Measure your own blade before committing to the stretcher length. Eyelet spacing varies between makers and 597 mm is typical, not universal. Better still, cut the stretcher last and fit it to the frame you actually built.

The stretcher looks slender for the load. It is not: at 572 mm between shoulders, 38 by 19 mm in ash, Euler buckling comes out around 7.9 kN assuming pinned ends and a modulus near 12 GPa. That is an order of magnitude check rather than a certification, but it is a comfortable order of magnitude.

Building it

Shape everything before the pins go in. Once a pin is driven the blade is captive, and every subsequent operation has a sharp 610 mm blade swinging off the workpiece.

Dress both arm blanks to 315 by 45 by 25 mm. Mark which face is inner on each, remembering they are handed.
Rip the blade slot down the inner face of each arm, 1.5 mm wide and 35 mm deep, running the full length. A bandsaw or a thin-plate rip saw both work. Test that the blade slides in freely before going further.
Chisel the stretcher pocket in the inner face, 20 mm along the arm and 10 mm deep, centred 189 mm up from the toe, leaving 3 mm of wood on each cheek.
Round the arm tops and cut a shallow notch on each outer edge, about 15 mm down from the top, to stop the cord riding off.
Shape the lower ends into handles. Chamfer everything. Sand now, because you will not get clean access later.
Drill the 4 mm pin holes 20 mm up from each toe, square through both cheeks.
Drop the blade eyelets into the slots, line them up with the holes, and drive the pins. Peen or epoxy the ends flush.
Assemble the frame and cut the stretcher to the length that gives you a light interference fit in both pockets.
Fit the cord as a loop of four strands between the arm tops, above the notches, and slip the toggle through it.
Oil the wood. Boiled linseed or a hardwax oil, several thin coats.

Tensioning and packing

Wind the toggle four to six turns and stop when a flick of the blade gives a clear note rather than a dull slap. Rest the toggle end against the stretcher so it cannot unwind.

Slacken it when you finish. Cord left wound overnight creeps, and wood left under load takes a set, so a saw stored tensioned is a saw that will not tension properly next time.

To pack: unwind fully, lift the stretcher out of its pockets, swing both arms down onto the blade, and lash the stretcher and toggle alongside with the cord. The bundle comes out 637 mm long and about 45 by 50 mm in section, which lashes to the outside of a pack and will not go inside one. That is the honest cost of a 610 mm blade, and it is the same for every folding design.

What it will not do

The throat is 146 mm. Roll a bigger log and cut from two sides and you will manage 290 mm, but slowly and with a wandering kerf.

Seven millimetres of teeth stay exposed at the middle of the folded bundle where the two arms meet. It is not enough to cut a pack, but it is enough to find a thumb. A scrap of leather over the join solves it.

And replacing the blade means punching out a pin, which is a workshop job rather than a field one. That is the deliberate trade behind never losing a fastener in the dark. Carry a spare cord, because that is the part that actually fails, and leave the spare blade at home.

SoC Intermediate 02: Cache coherency protocols

2026-08-06T00:00:00+01:00

Series: Intermediate SoC Design | Article 2 of 10

Two counters that will not scale

Here is a loop that counts events. It runs in about 2 seconds.

struct {
    long hits;
} stats[2];

// thread 0 runs: for (...) stats[0].hits++;
// thread 1 runs: for (...) stats[1].hits++;

You split it across two threads, one counter each. The threads share no variables. There is no lock, no atomic, no memory barrier, and no bug that any code review would catch. Each thread touches its own element and nothing else.

It now takes 6 seconds. Adding a core made the program three times slower.

Nothing in that code explains the result. The explanation lives one layer down, in the hardware that keeps caches agreeing with each other. This article covers that machinery: what it guarantees, how it works, and why it occasionally punishes correct-looking code. It targets engineers building or integrating multicore hardware, and the systems programmers who live with the result.

Coherence is not consistency

Two terms sound interchangeable and are not. Getting them confused makes every later discussion harder.

Coherence concerns one address at a time. If one core writes address X, every other core eventually sees that write to X, and nobody keeps using a stale copy. Cache controllers and the interconnect implement it.

Memory consistency concerns ordering between different addresses. It defines what software can assume about the order of loads and stores to X and Y. Barriers and acquire and release semantics live here. The instruction set architecture defines the model, and cores, store buffers, and the coherency fabric enforce it together.

A useful split: coherence is hardware keeping a promise about one location. Consistency is the contract the hardware offers software about many locations. This article is about coherence.

The single-writer rule

Every coherent system rests on one invariant. Learn this and most of the protocol becomes predictable.

For any cache line:

  Many caches may hold clean, readable copies.
  Only one cache may hold a dirty, writable copy.

Readers are cheap and can be plentiful. Writers are exclusive. When a core wants to write a line that other caches hold, it must first take ownership and remove every other copy.

That removal step is the source of most coherency traffic, most coherency latency, and the performance mystery in the opening section.

The four states of a cache line

MESI is the classic state machine for a cache line, named for its four stable states. Each cache tracks a state per line, not per variable.

State	Meaning
Modified	This cache holds the only valid copy, and it differs from memory
Exclusive	This cache holds the only valid copy, and it matches memory
Shared	This cache holds a clean copy, and other caches might hold it too
Invalid	This cache line holds nothing usable

Exclusive is the state that repays study. A line arrives in Exclusive when a core reads it and no other cache holds it. The copy is clean, so no writeback is needed, but the core already has sole ownership. A later write moves it to Modified with no bus traffic at all.

Without Exclusive, every first write to a freshly read line would need an invalidate transaction that has nobody to invalidate. That is why the state exists, and why protocols that omit it perform worse on private data.

Real designs add transient states on top of these four. A line waiting for invalidate acknowledgements is neither Shared nor Modified, and the implementation needs somewhere to put it.

What happens on a read miss

A read miss is the simplest coherent transaction, and it introduces every component involved.

The snoop filter decides who hears the request. It knows which caches might hold the line, so it sends the snoop only to those, rather than to everyone.

If another cache holds the line in Modified, that cache owns the newest data and memory is stale. It either writes the line back and lets memory answer, or forwards the data directly to the requester. Direct forwarding, called cache to cache transfer, is faster and most modern fabrics do it.

Taking ownership before a write

A core cannot write a line it shares. It first issues a read-for-ownership, which fetches the data and invalidates every other copy in one transaction.

Read the last two rows together. The line state changes to Modified only after both acknowledgements arrive. Until then the requesting core holds a promise, not ownership.

That ordering is the single-writer rule expressed in silicon. A design that transitions early creates a window where two caches both believe they can write, and the resulting corruption appears only under precise timing.

The cost is visible in the diagram. Every write to a shared line pays for a round trip to every sharer before it can proceed.

Snooping: every cache hears everything

The direct way to keep caches agreeing is to let them all listen to the same coherence traffic.

Every cache observes every read, invalidate, and ownership request, and each one checks whether it holds the line. The model holds few surprises during bring-up, and latency is low because there is no lookup step before the broadcast.

It stops scaling for three reasons:

Snoop traffic grows with the product of core count and request rate
Every broadcast wakes caches that do not hold the line, which wastes power
One structure that every cache must observe becomes hard to close timing on

Snooping suits four cores. It does not suit thirty-two.

Directories: telling only the caches that care

A directory records which caches might hold each line. The fabric consults it and sends targeted snoops instead of broadcasting.

Directory entry for cache line A

  Tag:       A[PA tag]
  Owner:     Core3, when Modified
  Sharers:   Core0=1 Core1=0 Core2=1 Core3=0
  State:     Shared

A read from Core 1 now disturbs Core 0 and Core 2 only. Core 3 never sees the request, so its cache stays quiet and its power stays down.

The costs are real. The directory needs storage proportional to the memory it covers, which is why designs track only cached lines rather than all of memory. Race handling also becomes harder, because the directory itself is a shared structure that can be stale while a transaction is in flight.

Snoop filters and the asymmetry of being wrong

A snoop filter is a compact directory whose job is avoiding pointless snoops. It does not have to be precise, but it does have to be conservative in one specific direction.

Conservative snoop filter rule:

  "Not present"   -> the line is definitely not in that cache.
  "Maybe present" -> the fabric sends a snoop to check.

The two ways of being wrong are not equivalent, and the difference matters more than any other property of the structure.

A false positive says a cache might hold a line it does not hold. The fabric sends a snoop, the cache answers that it has nothing, and the system loses a little time and power. The result stays correct.

A false negative says a cache does not hold a line it actually holds. The fabric skips the snoop, a stale copy survives an invalidate, and two caches disagree about memory. The result is silent data corruption.

Treat a false negative as a correctness bug of the highest severity. It is not a performance tuning question.

The hardware does not share variables

Return to the two counters. The threads shared no variables, and that was true. It was also irrelevant.

Coherency does not track variables. It has no idea that stats[0].hits and stats[1].hits are different objects, because it never sees objects. It tracks cache lines, typically 64 bytes, and a line is the smallest thing it can own, share, or invalidate.

One 64-byte cache line

  offset:  +0            +8                        +63
           [stats[0]]    [stats[1]]    [ ... rest of line ... ]
            ^ thread 0    ^ thread 1

  Thread 0 writes -> takes the line Modified, invalidates thread 1
  Thread 1 writes -> takes the line Modified, invalidates thread 0
  Thread 0 writes -> takes the line Modified, invalidates thread 1

Both counters sit in one line. Every write by either thread must take exclusive ownership of that line, which means invalidating the other core's copy. The line ping-pongs between the two caches, and each write pays a full coherency round trip instead of hitting in L1.

This is false sharing. The name is precise: the threads share nothing at the level of the source code, and everything at the level the hardware operates on. No amount of reading the C source reveals it, because the C source does not mention the unit that matters.

It is a software performance bug with a hardware cause, and neither layer is wrong. The hardware is honouring the single-writer rule exactly as specified.

When accelerators join the domain

Direct memory access engines and accelerators read and write memory without executing any of the cache maintenance instructions a core would. Systems handle this in one of three ways.

Non-coherent: Software cleans caches before a transfer out and invalidates them after a transfer in. The hardware is cheap, and a single missed maintenance operation corrupts the transfer.
Input output coherent: The engine participates in the coherency fabric for selected transactions, so its reads snoop the caches. Software stops needing maintenance for those buffers.
Fully coherent: The accelerator holds coherent copies itself, through a protocol such as ACE or CHI, and behaves like another core in the domain.

Each step up the list gains programmability and costs fabric complexity and verification effort. Most bugs in this area come from the first option, where a missing cache maintenance operation produces stale data that appears only when timing shifts.

State the coherency domain boundaries explicitly in the specification. Every engineer integrating a block needs to know which side of the boundary it sits on.

Atomics need the same ownership

Locks, reference counters, and queue indices all need read-modify-write sequences that no other core can interleave with. Coherency supplies the mechanism.

Atomic increment

  1. The core acquires the line with exclusive intent.
  2. The fabric prevents another core taking ownership unobserved.
  3. The core writes the updated value.
  4. If another core did intervene, the operation fails and software retries.

Exclusive monitors, load-reserved and store-conditional pairs, and far atomics executed near memory are all built on this foundation. The coherence protocol provides ownership, and the instruction set defines what software sees.

Contended atomics are expensive for the same reason false sharing is expensive. Every attempt moves a line between caches.

Why coherency bugs hide

Coherency bugs need specific interleavings, so they survive a great deal of testing before appearing.

Two cores racing for ownership of one line
An eviction colliding with an inbound snoop
A dirty line forwarded while its writeback is still pending
A snoop filter entry replaced at the wrong moment
Barrier ordering combined with outstanding writes
A transfer reading memory that a cache still owns

None of these appear in a single-core test, and few appear in a directed multicore test that runs the same order every time. Verification therefore combines four approaches:

Protocol checkers that watch the invariants continuously
Randomised traffic to reach interleavings nobody predicted
Formal properties for local invariants such as single-writer
Directed tests for the race classes already known

Design checklist

Decide these before the first line of coherent RTL:

Define the coherency domain boundaries in the specification.
Classify every requester as coherent, input output coherent, or non-coherent.
Keep stable line state and transient transaction state separate in the RTL.
Assert the single-writer invariant continuously, not only in directed tests.
Treat any snoop filter false negative as a correctness failure.
Measure false sharing and lock contention as part of performance sign-off.
Verify cache maintenance against real transfer buffers, not synthetic ones.

Padding, and how to check

The fix for the opening example is one line. Give each counter its own cache line:

struct {
    long hits;
} __attribute__((aligned(64))) stats[2];

The program returns to 2 seconds, and the memory cost is 56 wasted bytes per counter. That trade is almost always worth taking for data written by different threads.

To find the problem rather than guess at it, use perf c2c. It reports cache line contention directly, and names both the offending line and the offsets within it:

perf c2c record ./your_program
perf c2c report

Worth running once on anything threaded that scales worse than it should. The counters that fight are rarely the ones anybody suspects.

Previous: Article I-01: AXI4 protocol deep dive Next: Article I-03: Pipeline design and hazards

SoC Intermediate 01: AXI4 protocol deep dive

2026-08-02T00:00:00+01:00

Series: Intermediate SoC Design | Article 1 of 10

Introduction

This article explains how the AXI4 protocol achieves high throughput, and why that same design makes AXI4 hard to debug. It is written for engineers who already know the five channels and now have to build, integrate, or debug a real interface.

AXI is the Advanced eXtensible Interface, part of the AMBA family from ARM. AXI4 connects the high-bandwidth blocks of a system on chip: processors, direct memory access engines, graphics processors, display controllers, memory controllers, and coherent interconnects. The introductory article on interconnects described AXI as five independent channels with a valid and ready handshake. This article goes further, into bursts, transaction identifiers, ordering, backpressure, quality of service, and protocol compliance.

AXI is not a bus. It is a distributed flow-control contract between managers, interconnects, subordinates, buffers, bridges, and clock converters. Every one of those components can break the contract independently.

Note: this article uses the current AMBA terms manager and subordinate. Older documents and much existing code use master and slave for the same roles. The signal names are identical in both.

The five channels revisited

AXI4 separates read traffic and write traffic into five independent channels. Each channel carries its own handshake and makes progress on its own schedule.

Channel	Name	Direction
`AW`	Write address	Manager to subordinate
`W`	Write data	Manager to subordinate
`B`	Write response	Subordinate to manager
`AR`	Read address	Manager to subordinate
`R`	Read data	Subordinate to manager

A transfer occurs only on a rising clock edge where VALID and READY are both high. That single rule governs every channel.

AXI decouples the address channels from the data channels deliberately. A manager can send several write addresses before the subordinate accepts all the write data. A subordinate can delay responses while it continues to accept new addresses. This decoupling is the source of AXI throughput.

The cost of decoupling is bookkeeping. A correct design tracks every outstanding transaction, because the protocol never promises that two channels stay aligned.

The valid and ready contract

The valid and ready handshake carries two discipline rules that hand-written interfaces break more often than any other part of the protocol.

The first rule constrains the source. A source must not wait for READY before it asserts VALID. If the source has a transfer available, it asserts VALID immediately. A design that waits for READY first can deadlock against a destination that waits for VALID.

The second rule constrains the payload. Once VALID is high, the payload must stay stable until the transfer completes. The destination is free to assert and deassert READY at any time, and that freedom is how backpressure travels back through the system.

If the payload changes while VALID is high and READY is low, the destination can capture corrupted information. The failure is intermittent, because it appears only when the destination applies backpressure at the moment the source changes its data.

Burst types and addressing

A burst moves several data beats from one address phase. AXI4 supports three burst types, selected by the AxBURST field.

Burst	Behaviour	Typical use
`FIXED`	The address stays constant for every beat	A first in, first out data port
`INCR`	The address increments by the beat size	A normal memory copy
`WRAP`	The address increments, then wraps at an aligned boundary	A cache line refill

Two fields encode the shape of the burst. AxLEN holds the beat count minus one, so the transfer carries AxLEN + 1 beats. AxSIZE holds the base 2 logarithm of the beat width, so each beat carries 2^AxSIZE bytes.

Example: 4-beat INCR burst

  ARADDR = 0x8000_1000
  ARLEN  = 3          -> 4 beats
  ARSIZE = 3          -> 8 bytes per beat
  ARBURST= INCR

  Beat addresses:
    0x8000_1000
    0x8000_1008
    0x8000_1010
    0x8000_1018

Wrapped bursts and cache line refills

A wrapped burst keeps every beat inside one naturally aligned region. Caches use this to fetch the word the processor stalled on first, then collect the rest of the line.

The wrap boundary is the total burst size, which is the beat count multiplied by the beat width. When the address reaches that boundary, it returns to the start of the aligned region rather than crossing into the next one.

The address RADDR is shown for illustration. AXI does not carry an address on the read data channel, because the manager already knows the address from the read address phase.

Anatomy of a write transaction

A write completes only when all three write-side channels finish their work. The subordinate accepts the address, accepts every data beat, and returns a response.

The address phase and the data phase are independent. The manager can present write data before, during, or after the address handshake completes.

Many broken subordinates assume that AW and W arrive together. The assumption survives a simple testbench, then fails against a real interconnect that reorders the two channels through separate buffers.

WLAST marks the final data beat. A subordinate that counts beats without checking WLAST cannot detect a manager that sends the wrong number.

Anatomy of a read transaction

A read uses fewer channels than a write. One address phase produces one or more read data beats, and the final beat carries RLAST.

The read response travels in the RRESP field of each beat rather than on a separate channel. A burst can therefore report an error on one beat and success on another.

Transaction identifiers and ordering

Transaction identifiers let a manager keep several requests in flight at once. The AWID and ARID fields tag requests, and the BID and RID fields tag the matching responses.

Two ordering rules follow from the identifiers:

Transactions that share an identifier must complete in the order the manager issued them.
Transactions with different identifiers can complete in any order, if the interconnect and the subordinate support it.

Out-of-order read completion

  Manager issues:
    ARID=4, address in DRAM, row miss, slow
    ARID=7, address in SRAM, fast

  Interconnect can return:
    RID=7 first
    RID=4 later

  For two requests that both use ARID=4:
    responses return in issue order

This rule is what lets a memory controller reorder requests around DRAM bank conflicts. DRAM is dynamic random access memory, and a row miss costs tens of nanoseconds that a reordered request can hide.

The identifier is not an address and not a priority. It is the manager's statement about which of its own requests can complete out of order. A manager that reuses one identifier for everything forbids all reordering, and loses the performance that reordering provides.

Tracking outstanding transactions

Every AXI4 component keeps state for the transactions it has started and not yet finished. The decoupled channels make this bookkeeping mandatory rather than optional.

A manager tracks its own outstanding requests. An interconnect tracks routing state so responses reach the right manager. A subordinate that accepts several requests tracks the responses it still owes.

Read outstanding table

  Slot  ID  Source manager  Target subordinate  Beats left  Status
  ----  --  --------------  ------------------  ----------  ---------
  0     3   CPU0            DDR                 8           waiting
  1     8   DMA             SRAM                1           returning
  2     4   GPU             DDR                 16          waiting

Five questions decide whether the bookkeeping is correct:

Depth: How many outstanding reads and writes each interface supports.
Scope: Whether the limits apply per manager, per subordinate, or globally.
Interleaving: Whether any component still expects write data interleaving.
Errors: How error responses reach the originating manager, and whether the counters still balance afterwards.
Reset: Whether a reset during an outstanding transaction leaves a counter or a route table entry stale.

The third answer is fixed by the standard, and it simplifies subordinate design. AXI3 permitted write data interleaving, so a subordinate could receive beats from two write bursts mixed together. AXI4 removed it.

Response codes

Every AXI4 transaction reports a result. The result travels in BRESP for writes and RRESP for reads.

Response	Meaning
`OKAY`	The access succeeded
`EXOKAY`	An exclusive access succeeded
`SLVERR`	The target received the request and failed it
`DECERR`	Address decode failed, usually an unmapped address

The interconnect generates DECERR, not the target peripheral. An unmapped address has no target peripheral to generate anything, so the decode logic answers on its behalf.

A system that returns nothing for an unmapped address hangs instead of reporting a fault. This is one of the most common integration defects, and a single read from an unmapped address detects it.

Quality of service signalling

The AxQOS field lets a manager mark the relative urgency of a transaction. Quality of service, abbreviated QoS, is a 4-bit value carried on both AXI4 address channels.

A display controller fetching pixels for the next scanline needs low latency, because late pixels tear the image. A background copy engine can wait. The AxQOS field is how the manager states the difference.

The field is advisory. It changes nothing unless the interconnect or the memory controller implements an arbitration policy that reads it.

QoS-aware arbitration

  High urgency:  display scanout read   AxQOS=0xF
  Medium:        CPU cache refill       AxQOS=0x8
  Low:           background DMA copy    AxQOS=0x2

  Arbiter decision considers:
    QoS class
    starvation counter
    target availability
    outstanding limit

A policy where the highest value always wins starves the lower classes. Starved traffic holds buffers, full buffers apply backpressure, and backpressure can deadlock the system that the priority scheme was meant to protect. Production arbiters combine priority with an aging counter or a guaranteed bandwidth share.

Choosing between AXI4 and AXI4-Lite

AXI4-Lite is a subset of AXI4 intended for control and status registers. It removes the features that a register bank never uses.

Every transfer is a single beat.
The burst fields are absent.
The transaction identifier fields are absent.
The resulting subordinate is smaller and far quicker to verify.

Use AXI4-Lite for register banks. Use full AXI4 for high-throughput data movement. Attaching a large register block to full AXI4 gains nothing and costs verification effort, unless system integration forces the choice.

How AXI fails in practice

AXI failures usually appear as a hang rather than an error. A stalled handshake produces no exception, no trap, and no log entry.

The common root causes are:

VALID deasserts before the destination asserts READY
The payload changes while the transfer is stalled
WLAST is missing, early, or late
A subordinate assumes AW and W arrive in the same cycle
An outstanding counter underflows or overflows
A response identifier does not match any outstanding request
An interconnect frees a route table entry before the final beat
An unmapped access returns nothing instead of DECERR
A clock domain bridge drops a beat under backpressure

The fastest way to diagnose any of these is to capture all five channels around the stall. Then ask one question: which channel shows VALID high with READY low, and which component owes the next move.

That question converts a system hang into a single accountable interface. The component holding READY low is either waiting for something legitimate or has lost track of its own state.

A protocol monitor for the write channel

A small monitor catches most write channel violations before they reach silicon. It watches the handshakes and flags any sequence the protocol forbids.

The three transitions into the error state cover the failures that cost the most debug time. A response without a request means the identifier tracking is broken somewhere upstream. Too many beats means a beat counter disagrees with AWLEN. A second response means two components both think they own the transaction.

Design checklist

Work through these decisions before the first line of interface code:

Define the maximum outstanding reads and writes for every manager.
Decide which managers use multiple transaction identifiers, and how many.
Size every buffer for worst-case backpressure, not for average throughput.
Add protocol assertions at every custom AXI boundary in the design.
Map the full address space so that unmapped accesses return DECERR.
Keep AXI4-Lite register blocks single-beat and strongly ordered.
Capture all five channels in the waveform setup used for hang debug.

Summary

AXI4 performance comes from decoupling: independent channels, burst transfers, backpressure, transaction identifiers, and out-of-order completion. Each of those mechanisms raises throughput, and each one demands discipline in return.

That discipline covers handshake stability, outstanding transaction tracking, response ordering, and error handling. Most AXI failures are not a misunderstanding of one signal. They come from assuming that two independent channels stay aligned when the protocol explicitly permits them to drift apart.

Next: Intermediate Article 02: Cache coherency protocols

An always-on tmux setup

2026-08-02T00:00:00+01:00

If you have not met it yet, tmux is a terminal multiplexer. It lets one terminal window hold many sessions, split into panes, and it keeps those sessions alive after you disconnect. I wrote up the day-to-day mechanics previously in the tmux Training Manual, which is the better starting point if you are learning the keybindings.

This post is about what came after that. Once tmux is part of your daily routine, a handful of small annoyances start to grate. You forget to start it and lose a terminal full of work. A reboot wipes out a carefully arranged set of windows and panes. Shift+Enter mysteriously stops working in Claude Code and Codex the moment you are inside tmux. Selecting text with the mouse stops putting anything on the clipboard. And you spend the first month looking up the same four keybindings over and over.

Each of those has a fix, and each fix is only a few lines of config. This post walks through all of them as they now sit in my dotfiles repository. Individually they are small. Together they turn tmux from something you remember to start into something that is simply always there.

The five changes are:

Change	Problem it solves
Shell-native autostart	Forgetting to run `tmux`, then losing work when the terminal closes
tmux-resurrect and tmux-continuum	Losing the window and pane layout across a restart
Extended key reporting	Shift+Enter being byte-identical to Enter inside tmux
Two-row status line	Not remembering keybindings, and losing the host label under a TUI
Mouse selection through a copy command	Selections not reaching the system clipboard, or arriving as escape-sequence garbage

Everything below lives in the tmux config and the shell profile. On a standard Linux or macOS setup those are ~/.tmux.conf (or ~/.config/tmux/tmux.conf) and ~/.bashrc or ~/.zshrc. If you are following along without my dotfiles, use the paths in the left column below and ignore the rest of this section.

Standard location	Tracked file in my dotfiles
`~/.tmux.conf` or `~/.config/tmux/tmux.conf`	`config/tmux/tmux.conf`
`~/.zprofile`	`config/shell/dot-zprofile`
`~/.bashrc`	`config/shell/dot-bashrc`

Two different mechanisms put those in place, and neither is a symlink. tmux respects XDG_CONFIG_HOME, and config/shell/dot-profile sets it to point straight at the repository:

export XDG_CONFIG_HOME=$HOME/dotfiles/config

So tmux reads ~/dotfiles/config/tmux/tmux.conf directly, with no linking step at all. The shell files are sourced rather than linked, which keeps machine-local settings out of the repository. ~/.zprofile on each machine starts with:

source "$HOME/dotfiles/config/shell/dot-zprofile"

The dot- prefix is a GNU Stow convention, used elsewhere in the repository for configs that genuinely are linked. The wider layout is covered in Managing Dotfiles with Stow and Git.

Autostart from the shell profile

The usual advice is to configure autostart in the terminal emulator. That ties the behaviour to one application, so it does not follow you over SSH, and it does not survive changing terminals. Doing it in the shell profile is portable across every terminal on every machine that gets the dotfiles.

This goes in ~/.zprofile, which in my case is config/shell/dot-zprofile:

# Start or attach to the shared tmux session for interactive terminals. TMUX is
# set inside tmux, which prevents new panes from creating nested sessions.
# Set NO_TMUX=1 to get a plain shell, e.g. ghostty -e "env NO_TMUX=1 zsh -l".
# Deliberately not exec: on detach the login shell survives instead of the
# terminal window closing.
if [[ -o interactive && -z "${TMUX:-}" && -t 1 && -z "${NO_TMUX:-}" ]] && (( $+commands[tmux] )); then
  tmux new-session -A -s main
fi

The Bash equivalent goes in ~/.bashrc, mine at config/shell/dot-bashrc. Same logic, portable syntax:

if [[ $- == *i* && -z "${TMUX:-}" && -t 1 && -z "${NO_TMUX:-}" ]] && command -v tmux >/dev/null 2>&1; then
  tmux new-session -A -s main
fi

Four guards matter here, and every one of them prevents a real failure mode.

-z "${TMUX:-}" is the important one. tmux sets TMUX inside every pane it owns. Without this test, each new pane runs the profile, which starts another tmux, which runs the profile again. That is an infinite nesting loop that locks up the terminal.

-t 1 checks that standard output is a terminal. Non-interactive uses that still source the profile, such as ssh host command or an editor spawning a login shell to read the environment, must not be hijacked into tmux.

command -v tmux keeps the profile portable to machines where tmux is not installed. A missing binary should not break shell startup.

-z "${NO_TMUX:-}" is the escape hatch. More on it below.

new-session -A -s main is the whole trick: attach to the session named main if it exists, create it if it does not. One flag, no has-session test and conditional branch.

The Zsh version goes in ~/.zprofile, not ~/.zshrc. zprofile is sourced once for a login shell. zshrc is sourced for every interactive shell, which would be more places than necessary to run this.

Leaving a way out

Two details in that block are deliberate, and both exist so you can still get to a shell that is not inside tmux.

No exec. The common advice is exec tmux new-session -A -s main, which replaces the login shell with the tmux client rather than leaving a parent shell doing nothing. It also removes the thing you detach to: with exec there is no process behind tmux, so prefix + d has nothing to return to and the terminal window closes. Detach and quit become the same action. Running tmux without exec keeps the login shell alive underneath, so detaching lands you back at a prompt. The cost is one idle shell per terminal.

NO_TMUX. Set it and the profile skips the autostart entirely:

ghostty -e "env NO_TMUX=1 zsh -l"

Both matter for the same reason: when tmux is the thing that is broken, every terminal you open runs straight back into it. Without a shell to detach to and a way to start without tmux at all, there is nowhere to stand while you inspect or kill the server.

Login shells inside tmux

New tmux panes start as login Bash shells, showing up as -bash in the process list. Login Bash reads ~/.bash_profile and does not read ~/.bashrc at all, so if the autostart block and everything else lives in ~/.bashrc, panes come up with none of it. The shim in ~/.bash_profile:

if [[ -r "$HOME/.bashrc" ]]; then
  source "$HOME/.bashrc"
fi

On machines where tmux arrives through environment modules rather than being on PATH at login, the module has to be loaded before the command -v test can succeed. My Bash version does that inside the guard:

if [[ $- == *i* && -z "${TMUX:-}" && -t 1 && -z "${NO_TMUX:-}" ]]; then
  _dotfiles_module_load util gnu/tmux >/dev/null 2>&1
  if command -v tmux >/dev/null 2>&1; then
    tmux new-session -A -s main
  fi
fi

_dotfiles_module_load is a small wrapper of mine that is a no-op when no module system is present, so the same file still works on machines without one. The output redirection matters: module tools are chatty, and anything they print during shell startup ends up in scp and rsync sessions, which breaks them.

Session persistence with resurrect and continuum

tmux-resurrect saves and restores the tmux environment. tmux-continuum drives resurrect automatically on a timer and restores on server start. They are designed to be used together.

# Session persistence across restarts.
# resurrect: prefix + Ctrl-s saves, prefix + Ctrl-r restores. Saves the window
# and pane layout, window names, and each pane's working directory.
# continuum: autosaves every 15 min and auto-restores when the server starts.
set -g @resurrect-capture-pane-contents 'on'
set -g @resurrect-dir "$HOME/.tmux/resurrect"
set -g @continuum-restore 'on'
set -g @continuum-save-interval '15'

What actually gets restored: the window and pane layout, window names, the active window and pane, and each pane's working directory. @resurrect-capture-pane-contents 'on' adds the visible scrollback of each pane, so a restored session looks like the one you left rather than a grid of empty prompts.

Running programs are not restored by default, and that is the right default. Resurrect has an opt-in process whitelist, but blindly re-launching whatever was running is a good way to have a reboot re-run something you did not want re-run.

Saved state lands in ~/.tmux/resurrect as timestamped text files, with a last symlink to the most recent:

tmux_resurrect_20260802T094413.txt
tmux_resurrect_20260802T103006.txt
pane_contents.tar.gz
last -> tmux_resurrect_20260802T103006.txt

They are plain text. If a restore goes wrong you can read the file and see exactly what it thought your layout was.

The manual keys still work alongside the autosave: prefix + Ctrl-s saves, prefix + Ctrl-r restores. Worth using the manual save before a deliberate reboot rather than waiting up to 15 minutes for the timer.

The ordering gotcha

This one cost real debugging time:

# Keep these at the very bottom. continuum appends itself to status-right, so
# it must run after the status-right set above or autosave is silently lost.
run-shell ~/.tmux/plugins/tmux-resurrect/resurrect.tmux
run-shell ~/.tmux/plugins/tmux-continuum/continuum.tmux

Continuum implements its timer by appending a hook to status-right. tmux evaluates the status line on an interval, so continuum piggybacks on that as its clock. If your own set -g status-right runs after continuum loads, it overwrites continuum's addition and the autosave stops.

Nothing warns you. Manual saves keep working, so the setup looks healthy right up until a crash and the newest saved state is hours old. Keep the run-shell lines at the very bottom of the file, after every status-right assignment.

These are loaded with direct run-shell calls rather than through the tmux plugin manager, so the plugins need cloning by hand:

git clone https://github.com/tmux-plugins/tmux-resurrect ~/.tmux/plugins/tmux-resurrect
git clone https://github.com/tmux-plugins/tmux-continuum ~/.tmux/plugins/tmux-continuum

Letting Shift+Enter through

In a plain terminal, Enter and Shift+Enter send the same byte: carriage return, 0x0d. The Shift modifier has nowhere to go in the traditional encoding. This is not a tmux problem to begin with, but tmux makes it one, because tmux must choose whether to pass the modern encoding through.

The modern encoding is CSI u, sometimes called the Kitty keyboard protocol or extended key reporting. It gives modifiers a place to live in the escape sequence, so Shift+Enter becomes distinguishable from Enter.

This matters because terminal AI tools bind Shift+Enter to "insert a newline without submitting". Claude Code and Codex both do. Inside tmux without the setting below, that binding is dead: every Shift+Enter submits the prompt mid-thought.

# Pass extended key reporting (CSI u) through to applications. Without this,
# Shift+Enter is byte-identical to Enter inside tmux, so TUIs like Codex and
# Claude Code cannot bind it to "insert newline".
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Two lines, two different jobs:

set -s extended-keys on is a server option that tells tmux to forward extended keys to the application when the application asks for them. The alternative value always sends them unconditionally, which is more aggressive and can confuse applications that never opted in. on is the safer setting.

set -as terminal-features 'xterm*:extkeys' tells tmux that the outer terminal is capable of the protocol. Without this, tmux has no reason to believe the sequences will survive on the way out, so it will not emit them. Note the -a flag: it appends to the existing feature list rather than replacing it.

Both halves are required. The chain is terminal, then tmux, then application, and any link that does not speak the protocol breaks it. Your outer terminal also needs to support extended keys. Ghostty, Kitty, WezTerm and recent iTerm2 do. Extended keys need tmux 3.2 or newer.

The status line and a hint row

Next is the status line. Two things were wrong with the default. The host label from the Starship prompt disappears the moment a full-screen TUI takes over the pane, so on a multi-machine SSH setup you lose track of where you are. And tmux keybindings are hard to remember while you are still learning them.

set -g status 2
set -g status-style 'bg=#1e1e2e,fg=#a6adc8'
set -g status-left-length 30
set -g status-left '#[fg=#89b4fa,bold] #S #[default]'
set -g status-right-length 80
set -g status-right '#[fg=#89b4fa,bold]󰂋 #{?#{E:DOTFILES_HOST},#{E:DOTFILES_HOST},#h}#[fg=#6c7086]  •  #[fg=#f9e2af]%H:%M '
set -g window-status-separator ''
set -g window-status-format '#[fg=#6c7086] #I:#W '
set -g window-status-current-format '#[fg=#cba6f7,bold] #I:#W '
set -g 'status-format[1]' '#[align=centre,fg=#7f849c]Prefix: Ctrl-b • c: create • ,: rename • n/p: next/previous • d: detach'

set -g status 2 is the interesting one. Most people know status on and status off, but the option also takes a row count up to 5. With two rows, status-format[0] is the normal status line and status-format[1] is a second row you can fill with anything. Here it holds a centred cheat sheet of the keybindings you need while learning tmux. It is a comment in the config that you actually read, and deleting it later is a one-line change.

Keep the hint row short. Long labels and wide separators wrap on a narrow pane, and a row that wraps stops being readable at a glance. Window numbers are already on the row above, so the row does not need to explain 0-9 either.

The host label uses a conditional format:

#{?#{E:DOTFILES_HOST},#{E:DOTFILES_HOST},#h}

#{?condition,true,false} is the tmux ternary. #{E:VAR} expands an environment variable from the session environment. So this reads: if DOTFILES_HOST is set, show it, otherwise fall back to #h, tmux's own short hostname. The fallback means the config still works on a machine that has tmux but not the rest of the dotfiles.

Where DOTFILES_HOST comes from

The variable is set in the shell, not in tmux, which is the point: one definition feeds both the Starship prompt and the tmux status line, so they can never disagree about which machine you are on.

In config/shell/dot-zprompt:

_dotfiles_set_host_label() {
  local fqdn="" host="" rest="" label=""

  fqdn="$(hostname -f 2>/dev/null || hostname 2>/dev/null || printf '%s' "${HOST:-}")"
  host="${fqdn%%.*}"
  label="$host"

  if [[ "$host" == login* && "$fqdn" == *.*.* ]]; then
    rest="${fqdn#*.}"
    label="${rest%%.*}"
  fi

  typeset -g DOTFILES_HOST="$label"
}
_dotfiles_set_host_label
unset -f _dotfiles_set_host_label
export DOTFILES_HOST

The Bash version in dot-bashrc is the same logic with export in place of typeset -g.

Normally this is just the short hostname: take the fully qualified name and cut everything from the first dot. The interesting part is the login* branch. Compute clusters tend to name their entry points login1, login2, login3, which tells you nothing about which cluster you have landed on. When the short name starts with login and the FQDN has at least two dots, the label becomes the next domain component instead. So login2.helios.example.com displays as helios, which is the piece of information you actually wanted.

The function runs once per shell and is then unset, so it costs nothing on redraw. export is what matters for tmux: only exported variables reach the tmux session environment where #{E:DOTFILES_HOST} can read them.

Starship picks up the same variable through its env_var module in config/starship/starship.toml:

[env_var.DOTFILES_HOST]
# Shared with tmux; cluster login hosts are normalized by dot-zprompt.
variable = "DOTFILES_HOST"
format = "[󰂋 ]($style)[$env_value]($style) "
style = "#89b4fa bold"

The same Nerd Font glyph and the same blue appear in the tmux status-right above, so the label looks identical whether it is being drawn by the prompt or by tmux. When a TUI takes over the pane and the prompt scrolls away, the status line keeps showing it.

Keeping the label fresh

Session environment variables are captured when the session is created, so a long-lived session can hold a stale value. This line fixes that:

# Refresh the label when attaching from a new client. The explicit array index
# makes repeated config reloads idempotent.
set -g 'update-environment[99]' DOTFILES_HOST

update-environment is a list of variables tmux refreshes from the attaching client. Setting an explicit index rather than using -a to append means reloading the config repeatedly overwrites slot 99 each time instead of piling up duplicate entries.

The rest is cosmetic and matches the Catppuccin Mocha palette used elsewhere in the setup:

set -g pane-border-style 'fg=#313244'
set -g pane-active-border-style 'fg=#89b4fa'
set -g message-style 'bg=#313244,fg=#cdd6f4'
set -g mode-style 'bg=#cba6f7,fg=#1e1e2e,bold'

Mouse scroll and the clipboard

The last piece sits at the top of the config: the block that decides what the mouse does.

# Let the wheel scroll tmux pane history. Use Shift+drag for native terminal
# selection. On RHEL/X11, pipe tmux selections to xclip instead of emitting OSC52
# clipboard escapes, which can show up as garbage text in some terminal paths.
set -g mouse on
set -g set-clipboard off
set -s copy-command 'xclip -selection clipboard -in'
bind M set -g mouse
bind -T copy-mode-vi MouseDragEnd1Pane send -X copy-pipe-no-clear -C

# vim keys for copy mode
setw -g mode-keys vi

mouse on is not only about clicking to select panes. Without it, wheel and trackpad scroll is translated into arrow keys, and a TUI reading arrow keys as prompt history navigation will scroll your prompt history instead of the pane scrollback. That is a confusing bug until you know the cause.

Turning it on, though, means tmux now owns the mouse, and that is where the copy and paste trouble starts. Three separate problems, three lines.

The selection vanishes the moment you release the button. tmux's default MouseDragEnd1Pane binding is copy-selection-and-cancel, which copies and then immediately exits copy mode and clears the highlight. You get no visual confirmation that anything was selected at all. Rebinding to a -no-clear variant keeps the highlight up after the drag:

bind -T copy-mode-vi MouseDragEnd1Pane send -X copy-pipe-no-clear -C

The copy does not reach the system clipboard. By default tmux hands the selection to the terminal using OSC 52, an escape sequence asking the terminal emulator to set the clipboard on tmux's behalf. When it works it is excellent, because it survives SSH. When something in the chain does not interpret it, the bytes land in the terminal as visible garbage and the clipboard stays empty. That is what happens on RHEL over X11.

Stop tmux emitting the escape sequence and give it a real command to pipe through instead:

set -g set-clipboard off
set -s copy-command 'xclip -selection clipboard -in'

copy-command is what the -C flag on copy-pipe-no-clear invokes, so the binding, the pipe target and the disabled OSC 52 all work as one unit. On X11 that means xclip. Wayland wants wl-copy --type text/plain, and macOS wants pbcopy, so this line is the one to change per machine.

Sometimes you want the terminal's own selection, not tmux's. Rectangular selection across panes, or a drag that a remote tmux should not intercept. Most terminals give that to you with Shift held down while dragging, which bypasses mouse reporting entirely. For everything else there is a toggle:

bind M set -g mouse

prefix + M flips mouse mode off and on. Off, the terminal gets the mouse back completely and normal drag-to-select works as if tmux were not there.

Gotchas worth repeating

The five things most likely to bite:

Nested sessions. The TMUX guard in the shell profile is not optional. Without it, opening a pane starts a new tmux inside the pane, forever.
No exec, and an escape hatch. With exec, detaching closes the terminal instead of returning to a shell, so there is no way to reach a prompt outside tmux when tmux itself is what needs debugging. The bare call plus the NO_TMUX guard are what keep that possible.
Continuum's ordering. run-shell for continuum must come after every status-right assignment, or the autosave silently stops while manual saves keep working.
Extended keys need both lines. extended-keys on alone does nothing if tmux does not also believe the outer terminal supports the protocol.
Login Bash in panes. tmux panes are login shells, so on Bash the autostart block needs ~/.bash_profile to source ~/.bashrc or none of it runs.

Reload after editing with prefix + r, which is bound in the config:

bind r source-file $XDG_CONFIG_HOME/tmux/tmux.conf

Note that reloading does not undo settings, it only applies new ones. When debugging status line problems, kill the tmux server with tmux kill-server and start fresh rather than trusting a reload.

Tested on tmux 3.7b. The full configuration is config/tmux/tmux.conf in the dotfiles repository.

Zsh startup analysis and modern setup

2026-07-31T00:00:00+01:00

This post documents the current Zsh setup and the measurements that shaped it. It covers startup performance, completion behavior, plugins, and prompt design. The intended audience is anyone maintaining or reproducing this dotfiles setup.

The complete configuration is available in the dotfiles repository. The current setup uses Oh My Zsh, the Git plugin, command autosuggestions, syntax highlighting, and Spaceship Prompt.

Original startup performance

The baseline identifies which startup costs existed before the framework and plugins. The investigation started with a small Zsh configuration. A configured interactive login shell started in 103.60 ms at the median. The macOS global configuration required 27.88 ms, leaving 75.72 ms for user configuration.

The final benchmark used 5 warm-up launches and 60 measured launches. A Python harness used time.perf_counter() around /bin/zsh subprocesses. The harness redirected standard output and standard error to /dev/null.

Scenario	Median	Mean	95th percentile	Minimum	Maximum
Configured interactive login	103.60 ms	101.75 ms	113.95 ms	83.62 ms	116.52 ms
macOS global files only	27.88 ms	26.29 ms	29.97 ms	19.10 ms	31.34 ms
Configured login with `zprof`	111.38 ms	107.03 ms	116.10 ms	82.70 ms	120.02 ms

The original zprof result identified completion initialization as the main shell-function cost. A warm completion cache required 20.78 ms. Rebuilding the cache required 246.60 ms.

Function	Warm total	Rebuild total	Rebuild self time
`compinit`	20.78 ms	246.60 ms	95.20 ms
`compdef`	Not present	84.18 ms	84.18 ms
`compdump`	Not present	52.39 ms	52.39 ms
`compaudit`	10.97 ms	14.83 ms	14.83 ms

Top-level external commands do not appear in zprof. Separate measurements attributed about 27.35 ms to brew shellenv. Two uname processes added about 12.34 ms.

Changes added to the setup

This chapter summarizes each feature added after the baseline measurement. The setup combines a framework with focused interactive features. The tracked profile guards optional dependencies, so missing Homebrew packages do not prevent shell startup.

Feature	Purpose	Installation source
Oh My Zsh	Framework, completion integration, and plugin loading	Manual Git clone
Git plugin	Git aliases and helper functions	Bundled with Oh My Zsh
Spaceship Prompt	Structured asynchronous prompt	Homebrew
Zsh Autosuggestions	History-based command suggestions	Homebrew
Zsh Syntax Highlighting	Command-line token and validity highlighting	Homebrew
Victor Mono Nerd Font	Prompt and status glyphs	Homebrew cask
Tracked `dot-zprofile`	Portable shared configuration	Dotfiles repository

The portable setup lives in the tracked Zsh profile. Machine-local configuration remains in ~/.zprofile. That local file sources the tracked profile before applying machine-specific settings.

The shared profile loads Oh My Zsh first. It then loads the existing interactive configuration. This order preserves existing aliases because later alias definitions override Oh My Zsh aliases with the same name.

How completion changed

This chapter compares the original completion path with the framework-managed path. Zsh provides the completion engine through compinit. Oh My Zsh does not replace that engine. It configures, validates, and caches the same system.

Previous completion path

The previous configuration called compinit directly. An optimization ran a full scan once each day, then used compinit -C for later shells.

autoload -Uz compinit
if [[ "$(date +'%j')" != \
      "$(stat -f '%Sm' -t '%j' ~/.zcompdump 2>/dev/null)" ]]; then
  compinit
else
  compinit -C
fi

This approach used ~/.zcompdump and reduced repeated security audits. It saved about 12 ms inside compinit, but date and stat reduced the measured shell saving to about 4 ms.

Current Oh My Zsh completion path

Oh My Zsh prepares fpath before running compinit. It adds framework, custom, and enabled plugin completion directories. This ordering lets plugin completion definitions participate in the initial cache.

Oh My Zsh uses a host-specific and Zsh-version-specific dump file:

~/.zcompdump-${SHORT_HOST}-${ZSH_VERSION}

The framework records its Git revision and the complete fpath inside that dump. It removes the dump when either value changes. It also compiles the dump to Zsh Word Code with zrecompile, which reduces parsing work on later starts.

Completion security behavior also changes. Oh My Zsh uses compinit -i and reports insecure completion directories through its compfix support. The current profile leaves this security behavior enabled.

Behavior	Previous configuration	Current Oh My Zsh configuration
Completion engine	Native `compinit`	Native `compinit` managed by Oh My Zsh
Dump name	`~/.zcompdump`	Host and Zsh-version-specific dump
Refresh policy	Full scan once daily	Refresh when framework revision or `fpath` changes
Plugin completions	Existing `fpath` only	Plugin directories added before `compinit`
Security check	Full daily, skipped with `-C` afterward	Checked through `compinit` and `compfix`
Compiled dump	Not configured	Recompiled to Zsh Word Code

The daily optimization remains as a fallback in dot-zshrc. It runs only when Oh My Zsh is unavailable. This guard prevents 2 compinit calls in one shell.

Pressing Tab twice lists the matches with their descriptions:

Oh My Zsh also configures completion menus, caching, process completion, and Bash completion compatibility. The local matcher style still provides case-insensitive completion after the framework loads.

What the Git plugin provides

This chapter separates Git command shortcuts from the Git information shown in the prompt. The Oh My Zsh Git plugin provides a large alias library and several Git-aware functions. It does not install Git or change repository data during shell startup.

The aliases cover common branch, commit, fetch, log, merge, pull, push, rebase, stash, and worktree operations. The following examples remain available when they do not conflict with local aliases.

Alias or function	Behavior
`gaa`	Run `git add --all`
`gcb`	Create and check out a branch
`glog`	Show a one-line decorated graph
`grt`	Change to the repository root
`gbda`	Delete merged branches
`git_current_branch`	Return the current branch name
`git_main_branch`	Detect the repository's primary branch name
`gwip` and `gunwip`	Create and remove temporary work-in-progress commits

Local aliases load after the plugin and retain their established behavior. For example, Oh My Zsh defines gp as git push. This setup keeps the existing gp='git pull' alias. It also preserves the custom gl graph format and other long-standing shortcuts.

The plugin and Spaceship Git section serve different purposes. The plugin provides commands and functions. Spaceship displays repository state in the prompt.

Autosuggestions and syntax highlighting

This chapter covers the 2 plugins that provide feedback while a command is being entered. Zsh Autosuggestions displays faint command suggestions while text is entered. It uses command history by default, which makes repeated commands available without a history search. The suggested remainder appears in a dimmed colour and is accepted with the right arrow key:

Zsh Syntax Highlighting colors command-line tokens before execution. Its main highlighter distinguishes valid commands, invalid commands, paths, options, strings, and shell syntax. This feedback can reveal a typing error before the command runs.

The recording below shows all 3 features in one session. An autosuggestion is accepted, Tab lists the completion matches, an unknown command turns red, and the corrected command turns green:

Syntax highlighting loads last because it wraps Zsh Line Editor widgets. A later plugin could replace those wrappers and prevent highlighting from tracking edits correctly.

Both plugins come from the tracked Brewfile. The profile checks each installed path before sourcing it. A machine without Homebrew therefore starts Zsh without these optional features.

How Spaceship changes the prompt

This chapter compares the original one-line theme with the configured Spaceship layout. Spaceship Prompt replaces the Oh My Zsh robbyrussell theme. The configuration disables ZSH_THEME and sources the Homebrew Spaceship package after Oh My Zsh loads.

The prompt uses this order:

SPACESHIP_PROMPT_ASYNC=true
SPACESHIP_PROMPT_ADD_NEWLINE=true
SPACESHIP_CHAR_SYMBOL="⚡"
SPACESHIP_PROMPT_ORDER=(
  user
  dir
  git
  line_sep
  char
)

Each entry controls one prompt section:

user shows the username for Secure Shell sessions, root, or user changes.
dir shows the current directory and truncates long paths.
git shows the branch and dirty, ahead, behind, or diverged state.
line_sep places the command entry point on a separate line.
char shows a lightning symbol that changes color with command status.

Spaceship also provides a time section that prints a timestamp. This setup omits it deliberately. The section is absent from SPACESHIP_PROMPT_ORDER, so Spaceship never loads it. Its SPACESHIP_TIME_SHOW variable also defaults to false, which means listing time in the order alone would render nothing.

The Git section tracks the working tree. Stashing every change clears the dirty indicators, and restoring them brings the indicators back:

Asynchronous rendering prevents Git inspection from blocking command entry. Spaceship renders the prompt immediately, then updates asynchronous sections when their data becomes available. The Git section uses this behavior by default.

The robbyrussell theme uses one line. It shows a status arrow, the final directory component, the Git branch, and a dirty marker. Spaceship uses 2 lines, a path of up to 3 levels, and detailed Git synchronization state.

The lightning symbol changes from green to red after a failed command. The Brewfile includes Victor Mono Nerd Font for branch and status glyphs.

Startup cost after adding features

The added features increase startup time, but the result remains below 200 ms at the median. Each row comes from a separate 60-launch benchmark batch, so the differences are directional rather than a controlled component breakdown.

Configuration	Median startup	Change from previous row
Original configuration	103.60 ms	Baseline
Daily completion optimization	99.25 ms	-4.35 ms
Oh My Zsh and 3 plugins with `robbyrussell`	187.07 ms	+87.82 ms
Oh My Zsh, 3 plugins, and Spaceship	178.53 ms	-8.54 ms

That Spaceship run measured 178.69 ms mean and 186.35 ms at the 95th percentile. The minimum was 167.73 ms, and the maximum was 189.13 ms.

The Spaceship row was measured while the time section was still enabled. The section was removed afterwards, and the benchmark has not been repeated. The current prompt should therefore cost slightly less than this row reports.

Oh My Zsh accounts for most of the increase. Its measured functions include framework sourcing, completion validation, plugin loading, and cache compilation. Spaceship renders expensive Git information asynchronously, which protects interactive responsiveness after the shell becomes available.

Reproduce the setup

This chapter identifies every tracked file required to reproduce the shared setup. The repository contains the portable configuration and installation manifest:

Dotfiles repository
Installation README
Shared Zsh profile
Interactive Zsh configuration
Homebrew Brewfile
Install the Homebrew packages from the repository root.

sh brew bundle install --file="$HOME/dotfiles/config/brew/Brewfile"

Clone Oh My Zsh because it has no Homebrew formula.

sh git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh.git "$HOME/.oh-my-zsh"

Create a local ~/.zprofile that sources the shared profile.

zsh source "$HOME/dotfiles/config/shell/dot-zprofile"

Machine-local secrets and paths remain outside the repository. Application Programming Interface (API) keys live in ~/.config/codex/env, which is readable only by the owning user. The shared profile sources that file only when it exists.

Verification and remaining improvements

This chapter provides repeatable checks and identifies remaining optimization work. Measure wall-clock startup with a login shell:

time /bin/zsh -lic 'exit 0'

Enable function-level profiling with the existing debug switch:

time ZSH_DEBUGRC=1 /bin/zsh -lic 'exit 0'

Future work can avoid repeated brew shellenv calls in inherited environments. It can also replace external uname calls with Zsh parameters. De-duplicating fpath remains useful if nested shells create repeated Homebrew completion paths.

Knife Grinds and Their Main Uses

2026-07-23T00:00:00+01:00

Knife blades differ in more than shape and steel. Grind, the cross-section profile ground into edge, drives how blade cuts, how easy sharpen, and how well edge holds up to different tasks.

Flat Grind

Blade tapers straight from spine to edge, no secondary bevel curve. Simple, strong, easy sharpen.

Main uses: general-purpose knives, kitchen knives, everyday carry.

Scandi (Scandinavian) Grind

Single bevel runs from partway down blade straight to edge, no secondary edge bevel. Very easy sharpen on flat stone, good control for wood work.

Main uses: bushcraft, whittling, carving, favoured for scouting/camp knives.

Hollow Grind

Concave curve ground into blade sides, edge thin and sharp. Sharpens to very fine edge, but weaker and edge rolls easier under hard use.

Main uses: straight razors, fillet knives, precision cutting tasks.

Convex Grind

Edge curves outward, opposite of hollow. Strong edge, good for chopping, holds up well to impact.

Main uses: axes, machetes, heavy-use survival knives.

Chisel Grind

Only one side ground, other stays flat. Very sharp, but asymmetric cut pulls to one side.

Main uses: some Japanese kitchen knives, specialist woodworking tools.

Choosing a Grind

For scouting and cub activities, scandi grind usually best starting point. Easy sharpen in field, good control for carving, safe predictable cut.

SoC Article 11: HW/SW co-design, bridging software and silicon

2026-07-06T00:00:00+01:00

Series: Introduction to SoC Design | Article 11 of 11

Introduction

Throughout this series, we have focused primarily on the hardware side of SoC design: the processors, memory, buses, and physical implementation. But a SoC without software is inert. The firmware that boots it, the operating system that manages its resources, the drivers that talk to its peripherals, and the applications that use it are just as important as the hardware itself.

HW/SW Co-Design is the discipline of designing hardware and software together, recognising that they are inseparable aspects of the same system. This article brings together the software side of the SoC story, covering the boot process, device drivers, the OS interface, and the co-design trade-offs that shape every product decision.

The HW/SW interface: where they meet

Hardware and software communicate through a small number of well-defined mechanisms:

Memory-Mapped Registers

The primary interface between software and hardware on a SoC is memory-mapped I/O: every hardware block exposes a set of control and status registers (CSRs) at fixed addresses in the physical address space.

Typical UART Register Map (base address: 0x4000_0000):

  Offset  Register  Access  Description
  --------------------------------------------------------
  0x00    THR       WO      Transmit Holding Register
  0x00    RBR       RO      Receive Buffer Register
  0x04    IER       RW      Interrupt Enable Register
  0x08    IIR       RO      Interrupt Identification
  0x0C    LCR       RW      Line Control (baud, parity)
  0x10    MCR       RW      Modem Control
  0x14    LSR       RO      Line Status (TX ready, RX data)
  0x18    MSR       RO      Modem Status
  0x1C    SCR       RW      Scratch Register

To send a byte over UART, firmware: 1. Read LSR to check that the TX FIFO is not full. 2. Write the byte to THR. 3. Hardware takes over and drives the UART TX pin.

This read-modify-write register interface is the universal pattern for SoC firmware.

The Software Stack

The software on a SoC is organised in layers, each depending on the layer below it:

The Boot Process

Bringing a SoC from cold power-up to a running operating system is a multi-stage process, each stage loading and executing the next:

DDR initialisation: a hardware-SW co-design example

One of the most hardware-specific firmware tasks is DDR initialisation. Modern LPDDR5 DRAM requires a training sequence: a complex set of calibration steps that establishes the optimal timing relationships between the SoC and the DRAM:

The FSBL writes a sequence of magic values to the DDR controller and DRAM mode registers, then reads test patterns back to calibrate write and read timing. Only after this sequence completes successfully can the rest of the software stack use DRAM.

Device Drivers

A device driver is the software module responsible for managing a specific hardware peripheral. Drivers abstract the hardware details, presenting a clean, standardised interface to higher software layers.

In Linux, a character device driver for a simple UART might look like:

/* Simplified UART platform driver skeleton */
#include <linux/platform_device.h>
#include <linux/serial_core.h>
#include <linux/io.h>

#define UART_THR  0x00
#define UART_LSR  0x14
#define LSR_THRE  BIT(5)   /* TX holding register empty */

static void uart_write_char(struct uart_port *port, unsigned int c)
{
    /* Wait until TX FIFO has space */
    while (!(readl(port->membase + UART_LSR) & LSR_THRE))
        cpu_relax();
    /* Write character to hardware register */
    writel(c, port->membase + UART_THR);
}

static int uart_probe(struct platform_device *pdev)
{
    struct resource *res;
    void __iomem *base;

    /* Get MMIO base address from device tree */
    res  = platform_get_resource(pdev, IORESOURCE_MEM, 0);
    base = devm_ioremap_resource(&pdev->dev, res);

    /* Register with Linux serial framework */
    /* ... uart_add_one_port() ... */
    return 0;
}

The Device Tree (DTS) is the mechanism by which Linux discovers what hardware is present without hard-coding it in the kernel:

/* Device Tree fragment for a UART */
uart0: serial@40000000 {
    compatible = "myvendor,uart-v1";
    reg       = <0x40000000 0x100>;   /* MMIO base, size */
    interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
    clocks    = <&clk_periph>;
    clock-names = "uartclk";
    status    = "okay";
};

When Linux boots, it reads the Device Tree, matches compatible strings to registered drivers, and calls the driver's probe() function for each matching node.

HW/SW Partitioning

The most important architectural decision in co-design is which functions to implement in hardware and which in software. This partitioning determines performance, power, flexibility, and development cost.

Real trade-off examples

AES Encryption: - Software (Cortex-A, 1 core): ~300 MB/s, ~200 mW - Hardware accelerator: ~10 GB/s, ~5 mW - Decision: hardware, because encryption happens on every packet, latency is critical, and the algorithm is stable

JSON Parsing: - Software (optimised C): ~500 MB/s - Hardware: would require custom finite-state machine; format evolves - Decision: software, because flexibility matters more than raw speed

Video Decode (H.265): - Software (4 CPU cores): ~720p@30fps, ~2 W - Hardware codec: ~8K@120fps, ~50 mW - Decision: always hardware in a mobile SoC

Co-Simulation and Co-Verification

HW/SW co-design requires testing both halves together before silicon exists. There are several approaches:

Virtual platform and virtual prototype: a software model of the SoC, typically written in SystemC/Transaction-Level Modelling (TLM), that runs on a host workstation. The firmware binary is compiled for the target ISA and runs on an instruction-set simulator (ISS). This allows firmware development to begin before RTL is complete.

FPGA prototyping: the RTL is synthesised onto one or more large FPGAs, running at 5-50 MHz. Real firmware and software run on the FPGA, providing a cycle-accurate model that can run full Linux. FPGA prototyping boards (Xilinx VCU118, Intel Stratix 10) are essential tools for pre-silicon software development.

Hardware emulation: as discussed in Article 10, emulators compile the RTL into custom FPGAs that run at MHz speeds, supporting real-time testing with actual peripherals.

The RTOS vs Linux choice

For the CPU running on a SoC, a fundamental software decision is operating system choice:

OS Type	Examples	Best For
Bare Metal	None	Ultra-simple, few ms startup, max performance
RTOS	FreeRTOS, Zephyr, ThreadX	Hard real-time, < 1ms interrupt latency
Linux	Linux, Android	Feature-rich, large driver ecosystem, networking
Hypervisor	Xen, KVM	Running multiple OSes simultaneously (automotive, industrial)

Many SoCs run both: a Cortex-M managing power and safety-critical functions runs an RTOS (real-time operating system) or bare metal, while a Cortex-A cluster running Linux or Android handles the application layer. This heterogeneous multi-OS configuration is increasingly common.

IP Management and Reuse

As noted in Article 02, IP reuse is central to managing SoC complexity. Co-design extends this to include software deliverables alongside hardware IP:

A well-packaged IP block delivers: - RTL source (encrypted or open) - Testbench and UVM verification environment - Device driver (Linux kernel module or RTOS driver) - Register description file (IP-XACT, SystemRDL) for automatic header/driver generation - Reference firmware (bare-metal startup, peripheral init code) - Documentation (Technical Reference Manual, integration guide)

Increasingly, EDA tools automatically generate C header files and Linux device tree bindings from the hardware register descriptions, reducing the human effort and error risk in the software-hardware interface.

Looking back: the complete picture

We have now traversed the entire SoC landscape:

Article 01: From room to silicon: integration, motivation, anatomy
Article 02: What is a System on Chip: anatomy, motivation, IP cores
Article 03: The SoC design stack: abstraction layers, IP cores, Y-chart
Article 04: Processor cores: CPU, DSP, GPU, NPU, big.LITTLE
Article 05: Memory architecture: cache hierarchy, DRAM, MMU
Article 06: Interconnects and bus protocols: AXI, AHB, APB, crossbar, NoC
Article 07: Clocking, reset, and power domains: PLL, CDC, DVFS, power gating
Article 08: Peripherals and I/O: UART, SPI, I2C, USB, DMA, IRQ
Article 09: HDL and RTL design: SystemVerilog, FSM, simulation
Article 10: The SoC design flow: spec to RTL to synthesis to P&R to tape-out

Where to Go Next

With the introductory series complete, you are ready to explore the intermediate topics. These build directly on the foundations laid here:

Intermediate series (10 articles)

AXI4 Protocol Deep Dive: burst types, out-of-order, QoS, debug
Cache Coherency Protocols: MESI in hardware, multi-core coherency
Pipeline Design and Hazards: forwarding, stalling, branch prediction basics
RTL Synthesis and Timing Closure: SDC, STA, ECO flows
Clock Domain Crossing Techniques: synchronisers, async FIFOs, CDC analysis tools
SoC Verification with UVM: agents, sequences, scoreboards, coverage
DMA Controller Architecture: descriptor chains, scatter-gather, QoS
Interrupt Controllers in Depth: GIC, NVIC, priority, virtualization extensions
Memory-Mapped I/O and Linux Device Drivers: writing real kernel drivers
SoC Power Management Techniques: DVFS governors, CPUIdle, power domains in Linux

Advanced series (10 articles)

Out-of-Order Execution Architecture: Tomasulo, ROB, reservation stations
Network-on-Chip Design: topology, routing, flow control, virtual channels
DRAM Subsystem Timing: LPDDR5 protocol, refresh, power states, thermal throttle
Physical Design: Floorplanning and P&R: CTS, ECO, IR drop, antenna effects
Hardware Security in SoC: TrustZone, secure boot, side-channel attacks
AI/ML Accelerator Architecture: systolic arrays, dataflow, memory bandwidth analysis
Formal Verification Methods: model checking, SVA, property specification languages
Post-Silicon Debug and Validation: JTAG, CoreSight ETM, scan chains
FPGA-Based SoC Design: Zynq-7000, Cyclone V HPS, PetaLinux
Heterogeneous SoC Partitioning: HW/SW co-exploration, automated co-design tools

Summary

HW/SW co-design recognises that hardware and software are two facets of the same system: neither is meaningful without the other. The boot process takes a SoC from silicon power-on to a running application through several carefully orchestrated stages. Device drivers form the critical interface between the operating system and hardware registers. The partitioning of function between hardware and software is the most impactful architectural decision. Virtual platforms, FPGA prototypes, and emulators allow software development to proceed before silicon is available. Mastering co-design is what separates SoC systems engineers from specialists who know only one half of the system.

Previous: Article 10: The SoC design flow

12-Bar Blues on Guitar with 6th and 5th String Barre Chords

2026-07-02T00:00:00+01:00

The previous post played the 12-bar blues with open guitar chords, which works beautifully in E or A and not at all in Bb. Barre chords remove that limit: two movable shapes and the whole progression follows your fretting hand up and down the guitar neck, one shape per string, any key.

Recap: where 1, 4, and 5 sit on the neck

The Diatonic Chords post built the full root recipe on the 6th and 5th strings:

The blues only needs the 1, 4, and 5 corners of that map, and they form a tight little triangle:

1 -- root on the 6th string.
4 -- same fret, 5th string. No counting; the tuning interval between the strings is a perfect 4th.
5 -- two frets up from the 4, still on the 5th string.

Here is just that blues subset on its own, in G:

Find one note and the other two chords are already under your hand. That triangle is the same at fret 3, fret 8, or anywhere else, which is what makes the barre version of the progression movable.

The two shapes

Each corner of the triangle gets a barre shape named after the open chord it is built from:

E shape (6th string root) for the 1 -- the open E chord fingered with 2-3-4, with the index finger barring where the nut used to be.
A shape (5th string root) for the 4 and the 5 -- the open A chord with an index barre, moved to each root.

Worked example: blues in G

Same G at fret 3 as the recap diagram. The 1 is the E shape at fret 3; the 4 sits directly below it at the same fret in the A shape; the 5 is that A shape slid up two frets:

The 4 is the 1's pattern dropped one string set at the same frets, and the 5 is the 4 slid two frets up -- the triangle from the recap, now wearing full chords. Play any 12-bar grid from the previous post with these three and notice how little the hand travels: the 1-to-4 change is a string hop at the same fret, and the 4-to-5 change is a two-fret slide of the same shape. The shuffle feel carries over unchanged.

Any key, same triangle

Slide the whole triangle so the E shape lands on the key's root note on the 6th string:

Key	1 (E shape, 6th string)	4 (A shape, 5th string)	5 (A shape, 5th string)
F	fret 1	fret 1	fret 3
G	fret 3	fret 3	fret 5
A	fret 5	fret 5	fret 7
Bb	fret 6	fret 6	fret 8
C	fret 8	fret 8	fret 10
D	fret 10	fret 10	fret 12

This is the answer to the horn-player problem from the last post: when someone calls "blues in Bb", nothing about the progression changes -- the triangle just parks at fret 6.

The 7th variations

Want the bluesier dominant 7th sound from the previous post? Each barre shape turns into a movable 7th chord by lifting one finger: the freed string drops back onto the index-finger barre, and that barre note is the b7. In the E shape, lift the finger on the D string; in the A shape, lift the finger on the G string:

Same triangle, same frets, one finger fewer per chord. Swap them in wherever the grid wants more grit -- the 5 chord first, then all three -- and the triangle still plays the form anywhere on the neck.

12-Bar Blues on Irish Bouzouki in G, A, and E

2026-07-02T00:00:00+01:00

Same series, different instrument again: the 12-bar blues (the form, guitar barre chords) converted to Irish bouzouki. Shapes below are for GDAD tuning, the most common Irish setup; each pair of strings is a unison course, so the diagrams show four strings for four courses. Keys covered: G, A, and E.

The form, unchanged

Twelve bars, three chords, turnaround in bar 12:

1  1  1  1
4  4  1  1
5  4  1  1

Quick change, long 5, and the shuffle feel all carry over from the first post untouched. Only the shapes change -- and on bouzouki, how much of each chord you actually play is a stylistic choice, covered at the end.

Key of G

1-4-5 in G is G, C, D. GDAD is practically built for the key of G -- the 1 chord is two open courses and one finger:

The C voicing keeps the open G course ringing underneath (technically C/G); on a droning instrument that is a feature, not a compromise.

Key of A

1-4-5 in A is A, D, E:

Key of E

1-4-5 in E is E, A, B. The B is the A shape from the key of A slid two frets up -- the same "same shape, two frets" move the guitar barre post uses for every 4-to-5 change:

Drop the 3rd (the fret-6 note) and the barre alone gives 4-4-x-4 style bare fifths -- a B5 that drives just as well. Which leads to the real bouzouki move:

Drones, dyads, and the 7th

Irish bouzouki accompaniment leans modal: two- and three-note shapes, no 3rd, open courses droning. That vocabulary works on a blues too -- the 3rd of each chord is optional when the melody or the singer is supplying the blue notes, and 1-4-5 played as bare fifths with a shuffle drives just as hard as the full chords. Drop the labelled 3 from any diagram above and what remains is the modal version of the same chord.

For the bluesier colour the series keeps returning to, the 7th is one lifted or added finger away here too. The best of them falls out of the tuning for free in the key of E: lower the top course of the E shape to open and the open D course is the b7 --

Play the 12-bar grid in E with that shape as the 1 and the form starts sounding like it grew up on this instrument after all.

The 12-Bar Blues: One Progression, Every Key

2026-07-02T00:00:00+01:00

Ask a blues band what they are about to play and the answer is usually three numbers: "blues in E, quick change". That is the whole chart. The Nashville Number System makes this possible because the 12-bar blues is not really a set of chords, it is a set of relationships: the 1, the 4, and the 5 of whatever key you are in, arranged in a pattern that has not changed in a hundred years.

The form

Twelve bars, three chords, one line per four bars:

1  1  1  1
4  4  1  1
5  4  1  1

Read it as a story in three acts. The first line sits at home on the 1. The second line steps away to the 4 and comes back. The third line builds tension on the 5, softens through the 4, and lands home again, ready to repeat.

Bar 12 is the turnaround. The last bar's job is to point back to bar 1. The simplest version replaces the final 1 with a 5; fancier versions walk up chromatically into the 5 chord. Either way, the listener hears "here we go again" rather than "the end".

Common variations

The grid above is the base form, but bands rarely play it completely straight. All the common variants keep the same twelve-bar skeleton and change one or two cells.

Quick change. Bar 2 becomes a 4, which stops the four opening bars of 1 from feeling static. This is the most-called variant; note the turnaround 5 written into bar 12:

1  4  1  1
4  4  1  1
5  4  1  5

Long 5. Bar 10 stays on the 5 instead of dropping to the 4, holding the tension a bar longer. Common in early rock and roll:

1  1  1  1
4  4  1  1
5  5  1  1

Minor blues. Same skeleton with the 1 and 4 as minor chords, and a b6 chord adding drama in bar 9 before the 5. In A minor that third line is F, E7, Am, E7:

1- 1- 1- 1-
4- 4- 1- 1-
b6 5  1- 5

Jazz blues. Jazz players keep the twelve bars but recolour the third line, most noticeably replacing the 5-4 of bars 9-10 with a 2-5 cadence. Worth recognising when someone counts in "Straight No Chaser", but it is its own rabbit hole.

Whatever the variant, someone can call it in a few words ("quick change", "hold the five") because everyone shares the same numbered map.

Chords by key

Because the form is written in numbers, playing it in a new key is a lookup, not a transposition exercise:

Key	1	4	5
E	E	A	B
A	A	D	E
G	G	C	D
D	D	G	A
C	C	F	G

E and A are the guitar keys: the chords sit in open position and the boogie patterns below fall under the fingers. Horn players will call for Bb or F; that is what barre chords and a capo are for.

Plain major chords work fine. For more of a blues feel, swap any or all of them for dominant 7ths (E7, A7, B7): the added b7 gives the chords that unresolved, gritty blues colour. The 5 chord is the most common place to start.

The three chords in E

Open E and A, plus B7, the friendliest way to play the 5 in this key (the full B barre chord is no fun in the middle of a shuffle):

The shuffle feel

The chord grid says nothing about rhythm, and rhythm is half the style. Blues is rarely played with even eighth notes: it is played with a shuffle (or swing) feel, where each beat is split long-short instead of half-and-half. Count it as triplets, "1-and-a, 2-and-a", and play only the first and last note of each triplet: the offbeat lands two-thirds of the way through the beat, not halfway.

The animation below shows one bar of eighth notes, each dot lighting up when it is played. The straight row pulses evenly; the shuffle row plays the same notes, but the offbeats arrive late:

Straight

Shuffle

Both rows play eight notes per bar, but the shuffle "&" notes wait until two-thirds of the beat has gone by, and each downbeat note rings twice as long as the offbeat that follows it. That lopsided lope is the blues feel; once you can hear it, you will notice straight eighths sound stiff in this style. Strum the twelve bars above with this feel and it already sounds like blues.

Why bother with the numbers?

Because the number chart is the only version you have to memorise. Learn the grid at the top of this post once and you now know the 12-bar blues in E, A, G, D, C, and every other key: the table converts numbers to chord names. When a jam leader calls "blues in A, quick change, watch for the stops", every word of that maps onto something in this post except the stops, and those are just bars where the band hits beat one and lets the singer have the rest.

Next in the series: variations on the open A shape, plus the D and E shapes, to grow the chord vocabulary used in this progression.

12-Bar Blues on Ukulele in G, A, and E

2026-07-02T00:00:00+01:00

The 12-bar blues charts in this series (the form, guitar barre chords) are written in numbers, and numbers do not care what instrument you are holding. This post converts the same 1-4-5 chart to ukulele shapes in standard GCEA tuning, for the three keys a uke player is most likely to get called into: G, A, and E.

The form, unchanged

Twelve bars, three chords, turnaround in bar 12 -- exactly as on guitar:

1  1  1  1
4  4  1  1
5  4  1  1

All the variations from the first post (quick change, long 5, the shuffle feel) apply as written. Only the shapes below change.

Key of G

1-4-5 in G is G, C, D -- the friendliest blues key on a ukulele, all three chords in the first three frets:

Key of A

1-4-5 in A is A, D, E:

E major is famously the ukulele's least favourite chord. The 4442 voicing above is the most reliable of the standard options; if it fights you, use E7 instead -- easier, and the blues actively prefers the 7th sound anyway:

Key of E

1-4-5 in E is E, A, B. Guitarists love E blues for the open strings; on ukulele it is the workout key, with both the E and B shapes up the neck:

Here too the 7ths are the escape hatch: E7 (1202, above) for the 1 and B7 for the 5 turn the workout key into an easy one. B7 comes in two common voicings -- take your pick:

The open form is the easier grab -- fingers walk down 4-3-2 and the open A course rings as the b7. The barre form takes a moment more to set, but it damps cleanly for a choppy shuffle and it moves: slide it up a fret and it is C7, up three and it is D7. Let the hands decide.

Playing it

Strum with the same shuffle feel as on guitar -- the lopsided long-short eighths from the first post. The ukulele's short sustain suits a damped, percussive shuffle: a light palm or finger mute after each strum stands in for the guitar's palm muting. And since every shape above is fretted with a finger or two, swapping any chord for its dominant 7th costs nothing -- lean on them freely.

Diatonic Chords

2026-07-01T00:00:00+01:00

Major chords are made up of the 1st, 3rd, and 5th note of its diatonic major scale. For example, an A chord is the 1-3-5 of the A major scale (A, C#, E), and an E chord is the 1-3-5 of the E major scale (E, G#, B). Different notes, same recipe. From here we build the full set of diatonic chords in a key.

Every chord comes from a scale

The scale behind these chords is the diatonic major scale -- the same scale also called the natural major, the major scale, or the Ionian mode. All four names point at the same seven notes; "diatonic major" is the name used going forward in this post.

Every diatonic major scale is built from the same fixed pattern of steps: W-W-H-W-W-W-H. W is a whole step (two frets, a tone), H is a half step (one fret, a semitone). Starting on any root note and following that pattern produces a major scale in that key -- it's the pattern that makes a scale "major", not the starting note.

Applying W-W-H-W-W-W-H starting on A:

That gives the A diatonic major scale: A B C# D E F# G#. Pull out the 1st, 3rd, and 5th notes -- A, C#, E -- and that triad is the A major chord.

Do the same with the E diatonic major scale, applying W-W-H-W-W-W-H starting on E:

That gives E F# G# A B C# D#. The 1st, 3rd, and 5th are E, G#, B -- the E major chord.

Same shape of recipe, different scale, different notes. Every major chord in every key is built this way: 1-3-5 of its own major scale. That's the whole idea behind a "major chord" -- it isn't a fixed set of notes, it's a fixed relationship to whichever scale it's rooted on.

Diatonic chords: stacking the major scale

The A and E examples above both stacked a 1-3-5 triad starting on the scale's own root. Stack that same triad shape starting on every degree of the scale, not just the first, and you get the full set of chords that naturally belong to a key -- the diatonic chords.

"1-3-5" is really shorthand for a rule: take a note, skip one, take the next, skip one, take the next -- staying entirely inside the notes of the scale. Do that starting on the 1st degree of C major (C D E F G A B) and the third note is E, giving C-E-G. Do the same skip-one pattern starting on the 2nd degree instead and the third note is F, giving D-F-A. Same recipe, different starting point, but the scale only supplies the notes it has -- there's no F# to reach for, so the gap between D and F comes out smaller than the gap between C and E.

That gap is what decides major versus minor. The distance from root to third is measured in semitones (frets): a major third is 4 semitones, a minor third is 3 semitones. Breaking each triad down into its two internal gaps (root-to-3rd, and 3rd-to-5th) shows exactly where that difference comes from, and shows something that doesn't change alongside it -- the outer gap, root straight to fifth:

Degree	Triad notes	Root-to-3rd	3rd-to-5th	Root-to-5th	Quality
1	C-E-G	4 semitones	3 semitones	7 semitones	Major
2	D-F-A	3 semitones	4 semitones	7 semitones	Minor
3	E-G-B	3 semitones	4 semitones	7 semitones	Minor
4	F-A-C	4 semitones	3 semitones	7 semitones	Major
5	G-B-D	4 semitones	3 semitones	7 semitones	Major
6	A-C-E	3 semitones	4 semitones	7 semitones	Minor
7	B-D-F	3 semitones	3 semitones	6 semitones	Diminished

Every row's root-to-3rd and 3rd-to-5th gaps add up to the same root-to-5th distance: 7 semitones, a perfect fifth, on every degree except the 7th. Whether the chord reads as major or minor comes entirely from which gap -- 4 then 3, or 3 then 4 -- comes first; the outer boundary of the triad never moves. The 7th degree is the one exception: both inner gaps are 3 semitones, so they add up short, to 6 rather than 7 -- a flattened, or diminished, fifth. Stacking two minor thirds back to back is what makes that triad diminished rather than simply minor.

This major/minor/diminished pattern -- Maj min min Maj Maj min dim, reading up the scale -- is fixed for every major key; only the notes change, the same way the A and E chords earlier shared a recipe but not notes.

Each of these seven chords also gets a roman numeral, counting up from the root chord: I ii iii IV V vi vii°. Uppercase marks a major chord, lowercase marks minor, and the degree symbol marks diminished -- the numerals encode the same major/minor/diminished pattern from the table above, just as a label rather than a semitone count. Session musicians use a plain-digit version of the same idea -- 1 2m 3m 4 5 6m 7dim -- called the Nashville Number System, covered in full further down; it's the same major/minor/diminished labelling here, just written as numbers instead of numerals so the same chart works in any key.

I, IV, and V are the three major chords in the key, which is why they combine so freely in progressions: any two of them share strong voice-leading and neither introduces a note outside the key.

Chord table for every key

Key	I	ii	iii	IV	V	vi	vii°
C	C	Dm	Em	F	G	Am	Bdim
C#/Db	Db	Ebm	Fm	Gb	Ab	Bbm	Cdim
D	D	Em	F#m	G	A	Bm	C#dim
D#/Eb	Eb	Fm	Gm	Ab	Bb	Cm	Ddim
E	E	F#m	G#m	A	B	C#m	D#dim
F	F	Gm	Am	Bb	C	Dm	Edim
F#/Gb	F#	G#m	A#m	B	C#	D#m	E#dim
G	G	Am	Bm	C	D	Em	F#dim
G#/Ab	Ab	Bbm	Cm	Db	Eb	Fm	Gdim
A	A	Bm	C#m	D	E	F#m	G#dim
A#/Bb	Bb	Cm	Dm	Eb	F	Gm	Adim
B	B	C#m	D#m	E	F#	G#m	A#dim

Find your key, read across. The I, IV, V columns are the three chords used most often in simple progressions.

Where I, IV, and V sit on the neck

Every diatonic root note in a key can be found from a single starting point using the 6th and 5th strings, without needing a separate shape or position memorised for each chord:

Start on the root -- that's I.
Move up 2 frets on the same string -- that's ii.
Move up 2 more frets on the same string -- that's iii.
Drop down one string, back to the starting fret -- that's IV. Adjacent strings (except G to B) are tuned 5 semitones apart -- a perfect 4th, the same distance as root to IV -- so no fret-counting is needed here at all.
Move up 2 frets on this new string -- that's V.
Move up 2 more frets -- that's vi.

Worked example, root G on the 6th string at fret 3:

G-A-B on the 6th string are I-ii-iii; dropping to the 5th string at the same fret 3 lands on C, the IV; C-D-E on the 5th string are IV-V-vi. Every "+2 frets" step is a whole step, matching the W in the W-W-H-W-W-W-H formula -- the only reason the recipe can skip past the H (iii to IV) without adjusting the fret count is the one-string drop, which supplies that gap for free via the tuning itself. Once a root is located by name on either string, this same shape of movement finds every other diatonic root in that key.

The Nashville Number System

Session musicians don't read "G, C, D" off a chart -- they read "1, 4, 5". Numbers replace chord names so the same chart works in any key: the guitarist reads it in E, the piano player reads it in Bb, nobody transposes anything, they just play the same numbers off their own instrument's shapes.

Conventions:

Uppercase or plain digit = major (I, IV, V or 1, 4, 5)
Lowercase or digit + m = minor (ii, iii, vi, or 2m, 3m, 6m)
° or dim = diminished (vii° becomes 7dim)
Slash chords show the bass note after a slash: 5/7 means a V chord with the 7th in the bass

Because the numbers are relative to the key, not absolute notes, a chart written once works for a band where every player is in a different key on their own instrument. This is the foundation for the next post in this series, which applies it directly to a full 12-bar blues progression.

Using ctags with Verilog and SystemVerilog

2026-06-19T00:00:00+01:00

Navigating a large Verilog or SystemVerilog codebase without tag-based Go to Definition is painful. This tutorial shows how to generate and use ctags for projects that use a design.vc file list — common in simulators like Verilator, VCS, and xrun.

Prerequisites

Universal Ctags (preferred over Exuberant Ctags — it has better SystemVerilog support)

Install on macOS:

brew install universal-ctags

On Linux:

sudo apt install universal-ctags   # Debian/Ubuntu
brew install universal-ctags       # Homebrew on Linux

Check your version:

ctags --version

1. Understand the `design.vc` format

A typical design.vc looks like this:

+incdir+./rtl
+incdir+./ip
./rtl/top.sv
./rtl/subsystem.sv
./ip/uart/uart.sv

Lines beginning with +incdir+ define include paths.
Remaining lines are source files (usually .v / .sv).
Relative paths are normally relative to the design.vc location.

2. Create a file list for ctags

ctags expects plain file paths. Strip the +incdir+ lines and any comments with awk:

awk '
  /^\+incdir\+/ {next}
  /^\s*#/ {next}
  /^\s*$/ {next}
  {print}
' design.vc > design.files

If you want the include paths separately for other tools:

grep '^\+incdir\+' design.vc | sed 's/^\+incdir\+//' > design.incdirs

Note: ctags does not use include paths for preprocessing; it parses files directly. Make sure all files that define symbols are listed in design.files.

3. Generate the tags file

ctags -R --languages=SystemVerilog --fields=+nKz -f tags -L design.files

Flags:

-L design.files — read source paths from the file list
--languages=SystemVerilog — enables SV/Verilog parsing
--fields=+nKz — includes line number, kind, and scope in each tag
-f tags — write to tags

4. Configure your editor

Vim / Neovim

Tell Vim to search upward from the current file for a tags file:

set tags=./tags;

Navigate with:

Ctrl-] — jump to definition
Ctrl-t — jump back

Emacs

(setq tags-file-name "~/path/to/project/tags")

Navigate with M-. (jump) and M-* (back).

VS Code — ctags-companion extension

Install the Ctags Companion extension (gediminaszlatkus.ctags-companion).

Default settings that work well for SystemVerilog:

{
    "ctags-companion.command": "ctags -R --fields=+nKz",
    "ctags-companion.readtagsGoToDefinitionCommand": "readtags -en"
}

Once a tags file exists at the project root, Go to Definition (F12 / Cmd-click / right-click) will use it.

To make Go to Definition open in the current editor group rather than a split pane, add to your user settings:

{
    "workbench.editor.enablePreviewFromCodeNavigation": false,
    "workbench.editor.revealIfOpen": false
}

If split-pane behaviour persists, check that your keybinding is mapped to editor.action.revealDefinition and not editor.action.revealDefinitionAside.

5. Keep tags up to date

Regenerate after RTL changes:

ctags -R --languages=SystemVerilog --fields=+nKz -f tags -L design.files

Add a make target for convenience:

.PHONY: tags
tags:
    awk '/^\+incdir\+/ {next} /^\s*#/ {next} /^\s*$$/ {next} {print}' design.vc > design.files
    ctags -R --languages=SystemVerilog --fields=+nKz -f tags -L design.files

6. Auto-build on save

Vim: rebuild on BufWritePost

function! s:FindRoot() abort
  let l:vc = findfile('design.vc', expand('%:p:h').';')
  if !empty(l:vc)
    return fnamemodify(l:vc, ':h')
  endif
  let l:root = finddir('.git', expand('%:p:h').';')
  return empty(l:root) ? '' : fnamemodify(l:root, ':h')
endfunction

function! s:BuildTags() abort
  let l:root = s:FindRoot()
  if empty(l:root) | return | endif
  if filereadable(l:root . '/design.vc')
    execute 'silent !cd ' . shellescape(l:root) .
          \ ' && awk ''/^\+incdir\+/ {next} /^\s*#/ {next} /^\s*$/ {next} {print}'' design.vc > design.files' .
          \ ' && ctags -R --languages=SystemVerilog --fields=+nKz -f tags -L design.files'
  else
    execute 'silent !cd ' . shellescape(l:root) .
          \ ' && ctags -R --languages=SystemVerilog --fields=+nKz -f tags .'
  endif
endfunction

augroup verilog_tags
  autocmd!
  autocmd BufWritePost *.v,*.sv call s:BuildTags()
augroup END

Neovim: async job (non-blocking)

vim.opt.tags = { "./tags;" }

local function find_root()
  local vc = vim.fn.findfile("design.vc", vim.fn.expand("%:p:h") .. ";")
  if vc ~= "" then return vim.fn.fnamemodify(vc, ":h") end
  local git = vim.fn.finddir(".git", vim.fn.expand("%:p:h") .. ";")
  return git ~= "" and vim.fn.fnamemodify(git, ":h") or ""
end

local function build_tags()
  local root = find_root()
  if root == "" then return end
  local cmd
  if vim.fn.filereadable(root .. "/design.vc") == 1 then
    cmd = "cd " .. vim.fn.shellescape(root) ..
      " && awk '/^\\+incdir\\+/ {next} /^\\s*#/ {next} /^\\s*$/ {next} {print}' design.vc > design.files" ..
      " && ctags -R --languages=SystemVerilog --fields=+nKz -f tags -L design.files"
  else
    cmd = "cd " .. vim.fn.shellescape(root) ..
      " && ctags -R --languages=SystemVerilog --fields=+nKz -f tags ."
  end
  vim.fn.jobstart(cmd, { detach = true })
end

vim.api.nvim_create_autocmd("BufWritePost", {
  pattern = { "*.v", "*.sv" },
  callback = build_tags,
})

gutentags plugin

If you prefer a plugin, gutentags can manage tag generation automatically. Use a small wrapper script so it handles design.vc:

#!/usr/bin/env bash
# ctags_from_design_vc.sh — place in PATH
set -euo pipefail

if [[ -f design.vc ]]; then
  awk '/^\+incdir\+/ {next} /^\s*#/ {next} /^\s*$/ {next} {print}' design.vc > design.files
  exec ctags -R --languages=SystemVerilog --fields=+nKz -f tags -L design.files
else
  exec ctags -R --languages=SystemVerilog --fields=+nKz -f tags .
fi

Then configure gutentags:

let g:gutentags_project_root = ['design.vc', '.git']
let g:gutentags_ctags_executable = 'ctags_from_design_vc.sh'

7. Troubleshooting

No tags generated — check that design.files has correct, accessible paths. Switch to absolute paths if relative ones fail.

Missing modules or interfaces — confirm your ctags supports SystemVerilog. Universal Ctags handles it; Exuberant Ctags does not.

Include paths not respected — ctags does not preprocess; it parses files directly. Ensure every file that defines a symbol is in design.files.

Summary

Strip +incdir+ from design.vc to create design.files.
Run ctags -R --languages=SystemVerilog --fields=+nKz -f tags -L design.files.
Configure your editor (Vim / Neovim / Emacs / VS Code) to use the tags file.
Automate regeneration on save so tags stay current.

A Second MCP Server: Managing a Pelican Blog from Claude

2026-06-03T00:00:00+01:00

Once you've set up one self-hosted MCP server, adding a second is mostly a case of reusing the infrastructure you've already built. This post covers adding a blog-management MCP to the same host as an existing MCP server — so the OAuth service, nginx, and firewall rules carry over, and the new server is a matter of writing the tools and adding a new location block to nginx.

The target: a blog-mcp server that lets Claude pull the repo, create and edit posts, add images, run make github to build and publish, and push the source — all without leaving the conversation.

What's Already in Place

This guide assumes the first MCP server setup from the previous post is done:

Node.js 22 and supergateway installed on the host
nginx with OAuth bearer token validation (the map {} block and auth variable defined at the http {} level)
The OAuth server handling the OAuth authorization code + PKCE flow
Firewall rules blocking direct access to internal supergateway ports

If you're starting fresh, read that post first. The OAuth setup is the hard part; it isn't repeated here.

The Blog Repo Structure

The blog is a Pelican static site. Two branches:

main — Pelican source: content/, Makefile, pelicanconf.py, requirements.txt
gh-pages — built HTML output; GitHub Pages serves this branch

make github does three things: runs Pelican to build, runs ghp-import to stage the output onto gh-pages, then pushes that branch to GitHub.

When you clone a GitHub Pages repo, git defaults to the gh-pages branch (it's the GitHub default). The source is on main:

git clone git@github.com:yourname/yourname.github.io.git /opt/blog
cd /opt/blog
git checkout main

Adding the Second Server

The blog MCP runs on the same nginx port as the first MCP — no new public port needed. The difference is the URL path: the existing MCP server is reachable at /mcp, and the blog MCP is exposed at /blog-mcp. Internally, each path reverse-proxies to its own supergateway instance on a fixed localhost port.

https://your-mcp-host/mcp       → supergateway (first MCP)   [localhost:XXXX]
https://your-mcp-host/blog-mcp  → supergateway (blog MCP)    [localhost:YYYY]  ← new

The OAuth server, bearer token validation, and /.well-known/ discovery endpoints are shared — they're defined once and apply to all location blocks on the same server.

Setting Up the Pelican Environment

Debian Trixie blocks pip install at the system level (externally-managed-environment). Use a virtual environment:

apt install python3-pip python3-venv make
python3 -m venv /opt/blog-venv
/opt/blog-venv/bin/pip install -r /opt/blog/requirements.txt

The Makefile references pelican and ghp-import by bare name. Point it at the venv by adding two variables at the top:

PELICAN?=/opt/blog-venv/bin/pelican
GHPIMPORT?=/opt/blog-venv/bin/ghp-import

And update the github target to use $(GHPIMPORT) instead of ghp-import.

Test manually before wiring anything into MCP:

cd /opt/blog && make github

GitHub will reject commits from a private email address. Use the GitHub noreply address (find yours at github.com/settings/emails):

git config --global user.email "12345+username@users.noreply.github.com"

The MCP Server

/opt/blog-mcp/server.js — a Node.js ES module MCP server. The tools:

`blog_pull`

await execFileAsync("git", ["-C", BLOG_ROOT, "pull", "--rebase"], { timeout: 30000 });

Always call at the start of a session. Returns the git output.

`blog_list_posts`

Walks content/posts/ recursively (posts with images live in subdirectories), parses Pelican metadata from each .md/.markdown file, returns one summary line per post sorted by date descending.

Supports filtering by status (published, draft, all) and category.

JS footgun to avoid: In an async for...of loop, return exits the entire function — not just the current iteration. Use continue to skip. This caused blog_list_posts to return nothing on the first run because a post without a Title triggered an early return from the walk function.

// Wrong:
if (!meta.Title) return;   // exits walk(), finds nothing

// Right:
if (!meta.Title) continue; // skips this file, keeps walking

`blog_new_post`

const filename = `${today}_${slug}.md`;
const abs = path.join(POSTS_DIR, filename);

Writes a correctly-formatted Pelican metadata block. Hard-codes the author name and Status: draft. The LLM supplies title, category, tags, and body.

`blog_edit_post`

Find/replace in a post file, identified by slug, filename, or relative path. Used to flip status:

blog_edit_post(slug="my-post", old_string="Status: draft", new_string="Status: published")

`blog_make`

Runs an allowlisted make target. The allowlist is { "html", "publish", "github" }. clean is deliberately excluded — losing your output directory mid-session is annoying.

The key detail: pass the venv bin/ to the make subprocess via PATH:

await execFileAsync(MAKE, [target], {
  cwd: BLOG_ROOT,
  timeout: 120000,
  env: { ...process.env, PATH: `${VENV_BIN}:${process.env.PATH}` }
});

Without this, make can't find pelican or ghp-import.

make github takes 10–30 seconds depending on site size. Set proxy_read_timeout 120s in nginx — the default 60s is marginal.

`blog_commit` and `blog_push`

await execFileAsync("git", ["-C", BLOG_ROOT, "add", "-A"]);
await execFileAsync("git", ["-C", BLOG_ROOT, "commit", "-m", message]);
// ...
await execFileAsync("git", ["-C", BLOG_ROOT, "push", "origin", "main"]);

Separated intentionally — commit first, review blog_status, then push.

`blog_add_image`

Node 22 has fetch built in. Saves to content/images/{subdir}/{filename} and returns the {attach} path for use in post markdown:

const response = await fetch(url);
const buffer = await response.arrayBuffer();
await fs.writeFile(dest, Buffer.from(buffer));

The Systemd Service

/etc/systemd/system/blog-mcp.service:

[Unit]
Description=Blog MCP Server
After=network.target

[Service]
Type=simple
ExecStartPre=/bin/bash -c 'cd /opt/blog-mcp && npm install --silent'
ExecStart=/usr/bin/supergateway --stdio 'node /opt/blog-mcp/server.js' \
  --port <internal-port> --outputTransport streamableHttp
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=BLOG_ROOT=/opt/blog
Environment=VENV_BIN=/opt/blog-venv/bin

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now blog-mcp

Block the internal supergateway port from external access:

nft add rule inet filter input iif != 'lo' tcp dport <internal-port> drop
nft list ruleset > /etc/nftables.conf

The nginx Block

Rather than a new server block, the blog MCP gets a new location block inside the existing server. The map {} for bearer token validation was already defined at the http {} level, so the auth variable is available here automatically.

Add this location to the existing MCP server block:

location /blog-mcp {
    if ($mcp_auth_ok = 0) {
        add_header WWW-Authenticate 'Bearer realm="blog-mcp", resource_metadata="http://$http_host/.well-known/oauth-protected-resource"' always;
        return 401 '{"error":"unauthorized"}';
    }
    proxy_pass http://127.0.0.1:<internal-port>;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_buffering off;
    proxy_read_timeout 120s;
    proxy_set_header Connection '';
    chunked_transfer_encoding on;
}

nginx -t && systemctl reload nginx

The /.well-known/ discovery endpoints, /authorize, and /token locations are already present in the existing server block and serve both MCPs without any changes.

A Session in Practice

blog_pull()
→ "Already up to date."

blog_new_post(slug="my-topic", title="My Topic", category="Programming", tags=["Python"])
→ "Created content/posts/2026-06-03_my-topic.md (Status: draft)"

blog_edit_post(slug="my-topic", old_string="Status: draft", new_string="Status: published")
→ "Edited content/posts/2026-06-03_my-topic.md"

blog_commit(message="add: my-topic post")
→ "[main abc1234] add: my-topic post"

blog_make(target="github")
→ "Done: Processed 432 articles... git push origin gh-pages"

blog_push()
→ "main -> main"

Seven tool calls, one published post.

Why Not Just Use the Existing MCP?

The first MCP server already has write_text and edit tools. In theory you could manage a blog repo with those. In practice, it's the wrong tool — you'd be reading files to learn the Pelican metadata format, manually constructing filenames, running shell commands out of band, and hoping nothing breaks in the make step.

A purpose-built MCP server encodes the domain knowledge: where posts live, what the metadata block looks like, which make targets are safe to run, how to handle collateral like images and PDFs. The LLM just supplies the content.

Having built the first MCP server already, a few things carry over directly:

Domain-specific tools beat generic ones. blog_new_post is worth writing because it encodes the Pelican metadata format, the file naming convention, and the draft-by-default behaviour. The alternative — write_text with a format the LLM has to reconstruct every time — is slower and more fragile.

Server-side computation is free tokens. Alphabetical sorting, date stamping, filename construction — anything the server can do deterministically, it should. Don't ask the LLM to reason about things it doesn't need to.

Keep the allowlist tight. The make target allowlist exists because mistakes are much easier to prevent than to fix — make clean is not something you want an LLM calling by accident.

proxy_buffering off is not optional. Pelican builds can produce a lot of output. Without it, the nginx buffer fills, the connection stalls, and the tool times out without explanation. Slug: second-mcp-pelican-blog

Building a Personal MCP Server for Your Second Brain

2026-06-03T00:00:00+01:00

Claude can do more than answer questions — it can read and write files on a server you control. A Model Context Protocol (MCP) server is the bridge. This post covers building a personal MCP server that exposes a markdown vault as tools: list projects, search notes, create entries, and commit changes — all from a Claude conversation.

What It Is

The vault is a git repository of markdown files organised around the PARA method (Projects, Areas, Resources, Archive). The MCP server is a Node.js process that reads and writes those files in response to tool calls. Claude never sees the raw filesystem — it sees a curated set of typed tools with well-defined behaviour.

The key design principle: progressive disclosure. Don't give Claude a raw file API. Give it typed tools that encode domain knowledge — what a project file looks like, where the frontmatter ends, which fields are indexable.

The File Structure

vault/
  actions/            ← GTD next-actions, one file each
    <id>.md           ← frontmatter: id, stage, due, tags
    _template.md
  areas/              ← ongoing responsibilities / long-term goals
    <id>.md
    _template.md
  archive/
    actions/          ← done/cancelled actions (search-excluded by default)
    area/             ← retired areas
    projects/         ← completed projects
  blog/               ← longer-form research and series notes
  deploy/             ← systemd units and migration scripts
    vault-mcp.service
    brain-sync.service
    brain-sync.timer
  drafts/             ← blog post drafts (blog_draft tool writes here)
  journal/
    2026.md
  mcp/                ← MCP server code
    server.js         ← main server (see full source below)
    oauth-server.js   ← minimal OAuth 2.1 AS (covered in next post)
    package.json
    README.md
  memory/             ← always-on agent brief, loaded every session
    INDEX.md
  projects/           ← active work, one file per project
    <id>.md           ← frontmatter: id, domain, status, last_touched, next_action
    _template.md
  reference/          ← stable reference material
  CLAUDE.md           ← instructions for Claude Code sessions
  glossary.md         ← acronym table, grep-only (~1500+ lines)
  todo.md             ← protected, cannot be deleted via MCP

Each projects/<id>.md has frontmatter: domain, status, started, last_touched, next_action. These are the indexed fields — the tools scan frontmatter without reading bodies.

The Tools

Index tools (frontmatter-only scans)

list_projects(status?, domain?, include_archive?)
list_actions(stage?, domain?, due_before?, include_archive?)
list_areas(domain?, include_archive?)

These walk their directory, parse only the frontmatter block from each file, and return one summary line per entry. The LLM starts here every session — it gets an overview without reading thousands of lines of content.

include_archive defaults to false. Archive-excluded-by-default keeps lists fast and focused on active material. Pass include_archive: true only when you need historical entries.

Read and search

read_text(path)                          ← full file
grep(pattern, path?, include_archive?)   ← regex search across the vault

grep is the backbone of reference and fact lookup. The glossary file grows to thousands of lines — never bulk-read it; always grep it.

Write tools

write_text(path, content)
append(path, content)
edit(path, old_string, new_string)

edit does an exact find/replace of the first match. The server never rewrites a whole file when you're changing one line — it's faster and produces cleaner diffs in git history.

Archive tools

archive_project(id)
archive_action(id)
archive_area(id)

Move the file to archive/<type>/, flip status to done. No manual file moves or editor needed.

Auto-Commit on Write

Every write tool ends with a git commit and push:

await git(["-C", BRAIN_ROOT, "add", "-A"]);
await git(["-C", BRAIN_ROOT, "commit", "-m", `mcp: ${summary}`]);
await git(["-C", BRAIN_ROOT, "push"]);

This gives you a full history of every change Claude made, browsable in any git client. It also means the vault stays in sync with the remote backup — no separate sync step needed.

Gotcha: systemd doesn't set HOME. When the service runs as root, git push fails with fatal: unable to set up default path because /root/.gitconfig and .git-credentials aren't found. Fix this with a systemd drop-in:

/etc/systemd/system/vault-mcp.service.d/home.conf:

[Service]
Environment=HOME=/root

Without this, writes succeed locally but the push silently fails — the vault appears to work but isn't backing up.

The Sync Timer

A brain-sync.timer runs every 10 minutes as a backstop:

git -C $BRAIN_ROOT pull --rebase --autostash
git -C $BRAIN_ROOT push

This handles the case where a push failed mid-session. The remote git repo is the source of truth for backup; the server is the source of truth for content.

supergateway

The MCP server is a Node.js stdio process. supergateway bridges it to a Streamable HTTP endpoint so it can be reached over the network:

supergateway --stdio 'node /opt/brain/mcp/server.js' \
  --port 3001 --outputTransport streamableHttp \
  --streamableHttpPath /mcp

Claude Code connects via ~/.mcp.json:

{
  "brain": {
    "type": "http",
    "url": "http://your-server:3001/mcp"
  }
}

Exposing the Server: Cloudflare Tunnel

supergateway listens on a local port. To reach it from outside your network — for example from Claude.ai on mobile — you need to expose it. The cleanest option for a home server is a Cloudflare Tunnel, which creates an outbound-only connection from your server to Cloudflare's edge. No open inbound ports, no port-forwarding rules.

Setup

Install cloudflared on the same host as the MCP server:

# Debian/Ubuntu
curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | tee /usr/share/keyrings/cloudflare-main.gpg > /dev/null
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main' | tee /etc/apt/sources.list.d/cloudflared.list
apt update && apt install cloudflared

Authenticate and create the tunnel from the Zero Trust dashboard (Networks → Tunnels → Create tunnel), or via CLI:

cloudflared tunnel login
cloudflared tunnel create mcp-tunnel

Configure the tunnel to route traffic to the local MCP port:

/etc/cloudflared/config.yml:

tunnel: <tunnel-id>
credentials-file: /root/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: your-mcp-host.example.com
    service: http://localhost:3001
  - service: http_status:404

Add the DNS record and start the tunnel as a system service:

cloudflared tunnel route dns mcp-tunnel your-mcp-host.example.com
cloudflared service install
systemctl enable --now cloudflared

The MCP server is now reachable at https://your-mcp-host.example.com/mcp without any firewall changes.

Connecting Claude Code via the Public URL

Once the tunnel is running, update ~/.mcp.json to use the public HTTPS URL instead of the local port:

{
  "brain": {
    "type": "http",
    "url": "https://your-mcp-host.example.com/mcp"
  }
}

This is also the URL you'd add as a remote MCP connector in Claude.ai on mobile.

Security Warning: the Server is Unauthenticated at This Point

The tunnel exposes the MCP server to the public internet with no authentication. Anyone who discovers the URL can read and write every file in the vault. This is an accepted short-term risk for initial setup and testing, but should not be left in production.

There are two options, but with an important caveat:

Cloudflare Zero Trust Access — gates the tunnel at the edge before traffic reaches your server. You can restrict by email, IP, or issue service tokens. This works for Claude Code on the command line (where you can inject custom headers or use a service token), but does not work with Claude.ai's web MCP connector. Claude.ai's connector follows the MCP auth spec and expects OAuth — it has no mechanism to supply a Cloudflare Access service token.

OAuth on the MCP server — the approach covered in the next post. A minimal Node.js OAuth server sits behind nginx; nginx validates the bearer token on every /mcp request. This is what Claude.ai's connector expects when you add a remote server in the UI, and it works across all clients — Claude Code, Claude.ai web, and Claude.ai on mobile.

If you only need Claude Code access (local or on a trusted network), Cloudflare Access alone is sufficient. If you need Claude.ai web or mobile, OAuth is the only option.

The systemd Service

/etc/systemd/system/vault-mcp.service:

[Unit]
Description=Vault MCP Server
After=network.target

[Service]
Type=simple
ExecStartPre=/bin/bash -c 'cd /opt/brain/mcp && npm install --silent'
ExecStart=/usr/bin/supergateway \
  --stdio 'node /opt/brain/mcp/server.js' \
  --port 3001 \
  --outputTransport streamableHttp \
  --streamableHttpPath /mcp
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=BRAIN_ROOT=/opt/brain

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable --now vault-mcp

ExecStartPre runs npm install on every start — no manual dependency management after updates. Intentionally no git pull here: the service might start during a write, and a pull could clobber in-flight changes.

What You Get

Once running, a session looks like:

list_projects(status="active", domain="code")
→ 12 projects, one line each

read_text("projects/my-project.md")
→ full file contents

edit("projects/my-project.md",
     old_string="next_action: review",
     new_string="next_action: ship v1")
→ committed and pushed

No file paths to remember, no git commands to run, no editor to open. The vault stays in sync and the history tells you exactly what changed and when.

The next post covers adding OAuth authentication to this server so it can be safely exposed over the internet and connected to Claude.ai on mobile.

Full Source: server.js

mcp/server.js — v0.4.0

#!/usr/bin/env node
// brain-mcp: custom MCP server for the personal-brain vault.
//
// Design goal: progressive disclosure. Tools return the minimum tokens needed
// at each tier:
//   tier 1  list_projects / list_actions / list_areas  -> frontmatter summary only
//   tier 2  read_text      -> one full file, on demand
//   tier 3  grep           -> matching lines only, from glossary/reference/etc
//
// All paths are vault-relative and sandboxed to BRAIN_ROOT.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { promises as fs } from "node:fs";
import path from "node:path";
import { execFile } from "node:child_process";
import { promisify } from "node:util";

const execFileAsync = promisify(execFile);
const ROOT = path.resolve(process.env.BRAIN_ROOT || process.argv[2] || process.cwd());

// Files grep/list walks skip. Binary + noise.
const SKIP_DIRS = new Set([".git", "node_modules", ".obsidian"]);
const BINARY_EXT = new Set([".pdf", ".epub", ".png", ".jpg", ".jpeg", ".gif", ".zip", ".db"]);
const GREP_LIMIT = 200; // max match lines returned, guards against accidental whole-vault dumps

// PARA buckets: live dir -> archive dir. One file per item, frontmatter = index.
const ARCHIVE_MAP = {
  projects: "archive/projects",
  actions: "archive/actions",
  areas: "archive/area",
};

// Resolve a vault-relative path and refuse anything that escapes ROOT.
function resolveInRoot(rel) {
  const abs = path.resolve(ROOT, rel || ".");
  if (abs !== ROOT && !abs.startsWith(ROOT + path.sep)) {
    throw new Error(`path escapes vault root: ${rel}`);
  }
  return abs;
}

// Parse a leading YAML frontmatter block into a flat key->string map.
// Intentionally simple: our frontmatter is flat scalars, no nested YAML.
function parseFrontmatter(text) {
  if (!text.startsWith("---")) return {};
  const end = text.indexOf("\n---", 3);
  if (end === -1) return {};
  const block = text.slice(text.indexOf("\n") + 1, end);
  const out = {};
  for (const line of block.split("\n")) {
    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
    if (m) out[m[1]] = m[2].replace(/^["']|["']$/g, "").trim();
  }
  return out;
}

// Flip status/stage to archived and stamp an archived date into frontmatter.
function stampArchived(text) {
  const today = new Date().toISOString().slice(0, 10);
  text = text.replace(/^status:[ \t].*$/m, "status: archived");
  text = text.replace(/^stage:[ \t].*$/m, "stage: archived");
  if (text.startsWith("---")) {
    const end = text.indexOf("\n---", 3);
    if (end !== -1 && !/^archived:/m.test(text.slice(0, end))) {
      text = text.slice(0, end) + `\narchived: ${today}` + text.slice(end);
    }
  }
  return text;
}

async function* walk(dir) {
  let entries;
  try {
    entries = await fs.readdir(dir, { withFileTypes: true });
  } catch {
    return;
  }
  for (const e of entries) {
    if (e.isDirectory()) {
      if (SKIP_DIRS.has(e.name)) continue;
      yield* walk(path.join(dir, e.name));
    } else if (e.isFile()) {
      if (BINARY_EXT.has(path.extname(e.name).toLowerCase())) continue;
      yield path.join(dir, e.name);
    }
  }
}

// Commit and push a single file after a write operation.
async function gitCommitAndPush(rel, action) {
  try {
    await execFileAsync("git", ["-C", ROOT, "add", rel]);
    await execFileAsync("git", ["-C", ROOT, "commit", "-m", `mcp: ${action} ${rel}`]);
    await execFileAsync("git", ["-C", ROOT, "pull", "--rebase", "--autostash", "origin", "main"]);
    await execFileAsync("git", ["-C", ROOT, "push", "origin", "main"]);
    return " — pushed";
  } catch (err) {
    const msg = err.stderr || err.message || String(err);
    if (msg.includes("nothing to commit")) return "";
    return ` — push failed: ${msg.trim().split("\n")[0]}`;
  }
}

// Commit a move (new file added, old path deleted) in one commit.
async function gitCommitMove(oldRel, newRel, action) {
  try {
    await execFileAsync("git", ["-C", ROOT, "add", newRel]);
    await execFileAsync("git", ["-C", ROOT, "add", "-A", "--", oldRel]);
    await execFileAsync("git", ["-C", ROOT, "commit", "-m", `mcp: ${action} ${oldRel} -> ${newRel}`]);
    await execFileAsync("git", ["-C", ROOT, "pull", "--rebase", "--autostash", "origin", "main"]);
    await execFileAsync("git", ["-C", ROOT, "push", "origin", "main"]);
    return " — pushed";
  } catch (err) {
    const msg = err.stderr || err.message || String(err);
    if (msg.includes("nothing to commit")) return "";
    return ` — push failed: ${msg.trim().split("\n")[0]}`;
  }
}

// Shared: move <kind>/<id>.md into its archive dir, flipping status/stage.
async function archiveItem(kind, id) {
  const srcRel = `${kind}/${id}.md`;
  const src = resolveInRoot(srcRel);
  let text;
  try {
    text = await fs.readFile(src, "utf8");
  } catch {
    return { content: [{ type: "text", text: `${srcRel} not found` }], isError: true };
  }
  text = stampArchived(text);
  const destRel = `${ARCHIVE_MAP[kind]}/${id}.md`;
  const dest = resolveInRoot(destRel);
  await fs.mkdir(path.dirname(dest), { recursive: true });
  await fs.writeFile(dest, text);
  await fs.unlink(src);
  const status = await gitCommitMove(srcRel, destRel, "archive");
  return { content: [{ type: "text", text: `archived ${srcRel} -> ${destRel}${status}` }] };
}

const server = new McpServer({ name: "brain-mcp", version: "0.4.0" });

// ---- tier 1: derived indexes -----------------------------------------------
server.registerTool(
  "list_projects",
  {
    title: "List projects",
    description:
      "Derived project index. Scans frontmatter of projects/*.md (skips _template) and returns one summary line per project. Reads frontmatter only, never bodies. Start here every session.",
    inputSchema: {
      status: z.enum(["active", "idle", "done"]).optional().describe("filter by status"),
      domain: z.string().optional().describe("filter by domain, e.g. woodwork, code, 3d, trip, work"),
      include_archive: z.boolean().optional().describe("also scan archive/projects/ (default false)"),
    },
  },
  async ({ status, domain, include_archive }) => {
    const dirs = [resolveInRoot("projects")];
    if (include_archive) dirs.push(resolveInRoot("archive/projects"));
    const lines = [];
    for (const dir of dirs) {
      for await (const file of walk(dir)) {
        const rel = path.relative(ROOT, file);
        if (path.basename(file) === "_template.md") continue;
        if (path.extname(file) !== ".md") continue;
        const fm = parseFrontmatter(await fs.readFile(file, "utf8"));
        if (!fm.id) continue;
        if (status && fm.status !== status) continue;
        if (domain && fm.domain !== domain) continue;
        lines.push(
          `${fm.id} | ${fm.domain || "?"} | ${fm.status || "?"} | touched ${fm.last_touched || "?"} | next: ${fm.next_action || "-"} | ${rel}`
        );
      }
    }
    lines.sort();
    return { content: [{ type: "text", text: lines.length ? lines.join("\n") : "(no projects match)" }] };
  }
);

server.registerTool(
  "list_actions",
  {
    title: "List actions",
    description:
      "Derived action index (GTD). Scans frontmatter of actions/*.md (skips _template), returns one line per action sorted by due date (undated last). Reads frontmatter only.",
    inputSchema: {
      stage: z.enum(["someday", "next", "waiting"]).optional().describe("filter by stage"),
      domain: z.string().optional().describe("filter by tag, e.g. 3d, workshop, code"),
      due_before: z.string().optional().describe("only actions with due <= this YYYY-MM-DD"),
      include_archive: z.boolean().optional().describe("also scan archive/actions/ (default false)"),
    },
  },
  async ({ stage, domain, due_before, include_archive }) => {
    const dirs = [resolveInRoot("actions")];
    if (include_archive) dirs.push(resolveInRoot("archive/actions"));
    const rows = [];
    for (const dir of dirs) {
      for await (const file of walk(dir)) {
        const rel = path.relative(ROOT, file);
        if (path.basename(file) === "_template.md") continue;
        if (path.extname(file) !== ".md") continue;
        const fm = parseFrontmatter(await fs.readFile(file, "utf8"));
        if (!fm.id) continue;
        if (stage && fm.stage !== stage) continue;
        if (domain && !(fm.tags || "").includes(domain)) continue;
        if (due_before && (!fm.due || fm.due > due_before)) continue;
        rows.push({
          due: fm.due || "~",
          line: `${fm.id} | ${fm.stage || "?"} | due ${fm.due || "-"} | tags ${fm.tags || "-"} | ${rel}`,
        });
      }
    }
    rows.sort((a, b) => (a.due < b.due ? -1 : a.due > b.due ? 1 : 0));
    return {
      content: [{ type: "text", text: rows.length ? rows.map((r) => r.line).join("\n") : "(no actions match)" }],
    };
  }
);

server.registerTool(
  "list_areas",
  {
    title: "List areas",
    description:
      "Derived area index. Scans frontmatter of areas/*.md (skips _template), one line per area of responsibility / long-term goal. Reads frontmatter only.",
    inputSchema: {
      domain: z.string().optional().describe("filter by domain"),
      include_archive: z.boolean().optional().describe("also scan archive/area/ (default false)"),
    },
  },
  async ({ domain, include_archive }) => {
    const dirs = [resolveInRoot("areas")];
    if (include_archive) dirs.push(resolveInRoot("archive/area"));
    const lines = [];
    for (const dir of dirs) {
      for await (const file of walk(dir)) {
        const rel = path.relative(ROOT, file);
        if (path.basename(file) === "_template.md") continue;
        if (path.extname(file) !== ".md") continue;
        const fm = parseFrontmatter(await fs.readFile(file, "utf8"));
        const id = fm.id || path.basename(file, ".md");
        lines.push(`${id} | ${fm.domain || "?"} | updated ${fm["last-updated"] || fm.last_touched || "?"} | ${rel}`);
      }
    }
    lines.sort();
    return { content: [{ type: "text", text: lines.length ? lines.join("\n") : "(no areas match)" }] };
  }
);

// ---- tier 2: read one file -------------------------------------------------
server.registerTool(
  "read_text",
  {
    title: "Read file",
    description: "Read a full vault file as text. Use after list_projects/grep narrows to one file.",
    inputSchema: { path: z.string().describe("vault-relative path, e.g. projects/woodwork-table.md") },
  },
  async ({ path: rel }) => {
    const text = await fs.readFile(resolveInRoot(rel), "utf8");
    return { content: [{ type: "text", text }] };
  }
);

// ---- tier 3: content search ------------------------------------------------
server.registerTool(
  "grep",
  {
    title: "Grep content",
    description:
      "Search file contents by regex, return matching lines as 'relpath:lineno: text'. Use for glossary/reference/fact lookups instead of reading whole files. Skips archive/ by default.",
    inputSchema: {
      pattern: z.string().describe("JavaScript regex, case-insensitive"),
      path: z.string().optional().describe("limit to this file or subdir (default whole vault)"),
      include_archive: z.boolean().optional().describe("also search archive/ (default false)"),
    },
  },
  async ({ pattern, path: rel, include_archive }) => {
    let re;
    try {
      re = new RegExp(pattern, "i");
    } catch (e) {
      return { content: [{ type: "text", text: `bad regex: ${e.message}` }], isError: true };
    }
    const start = resolveInRoot(rel);
    const stat = await fs.stat(start);
    let files = [];
    if (stat.isFile()) files.push(start);
    else for await (const f of walk(start)) files.push(f);

    const archiveAbs = resolveInRoot("archive");
    const startInArchive = start === archiveAbs || start.startsWith(archiveAbs + path.sep);
    if (!include_archive && !startInArchive) {
      files = files.filter((f) => !(f === archiveAbs || f.startsWith(archiveAbs + path.sep)));
    }

    const hits = [];
    for (const file of files) {
      if (hits.length >= GREP_LIMIT) break;
      const text = await fs.readFile(file, "utf8");
      const relp = path.relative(ROOT, file);
      text.split("\n").forEach((line, i) => {
        if (hits.length < GREP_LIMIT && re.test(line)) hits.push(`${relp}:${i + 1}: ${line.trim()}`);
      });
    }
    return {
      content: [
        { type: "text", text: hits.length ? hits.join("\n") + (hits.length >= GREP_LIMIT ? "\n(truncated)" : "") : "(no matches)" },
      ],
    };
  }
);

// ---- writes ----------------------------------------------------------------
server.registerTool(
  "append",
  {
    title: "Append to file",
    description: "Append text to a file (created if missing). For append-only data: journal lines, project Log entries.",
    inputSchema: {
      path: z.string().describe("vault-relative path"),
      text: z.string().describe("text to append; a trailing newline is added if absent"),
    },
  },
  async ({ path: rel, text }) => {
    const abs = resolveInRoot(rel);
    await fs.mkdir(path.dirname(abs), { recursive: true });
    await fs.appendFile(abs, text.endsWith("\n") ? text : text + "\n");
    const status = await gitCommitAndPush(rel, "append");
    return { content: [{ type: "text", text: `appended to ${rel}${status}` }] };
  }
);

server.registerTool(
  "edit",
  {
    title: "Edit file",
    description: "Replace the first exact occurrence of old_string with new_string in a file. Targeted edit, no full rewrite.",
    inputSchema: {
      path: z.string(),
      old_string: z.string().describe("exact text to find (must be unique enough to match once)"),
      new_string: z.string(),
    },
  },
  async ({ path: rel, old_string, new_string }) => {
    const abs = resolveInRoot(rel);
    const text = await fs.readFile(abs, "utf8");
    const idx = text.indexOf(old_string);
    if (idx === -1) return { content: [{ type: "text", text: "old_string not found" }], isError: true };
    const next = text.slice(0, idx) + new_string + text.slice(idx + old_string.length);
    await fs.writeFile(abs, next);
    const status = await gitCommitAndPush(rel, "edit");
    return { content: [{ type: "text", text: `edited ${rel}${status}` }] };
  }
);

server.registerTool(
  "write_text",
  {
    title: "Write file",
    description: "Create or overwrite a file. Use for new project/action/area files from a template; prefer append/edit for existing files.",
    inputSchema: { path: z.string(), content: z.string() },
  },
  async ({ path: rel, content }) => {
    const abs = resolveInRoot(rel);
    await fs.mkdir(path.dirname(abs), { recursive: true });
    await fs.writeFile(abs, content);
    const status = await gitCommitAndPush(rel, "write");
    return { content: [{ type: "text", text: `wrote ${rel}${status}` }] };
  }
);

server.registerTool(
  "list",
  {
    title: "List directory",
    description: "List files and directories at a vault path.",
    inputSchema: { path: z.string().optional().describe("vault-relative dir, default root") },
  },
  async ({ path: rel }) => {
    const abs = resolveInRoot(rel || ".");
    const entries = await fs.readdir(abs, { withFileTypes: true });
    const out = entries
      .filter((e) => !SKIP_DIRS.has(e.name))
      .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
      .sort();
    return { content: [{ type: "text", text: out.join("\n") || "(empty)" }] };
  }
);

// ---- archive ---------------------------------------------------------------
server.registerTool(
  "archive_project",
  {
    title: "Archive project",
    description: "Move projects/<id>.md to archive/projects/<id>.md and set status: archived.",
    inputSchema: { id: z.string().describe("project id (filename without .md)") },
  },
  async ({ id }) => archiveItem("projects", id)
);

server.registerTool(
  "archive_action",
  {
    title: "Archive action",
    description: "Move actions/<id>.md to archive/actions/<id>.md and set stage: archived.",
    inputSchema: { id: z.string().describe("action id (filename without .md)") },
  },
  async ({ id }) => archiveItem("actions", id)
);

server.registerTool(
  "archive_area",
  {
    title: "Archive area",
    description: "Move areas/<id>.md to archive/area/<id>.md and set status: archived.",
    inputSchema: { id: z.string().describe("area id (filename without .md)") },
  },
  async ({ id }) => archiveItem("areas", id)
);

// ---- glossary --------------------------------------------------------------
server.registerTool(
  "glossary_add",
  {
    title: "Add glossary entry",
    description:
      "Insert a new row into glossary.md in the correct alphabetical position by acronym. " +
      "Server-side sort — do not read glossary.md first.",
    inputSchema: {
      acronym:    z.string().describe("The acronym or short form, e.g. 'ACE'"),
      definition: z.string().describe("Full expansion, e.g. 'AMBA Coherency Extensions'"),
      notes:      z.string().optional().describe("Optional context or disambiguation"),
    },
  },
  async ({ acronym, definition, notes = "" }) => {
    const rel = "glossary.md";
    const abs = resolveInRoot(rel);
    const text = await fs.readFile(abs, "utf8");
    const lines = text.split("\n");

    const isDataRow = (l) => /^\|/.test(l) && !/^\|[-: |]+\|/.test(l);
    const acronymOf  = (l) => l.split("|")[1]?.trim() ?? "";
    const newKey = acronym.toLowerCase();
    let insertAt = -1;
    for (let i = 0; i < lines.length; i++) {
      if (isDataRow(lines[i]) && acronymOf(lines[i]).toLowerCase() <= newKey) {
        insertAt = i + 1;
      }
    }
    if (insertAt === -1) {
      insertAt = lines.findIndex((l) => /^\|[-: |]+\|/.test(l)) + 1;
    }

    const newRow = `| ${acronym} | ${definition} | ${notes} |`;
    lines.splice(insertAt, 0, newRow);
    await fs.writeFile(abs, lines.join("\n"));
    const status = await gitCommitAndPush(rel, "glossary_add");
    return { content: [{ type: "text", text: `added '${acronym}' at line ${insertAt + 1}${status}` }] };
  }
);

// ---- blog drafts -----------------------------------------------------------
server.registerTool(
  "blog_draft",
  {
    title: "Create blog draft",
    description:
      "Create a new blog draft in drafts/blog-{slug}.md with correct frontmatter. " +
      "The 'blog' tag is always included; add domain-specific tags alongside it.",
    inputSchema: {
      slug:  z.string().describe("kebab-case identifier, e.g. 'mcp-oauth-setup'"),
      title: z.string().describe("Post title, used as the H1 heading"),
      tags:  z.array(z.string()).optional().describe("Extra tags beyond 'blog'"),
      body:  z.string().optional().describe("Initial markdown body content"),
    },
  },
  async ({ slug, title, tags = [], body = "" }) => {
    const today = new Date().toISOString().slice(0, 10);
    const allTags = ["blog", ...tags.filter((t) => t !== "blog")];
    const rel = `drafts/blog-${slug}.md`;
    const abs = resolveInRoot(rel);

    const content = [
      "---",
      `id: blog-${slug}`,
      `stage: draft`,
      `tags: [${allTags.join(", ")}]`,
      `created: ${today}`,
      "---",
      "",
      `# ${title}`,
      "",
      body,
    ].join("\n").trimEnd() + "\n";

    await fs.mkdir(path.dirname(abs), { recursive: true });
    await fs.writeFile(abs, content);
    const status = await gitCommitAndPush(rel, "blog_draft");
    return { content: [{ type: "text", text: `created ${rel}${status}` }] };
  }
);

// ---- delete ----------------------------------------------------------------
server.registerTool(
  "delete",
  {
    title: "Delete file",
    description:
      "Permanently delete a vault file. A small set of core files (glossary.md, CLAUDE.md, README.md, todo.md) are protected.",
    inputSchema: {
      path: z.string().describe("vault-relative path"),
    },
  },
  async ({ path: rel }) => {
    const PROTECTED = new Set(["glossary.md", "CLAUDE.md", "README.md", "todo.md"]);
    if (PROTECTED.has(path.basename(rel))) {
      return { content: [{ type: "text", text: `'${rel}' is a protected file and cannot be deleted` }], isError: true };
    }
    const abs = resolveInRoot(rel);
    try { await fs.access(abs); } catch {
      return { content: [{ type: "text", text: `'${rel}' not found` }], isError: true };
    }
    await fs.unlink(abs);
    try {
      await execFileAsync("git", ["-C", ROOT, "rm", "--cached", rel]);
      await execFileAsync("git", ["-C", ROOT, "commit", "-m", `mcp: delete ${rel}`]);
      await execFileAsync("git", ["-C", ROOT, "pull", "--rebase", "--autostash", "origin", "main"]);
      await execFileAsync("git", ["-C", ROOT, "push", "origin", "main"]);
      return { content: [{ type: "text", text: `deleted ${rel} — pushed` }] };
    } catch (err) {
      const msg = (err.stderr || err.message || String(err)).trim().split("\n")[0];
      return { content: [{ type: "text", text: `deleted ${rel} (git: ${msg})` }] };
    }
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Adding OAuth Authentication to a Self-Hosted MCP Server

2026-06-03T00:00:00+01:00

If you're running a self-hosted MCP server and exposing it over HTTP, you need authentication. Without it, anyone who can reach your port can invoke your tools.

This post covers adding OAuth 2.1 auth to the vault MCP server from the previous post. Claude.ai's MCP connector implements the full OAuth 2.1 authorization code + PKCE flow — it expects an OAuth Client ID and Secret, not a pre-shared bearer token. So that's what we build.

The Starting Point

The server runs on a Debian container on Proxmox. The stack before this work:

server.js — Node.js MCP server (stdio transport)
supergateway — bridges stdio → Streamable HTTP on port 3001
vault-mcp.service — systemd unit managing supergateway
No authentication — port 3001 open, any client could read and write vault files

Step 1: nginx as an Authenticating Reverse Proxy

supergateway has no built-in support for validating incoming authentication — --oauth2Bearer is outbound-only, adding headers to requests supergateway makes upstream, not checking headers on requests coming in.

The solution is to place nginx in front: move supergateway to an internal port, and let nginx handle bearer token validation before any request reaches the MCP server.

Claude.ai's MCP connector requires three things from an OAuth server:

A /.well-known/oauth-authorization-server discovery endpoint (RFC 8414)
An /authorize endpoint it can redirect the user's browser to
A /token endpoint where it exchanges the authorization code for an access token

nginx serves the discovery endpoints statically and proxies /authorize and /token to a small Node.js OAuth server running on localhost.

Step 2: The Architecture

MCP client (Claude.ai)
      │  HTTP  Authorization: Bearer <token>
      ▼
 nginx :3001  (public)
      │  validates bearer token
      │  serves /.well-known/ OAuth discovery endpoints
      │  proxies /authorize and /token to OAuth server
      ▼
 OAuth server :3003  (localhost only)
      │  minimal OAuth 2.0 AS — auto-approves, issues static token
      ▼
 supergateway :3002  (localhost only, blocked by firewall)
      │
      ▼
 node server.js

Step 3: Move supergateway, Install nginx, Block the Internal Port

# Move supergateway to an internal port
sed -i 's/--port 3001/--port 3002/' /etc/systemd/system/vault-mcp.service
systemctl daemon-reload && systemctl restart vault-mcp

# Install nginx
apt install -y nginx

# Block external access to the internal supergateway port
nft add rule inet filter input iif != 'lo' tcp dport 3002 drop
nft list ruleset > /etc/nftables.conf
systemctl enable nftables

Step 4: A Minimal OAuth Server in ~150 Lines of Node.js

For a single-user personal server, a "real" OAuth AS doesn't need to be complex. The key insight: auto-approve all authorization requests — there's only one trusted client — and always issue the same static access token so nginx validation stays simple and restarts don't force re-authentication.

// oauth-server.js (abridged)
import http from "node:http";
import crypto from "node:crypto";

const { OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_ACCESS_TOKEN } = process.env;
const pendingCodes = new Map();

const server = http.createServer((req, res) => {
  // GET /authorize — auto-approve, redirect with code
  if (req.method === "GET" && pathname === "/authorize") {
    const { client_id, redirect_uri, state, code_challenge, code_challenge_method } = query;
    if (client_id !== OAUTH_CLIENT_ID) return json(res, 400, { error: "invalid_client" });

    const code = crypto.randomBytes(24).toString("base64url");
    pendingCodes.set(code, {
      redirectUri: redirect_uri,
      codeChallenge: code_challenge,
      method: code_challenge_method,
      expiresAt: Date.now() + 5 * 60 * 1000,
    });

    const redirect = new URL(redirect_uri);
    redirect.searchParams.set("code", code);
    if (state) redirect.searchParams.set("state", state);
    res.writeHead(302, { Location: redirect.toString() });
    return res.end();
  }

  // POST /token — verify PKCE + client secret, return static token
  if (req.method === "POST" && pathname === "/token") {
    // ... validate client_id, client_secret, code, PKCE verifier ...
    return json(res, 200, {
      access_token: OAUTH_ACCESS_TOKEN,
      token_type: "Bearer",
      expires_in: 31536000,  // 1 year — effectively non-expiring
    });
  }
});

server.listen(3003, "127.0.0.1");

Failure 3: crypto.timingSafeEqual Crashes on Mismatched Lengths

When testing with a wrong client_secret, the server crashed:

RangeError: Input buffers must have the same byte length

crypto.timingSafeEqual requires both buffers to be exactly the same byte length — it throws rather than returning false. Always guard it:

const secretBuf   = Buffer.from(client_secret || "");
const expectedBuf = Buffer.from(OAUTH_CLIENT_SECRET);
const secretOk = secretBuf.length === expectedBuf.length &&
  crypto.timingSafeEqual(secretBuf, expectedBuf);

Without the guard, a wrong-length secret becomes a denial-of-service vector — the crash causes a 502 from nginx.

Step 5: Wire nginx to the OAuth Server

Updated nginx config — the key additions are proxying /authorize and /token, and adding the OAuth discovery metadata:

server {
    listen 3001;
    server_name _;

    location = /.well-known/oauth-protected-resource {
        default_type application/json;
        add_header Access-Control-Allow-Origin * always;
        return 200 '{"resource":"http://$http_host","authorization_servers":["http://$http_host"]}';
    }

    location = /.well-known/oauth-authorization-server {
        default_type application/json;
        add_header Access-Control-Allow-Origin * always;
        return 200 '{"issuer":"http://$http_host","authorization_endpoint":"http://$http_host/authorize","token_endpoint":"http://$http_host/token","response_types_supported":["code"],"grant_types_supported":["authorization_code"],"code_challenge_methods_supported":["S256","plain"],"token_endpoint_auth_methods_supported":["client_secret_post"]}';
    }

    location = /authorize {
        proxy_pass http://127.0.0.1:3003;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
    }

    location = /token {
        proxy_pass http://127.0.0.1:3003;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
    }

    location /mcp {
        if ($mcp_auth_ok = 0) {
            add_header WWW-Authenticate 'Bearer realm="mcp", resource_metadata="http://$http_host/.well-known/oauth-protected-resource"' always;
            return 401 '{"error":"unauthorized"}';
        }
        proxy_pass http://127.0.0.1:3002;
        proxy_buffering off;
        proxy_read_timeout 300s;
        proxy_set_header Connection '';
        chunked_transfer_encoding on;
    }
}

Step 6: The $http_host Gotcha

Per RFC 8414, the issuer in OAuth metadata must match the URL used to discover it. A mismatch is a valid reason for a client to reject the metadata entirely. Even if the connector didn't strictly validate the issuer, a private LAN IP is unreachable from Claude.ai's infrastructure if the token exchange happens server-side.

This surfaces as the OAuth flow appearing to start but never completing — the nginx access log shows the browser hitting /authorize (302 ✓), then Claude.ai's connector hitting /mcp again with 401, with no /token call in between.

If you're seeing this, check your /.well-known/oauth-authorization-server response. A hardcoded private IP or a hostname that doesn't match the public domain the client is connecting through is almost certainly the cause:

{
  "issuer": "http://192.168.x.x:3001",
  "token_endpoint": "http://192.168.x.x:3001/token"
}

Fix: Use nginx's $http_host variable in the metadata JSON so the URLs always reflect whatever hostname the request arrived on:

return 200 '{"issuer":"http://$http_host","token_endpoint":"http://$http_host/token",...}';

After this change: ✅ Claude.ai completed the full OAuth flow and connected successfully.

The OAuth Server systemd Service

/etc/systemd/system/oauth-server.service:

[Unit]
Description=MCP OAuth Server
After=network.target

[Service]
Type=simple
ExecStart=node /opt/mcp-oauth/oauth-server.js
Restart=always
RestartSec=5
Environment=NODE_ENV=production
Environment=OAUTH_CLIENT_ID=your-client-id
Environment=OAUTH_CLIENT_SECRET=your-client-secret
Environment=OAUTH_ACCESS_TOKEN=your-static-bearer-token

[Install]
WantedBy=multi-user.target

The static OAUTH_ACCESS_TOKEN is the value in nginx's map {} block. Generate all three secrets with openssl rand -base64 48 and treat them like passwords.

Lessons

#	Lesson
1	`proxy_buffering off` is essential for MCP streaming — without it clients hang
2	`crypto.timingSafeEqual` throws on mismatched buffer lengths — always check lengths first
3	Never hardcode IPs in OAuth metadata — use `$http_host` so the issuer always matches the discovery URL
4	`nftables iif != "lo" tcp dport XXXX drop` is the cleanest way to lock an internal service to loopback

The minimal OAuth server approach (auto-approve + static token) is a good fit for a personal server. It's not a security shortcut — the actual secret is the client credentials, PKCE is enforced, and the issued token is what nginx validates. The "simplification" is just removing the login page that makes no sense for a single trusted client.

The next post covers adding a second MCP server to the same host — reusing all of this OAuth infrastructure for a blog-management server on a different URL path.

SoC Article 10: The SoC design flow - From specification to silicon

2026-06-03T00:00:00+01:00

Series: Introduction to SoC Design | Article 10 of 11

Introduction

Designing a System-on-Chip (SoC) is not a single act of creation. It is a disciplined, iterative engineering process. A team of hundreds, sometimes thousands, of engineers spends one to three years completing it. The design flow is the structured sequence of phases, tools, and verification checkpoints that transforms an initial concept into a physical chip ready for manufacture.

This article walks through the entire flow, from the first line of specification to the GDSII file sent to the foundry, explaining what happens at each stage and why each step is necessary.

Why the flow matters

Semiconductor manufacturing is extraordinarily expensive and irreversible. Taping out a 7 nm chip can cost $20--50 million in NRE (Non-Recurring Engineering) costs. A single bug that reaches silicon can require a complete re-spin, delaying the product by 6--12 months and costing tens of millions of dollars. Examples include a wrong bit in a register address or a timing path that fails at high temperature.

The design flow exists to make bugs cheap to find early and impossible to reach silicon. Every stage adds more confidence that the design will work correctly when manufactured.

Overview of the flow

Stage 1: Specification

The design begins with a specification document: a detailed description of what the chip must do, including:

Functional requirements: what operations it must support
Performance targets: minimum operating frequency, latency, throughput
Power budget: maximum active power, standby power
Area budget: die size constraint (directly affects cost)
Interface requirements: which external protocols must be supported
Operating conditions: voltage range, temperature range, process corners

System architects and product managers write specifications. Specifications are often imprecise at first. The design process refines them as constraints become clearer.

Stage 2: Architecture

The architecture phase translates requirements into a block-level design. Key decisions:

IP selection: Which CPU core? Which bus protocol? Which memory interface? Purchased intellectual property (IP), such as an ARM Cortex-A core or Synopsys DesignWare USB, or custom-designed?

Hardware/software (HW/SW) partitioning: Which functions are implemented in fixed hardware and which run in software on the CPU? Hardware is faster and more energy-efficient but inflexible; software is flexible but slower.

Memory map: Where in the 32-bit or 64-bit address space does each block live? The memory map is fundamental: once set, changing it breaks all software.

Block diagram and interface specification: Defining the ports of each block and how they connect to the bus.

The output of the architecture phase is an architecture specification: a document that all downstream engineers work from.

Stage 3: RTL Design

Each block in the architecture is coded in SystemVerilog or VHDL at register transfer level (RTL). This phase is typically the longest and involves the most engineers.

IP integration: Licensed IP is delivered as RTL source files or encrypted IP. They are instantiated in the top-level integration and connected to the bus fabric.

Custom RTL: Blocks that do not exist as purchasable IP are designed from scratch by the team's RTL engineers.

Lint checking: Automated tools scan the RTL for common coding mistakes (undriven signals, unintended latches, undeclared ports) before simulation.

RTL Lint Checks (examples):

  ✗ Combinational loop -- combinational path with no register
  ✗ Multi-driven net -- two drivers connected to same wire
  ✗ Unintended latch -- missing default in always_comb case
  ✗ Width mismatch -- 8-bit signal assigned to 16-bit port
  ✗ Reset missing -- flip-flop has no reset path
  ✗ X-propagation risk -- uninitialized signal used in logic

Stage 4: Functional Verification

Verification is the process of proving (to sufficient confidence) that the RTL correctly implements the specification. It is the biggest investment in a modern SoC project, typically consuming 60--70% of total design effort and schedule.

Simulation

Engineers simulate the RTL against a testbench that models the SoC's environment. Most modern SoC testbenches use the Universal Verification Methodology (UVM), a standardised framework for building reusable verification components:

Coverage-Driven Verification

Engineers define coverage metrics: measurable goals that indicate whether enough of the design space has been tested:

Code coverage: Has every line and branch of the RTL been exercised?

Functional coverage: Have all interesting combinations of inputs occurred? For example: FIFO full during reset, all AXI burst lengths, or all interrupt priority combinations.

Verification is complete when coverage goals are met, all bugs have been fixed and re-verified, and a formal sign-off review has been passed.

Formal Verification

Formal verification uses mathematical techniques to prove properties about the design, rather than testing with specific inputs. It can exhaustively check all possible input sequences (up to a bounded depth).

Formal vs Simulation:

  Simulation:         Tests specific sequences chosen by engineers
                      → Can miss corner cases
                      → Fast for common cases

  Formal:             Mathematically proves properties hold for ALL inputs
                      → Complete for bounded depth
                      → Can find bugs simulation never would
                      → Slower, limited to smaller blocks

Formal verification tools (Cadence JasperGold, Synopsys VC Formal) are used for: - Block-level property checking - Clock domain crossing analysis - Security property verification - Register model consistency

Hardware Emulation

For large SoCs, simulation is too slow to run real software. Hardware emulators (Cadence Palladium, Synopsys ZeBu) compile the RTL into custom field-programmable gate arrays (FPGAs) or application-specific integrated circuits (ASICs) that run 100--1000x faster than software simulation. This allows booting Linux, running real drivers, and executing application-level tests before silicon is available.

Stage 5: Synthesis

Once RTL verification is complete, synthesis converts the RTL into a gate-level netlist using a specific technology's standard cell library.

Synthesis Constraints

The synthesis tool needs to know the timing requirements, expressed in Synopsys Design Constraints (SDC) format:

# SDC constraint example
create_clock -name "cpu_clk" -period 0.5 [get_ports clk_in]  ; # 2 GHz clock
set_input_delay  0.1 -clock cpu_clk [all_inputs]
set_output_delay 0.1 -clock cpu_clk [all_outputs]
set_max_fanout   20  [all_registers]

The tool then maps each RTL construct to available cells from the standard cell library: a characterised set of gates (AND2, OR3, DFF, MUX2, ...) provided by the foundry or cell library vendor.

Gate-Level Netlist

The output is a gate-level netlist: a flat or hierarchical description of the design in terms of specific cell instances and their interconnections:

// Example gate-level netlist fragment (post-synthesis)
module counter_synth (clk, rst_n, en, count);
  // Cell instances from the standard cell library:
  DFF_X1 FF0 (.D(n12), .CK(clk), .Q(count[0]));
  DFF_X1 FF1 (.D(n14), .CK(clk), .Q(count[1]));
  AND2_X1 U1 (.A1(en), .A2(count[0]), .ZN(n12));
  XOR2_X1 U2 (.A(count[1]), .B(n12), .Z(n14));
  // ... hundreds or thousands of cells
endmodule

Stage 6: Physical design (back-end)

Physical design transforms the logical netlist into a physical layout: geometric shapes on the silicon used to manufacture the chip. This is the "back-end" of the design flow.

Floorplanning

The die is partitioned into regions, and major blocks are placed at approximate locations. Phase-locked loops (PLLs), physical layer interfaces (PHYs), static RAM (SRAM), and IP hard macros are placed at fixed locations first.

Placement

The automatic placement tool places all standard cells within each block's area, minimising wire length and ensuring timing constraints can be met.

Clock tree synthesis

Clock tree synthesis (CTS) builds the clock distribution tree that delivers the clock signal with minimal skew and jitter to every flip-flop. As discussed in Article 06, CTS is one of the most critical and time-consuming back-end steps.

Routing

Routing connects all cell inputs and outputs with metal wires according to the netlist. Modern designs have 10--15 metal layers; the router must find paths for millions of wires without violations.

Verification After Routing: Sign-off Checks

Physical Verification Checks:

  DRC (Design Rule Check)
      ✓ Minimum wire width, spacing, via rules
      ✓ Antenna rules (charge accumulation during manufacture)
      ✓ Process-specific rules from the foundry

  LVS (Layout vs Schematic)
      ✓ Does the physical layout match the netlist?
      ✓ No extra or missing connections?

  ERC (Electrical Rule Check)
      ✓ Short circuits, open nets
      ✓ Floating inputs, missing power connections

Stage 7: Sign-off

Before tape-out, the design must pass a series of sign-off checks that confirm it works correctly after fabrication:

Static Timing Analysis (STA): Verifies that every logic path in the design meets the required timing, across all process corners (fast/slow transistors), voltages (nominal/low), and temperatures (cold/hot):

STA Timing Path Example:

  Launch FF               Capture FF
      │                       │
  clk→[FF1]──[Comb Logic]──►[FF2]←clk
              (delay = 0.35 ns)

  Setup check:
    Required time = Clock period - Setup time
                  = 0.5 ns - 0.03 ns = 0.47 ns
    Data arrival  = Launch clock edge + buffer delay + logic delay
                  = 0 + 0.10 ns + 0.35 ns = 0.45 ns
    Slack         = 0.47 - 0.45 = +0.02 ns ✓ (positive = PASS)

  If slack were negative, the path would need to be fixed
  (by resizing cells, restructuring logic, or relaxing the clock).

Power Analysis: Estimates active and leakage power consumption across typical and worst-case workloads.

IR Drop Analysis: Verifies that the power distribution network delivers sufficient voltage to every cell, accounting for resistive drops through the metal power rails.

Stage 8: Tape-out and fabrication

Tape-out is the formal submission of the Graphic Design System II (GDSII) file to the foundry: the geometric database of every polygon on every mask layer used to manufacture the chip.

After tape-out:

Mask making: The foundry converts GDSII into photomasks (~$1M--$5M per mask set for advanced nodes).
Wafer fabrication: An 8--24 week process, typically 400--900 process steps.
Wafer probing: Each die is tested electrically before dicing.
Dicing: The wafer is cut into individual dies.
Packaging: Each die is bonded into a package such as a ball grid array (BGA) or quad flat package (QFP).
Final test: Packaged devices are tested at speed and temperature.
Characterisation: A sample of devices is measured to build a statistical model of the process.

State machine of the design flow

Tools of the trade

Phase	Industry Tools
RTL Lint	Mentor Questa Lint, Synopsys Spyglass
Simulation	Synopsys VCS, Cadence Xcelium, Mentor Questa
Formal Verification	Cadence JasperGold, Synopsys VC Formal
Emulation	Cadence Palladium, Synopsys ZeBu
Synthesis	Synopsys Design Compiler / Fusion Compiler, Cadence Genus
Physical Design	Cadence Innovus, Synopsys IC Compiler II
STA Sign-off	Synopsys PrimeTime, Cadence Tempus
Physical Verification	Siemens Calibre, Cadence PVS
Open-Source Alternatives	Yosys (synthesis), OpenROAD (PD), KLayout (viewing GDSII)

Summary

The SoC design flow is a rigorous, multi-stage process designed to catch errors at the cheapest possible point: before they reach silicon. It begins with specification and architecture, progresses through RTL coding and verification, then synthesis, physical design, and sign-off, culminating in tape-out. Verification is the largest time investment, spanning simulation, assertion-based checking, and formal methods. Physical design transforms the logical netlist into real geometry on the wafer. Every phase generates new insights that may require revisiting earlier phases. The flow is iterative, not linear.

Advanced articles this topic connects to

RTL Synthesis and Timing Closure: Constraint writing, ECO, multi-corner STA
Physical Design: Floorplanning and Place-and-Route: In-depth CTS, routing, signoff
Post-Silicon Debug and Validation: What happens when the chip comes back from the foundry

Previous: Article 09 -- Hardware Description Languages | Next: Article 11 -- HW/SW Co-Design

AMBA low power interface: Q-Channel and P-Channel explained

2026-05-19T00:00:00+01:00

Modern System on Chip (SoC) designs contain dozens of independent IP blocks, each drawing power even when inactive. The AMBA (Advanced Microcontroller Bus Architecture) Low Power Interface (LPI) provides every block with a standardized handshake protocol to coordinate safe clock and power removal. This post covers both LPI interface types, Q-Channel and P-Channel, with timing diagrams and state machines drawn from the ARM IHI0068 specification.

Why low-power handshaking matters

Every IP block on a System on Chip (SoC) draws power even when it sits idle. Clock gating and power gating are the primary tools for reducing that static power drain. Clock gating stops the clock to a block without removing its power rail. Power gating removes the power rail entirely for deeper power savings. Both techniques corrupt internal state if the controller applies them while the block has outstanding transactions or unflushed pipelines. A handshake protocol requires the block to signal that it has finished all activity before the controller removes its clock or power. Without this handshake, the controller has no reliable way to determine whether gating is safe.

Signal naming conventions

AMBA (Advanced Microcontroller Bus Architecture) LPI (Low Power Interface) uses a consistent naming scheme across all its interfaces. Understanding this scheme makes signal tables and timing diagrams much easier to read.

Active-level suffixes

Signals with an n suffix are active low: the signal is asserted when driven to logic 0. QREQn (quiescence request) is active when its value is 0, meaning the controller is requesting quiescence. Driving it to 1 deasserts the request. Signals without an n suffix are active high: QDENY is asserted when its value is 1, meaning the device is denying the request.

Width notation

Multi-bit signals carry a width specifier in brackets. PSTATE[M-1:0] is M bits wide, where M is implementation defined. PACTIVE[N-1:0] is N bits wide, with one bit per monitored power domain. Single-bit signals carry no width notation.

Parity check suffix

Issue D of IHI0068 introduced optional parity protection. Each primary signal gains a companion check signal with the CHK suffix. QREQn pairs with QREQCHK, and QACCEPTn pairs with QACCEPTCHK. Each check signal carries the odd parity of its primary signal, so the XOR of a signal and its check signal is always 1 when no fault is present.

Q-Channel: the quiescence handshake

Q-Channel (Quiescence Channel) handles the most common low-power scenario: safely stopping a device so the controller can gate its clock or power. It evolved from the AXI Low Power Interface signals CSYSREQ, CSYSACK, and CACTIVE, and remains backward compatible with AXI LPI devices when QDENY is absent.

Q-Channel signals

Q-Channel uses four signals. The controller drives QREQn; the device drives the remaining three.

Signal	Direction	Active level	Description	Introduced
`QREQn`	Controller to device	LOW	Requests the device to quiesce	IHI0068 B
`QACCEPTn`	Device to controller	LOW	Device has quiesced; clock or power gating is safe	IHI0068 B
`QDENY`	Device to controller	HIGH	Device cannot quiesce at this time	IHI0068 B
`QACTIVE`	Device to controller	HIGH	Device has pending activity	IHI0068 B

The specification requires QREQn to be register-driven at the controller. QACCEPTn and QDENY must be register-driven at the device. QACTIVE can be a combinational OR of internal activity signals.

Q-Channel state machine

The Q-Channel defines 6 legal states. The values of QREQn, QACCEPTn, and QDENY determine the current state entirely. Two paths exist: an accepted path where the device quiesces, and a denied path where the device refuses and the controller withdraws.

The state table lists every legal combination and the corresponding device status:

State	`QREQn`	`QACCEPTn`	`QDENY`	Device status
Q_RUN	1	1	0	Operational
Q_REQUEST	0	1	0	Draining activity; quiescence requested
Q_STOPPED	0	0	0	Quiescent; clock or power gating is safe
Q_EXIT	1	0	0	Restoring clock or power (implementation-defined delay)
Q_DENIED	0	1	1	Device denied the request; remains operational
Q_CONTINUE	1	1	1	Controller deasserted `QREQn` after denial

The combination QACCEPTn=0, QDENY=1 is illegal and must never occur.

Accepted handshake

The accepted path runs from Q_RUN through Q_REQUEST, Q_STOPPED, and Q_EXIT and back to Q_RUN. The controller asserts QREQn low to start the handshake. The device drains its outstanding activity, drops QACTIVE, then asserts QACCEPTn low to confirm it is quiescent. The controller can gate the clock or power during Q_STOPPED. When the controller is ready to restore the device, it deasserts QREQn high, entering Q_EXIT. The device responds by deasserting QACCEPTn high once it detects the restored clock, returning to Q_RUN.

Denied handshake

The denied path branches from Q_REQUEST when the device cannot quiesce. The device asserts QDENY high while keeping QACCEPTn high, entering Q_DENIED. The controller must withdraw its request by deasserting QREQn high, entering Q_CONTINUE. The device then deasserts QDENY low, and both sides return to Q_RUN. The controller can reattempt the request after it observes Q_RUN.

Handshake transition rules

The IHI0068 specification defines strict conditions for each signal transition. These rules prevent illegal states from being reached.

QREQn rules:

QREQn can fall only when QACCEPTn is HIGH and QDENY is LOW (the interface is in Q_RUN).
QREQn can rise when both QACCEPTn and QDENY are LOW (Q_STOPPED), or both are HIGH (Q_CONTINUE).

QACCEPTn rules:

QACCEPTn can fall only when QREQn is LOW and QDENY is LOW.
QACCEPTn can rise only when QREQn is HIGH and QDENY is LOW.

QDENY rules:

QDENY can rise only when QREQn is LOW and QACCEPTn is HIGH.
QDENY can fall only when QREQn is HIGH and QACCEPTn is HIGH.

P-Channel: multi-state power transitions

P-Channel (Power Channel) handles power management for devices that support multiple distinct power states. Each state can have different voltages, clock frequencies, and retention configurations. Use P-Channel when Q-Channel's binary run-stop model is insufficient for the power architecture. P-Channel communicates the target state directly to the device through an implementation-defined PSTATE encoding, rather than an implicit quiesce signal.

P-Channel signals

P-Channel uses 5 signals. The controller drives PSTATE and PREQ; the device drives PACTIVE, PACCEPT, and PDENY.

Signal	Direction	Active level	Width	Description	Introduced
`PACTIVE[N-1:0]`	Device to controller	HIGH	N bits	Device activity indication; one bit per domain	IHI0068 B
`PSTATE[M-1:0]`	Controller to device	--	M bits	Target power state (implementation defined)	IHI0068 B
`PREQ`	Controller to device	HIGH	1 bit	Power state transition request	IHI0068 B
`PACCEPT`	Device to controller	HIGH	1 bit	Device accepts the requested transition	IHI0068 B
`PDENY`	Device to controller	HIGH	1 bit	Device denies the requested transition	IHI0068 B

PREQ and PSTATE must be register-driven at the controller. PACCEPT and PDENY must be register-driven at the device. The PSTATE encoding is implementation defined; ARM publishes recommended values in the Power Policy Unit Specification. Only one of PACCEPT or PDENY changes per handshake transition.

P-Channel state machine

The P-Channel defines 6 states, determined by the values of PREQ, PACCEPT, and PDENY. The normal path transitions from P_STABLE through P_REQUEST and P_ACCEPT before returning to P_STABLE. The denied path branches from P_REQUEST and returns via P_CONTINUE.

State	`PREQ`	`PACCEPT`	`PDENY`	Description
P_STABLE	0	0	0	Idle; device is in its current power state
P_REQUEST	1	0	0	Controller requests a transition to `PSTATE`
P_ACCEPT	1	1	0	Device accepts; transition is in progress
P_COMPLETE	0	1	0	Controller deasserts `PREQ`; transitional state
P_DENIED	1	0	1	Device denies the requested transition
P_CONTINUE	0	0	1	Controller returns `PREQ` low after denial; transitional state

Accepted transition

The controller sets PSTATE to the target state before asserting PREQ high. The device samples PSTATE when it detects PREQ rising. When the device is ready to transition, it asserts PACCEPT high. The controller responds by deasserting PREQ low, entering P_COMPLETE. When the transition completes, the device deasserts PACCEPT low and both sides return to P_STABLE.

Denied transition

If the device cannot accept the requested transition, it asserts PDENY high instead of PACCEPT. The controller must respond by deasserting PREQ low, entering P_CONTINUE. The device then deasserts PDENY low, and both sides return to P_STABLE. The controller can reattempt the transition with the same or a different PSTATE value.

Choosing between Q-Channel and P-Channel

Q-Channel covers the majority of clock gating and simple power gating use cases. P-Channel is appropriate when a device supports multiple defined power states that require explicit enumeration. The ARM recommendation is to use Q-Channel where it is sufficient and to introduce P-Channel only for IP blocks with complex power policies.

Criterion	Q-Channel	P-Channel
Number of power states	2: run or quiescent	Many; implementation defined
Target state communicated to device	None; quiescence is implicit	Via `PSTATE` encoding
Backward compatible with AXI Low Power Interface (LPI)	Yes (without `QDENY`)	No
Complexity	Low	Higher
Typical use	Clock gating, simple power gating	Retention states, multi-voltage domains, complex power policy

Parity protection: Issue D additions

Issue D of IHI0068 (published September 2021) added optional parity protection to both Q-Channel and P-Channel. Each primary signal gains a companion check signal with a CHK suffix. For example, QREQn pairs with QREQCHK, and QACCEPTn pairs with QACCEPTCHK. Each check signal carries the odd parity of its primary signal, so the XOR of any signal and its check signal equals 1 when no fault is present. Parity protection is optional; systems without fault-detection requirements can omit the check signals.

Q-Channel parity signals

Primary signal	Check signal	Direction
`QREQn`	`QREQCHK`	Controller to device
`QACCEPTn`	`QACCEPTCHK`	Device to controller
`QDENY`	`QDENYCHK`	Device to controller
`QACTIVE`	`QACTIVECHK`	Device to controller

P-Channel parity signals

Primary signal	Check signal	Direction
`PACTIVE[N-1:0]`	`PACTIVECHK[N-1:0]`	Device to controller
`PSTATE[M-1:0]`	`PSTATECHK[M-1:0]`	Controller to device
`PREQ`	`PREQCHK`	Controller to device
`PACCEPT`	`PACCEPTCHK`	Device to controller
`PDENY`	`PDENYCHK`	Device to controller

Backward compatibility with AXI LPI

AXI Low Power Interface (LPI) predates IHI0068 and uses three signals: CSYSREQ, CSYSACK, and CACTIVE. Q-Channel is the direct replacement and maps to these signals as follows:

AXI LPI signal	Q-Channel equivalent	Notes
`CSYSREQ`	`QREQn`	Controller drives both
`CSYSACK`	`QACCEPTn`	Device drives both
`CACTIVE`	`QACTIVE`	Device drives both
(none)	`QDENY`	Tie `QDENY` LOW at the controller when connecting to an AXI LPI device

When connecting a Q-Channel controller to an AXI LPI device that has no QDENY port, tie QDENY LOW at the controller. This removes the denied path and reduces the interface to the backward-compatible subset.

Summary

AMBA Low Power Interface (LPI) provides two complementary handshake protocols for coordinating safe clock and power gating on System on Chip (SoC) designs. Q-Channel handles run-stop quiescence with 4 signals and 6 states, making it well suited to clock gating and straightforward power gating. P-Channel handles multi-state power transitions where the controller communicates the target state directly using an implementation-defined PSTATE encoding. Both interfaces follow strict transition rules to prevent illegal states. Issue D of IHI0068 added optional parity check signals to both interfaces for functional safety applications. The full specification is available from the ARM Documentation Service as IHI0068D.

SoC Article 09: Hardware Description Languages and RTL Design

2026-05-01T00:00:00+01:00

Series: Introduction to SoC Design | Article 9 of 11

Introduction

Hardware does not appear from nowhere. Before manufacturing a single transistor, engineers must describe the behaviour of a System-on-Chip (SoC). They use a language that both humans and tools can process: simulating, verifying, and ultimately synthesising the design into real logic gates.

Hardware Description Languages (HDLs) are that language. They look superficially like programming languages. In reality they describe hardware: circuits that exist and operate in parallel, not sequential lists of instructions. Understanding this distinction is the single most important step in learning HDL design.

The fundamental difference: parallelism

In a software program, statements execute one after another:

# Software: sequential execution
a = read_sensor()
b = process(a)
c = output(b)      # c is calculated AFTER b is calculated

In hardware, all blocks of logic are always active simultaneously. Every combinational logic path is constantly computing its output from its inputs, every clock edge triggers every flip-flop at once:

// Hardware: everything runs concurrently
// All these assignments happen in PARALLEL, every clock cycle
always_ff @(posedge clk) begin
    reg_a <= input_a;      // This flip-flop samples input_a
    reg_b <= reg_a + 1;    // This flip-flop samples reg_a + 1
    reg_c <= reg_b << 2;   // This flip-flop samples reg_b shifted left
end
// All three updates happen simultaneously on every rising clock edge

This parallel nature is what makes hardware description language (HDL) design difficult for software engineers at first: there is no "sequence of operations". There is a network of logic gates and registers, all computing simultaneously.

The two major HDLs: Verilog and VHDL

The industry is divided between two hardware description languages (HDLs), both established in the 1980s and both standardised by the Institute of Electrical and Electronics Engineers (IEEE):

Verilog: C-like syntax, concise, originally designed for simulation. Extended into SystemVerilog (IEEE 1800), which adds object-oriented programming (OOP) features, assertions, and randomised verification constructs.

VHDL (VHSIC Hardware Description Language): Ada-like syntax, strongly typed, verbose. Historically dominant in Europe, aerospace, and defence.

For this series, examples use SystemVerilog for hardware design and VHDL where instructive for comparison. The concepts are identical.

RTL vs behavioural vs structural

Hardware description language (HDL) code can be written at different levels of abstraction:

Structural: instantiate specific gates and connect them with wires:

// Structural: instantiate specific primitives
and_gate U0 (.a(in_a), .b(in_b), .y(wire_and));
or_gate  U1 (.a(wire_and), .c(in_c), .y(out));

Behavioural: describe what the circuit does:

// Behavioural: synthesis tool decides the gates
assign out = (in_a & in_b) | in_c;

Register transfer level (RTL): explicit registers and data paths:

// RTL: explicit registers and data paths
always_ff @(posedge clk or negedge rst_n) begin
    if (!rst_n)   data_reg <= '0;
    else          data_reg <= data_in;
end
assign data_out = data_reg + offset;

SystemVerilog key constructs

Modules

The module is the fundamental building block: equivalent to a function or class in software, but representing a hardware block with defined ports:

module adder #(
    parameter WIDTH = 8          // configurable width
) (
    input  logic [WIDTH-1:0] a,
    input  logic [WIDTH-1:0] b,
    input  logic             cin,
    output logic [WIDTH-1:0] sum,
    output logic             cout
);
    assign {cout, sum} = a + b + cin;
endmodule

Modules are instantiated to create the structural hierarchy of a SoC:

module alu (
    input  logic [31:0] src_a, src_b,
    input  logic [3:0]  op,
    output logic [31:0] result,
    output logic        zero
);
    logic [31:0] add_result;
    logic        add_carry;

    adder #(.WIDTH(32)) u_adder (
        .a    (src_a),
        .b    (src_b),
        .cin  (1'b0),
        .sum  (add_result),
        .cout (add_carry)
    );

    always_comb begin
        case (op)
            4'b0000: result = add_result;          // ADD
            4'b0001: result = src_a - src_b;       // SUB
            4'b0010: result = src_a & src_b;       // AND
            4'b0011: result = src_a | src_b;       // OR
            4'b0100: result = src_a ^ src_b;       // XOR
            4'b0101: result = src_a << src_b[4:0]; // SLL
            default: result = '0;
        endcase
        zero = (result == '0);
    end
endmodule

Sequential Logic: always_ff

The always_ff block describes registers. It executes on every rising (or falling) clock edge:

// 8-entry FIFO with synchronous read and write
module fifo8 (
    input  logic       clk, rst_n,
    input  logic [7:0] wdata,
    input  logic       wen, ren,
    output logic [7:0] rdata,
    output logic       full, empty
);
    logic [7:0] mem [0:7];
    logic [2:0] wptr, rptr;
    logic [3:0] count;

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            wptr  <= '0;
            rptr  <= '0;
            count <= '0;
        end else begin
            if (wen && !full) begin
                mem[wptr] <= wdata;
                wptr      <= wptr + 1'b1;
                count     <= count + 1'b1;
            end
            if (ren && !empty) begin
                rptr  <= rptr + 1'b1;
                count <= count - 1'b1;
            end
        end
    end

    assign rdata = mem[rptr];
    assign full  = (count == 4'd8);
    assign empty = (count == 4'd0);
endmodule

Combinational Logic: always_comb

The always_comb block describes purely combinational logic: it re-evaluates whenever any of its inputs change:

// Priority encoder: find the index of the highest-priority set bit
module priority_enc (
    input  logic [7:0] req,
    output logic [2:0] grant_id,
    output logic       valid
);
    always_comb begin
        valid    = |req;
        grant_id = '0;
        if      (req[7]) grant_id = 3'd7;
        else if (req[6]) grant_id = 3'd6;
        else if (req[5]) grant_id = 3'd5;
        else if (req[4]) grant_id = 3'd4;
        else if (req[3]) grant_id = 3'd3;
        else if (req[2]) grant_id = 3'd2;
        else if (req[1]) grant_id = 3'd1;
        else             grant_id = 3'd0;
    end
endmodule

Finite state machines in RTL

The Finite State Machine (FSM) is one of the most important patterns in digital design. An FSM transitions between a finite set of states based on inputs and the current state. Each state produces outputs based on that state.

Example: simple UART receiver FSM

A universal asynchronous receiver/transmitter (UART) receiver reads serial data one bit at a time. The FSM below controls the bit sampling and framing logic:

typedef enum logic [1:0] {
    IDLE  = 2'b00,
    START = 2'b01,
    DATA  = 2'b10,
    STOP  = 2'b11
} uart_state_t;

module uart_rx (
    input  logic       clk, rst_n,
    input  logic       rx,
    output logic [7:0] data,
    output logic       valid
);
    uart_state_t state;
    logic [2:0]  bit_cnt;
    logic [7:0]  shift_reg;

    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            state     <= IDLE;
            bit_cnt   <= '0;
            shift_reg <= '0;
            valid     <= 1'b0;
        end else begin
            valid <= 1'b0;
            case (state)
                IDLE:  if (!rx)            state <= START;
                START: begin
                    bit_cnt <= '0;
                    state   <= DATA;
                end
                DATA: begin
                    shift_reg <= {rx, shift_reg[7:1]};
                    if (bit_cnt == 3'd7) state <= STOP;
                    else                 bit_cnt <= bit_cnt + 1'b1;
                end
                STOP: begin
                    if (rx) begin
                        data  <= shift_reg;
                        valid <= 1'b1;
                    end
                    state <= IDLE;
                end
            endcase
        end
    end
endmodule

The corresponding state diagram:

Simulation and testbenches

Hardware description language (HDL) code is verified by simulation: running the design against a set of inputs (a testbench) and checking the outputs.

A testbench is not synthesisable. Its job is to: 1. Instantiate the DUT (Device Under Test). 2. Generate stimulus (clock, inputs). 3. Check outputs against expected values. 4. Report pass/fail.

`timescale 1ns/1ps
module tb_counter;
    logic       clk, rst_n, en;
    logic [3:0] count;

    counter #(.WIDTH(4)) dut (.*);

    initial clk = 0;
    always #5 clk = ~clk;

    initial begin
        rst_n = 0; en = 0;
        @(posedge clk); #1;
        rst_n = 1;
        @(posedge clk); #1;
        en = 1;
        repeat(20) @(posedge clk);
        en = 0;
        repeat(5) @(posedge clk);

        if (count !== 4'd4)
            $error("FAIL: expected 4, got %0d", count);
        else
            $display("PASS");
        $finish;
    end

    initial begin
        $dumpfile("counter_tb.vcd");
        $dumpvars(0, tb_counter);
    end
endmodule

SystemVerilog assertions

Assertions are formal, self-checking properties embedded directly in the design or testbench using SystemVerilog Assertions (SVA). They check that the hardware obeys its specification throughout simulation.

// Assert: write enable must not be asserted when full
property no_overflow;
    @(posedge clk) disable iff (!rst_n)
    (full |-> !wen);
endproperty
assert property (no_overflow)
    else $error("FIFO overflow attempted!");

// Assert: data must be stable while valid and not yet consumed
property data_stable;
    @(posedge clk) disable iff (!rst_n)
    (valid && !ready) |=> $stable(data);
endproperty
assert property (data_stable)
    else $error("Data changed while valid/!ready");

// Cover: verify the full condition is exercised in tests
cover property (@(posedge clk) full);

Assertions serve as executable specifications: they document intended behaviour and catch violations automatically during simulation.

Common RTL pitfalls

Unintended Latches

If a case or if statement in always_comb does not cover all possible input combinations, synthesis infers a latch: level-sensitive storage that was not intended:

// BAD: missing default -> inferred latch on 'out'
always_comb begin
    case (sel)
        2'b00: out = a;
        2'b01: out = b;
        // 2'b10 and 2'b11 not covered -> LATCH!
    endcase
end

// GOOD: add default assignment before the case
always_comb begin
    out = '0;
    case (sel)
        2'b00: out = a;
        2'b01: out = b;
    endcase
end

Simulation-Synthesis Mismatch

Some SystemVerilog constructs simulate differently from how they synthesise. initial blocks, delays (#100), and complex data types exist only for simulation and are ignored or unsupported during synthesis. Always verify that RTL synthesises to the intended hardware, not just simulates correctly.

The synthesis step

Synthesis transforms register transfer level (RTL) code into a gate-level netlist: a description in terms of actual standard cells (AND, OR, flip-flop, multiplexer cells) from a technology library.

The synthesis tool reads the RTL plus a constraints file (.sdc) that specifies the target clock frequency and I/O timing budgets, then maps to whatever cell library the target process provides.

Summary

Hardware description languages (HDLs) are the foundation of SoC design. SystemVerilog and VHDL describe digital logic at the register transfer level (RTL): specifying registers and the combinational logic that transfers data between them. The key mental model shift from software is parallelism: all RTL executes simultaneously, not sequentially. Modules provide the structural hierarchy for building large designs from smaller, verifiable blocks. Finite state machines (FSMs) are a core design pattern for controlling sequential behaviour. Simulation and assertions verify correctness before committing to silicon. Synthesis transforms RTL into gate-level hardware.

Fretboard Diagrams in Pelican

2026-04-25T00:00:00+01:00

For a long time my guitar diagrams lived on paper -- annotated chord boxes and scale grids scribbled in notebooks. When it came to writing them up digitally I found the process time consuming and the results inconsistent: different posts would use different styles, sizes, or notation conventions with no easy way to keep them in sync. This post introduces pelican-fretboard, a plugin that renders chord charts, scale boxes, and tab directly from fenced code blocks in Markdown. Diagrams are generated as SVGs, cached on disk, and served as static files -- nothing to install on the reader's side.

The plugin uses fretdrom as its rendering engine. Fretdrom takes JSON5 input -- the same wavedrom-style philosophy of a single top-level key determining diagram type -- and emits clean SVG. Blocks use the fretdrom language identifier in Markdown fences.

The problem with ASCII diagrams

The classic way to notate a chord in plain text looks like this:

E Major

e ---0---
B ---0---
G ---1---
D ---2---
A ---2---
E ---0---

Fingers: - 2 3 1 - -

It works, but it is fragile to copy-paste, hard to scan at a glance, and carries no colour or visual hierarchy to distinguish the root note from the rest of the chord.

Chord diagrams

The plugin renders a fretdrom block with a chord key into a standard box diagram. The frets string runs low string to high (E A D G B e for standard tuning). x means muted, 0 is open, 1-9 are fret numbers.

Fingers view

Add a fingers string and each fretted dot shows the finger number. - means no label:

```fretdrom
{ chord: { name: "E Major", frets: "022100", fingers: "-231--" } }
```

Open strings show a small circle above the nut; the first fret is drawn as a thicker nut line.

Intervals view

Supply an intervals array instead and each dot shows its interval relative to the root. When intervals is present the subtitle automatically shows Intervals:

```fretdrom
{ chord: { name: "E Major", frets: "022100", intervals: ["R", "5", "R", "3", "5", "R"] } }
```

Comparing fingers and intervals views of the same chord makes it easy to see which finger lands on which interval -- useful when discussing voicings or substitutions.

A seventh chord

G7 is a good test because it includes four distinct intervals. The intervals view makes the b7 on the high e string immediately visible:

```fretdrom
{ chord: { name: "G7", frets: "320001", intervals: ["R", "5", "3", "R", "5", "b7"] } }
```

The same shape in fingers mode:

```fretdrom
{ chord: { name: "G7", frets: "320001", fingers: "32---1" } }
```

Barre chords

The barre key draws the barre bar. from_string and to_string are 1-indexed, low string to high:

```fretdrom
{ chord: {
  name: "F Major (barre)",
  frets: "112331",
  fingers: "112341",
  root_strings: [1, 6],
  barre: { fret: 1, from_string: 1, to_string: 6 }
}}
```

Scale diagrams

The scale key renders a fretboard grid. grid is an array of rows, one per string (low E first), each row an array of cell values. "R" = root, "x" = scale note, "." = empty.

```fretdrom
{ scale: {
  name: "A Minor Pentatonic",
  start_fret: 5,
  num_frets: 5,
  grid: [
    ["R", ".", ".", "x", "."],
    ["x", ".", "x", ".", "."],
    ["x", ".", "R", ".", "."],
    ["x", ".", "x", ".", "."],
    ["x", ".", ".", "x", "."],
    ["R", ".", ".", "x", "."]
  ]
}}
```

Fret numbers are shown on the left so the position on the neck is always clear. Cell values other than R, x, and . are treated as interval labels and rendered inside the dot.

Tab

The tab key takes an array of string lanes, highest string first (standard tab order). Each lane has a name and a wave string where each character is one beat: . is an empty beat (dash), 0-9 are fret numbers. config.bar draws bar lines every N beats:

```fretdrom
{ name: "E String Blues Riff",
  tab: [
    { name: "e", wave: "................" },
    { name: "B", wave: "................" },
    { name: "G", wave: "................" },
    { name: "D", wave: "................" },
    { name: "A", wave: "................" },
    { name: "E", wave: "0..3.5.3..0....." }
  ],
  config: { bar: 8 }
}
```

Any fretted instrument

Set tuning to match your instrument and the string count adjusts automatically:

```fretdrom
{ chord: { name: "E (bass)", tuning: "EADG", frets: "0221", fingers: "-231", root_strings: [1] } }
```

The same syntax works for ukulele (GCEA), five-string bass (BEADG), mandola (GDAE), or any open tuning.

How it works

The plugin registers a Markdown preprocessor that intercepts fretdrom fenced blocks before they reach the syntax highlighter. Each block is parsed as JSON5 and passed to the fretdrom CLI, which returns an SVG on stdout. The SVG is saved to content/images/fretboard/ using an MD5 hash of the block content as the filename. The fenced block is replaced inline with a Markdown image reference. The SVG cache persists across make clean -- diagrams are only regenerated when their source content changes.

If the fretdrom binary is not found the block falls back to a json5 code block so the build never fails.

Source and installation instructions are at github.com/morganp/pelican-fretboard.

SoC Article 08: Peripherals and I/O - Connecting the SoC to the world

2026-04-24T00:00:00+01:00

Series: Introduction to SoC Design | Article 8 of 11

Introduction

A System-on-Chip (SoC) without input/output (I/O) is a black box. No matter how powerful its central processing units (CPUs) or how fast its memory, it has no way to receive information from the world or send results back out. Peripherals are the hardware blocks that bridge the gap between the digital logic inside the chip and the physical world outside it: sensors, displays, storage, networks, and human interfaces.

This article surveys the most common peripheral types found in SoCs, explains the protocols they use, and shows how they connect to the rest of the chip.

The peripheral landscape

Peripherals vary enormously in bandwidth, latency, and complexity:

GPIO

General-purpose input/output (GPIO) is the simplest peripheral: a set of pins that can be individually configured as either digital inputs or digital outputs, under software control.

GPIO pins on modern SoCs are typically multiplexed: the same physical pin can serve as GPIO or as a dedicated function for a peripheral like UART or SPI. The IOMUX (I/O multiplexer) hardware block selects which function a pin serves:

UART

Universal Asynchronous Receiver/Transmitter (UART) is the oldest and simplest serial communication protocol. It is asynchronous (no shared clock between sender and receiver) and full-duplex (simultaneous send and receive on separate wires).

UART frame format

A UART frame consists of: start bit, 7-9 data bits, optional parity bit, and 1-2 stop bits.

The receiver samples the line at 16x the baud rate to detect the start bit edge, then samples each data bit at the midpoint of its period. Both sides must be configured to the same baud rate (for example, 115200 bps).

UARTs serve primarily as debug consoles: they are the primary serial debug output tool in embedded systems. Almost every SoC has at least one UART that provides a serial terminal during boot.

SPI

Serial Peripheral Interface (SPI) is a synchronous serial protocol where the master provides the clock. It is designed for short-distance communication between a SoC and peripheral ICs such as flash memory, sensors, digital-to-analogue converters (DACs), and displays.

SPI signals

SPI timing

SPI supports four modes based on CPOL (clock polarity) and CPHA (clock phase), enabling compatibility with different devices. Most flash memories and sensors use Mode 0 or Mode 3.

SPI has no addressing scheme: the chip select line selects the target device. Multiple slaves require one CS line per slave. Quad-SPI (QSPI) uses four data lines instead of one, quadrupling throughput.

I2C

Inter-Integrated Circuit (I2C) is a two-wire synchronous protocol supporting multiple masters and multiple slaves on the same bus. It uses 7-bit or 10-bit addressing to select which device a transaction targets.

I2C signals

I2C transaction format

The START condition (SDA falls while SCL is high) begins every transaction. The master sends 7 address bits and an R/W bit, then waits for an ACK: the addressed slave pulls SDA low for one clock cycle. Data bytes follow, each acknowledged by the receiver.

I2C standard speeds are 100 kHz (standard), 400 kHz (fast), 1 MHz (fast-plus), and 3.4 MHz (high-speed). Common uses include temperature sensors, inertial measurement units (IMUs), power management ICs (PMICs), cameras, electrically erasable programmable read-only memory (EEPROM), and displays.

USB

Universal Serial Bus (USB) is the dominant PC-to-peripheral protocol, and is increasingly common on embedded SoCs. A complete USB implementation includes:

USB PHY (Physical Layer): analog front-end handling differential signalling
USB controller and IP stack: protocol stack implementation (USB 2.0 at 480 Mb/s, USB 3.x up to 20 Gb/s)
USB hub and root hub logic: in host-mode SoCs

USB 2.0 uses a tiered star topology with a single host, supporting 127 devices. USB communication is always host-initiated: a device can never spontaneously send data. It must wait to be polled or for the host to grant a transfer.

USB transfers are classified into four types:

Transfer Type	Description	Use Case
Control	Enumeration, configuration	Device setup
Bulk	Large data, guaranteed delivery	Storage (USB flash)
Interrupt	Small, time-bounded data	Human Interface Device (HID): mouse, keyboard
Isochronous	Time-sensitive, no retry	Audio, video streaming

USB 3.x adds SuperSpeed lanes with a completely different physical layer, using 128b/132b coding instead of 8b/10b and separate TX and RX differential pairs. It maintains backward compatibility with USB 2.0.

Ethernet MAC

Ethernet connectivity requires two hardware blocks:

MAC (Media Access Control): implements the Ethernet frame format, collision detection (for legacy half-duplex), flow control, and first-in first-out (FIFO) buffer management. The MAC lives on-chip.

PHY (Physical Layer): converts between the digital MAC signals and the analog signals on the twisted-pair cable. The PHY is usually a separate chip, connected to the MAC via the Reduced Gigabit Media Independent Interface (RGMII) or Serial Gigabit Media Independent Interface (SGMII).

The MAC operates as a DMA master: when a packet arrives, the MAC's DMA engine writes it to a pre-allocated buffer in dynamic RAM (DRAM) and signals the CPU via interrupt. Outgoing packets are described by descriptors pointing to DRAM buffers, and the MAC fetches and transmits them independently.

DMA controller

Almost all high-bandwidth peripherals include or connect to a Direct Memory Access (DMA) engine. DMA enables peripherals to transfer large blocks of data to and from memory without the central processing unit (CPU) processing every byte.

DMA is essential for audio streaming, video capture, USB bulk transfers, UART high-speed data, and anything involving moving more than a few bytes at a time.

Interrupt controller

Peripherals signal the CPU when they need attention using interrupts: electrical signals that cause the CPU to pause its current task and run an Interrupt Service Routine (ISR). The CPU saves its state before the ISR runs and restores it afterwards.

A SoC may have dozens of interrupt sources (UART received a byte, SPI transfer complete, GPIO edge, timer expired, DMA done). The interrupt controller collects these signals, prioritises them, and presents the highest-priority pending interrupt to the CPU.

ARM's GIC (Generic Interrupt Controller) is the standard interrupt controller for Cortex-A SoCs. It supports up to 1020 interrupt sources and 8 priority levels. It can also target interrupts to specific CPU cores, which is useful for load balancing in multi-core systems.

Timer and watchdog

Timers are counter circuits that count clock cycles and generate an interrupt when they reach a preset value. They are used for:

Operating system (OS) tick (for example, 1 ms for task scheduling)
PWM generation (Pulse Width Modulation for motor control, LEDs)
Capture (measuring pulse widths on GPIO inputs)
Timeouts

A watchdog timer is a specific timer that firmware must periodically reset. If the firmware crashes or hangs, the watchdog expires and resets the entire system: essential for reliable embedded operation.

Summary

Peripherals are the interface between a SoC and the physical world. GPIO provides flexible single-bit I/O. Serial protocols like UART, SPI, and I2C provide low-to-medium bandwidth connections to sensors and devices. USB provides standardised high-speed connectivity to external devices. Ethernet connects the SoC to networks. DMA engines free the CPU from data movement tasks. The interrupt controller efficiently manages asynchronous events from all these sources. Together, these blocks are what allow a SoC to run in a real product.

SoC Article 07: Clocking, Reset, and Power Domains

2026-04-18T00:00:00+01:00

Series: Introduction to SoC Design | Article 7 of 11

Introduction

Every digital circuit needs a clock: a periodic signal that synchronises all the flip-flops in a System-on-Chip (SoC), causing them to sample their inputs and update their outputs in a coordinated fashion. Designing, distributing, and managing the clock is an entire sub-discipline of SoC engineering.

Reset places a chip in a known initial state. Power management dynamically controls which blocks are active and at what voltage. Both are critical infrastructure topics that every SoC designer must understand.

Why clocking is hard

Generating a clock signal that oscillates at a precise frequency seems straightforward. The real challenge is delivering that signal to millions of flip-flops distributed across a die that may be 100 mm² or larger, all arriving at exactly the same time (to within picoseconds), despite:

Wire resistance and capacitance: signals are delayed differently depending on path length.
Process variation: transistors at different corners of the die behave slightly differently.
Temperature gradients: hot areas near power-hungry cores have slower transistors.
Voltage droop: areas with high switching activity momentarily drop in supply voltage.

This collection of problems is called clock skew (spatial variation) and clock jitter (temporal variation). Both reduce the timing margin available for logic between flip-flops.

The clock distribution tree

The solution is a carefully engineered clock tree: a hierarchical network of buffers that distributes the clock signal from a single source to all destinations. Engineers size each branch so that all paths have approximately equal delay.

All paths from source to leaf flip-flops are equal length, giving equal delay and low skew.

Clock tree synthesis (CTS) is an automated step in the physical design flow that constructs this tree. It is one of the most critical steps in achieving timing closure.

Phase-locked loops

SoCs do not use their raw crystal oscillator frequency (typically 24--100 MHz from an external crystal) directly. Instead, a phase-locked loop (PLL) multiplies and divides this reference to generate the precise frequencies needed by each subsystem.

Output frequency = Ref × (N/M) where N and M are programmable dividers.

A PLL is an analog circuit embedded in the otherwise digital SoC. Its output frequency is controlled by a digital divider, but the loop filter and VCO (Voltage-Controlled Oscillator) are analog. This makes PLLs sensitive to supply noise: they have their own isolated power supply on-chip.

A typical large SoC has 4--12 PLLs: - Central processing unit (CPU) PLL (0.8--3.5 GHz) - Graphics processing unit (GPU) PLL - Double data rate (DDR) PLL (matched to dynamic RAM (DRAM) frequency) - Peripheral PLL (100--400 MHz for buses) - Universal Serial Bus (USB) and PCI Express (PCIe) PLLs (specific protocol reference frequencies)

Multiple clock domains

Different parts of a SoC operate at different frequencies, and often from different clocks. A clock domain is a group of flip-flops all clocked by the same source.

When data must cross from one clock domain to another, a Clock Domain Crossing (CDC) circuit is required. For example, the CPU domain and the peripheral Advanced Peripheral Bus (APB) domain run at different frequencies. Failure to handle CDCs correctly is one of the most common sources of functional bugs in SoC designs.

The metastability problem

When a flip-flop's input changes near its sampling edge, the flip-flop may enter a metastable state: neither a clean 0 nor a clean 1. If the metastable state propagates, it can corrupt data or cause unexpected behaviour.

The probability of metastability resolving correctly increases with time. A two-stage synchroniser provides enough time in most situations for resolution before the signal is used:

The two-stage synchroniser adds two destination-clock cycles of latency but reduces the probability of a metastability-induced failure to negligible levels. More complex CDCs (for multi-bit signals or first-in first-out (FIFO) buffers) use more sophisticated structures.

Reset: Getting to a known state

Reset is the mechanism that places all flip-flops in their initial, known state. Without reset, the behaviour of a digital circuit after power-up is non-deterministic. Each flip-flop powers up in either 0 or 1, but which value depends on manufacturing variation and environmental conditions. Simulation tools represent this uncertain power-up state as x (unknown). The state is definite at the hardware level but unpredictable across devices and power cycles. Reset resolves the non-determinism by driving every flip-flop to a specified, known value.

Reset sources

A SoC typically has several reset sources:

Synchronous vs asynchronous reset

Asynchronous reset: the flip-flop resets immediately when RST is asserted, regardless of the clock. Fast response, but the reset de-assertion must be synchronised to avoid metastability.

Synchronous reset: the flip-flop only resets on the next rising clock edge after RST is asserted. Requires a clean clock, but avoids de-assertion timing issues.

In practice, most SoC designs use asynchronous assert, synchronous de-assert (ASAD): the reset asserts immediately for reliability, and de-asserts through a synchroniser to prevent metastability.

Power domains and power management

A modern SoC is not a single block of silicon that is either fully on or fully off. It is divided into power domains -- regions that can be independently powered up or down. This enables enormous power savings by only energising the blocks that are currently needed.

Power states

A typical SoC power state machine:

Power gating

Power gating uses header or footer switches (large p-type (PMOS) or n-type (NMOS) transistors) to physically disconnect a domain from its supply rail, reducing leakage current to near zero:

When the block is gated off, its internal state is lost. If the state must be preserved (for example, cache contents or CPU registers), retention registers: special flip-flops with a separate, always-powered supply, save critical state before power-down.

DVFS

Dynamic Voltage and Frequency Scaling (DVFS) reduces power consumption by lowering both the supply voltage and clock frequency when full performance is not needed. Power consumption of complementary metal-oxide-semiconductor (CMOS) logic scales approximately as:

P_dynamic ≈ α × C × V² × f

Where:
  α = activity factor (fraction of gates switching per cycle)
  C = total capacitance
  V = supply voltage
  f = clock frequency

Since power scales with V², halving the voltage reduces dynamic power by 4×. Modern SoC CPUs support many operating points, and the operating system (OS) uses a DVFS governor to select the appropriate operating point based on workload.

Clock gating

A lighter-weight alternative to power gating is clock gating: stopping the clock to a region of logic. With the clock stopped, flip-flops no longer switch, and dynamic power drops to near zero (though leakage continues). Clock gating is implemented with an integrated clock gating cell (ICG):

When EN = 0, GATED_CLK is held low (no switching). When EN = 1, GATED_CLK follows CLK normally. The internal latch captures EN during the CLK=low phase, ensuring GATED_CLK transitions only at clock boundaries and never produces a glitch:

Modern synthesis tools automatically insert clock gating cells throughout the design, reducing dynamic power by 20--40% with no architect effort.

The always-on domain

Even in the deepest sleep state, some logic must remain powered. This includes the real-time clock (RTC) to wake the system at a scheduled time, the power management unit to manage power-up sequencing, and retention registers holding critical context. This collection of always-powered logic is the Always-On (AO) domain: it draws power from a supply that is never switched off while the battery is present.

Summary

Clocking, reset, and power management are the infrastructure that makes a SoC run correctly and efficiently. PLLs generate the precise, stable frequencies required by each subsystem. The clock tree distributes the clock signal with minimal skew. Clock domain crossings require careful synchronisation to prevent metastability. Reset places all logic in a known initial state, with the source and polarity carefully considered. Power domains, gating, and DVFS together reduce energy consumption dramatically, enabling always-on devices to run for days or years on a small battery.

Intermediate articles this topic connects to

Clock Domain Crossing Techniques: Metastability in depth, multi-bit CDC, async FIFOs
Power Management Techniques: DVFS, retention, power sequencing, PMU firmware
Physical Design: Floorplanning and Place-and-Route (Advanced): CTS, IR drop analysis

Previous: Article 06 -- Interconnects and Bus Protocols Next: Article 08 -- Peripherals and I/O: Connecting the SoC to the World

Proxmox: Disable root@pam Login and Create a Sudo User

2026-04-17T00:00:00+01:00

Out of the box, Proxmox VE only has the root@pam account. Logging in directly as root is convenient during initial setup, but it is a bad habit to keep. This post walks through creating a named PAM user, granting it sudo access, and then disabling root login via both SSH and the web UI.

Authentication Realms: @pam vs @pve

The @ suffix in Proxmox usernames is not cosmetic -- it identifies which authentication realm validates the password.

@pam -- Linux Pluggable Authentication Modules. Proxmox delegates the password check to the host operating system. The user must exist as a real UNIX account in /etc/passwd. Password changes happen with passwd on the shell. SSH login uses the same credentials. This is the realm for admin accounts that also need shell access.

@pve -- Proxmox Virtual Environment internal realm. Passwords are stored in Proxmox's own database (/etc/pve/priv/shadow.cfg), completely separate from the OS. The user has no UNIX account and cannot SSH in. This is the right realm for giving colleagues or tenants web UI access without touching the OS user database.

@ldap / @ad -- Optional realms for binding to an LDAP directory or Active Directory. Not covered here.

Realm	Password stored	SSH access	UNIX account required
`@pam`	Linux PAM (`/etc/shadow`)	Yes	Yes
`@pve`	Proxmox internal DB	No	No

For the admin account in this guide we use @pam because we also want sudo and SSH access.

Why Bother

Audit logs become meaningful. root in auth logs could be anyone; dave is traceable.
SSH brute-force tools target root first. Disabling it removes the most-attacked entry point.
Sudo with NOPASSWD for specific commands is still safer than a permanent root shell.

1. Install sudo

Proxmox minimal installs may not include sudo:

apt update && apt install -y sudo

2. Create the System User

useradd -m -s /bin/bash dave
passwd dave

-m creates a home directory. Set a strong password when prompted.

3. Grant sudo Access

Add dave to the sudo group, which is already configured in /etc/sudoers to allow full sudo:

usermod -aG sudo dave

To verify the group membership took effect:

id dave

You should see sudo in the groups list.

4. Register the User in Proxmox

Proxmox has its own user database separate from the Linux PAM database. The @pam realm bridges them, but you still need to add the user in the Proxmox layer.

Via the web UI: Datacenter > Permissions > Users > Add

User: dave
Realm: pam
Enable: checked

Via the CLI:

pveum user add dave@pam

5. Assign a Proxmox Role

The user needs at least one permission to do anything useful. For a full admin, assign the built-in Administrator role at the root path /:

pveum acl modify / -user dave@pam -role Administrator

For a more restricted setup, use PVEAdmin (everything except node-level config) or define a custom role.

6. Test the New Account

Before locking out root, confirm the new account works end to end:

Open a new terminal (do not close the existing root session).
SSH in as dave:

bash ssh dave@<proxmox-ip>
Confirm sudo works:

bash sudo -i
Log in to the Proxmox web UI at https://<proxmox-ip>:8006 as dave@pam.

Do not proceed to the next step until all three work.

7. Disable root SSH Login

Edit /etc/ssh/sshd_config:

sudo nano /etc/ssh/sshd_config

Find or add the following line:

PermitRootLogin no

Reload SSH without dropping existing connections:

sudo systemctl reload sshd

Verify by attempting ssh root@<proxmox-ip> -- it should now be refused.

8. Disable root@pam in the Proxmox Web UI

Even with SSH root login disabled, root@pam can still authenticate through the Proxmox web UI. To disable it:

Via the web UI: Datacenter > Permissions > Users > select root > Edit > uncheck Enable

Via the CLI:

pveum user modify root@pam --enable 0

This does not delete root or change anything at the Linux level. It only prevents login through the Proxmox authentication stack.

Note: The Linux root account remains intact. You can always recover it from the physical console or by re-enabling root@pam through the CLI as your admin user with sudo.

Verification Checklist

Check	Command	Expected Result
dave SSH login	`ssh dave@<ip>`	Login prompt
dave sudo	`sudo -i`	Root shell
dave web UI	Browser `https://<ip>:8006`	Logged in as dave@pam
root SSH blocked	`ssh root@<ip>`	Permission denied
root web UI blocked	Browser login as root@pam	Login rejected

Summary

Step	What It Does
`useradd`	Creates the Linux PAM account
`apt install sudo`	Ensures sudo is present
`usermod -aG sudo`	Grants full sudo via the sudo group
`pveum user add`	Registers the account in Proxmox
`pveum acl modify`	Assigns a Proxmox role
`PermitRootLogin no`	Blocks root SSH
`pveum user modify root@pam --enable 0`	Blocks root Proxmox web UI login

Proxmox: Setting Up a New User Account with Dotfiles

2026-04-17T00:00:00+01:00

This post follows on from Proxmox: Disable root@pam Login and Create a Sudo User. At that point you have a working dave account with sudo. The next step is making it feel like home: a few essential tools and your dotfiles pulled from GitHub.

The dotfiles repo used in this guide is morganp/dotfiles.

Two Strategies

Before diving in, it helps to understand the two ways config files are deployed. Most tools use GNU Stow, which creates symlinks from $HOME (or an XDG config dir) into the repo. A change to the repo file is immediately live everywhere that file is symlinked.

A small number of files -- shell configs and Vim -- use a source wrapper instead. ~/.zshrc is a real file that exists only on the local machine and contains a single source line pointing into the repo. This allows host-specific additions (work proxy settings, machine-specific aliases) to live below the source line without touching the shared repo file. It also prevents tools that append to .bashrc from dirtying the repo.

The split is:

File	Strategy	Reason
Most config (git, screen, ctags, ...)	Stow symlink	Identical across all hosts
`~/.zshrc`, `~/.bashrc`	Source wrapper	Host-specific additions needed
`~/.vimrc`	Source wrapper	Different plugin sets per host

Install Basic Tools

SSH in as your new user and install the essentials in one pass:

sudo apt update && sudo apt install -y git stow

gh (the GitHub CLI) is not in the standard Debian/Ubuntu repos, so it needs the official GitHub apt source:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
    | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] \
    https://cli.github.com/packages stable main" \
    | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null

sudo apt update && sudo apt install -y gh

Verify all three are present:

git --version
stow --version
gh --version

Authenticate with GitHub

Before cloning private repos, authenticate gh:

gh auth login

Select GitHub.com, then HTTPS, then Login with a web browser (or a personal access token if the host has no browser). The token is stored in ~/.config/gh/hosts.yml.

Confirm it worked:

gh auth status

Clone the Dotfiles Repository

gh repo clone morganp/dotfiles ~/dotfiles

Or with plain git over HTTPS if you skipped gh:

git clone https://github.com/morganp/dotfiles.git ~/dotfiles

Strategy 1: Apply with run_stow

The --dotfiles flag used throughout the script tells Stow to treat a file named dot-foo in the package as .foo in the target directory. This lets the repo store dotfiles without leading dots, making them visible in directory listings and avoiding accidental git ignores.

The repo ships a run_stow script that applies each package explicitly and creates any XDG config directories that may not exist yet:

cd ~/dotfiles/config
bash run_stow

Under the hood it does things like:

stow input --dotfiles -t ~/
stow screen --dotfiles -t ~/
stow ctags --dotfiles -t ~/

mkdir -p $HOME/.config/git
stow git -t $HOME/.config/git

If Stow finds a file already at the target (e.g. the default .inputrc written by the system), it will refuse to proceed and print a conflict warning. Remove or back up the conflicting file first:

mv ~/.inputrc ~/.inputrc.bak

Then re-run the script. Reload the shell once done:

exec bash

Strategy 2: Shell and Vim via Source Wrapper

The shared repo file holds config common to all hosts. Each machine's ~/.zshrc is a thin wrapper that sources the shared file first, then adds anything host-specific below:

# ~/.zshrc -- this file is NOT in the repo, it lives only on this host
source ~/dotfiles/config/shell/dot-zshrc

# host-specific additions below
export http_proxy=http://proxy.work.example.com:3128
alias backup="rsync -av /data /mnt/nas/backup"

For a work vs. home split, source a second context file or use a hostname conditional:

source ~/dotfiles/config/shell/dot-zshrc

if [[ $(hostname) == *"work"* ]]; then
    source ~/dotfiles/config/shell/dot-zshrc_work
fi

Create ~/.bashrc the same way:

# ~/.bashrc
source ~/dotfiles/config/shell/dot-bashrc

For Vim, dot-vimrc_clean is a minimal, plugin-free config well suited to servers. Create ~/.vimrc sourcing it:

" ~/.vimrc
so ~/dotfiles/config/vim/dot-vimrc_clean

The repo also contains dot-vimrc (full config with plugins) and dot-vimrc_spelling -- point ~/.vimrc at whichever suits the host. Because these wrapper files are not managed by Stow, they are not tracked by the dotfiles repo on this machine.

Verify

Check that the Stow symlinks landed:

ls -la ~/ | grep '\->'
ls -la ~/.config/git/ | grep '\->'

Check that the source wrappers are in place:

head -1 ~/.zshrc
head -1 ~/.vimrc

Both should show the source / so line pointing into ~/dotfiles/.

Any future change to a file in ~/dotfiles/ is immediately live. Commit and push from ~/dotfiles/ as normal to keep the repo in sync across hosts.

Summary

Strategy	Files	How
Stow symlink	Most config (git, screen, ctags, ...)	`bash run_stow` from `~/dotfiles/config`
Source wrapper	`~/.zshrc`, `~/.bashrc`, `~/.vimrc`	Real local file with a single `source` line

Tool	Purpose
`git`	Version control, cloning the dotfiles repo
`stow`	Symlink manager for most config packages
`gh`	GitHub CLI for authentication and repo operations

Copy and Paste in a Multi-OS System

2026-04-15T00:00:00+01:00

Working across macOS locally and a remote RHEL system through OpenText Exceed TurboX creates a clipboard shortcut mismatch. Linux applications expect Ctrl-Shift-C / Ctrl-Shift-V for copy and paste; macOS expects Cmd-C / Cmd-V. Switching mental models every time the active window changes is error-prone and slow. This post covers a setup that makes both shortcut conventions work regardless of which application is in focus.

The Problem

Context	Copy	Paste
macOS native apps	`Cmd-C`	`Cmd-V`
Linux terminal via Exceed	`Ctrl-Shift-C`	`Ctrl-Shift-V`
gVim via Exceed	`"+y`	`"+gP`

The goal is to be able to use either convention and have it work correctly -- mapping macOS shortcuts into Linux ones when Exceed is active, and mapping Linux shortcuts into macOS ones everywhere else.

eXceed Usage

Terminal Emulator

A terminal emulator running inside Exceed already supports the Linux convention natively -- no configuration is required:

Ctrl-Shift-C -- copy to system clipboard
Ctrl-Shift-V -- paste from system clipboard

gVim: Adding Ctrl-Shift-C / Ctrl-Shift-V

Vim does not use the system clipboard by default. Add the following to .vimrc to map the Linux terminal shortcuts to yank and paste from the system clipboard (+ register):

" Map Ctrl-Shift-C / Ctrl-Shift-V to system clipboard copy / paste
:map <C-S-c> "+y
:map <C-S-v> "+gP

Karabiner-Elements: Unifying the Shortcuts on macOS

Karabiner-Elements is a keyboard remapper for macOS. Two sets of rules are needed -- one for all applications except Exceed, and one for Exceed specifically.

Rule Set 1: Ctrl-Shift shortcuts outside Exceed

For every application except Exceed, map the Linux-style shortcuts to their macOS equivalents. This means pressing Ctrl-Shift-C in any native macOS app triggers Cmd-C, so the Linux muscle memory works everywhere.

The four rules (copy, paste, cut, undo):

{
    "description": "Map Ctrl+Shift+C to Copy (Cmd+C)",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_unless"
                }
            ],
            "from": {
                "key_code": "c",
                "modifiers": { "mandatory": ["control", "shift"] }
            },
            "to": [{ "key_code": "c", "modifiers": ["left_command"] }],
            "type": "basic"
        }
    ]
}

{
    "description": "Map Ctrl+Shift+V to Paste (Cmd+V)",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_unless"
                }
            ],
            "from": {
                "key_code": "v",
                "modifiers": { "mandatory": ["control", "shift"] }
            },
            "to": [{ "key_code": "v", "modifiers": ["left_command"] }],
            "type": "basic"
        }
    ]
}

{
    "description": "Map Ctrl+Shift+X to Cut (Cmd+X)",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_unless"
                }
            ],
            "from": {
                "key_code": "x",
                "modifiers": { "mandatory": ["control", "shift"] }
            },
            "to": [{ "key_code": "x", "modifiers": ["left_command"] }],
            "type": "basic"
        }
    ]
}

{
    "description": "Map Ctrl+Shift+Z to Undo (Cmd+Z)",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_unless"
                }
            ],
            "from": {
                "key_code": "z",
                "modifiers": { "mandatory": ["control", "shift"] }
            },
            "to": [{ "key_code": "z", "modifiers": ["left_command"] }],
            "type": "basic"
        }
    ]
}

Rule Set 2: Cmd shortcuts inside Exceed

When Exceed is the active application, the reverse mapping applies: Cmd-C/V/X/Z are translated into Ctrl-Shift-C/V/X/Z so they reach gVim and other Linux applications with the shortcuts they expect.

{
    "description": "Map Copy Cmd+C to Ctrl+Shift+C on Exceed",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_if"
                }
            ],
            "from": {
                "key_code": "c",
                "modifiers": { "mandatory": ["left_command"] }
            },
            "to": [{ "key_code": "c", "modifiers": ["control", "shift"] }],
            "type": "basic"
        }
    ]
}

{
    "description": "Map Paste Cmd+V to Ctrl+Shift+V on Exceed",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_if"
                }
            ],
            "from": {
                "key_code": "v",
                "modifiers": { "mandatory": ["left_command"] }
            },
            "to": [{ "key_code": "v", "modifiers": ["control", "shift"] }],
            "type": "basic"
        }
    ]
}

{
    "description": "Map Cut Cmd+X to Ctrl+Shift+X on Exceed",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_if"
                }
            ],
            "from": {
                "key_code": "x",
                "modifiers": { "mandatory": ["left_command"] }
            },
            "to": [{ "key_code": "x", "modifiers": ["control", "shift"] }],
            "type": "basic"
        }
    ]
}

{
    "description": "Map Undo Cmd+Z to Ctrl+Shift+Z on Exceed",
    "manipulators": [
        {
            "conditions": [
                {
                    "bundle_identifiers": [
                        "^com\\.OpenText\\.Exceed-TurboX-Client$"
                    ],
                    "type": "frontmost_application_if"
                }
            ],
            "from": {
                "key_code": "z",
                "modifiers": { "mandatory": ["left_command"] }
            },
            "to": [{ "key_code": "z", "modifiers": ["control", "shift"] }],
            "type": "basic"
        }
    ]
}

Result

With both rule sets in place:

Action	Outside Exceed	Inside Exceed
Copy	`Ctrl-Shift-C` or `Cmd-C`	`Ctrl-Shift-C` or `Cmd-C`
Paste	`Ctrl-Shift-V` or `Cmd-V`	`Ctrl-Shift-V` or `Cmd-V`
Cut	`Ctrl-Shift-X` or `Cmd-X`	`Ctrl-Shift-X` or `Cmd-X`
Undo	`Ctrl-Shift-Z` or `Cmd-Z`	`Ctrl-Shift-Z` or `Cmd-Z`

Both shortcut conventions work in both contexts. Switching between a macOS application and a remote RHEL session in Exceed requires no change in keyboard habit.

Managing Karabiner Configuration with Stow

Karabiner-Elements stores its configuration as JSON at ~/.config/karabiner/karabiner.json. This makes it straightforward to track in a dotfiles repository and deploy with GNU Stow.

In the dotfiles repo, place the config at config/karabiner/karabiner.json to mirror the target path. Then create the directory and stow it:

mkdir -p $HOME/.config/karabiner
stow karabiner -t $HOME/.config/karabiner

This creates a symlink from ~/.config/karabiner/karabiner.json into the dotfiles repo, so any edits made via the Karabiner-Elements UI are immediately reflected in the tracked file.

The Karabiner config for this setup is included in morganp/dotfiles.

Parametric Knob Maker for OpenSCAD

2026-04-13T00:00:00+01:00

Parametric thumbscrew knobs come up often enough in 3D printing projects that it is worth having a reusable library for them. This post covers a fork of aminGhafoory/parametric-knob-maker that adds a generalised round knob module. The fork is at morganp/parametric-knob-maker.

The library was used to generate the thumbscrew knob in the pinch rods post.

Installation

Clone or download the repository into your OpenSCAD libraries folder:

~/.local/share/OpenSCAD/libraries/     (Linux)
~/Documents/OpenSCAD/libraries/        (macOS)
My Documents\OpenSCAD\libraries\       (Windows)

The `knob()` Module

File: parametric_knob.scad

The round knob has a narrower offset base for mounting clearance, chamfered top and bottom edges, and equally-spaced cylindrical grip cutouts around the perimeter. Z=0 is at the base, making it straightforward to position on top of a screw shaft.

include <parametric-knob-maker/parametric_knob.scad>

knob(
    knob_height,       // height of the main knob body         (default: 15)
    knob_diam,         // diameter of the main knob body       (default: 30)
    offset_height,     // height of the narrower base section  (default: 5)
    offset_diam,       // diameter of the base section         (default: knob_diam/2)
    knob_chamfer,      // top edge chamfer depth at 45 deg     (default: 2)
    base_chamfer,      // base edge chamfer depth at 45 deg    (default: 1)
    num_grip_cutouts,  // number of finger grip cutouts        (default: 15)
    grip_cutout_diam,  // diameter of each grip cutout         (default: 4)
    cutout_radius_adj, // outward offset of cutout centres     (default: 1)
    knob_color         // preview colour                       (default: "red")
);

Default knob

include <parametric-knob-maker/parametric_knob.scad>
knob();

Small thumbscrew knob

Compact knob for M3/M4 screws where finger space is limited.

include <parametric-knob-maker/parametric_knob.scad>
knob(knob_height=8, knob_diam=20, offset_height=2);

Large adjustment knob

Wider knob with more cutouts for applications needing higher torque or finer control.

include <parametric-knob-maker/parametric_knob.scad>
knob(
    knob_height      = 20,
    knob_diam        = 50,
    num_grip_cutouts = 20,
    grip_cutout_diam = 6,
    knob_color       = "SteelBlue"
);

Slim base

A narrow offset base minimises the footprint on the mounting surface -- useful when the knob sits close to a panel or bracket.

include <parametric-knob-maker/parametric_knob.scad>
knob(
    knob_height   = 15,
    knob_diam     = 35,
    offset_height = 2,
    offset_diam   = 10,
    knob_color    = "DarkOrange"
);

Combining with a BOSL2 screw

The knob() module pairs neatly with BOSL2's screw() to produce a complete thumbscrew assembly. Place the screw with anchor=BOTTOM so the thread points downward, then translate the knob up to sit on top of the shaft.

include <parametric-knob-maker/parametric_knob.scad>
include <BOSL2/std.scad>
include <BOSL2/screws.scad>

THREAD_LEN = 12;

union() {
    screw(spec="M5", length=THREAD_LEN+1, thread=true, anchor=BOTTOM);
    translate([0, 0, THREAD_LEN])
        knob(knob_height=10, offset_height=1);
}

The `hex_knob()` Module

File: parametric_hex_knob.scad

The hex knob is intended to capture a hex-head bolt in its base recess and provide a through-hole for the shaft, removing the need for any additional fastener. The hex screw recess is currently under development and commented out -- the module renders the knob body and grip cutouts only.

include <parametric-knob-maker/parametric_hex_knob.scad>

hex_knob(
    knob_height,          // height of the knob body           (default: 15)
    knob_diam,            // diameter of the knob              (default: 30)
    screwhead_facetoface, // hex head face-to-face size (mm)   (default: 8)
    screwhead_depth,      // depth of hex recess               (default: 12)
    thru_hole_diam,       // through-hole diameter             (default: 4)
    num_grip_cutouts,     // number of finger grip cutouts     (default: 20)
    grip_cutout_diam,     // diameter of each grip cutout      (default: 4)
    cutout_radius_adj     // outward offset of cutout centres  (default: 1)
);

The screwhead_facetoface parameter corresponds to the face-to-face dimension s in DIN 933. The knob is designed to capture the bolt head in the base recess with the shaft passing through -- the hex recess feature is still under development.

Default hex knob	Large hex knob

Implementation Notes

The knob() geometry is built from 2D profiles rotated with rotate_extrude(). Chamfers are cut using difference() against polygon shapes. Grip cutouts are placed by a helper module rotate_on_circle() that distributes cylinders at equal angular intervals around the perimeter using sin()/cos() positioning.

The source is on GitHub at morganp/parametric-knob-maker.

RFC 2119 Requirements Keywords

2026-04-13T00:00:00+01:00

A previous post on Requirements Writing covered the IEEE normative term conventions used in hardware and semiconductor product development. This post covers a related but distinct standard: RFC 2119, authored by Scott Bradner and published by the IETF in 1997. RFC 2119 defines a small vocabulary of requirement keywords intended for internet protocol specifications, but its usage has spread widely into software engineering, open source project documentation, and API specifications.

The RFC 2119 Keywords

RFC 2119 defines five levels of requirement, expressed through the following keywords and their synonyms:

Keyword	Synonyms	Meaning
MUST	REQUIRED, SHALL	An absolute requirement of the specification.
MUST NOT	SHALL NOT	An absolute prohibition of the specification.
SHOULD	RECOMMENDED	There may be valid reasons to ignore this in particular circumstances, but the full implications must be understood and weighed before doing so.
SHOULD NOT	NOT RECOMMENDED	There may be valid reasons when this behaviour is acceptable, but the full implications should be understood before proceeding.
MAY	OPTIONAL	The item is truly optional. Implementations that omit it and implementations that include it must interoperate correctly.

RFC 2119 provides explicit definitions for both the positive and negative forms of each level. The negative forms -- MUST NOT and SHOULD NOT -- are first-class entries in the standard, not merely implied.

The Capitalisation Convention (RFC 8174)

A critical and commonly overlooked aspect of RFC 2119 is that the special meanings apply only when the keywords appear in ALL CAPITALS. When the same words appear in lowercase, they carry their ordinary English meanings and make no normative claim. RFC 8174, published in 2017, was issued specifically to clarify and reinforce this distinction after widespread confusion in practice.

Documents that use RFC 2119 vocabulary should include a boilerplate statement at the top, such as:

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

This convention means that an author can write "the system should log errors" as informal guidance without it carrying normative weight, while "the system SHOULD log errors" is a normative SHOULD-level requirement. The IEEE standard has no equivalent mechanism -- every occurrence of "shall", "should", or "may" carries normative meaning regardless of case.

Key Differences from IEEE Conventions

The IEEE Standards Style Manual and RFC 2119 share the same intent -- precise, unambiguous requirements -- but they make different choices in several areas. The differences are significant enough that mixing vocabulary from both standards in the same document without clarification will cause confusion.

MUST vs SHALL

This is the sharpest conflict between the two conventions.

RFC 2119: MUST and SHALL are exact synonyms. Either may be used to express an absolute requirement, and the choice between them is purely stylistic.

IEEE: The word "must" is deprecated for requirements use. "Shall" is the sole term for a mandatory requirement. "Must" is reserved for describing unavoidable situations -- physical constraints or facts of nature -- not obligations imposed by the specification.

In a hardware or semiconductor context following IEEE conventions, writing MUST where the IEEE expects SHALL is non-conforming. In an IETF or software context following RFC 2119, writing "shall" is unusual but not incorrect. When working across both domains, choose one convention and state it explicitly at the outset.

Negative Forms

The IEEE style manual covers negative requirements through phrasing such as "shall not" but does not give MUST NOT or SHOULD NOT the same explicit definitional treatment that RFC 2119 does. RFC 2119 is more thorough here: MUST NOT is defined as an absolute prohibition on equal footing with MUST as an absolute requirement.

OPTIONAL as a Synonym for MAY

RFC 2119 defines OPTIONAL as a formal synonym for MAY, emphasising interoperability: if a feature is OPTIONAL, both implementations that include it and those that omit it are conforming, and they must work together. The IEEE treatment of "may" does not carry this interoperability framing -- it signals permission within the specification, not a guarantee of cross-implementation compatibility.

Scope of Use

RFC 2119 includes explicit guidance that its keywords "must be used with care and sparingly". They should only appear where a requirement is genuinely necessary for interoperability or to prevent harmful behaviour -- not to impose implementation style or preferred approaches. The IEEE standard is similarly precise, but the RFC 2119 framing is explicitly interoperability-first, reflecting its origin in network protocol design.

When to Use Which Convention

Context	Recommended convention
Hardware, silicon, semiconductor product specs	IEEE Standards Style Manual (shall / should / may)
IETF internet protocol specifications	RFC 2119 / RFC 8174 (MUST / SHOULD / MAY in caps)
Software project specifications, APIs, open source	RFC 2119 is common; state the convention explicitly
Mixed hardware/software systems	Choose one; document it in a definitions section

Whichever convention is in use, the principle from the requirements writing post applies: terms must be used precisely and consistently. Imprecision in normative vocabulary -- using "should" when "shall" is meant, or omitting MUST NOT when a prohibition is intended -- produces requirements that are untraceable and unverifiable.

Resources

RFC 2119 -- Key Words for Use in RFCs to Indicate Requirement Levels
RFC 8174 -- Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
Requirements Writing -- IEEE normative terms and requirement categories

3D Printed Pinch Rods in OpenSCAD

2026-04-12T00:00:00+01:00

What are Pinch Rods?

Pinch rods are a traditional woodworking measuring tool that predate the tape measure as the reliable way to check whether a box, cabinet, or carcase is square. The concept is simple: two flat rods with pointed ends overlap and slide through a pair of guide blocks. You nestle the tips into opposite diagonal corners of an assembly, lock the rods in place, then check the other diagonal. If both diagonals match, the assembly is square.

The beauty of pinch rods over a tape measure is that you never read a number. The rods physically span the diagonal, and you use that same span directly on the other diagonal. Any discrepancy is immediately obvious as a gap or an overrun at one tip.

They have a second use too: transferring interior dimensions. Set the rods to fit snugly inside a space, lock them, carry the tool to your workpiece, and mark directly. No arithmetic, no misread ruler.

Lost Art Press have documented pinch rods across several articles spanning 2013 to 2025, from a home-centre build using steel tube sleeves and heart pine, through to the machined brass Crucible Tool hardware and a new all-metal prototype using 1/4" keystock. The design has been remarkably stable across all those years -- two rods, two guides, one thumbscrew.

The OpenSCAD Design

A parametrised OpenSCAD model. The guides with or without the rods can be 3D printed. The full source is on GitHub at morganp/OpenSCAD_PinchRods.

The model parameters:

STOCK_THICKNESS = 19/2;  // height of ONE rod -- two stack to fill the opening
STOCK_WIDTH     = 19;    // width of each rod
WALL_THICKNESS  = 5;     // guide wall thickness
GUIDE_LENGTH    = 40;    // depth of each guide block

The two rods are 19mm wide and 9.5mm tall each. They sit one on top of the other inside both guide blocks, so the guide opening is 19mm x 19mm total.

Display Mode

A MODE variable at the top switches between a full assembly preview and single-part export for printing:

MODE = "assembled";   // or "print"
PRINT_PART = "guide2"; // "fastener" | "guide1" | "guide2" | "rod"

The Two Guides

The guides are intentionally different. Each one locks a different rod, so you can set one end, then adjust the other independently.

Guide 1 is mounted inverted in the assembly. Flipping it 180 degrees around the X axis keeps the rod opening in exactly the same position (the opening is symmetric around the centreline at Z = 14.5mm), but moves the countersunk screw hole from the bottom to the top. A screw through that top hole locks onto the top rod.

Guide 2 has a cylindrical standoff boss on top with an M5 threaded hole. A clamping membrane -- a thin slab just inside the opening -- transmits force from the thumbscrew down onto the bottom rod when the knob is tightened. BOSL2's screw_hole() cuts the threaded recess into the standoff, and screw() with anchor=BOTTOM generates the matching fastener.

Guide 1 -- inverted, screw hole on top	Guide 2 -- M5 thumbscrew knob

Tapered Tips

Each rod has a 45-degree chisel taper at one end. Both tapers point toward the shared centreline between the two stacked rods, so from the side the two tips form a symmetric arrowhead shape pointing at the Z midpoint.

The taper is generated using hull() between a knife-edge line at the tip and a full rectangular cross-section a little further along. At 45 degrees the horizontal run equals the vertical rise, so the taper length is exactly STOCK_THICKNESS (9.5mm). The two rods have their tapers on opposite ends of the assembly so each tip engages a different corner of the workpiece.

Printable Parts

Four parts are printed separately. For 3mf export, set MODE = "print" and select the part with PRINT_PART. Note that Guide 1 is printed in its natural orientation (flat bottom on the bed) and then flipped over when assembled. Print two rods and flip one on assembly -- both are the same shape.

Guide 1	Guide 2	Thumbscrew	Rod (print x2)

Dependencies

The SCAD file requires two OpenSCAD libraries in your libraries folder:

BOSL2 -- parametric screws, threads, and screw holes
parametric-knob-maker -- the thumbscrew knob profile (fork with generalised round knob module)

The source is on GitHub at morganp/OpenSCAD_PinchRods.

SoC Article 06: Interconnects and Bus Protocols - AXI, AHB, and APB

2026-04-09T00:00:00+01:00

Series: Introduction to SoC Design | Article 6 of 11

Introduction

Every SoC block, including CPUs, DMA engines, memory controllers, and peripherals, must communicate with every other block. The internal communication fabric that makes this possible is called the interconnect or bus. Choosing and designing the interconnect is one of the most consequential architectural decisions in SoC design: it determines bandwidth, latency, arbitration, and overall system throughput.

This article introduces the major bus standards used in modern SoCs, with emphasis on ARM's AMBA (Advanced Microcontroller Bus Architecture) family, which is the dominant standard in the industry.

Why a Standard Bus Matters

Without a standard interface, every IP block would need a custom interface to every other block: an impractical explosion of design effort. A standard bus protocol defines:

Signal names and widths -- both sides know how to connect
Handshake mechanism -- how a master requests and a slave responds
Transaction semantics -- what "read", "write", and "burst" mean
Timing requirements -- setup times, hold times, latency bounds

IP vendors design their blocks to be plug-compatible with the standard, so a UART controller from one vendor and a DMA engine from another can both connect to the same ARM CoreLink interconnect without any custom glue logic.

The AMBA Family

ARM's AMBA specification, first published in 1996 and evolving through multiple generations, defines a family of bus protocols at different performance tiers:

The family spans from simple, low-power APB peripherals on the right through pipelined AHB, high-performance AXI4, all the way to cache-coherent ACE/CHI protocols used in multi-core processor clusters on the left.

APB: advanced peripheral bus

APB is the simplest AMBA protocol, designed for low-bandwidth, low-power peripheral registers. It is a synchronous, non-pipelined bus with no burst mode -- every transfer takes a minimum of two clock cycles.

APB Signals

Key APB signals:

PCLK: clock
PRESETn: active-low reset
PADDR: address (12-32 bit)
PSEL: select, asserted to indicate target peripheral
PENABLE: enable, on second cycle of every transfer
PWRITE: direction, high = write, low = read
PWDATA: write data
PRDATA: read data (from slave)
PREADY: slave extends transfer if not ready
PSLVERR: slave error response

APB Write Timing

An APB write transaction takes place over two phases: Setup and Access:

In the Setup phase, PSEL is asserted and the address and write data are presented. In the Access phase, PENABLE goes high confirming the transfer. PREADY allows a slow peripheral to extend the access phase by holding it low.

APB is ideal for: UART, SPI, I2C, GPIO, timer, and watchdog registers -- anything that does not require high data throughput.

AHB: advanced high-performance bus

AHB sits in the middle tier. It is a pipelined, higher-bandwidth protocol supporting burst transfers. AHB separates the address phase and data phase, allowing the next address to be issued while the current data transfer is in progress.

Key AHB Signals

HCLK, HRESETn: clock and reset
HADDR: address (32-bit)
HTRANS: transfer type, IDLE, BUSY, NONSEQ, or SEQ
HWRITE: direction
HSIZE: transfer size (8, 16, 32, 64... bit)
HBURST: burst type (SINGLE, INCR, WRAP4, INCR4...)
HWDATA and HRDATA: write and read data
HREADY: transfer complete or extend
HRESP: response (OKAY or ERROR)

AHB Pipelined Burst Read

The key insight: while the data for A0 is being returned, the address A1 is already being presented. This pipeline overlap hides address-to-data latency and improves throughput.

AHB Arbitration

When multiple masters (CPU, DMA) contend for the AHB, an arbiter decides who gets access using a bus grant / bus request protocol. Masters assert HBUSREQx when they want the bus; the arbiter asserts HGRANTx to indicate the winner. This round-robin or priority-based arbitration introduces a form of time-division multiplexing onto the shared bus.

AXI: advanced eXtensible interface

AXI4 is the highest-performance AMBA protocol, used to connect CPUs, memory controllers, DMA engines, GPUs, and other high-bandwidth masters and slaves. It is the backbone of most modern SoCs.

AXI4's key innovation is independent channels: read and write transactions are completely separate, and multiple transactions can be in flight simultaneously.

The five AXI channels

The five channels are:

AW (Write Address): master sends the address and burst parameters for a write
W (Write Data): master sends the data beats with byte strobes and WLAST flag
B (Write Response): slave confirms the write completed (or reports an error)
AR (Read Address): master sends the address and burst parameters for a read
R (Read Data): slave returns data beats with RLAST flag

Valid/Ready Handshake

Every AXI channel uses the same valid/ready handshake protocol. The sender asserts VALID when it has data to transfer. The receiver asserts READY when it can accept data. The transfer completes on the rising clock edge when both are high:

This decoupled handshake is powerful: the master can issue addresses continuously; the slave can stall when its internal buffers are full, without requiring the master to back off.

AXI burst transfers

Rather than issuing many single transactions, AXI supports burst transfers -- a single address phase followed by multiple data beats. This dramatically improves efficiency for sequential memory access.

Key burst parameters:

AWLEN / ARLEN -- number of data beats (0=1 beat, 255=256 beats for AXI4)
AWSIZE / ARSIZE -- bytes per beat (1, 2, 4, 8, 16, 32, 64, 128)
AWBURST / ARBURST -- burst type:
FIXED -- same address repeated (useful for FIFOs)
INCR -- address increments each beat (normal memory access)
WRAP -- like INCR but wraps at a boundary (useful for cache lines)

AXI IDs and out-of-order transactions

AXI assigns each transaction an ID (AWID / ARID). A slave may respond to transactions out of order as long as responses within the same ID are in order. This allows a memory controller to optimise DRAM access patterns rather than being forced to respond in the exact order of requests.

The interconnect: from bus to crossbar

A simple shared bus forces all masters to share a single data path -- only one master can use it at a time. This creates a bottleneck in systems with multiple high-bandwidth masters.

The solution is an AXI crossbar (also called a switch matrix): it provides dedicated paths between every master-slave pair, allowing multiple simultaneous transfers as long as they target different slaves.

ARM's CoreLink NIC-400 and NIC-450 are examples of AXI mux-style interconnects, where a fixed matrix routes each master to a set of slaves. The CoreLink NI-700 takes a different approach: it is a Network-on-Chip (NoC) switched network that routes transactions independently through the fabric, allowing better scalability for large numbers of endpoints. RISC-V SoCs commonly use TileLink or AXI crossbars built with open-source IP.

QoS: Quality of Service in Interconnects

Not all traffic is equal. A display engine reading pixel data must deliver frames at a guaranteed rate, or the screen will tear. A background DMA transfer moving log data is not time-critical. AXI4 supports QoS signalling (ARQOS / AWQOS) -- a 4-bit priority tag attached to every transaction.

The interconnect uses these tags to arbitrate between competing masters, ensuring that time-sensitive traffic is served first without starvation of low-priority traffic.

AXI4-Lite: the simplified register interface

Full AXI4 has substantial complexity -- burst management, ID tracking, out-of-order responses. For accessing peripheral register banks (where individual 32-bit reads and writes are all that is needed), AXI4-Lite offers a simplified subset:

No burst support (single transfers only)
No transaction IDs
No out-of-order support
Simple 32-bit or 64-bit data width

AXI4-Lite is extremely common for connecting peripheral IP blocks to the system bus, where its simplicity makes it easy to implement correctly.

APB bridge: connecting the bus tiers

Because APB is simpler and lower power, slow peripherals are typically attached to an APB bus rather than directly to the AXI/AHB backbone. An AXI-to-APB bridge converts between the protocols:

The bridge runs the APB at a lower, slower clock (e.g., 100 MHz) while the AXI backbone runs at 500 MHz or more, reducing dynamic power in the peripherals.

Network-on-Chip (NoC)

In the largest, most complex SoCs -- server processors, AI accelerators -- even an AXI crossbar becomes a bottleneck. The solution is a Network-on-Chip (NoC): a switched packet network embedded on the die, with routers at each node and links between them.

NoCs provide:

Scalability -- adding more processing tiles does not require redesigning the interconnect
Bandwidth -- multiple simultaneous transfers across different links
Modularity -- standard router IP can be assembled in different topologies

This is an advanced topic covered in the advanced article series.

Summary

SoC interconnects form the communication backbone that links every functional block. The AMBA protocol family provides a hierarchy of protocols: APB for simple peripherals, AHB for mid-range transfers, and AXI for high-performance connections. AXI's independent channel architecture and valid/ready handshake enable high-throughput, pipelined, out-of-order transfers. Crossbar interconnects replace shared buses to allow simultaneous transfers between different master-slave pairs. Understanding these protocols is essential for designing IP blocks that plug into an SoC and for debugging system-level performance issues.

SoC Article 05: Memory Architecture - Caches, DRAM, and On-chip Storage

2026-04-04T00:00:00+01:00

Series: Introduction to SoC Design | Article 5 of 11

Introduction

Of all the factors that determine a SoC's real-world performance, memory is often the most important and the most overlooked by beginners. A modern CPU core can theoretically execute billions of operations per second, but most of that potential is wasted if data cannot be delivered fast enough.

The art of SoC memory architecture is bridging the massive speed gap between the processor (which wants data in nanoseconds) and the external DRAM (which takes tens of nanoseconds to respond) in the most energy-efficient way possible.

The Memory Speed Gap

The problem starts with a fundamental mismatch in technology:

Notice the gap: a CPU register delivers data in under a nanosecond, while external DRAM takes 50-70 ns - roughly 100x slower. Without a caching strategy, the CPU would spend most of its time waiting for memory.

The Memory Hierarchy

The solution is a hierarchy of storage technologies, organised by speed, cost, and distance from the processor:

The hierarchy works because of locality - the observation that most programs access the same data repeatedly over a short period (temporal locality) and access data at adjacent addresses in sequence (spatial locality). Caches exploit both properties.

How Caches Work

A cache is a small, fast SRAM that stores copies of recently-used data from slower memory. When the CPU reads an address, it first checks the cache:

Cache hit - the data is in the cache; it is returned immediately (low latency)
Cache miss - the data is not in the cache; it must be fetched from a slower level

Cache Organisation

A cache is organised into lines (also called blocks) - the minimum unit of transfer between memory levels. A typical cache line is 64 bytes.

Three important cache parameters:

Capacity - total amount of data the cache can hold.

Associativity - how many possible cache locations a given memory address can map to. A direct-mapped cache is simplest: each address maps to exactly one line. A fully-associative cache can hold any address in any line. A 4-way set-associative cache is a compromise: each address maps to a set of 4 lines.

Write policy - what happens when the CPU writes to a cached address:

Write-through: simultaneously update both cache and memory (simple, but uses memory bandwidth)
Write-back: update only the cache, mark the line "dirty", and write to memory only when the line is evicted (more efficient)

Static RAM (SRAM): the cache technology

Caches are built from SRAM (Static RAM). Each bit is stored in a six-transistor cell (6T SRAM) - two cross-coupled inverters and two access transistors.

SRAM retains data as long as power is applied (it is volatile). It is fast (sub-nanosecond access) but uses significant area - roughly 100-150 F per bit (where F is the minimum feature size). This is why caches are small relative to DRAM.

DRAM: the main memory technology

External DRAM uses a one-transistor, one-capacitor (1T1C) cell. The charge on a capacitor represents the bit value.

The 1T1C cell is much smaller than a 6T SRAM cell, enabling much higher density - today's DRAM stores tens of gigabits per die. However, the capacitor leaks charge over time, so each cell must be refreshed (read and rewritten) thousands of times per second. This refresh activity consumes power and introduces brief periods where the memory cannot be accessed.

DRAM Organisation

DRAM is organised into banks, rows, and columns. Accessing data requires:

Activate (open) a row - copies the row into a row buffer (sense amplifiers)
Read/Write column - access the desired column from the row buffer
Precharge - close the row (prepare for the next row activation)

Key timing parameters:

tRCD - Row-to-Column Delay (time after ACT before a column can be accessed)
CL - CAS Latency (time after READ command before data appears)
tRP - Row Precharge time (time to precharge before next ACT)
tRAS - Row Active time (minimum time row must be open)

On-chip SRAM (Tightly Coupled Memory)

In addition to caches, many SoCs include blocks of Tightly Coupled Memory (TCM) - SRAM directly connected to the processor core, accessed through a dedicated bus rather than through the cache hierarchy. TCM provides:

Guaranteed latency - always one cycle, no possibility of a cache miss
Deterministic behaviour - essential for real-time systems
DMA-accessible storage - used for buffers shared with peripherals

This is particularly common in ARM Cortex-M microcontrollers, where code critical for interrupt service routines may be placed in ITCM (Instruction TCM) to ensure it always executes at maximum speed.

The DRAM Controller

Between the SoC's system bus and the DRAM package sits the DRAM controller - a complex piece of hardware that:

Translates read/write requests from the bus into DRAM-specific command sequences (ACT, RD, WR, PRE, REF)
Schedules requests to maximise row-buffer hit rate and memory bandwidth
Issues periodic refresh commands to prevent data loss
Manages multiple banks and ranks for parallel access
Implements QoS (Quality of Service) to ensure latency-sensitive initiators (for example, display engines) get priority

Non-Volatile Storage

Beyond volatile DRAM, SoCs interface with non-volatile storage where data must persist after power-off:

eMMC (embedded MultiMediaCard) - flash memory in a BGA package, soldered to the board. Used in mid-range phones and single-board computers.

UFS (Universal Flash Storage) - faster, lower-latency serial protocol with command queuing. Used in high-end smartphones.

NOR Flash - byte-addressable, execute-in-place (XIP) capable. Often used for bootloaders on embedded systems.

NAND Flash - high density, page/block-based access. Requires a flash translation layer (FTL) to manage wear levelling.

The SoC connects to these through dedicated controller IP blocks: eMMC controller on AHB/APB, UFS controller on AXI, QSPI controller on APB for NOR flash, and NAND controller on AHB.

Memory mapping: the software view

From software's perspective, all memory - SRAM, DRAM, memory-mapped registers, flash - appears as a flat address space. The processor simply reads and writes to 32-bit or 64-bit addresses; the hardware decides which memory or peripheral handles each range.

The memory map is one of the first things a firmware developer consults when writing code for a new SoC. It is typically documented in the SoC's Technical Reference Manual (TRM).

Cache coherency: the multi-core problem

When multiple CPU cores share a memory system, a challenge arises: what happens if two cores have different cached copies of the same address?

This is the cache coherency problem. If Core 0 writes to address A and Core 1 has a stale cached copy of A, Core 1 will read incorrect data.

Hardware cache coherency protocols solve this. The most common is MESI (Modified, Exclusive, Shared, Invalid):

Each cache line has a state tag (M, E, S, or I) that determines how it may be used. A bus snooping mechanism or directory protocol ensures all cores agree on the current state.

Memory Management Unit (MMU)

The MMU translates virtual addresses (used by software) into physical addresses (used by hardware). This translation enables:

Process isolation - each process has its own virtual address space
Memory protection - preventing processes from accessing each other's memory
Virtual memory - presenting more memory than is physically available

Translation is performed via a page table hierarchy stored in DRAM. To avoid the latency of a full table walk for every access, the CPU caches recent translations in the TLB (Translation Lookaside Buffer):

The ARM SMMU (System Memory Management Unit) extends this concept to non-CPU masters (DMA engines, GPU), ensuring that peripheral DMA transfers are also constrained to authorised memory regions.

Summary

The SoC memory architecture is a carefully designed hierarchy that bridges the speed gap between fast-but-small on-chip SRAM and slow-but-large external DRAM. Caches exploit locality to keep frequently-used data close to the processor. DRAM controllers manage the complex command sequencing needed to drive modern LPDDR memory. The MMU virtualises the address space to enable protection and isolation. Together, these components are often the primary determinant of real-world SoC performance.

Intermediate Articles This Topic Connects To

Cache Coherency Protocols: MESI, MOESI, directory-based coherency in detail
DRAM Subsystem Timing (Advanced): tRCD, tCL, CWL, refresh, power states, LPDDR5
Memory-Mapped I/O and Linux Device Drivers: how software talks to hardware registers

Previous: Article 04 -- Processor Cores Next: Article 06 -- Interconnects and Bus Protocols

SoC Article 04: Processor Cores - CPU, DSP, GPU and Hardware Accelerators

2026-03-27T00:00:00+00:00

Series: Introduction to SoC Design | Article 4 of 11

Introduction

The processor is the heart of any SoC. But "processor" is a broad term that covers a remarkably diverse family of designs, each optimised for a different class of computation. A modern smartphone SoC may contain a dozen or more distinct processing engines - general-purpose CPUs, a graphics processor, a signal processing cluster, a neural network accelerator, and several smaller microcontrollers managing power and connectivity.

This article surveys the main classes of processor used in SoCs, explains what makes each suited to its domain, and introduces the key architectural concepts every SoC designer needs to understand.

The Processing Landscape

Different computational tasks have different shapes. Some are sequential and unpredictable (parsing a web page). Others are massively parallel and regular (multiplying a matrix). Still others require precisely timed, low-latency responses (handling a radio frame). These different "shapes" of computation call for different processor architectures.

General-Purpose CPU Cores

Architecture Fundamentals

A CPU core executes a sequential stream of instructions: fetch, decode, execute, access memory, write back. The efficiency of this loop determines performance.

Modern CPU cores in SoCs are overwhelmingly RISC (Reduced Instruction Set Computer) designs. The dominant ISA is ARM, with RISC-V growing rapidly in open-source and embedded applications.

The key subsystems inside a CPU core are:

Pipeline Stages

A five-stage pipeline is the canonical teaching model:

The big.LITTLE concept

For power-sensitive SoCs (smartphones, wearables), ARM developed the big.LITTLE architecture, which pairs high-performance "big" cores with energy-efficient "little" cores on the same die:

The OS scheduler assigns heavy tasks (video decoding, gaming) to the big cores, and lightweight tasks (receiving notifications, idle polling) to the little cores. This can reduce energy consumption by 10x or more compared to running everything on the big cores.

Key Performance Metrics

IPC (Instructions Per Cycle) - how much useful work a core does per clock cycle
Clock frequency - cycles per second (GHz)
Performance = IPC x Frequency
CPI (Cycles Per Instruction) = 1/IPC; lower is better

Modern high-performance cores achieve IPC values of 4-8 by executing multiple instructions simultaneously (superscalar) and speculatively executing future instructions.

Soft vs Hard CPU Cores

An important distinction for SoC designers is between soft and hard processor cores:

Hard cores are transistor-level implementations physically embedded in the silicon - you cannot change them. They are highly optimised for performance and area. The ARM Cortex-A cores in a smartphone SoC are hard cores licensed from ARM.

Soft cores are RTL descriptions that you synthesise yourself onto the target process or onto FPGA fabric. They are portable and configurable but less efficient. Examples include: - ARM Cortex-M0 (available as soft core for ASIC/FPGA) - RISC-V cores (PicoRV32, VexRiscv, BOOM, Rocket) - MicroBlaze (Xilinx/AMD FPGA soft core) - Nios II (Altera/Intel FPGA soft core)

SoC designers on FPGAs (see Article 09) almost always use soft cores since they are placing logic into reconfigurable fabric.

Digital Signal Processors (DSPs)

A DSP is a processor specialised for signal processing algorithms. Its architecture is tuned for two operations that appear constantly in such algorithms: multiply-accumulate (MAC) and data movement.

The MAC operation

The core of almost all digital signal processing is the dot product: multiply pairs of numbers and sum the results. This appears in: - FIR filters: y[n] = h[0]x[n] + h[1]x[n-1] + ... + h[N]x[n-N] - FFT (Fast Fourier Transform) - Convolution in image processing and neural networks

A MAC operation computes: Accumulator += A x B in a single cycle.

DSP architecture features

DSPs include hardware features that a general-purpose CPU lacks:

Hardware loopers - zero-overhead loops without branch penalty
Dual-MAC units - two multiply-accumulate operations per cycle
Circular addressing - automatic modulo addressing for filter delay lines
Bit-reverse addressing - essential for FFT butterfly operations
SIMD instructions - Single Instruction Multiple Data, processing several samples simultaneously

DSPs are commonly found in SoCs handling audio codecs, cellular modem baseband processing, image signal processing (ISPs), and radar systems.

Graphics Processing Units (GPUs)

A GPU is architected around massive parallelism. Instead of a few powerful, complex cores, a GPU contains hundreds or thousands of simple shader cores that execute in lockstep on large datasets.

The programming model is based on the observation that rendering a 3D scene, applying a filter to an image, or training a neural network involves applying the same operation to many different data points independently.

In mobile SoCs, GPUs are used for: - 3D gaming and UI rendering - Video encode/decode - Computer vision and augmented reality - Machine learning inference (alongside or instead of dedicated NPUs)

Common mobile GPU families include ARM Mali, Qualcomm Adreno, and Apple's own GPU (unnamed, integrated in A-series chips).

Hardware Accelerators

As compute-intensive AI workloads have become dominant, SoC vendors have added dedicated hardware accelerators - fixed-function silicon blocks that execute one type of computation extremely efficiently.

Neural processing unit (NPU and neural engine)

An NPU accelerates neural network inference - the process of running a trained model on new input data. The core operation is matrix-vector multiplication (essentially a large MAC array).

In a systolic array, data flows through the processing elements rhythmically. Weights are pre-loaded; activations and partial sums flow through, with each PE performing one MAC per cycle. This achieves very high utilisation of the multiplication hardware.

Video codec engine

Encoding and decoding H.264/H.265/AV1 video in software is extremely CPU-intensive. A dedicated hardware codec can process 4K video at 30+ frames per second while drawing milliwatts, compared to watts for a software implementation. Modern SoCs include fixed-function codec blocks that implement the specific algorithms of each video standard.

Cryptographic accelerator

AES encryption, SHA hashing, RSA/ECC public-key operations, and True Random Number Generation (TRNG) are all candidates for hardware acceleration. Performing AES-128 in hardware can be 50-100x more energy-efficient than software.

Image signal processor (ISP)

The camera pipeline - demosaicing, noise reduction, white balance, tone mapping, HDR merging - runs in a dedicated ISP. This is a DSP-like block hardwired to the specific algorithms of computational photography.

The processor cluster: putting it together

A high-end mobile SoC might contain the following processing elements:

Processor state machine: a simplified view

Every processor can be modelled as a state machine. Here is a simplified view of a CPU's states in a typical embedded SoC context:

Choosing the right processor for your SoC

The processor choice depends critically on the application:

Application	Primary Processor	Rationale
IoT sensor node	Cortex-M0+ (soft/hard)	Ultra-low power, simple code
RTOS control system	Cortex-M4 / M7	Real-time response, DSP extensions
Automotive ADAS	Cortex-A + DSP cluster	Linux needed + CV workloads
Smartphone	big.LITTLE Cortex-A	Variable load, battery priority
Edge AI inference	ARM + NPU	Dominates workload
5G baseband	Multi-DSP cluster	Fixed-point signal processing
FPGA prototyping	RISC-V soft core	Open, configurable, no licence fee

Summary

SoC processing subsystems are not monolithic: they combine CPUs for general-purpose code, DSPs for signal processing, GPUs for parallel/graphics workloads, and hardware accelerators for specific high-demand functions like AI inference, video coding, and cryptography. Each architecture is optimised for its domain. The RISC philosophy underpins most modern SoC CPUs, while the systolic array and SIMD principles dominate accelerators. Understanding the trade-offs between these options is one of the core competencies of SoC architecture.

Intermediate Articles This Topic Connects To

Pipeline Design and Hazards: data, structural, and control hazards; forwarding networks
Cache Coherency Protocols: how multiple CPU cores agree on the state of shared memory
AI Accelerator Architecture (Advanced): dataflow, weight stationarity, memory bandwidth

Previous: Article 03 -- The SoC Design Stack Next: Article 05 -- Memory Architecture: Caches, DRAM, and On-chip Storage

SoC Article 03: The SoC design stack, from transistors to software

2026-03-21T00:00:00+00:00

Series: Introduction to SoC Design | Article 3 of 11

Introduction

In the previous article we looked at what a SoC is. Now we need to understand how it is described, designed, and built. The answer is not a single language or a single tool - it is a stack of abstraction layers, each hiding complexity from the layer above it.

This concept of layered abstraction is one of the most powerful ideas in all of engineering, and it is particularly rich in SoC design, where the stack spans from quantum mechanics at the silicon level all the way up to the C programs and operating systems that run on the finished chip.

The Abstraction Hierarchy

Think of SoC design as a series of nested boxes. Each layer can be understood and reasoned about independently, so long as it respects the contracts defined by the layers around it.

Engineers who work in SoC design typically specialise in one or two adjacent layers. A physical design engineer thinks in terms of polygons and resistance; a firmware engineer thinks in terms of memory-mapped registers and interrupt vectors. The stack is the shared vocabulary that lets them collaborate.

The Gajski-Kuhn Y-Chart

A classic way to visualise the design space is the Y-chart, introduced by Daniel Gajski and Robert Kuhn in 1983. It organises design descriptions along three axes (or "domains"), each of which can be examined at multiple levels of abstraction:

The key insight of the Y-chart is that every design activity maps a description from one domain into another at the same level of abstraction. Synthesis maps a behavioural RTL description into a structural gate-level netlist. Place-and-route maps a structural netlist into a physical layout.

Layer 1: Devices and Transistors

At the very bottom of the stack sits the transistor - the fundamental switch of digital electronics. Modern SoCs are built using CMOS (Complementary Metal-Oxide-Semiconductor) technology, which uses two complementary transistor types: nMOS (conducts when gate is high) and pMOS (conducts when gate is low).

A single CMOS inverter (NOT gate) uses one nMOS and one pMOS transistor. This pairing is elegant: it ensures that when the output is stable, no DC path exists from power to ground, so the circuit draws near-zero static power.

The process of manufacturing transistors is described by the technology node - a number like 5 nm, 7 nm, or 28 nm. This roughly corresponds to the minimum feature size achievable. Smaller nodes pack more transistors into the same area but require more expensive processes.

Layer 2: Logic Gates

Transistors are combined to form logic gates - circuits that implement boolean operations. Gates are the building blocks of all digital logic.

In practice, NAND and NOR gates are the most fundamental - any other gate can be built from them (they are "universal"). Standard cell libraries contain dozens to hundreds of gate variants with different drive strengths, optimised for speed or area.

Layer 3: Register Transfer Level (RTL)

Above the gate level sits the Register Transfer Level (RTL), the primary working abstraction for SoC designers. RTL describes a circuit in terms of:

Registers - collections of flip-flops that hold state
Combinational logic - the boolean functions that compute new values from current state and inputs
Data transfers - moving values between registers, through functional units (ALUs, multiplexers)

RTL is described using a Hardware Description Language (HDL) - either Verilog/SystemVerilog or VHDL. Here is a simple 4-bit counter in both:

// SystemVerilog -- 4-bit synchronous counter with enable
module counter #(parameter WIDTH = 4) (
    input  logic             clk,
    input  logic             rst_n,   // active-low reset
    input  logic             en,
    output logic [WIDTH-1:0] count
);
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n)
            count <= '0;
        else if (en)
            count <= count + 1'b1;
    end
endmodule

-- VHDL -- equivalent 4-bit synchronous counter
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity counter is
    generic (WIDTH : integer := 4);
    port (
        clk   : in  std_logic;
        rst_n : in  std_logic;
        en    : in  std_logic;
        count : out std_logic_vector(WIDTH-1 downto 0)
    );
end entity;

architecture rtl of counter is
    signal cnt : unsigned(WIDTH-1 downto 0);
begin
    process(clk, rst_n)
    begin
        if rst_n = '0' then
            cnt <= (others => '0');
        elsif rising_edge(clk) then
            if en = '1' then
                cnt <= cnt + 1;
            end if;
        end if;
    end process;
    count <= std_logic_vector(cnt);
end architecture;

The behaviour of this counter over time is shown in the timing diagram below:

Layer 4: The Instruction Set Architecture (ISA)

The ISA is the contract between hardware and software. It defines:

The programmer-visible registers (for example, x0–x31 in RISC-V)
The instruction set - the opcodes and their semantics
Memory addressing modes - how addresses are formed
Exception and interrupt behaviour
Privilege levels - user, supervisor, machine mode

The ISA is intentionally a stable interface. A program compiled for RISC-V will run correctly on any RISC-V implementation, regardless of how many pipeline stages it has, how large its caches are, or whether it executes instructions out of order. The microarchitecture can change entirely as long as it correctly implements the ISA.

There are two broad architectural philosophies:

Attribute	CISC	RISC
Philosophy	Complex instructions doing more work	Simple, fast instructions
Instruction size	Variable (1-15 bytes on x86)	Fixed (4 bytes in RISC-V, ARM)
Register count	Historically few	Many (16-32+)
Examples	x86 / x86-64	ARM, RISC-V, MIPS
Common in SoCs	Desktop/server	Mobile, embedded, IoT

Most modern SoCs use RISC-based ISAs (particularly ARM) because their simpler, more regular instruction encodings are easier to implement efficiently in hardware.

Layer 5: Microarchitecture

The microarchitecture is the implementation of the ISA - the actual pipeline, caches, branch predictors, and functional units that execute instructions. It is typically described at RTL level.

A simple five-stage pipeline illustrates the key idea:

Multiple instructions are in-flight simultaneously, improving throughput. The art of microarchitecture is managing the interactions between them - particularly hazards where one instruction depends on the result of a previous one that hasn't finished yet.

IP cores: pre-built design blocks

One of the most important concepts in SoC design is the Intellectual Property (IP) core - a pre-designed, pre-verified block that can be reused in a new design. IP reuse is what makes SoC development tractable: instead of designing every block from scratch, engineers assemble proven components.

IP cores come in three forms:

ARM's Cortex-M series are delivered as soft IP - you receive the RTL description and synthesise it yourself. ARM's Cortex-A series in advanced processes often comes as hard IP - the physical layout is fixed for a particular foundry process.

Common IP blocks found in SoCs:

CPU cores - ARM Cortex-A/M/R, RISC-V cores
GPU IP - ARM Mali, Imagination PowerVR
USB PHY and controller - Synopsys DesignWare
PCIe controller - Synopsys, Cadence
Memory controllers - DDR PHY from specialised vendors
Ethernet MAC/PHY - various vendors
Cryptography engines - AES, SHA, PKA implementations

The Design Flow Overview

Taking an SoC from concept to fabricated silicon follows a structured sequence of steps, each with its own tools and verification checkpoints:

Article 10 in this series covers the design flow in detail. For now, the important point is that design is not a linear process - it is iterative. Problems discovered during synthesis or place-and-route often require revisiting the RTL, and sometimes the architecture.

Modelling languages: choosing the right abstraction

Different languages are suited to different levels of the design stack:

Language	Level	Primary Use
SystemC	Architecture / TLM	System-level modelling, HW/SW co-design
SystemVerilog	RTL / Gate	Hardware design, simulation, formal
VHDL	RTL / Gate	Hardware design (historically in Europe/defence)
Verilog	RTL / Gate	Older HDL, still widely used
C/C++	Algorithm / Firmware	SW design, hardware test benches
Python	Verification / Tools	Test automation, tooling, cocotb test benches

Summary

SoC design is organised as a stack of abstraction layers, from quantum-mechanical effects in transistors at the bottom to application software at the top. Each layer hides complexity from the layer above it, enabling teams of specialists to collaborate without needing to understand every detail. The key levels are: device/transistor, logic gate, RTL, ISA, microarchitecture, and software. IP reuse is the mechanism that makes modern SoC development tractable. The design flow moves from specification through RTL, synthesis, physical design, and sign-off before tape-out.

Intermediate Articles This Topic Connects To

RTL Synthesis and Timing Closure: how EDA tools map RTL to gates and meet timing
SoC Verification with UVM: proving the RTL is correct before committing to silicon
Formal Verification Methods: using mathematics to prove hardware correctness

Previous: Article 02 -- What is a System on Chip? Next: Article 04 -- Processor Cores: CPU, DSP, GPU and Hardware Accelerators

SoC Article 02: What is a System on Chip, anatomy and motivation

2026-03-15T00:00:00+00:00

Series: Introduction to SoC Design | Article 2 of 11

Introduction

In the previous article we traced the seventy-year journey from room-sized mainframes to silicon-level integration, arriving at the System on Chip: a complete computer system fabricated on a single piece of silicon. Now it is time to look inside one: what blocks does it contain, how do they relate, and why does integration deliver such dramatic benefits?

The Board-to-Silicon Transition

In traditional electronics, a "system" was a circuit board populated with many separate chips, each performing one role: a CPU chip, a separate memory controller, a graphics processor, communication peripheral chips, and a power management IC, all connected by copper traces on the PCB.

A System on Chip collapses most or all of those components onto a single piece of silicon. The processor, memory interfaces, graphics engine, USB controller, cryptographic accelerator, radio interface, and many other functional blocks are fabricated together in one integrated circuit.

The term "SoC" emerged formally in the mid-1990s when transistor densities crossed roughly 100 million per chip, the threshold at which integrating a complete system became both technically practical and economically compelling. Today, modern SoCs routinely contain tens of billions of transistors.

Why Does Integration Matter?

Putting everything on one die is not just about convenience. It delivers fundamental advantages across every dimension that matters.

Speed

On-chip wires are nanometres wide and micrometres long. Signals cross them in fractions of a nanosecond. Signals crossing a PCB encounter far greater inductance and capacitance, longer paths, and the need for high-drive output buffers, all of which introduce significant delay. An on-chip memory access takes 1-5 ns; an off-chip access might take 60-100 ns for the same data.

Power Efficiency

Driving a signal off-chip requires pumping it up to a voltage level and current that the PCB can handle reliably - this is fundamentally wasteful. On-chip signalling operates at much lower voltages (as little as 0.4 V for the fastest paths) and does not need the drive strength of an off-chip interface. Every chip-to-chip boundary eliminated saves power directly.

Area and Cost

Fewer chips means a smaller PCB, which means a smaller, lighter product. At the volumes of the smartphone market (billions of units per year), even a 5 mm² reduction in PCB area translates into substantial savings. One complex SoC may cost less to manufacture and assemble than the collection of chips it replaces.

Reliability

Solder joints and connectors are the most common failure points in electronic assemblies. Fewer chips mean fewer joints, longer mean time between failures, and better suitability for vibration-prone environments (automotive, industrial, aerospace).

The Anatomy of a Generic SoC

While no two SoCs are identical, most share a recognisable set of functional blocks:

Each block has its own dedicated article later in the series. Here is a brief map of what each does:

Processing Subsystem

The "brains" of the SoC. One or more CPU cores execute general-purpose software. Alongside them are specialised processors - DSPs for signal processing, GPUs for graphics and parallel computation, and dedicated hardware accelerators for AI inference, video coding, and cryptography. (Article 04)

Memory Subsystem

On-chip SRAM provides fast, low-latency storage close to the processors. DRAM controllers connect to external memory for the large working set. A cache hierarchy sits between the two. (Article 05)

System Interconnect

The internal "highway" connecting all blocks. High-bandwidth connections use AXI; lower-bandwidth peripheral connections use AHB or APB. (Article 06)

DMA Engine

Direct Memory Access allows peripherals to move blocks of data to/from memory without involving the CPU - essential for high-throughput peripherals like USB, Ethernet, and cameras. (Article 08)

Peripherals

The interfaces that connect the chip to the external world: UART, SPI, I2C, GPIO, USB, Ethernet, and many others. (Article 08)

Clock and Reset

A PLL generates the precise, stable frequencies each subsystem requires. The reset subsystem places all flip-flops in a known initial state after power-up. (Article 07)

Power Management

The PMU selectively powers down idle blocks, runs the CPU at lower voltage when full speed is not needed, and manages battery charging in portable devices. (Article 07)

Security Engine

Dedicated hardware for encryption, secure boot, key storage, and access control. ARM TrustZone partitions the chip into secure and non-secure domains. (Article 11)

SoC Examples in the Real World

SoC	Application	Notable Features
Apple A18 (iPhone 16)	Smartphone	6-core CPU, 6-core GPU, Neural Engine, 16 B transistors
Qualcomm Snapdragon 8 Gen 3	Android phone	big.LITTLE cluster, Hexagon DSP, integrated 5G modem
NVIDIA Orin	Autonomous vehicles	12-core ARM, Ampere GPU, deep learning accelerator
Raspberry Pi RP2040	Hobbyist MCU	Dual Cortex-M0+, PIO state machines, 264 KB SRAM
Nordic nRF5340	IoT / BLE	Dual ARM cores, Bluetooth 5.3 radio integrated on-chip
Xilinx Zynq UltraScale+	FPGA SoC	ARM quad-core + FPGA fabric + GPU + DSP slices

The range here is important. An SoC is not just a smartphone chip. The same integration principle applies from a $0.50 microcontroller running a light switch to a $200 chip managing an autonomous vehicle.

The Complexity Challenge

Integration delivers benefits, but it raises design complexity to a different level entirely. A modern SoC is designed by teams of hundreds of engineers over one to three years. The design must:

Meet timing requirements across all operating conditions (voltage, temperature, process variation)
Be verified correct before manufacture - a bug in silicon costs millions to fix
Balance the competing bandwidth demands of many simultaneous data flows
Boot reliably from cold power-off and recover gracefully from faults
Meet strict power and thermal budgets across wildly different workloads

Managing this complexity is the central discipline of SoC design, and it is the reason for the structured methodologies this series explores.

HW/SW Duality

A crucial insight for SoC design is that hardware and software are both valid ways to implement any function. The choice between them is a trade-off, and it shapes the entire architecture:

Attribute	Hardware	Software
Performance	Very high (parallel, GHz)	Lower (sequential execution)
Flexibility	Fixed after tape-out	Updateable/patchable
Energy efficiency	Excellent for specific tasks	Lower for the same task
Development time	Long, expensive	Shorter, cheaper
Debugging difficulty	Very high post-silicon	Much easier

Most SoCs exploit this duality deliberately - placing performance-critical, stable functions in hardware, and flexible or complex control logic in software. Understanding where to draw that line is one of the core skills in SoC architecture and is the subject of Article 11.

Summary

A System on Chip integrates what was once a board full of discrete chips - processors, memory controllers, communication interfaces, and more - onto a single piece of silicon. Integration delivers speed (proximity), power efficiency (no off-chip driving), smaller area (fewer chips), and higher reliability (fewer solder joints). Every SoC shares a recognisable anatomy: processing subsystem, memory subsystem, system interconnect, DMA engine, peripherals, clock/reset, power management, and security. The following articles examine each of these in turn.

Intermediate Articles This Topic Connects To

AXI4 Protocol Deep Dive: the interconnect in detail
SoC Power Management Techniques: DVFS, power gating, retention
Heterogeneous SoC Partitioning (Advanced): formal HW/SW co-exploration

Previous: Article 01 -- From Room to Silicon Next: Article 03 -- The SoC Design Stack: From Transistors to Software

Managing Dotfiles with Stow and Git

2026-03-07T00:00:00+00:00

Configuration files (dotfiles) for tools like Zsh, Vim, tmux, and Git tend to accumulate across machines over time. Without a strategy, they diverge: one machine has tuned aliases, another has an old vimrc, and a new machine starts from scratch. Keeping dotfiles in a single Git repository solves this. Clone once, link into place, and every machine stays consistent.

My dotfiles are on GitHub at morganp/dotfiles.

Why Centralise Dotfiles

A single source of truth for all shell and tool configuration.
Version history lets you see what changed and roll back if something breaks.
Setting up a new machine reduces to cloning the repo and running a handful of commands.
Sharing config across macOS and Linux with minimal platform-specific branching.

Cloning the Repo

git clone https://github.com/morganp/dotfiles.git ~/dotfiles

Linking Config Files

There are two approaches depending on the tool.

Sourcing (Zsh and Vim)

Some tools are simplest to handle by having the home directory config file source the dotfiles version directly.

Zsh -- add to ~/.zshrc:

source ~/dotfiles/config/shell/dot-zshrc

Vim -- add to ~/.vimrc:

so ~/dotfiles/config/vim/dot-vimrc_clean

GNU Stow (Everything Else)

GNU Stow manages symlinks. It takes a package directory and creates symlinks in a target directory that mirror the structure. With the --dotfiles flag, files named dot-foo are linked as .foo in the target, keeping the repo free of files that would be hidden by default.

Install Stow and other packages via Homebrew:

brew bundle install --file=~/dotfiles/config/brew

Then link the remaining configs:

cd ~/dotfiles/config
stow git --dotfiles -t ~/
stow input --dotfiles -t ~/
stow screen --dotfiles -t ~/

A run_stow script in the repo automates this.

Tmux

Tmux looks for its config via the $XDG_CONFIG_HOME variable, set in config/shell/dot-profile:

$XDG_CONFIG_HOME/tmux/tmux.conf

For the tmux plugin manager, clone TPM separately:

git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Shell Features

The dotfiles configure the following shell aliases across Bash and Zsh:

Alias	Description
`ls`	File list with colour
`ll`	Long list with human-readable sizes and colour
`la`	As `ll` but includes hidden files
`lt`	Directory tree view
`..`	Up one directory

Other configurations included:

Screen: Virtual tabs across the bottom in standard colours.
Inputrc: Case-insensitive tab completion, including hidden files.

Emotional Intelligence in the Workplace

2026-03-07T00:00:00+00:00

Emotional intelligence (EQ) is the ability to recognise, understand, and manage your own emotions, as well as the emotions of those around you. In professional settings, EQ significantly influences how individuals lead, collaborate, and navigate difficult situations.

High EQ: What It Looks Like

Leaders and employees that demonstrate high EQ:

Navigate not just motivating and empowering employees and team members, but also navigate complex and challenging decision making with the mastery of emotional response.
Are realistic but not negative and overcome with their emotions.
Are enthusiastic and confident in themselves and the team.
Demonstrate trust and respect.
Are communicative and cooperative.
Volunteer for assignments and decisions.
Include and engage others as much as possible.
Share openly with the team.
Demonstrate empathy.
Actively listen.
Are flexible.
Develop their teams.

Low EQ: Warning Signs

Low EQ may show up as:

Emotional outbursts, typically out of proportion to the situation at hand.
Not listening to others.
Becoming argumentative.
Blaming others.
Believing that others are overly sensitive, because the person with low EQ cannot understand how others feel.
Difficulty maintaining friendships and other relationships.
Stonewalling, or refusing to see other points of view.

Why It Matters

High EQ is not about suppressing emotion -- it is about channelling emotion constructively. Teams led by high-EQ individuals tend to communicate more openly, recover from setbacks more quickly, and make better collective decisions. Recognising low EQ behaviours early, in yourself and others, is the first step toward building a healthier team culture.

MakerWorld Parametric Models with OpenSCAD

2026-03-07T00:00:00+00:00

MakerWorld listings with a "Customize" button let users tweak model parameters, preview changes live, and download a ready-to-print file. Under the hood, these are OpenSCAD scripts. MakerWorld runs the script inside their Parametric Model Maker app and presents the configurable variables as a UI for the end user.

If you can write an OpenSCAD script that generates your model and expose the key dimensions as variables, MakerWorld handles the rest: a polished customizer UI and a downloadable 3mf file.

OpenSCAD is a free, code-based CAD tool. Rather than clicking tools and dragging dimensions, you describe geometry as code. For example, instead of drawing a sphere and setting its diameter to 20mm, you write:

sphere(d = 20);

Think of it as scripting the feature timeline you would normally follow in Fusion 360 or Onshape.

Getting Started with OpenSCAD

Learning resources:

YouTube tutorials are the quickest way to get a feel for what OpenSCAD can do.
The official OpenSCAD documentation and cheatsheet are available online.
LLMs like ChatGPT are surprisingly effective: describe the object you want, ask for an OpenSCAD script, and iterate from there.

Testing your script:

Run it locally in OpenSCAD on your own machine as you develop.
Or use MakerWorld's Parametric Model Maker directly in your browser without installing anything.

Which version of OpenSCAD does MakerWorld support?

MakerWorld is compatible with the 2021 official release. The project has daily development builds with additional features, but stick with the stable 2021 release to ensure compatibility.

Publishing to MakerWorld

To add a Customize button to your listing, create a new MakerWorld listing and upload the .scad file instead of a .3mf file. MakerWorld will automatically detect it and enable the customizer. You also earn MakerWorld points when users download via the Customize button.

Controlling the Customizer UI

Any variable declared at the top of your script appears as an editable field in the UI automatically. To control the widget type (slider, dropdown, colour picker, help text), use comments following the OpenSCAD Customiser standard. The easiest way to explore the options is to click the "Sample Code" icon in the bottom-left of the Parametric Model Maker. It loads example code demonstrating all available widgets.

Example: dropdown with named options

// Select which size you want
Box_Size = 10; // [10:Large, 5:Medium, 1:Small]

Font selector:

Label_Font = "Arial"; // font

Available fonts are those pre-loaded by MakerWorld, which includes most of Google Fonts. The full list is in the Parametric Model Maker under the "Book" icon then "Third-party fonts".

Libraries

MakerWorld supports a curated set of OpenSCAD libraries:

Library	Purpose
BOSL2	General-purpose functions and geometry
UB	Miscellaneous utilities
KeyV2	Keyboard keycap generation
gridfinity-rebuilt-openscad	Gridfinity bin generation
threads-scad	Threaded parts
Getriebe	Gear generation
knurledFinishLib_v2	Knurled surface textures

Largely based on this Reddit post in r/BambuLab.

OpenSCAD on Apple Silicon

2026-03-07T00:00:00+00:00

OpenSCAD is a script-based 3D CAD modeller, well suited to parametric and printable part design. The snapshot release has native Apple Silicon support.

Install Homebrew

If Homebrew is not already installed, run the following in Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install OpenSCAD

The snapshot cask provides the latest development build with native ARM support:

brew install --cask openscad@snapshot

Once installed, OpenSCAD will be available in /Applications and can be launched from Spotlight or the Applications folder.

reMarkable: Local File Transfer Without the Cloud

2026-03-07T00:00:00+00:00

The reMarkable tablet is excellent for reading and annotating PDFs, but by default it routes everything through reMarkable's cloud. If you prefer to keep files local -- for privacy, or simply because you do not want a subscription -- you can unpair the device and use the built-in USB file server instead.

Unpairing from the Cloud
Enabling the USB Web Interface
Transferring Files via http://10.11.99.1/
Tips and Limitations

1. Unpairing from the Cloud

Unpairing stops the device from syncing to reMarkable's servers. Your existing documents remain on the device; they are simply no longer backed up or accessible from the reMarkable apps on other devices.

On the tablet:

Open Settings (gear icon, bottom-left of the home screen)
Go to Storage
Tap Unpair device
Confirm when prompted

Once unpaired, the tablet no longer requires a reMarkable account or internet connection for normal use. The cloud sync icon will disappear from the top bar.

Note: Unpairing is reversible. You can re-pair the device at any time from the same Settings screen by signing back in to your reMarkable account.

2. Enabling the USB Web Interface

The reMarkable has a built-in HTTP file server that becomes accessible over USB. When enabled, the tablet presents itself as a USB network adapter and serves files at http://10.11.99.1/.

On the tablet:

Open Settings
Go to Storage
Enable USB transfer (the toggle may be labelled "USB web interface" depending on firmware version)

Connect the tablet to your computer using the supplied USB-C cable. The tablet will appear as a network device (USB Ethernet adapter) rather than a mass storage drive.

On Linux the interface typically appears as usb0 or enp0s20u1 and receives an address in the 10.11.99.0/24 subnet automatically via DHCP from the tablet.

Verify connectivity:

ping 10.11.99.1

3. Transferring Files

Open a browser and navigate to:

http://10.11.99.1/

The web interface shows all documents and notebooks currently on the device, organised in folders matching the tablet's home screen layout.

Uploading PDFs

Click Import (or the upload button, top-right)
Select one or more PDF files from your computer
The files appear on the tablet home screen immediately -- no restart required

Supported formats: PDF and EPUB.

Downloading annotated files

Click on any document in the web interface
Select Download to save the annotated PDF to your computer

The downloaded file includes all pencil annotations, highlights, and notes made on the tablet.

Command-line upload with curl

For scripting or batch uploads:

curl -X POST http://10.11.99.1/documents/ \
  -F "file=@/path/to/document.pdf"

To upload into a specific folder, first find the folder UUID from the web interface URL, then:

curl -X POST "http://10.11.99.1/documents/{folder-uuid}" \
  -F "file=@/path/to/document.pdf"

4. Tips and Limitations

No Wi-Fi required. The USB file server works entirely over the USB cable with no network connection needed.
Cable must stay connected. The web interface is only available while the tablet is plugged in. Unplugging immediately drops the 10.11.99.1 address.
One client at a time. The built-in server is minimal; avoid opening multiple browser tabs uploading simultaneously.
Folder structure is flat internally. The reMarkable stores documents with UUIDs internally; the folder hierarchy you see in the web interface is a virtual view maintained by the device.
Firmware updates still work offline. Updates are downloaded over Wi-Fi separately from the cloud sync; unpairing does not block firmware updates if Wi-Fi is available.
Annotations on existing PDFs are exported as a new annotated PDF -- the original on- device file is not modified.

SoC Article 01: From Room to Silicon — The Story of the Computer System

2026-03-07T00:00:00+00:00

Series: Introduction to SoC Design | Article 1 of 11

Introduction

There is a photograph from 1964 that captures the scale of computing at the time. It shows two engineers installing an IBM System/360 Model 50. They are not sitting at desks. They are standing in a large, air-conditioned room, surrounded by cabinets the size of wardrobe closets, connected by thick bundles of cabling snaking under a raised false floor. The computer weighs approximately two tonnes. It required specialist riggers with cranes and fork trucks to move into the building. It draws 30 kilowatts of power — enough to heat several homes.

That machine cost around $3.5 million in 1964 dollars. It performed roughly 500,000 operations per second.

The phone in your pocket performs about 15 trillion operations per second, thirty million times more, on a sliver of silicon roughly 100 mm² in area, weighing a fraction of a gram, drawing less than three watts. It fits comfortably in a jacket pocket.

This article is the story of how we got from there to here. It is not just a history lesson. Understanding the shape of that journey — what drove miniaturisation at each step, and what trade-offs were made along the way — is essential context for understanding why modern SoC design is structured the way it is.

What is a "system"?

Before discussing a System on Chip, we should understand what the word "system" means in this context.

In engineering, a system is a collection of components that work together to perform a function greater than any single component could achieve alone. A computer system, in the classical sense, means all the hardware necessary to store, retrieve, and process information:

processor: the arithmetic and logic engine
memory: where programs and data live
storage: where data persists when power is off
input and output: keyboards, displays, printers, serial ports
interconnect: the buses and cables that tie it all together
power supply: the electrical infrastructure

For decades, each of these was a separate physical unit, often made by different vendors, assembled on a raised floor in a dedicated machine room. The history of computing is largely the story of these components shrinking, converging, and ultimately merging.

Era 1: The Room-Sized Machine (1950s–1960s)

Valves and Racks

The earliest electronic computers used vacuum tubes (valves) as their switching elements. A vacuum tube is roughly the size of a light bulb. A computer that needs hundreds of thousands of switching elements built from vacuum tubes fills a building.

ENIAC (1945) is the canonical example: 17,468 vacuum tubes, 70,000 resistors, 10,000 capacitors, filling a room 2.4 m × 1.8 m × 30 m. It consumed 150 kilowatts of power and broke down regularly — with so many valves, a failure every few hours was normal. Operators spent more time repairing it than computing with it.

The Manchester Baby (1948), while tiny by comparison, still occupied a substantial rack of equipment and required skilled operators to program it using switches and plugboards.

Approximate Physical Scale — 1950s Computer Systems

  ┌──────────────────────────────────────────────────────────────────┐
  │                                                                  │
  │  ENIAC (1945)                                                    │
  │                                                                  │
  │  [██████████████████████████████████████████████████████████]    │  ← 30 metres
  │  [█ Accumulator █][█ Multiplier █][█ Divider █][█ I/O █][█...█]  │
  │                                                                  │
  │  Weight: ~27 tonnes   Power: 150 kW   Speed: 5,000 ADD/sec       │
  │                                                                  │
  └──────────────────────────────────────────────────────────────────┘

The transistor changes everything

In 1947, Bell Labs invented the transistor. It did the same job as a vacuum tube — acting as an electronic switch — but was smaller, faster, cooler, more reliable, and consumed far less power. By the late 1950s, computers began to be built from transistors instead.

IBM System/360 (1964) was a landmark: the first family of computers with a common instruction set, so that programs written for one model would run on any other. But it was still a room-scale machine. The System/360 Model 50 filled multiple cabinets, required dedicated air conditioning, and had to be craned into the computer room through specially widened doorways or lowered through the roof.

The economics were equally extreme: only universities, large corporations, government agencies, and national laboratories could afford to own one. Everyone else bought time-shares, submitting jobs on punched cards and waiting hours for results.

Era 2: The Minicomputer (1965–1975)

Thinking Small

The minicomputer was not called "mini" because it was small by today's standards. It was called mini because it was dramatically smaller than the mainframes it accompanied — small enough to fit in a single large cabinet, deliverable in a standard lift, operable without a dedicated air-conditioned room.

Digital Equipment Corporation (DEC) pioneered this category. Their PDP-8 (1965) was a 12-bit machine that cost $18,000 — expensive, but accessible to a laboratory, university department, or medium-sized company without a dedicated data centre.

The PDP-11 (1970) is one of the most important computers ever designed. It was a 16-bit machine that fit in a single rack about the size of a tall filing cabinet. It had a clean, elegant instruction set that influenced virtually every processor architecture that followed — including Unix, which was first developed on a PDP-7 and PDP-11.

DEC PDP-11 (1970) — Physical Footprint:

  ┌─────────────────────┐
  │  ┌───────────────┐  │
  │  │  Backplane    │  │  ← Processor and memory cards slot in here
  │  │  (UNIBUS)     │  │
  │  │               │  │
  │  │  CPU card     │  │  ← A single card, 30 cm × 25 cm
  │  │  Memory cards │  │
  │  │  I/O cards    │  │
  │  └───────────────┘  │
  │  Power supply       │
  └─────────────────────┘
    ~ 60 cm × 45 cm × 60 cm
    Weight: ~30 kg
    Power: ~300 W
    Speed: ~1 million ops/sec
    Cost: ~$10,000 (1970)

The PDP-11 introduced several ideas that persist in modern SoC design: memory-mapped I/O (where peripherals appear as addresses in the memory map), a bus standard (UNIBUS), and the concept of a clean separation between the processor and the rest of the system through a well-defined bus interface.

The minicomputer era's legacy

The minicomputer era produced ideas that underpin every SoC today:

Bus standards: the UNIBUS, Multibus, and S-100 buses established the principle that components from different vendors could interoperate on a common bus
Operating systems: Unix was born on the PDP-11; its model of processes, file descriptors, and device drivers lives on in Linux running on modern SoCs
Modular architecture: CPU, memory, and I/O were separate cards in the same backplane, a precursor to the IP block model

Era 3: The Microprocessor (1971–1980)

Everything on one chip

In 1971, Intel introduced the 4004 — the first microprocessor. It placed the entire CPU — arithmetic unit, registers, control logic — onto a single chip about 12 mm². It ran at 740 kHz and processed 4-bit numbers.

This was a revolutionary idea: previously, a "CPU" was a cabinet full of boards. Now it was a package you could hold between your fingers.

The 8080 (Intel, 1974), 6502 (MOS Technology, 1975), and Z80 (Zilog, 1976) followed in rapid succession. These 8-bit processors became the engines of the personal computer revolution.

The Intel 8086 (1978) and Motorola 68000 (1979) raised the bar to 16-bit, with the 68000 in particular earning a reputation for elegance and performance that made it the choice for the Apple Macintosh, the Amiga, the Atari ST, and countless workstations.

But the microprocessor alone was just the CPU. Everything else — memory, storage, I/O — was still provided by separate chips on a board. The "system" was still a board, just a smaller one.

Era 4: The Personal Computer (1977–1990)

The desktop system

The first personal computers were kits for hobbyists. The Altair 8800 (1975) was an 8080-based machine with no keyboard, no display, and no software beyond a bootloader — users programmed it by toggling switches on the front panel.

Within a few years, Apple, Commodore, and Tandy produced complete personal computers: CPU, RAM, ROM, keyboard, display output, and storage on a single motherboard in a desktop enclosure. The Apple II (1977) sold as a complete system you could put on a desk.

Apple II Motherboard (1977) — A Complete Computer System on One Board:

  ┌────────────────────────────────────────────────────────────────┐
  │                       Apple II Motherboard                     │
  │                                                                │
  │  [6502 CPU]  [RAM chips × 8]  [ROM chips × 2]  [Video chip]    │
  │                                                                │
  │  [Keyboard encoder]  [Cassette I/O]  [Speaker driver]          │
  │                                                                │
  │  ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐       │
  │  │Slot│ │Slot│ │Slot│ │Slot│ │Slot│ │Slot│ │Slot│ │Slot│       │
  │  │  1 │ │  2 │ │  3 │ │  4 │ │  5 │ │  6 │ │  7 │ │  8 │       │
  │  └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘ └────┘       │
  │                (expansion cards for disk, serial, etc.)        │
  │                                                                │
  │  Board size: ~30 cm × 25 cm    Number of chips: ~66            │
  │  System power: ~25 W           Speed: 1 MHz                    │
  └────────────────────────────────────────────────────────────────┘

The IBM PC (1981) standardised the desktop architecture that dominated computing for three decades: a processor, a chipset handling memory and I/O, expansion slots for peripherals, and a shared bus (first ISA, later PCI). By the late 1980s, a PC could sit on a desk, consume 50–200 W, and perform millions of operations per second for a few thousand dollars.

The chip count had fallen from thousands (mainframe) to hundreds (minicomputer) to dozens on a single motherboard. But a PC motherboard was still a system assembled from many chips: CPU, north bridge, south bridge, graphics chip, sound chip, network chip, storage controller, and many more.

Era 5: The laptop and mobile computing

Batteries change everything

The first truly portable computers appeared around 1981. The Grid Compass (1982) was used by NASA and the US military — it was functional but cost $8,000 and ran for barely four hours on battery. The Compaq LTE (1987) was the first laptop to use a 3.5" hard drive and internal battery in a genuinely portable form factor.

Mobile computing imposed a constraint that desktop design had never faced: batteries. A desktop computer plugged into the wall can draw as much power as needed. A laptop must run for hours on a battery with finite energy.

Power Budget — Desktop vs. Laptop (late 1980s):

  Desktop PC (1988):         Compaq LTE (1987):
  Power: ~150 W              Power: ~8 W
  Battery: none              Battery: NiCd, ~2 hr life
  Weight: ~10 kg             Weight: ~3 kg
  Size: tower case           Size: 28 cm × 22 cm × 4 cm

  Problem: the same chips designed for desktop
  drew 150 W — far too much for a battery.
  A new approach to chip design was needed.

Power pressure drove two responses:

Low-voltage CMOS — designers switched from bipolar logic (powerful but power-hungry) to CMOS (Complementary Metal-Oxide-Semiconductor), which consumes power only when transistors switch, not when they are idle. This dramatically reduced both active and standby power.

Integration — every chip-to-chip interface wastes energy driving signals off-chip and back. Merging two chips into one removes those interfaces. The laptop era was the first time integration was driven primarily by power rather than just performance.

Era 6: The mobile phone and the ARM architecture

An architecture built for efficiency

In 1983, Acorn Computers in Cambridge designed their own processor: the Acorn RISC Machine, or ARM. It was a 32-bit RISC processor designed to be simple, low-power, and fast enough for interactive computing in an inexpensive product. The original ARM1 ran at 6 MHz and consumed a fraction of a watt — remarkable for 1985.

Acorn spun off Advanced RISC Machines Ltd in 1990 as a joint venture with Apple and VLSI Technology. Rather than manufacturing chips itself, ARM licenced its architecture to other companies — a business model that would eventually see ARM cores inside virtually every mobile device on the planet.

The first mobile phones were large, power-hungry, and limited. As GSM digital mobile telephony spread in the 1990s, phones needed to perform signal processing (decoding the radio channel), handle the telephone UI, and manage a small battery. They could afford perhaps 200 mW of sustained power.

A phone of the early 2000s had several separate chips: a baseband processor (running the radio protocols), an application processor (running the UI and apps), a power management IC, a display controller, and various analog front-ends for audio and radio. These chips communicated over a shared PCB — the "system" was a small board inside a plastic case.

This was the moment before SoC. All the pieces existed — they just were not yet on the same die.

Era 7: The System on Chip (1995–present)

Integration crosses a threshold

As process technology advanced through the 1990s — from 350 nm to 250 nm to 180 nm — the number of transistors that could be fabricated reliably on a single die crossed 100 million. That is enough transistors to implement not just a CPU, but everything around it: memory controllers, DSPs, display engines, USB, audio, and power management.

The Texas Instruments OMAP series (early 2000s) was among the first true smartphone SoCs: ARM application processor, DSP, camera interface, display controller, and power management all on one die. This appeared in early Nokia smartphones and PDAs.

Apple's acquisition of PA Semi in 2008 and its launch of the A4 SoC in 2010 (the first iPhone 4 chip) signalled that the world's most valuable consumer electronics company was betting everything on the SoC model. Qualcomm, Samsung, MediaTek, and HiSilicon followed with their own vertical SoC programmes.

The convergence was complete:

The Integration Journey — Same Computational Power, Shrinking Footprint:

  Year   System                      Physical Size       Power    Transistors
  ─────────────────────────────────────────────────────────────────────────
  1964   IBM System/360 Model 50     2 rooms, 2 tonnes   30 kW    ~500,000
  1970   DEC PDP-11/20               Filing cabinet      300 W    ~20,000 *
  1977   Apple II (full system)      Desk (30×25 cm PCB) 25 W     ~100,000 *
  1982   Intel 80286 CPU alone       28-pin DIP package  3 W      134,000
  1993   Intel Pentium               273-pin PGA chip    15 W     3.1 M
  2003   Nokia 6600 (5 chips total)  PCB inside a phone  200 mW   ~50 M total
  2010   Apple A4 SoC                12 mm × 12 mm die   ~1 W     ~300 M
  2020   Apple A14 SoC               88 mm² die          ~3 W     11.8 B
  2024   Apple A18 SoC               90 mm² die          ~3 W     ~16 B
  ─────────────────────────────────────────────────────────────────────────
  * Approximate, counting discrete transistors and SSI/MSI chips

Moore's Law: the engine of miniaturisation

No account of this journey is complete without Moore's Law. In 1965, Gordon Moore (co-founder of Intel) observed that the number of transistors on a commercially practical integrated circuit doubled approximately every two years. This was an empirical observation about the economics of the semiconductor industry, but it became a self-fulfilling prophecy: the industry organised itself to deliver that doubling, and did so for more than fifty years.

Each doubling meant that the same design could be shrunk to half the area (reducing cost), or that twice as much logic could fit in the same area (enabling integration). Both drove the SoC story.

Moore's Law has slowed in recent years — physical limits make further miniaturisation increasingly difficult and expensive below 3 nm. The industry is responding with new techniques: 3D stacking (chips stacked vertically), chiplets (multiple dies in one package), and new materials. But the principle — relentless pressure toward more integration per unit cost — continues.

What "System" Means Now

Return to where we started: the IBM System/360, craned into a dedicated machine room, requiring a team of operators and a purpose-built building to run.

Today's SoC is a more capable system — more memory, faster clock, more peripherals, better networking — occupying an area smaller than a fingernail, drawing power measurable in milliwatts, costing a few dollars to manufacture at scale.

But it is still a system: processor, memory controller, interconnect, peripherals, power management, security hardware. The same logical building blocks exist. They have simply been reimplemented in silicon, brought together on a single die, separated by wires measured in nanometres rather than copper cables measured in metres.

Understanding that lineage — why the blocks exist, what problems they solve, where the trade-offs come from — is the context for everything that follows in this series.

Summary

Computer systems began as room-filling collections of vacuum tubes. The transistor enabled the minicomputer — a cabinet-scale machine accessible to laboratories and companies. The microprocessor collapsed the CPU onto a single chip and made the personal computer possible. Mobile computing added battery constraints that drove integration for power efficiency. The System on Chip emerged when transistor densities crossed the threshold that made fitting an entire system — CPU, memory, peripherals, and more — onto a single die both technically feasible and economically compelling. Moore's Law underpinned the entire journey, doubling integration density roughly every two years for five decades.

Series Roadmap

Article	Topic
01	From Room to Silicon — History of the Computer System (this article)
02	What is a System on Chip? — Anatomy and Motivation
03	The SoC Design Stack: From Transistors to Software
04	Processor Cores: CPU, DSP, GPU and Hardware Accelerators
05	Memory Architecture: Caches, DRAM, and On-chip Storage
06	Interconnects and Bus Protocols: AXI, AHB, and APB
07	Clocking, Reset, and Power Domains
08	Peripherals and I/O: Connecting the SoC to the World
09	Hardware Description Languages and RTL Design
10	The SoC Design Flow: From Specification to Silicon
11	HW/SW Co-Design: Bridging Software and Silicon

Next: Article 02 -- What is a System on Chip? Anatomy and Motivation

Requirements Writing

2026-03-06T18:00:00+00:00

Good requirements engineering is fundamental to delivering products that meet customer needs within cost and schedule. A well-formed requirement identifies a specific user or stakeholder, defines a positive end result, and states a measurable success criterion -- for example: "The internet user shall be able to access their current account balance in less than 5 seconds." Requirements must be unambiguous, singular (one requirement per statement), and free of escape clauses such as "unless", "except", or "if possible". They should avoid designing the solution, speculating about future needs, or using vague qualitative terms like "user-friendly" or "flexible" that cannot be verified. The normative terms shall, should, and may carry specific and distinct meanings -- using them precisely is critical to a traceable and verifiable requirement set.

Note: The IBM Requirements Writing Training document uses 'shall' or 'will' interchangeably to signal a mandatory requirement. The IEEE Standards Style Manual (also referenced below) deprecates the use of 'will' for mandatory requirements, reserving it for statements of fact only. The IEEE definition is the preferred usage.

Normative Terms

Normative requirements are normally phrased using one of the three terms below: shall, should, or may. All normative elements that are requirements (shall) are to be followed in all cases in order to be in conformity.

Term	Priority	Description
'Shall'	High	'Must-have' for minimum viable product (MVP)
'Should'	Medium	'Desirable' in product and to be considered for phase 1, including any impact
'May'	Low	'Nice-to-have' and could be included if no impact to key metrics. Should log decision.

Use of Special Terms (from IEEE Standards Style Manual)

The word shall is used to indicate mandatory requirements strictly to be followed in order to conform to the Specification and from which no deviation is permitted (shall equals is required to).

The use of the word must is deprecated and shall not be used when stating mandatory requirements; must is used only to describe unavoidable situations.

The use of the word will is deprecated and shall not be used when stating mandatory requirements; will is only used in statements of fact.

The word should is used to indicate that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others; or that a certain course of action is preferred but not necessarily required; or that (in the negative form) a certain course of action is deprecated but not prohibited (should equals is recommended that).

The word may is used to indicate a course of action permissible within the limits of the Specification (may equals is permitted to).

The word can is used for statements of possibility and capability, whether material, physical, or causal (can equals is able to).

All sections are normative, unless they are explicitly indicated to be informative.

Requirement Categories

The following categories reflect a common industry classification used in semiconductor product development.

Category	Definition	Owner
CR	Customer Requirement -- A customer need that the product needs to meet. Gathered from customer interaction, field channels or market research. May not be possible to meet all CRs on a product due to risk or resources.	Marketing, Systems
SR	System Requirement -- Describes the required black-box behaviour of the device. Customer visible SRs are the primary basis for the datasheet. Often, an SR translates a CR into the plan-of-record for a product. Captures the negotiated attribute. May not fully meet the ideal CR.	Systems
DR	Design Requirement -- Result of distillation of SR, driven by implementation choices that do not affect the black-box behaviour but need to be defined for the design or verification team. Capture constraints required to implement the SRs.	Design
VR	Verification Requirement -- Description of what needs to be done to ensure an SR and/or DR is implemented correctly. Linked to at least one SR and/or DR. Checks and coverage information is recorded in VRs.	Verification
VAR	Validation Requirement -- A concise description of how an SR or DR of any requirement type will be covered with a test case during the emulation or post-silicon phase of development. Validation requirements check whether we implemented the right thing through means of functional testing or parametric silicon measurements. Test conditions are recorded in a VAR. Linked to at least one SR.	Validation

Requirement Types

Type	Definition
Functional	Normative functional requirements that can be verified and/or validated.
Parametric	Normative parametric requirements that can be verified and/or validated.
Register Field	Normative register field requirements.
Informative	Informative requirement content, not actionable, but provides context for better interpretation of normative requirements. Informative elements are illustrations, examples, or suggestions that explain the meaning and implications of requirements, as well as case studies on their application. May include diagrams and other attachments which are not to be treated as normative.
Use Case	System-level use cases. Commonly captured as diagrams and set context (informative) but can require verification and distillation into further requirements (normative).

Resources

Scotland Outdoor Routes

2026-03-06T12:00:00+00:00

Misc

Historic Scotland (Family £106/year includes entry to Edinburgh Castle): https://www.historicenvironment.scot/

Site Map (PDF)

Mapping


Memory Map (£25/year)	https://memory-map.com/maps/uk-os-topo-maps/
Bing Maps, switch from Road to Ordnance Survey (free)	https://www.bing.com/maps
Ordnance Survey Maps (7 day free trial, £24/year)	https://osmaps.ordnancesurvey.co.uk/
Rucksack Readers for long distance routes (~£15 per map)	https://www.rucsacs.com/book-category/scotland/
Spokes Cycle Maps (~£7 per map)	http://www.spokes.org.uk/spokes-maps/
Urban Nature Maps (Edinburgh & Glasgow, £10 each)	edinburgh-urban-nature-map
Scots Ways	https://scotways.com/maps-and-leaflets/

All Scotland

Edinburgh

Seven Hills

Castle Rock
Calton Hill
Arthur's Seat
Blackford Hill
Braid Hills
Corstorphine Hill
Craiglockhart Hills

Midlothian

Pentland Hills

East Lothian

Core Paths Map links

Map	Area
Map A	Gullane, Aberlady and surrounding area
Map B	North Berwick and surrounding area
Map C	Whitekirk and surrounding area
Map D	Musselburgh North
Map E	Prestonpans, Port Seton, Tranent North
Map F	Longniddry and Haddington West
Map G	Haddington East and surrounding area
Map H	East Linton, Stenton and surrounding area
Map J	Dunbar and surrounding area
Map K	Innerwick and surrounding area
Map L	Musselburgh South and Whitecraig
Map M	Tranent South, Macmerry, Ormiston
Map N	Pencaitland and East Saltoun
Map O	Gifford and surrounding area
Map P	Garvald and surrounding area
Map Q	East Lammermuir Hills
Map R	Oldhamstocks and surrounding area
Map S	Glenkinchie and South West area
Map T	Humbie and surrounding area
Map U	Western Lammermuir Hills
Map V	Central Lammermuir Hills
Map W	Whiteadder and South East Lammermuir Hills

Aviemore

https://www.cairngormmountain.co.uk/

Rothiemurchus

https://rothiemurchus.net/outdoor-activities-at-aviemore/

Loch-an-Eilein: https://rothiemurchus.net/visit/loch-an-eilein/

Laggan Wolftrax

Insh Marshes Nature Reserve

North Ayrshire

Arran

Aberdeenshire

Tarland Trails

tmux Training Manual: Ghostty, xterm and PVE LXC Terminals

2026-02-27T12:00:00+00:00

tmux is a terminal multiplexer: it lets you run multiple terminal sessions inside a single window, split panes side by side, and crucially, keep sessions alive after you disconnect. For headless Proxmox VE (PVE) LXC containers accessed over SSH, this is essential. If your SSH connection drops mid-task, tmux keeps the job running and lets you reattach exactly where you left off. This manual walks through tmux in practical exercises, covering Ghostty on macOS, xterm, and terminal sessions inside PVE LXC containers.

Getting Back to a Known State

This section comes first because it is the most important concept to internalise. Just as pressing Escape repeatedly in vim returns you to a safe state, tmux has equivalent recovery paths. Learn these before anything else.

The Prefix Key

Every tmux command starts with the prefix key, which is Ctrl+b by default. You press Ctrl+b, release both keys, then press the command key. Nothing happens if you just hold Ctrl+b without following up.

If you press Ctrl+b and then the wrong key, tmux usually just ignores it. You are not stuck.

Exiting Any Mode

Situation	How to exit
Stuck in copy mode	Press `q` or `Escape`
Stuck in command mode (`:` prompt)	Press `Escape` or `Ctrl+c`
Pane running something	Press `Ctrl+c` to interrupt it
Everything looks wrong	Detach with `Ctrl+b d` and reattach fresh

Emergency Exit Sequences

Detach from session (session keeps running):

Ctrl+b d

List all sessions from outside tmux:

tmux ls

Reattach to a named session:

tmux attach -t <session-name>

Reattach to the most recent session:

tmux attach

Kill a specific pane (with confirmation prompt):

Ctrl+b x

Kill a specific window (with confirmation prompt):

Ctrl+b &

Kill a session entirely from the command line:

tmux kill-session -t <session-name>

Kill all tmux sessions:

tmux kill-server

The pattern to remember: Ctrl+b d detaches safely, tmux ls shows what is running, and tmux attach -t <name> gets you back. These three commands will rescue you from almost any situation.

Installation

Debian and Ubuntu LXC Containers

sudo apt update
sudo apt install tmux

macOS (Ghostty Host)

brew install tmux

Verify Installation

tmux -V

Expected output: tmux 3.x (version 3.3a or later is common as of 2026).

Terminal Compatibility Notes

Ghostty

Ghostty works excellently with tmux. It supports true colour, full mouse reporting, and passes modifier keys correctly. No special configuration is needed.

If colours look wrong inside tmux running in Ghostty, set this in your shell profile:

export TERM=xterm-256color

Or add this to ~/.tmux.conf to force 256 colour mode:

set -g default-terminal "screen-256color"

xterm

xterm is a reliable fallback. It handles tmux correctly but defaults to a limited colour palette. Set the terminal type explicitly if you see rendering artefacts:

TERM=xterm-256color tmux

Or add to your shell profile permanently:

export TERM=xterm-256color

PVE LXC Console: noVNC vs SSH

PVE's web console (noVNC) can cause key capture problems with tmux. The Ctrl+b prefix may not pass through correctly because the browser intercepts some key combinations. In practice, Ctrl+b often works, but scrolling, mouse support, and certain modifier combinations behave inconsistently.

Recommendation: always use SSH into the LXC for tmux work.

ssh user@<lxc-ip>

SSH gives you a proper PTY, correct terminal type negotiation, and reliable key forwarding. noVNC is fine for quick root access or emergency recovery, but not for regular tmux sessions.

If you must use the PVE noVNC console with tmux, set a longer escape time to reduce timeout frustration:

set -sg escape-time 50

Exercise 1: First Session

This exercise covers starting, using, detaching, and reattaching to a named session.

Start a Named Session

tmux new -s training

You are now inside a tmux session called training. The green (or coloured) bar at the bottom is the status bar.

Reading the Status Bar

The status bar shows:

Left side: session name in brackets, e.g. [training], followed by window index and name, e.g. 0:bash
Right side: hostname and time (depending on your config)
An asterisk * next to the current window name

Run a Command

top

Watch it run. Now detach without killing it.

Detach from the Session

Ctrl+b d

You are back at your normal shell prompt. The top command is still running inside tmux.

Verify the Session is Still Running

tmux ls

Output:

training: 1 windows (created Thu Feb 27 12:00:00 2026)

Reattach to the Session

tmux attach -t training

You are back inside the session. top is still running. Press q to quit top.

Quick Reconnect: Attach or Start in One Command

tmux attach has the short form tmux a. With no target it attaches to the most recently used session, which is exactly what you want when only one session exists:

tmux a

To attach if a session exists, or start a fresh one if none does, chain the two:

tmux a || tmux

A cleaner built-in alternative is new-session -A, which means "attach to this named session, creating it first if needed". It is idempotent, so it is safe as a login one-liner or shell alias:

tmux new -A -s main

Both patterns make reconnecting to a headless LXC a single muscle-memory command: SSH in, type it, and you are either back where you left off or in a fresh session.

Recovery Notes for Exercise 1

If you lose track of session names, tmux ls always shows what is running. If tmux ls shows nothing, there are no sessions and you start fresh with tmux new -s <name>.

Exercise 2: Windows

Windows in tmux are like browser tabs. Each window fills the full terminal area and can run a different program.

Create a New Window

Ctrl+b c

A new window appears. The status bar now shows two windows: 0:bash and 1:bash.

Name the Current Window

Ctrl+b ,

A rename prompt appears at the bottom. Type a name, for example logs, then press Enter.

Switch Between Windows

Switch to window by number:

Ctrl+b 0
Ctrl+b 1

Switch to next window:

Ctrl+b n

Switch to previous window:

Ctrl+b p

List All Windows (Known State Check)

Ctrl+b w

An interactive list of all windows appears. Use arrow keys to navigate and Enter to select. Press Escape to cancel without switching. This gives you a clear view of what is open.

Close a Window

The cleanest way is to exit the shell:

exit

Or force close the current window (with confirmation):

Ctrl+b &

Type y to confirm. If you have multiple windows, tmux moves you to the next one. If it was the last window, the session ends.

Recovery Notes for Exercise 2

If you are confused about which window you are in, Ctrl+b w shows the full list. If a window is running something stuck, Ctrl+b & closes it after confirmation.

Exercise 3: Panes

Panes split a single window into multiple terminal areas visible at the same time.

Split Horizontally (Left and Right)

Ctrl+b %

The window is now split into two vertical columns (left pane and right pane).

Split Vertically (Top and Bottom)

Ctrl+b "

The current pane is split into two horizontal rows.

Navigate Between Panes

Use the prefix followed by an arrow key:

Ctrl+b <arrow key>

For example, Ctrl+b then the right arrow moves focus to the right pane.

Show Pane Numbers (Known State Check)

Ctrl+b q

Large numbers appear briefly over each pane. Press the number while it is visible to jump to that pane directly.

Resize a Pane

Hold the prefix and then repeatedly press arrow keys. In most terminals:

Ctrl+b :resize-pane -D 5

This resizes the current pane down by 5 rows. Directions: -U (up), -D (down), -L (left), -R (right).

Alternatively, if mouse mode is enabled (covered in the config section), you can drag pane borders.

Zoom a Pane to Full Screen

Ctrl+b z

The current pane expands to fill the entire window. Press Ctrl+b z again to return to the split layout. The status bar shows [Z] when a pane is zoomed.

Close a Pane

The cleanest way:

exit

Or force close with confirmation:

Ctrl+b x

Type y to confirm. If it is the last pane in the window, the window closes too.

Recovery Notes for Exercise 3

Ctrl+b q shows pane numbers so you can see where you are. Ctrl+b z is useful if you accidentally zoomed and the layout looks wrong: toggle it again to return to the split view.

Exercise 4: Copy Mode (and How to Exit It)

Copy mode lets you scroll back through terminal output and copy text. Knowing how to exit it reliably is as important as knowing how to enter it.

Enter Copy Mode

Ctrl+b [

The status bar shows [Copy] in the top right corner. You are now in copy mode.

Navigate in Copy Mode

Key	Action
Arrow keys	Move cursor one line/column
`PgUp` / `PgDn`	Scroll up or down a page
`g`	Go to the top of the scrollback buffer
`G`	Go to the bottom (current output)
`/`	Search forward
`?`	Search backward
`n`	Next search match
`N`	Previous search match

Exit Copy Mode

Press q or Escape.

This is the key thing to remember. If you are in copy mode and the terminal seems unresponsive to normal commands, you are still in copy mode. Press q or Escape to return to normal mode.

Copy Text

Enter copy mode: Ctrl+b [
Navigate to the start of the text you want
Press Space to begin selection
Move to the end of the text
Press Enter to copy and exit copy mode

Paste Copied Text

Ctrl+b ]

This pastes the tmux clipboard into the current pane at the cursor position.

Recovery Notes for Exercise 4

If your keyboard input is being swallowed and commands are not running, the most likely cause is that you are in copy mode. Press q first, then Escape if q did not work.

Exercise 5: PVE LXC Workflow

This exercise demonstrates the core use case for tmux in a Proxmox VE environment: running long tasks in an LXC container and safely reconnecting after a disconnect.

Step 1: SSH into the LXC Container

From your workstation (Ghostty or any terminal):

ssh user@<lxc-ip>

Replace <lxc-ip> with the IP address of your LXC container. You can find this in the PVE web interface under the container's Network tab, or by running ip a inside the container.

Step 2: Start a Persistent Session

tmux new -s work

Step 3: Run a Long Job

sudo apt upgrade

This may take several minutes. Let it run.

Step 4: Detach and Close SSH

Ctrl+b d

You are back at the container's shell prompt (outside tmux). Now close the SSH connection entirely:

exit

Or close the terminal window. The apt upgrade is still running inside the tmux session on the LXC container.

Step 5: Reconnect and Reattach

Open a new terminal and SSH back in:

ssh user@<lxc-ip>

List running sessions:

tmux ls

Output:

work: 1 windows (created Thu Feb 27 12:05:00 2026)

Reattach:

tmux attach -t work

You are back watching apt upgrade complete, exactly as you left it.

Why tmux Beats GNU Screen for LXC Work

Both tmux and screen provide session persistence, but tmux has clearer defaults, better pane support, and easier scripting. The tmux ls command gives a clean session overview. Pane splitting is built in without workarounds. Configuration via ~/.tmux.conf is straightforward. For new setups, start with tmux.

Quick Reference Table

Action	Key or Command	Notes
New named session	`tmux new -s <name>`	Run from shell
List sessions	`tmux ls`	Run from shell
Attach to session	`tmux attach -t <name>`	Run from shell
Detach from session	`Ctrl+b d`	Session keeps running
New window	`Ctrl+b c`
Rename window	`Ctrl+b ,`
Switch to window N	`Ctrl+b <N>`	0-9
Next window	`Ctrl+b n`
Previous window	`Ctrl+b p`
List windows	`Ctrl+b w`	Interactive picker
Close window	`Ctrl+b &`	Confirmation required
Split pane left/right	`Ctrl+b %`
Split pane top/bottom	`Ctrl+b "`
Navigate panes	`Ctrl+b <arrow>`
Show pane numbers	`Ctrl+b q`
Zoom pane toggle	`Ctrl+b z`	Status bar shows [Z]
Close pane	`Ctrl+b x`	Confirmation required
Enter copy mode	`Ctrl+b [`
Exit copy mode	`q` or `Escape`
Start selection	`Space`	While in copy mode
Copy selection	`Enter`	While in copy mode
Paste	`Ctrl+b ]`
Reload config	`Ctrl+b :source-file ~/.tmux.conf`
Kill session	`tmux kill-session -t <name>`	Run from shell

Config Tweaks

tmux reads ~/.tmux.conf on startup. Create or edit this file to customise behaviour. Changes take effect in new sessions, or you can reload without restarting.

Location

~/.tmux.conf

Change the Prefix Key to Ctrl+a

Many users prefer Ctrl+a because it is easier to reach and was the screen default:

unbind C-b
set -g prefix C-a
bind C-a send-prefix

After this, all commands use Ctrl+a instead of Ctrl+b. The bind C-a send-prefix line lets you type a literal Ctrl+a in programs like bash by pressing the prefix twice.

Enable Mouse Support

set -g mouse on

With mouse enabled, you can click to select panes, drag borders to resize, and scroll with the mouse wheel. Scroll wheel enters copy mode automatically. To exit copy mode after scrolling, press q.

Increase Scrollback Buffer

The default scrollback is 2000 lines, which fills up quickly. Increase it:

set -g history-limit 10000

Reduce Escape Time (Useful for PVE noVNC)

set -sg escape-time 50

This reduces the delay tmux waits after pressing Escape before deciding it is not a prefix sequence. Lower values make Escape feel more responsive in vim and other tools inside tmux.

Start Window and Pane Index at 1

By default windows are numbered from 0. Starting at 1 maps better to the number keys:

set -g base-index 1
setw -g pane-base-index 1

Reload Config Without Restarting

After editing ~/.tmux.conf, reload it inside a running tmux session:

Ctrl+b :source-file ~/.tmux.conf

Or add a keybinding for this in ~/.tmux.conf:

bind r source-file ~/.tmux.conf \; display-message "Config reloaded"

Then use Ctrl+b r (or Ctrl+a r if you changed the prefix) to reload.

Minimal Recommended Config

# Change prefix to Ctrl+a
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Enable mouse
set -g mouse on

# Increase scrollback
set -g history-limit 10000

# Reduce escape time
set -sg escape-time 50

# Start numbering from 1
set -g base-index 1
setw -g pane-base-index 1

# Reload config
bind r source-file ~/.tmux.conf \; display-message "Config reloaded"

Known State Cheatsheet

Bookmark this section. When something goes wrong, work through it from top to bottom.

1. Exit any mode:

In copy mode: press q, then Escape if needed
In command mode: press Escape
Program stuck: press Ctrl+c

2. Check what windows and panes are open:

Ctrl+b w    (list windows)
Ctrl+b q    (show pane numbers)

3. Detach safely (session keeps running):

Ctrl+b d

4. From the shell, list all sessions:

tmux ls

5. Reattach to a session:

tmux attach -t <name>
tmux attach          # most recent session

6. Kill a stuck pane:

Ctrl+b x    (confirmation prompt, then y)

7. Kill a stuck window:

Ctrl+b &    (confirmation prompt, then y)

8. Kill a session entirely:

tmux kill-session -t <name>

9. Nuclear option: kill all tmux sessions:

tmux kill-server

10. Start fresh:

tmux new -s main

Following this list top to bottom will resolve the vast majority of situations where tmux feels stuck or confusing. The core principle: Ctrl+b d gets you out, tmux ls shows what is there, and tmux attach gets you back in.

Installing Homebrew on a Debian 13 (Trixie) LXC Container

2026-02-25T00:00:00+00:00

This tutorial documents a working, verified installation of Homebrew (Linuxbrew) on a Debian 13 "trixie" LXC container. Every step reflects what was actually done on this system; nothing has been invented or copied from generic guides without verification.

Tested environment: - Debian GNU/Linux 13 (trixie), amd64 - LXC unprivileged container - Homebrew 5.0.15 - Primary non-root user: morgan (uid=1000)

Prerequisites
Installation Steps
Per-User Shell Setup
Verification
Adding Future Users
Troubleshooting

1. Prerequisites

System packages

The Homebrew installer requires these packages. Install them as root before running the installer:

apt-get update
apt-get install -y build-essential git curl file procps

Verify all five are present:

ii  build-essential 12.12              amd64  Informational list of build-essential packages
ii  curl            8.14.1-2+deb13u2   amd64  command line tool for transferring data with URL syntax
ii  file            1:5.46-5           amd64  Recognize the type of data in a file using "magic" numbers
ii  git             1:2.47.3-0+deb13u1 amd64  fast, scalable, distributed revision control system
ii  procps          2:4.0.4-9          amd64  /proc file system utilities

PATH gotcha: /usr/sbin must be in root's PATH

On Debian 13, /usr/sbin is not automatically in the PATH of non-login shells (including those invoked by su without -l). The installer calls useradd, which lives at /usr/sbin/useradd. If /usr/sbin is missing from your PATH the installer will fail with a confusing "command not found" error.

Before running the installer, confirm your PATH includes /usr/sbin:

echo $PATH

If it does not, prepend it for the session:

export PATH="/usr/sbin:$PATH"

Or simply run the installer from a full login shell (su - rather than su).

2. Installation Steps

All steps in this section are run as root.

Step 1 — Create the dedicated `linuxbrew` group

Homebrew on Linux uses a shared group so that multiple users can write to the installation prefix. Create it before the installer runs so you control its GID:

groupadd linuxbrew

Step 2 — Pre-create the Homebrew prefix directory

The Homebrew installer expects to own /home/linuxbrew/.linuxbrew. In an LXC container the installer sometimes cannot create /home/linuxbrew itself due to ownership constraints on /home. Pre-create it and set the correct ownership before running the installer:

mkdir -p /home/linuxbrew/.linuxbrew
chown -R morgan:linuxbrew /home/linuxbrew
chmod 2775 /home/linuxbrew
chmod 2775 /home/linuxbrew/.linuxbrew

The 2775 mode sets the setgid bit (s) on the directory. This causes all files and subdirectories created inside to inherit the linuxbrew group automatically, which is what allows multiple users to install and update packages.

After this step, ls -la /home/linuxbrew/ should show:

drwxrwxr-x  3 morgan linuxbrew 4096 Feb 25 15:31 .
drwxr-xr-x  4 root   root      4096 Feb 25 15:31 ..
drwxrwsr-x 14 morgan linuxbrew 4096 Feb 25 15:31 .linuxbrew

And stat /home/linuxbrew/.linuxbrew confirms the setgid bit:

Access: (2775/drwxrwsr-x)  Uid: ( 1000/  morgan)   Gid: ( 1001/linuxbrew)

Step 3 — Add the primary user to the linuxbrew group

usermod -aG linuxbrew morgan

The -a flag is critical — without it usermod -G replaces all supplementary groups instead of appending to them.

Step 4 — Run the Homebrew installer as the primary user

Switch to the non-root user and run the official installer. Do not run it as root:

su - morgan
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Because the prefix directory already exists and is writable by the linuxbrew group (and morgan is a member), the installer will populate it without needing to create it or change system-level ownership.

Step 5 — Create the system-wide profile.d script

To activate Homebrew automatically for every user who logs in, create a shell script in /etc/profile.d/ as root:

cat > /etc/profile.d/homebrew.sh << 'EOF'
#!/bin/bash
if [ -d "/home/linuxbrew/.linuxbrew" ]; then
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
fi
EOF
chmod +x /etc/profile.d/homebrew.sh

This is exactly the file present on this system:

# /etc/profile.d/homebrew.sh
#!/bin/bash
if [ -d "/home/linuxbrew/.linuxbrew" ]; then
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
fi

The if guard makes the script safe on systems where the prefix does not exist (e.g., before installation, or if the directory is removed).

3. Per-User Shell Setup

The /etc/profile.d/homebrew.sh script runs automatically for login shells. This covers su - username, SSH logins, and console logins.

For interactive non-login shells (e.g., a new terminal tab that sources ~/.bashrc instead of ~/.bash_profile), a user may need to add the following to their ~/.bashrc:

# Homebrew (Linuxbrew)
if [ -d "/home/linuxbrew/.linuxbrew" ]; then
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
fi

brew shellenv sets these environment variables:

Variable	Value
`HOMEBREW_PREFIX`	`/home/linuxbrew/.linuxbrew`
`HOMEBREW_CELLAR`	`/home/linuxbrew/.linuxbrew/Cellar`
`HOMEBREW_REPOSITORY`	`/home/linuxbrew/.linuxbrew/Homebrew`
`PATH`	prepends `/home/linuxbrew/.linuxbrew/bin` and `.../sbin`
`MANPATH`	prepends `.../share/man`
`INFOPATH`	prepends `.../share/info`

4. Verification

Confirm the installation prefix layout

ls -la /home/linuxbrew/.linuxbrew/

Expected output (all entries owned by morgan:linuxbrew, setgid s visible):

total 56
drwxrwsr-x 14 morgan linuxbrew 4096 Feb 25 15:31 .
drwxrwxr-x  3 morgan linuxbrew 4096 Feb 25 15:31 ..
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 Caskroom
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 Cellar
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 Frameworks
drwxrwsr-x 15 morgan linuxbrew 4096 Feb 25 15:31 Homebrew
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 bin
drwxrwsr-x  3 morgan linuxbrew 4096 Feb 25 15:32 etc
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 include
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 lib
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 opt
drwxrwsr-x  2 morgan linuxbrew 4096 Feb 25 15:31 sbin
drwxrwsr-x  6 morgan linuxbrew 4096 Feb 25 15:32 share
drwxrwsr-x  3 morgan linuxbrew 4096 Feb 25 15:31 var

Check the Homebrew version

su - morgan -c 'brew --version'

Homebrew 5.0.15

Run brew doctor

su - morgan -c 'brew doctor'

Your system is ready to brew.

Confirm group membership

getent group linuxbrew
# linuxbrew:x:1001:morgan

id morgan
# uid=1000(morgan) gid=1000(morgan) groups=1000(morgan),100(users),1001(linuxbrew)

Test installing a package (dry run)

su - morgan -c 'brew install --dry-run hello'

==> Would install 1 formula:
hello

5. Adding Future Users

When a new user needs Homebrew access:

# As root — add the new user to the linuxbrew group
usermod -aG linuxbrew newuser

The user must log out and back in (or start a new login shell) for the group change to take effect. The /etc/profile.d/homebrew.sh script will activate brew for them automatically on their next login. No other changes are needed.

To verify the new user can reach Homebrew:

su - newuser -c 'brew --version'

6. Troubleshooting

`brew: command not found` in a non-login shell

The /etc/profile.d/homebrew.sh script only runs in login shells. In a non-login shell (typical terminal emulators, su username without the -), Homebrew will not be on the PATH.

Fix: source the script manually, or add the eval line to ~/.bashrc as shown in Section 3.

Quick test — if this works but brew does not:

/home/linuxbrew/.linuxbrew/bin/brew --version

then the issue is purely PATH/environment, not the installation.

`useradd: command not found` during installation

useradd lives at /usr/sbin/useradd. On Debian 13, /usr/sbin is not in the PATH of non-login root shells. Run the installer from a full login shell:

su -        # note the hyphen — this gives a login shell with /usr/sbin in PATH

Or prepend it explicitly before running the installer:

export PATH="/usr/sbin:$PATH"

Installer fails to create `/home/linuxbrew`

In LXC containers, the installer may not be able to create the prefix directory itself because /home is owned by root:root with mode 755. The installer does not have write access to /home when running as a non-root user.

Solution: pre-create the directory as root before running the installer (see Step 2).

Permission denied errors when running `brew install`

The user must be in the linuxbrew group and must have started a new session after being added. Check:

id          # linuxbrew should appear in the groups list

If linuxbrew is absent, either the usermod -aG linuxbrew username step was skipped, or the user has not logged out and back in since being added.

`brew doctor` reports warnings about `/usr/local`

On Linux, Homebrew uses /home/linuxbrew/.linuxbrew as its prefix, not /usr/local. Warnings about /usr/local being absent or not owned by the current user are normal and harmless on a Linux installation.

Quick-Reference: Full Root-Side Install Sequence

# 1. Install dependencies
apt-get update && apt-get install -y build-essential git curl file procps

# 2. Ensure /usr/sbin is in PATH (run as login shell or set manually)
export PATH="/usr/sbin:$PATH"

# 3. Create the linuxbrew group
groupadd linuxbrew

# 4. Pre-create the prefix and set ownership/permissions
mkdir -p /home/linuxbrew/.linuxbrew
chown -R morgan:linuxbrew /home/linuxbrew
chmod 2775 /home/linuxbrew
chmod 2775 /home/linuxbrew/.linuxbrew

# 5. Add the primary user to the group
usermod -aG linuxbrew morgan

# 6. Run the installer as the non-root user
su - morgan -c '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'

# 7. Install the system-wide profile.d activation script
cat > /etc/profile.d/homebrew.sh << 'EOF'
#!/bin/bash
if [ -d "/home/linuxbrew/.linuxbrew" ]; then
    eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
fi
EOF
chmod +x /etc/profile.d/homebrew.sh

# 8. Verify
su - morgan -c 'brew --version && brew doctor'

FSM Diagrams in Pelican and Claude Code

2026-02-22T18:00:00+00:00

Finite state machines turn up everywhere: protocol implementations, hardware controllers, UI flows, parsers. Drawing them well is useful but tedious. This post covers two tools I've built: a Pelican plugin that renders FSM diagrams at build time so they appear as images in published posts, and a Claude Code skill that generates diagrams from plain-English descriptions.

The pattern is identical to the WaveDrom plugin and skill: describe what you want, get a fenced code block, paste it into a post, and the build renders it to SVG automatically.

The Pelican plugin

The plugin is at github.com/morganp/pelican-fsm, cloned to ~/Code/pelican-fsm (a sibling directory to the blog repo). It intercepts fenced ```mermaid ``` and ```dot ``` code blocks before Pelican's standard Markdown processing, renders each one to an SVG using the appropriate CLI tool, caches the result by content hash in content/images/fsm/, and replaces the block with a standard image reference. Pelican then copies the SVG to output/images/fsm/ as a static asset.

SVGs are cached across builds, so only diagrams whose source has changed are re-rendered.

Requirements

Mermaid CLI for mermaid blocks:

npm install -g @mermaid-js/mermaid-cli

Graphviz for dot blocks:

brew install graphviz      # macOS
sudo apt install graphviz  # Debian/Ubuntu

Both tools are optional. If one is missing, blocks for that type fall back gracefully to a fenced text block without failing the build.

Installation

Clone the plugin alongside your Pelican project and install it into the Pelican virtualenv in editable mode:

git clone https://github.com/morganp/pelican-fsm ../pelican-fsm
source venv/bin/activate
pip install -e ../pelican-fsm --config-settings editable_mode=compat

The editable_mode=compat flag is required. Without it, modern setuptools editable installs use a path-hook mechanism that prevents Pelican's namespace plugin auto-discovery from finding the plugin.

Pelican 4.5+ auto-discovers namespace plugins, so no changes to pelicanconf.py are needed.

Optional config

If mmdc or dot are not on your PATH during the build, set their full paths in pelicanconf.py:

FSM_MERMAID_CLI = '/opt/homebrew/bin/mmdc'
FSM_DOT_CLI = '/opt/homebrew/bin/dot'

Using it in a post

Write a fenced code block with the language set to mermaid or dot:

```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Running : start
    Running --> Idle : stop
    Running --> Error : fault
    Error --> Idle : reset
```

At build time this becomes an SVG embedded in the page:

Graphviz DOT works the same way, and is a better fit for hardware and RTL documentation where the compact box-and-arrow style is conventional:

If the CLI is not found or rendering fails, the block falls back to fenced text — the post still builds, you just see the raw source instead of a diagram.

The Claude Code skill

The skill lives at github.com/morganp/dotfiles/tree/main/config/claude/skills/fsm. Claude Code auto-discovers skills from ~/.claude/skills/ and loads them on demand.

The skill triggers automatically when you describe anything involving states, transitions, or control flow: protocol implementations, UI flows, hardware FSMs, parsers, game logic. You describe the system in plain English and Claude generates the diagram.

The skill knows:

Full Mermaid stateDiagram-v2 syntax: plain states, display labels, transitions with events/guards/actions, composite (nested) states, choice pseudostates, fork/join for parallel regions, concurrent regions (--), notes, direction, and classDef styling
Graphviz DOT FSM conventions: Moore vs Mealy annotation, initial pseudostate arrow, accepting states as double circles
When to prefer each format: Mermaid for software/web docs, DOT for hardware/RTL

Example workflow

Describe the system:

"Draw the states for a TCP connection"

Claude produces:

Because the skill outputs a mermaid fenced block, you can paste it directly into a blog post and the Pelican plugin renders it automatically.

Installing the skill

mkdir -p ~/.claude/skills/fsm
curl -o ~/.claude/skills/fsm/SKILL.md \
  https://raw.githubusercontent.com/morganp/dotfiles/main/config/claude/skills/fsm/SKILL.md

Or clone the dotfiles repo and symlink:

git clone https://github.com/morganp/dotfiles ~/dotfiles
ln -s ~/dotfiles/config/claude/skills/fsm ~/.claude/skills/fsm

Syntax quick reference

Both formats can express the same FSM concepts, but use different syntax. The table below maps them side by side.

Concept	Mermaid `stateDiagram-v2`	Graphviz DOT
Graph declaration	`stateDiagram-v2`	`digraph FSM { ... }`
Default node style	automatic	`node [shape=circle]`
Left-to-right layout	`direction LR`	`rankdir=LR`
Comment	`%% comment`	`// comment`
Plain state	`StateName`	`StateName`
State with display label	`state "Label" as Name`	`Name [label="Label"]`
Initial pseudostate	`[*] --> State`	`__start [shape=point width=0.2]` + `__start -> State`
Final/accepting state	`State --> [*]`	`State [shape=doublecircle]`
Transition	`A --> B`	`A -> B`
Transition with event	`A --> B : event`	`A -> B [label="event"]`
Transition with action	`A --> B : event / action()`	`A -> B [label="event / action()"]`
Guarded transition	`A --> B : [guard]`	`A -> B [label="[guard]"]`
Composite (nested) state	`state S { ... }`	`subgraph cluster_S { ... }`
Choice pseudostate	`state C <<choice>>`	`C [shape=diamond]`
Fork pseudostate	`state F <<fork>>`	invisible node + multiple outgoing edges
Join pseudostate	`state J <<join>>`	invisible node + multiple incoming edges
Concurrent regions	`--` inside composite	parallel `subgraph` blocks

Project structure

~/Code/
├── morganp.github.io/              # blog source (main branch)
│   └── content/images/fsm/         # SVG cache (persists across make clean)
└── pelican-fsm/                    # github.com/morganp/pelican-fsm
    └── pelican/plugins/fsm_renderer/
        ├── __init__.py             # plugin entry point, signal registration
        └── preprocessor.py        # Markdown extension + preprocessor

~/.claude/skills/
└── fsm/
    └── SKILL.md                    # Claude Code skill definition

The combination is useful for any documentation that involves control flow: describe the behaviour, get the diagram from Claude, drop it into a post, and the plugin renders it at build time. No manual editing of diagram syntax, no copy-pasting between browser tabs.

Verilog Lint Skill for Claude Code

2026-02-22T12:00:00+00:00

I've been using Claude Code for RTL generation lately, and the missing piece was a tight feedback loop between code generation and linting. Writing Verilog by hand is tedious; having Claude generate it and immediately validate it with real tools closes that gap nicely.

What it does

The skill connects two open-source linters into an agentic write → lint → fix → re-lint loop:

Verilator (--lint-only -Wall) catches semantic errors: undeclared signals, bit-width mismatches, blocking assignments in always_ff blocks, multi-driven nets
Verible (verible-verilog-lint) enforces style: naming conventions, whitespace, port alignment, always_ff/always_comb discipline

When Claude generates RTL, the skill automatically:

Writes the code to a temp file
Runs both linters
Parses error messages with line numbers
Applies fixes and re-lints — up to 3 times
Reports clean status or surfaces a diagnostic table if errors remain

Why two tools

They complement each other. Verilator thinks like a synthesizer — it catches things that will fail elaboration or produce incorrect silicon. Verible doesn't simulate; it reads the source and checks against Google's SystemVerilog style guide. Together they cover both "will this work" and "is this readable".

Both are free and open source

Verilator: brew install verilator / apt install verilator
Verible: brew tap chipsalliance/verible && brew install verible (macOS), or grab a binary from the GitHub releases page

RTL patterns baked in

The skill includes reference patterns for mistake-free SystemVerilog: synchronous-reset flip-flops, always_comb combinational blocks, parameterized FSMs with typedef enum. Claude defaults to these when generating new modules, which avoids most of the common lint warnings before the first pass even runs.

Same pattern as WaveDrom

This follows the same skill format as the WaveDrom timing diagram skill — a SKILL.md file that gives Claude structured instructions, reference tables, and workflow steps. Both skills live in ~/.claude/skills/ and are picked up automatically by Claude Code.

The combination is handy for hardware work: describe a protocol, get a timing diagram, then generate and lint the RTL that implements it.

WaveDrom Timing Diagrams in Pelican with Claude Code

2026-02-20T12:00:00+00:00

WaveDrom is a JavaScript library that renders digital timing diagrams from a simple JSON-based format called WaveJSON. It's widely used in hardware documentation — you describe signal transitions in a compact string notation, and WaveDrom draws the waveform. This post covers two tools I've built around it: a Pelican plugin that renders diagrams at build time, and a Claude Code skill that generates WaveJSON from plain English.

The Pelican plugin

The plugin is at github.com/morganp/pelican-wavedrom, cloned to ~/Code/pelican-wavedrom — a sibling directory to the blog repo. It intercepts fenced ```wavedrom ``` code blocks before Pelican's standard Markdown processing, renders each one to an SVG using wavedrom-cli, caches the result by content hash in content/images/wavedrom/, and replaces the block with a standard image reference. Pelican then copies the SVG to output/images/wavedrom/ as a static asset.

SVGs are cached across builds — only diagrams whose source has changed are re-rendered.

Installation

The plugin requires wavedrom-cli globally via npm:

npm install -g wavedrom-cli

Then clone the plugin alongside your blog repo and install it into the Pelican virtualenv in editable mode:

git clone https://github.com/morganp/pelican-wavedrom ../pelican-wavedrom
source venv/bin/activate
pip install -e ../pelican-wavedrom --config-settings editable_mode=compat

The editable_mode=compat flag is required. Without it, modern setuptools editable installs use a path-hook mechanism that prevents Pelican's namespace plugin auto-discovery from finding the plugin.

Pelican 4.5+ auto-discovers namespace plugins — no changes to pelicanconf.py are needed.

Optional config

If wavedrom-cli is not on your PATH during the build (e.g. in a CI environment), set its full path in pelicanconf.py:

WAVEDROM_CLI = '/opt/homebrew/bin/wavedrom-cli'

Using it in a post

Write a fenced code block with the language set to wavedrom:

```wavedrom
{ "signal": [
  { "name": "CLK",     "wave": "p.....|..." },
  { "name": "Data",    "wave": "x.345x|=.x", "data": ["head", "body", "tail", "data"] },
  { "name": "Request", "wave": "0.1..0|1.0" }
]}
```

At build time (make html or make github) this becomes an SVG embedded in the page:

If wavedrom-cli is not found or rendering fails, the block falls back to a fenced json block — the post still builds, you just see the raw JSON instead of a diagram.

The Claude Code skill

The skill lives at ~/.claude/skills/wavedrom/SKILL.md. Claude Code auto-discovers skills from ~/.claude/skills/ and loads them on demand.

The skill triggers automatically when you describe anything related to timing diagrams, waveforms, or digital protocols — SPI, I2C, UART, AXI handshakes, clock enables, request/acknowledge patterns. You describe the signals in plain English; Claude generates the WaveJSON.

The skill includes:

The full WaveJSON wave-character reference (p, n, 0, 1, x, z, ., =, 2–9, |)
Signal properties (phase, period, node)
Top-level properties (edge, config, head, foot)
Group and spacer syntax
Edge annotation syntax for timing arrows between signals
Common patterns: SPI transactions, request/acknowledge handshakes, clock-with-enable, grouped signals

Example workflow

Describe the protocol:

"Draw an I2C start condition followed by a 7-bit address byte with ACK"

Claude generates the WaveJSON and explains the timing. Because the skill outputs a wavedrom fenced block (not just JSON), you can paste it directly into a blog post and the Pelican plugin renders it automatically.

WaveJSON quick reference

The wave string for each signal is a sequence of characters:

Char	Meaning
`p` / `n`	Positive / negative clock (with tick mark)
`0` / `1`	Logic low / high
`x`	Unknown / undefined
`z`	High impedance
`.`	Continue previous state
`=`	Multi-bit data (label from `data` array)
`2`–`9`	Coloured data states
`\\|`	Gap / break in time axis

A minimal diagram:

An SPI transaction with chip select:

A request/acknowledge handshake with an edge annotation showing propagation delay:

Project structure

~/Code/
├── morganp.github.io/          # blog source (main branch)
│   └── content/images/wavedrom/  # SVG cache (persists across make clean)
└── pelican-wavedrom/           # github.com/morganp/pelican-wavedrom
    └── pelican/plugins/wavedrom_generator/
        ├── __init__.py         # plugin entry point, signal registration
        └── preprocessor.py    # Markdown extension + preprocessor

~/.claude/skills/
└── wavedrom/
    └── SKILL.md                # Claude Code skill definition

The combination is useful for hardware documentation: describe a protocol in English, get WaveJSON from Claude, drop the block into a post, and the plugin renders it at build time. No manual JSON editing, no copy-pasting between browser tabs.

The same skill format is used by the Verilog lint skill — describe a module, get generated RTL, and the lint loop validates it automatically.

Top Museums for Families

2025-12-05T15:06:00+00:00

Beamish

Life Science Centre

Eureka: Children’s Museum Eureka: Science Museum

Eden Camp

Dynamic Earth

Reduce Rack Drum Kit Size

2025-12-05T14:50:00+00:00

For the Yamaha DTX8 the cymbals mount on to the horizontal drum rack tubes. A more compact setup can be achieved if the cymbal mounts are onto of the vertical tubes. Some drum racks already have this setup, typically on the lower end as it requires less harder to be supplied. It seems like a great way to save space if trying to fit a drum kit into your home!  Gibraltar have this clamp, to convert other drum racks with (1.5”) 38.1mm tubing.

Expanding Yamaha DTX8 Drum Kit

2025-12-05T14:43:00+00:00

TOM

Parts Required for adding 4th Tom (second floor tom) to a Yamaha DTX8 kit.

Mounting bracket for rack: Yamaha TPCL500 Tom Holder. UK supplier.

10” tom, on the DTX8 they are all 10”: Yamaha XP125T M.   Note are the Mesh heads(M), not the (X) heads.  UK supplier.

eBay might also be a good source for used components.

Adding a Cymbal

Cable splitting tom1 for tom1 single zone and a single zone splash cymbal.

Yamaha PCY10010-inch cymbal pad
Yamaha CYAT500 Cymbal Attachment  Splash £180 UK Supplier.

Alternatively for another crash or simply larger 13” pad a Yamaha PCY135A pad could be used.

Crash £200 UK Supplier.

Yamaha Drum App

2025-12-05T14:38:00+00:00

For Yamaha electronic drum kits (DTX) there is a ‘DTX Touch app’ for iPhone, iPad, Android that lets you more easily manage the kit sounds.

Command Line Disk Usage

2025-09-06T13:19:00+01:00

NCurses Disk Usage

A useful Command Line Iterface (CLI) for exploring disk usage:

ncdu

Example output.

ncdu 2.9.1 ~ Use the arrow keys to navigate, press ? for help
--- ... github.io --------------------------
  115.6 MiB [##################] /venv
   59.7 MiB [#########         ] /output
   47.6 MiB [#######           ] /.git
   46.1 MiB [#######           ] /content
    8.0 KiB [                  ]  .DS_Store
    8.0 KiB [                  ]  tasks.py
    8.0 KiB [                  ] /__pycache__
    4.0 KiB [                  ]  Makefile
    4.0 KiB [                  ]  readme.md
    4.0 KiB [                  ]  pelicanconf.py
    4.0 KiB [                  ]  python_search_category.py
    4.0 KiB [                  ]  python_search_and_replace.py
    4.0 KiB [                  ]  create_new_post.py
    4.0 KiB [                  ]  publishconf.py
    4.0 KiB [                  ]  .gitignore
    4.0 KiB [                  ]  CNAME

If you are using MacOS then brew can be used to install:

brew install ncdu

Disk Usage

The disk usage tool du is a simpler non interactive way of listing file sizes.

du -h -d 1
  60M   ./output
  46M   ./content
 8.0K   ./__pycache__
 116M   ./venv
  48M   ./.git
 313M   .

The -h gives human readable output, ie sizes in k, M, G TBytes.
thr -d 1 on MacOS limits listing to 1 directory deep. -scan be used to summarise the requested directory.

Tree

Another alternative is to use tree to list folde contents with the -hoption to give human readable file sizes.

tree -L 1 -h
[ 608]  .
├── [ 128]  __pycache__
├── [  19]  CNAME
├── [ 224]  content
├── [1.2K]  create_new_post.py
├── [2.8K]  Makefile
├── [ 28K]  output
├── [2.1K]  pelicanconf.py
├── [ 528]  publishconf.py
├── [1.3K]  python_search_and_replace.py
├── [1.7K]  python_search_category.py
├── [2.2K]  readme.md
├── [4.1K]  tasks.py
├── [ 224]  venv
└── [ 224]  venv_old

MacOS install tree with brew:

brew install tree

Book: Mastering the command line

2025-05-31T10:11:00+01:00

Mastering the command line like a hacker by Xiaodong Xu

The book focuses on bash and zsh, which is great since I use both of those shells.

The useful sections from the book include:

Zsh Completion

# ~/.zshrc
autoload -U compinit
compinit -i

source ~/dotfiles/zsh-autosuggestions/zsh-autosuggestions.zsh

The zsh-autosuggestions.zsh needs to be installed/downloaded from Github, adding as a seperate depo or adding as a submodule to your dotfiles depo.

History

BASH History

# ~/.bashrc
# Save 5000 lins of history, with the same scroll back in the terminal
HISTFILESIZE=5000
HISTSIZE=5000

# Do not save duplicate commands, ignore commands starting with a space
HISTCONTROL='erasedups:ignorespace'

ZSH History

# ~/.zshrc 
# Save 5000 lins of history, with the same scroll back in the terminal
SAVEHIST=5000
HISTSIZE=5000

# Do not save duplicate commands, ignore commands starting with a space
setopt HIST_IGNORE_ALL_DUPS
setopt HIST_IGNORE_SPACE

Using History

View the last 5 commands

# Bash
$ history 5
# Zsh
$ history -5

For zsh we can see the last time the command was run and the time taken with :

history -i -D

Alternative command to history:

fc

Searching History

The most common way is piping history through grep to search.

$ history | grep 'cmd'

Ctrl+r is another option which starts a reverse search through the history.

Ctrl+p and Ctrl+n can be used to scroll forwards and backwards through previous commands. Although for me the up down cursors workk mor enaturally.

Repeating Commands

Repeat the last command used (Bang Bang)

!!

great example is when you run a command but it fails because of require Superuser access.

$ cmd_that_needs_root
> fail
$ sudo !!
> yay!

Execute command 2 back.

!-2
#Note
!! => !-1

Execute command 100 from history

!100

Last Argument

!$ recalls the last Argument. typicall usage could be with mkdir and cd:

$ mkdir notes
$ cd !$

Better Python Iterators

2025-03-01T12:24:00+00:00

Pyhton can convert most (all) lists/collections into iterator objects, this is done by calling iter() ie

num_list = [1, 2, 3] 
num_iter = iter(num_list)  # Returns Iterator

Python in the background is calling the objects __iter__() method.

A typical method for returning an Iterator is using a for loop to compile/create the elements. However the draw back to this is that the for loop can not begin executing until the full iterator is created.
This could make it the program look like it has stalled while it compiles long and or complex iterator objects.

Generator Functions

Generator function allow an optimisation that it allows the use of the iterator after each element has been created. Generator functions return elemnts using yield instead of return on the complete list. The a benefit of this approach is that the full iterator never has to be held in memory at the same time, allowing much larger data sets to be analysed.

Generator Example

def my_generator(n):

    # initialize counter
    value = 0

    # loop until counter is less than n
    while value < n:

        # produce the current value of the counter
        yield value

        # increment the counter
        value += 1

Non-Generator Example

def my_nongenerator(n):

    # initialize counter
    value = 0
    this_list = list()
    # loop until counter is less than n
    while value < n:

        # produce the current value of the counter
        this_list.append( value )

        # increment the counter
        value += 1
    return this_list

Packaging Python Projects

2025-02-28T15:22:00+00:00

How to package a pythin script or project for distribution. Offical Docs are [here][python_package]. Packaging for pip requires use of a [build backend][], [Hatchling][] is the default for this example.

This run through uses the testPyPI.

Summary

Initialise Python project area: note: the build process also uses the gitignore to excluded the venv folder.

mkdir packaging_tutorial
cd packagin_tutorial
python3 -m venv venv
source venv/bin/activate
curl --output .gitignore "https://raw.githubusercontent.com/github/gitignore/refs/heads/main/Python.gitignore"

Create the folder structure:

packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── example_package_YOUR_USERNAME_HERE/
│       ├── __init__.py
│       └── example.py
└── tests/

__init__.py can be empty, but allows project to be imported in standard way.

pyproject.toml - directs pip how to build the project

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
  { name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.8"
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent",
]
license = "MIT"
license-files = ["LICEN[CS]E*"]

[project.urls]
Homepage = "https://github.com/pypa/sampleproject"
Issues = "https://github.com/pypa/sampleproject/issues"


[python_package]: https://packaging.python.org/en/latest/tutorials/packaging-projects/
[build backend]: https://packaging.python.org/en/latest/glossary/#term-Build-Backend
[Hatchling]: https://hatch.pypa.io/latest/

Generate Distrubution Archive

Update build

pip install --upgrade build

Build:

python3 -m build

This should create

dist/
├── example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl (Built Distribution)
└── example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz (Source Distibution)

Upload!

Create and store API token. Create Token, set scope to entire account.

Update twine

pip install --upgrade twine

Upload the files in dist

python3 -m twine upload --repository testpypi dist/*

Once Complete the uploaded package can be viewed here:

https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE.

Test install

python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-package-YOUR-USERNAME-HERE

Python Parsing XML

2025-01-05T13:31:00+00:00

Parsing XML with Python using the standard library xml.etree.ElementTree. It converts XML text into a tree of Element objects you can traverse and query.

Basic Parsing

import xml.etree.ElementTree as ET

data = '''<person>
  <name>Chuck</name>
  <phone type="intl">
    +1 734 303 4456
  </phone>
  <email hide="yes" />
</person>'''

tree = ET.fromstring(data)
print('Name:', tree.find('name').text)
print('Attr:', tree.find('email').get('hide'))

Parsing from a File

tree = ET.parse('data.xml')
root = tree.getroot()
print(root.tag)

Iterating over Children

for child in root:
    print(child.tag, child.attrib)

Use iter() to walk the entire tree recursively:

for elem in root.iter('phone'):
    print(elem.text.strip())

Accessing Attributes and Text

elem = root.find('phone')
elem.text.strip()       # text content
elem.get('type')        # attribute value (None if missing)
elem.attrib             # dict of all attributes

Finding Multiple Elements

# All direct children matching a tag
root.findall('item')

# XPath-style expressions
root.findall('./items/item')
root.find('./items/item[@id="1"]')

Handling Namespaces

XML namespaces appear as {uri}tag. Register a prefix to keep queries readable:

ns = {'ns': 'http://example.com/schema'}
root.find('ns:item', ns)

For larger or more complex XML, consider lxml which is faster and supports full XPath:

pip install lxml

Python Web Parsing

2025-01-05T11:15:00+00:00

For parsing web pages with Python, BeautifulSoup is a helpful library. To install:

pip install beautifulsoup4

You also need a way to fetch the page. The standard library urllib works fine for simple cases; requests is more ergonomic for anything complex:

pip install requests

Basic Usage: Extract all links

import urllib.request, urllib.parse, urllib.error
from bs4 import BeautifulSoup
import ssl

# Ignore SSL certificate errors
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE

url = input('Enter URL: ')
html = urllib.request.urlopen(url, context=ctx).read()
soup = BeautifulSoup(html, 'html.parser')

# Retrieve all anchor tags
tags = soup('a')
for tag in tags:
    print(tag.get('href', None))

Finding Elements

BeautifulSoup provides several ways to locate content:

# First matching element
soup.find('h1')
soup.find('div', class_='content')
soup.find('a', id='main-link')

# All matching elements (returns a list)
soup.find_all('p')
soup.find_all('a', class_='external')

# CSS selector syntax
soup.select('div.article > p')
soup.select_one('#footer a')

Extracting Text and Attributes

tag = soup.find('a')

tag.text          # visible text content (strips tags)
tag.get_text()    # same, with optional separator
tag['href']       # attribute access (raises KeyError if missing)
tag.get('href')   # safe attribute access (returns None if missing)

Using requests Instead of urllib

import requests
from bs4 import BeautifulSoup

response = requests.get('https://example.com')
soup = BeautifulSoup(response.text, 'html.parser')

for link in soup.find_all('a'):
    print(link.get('href'))

Note: always check response.status_code == 200 before parsing, and respect robots.txt.

Pelican New Post script

2025-01-03T16:44:00+00:00

In the aim of keeping the navigation of the Blog posts clean, I have limited my self to a few general categories, but remeberign them while editing in vim and not creating typos is a pain. Therefore I have added the category selection to my pyhton script for creating the new markdown files.

When running this file from the command line, top level of my pelican project, it first prompts for a category selection then requests The title of the post. The new file is created and correctly formated for a Pelican markdown post.

#!/usr/bin/python3
# coding=utf-8

# CLI for creating a new markdown post

import html

from datetime import datetime

# datetime object containing current date and time
now = datetime.now()

# dd/mm/YY H:M
dt_string = now.strftime("%Y-%m-%d %H:%M")
dt_string_simple = now.strftime("%Y-%m-%d")

# Create dictionary of categories, ask for user selection.
cat_dict = {1:"Cooking", 2:"Engineering", 3:"Home", 4:"Outdoor", 5:"Photography", 6:"Tech"}
print( cat_dict )
post_cat = input("Enter Post Category :")
post_cat = int(post_cat)

#Request title of blog post
post_title = input("Enter Post Title : ")

post_title = html.escape(post_title) # sanitize
post_title_safe = post_title.replace(' ', '_')

new_post_name = dt_string_simple + '_' + post_title_safe

this_file_name = "./content/posts/"+new_post_name+".md"

with open(this_file_name, "w") as file:
    file.write("Title: " + post_title + "\n")
    file.write("Date: %s \n" % dt_string)
    file.write("Category: %s\n" % cat_dict[post_cat])
    file.write("Tags: python\n")
    file.write("Author: morganp\n")
    file.write("Status: draft\n")
    file.write("<!--to publish change draft to published-->\n")

print(this_file_name)

Python Base Types

2025-01-02T18:09:00+00:00

Making notes as I work through Dr Chucks Python for Everyone course on Coursera.

There are 3 main types in Python:

Lists []
Dictionaries {}
Tuples ()

List

Lists are mutable, ie elements can be changed.
Creation of a list:

emptylist = []
thislist  = ["A","B","C"]
print( thislist )
  ['A', 'B', 'C']
print( thislist[1] )
  B

Dictionary

Dictionaries are key value pairs.
Creation of Dictionary

emptydict = {}
thisdict  = {0:"A", 1:"B", 2:"C"} 
print( thisdict )
  {0: 'A', 1: 'B', 2: 'C'}
print( thisdict[1] )
  B

Tuple

Tuples are unmodifiable lists. elements can not be changed or reordered.
Creation of Tuple.

emptytuple = () # This is of no real use as imutable
thistuple  = ("A", "B", "C")
print( thistuple )
  ('A', 'B', 'C')
print( thistuple[1] )
  B

Modify Pelican theme

2025-01-02T16:53:00+00:00

First figure out which theme you are using. List installed themes via:

% pelican-themes -l
simple
notmyidea

pelicanconf.py does not set a THEME, therfore defaulting to notmyidea.

The template locaions are (update your python version as appropriate):

cd venv/lib/python3.13/site-packages/pelican/themes/notmyidea/templates

At a minimum a theme must contain these files, which could be altered in your local copy of the theme.

└── templates
    ├── archives.html         // to display archives
    ├── period_archives.html  // to display time-period archives
    ├── article.html          // processed for each article
    ├── author.html           // processed for each author
    ├── authors.html          // must list all the authors
    ├── categories.html       // must list all the categories
    ├── category.html         // processed for each category
    ├── index.html            // the index (list all the articles)
    ├── page.html             // processed for each page
    ├── tag.html              // processed for each tag
    └── tags.html             // must list all the tags. Can be a tag cloud.

Pelican Site add Tags and Categories list

2025-01-02T15:39:00+00:00

I think it improves website usability when they are navigatable via the URL.

For example when viewing Posts under the caetegory 'Tech' ie https://lizard-spock.co.uk/category/tech.html,

removing the category and viewing https://lizard-spock.co.uk/category/ should list the possible categories.

The page is created by pelican but it is placed as :

https://lizard-spock.co.uk/categories.html

Not

https://lizard-spock.co.uk/category/index.html

To remedy this, modify your pelicanconf.py Adding in some page mappings.

## Adding template pages creating /tag/index.html from tags.html
TEMPLATE_PAGES = {'tags.html': 'tag/index.html'}

The Above takes the tags.html template and makes it available via example.com/tag

Japanese Garden 10 Years on

2025-01-02T13:02:00+00:00

An update to the Japanese Garden, aorund 10 years after it was built.
The ground cover is being removed in some of these images for the next iteration.

The large panorama is 270 degree view of 3 sides of it.

Various iterations of ground cover, last one was partially paved.

Older pictures during Construction

Then main structure nearly complete

Leveling up the roofs for the seating area. The large panorama is a 270 degree view of 3 sides of it.

Python Regular Expressions

2024-12-23T10:21:00+00:00

Python Regular Expressions Quick Guide:

^        Matches the beginning of a line
$        Matches the end of the line
.        Matches any character
\s       Matches whitespace
\S       Matches any non-whitespace character
*        Repeats a character zero or more times
*?       Repeats a character zero or more times 
         (non-greedy)
+        Repeats a character one or more times
+?       Repeats a character one or more times 
         (non-greedy)
[aeiou]  Matches a single character in the listed set
[^XYZ]   Matches a single character not in the listed set
[a-z0-9] The set of characters can include a range
(        Indicates where string extraction is to start
)        Indicates where string extraction is to end

Based on Dr Chucks from Python for Everyone course.

Usage:

import re

list_of_strings = re.findall(<pattern>, string)

Adaptive Filter Theory Notes 1

2024-12-19T11:04:00+00:00

Notes From Reading Adaptive Signal Theory (5th Ed) by Simon Haykin

Three Basic Kinds Of Estimation

Filtering - Extraction of Current and previous information. RealTime operation.
Smoothing - Data after the time of interest is used. Posteriori operation.
Prediction - forcasting for some time in the future. RealTime operation.

Filter optimization is useful to think of minimising the mean-square-error.

For stationary inputs the Wiener filter is considered optimal in mean-square-error sense.

Plots of the mean-square value of the error signal versus the adjustable parameters of the linear filter is known as the error-performance-surface. The min point on this is the Wiener solution.

Wiener Filter is no good with moving signals, or precense of noise. Kalman Filters are useful in this sitation.

Node Red vs Home Assistant

2024-10-24T15:58:00+01:00

Node Red vs Home Assistant

Which is better* ?

*better: CPU/RAM efficient, easier to learn and or offer better support of devices

Materials used for comparison video this review, end with the conclusion:

Home Assistant and Node-RED have their merits when it comes to automating your home. The choice ultimately depends on your preferences and specific requirements. While Home Assistant offers a user-friendly interface and integration within a single system, Node-RED provides versatility, the ability to connect to multiple Home Assistant instances and other APIs. Consider your needs, technical proficiency, and desired level of customization to determine which platform suits you best. Let us know your thoughts in the comments.

Proxmox Plex Container

2024-10-24T13:10:00+01:00

With Proxmox installed time to setup Plex in a container, and migrate from Synology NAS.

I am following these guides for plex setup, and there following guide for synology to proxmox migration.

Starting with ProxMox

2024-10-24T12:56:00+01:00

Having decided that Proxmox is the way forward to manage docker and ivrtualisation outside of the synology NAS. i need to figure out how to install , use and manage proxmox.

For the first instance I will be following the guide to Proxmox.

There is another good tutorial here which covers installing proxmox and then creating a virtual machine for home assistant.

Note from :

> You manage a Docker instance from the host, using the Docker Engine command-line interface. It is not recommended to run docker directly on your Proxmox VE host. If you want to run application containers, for example, Docker images, it is best to run them inside a Proxmox QEMU VM.

Beelink N200 Proxmox and Plex

2024-10-24T11:43:00+01:00

To improve the Plex transcoding options and off load the computation from the NAS, the plan is purchase a BeeLink EQ13 Alder Lake N200 16GB Ram and 500GB Drive, currently for sale at £215.

The Beelink will then have proxmox installed as the main operating system. A docker container for Plex and the other dockers that are currently hosted on the NAS box.

Theguide for plex install I will be following here.

A virtual machine for Hssistant OS can also be installed to run HomeAssistant.

Cat8 T-568

2024-10-21T13:31:00+01:00

Cat 8 Wiring, comes in 2 variants T-568A and T-568B.

Cat8 replaces the need for crimping tools with field termination kits. Both ends need to wired the same otherwise there is no perfomance difference.

Synology Connecting Across VLAN with active VPN

2024-10-16T11:30:00+01:00

When a Synology NAS creates a VPN connection it overides the default gateway, except for devices listed as contained within its subnet. According to the a post on the synology forum even if the subnet is changed to 255.255.0.0 it will not see devices on another VLAN. It feels like a subnet mask of 255.255.255.0 is hardcoded.

For Allowing my Synology NAS to create a VPN connection and see device on my VLANS I had to add a static route defining a gatweway for the VLAN IP/subnet.

Network Destination: 192.168.107.0  # This is the VLAN 107
Netmask            : 255.255.255.0  # Standard netmask for a VLAN
Gateway            : 192.168.100.1  # Gateway for the Synology NASs VLAN
Interface          : physical interface that the Synology NAS uses to connect to the VLAN

TeX hyphenation

2024-10-14T14:45:00+01:00

When TeX/LaTeX is fully justifying text there are times when it could do better but it does not know how to hyphenate certain words. Here we can give it guidnace on how to split words.

For example (insert into the pre-amble):

\hyphenation{acro-nym}

Multiple hyphenation points can also be defined, and for related words:

\hyphenation{ac-ro-nym ac-ro-nym-ic a-cro-nym-i-cal-ly}

The hyphenation point can be inserted manually with a \-, but it is best to setup in the pre-amble and keep all the layout rules together.

acro\-nym

Preventing Hyphenation

Preventing hyphenation can be done by decalring in the pre-amble without a hyphen or inline with an \mbox command

\hyphenation{automobile}

this will stop hyphenation of inline text \mbox{automobile}

Global Hyphenation Control

Use the hphenat package to prevent all hyphenation

\usepackage[none]{hyphenat}

There are some better ideas on this TeX SO Question.

TeX Paragraph Box

2024-10-11T14:18:00+01:00

parbox is a LaTeX command used to place a box around text.

Remeber that optional arguments are in [] (Square brackets)

Typical usage is :

\parbox[alignment]{width}{text}

The options are:

alignment:
  t - Top alligned
  c - vertically centered
  b - Bottom alligned
  s - Stretch to fill vertically

width fractional value followed by ISO units of mm, cm and in are supported

Example:

\documentclass{article}
\begin{document}
  \parbox[b]{2.3cm}{b for bottom aligned}
\end{document}

If a large amount of text is to be placed in the box minipage is preffered over parbox.

\documentclass{article}
\begin{document}
  \begin{minipage}{2.3cm}
    minipage not parbox
  \end{minipage}
\end{document}

minipage supports all the arguments of \parbox, as well as \footnote

\documentclass{article}
\begin{document}
  \begin{minipage}{5cm}
    minipage not parbox \footnote{this is a foot note}.
    Second Line with another foot note \footnote{Another foot note}.
  \end{minipage}
\end{document}

LaTeX macros

2024-10-10T14:17:00+01:00

LaTeX macros can be used as simple text replacments for example:

\documentclass{article}
\newcommand{\LUG}{LEGO User Group}
\begin{document}
  \section{Welcome to the \LUG}
\end{document}

More Advanced usage allows LaTeX macros to be used like functions:

\documentclass{article}
\newcommand{\LUG}[1]{\textbf{#1} LEGO User Group}
\begin{document}
  \section{Welcome to the \LUG{tartan}}
\end{document}

Tools for Technical Writing

2024-09-10T10:17:00+01:00

WYSIWYG editor for LaTeX lyx, and a manager for Bibliography JabRef.

Lyx Tutorial: Lyx mac Guide

JabRef Tutorial: Getting Started

Tools avialable via home brew:

brew install lyx
brew install jabref

Bike Chain Cleaning

2024-06-14T12:27:00+01:00

Chain Cleaning method:

 Clean the chain with WD40 (water dispersant).
 Wipe dry with kitchen roll. 
 Spray with Comma White Grease and wipe clean again.

The chain should be lubricated on the moving parts of the chain, not the surface in contact with cogs.

Pyhton_virtual_env

2024-05-30T16:03:00+01:00

Creating/Setup a pyhton virtual enviroment called 'venv'

python3 -m venv venv

Load the virtual env called venv

source venv/bin/activate

RealPython Guide, Docs.

Convolution in Python

2024-05-03T14:25:00+01:00

Convolution in Python, for merging filter responses, creating pascals triangle ...

import numpy as np

a= np.array([1,1])
b= np.array([1,1])

c =np.convolve(a, b)
c
> array([1, 2, 1])

Perforce Update files in a Shelve

2024-04-30T11:04:00+01:00

Perforce can temporarily checkins of changes that you might want to share with others before fully commiting them to the code base. These P4 Shelves have some properties that seem undesirable for a revision control system. They are not imuttable.

From there nature they are temporary but they can also be altered and maintain the same changelist number. Solution based on this SO answer.

Lets create file a.txt with some default content, and create a shelve.

echo "File a - line 1" >> a.txt
p4 add a.txt
p4 shelve ...

> Change 3265397 created with 1 open file(s).
> Shelving files for change 3265397.

Remeber the Changelist number for the shelve, we will refer to it as \<change#>. Now lets modify a and create a b.txt.

p4 edit a.txt
echo "File a - line 2 after intial shelve" >> a.txt
echo "File b - line 1 Missed in first shelve" >> b.txt
p4 add b.txt

p4 reopen -c <change#> b.txt

> b.txt#1 - reopened; change 3265397

p4 shelve -r -c <change#>

> Shelving files for change 3265397.
> add //./a.txt#1
> add //./b.txt#1
> Change 3265397 files shelved.

Python merge PDFs

2024-04-22T18:49:00+01:00

Using python script to merge pdfs together.

Install package

pip install pypdf

Script:

from pypdf import PdfWriter

pdfs = ['file1.pdf', 'file2.pdf', 'file3.pdf', 'file4.pdf']

#merger = PdfMerger()
merger = PdfWriter()

for pdf in pdfs:
    merger.append(pdf)

merger.write("result.pdf")
merger.close()

source

Pythonista pip install pelican

2024-04-20T12:04:00+01:00

On the journey towards publish static site generator blog posts from iPadOS, my next step after installing stash on pythonista is uisng pip to install the pelican library.

Pythonista using stash for pip

2024-04-19T17:04:00+01:00

To run pip in pythonista we need to install stash first.

See stash page sfor latest details, at time of install I had to run this from the pythinista terminal:

import requests as r; exec(r.get('https://bit.ly/get-stash').content)

Then to start stash from a new (restart pyhtonista app) find and run the launch_stash.py script

there will then be a second terminal with the stash command line open up

Python read a CSV file

2024-04-19T12:34:00+01:00

Python example for reading data from a csv file.

import csv
with open(data.csv', newline='') as csvfile:
    spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
    for row in spamreader:
        print(', '.join(row))

Import csv into a numpy array.

import numpy as np
import csv
with open('data.csv', 'r') as f:
  reader = csv.reader(f)
  data   = list(reader)
# data_array = np.array(data)  # Conversion for strings
data_array = np.array(data, dtype=float) # Conversion for doubles

# Print first 10 data elements.
for a in range(0,10):
  print( data_array[a] )

Outputs:

source

Python Sinewave

2024-04-19T12:34:00+01:00

Python example for creatign and plotting a sinewave:

# coding: utf-8

import numpy as np
import matplotlib.pyplot as plt

fs   = 48000
freq = 1000 #Hz
amp  = 1.0 # Linear Amplitude
t    = 100/fs # Seconds sample length

amp_db = 20*np.log10(amp)
file_name = 'sine_%dHz_%4.2f_amp' % ( freq, amp_db)
label_name = "Sinewave %dHz %5.2fdB" % (freq, amp_db)

#samples = np.linspace(0, t, int(fs*t), endpoint=False)
samples = np.arange(t * fs) /fs

signal =amp * np.sin(2 * np.pi * freq * samples)

fig, ax = plt.subplots()
ax.plot(signal, label=label_name)
ax.set_title('Sinewave')

plt.legend()
plt.show()
plt.savefig(filename + '.png')

Generates and saves this plot

To export the 'signal' data as a CSV file:

import csv
with open(file_name+'.csv', 'w', newline='') as csvfile:
  f_writer = csv.writer(csvfile, delimiter=' ',quotechar='|', quoting=csv.QUOTE_MINIMAL)
  f_writer.writerows(map(lambda x: [x], signal))

*.csv output:

0.0
0.13052619222005157
0.25881904510252074
0.3826834323650898
0.49999999999999994
0.6087614290087207

"Home Directory File Structure"

2015-10-22T10:32:44+01:00

Apples default directory structure is :

/Users/username
├── Desktop
├── Documents
├── Downloads
├── Library   # Hidden by default
├── Movies
├── Music
├── Pictures
├── Public

My current setup After adding Dropbox, dotfiles stored on github, Code, and user level applications folder:

/Users/username
├── Applications
├── Code
├── Desktop
├── Documents
├── Downloads
├── Dropbox
├── Library
├── Movies
├── Music
├── Pictures
├── Public
├── dotfiles

At present though my Dropbox is a mess of some documents, some code and lots of ebooks. Free Dropbox does not have enough space for me to the entire home directory. Considering a BtSync pro account which allows selective sync. BtSync will allow me to set the root as my home directory and select which folders from that to sync.

I have started using USB flash drives again, and have found unison to be a useful tool for syncing local drives to each other.

Me example unison sync (USB drive is called 'Dropbox'):

unison ~/ /Volumes/Dropbox/Unison/ -fat -auto -links true \
-path Code      \
-path Documents \
-path Dropbox

#-fat Work With FAT filesystem (ThumbDrive)
#-auto Accept default action for non-merges
#-links true follow symlinks

Now that the 'Dropbox' root is my home directory I can reorganise. Books should become a top level folder, and share a place along side Music and Movies.

Dropbox is kept but mainly used for sharing temporary files with others.

/Users/username
├── Applications
├── Books
├── Code
├── Desktop
├── Documents
├── Downloads
├── Dropbox
├── Library
├── Movies
├── Music
├── Pictures
├── Public
├── dotfiles

Dropbox: sending large files BT Sync: Synchronising files (eBook collection) Unison: Synchronising local drives (Thumbdrive to local documents/ebooks) ReadyNAS: Remote access to larger volume drives (Movies and TV Collections) Above could be a BT Sync non populated folder

"JapaneseGarden"

2015-10-10T12:50:55+01:00

First step creating the retaining wall, to become a raised bed.

"Potting Bench"

2015-10-10T12:23:15+01:00

Homemade potting bench, using 15 2.4M Fence boards (£45).

Note for ease of building the height was 1.2M, half a 2.4 meter board, this is too high.

"Self Watering Propagator"

2015-10-10T12:04:12+01:00

Propagator hack using some seed trays and capillary matting.