lochsh

Pandaí or "pandy" for a tin mug or jug

2026-02-25T00:00:00+00:00

Childhood memories

My mother was talking about her childhood summers in rural Donegal, and used the word "pandy" to describe the tin drinking vessels she was often tasked with bringing to the men out working, along with a pail of water from the spring well to fill the vessels from. My culturally hungry ears pricked; could this be a Gaelic word? The initial p- marks it as a loan word — but from which language, and with what meaning?

My grandparents and two of my granny's brothers, with my uncle as a young boy. My uncle is drinking from a pandaí. The men, I am told, are drinking milky tea from glass bottles.

The word pandaí does not seem to appear in any major Irish dictionaries, but searching the digitised parts of Ireland's National Folklore Collection yields a few usages in Donegal. A selection:

From near Creeslough:
- Tháinic sí annsin agus shín sí an pandaí dó agus d'ól se achan braon a bhí
- "She came there and passed the pandy to him, and he drank every drop"
From near Kilcar
- Gheibheadh siad baisín céad uair agus cuireadh siad gráinín ann. Go minic chuireadh siad dhorn de min bhuidhe fríd. Chuireadh siad gráinín soda agus gráinín salainn isteach leobhtha annsin. Chuireadh siad pandaí blaithche isteach annsin agus mheasgadh siad na ceithre rudaí le chéile.
- A description of how to make soda bread; pandaí blaithche = "pandy of buttermilk".

A pandaí made by John Doherty, taken from Conor Thomas Caldwell's PhD thesis

My family only called the small drinking vessels "pandies", with larger tin vessels (as used for getting water from the well or collecting milk from the cows) called pails or buckets. There are examples of "pandy" also being used for these larger vessels:

near Glendowan
- "When a heifer calves you are to put a palm branch and a penny at the bottom of the pandy when you are milking her for the first time. This saves her from witchcraft."

These corroborating examples are pleasing, but do not get us any closer to understanding the origin of the word. There are a few usages of the word with divergent meanings that perhaps hold the key: in Munster, "pandy" appears to refer to mashed potatoes (see "poundies" in Ulster¹), and some sources also use it to refer to receiving a beating. In fact, we find a version of pandaí with slenderised consonants as peaindí² in Ó Dónaill's dictionary, with meanings "tin mug" and "mashed potatoes (with milk and butter)".

What do tin mugs, mashed potatoes, and physical beatings have in common? The clue is in the Ulster word "poundies" for mashed potato with sybies: all three involve pounding! Tin mugs are hammered into shape, potatoes are pounded into mash, and alas schoolchildren of yore were routinely whacked. It would seem to me that "pound" was borrowed into Irish to make pandaí, where in this instance the suffix -aí makes it "thing that is pounded" or (pleasingly) "poundee" — and then from there it was retained in some Hiberno-Englishes as "pandy".

To demonstrate the pounding: travelling tinsmiths would make things like pandies to sell. You can watch Johnny Doherty make one in the 1972 documentary Fiddler on the Road:

An alternative etymology

I was pleased with my above proposed etymology, but a subsequent discovery has me questioning it.

Collins' English dictionary defines "pandy" as "(in schools) a stroke on the hand with a strap as a punishment", and notes the term is primarily used in Scotland and Ireland³. The etymology is proposed as deriving from the imperative pande manum, Latin for "hold out [your] hand". This seems to have been issued to pupils by teachers, at a time when Latin was still used in schools, as described in James Wilson's Early Recollections of Life at King William's College on The Isle of Man. Both "pandy" and pande manum are used to refer to this punishment in various English language texts⁴.

So did "pandy" come to Irish via this restricted meaning, and spread in usage to other things that were struck? Or does the word "poundies" suggest that the usage for mashed potatoes at least evolved separately? I do stand by the idea that the tin mugs take their name from being struck during their manufacture, but whether this came from English "pound" or "pandy" (for a school beating), I cannot say.

Usages of pandaí or "pandy"

Map of uses in Ireland of pandaí or "pandy". The markers have been somewhat roughly placed. The only usages I could find in Scotland or the Isle of Man were in English and referred to the school punishment.

The Munster usage for a beating describes a horse's feet crushing a fox as having "made a pandy of him", which might just be referring to getting mashed like a potato.

Below is a list of usages of pandaí or "pandy" to mean something along the lines of "tin mug". All are from Donegal, except one from Mayo.

In Seán Ó hEochaidh's Sean-chainnt Theilinn (1955), pandaí is glossed as "a tin pot", and used in the saying Tá sé go h-oiread an phandaí. If I understand correctly this means "it's as big as a pandy" and is used to describe small tasks, or tasks near their completion.
In Pól Ó Seachnasaigh's Eagrán de na scéalta idirnáisiúnta ó na Cruacha Gorma a bhailigh Seán Ó hEochaidh do Choimisiún Béaloideasa Éireann i 1947 agus 1948 (2012), stories collected from the Bluestacks by Seán Ó hEochaidh are reproduced. Story 26:
Dúirt an seanduine leis an bhean ar ais go gcaithfeadh sí éirí, agus an bhó a bhleán, bhí bó ann i ndiaidh breith, agus pandaí den bhainne a thabhairt dó, nó nach gcuirfeadh sé isteach an oíche.
"The old man said to the woman again she must get up, and milk the cow, the cow was after giving birth, and bring a pandy of milk, or he wouldn't pass the night."
In a song collected in the Bluestacks, published in Béaloideas, Iml. 68 (2000)
In Gerard Stockman's The Irish of Achill, Co. Mayo (1974), pandaí is glossed as "an aluminium mug"
In Pádraig Ó Baoighill's writing, including in Srathóg Feamnaí agus Scéalta Eile (2001): Ó bhreacadh na maidne bhí fear an oileáin ina shuí agus pandaí de tae dhubh déanta aige. "[...] and he made a pandy of black tea."
In Conor Thomas Caldwell's 'Did you hear about the poor old travelling fiddler?' – The Life and Music of John Doherty (2013)
In this inscription in Edenfinfreagh, telling the story of John Doherty's brother Mickey escaping violence from Black and Tans by making a pandaí on the spot to demonstrate he was just a poor tinsmith.
Diarmuid Ó hAirt's Cnuasach Conallach: A Computerized Dictionary of Donegal Irish defines it as Soitheach stáin ("tin vessel"), and uses sources collected from The Frosses, Lettermacaward, and Glencolmcille.
In these interviews in Teelin and Cloghan.
In a song collected in Patrick MacGill's Songs of Donegal (1921). Page 19: "In all things handy/Thatching a haystack or mending a pandy"
In Seaghán 'ac Meanman's works, including in Mám Eile as an Mhála Chéadna (1954): Níorbh' fhada go dtáinig an chomharsanach a ba deirean-naighe a bhí astigh an oidhche roimh ré, agus bhí pandaí bainne leis. "[...] and he had a pandy of milk with him."
In Joy Elliott's Derby to Donegal – by design (2011): "Inside I was invited to a ‘pandy’ of tea. A pandy was a tin mug, usually blackened from being nudged into the fire, so tea ended up being stewed this way."
In Brighid "Biddy" McLaughlin's Tales of a Patchwork Life (2024): "a tin pandy made by Irish travellers that my son Johnny still drinks from"
Referring to a metal trophy

Other usages can be found by searching duchas.ie. The National Corpus of Irish also records "pandy" in a couple audio interviews that I haven't listed above.

The panda in the room

I should mention that "panda", for the animals, has been borrowed into Irish and the plural is pandaí. This is of course unrelated etymologically! 🐼

Personally I've only ever called it "champ". I've seen "poundies" in Peadar O'Donnell's writing. Possibly it is used outside Ulster too, and it might not always refer to mashed potatoes and sybies. ↩
I haven't found any clear record of anyone using this form for tin mugs. There are a couple usages of it in The National Corpus of Irish but I'm not sure what they're referring to. The first one is a food, I don't know about the second. ↩
Thankfully corporal punishment was a thing of the past when I went to school, but my parents both received the belt as punishment. They had no recollection of the term "pandy" ever being used in relation to it. It is recorded in the DASG fieldwork in Inverness. ↩
A non-exhaustive list of usages referring to hitting the hands with a strap or cane:
- 1715, Scotland, pande manum: Sermon preached by Mr. James Rows (sic), in St. Geil's Kirk at Edinburgh
- 1833, Scotland, pandies: John Kennedy's Geordie Chalmers; or, the Law in Glenbuckie
- 1863, England, pandied: Charles Kingsley's The Water-Babies
- 1917, Ireland, pandies: James Joyce's A Portrait of the Artist as a Young Man
↩

Goidé mar a deirtear "frog" i nGaedhilg?

2026-02-11T00:00:00+00:00

Cuairteoir gan iarraidh: an uninvited guest

Two months ago I was sitting on the sofa cuddling my cat when, out of the corner of my eye, I seen something small and dark hop into the room through the open doorway. I knew I'd seen a frog, but my brain was yet to accept this unlikelihood. I turned my head to see the dark shape on the floor, still now. Then it hopped again: there was a frog in the house! The wee lad was massive as well, or such was my perception, faced with the intrusion as I was.

We transferred him safely outside. Before he leapt away into the darkness, our eyes met, and I understood the task he had bequeathed me: I knew I must find all the Gaelic words for frog.

A map of words for frogs across the Gaelic world

Above is a map showing attested words used by local people for "frog". Zooming out will reveal datapoints in Nova Scotia. The main sources are:

Wagner, H. (1958-1969), Linguistic Atlas and Survey of Irish Dialects (LASID), Dublin Institute of Advanced Studies
Digital Archive of Scottish Gaelic (DASG). University of Glasgow <dasg.ac.uk>
The Schools' Collection, National Folklore Collection, University College Dublin <duchas.ie>
Tobar an Dualchais <tobarandualchais.co.uk>, Sabhal Mòr Ostaig
Dòrlach's fieldwork, kindly shared by Àdhamh Ó Broin <dorlach.scot>

The markers can be filtered by source and by word category using the checkboxes below the map. Clustering can also be enabled or disabled. When disabled, the remaining clusters are co-ordinates for which there is more than one data point.

The GeoJSON file containing the data can be downloaded here, licensed under CC BY-NC-SA 4.0.

A map showing recorded usages of words for frog, with categories of words grouped together (e.g. mula-mhàgag displayed as mial-mhàgain, liospán displayed as lisbín). Nova Scotia exclusively had màgan for frog.

The goal with the words included in the map is to have traceable examples of local native speakers using each word. I am keen to not allow this goal to unnecessarily exclude areas where the local language died. Where a dictionary is the only source of a word, I have not included it, but will often mention it in the text below. For some words, there are enough secondary sources that it feels right to include it on the map. These secondary sources are often from non-native speakers who were experts in a particular area's language, but which don't name a specific speaker and only refer to a broad area. There is some judgement involved in what to include and what to exclude, and I hope my reasoning is made clear both in the details of each datapoint, and in the writing below.

Click for more information about the sources and data

Resources like the LASID and DASG are based on fieldwork designed to record the words local people used in everyday speech. Materials in Ireland's National Folklore Collection, and those used from Tobar an Dualchais, are largely recordings of storytelling or other lore. Storytelling, particularly for a recording audience, can be in a higher register than every day speech¹. This is not to say that words taken from these resources lack authenticity, just that their context differs from that of words taken from conversation- and questionnaire-based linguistic fieldwork.

Other sources are from books and newspaper articles, where the author was either a native speaker of the local language, or was reporting on the local language.

For sources like The Schools' Collection in Ireland's National Folklore Collection, the linguistic background of the informants is not made explicit as in sources like the LASID. If I ever have reason to believe the informant might not be a native speaker or be a native speaker from somewhere else, I have included a note. I have not included all examples of frog from The Schools' Collection as there are so many!

I do not intend for the datapoints to indicate that frogs were exclusively called a particular word in a place, or that a word was exclusively used for frogs (e.g. leumachan is here recorded as being used for some beach insect or crusteacean). Many of the words recorded might have been supplementary to others. Additionally, much of the data is from the mid 20th century and as such may not reflect current local vocabulary. Indeed, the local language has sadly died in many of the places included. I hope that my work here can celebrate dialectal diversity, preserve the existence of lost words, and provide a fun way to engage with linguistic heritage.

Toads

Some of the words provided are cited as meaning "toad" by other sources. Not everyone has a clear linguistic distinction between "frog" (for me, frogs have shiny skin and jump) and "toad" (for me, toads have dry knobbly skin and crawl)². Not everyone's distinction will be the same, especially across languages. Some of the words found here describe a creature as a crawler, which certainly evokes toads for me. If you see a word cited as meaning "frog" that for you means "toad", please bear inter-speaker and geographic variation in mind, as well as the way words can evolve over time.

Although words specifically used for toads are also of interest, I have limited the scope of this project to words used for frogs.

Phonetic transcription

The LASID transcriptions are shown with narrow phonetic transcription brackets e.g. [Lɪːsḳɑːn´]. This is in accordance with the source material's explicit description of the transcriptions as phonetic. The narrowness of the transcriptions varies a little; all fieldworkers seem to aim to be very narrow in terms of vowel notation, with a detailed vowel chart with many labelled points provided. A spectrum of consonant palatalisation is allowed for in the notation, and various non-phonemic fortis/lenis consonant contrasts, alongside the phonemic ones. However, some details seem to be inconsistently recorded, like lack of aspiration on plosives (always shown on Scottish transcriptions, but only sometimes shown on e.g. /sk/ sequences, where I'd consistently expect an unaspirated /k/), and velar and palatal off-glides (seemingly only sometimes shown, but often missing from places I would expect to hear them, e.g. in Conamara speaker's pronunciation of the language's endonym). Devoicing of consonants seems rarely recorded. It's not clear that there's any provision for recording approximant realisations of slender r. Around Gaoth Dobhair I have certainly heard something like [j] for /r'/, which possibly is recorded in the LASID as /r′′/ to indicate "strong palatalisation".

I have added my own IPA transcriptions to "translate" the LASID symbols. I am not providing these because I think they're an improvement; on the contrary, they're much more annoying to read. I hope that they can be useful to people with knowledge of the IPA but without knowledge of common Gaelic transcription conventions. They should be read with the understanding of the apparent limitations of the source transcription described above.

Guide to suffixes

Descriptions largely taken from Wiktionary.

Irish -án, Scottish -an, Manx -an or -ane
- lochán, lochan, loghan. "pond, pool, small lake" (diminutive of loch)
- grianán, grianan, grianane. "sunny spot" (from the word meaning "sun" + suffix)
- A suffix used to derive instruments, diminutives, and other nouns from primary nouns.
Irish -adóir, Scottish -adair, Manx -der
- bréagadóir, breugadair, breageyder. "liar"
- Suffix appended to words to create an agent noun, indicating a person who does (or a thing that does) something
Irish -ach, Scottish -ach, Manx -agh
- Éireannach, Èireannach, Erinagh. "Irish person" (noun)
- Forms nouns from other nouns and adjectives with the sense of ‘person or thing connected or involved with, belonging to, having’.
Irish -aire, Scottish -aire, Manx -eyr
- iascaire, iasgair, eeasteyr. "Fisherman" (from the word meaning "fish" plus suffix)
- Forming nouns from nouns and adjectives with the sense of ‘person or thing connected or involved with, belonging to, having’
Irish -anna, Scottish -an, Manx -yn
- bláthanna, blàthan, blaaghyn. "flowers"
- Pluralises some nouns

Thoughts on each word

Frog: taboo-avoidance?
Losgann: the peat bog's answer to mythical fire beasts?
Lisbín: taboo deformation of losgann?
Sonasan: an etymylogical outlier?
Fliuchán: a lost word from Derry
Leumachan and leumadair: leaper
Crónán and cnádán: for the frog's sweet song
Gille-cràigean, cràigean, and cròigean: well-pawed lads
Màgan, smàigean and mial-mhàgain: crawlers
Laprachán, lapadán, laparán and lapadóir: paddlers
Crúbán claidhe: what do frogs have to do with crabs?
Breallach lathaí: a crude comparison? Rated PG
Lúbóg lathaí and lúbar lathaí: for the frog's bendy legs?
Frús: found only in the LASID. Another foreign loan?
Preabaire na lathaighe: mud hopper
Athadán: Conamara creature
Tortán: clod?
Ceanna-phiullan: usually used for tadpoles

Frog: taboo-avoidance?

I found this in places all over Ireland, but not at all in Scotland³. Of the 49 LASID locations in Ireland that gave a response for "frog", 34 gave a variation on this word. Anecdotally it is the most common word used in Irish today. It is the only word I found native attestations of on The Isle of Man.

Could the usage of a foreign loan word, from English, be due to a taboo, where it was feared saying the true name of the creatures would summon them? Christopher Lewin, a Manx scholar, kindly corresponded with me about Manx words for frogs, and he suggested the possibility of this taboo.

My teacher Dubhán Ó Longáin pointed out the belief that frogs entering the home is an omen of death, which would support this taboo idea. Ireland's National Folklore Collection would seem to support this as a widely held belief, if not universal: a sample of 52 "frog omens" (exclusively frogs entering the house or crossing your path on the road) showed only 8 that signalled good luck, and 2 that signalled marriage or childbirth; the remaining 80% signalled death or bad luck⁴.

It's of course quite possible that an English loan came to replace a native word through language contact, without any word-specific pressure, but I don't know of any other name for an animal that has changed in this way. Some force must have caused a shift — that is, unless "frog" was actually the first word many Gaels heard used for the creatures.

I learnt during this research that it is a common belief that frogs are not native to Ireland. Several 17th century texts attribute this to "the graces of our patron Saint Patrick" (Ó Maonaigh, 1952) or to some mystical quality of the island. From de Rochefort (1779):

It is a peculiarity in this island that there are no venomous animals, not even frogs, toads, lizards, spiders, nor any other kind, which is a mark of the purity and goodness of its air. Some persons have tried the experiment whether any creatures of this sort brought from other places would live here, but it is a certainty that they die as soon as they arrive in the country; and farther it is said, that the touch of a native of Ireland proves mortal to any of these animals in any foreign country whatsoever, and that a circle being made about any venomous creature with a stick which grew in this island, the animal will instantly die.

The frog's arrival in Ireland is variously attributed to the Anglo-Norman invasion of the 12th century, or to students of Trinity College of the 17th century⁵, or to William of Orange⁶, or some unknown 18th century introducer in County Down⁷. An account from Gerard of Wales of a frog being found in Waterford sometime in the 1170s or 1180s⁸ speaks of fascination and consternation when the creature is presented at court⁹:

[...] a frog was found, within my time, in the grassy meadows near Waterford, and brought to court alive before Robert Poer, who was at that time warden there, and many others, both English and Irish. And when numbers of both nations, and particularly the Irish, had beheld it with great astonishment, at last Duvenold¹⁰, 58th King of Ossory, a man of sense among his people, and faithful, who happened to be present, beating his head, and having deep grief at heart, spoke thus:—

“That reptile is the bearer of doleful news to Ireland.”

And uttering a sort of prognostic, he further said, that it portended, without doubt, the coming of the English, their threatened conquest, and the subjugation of his own nation.

If frogs were indeed brought to Ireland along with colonisation, perhaps the word "frog" came with them. Even if frogs had long been native to Ireland, but in isolated populations or select parts such that many Irish people did not come into contact with them and thus did not have a word for them, it is conceivable that "frog" did not replace a native word, but was the first name many people heard applied to the creature.

While it's likely the Anglo-Norman elite would have called the creatures raine, it is conceivable many of the footsoldiers would have spoken Middle English and called the creatures frogge.

Drumcliffe Cross in Sligo, from c. 11th century, seemingly showing a frog carved in the stone. Evidence of their existence in Sligo at that time? Image source: Megalithic Ireland

The idea of much of Ireland having no word for frog that predates Middle English is not especially attractive to me. Returning to our first idea, of taboo: Gerard of Wales' account above certainly gives an early example of frogs being treated as a bad omen. Dubourdieu (1802) conveys similarly fearful local attitudes in county Down:

[...] there are many stories still current of the terror and surprise excited by the view of this disgusting though innocent animal, which seems formed to be the prey of every voracious creature, either by land or water, within whose reach it comes.

It is tempting to make the conjecture that the complete lack of usage of frog in Scotland is because they are not a bad omen there, thereby supporting the idea that the word is used as a taboo substitute in Ireland, where there is evidence of negative superstition. This is not something I am able to substantiate. The Calum Maclean Project provides digital access to over 13 000 manuscript pages of Gaelic folklore collected across Scotland's Highlands and Islands — no particular lore about frogs is available, only an amusing story about a Uist man seeing one for the first time and thinking it was a fairy. Could the lack of discussion of frogs implicitly suggest that there was not much lore to record about them, and hence no negative associations? Perhaps; but Scotland has plenty of descriptive words for frogs that could easily be taboo substitutes themselves. Similarly the only lore I've been able to find about frogs on The Isle of Man, where frog was used, is the seemingly pan-Gaelic belief that licking a frog might cure you of many ailments (Clague, 1911)¹¹.

The truth will remain ambiguous, but personally, I find the idea of "frog" being used euphemistically quite compelling. One of the words explored below, lisbín, could be explained by taboo deformation from losgann. Various phonetically intermediate forms are attested, supporting the idea of it being akin to a "minced oath". Perhaps losgann was the taboo word everyone was trying to avoid. ↩

Losgann: the peat bog's answer to mythical fire beasts?

I found this across some of Ireland and Scotland, especially in Argyll. Only three LASID returns gave this word, two of which were in Argyll, and one in Mayo. Three of the four instances in the Schools' Collection are in Donegal.

MacBain (1911) suggests that this word is related to loisc meaning to burn¹², referring to the sting from touching the secretions of the frog's skin.

However...I don't believe touching a common frog causes any stinging sensation, does it? Toads do secrete a bufotoxin, which can cause an allergic reaction on contact, but is mostly dangerous when ingested.

I have a perhaps more compelling idea: The Electronic Dictionary of the Irish Language entry for loscann directed me to O'Clery's Irish Glossary from 1643:

The notes say the salamander is called loisgionn "because it is burnt"; salamanders are known to nest in firewood, and in mythology are associated with fire. Dinneen (1904) also lists "salamander" as a possible translation of loisceann. The 14th century manuscript Leabhar Méig Shamhradháin (McKenna, 1947) seems to use losguinn to refer to a dragon¹³.

Is the humble frog the peat bog's answer to mythical fire beasts of old? It would seem plausible that losgann evolved from referring to dragons and salamanders to the closest creature Ireland has to offer: the frog (though arguably the newt is a more obvious descendant).

An alternative hypothesis stems from the discovery that the word "salamander" has historically been used for crickets and grasshoppers¹⁴. Crickets are attracted to warmth, and historically have been associated with the hearth. Could the evolution instead be (association with fire) -> crickets -> (association with jumping) -> frogs?¹⁵

An etymology related to the frog's jumping would certainly be less unusual than one directly related to salamanders and dragons. Marstrander (1908) explores possibilities for the etymology of losgann and divides Indo-European languages' words for frogs and toads into categories, named for their:

croaking (Latin rana, Latvian var̂de)
skin (shiny for frogs, bumpy for toads) (Sanskrit maṇḍū́ka is given as being from root maṇḍá meaning scum or cream. Not the most convincing...)
distinctive hands (French crapaud for toad)
way of moving (jumping for frogs, crawling for toads)

Marstrander complains that a proposed etymology for losgann to do with burning seems unlikely due to its uniqueness among other Indo-European language's words for frogs. Perhaps the missing piece he needed was the crickets.

losgann lathaighe, luascán lathaighe, loscán laithighe, ⁊c.

An enjoyable variant of this word, that I found primarily in Mayo and Galway, is losgann lathaighe (modern spelling lathaí), which I will choose to translate as "mud salamander".

East Sutherland's losgaid

An interesting variant found in Embo in East Sutherland is losgaid [ɫosɡidʹ]. Noticeably similar is the usage of iosgaid in place of easgann for eel, recorded in Dorian (1978).

On spelling variations

I have addressed losgann vs. loscann in my general orthography notes. These spellings both reflect a pronounciation of something like /ˈl̪ˠɔsˠkən̪ˠ/, where the first vowel may vary. The spelling loscán reflects a pronunciation found in Connacht where the final consonant is lenis and the final vowel is clear: /ˈl̪ˠosˠkɑːnˠ/. ↩

Lisbín: taboo deformation of losgann?

This word and its variants had only a handful of attestations, all in Ireland, with no obvious geographical centre. Usages were found in Kerry (1), Galway (1), Mayo (1) and Donegal (3).

This word, most commonly spelt lispín in the examples I found, isn't in Ó Dónaill's dictionary. A schoolchild in Listowel, County Kerry defines it as meaning "frog or lizard". Dinneen (1904) lists this word as being found in Sligo, and meaning "frog".

The etymology seemed opaque to me initially. It would appear to be a diminutive of lisp or liosp (the suffix -ín slenderises the final consonants), but this line of enquiry didn't lead anywhere.

This speaker from Donegal uses it for a type of fish, and suggests it might be related to losgann. If this is the case, I'd expect to be able to find some intermediate forms. Fanad's Father Mac Giolla Ceara uses liospán for "frog" in Ceachta as Leabhar na Cruinne¹⁶. Ó Dónaill's dictionary does list this spelling as a variant of loscann!

Similarly, in The Schools' Collection I found a usage¹⁷ of luspán, referring to some kind of small creature found by a turf bank. Whether it refers to a frog is ambiguous, but to me it seems the most likely candidate. Apart from the quality of the initial consonant and possibly the first vowel, luspán would likely match the pronunciation indicated by liospán.

The foot of a turf bank can be quite wet and muddy, a likely place to find a frog. Image source: geograph.org.uk

In the above section on the word "frog", I explored the idea of "frog" being used to substitute for a taboo "true" name for the creature. If losgann was such a taboo name, then the evolutions to luspán, liospán, lispín could be explained by taboo deformation — that is, deliberately phonetically altering a word to avoid actually saying it (as with "jeepers" for "Jesus").

Example phonemic transcriptons of the attested words I propose are evolutions of loscann to lispín. A síneadh fada on an unstressed syllable taken to mean a clear short vowel, as in my experience in Donegal. Some further phonetically intermediate stages would be grammatically restricted, e.g. liospáin would be a declension of liospán.

If this word is indeed a phonetic variation on losgann, then the fact it is also used for lizards might give credence to the idea that the word comes directly from salamanders, rather than indirectly via crickets (see above section on losgann).

lisbín locha

A variant I found a single example of, in Mayo, was lisbín locha¹⁸, which we might translate as "loch salamander".

Use of losgann to mean "semi-aquatic"

Meath's Aodh Mac Domhnaill (1802-1867) uses losgann to mean "semi-aquatic" (Beckett, 1967). The editor renders lighsgan and other various spellings as loscán. On otters:

Is loscán an dobharchú, óir is ar an uisce a ghintear na coileáin agus dá bhrí sin baineann a mbeatha amach faoi agus os cionn uisce.

"The otter is loscán, for in the water the pups are born and therefore they spend life out of and in the water."

The same text uses frag (rendered frog by the editor) for "frog". Does the use of losgann to mean any semi-aquatic creature support the idea of it being a taboo word? Perhaps not. However, the usage seems at odds with all earlier examples given in the eDIL. Given our proposed etymology for losgann, it would seem this usage has come from the previous use of the word to mean "frog" specifically. Perhaps after the word had become infrequent, and frog had become ubiquitous, this more general usage became possible.

Other usages of lisbín

An Irish telling of The Princess and the Frog
A character in a play
Possibly in the name of this beach, written i nGaedhilg in this news article as Trá Lispín
In The Man Who Invented Sin by Seán O'Faoláin

↩

Sonasan: an etymylogical outlier?

I found this word in two places in Wester Ross. It is also stated to be used in nearby Skye in Forbes (1905).

In Robertson (1900) p. 364 sonasan is described as specifically referring to "the young frog when it has passed the tadpole stage".

The word can be the nominative plural for sonas, which means "joy" or "good fortune". Use of the plural seems uncommon, but it is used this way in a few old sources:

’N uair a rainig mi’n gleannan
B’oirdhearc sealladh nam bruach,
Bho na chaochail an doinionn
’S a thainig sonasan nuadh

"[...] and new joys have come". The above is from a song Cuairt Mhaidne A'Bhuachaille, by Calum MacEath, which won a prize at a 1926 Mòd, and was reprinted in An Gaidheal by An Comunn Gàidhealach.

In the frog's case, the suffix -an is being used either diminutively or to create some other new noun (see suffix guide). The plural is recorded as sonasánan [sɔ᷉nəsɑnən], [sɔ᷉nəsɑnː] in Wentworth (1993). It would seem that frogs are being referred to as "wee joys", or "joyful things".

Referring to a frog as a "wee joy", while delightful, seemed unexpected to me. Superficially sonasan reminds me of snasán, listed above as a synonym for loisgionn (see section on losgann). This word refers to polish, stemming from the word snas for cutting or chipping, perhaps because of the process of making shellac involves scraping a resin secreted by bugs from tree bark, melting it into a sheet, then breaking that into small chips. I have no suggestion for how this might be related to frogs or crickets, and no justification for why the vowel might have been inserted to create sonasan. The knowledge that burnt frog innards were once used for polish seems like a red herring.

Perhaps we can take this word at face value: as describing the joyful motion of the leaping young frog, newly be-legged — or as signifying a positive omen. ↩

Fliuchán: a lost word from Derry

This word is reported as once having been found in County Derry

By the time of the LASID in the 1950s, the fieldworkers could find no native speakers in Derry. However, a variety of earlier secondary sources record the word fliuchán as being used for "frog". I have not found the word used with this meaning elsewhere.

The word fliuch means wet, and correspondingly fliuchán means "wet thing" or "wetness". In Kerry it is used to refer to rain, see Sjoestedt (1930), and this example in the Schools Collection. It is also used in this entry from Conamara to describe some kind of seafood that people long ago would have eaten, listed alongside crabs, clams, and seaweed.

Sources where it used to mean frog:

Dinneen (1904) p. 320 "a frog (Der.)"
Cormac (1909) (pictured above) He says that in Derry they call frogs fliuchán.
Mac Meanman (1940): Ceann aca sin an frog nó an fliuchán mar deirtear i gcorr-áit ins an chúigeadh seo. A Donegal source saying frogs are known as fliuchán elsewhere in Ulster.
Mac Gréagóir (1908) (pictured below) A riddle describing frogs has the answer fliuchán díge. It is not specifically attributed to Derry, just Ulster.

Ciarán Ó Duibhín believes the 'Cormac' in An Claidheamh Soluis is Séamus Ó Ceallaigh (1879-1954), whose father was from Draperstown and was raised with Irish until he was 7 years old. More information is available at ainm.ie and in Whitfield (1994).

Fliuchán díge

In 1908 Aoidhmín Mac Gréagóir published a series of articles in An Claidheamh Soluis titled Sean-Ranna Ultacha (Eng. old verse of Ulster). A riddle is included:

The riddle asks what jumps over rocks and jumps into the loch. The answer, fliuchán díge, we can translate as "wet thing of the ditch". ↩

Leumachan and leumadair: leaper

I found variants of leumachan in various parts of Scotland, especially in West and North Sutherland. Dòrlach's fieldwork found leumadair once in the North of Lewis, and The Schools' Collection records it once in Mayo (as léimeadóir).

The etymology of leumachan seems transparent: leum + ach + an = "(wee) jumping thing". Similarly for leumadair: "jumper". Leumadair is also used for other leaping animals, like dolphins¹⁹ or grasshoppers. Sometimes qualifiers are used: Dòrlach's fieldwork in Scotland found leumadair-fèoir ("grass jumper") for grasshopper, which is also found in the 1819 Manx bible as lheimydyr-faiyr.

It is possible that leumachan was also used for frog by native Manx speakers, as it is given in Fargher (1969), rendered lheimaghan. It is likely this was a neologism introduced by Fargher, however. I couldn't find any native corroboration. Fargher's work is discussed further in the section on words not included in the map.

Variations

Several variations of leumachan came up, in fact far more commonly than plain leumachan:

leumrachan, Carloway on Lewis
leumbrochan, Clashnessie, also on Lewis
leumbhrochan, Achiltibuie near Ullapool
leumnachan, Drumbuie, Lochalsh

Indeed, the word léimneach seems more common in Ireland than léimeach. How come?

In Robertson (1900), leumrachan is explained as coming about through dissimilation from leumachan. This explanation does not make sense to me. Dissimilation is a phonetic process where sounds change to make them more distinct from surrounding sounds, or where sounds that are too similar to others within a word are removed. There are various proposed reasons for this, but generally it seems to be done to make a word easier to say, or more pleasing to the ear. Gaelic examples of this given by others: dealagán for gealagán ("egg white", Quiggin, 1906), caoláire for caol sháile (logainm.ie). In English a common example is rhotic speakers pronouncing "berserk" as "beserk".

Perhaps it is lack of knowledge on my part, but I don't see how the insertion of /n/ or /r/ here can be explained by dissimilation. Certainly the substitution of /r/ for /n/, as in pronunciations of mná (e.g. /mˠɾˠãː/) found in most places except Munster, seems well-described by dissimilation. But the insertion of nasal /n/ after nasal /m/ does not seem well-described by this.

What if leumnachan (and thereby leumrachan &c. by dissimilation) could be explained by leumnach being formed from the plural? The Old Gaelic nominative plural léimmen gave rise to léimanna in Ireland and leuman in Scotland. The eDIL records the old spellings of lémennach and leminnach. Could these reflect the suffixation of léimmen? Beyond the example old spellings, I don't have much to support this — except that there are other examples of -ach suffixation that are made from the plural: aidhmeannach ("designing; ambitious", from "aims, purposes"), greamannach ("biting, inclined to bite; sticky" from "grips (n.); bites (n.)"). Perhaps the plural here conveyed repeated jumping. I find this a more satisfying explanation than the dissimilation above. ↩

Crónán and cnádán: for the frog's sweet song

Both of these words seem rare, at least for referring to frogs. Crónán came up twice in West Donegal, and once in the Fews in Armagh. Cnádán was found once each in Waterford and Cork, and is also listed in some old dictionaries and referred to in articles from the late 1800s. Modern sources often cite cnádán as referring to the Natterjack Toad. Cnádán is one of the words used in an 1817 edition of the bible²⁰. See bible appendix for more information.

Crónán: hummer

Both of these words refer to the frog's croaking. The first, crónán is translated in Hamilton (1974) as "purring", "humming", and beyond the frog's croak is also used for other low pitched relatively white sounds:

for a cat's purring, see the sean-cainnt collected several times in the Schools' Collection: Is ar mhaithe leis fhéin a dheineann an cat crónán "the cat purrs for himself", the significance of which I have seen explained in several diverging ways

for the sound of a babbling brook (Sinclair, 1879, p. 320): Aig an allt' tha crònan fann/Air a' ghaoith tha fàile cùbhraidh, from a song collected from Argyll-born bard Eanraig MacIlleBhàin

for the sound of waves crashing onto the shore (Sinclair, 1879, p. 223): An tonn ri crònan air cladach còmhnard, from a song collected from Iain Caimbeul, Bàrd na Leidige.

Slightly less congruous is its use for birdsong (Sinclair, 1879, p. 291), though I suppose this too can be a pleasant background noise.

A variant recorded in Donegal and in The Fews (Dunbar, 2025) is crónán díge, which we might translate as "ditch hummer" (ditches often collect water, creating a lovely froggy habitat).

What of the etymology of this word? The English word "croon" is thought to derive from Middle Dutch crônen, which certainly matches phonetically and loosely in terms of meaning. Perhaps the word was borrowed directly from there, or from Middle English, or from the modern form "croon". Regardless, perhaps we can revise our earlier translation of crónán díge to "ditch crooner" for a more romantic vision.

Cnádán: croaker

This word seems to most commonly have been used for the plant burdock, see various sources in The Schools' Collection, and again Hamilton (1974).

Its usage for frogs seems to be onomatopoeic. The Scottish cnàg /kʰɾãːk/ and gnàg /kɾãːk/ for the frog's croak are notably similar. It is recorded several times in the The Schools' Collection as a pejorative for someone who moans or is cranky, and translated in this sense as "a croaker".

When I did first understand this word to be likely onomatopoeic, I wondered if this would only be the case in places where it is pronounced to begin with /kɾˠ/ (further north in Ireland) rather than /knˠ/ (further south in Ireland). To me, this was all that would make sense in terms of onomatopoeia. However, the only places I found it recorded were firmly in the south of the island: the LASID records [knɑũˈdɑːn] in Waterford. I think this just serves to illustrate how arbitrary onomatopoeia can be, easily demonstrated by comparing animal sounds across languages.

Our two singers in unison

Signs of rain:

Nuair aireóchtha na froganna ag crónán agus ag cnádán.
"When you hear the frogs crooning and croaking."

↩

Gille-cràigean, cràigean, and cròigean: well-pawed lads

Gille-cràigean was recorded a few times around Ardnamurchan and on Lismore, and usage of cràigean then stretches in an unbroken (in the data I have gathered) band running northeast across Scotland to Strathspey, where cròigean is found.

These words appear to refer to the frog's "hands". Dwelly's dictionary defines cràg and cròg primarily as "large or clumsy hand", with various other hand or paw definitions given also. Macbain (1911) derives cràigean from these words, translating it as "well-pawed one". The addition of gille makes it "well-pawed lad".

I've seen it suggested that this word is instead derived from cnag /kʰɾãk/, which Dwelly defines as "pin; peg; knob". Presumably this would describe the frog as a wee lump. This seems less likely to me, both from the meaning, and due to the fact that cràigean has a long vowel (e.g. [kɾɑ:ɡʹɑ̃ṉ] is recorded in Badenoch) as in cràg, and is also found as cròigean, reflecting the variants cràg and cròg. ↩

Màgan, smàigean and mial-mhàgain: crawlers

All three Nova Scotia datapoints record màgan for frog. In Scotland it is more common for this to mean toad. However, its variant mial-mhàgain is popular in Scotland for frog, particularly on Skye and Raasay. Smàigean was found in East Perthshire, and is also used for "toad" in other places.

Dwelly's dictionary defines màg as "paw; claw; ludicrous term for the hand", and "seal's paw (Argyll)". Màigean is given as "Fat little man; child beginning to walk; toad; frog; ludicrous term for a man with a creeping or sprawling gait, or moving on all fours." MacBain (1911) suggests this term for toads should properly be mial-mhàgain, meaning "squat beast".

Certainly there seems to be a strong association with crawling here, hence to me this word would evoke toads more than frogs. Nevertheless, variants of mial-mhàgain appear popular for frogs. On Skye and Raasay this is often rendered mula-mhàgag. In Robertson (1898), this is analysed as epenthesis, noting other examples of vowel insertion like seana-mhathair instead of sean-mhathair for grandmother. Epenthesis between liquid consonants (l, n, r) followed by certain other consonants is widespread, but the rules that govern it do vary. Compare the various Irish pronounciations of seanmháthair here.

Is the usage of a term associated with crawling because frogs and toads were undistinguished in some places, or the words got confused? MacBain's translation of "squat beast" certainly suits frogs well, see also the section on crúbán claidhe. It's possible these terms take their meaning from the squatting, rather than movement in that position.

But what of smàigean? Is the s- etymological? MacBain also defines smàg as "paw", but compares it to English "smuggle". It seems worth noting that in Proto Indo European, many *s- prefixes are theorised to have been optional, or only present in some inflections²¹. Hence the English word "small" and the Irish word míol ("animal") are thought to be from the same PIE root meaning "small animal". Whether the same word could be preserved in a language with and without the s prefix is not clear to me. ↩

Laprachán, lapadán, laparán and lapadóir: paddlers

Laprachán or laprachán lathái was found a few times in Galway and once in Waterford. Lapadán had one example each in Galway and Monaghan, lapadóir one in Mayo, and lapadóir lathaí one in Galway. Laparán was found once in Limerick, and in a novel by a Donegal author.

While màgan and its variants stem from the word màg, these words appear to stem from the word lapa. Relevant extracts from Dinneen's dictionary, pp. 419-420:

lapa: a paw, the fist
lapach: a swamp, a marsh
lapadán: a kind of sea-fish; also a bird called "diver"; a small inactive person (Donegal); a clumsy person
lapáil: act of using the paws, pawing; of a frog swimming (Connacht)
lapaire: one that paws or pads with the hand
laparnach: a wading through water etc.; pawing or handling soft mud etc.

Ó Dónaill's dictionary lists laparnach as a variant of slaparnach, meaning the act or sound of splashing water. This would seem to be imitative. The varying use of initial "s" reminds me of variant "plash" for "splash" in English. This would explain the seemingly incongruous use of lapach to mean "marsh": as a description of the sound made while walking through it. Ó Dónaill lists slaprach as "wet, soggy land".

In The Schools' Collection, lapa is used to refer to a goose's webbed feet, and also seemingly a severed human hand. I haven't been able to find any suggested etymologies for it. Ó Dónaill defines laprachán as "toddler; waddler", possibly evoking crawling. I wonder if there are two etymologies at play here, one associated with splashing and another with hands. I expect they are one and the same, with the hand being the splashing implement. ↩

Crúbán claidhe: what do frogs have to do with crabs?

This word was found twice, both times on the Curraun Peninsula, east of Achill Island in Mayo.

This seemingly very local term might be translated as "dyke beastie", with dyke meaning dry-stone wall ("dry stone wall beastie" doesn't have the same ring to it, and it is common to call them dykes in Scotland, where I am from).

Excerpts from Stockman (1974). In some other places claidhe is used to mean "ditch".

The word crúbán would appear to refer to an animal with some kind of notable hands; crúb is listed in Dinneen's dictionary as meaning "a claw, a hoof, or paw". The descriptive bounds of these words will of course vary between individuals, but I would personally not use any of these words to refer to a frog's..."hands". Perhaps crúb can be used for any non-human limb appendage. The diminutive crúibín has been borrowed into English to refer to pig trotters as food (to me, a distinctively large food, but nevertheless...).

Crúbán is hard to find written Irish attestations of. An example in the Schools' Collection uses it in the name for a plant shaped like a hare's paw. It is also listed in Ó Dónaill's dictionary as referring to a "short potato-ridge at angle to main ridge", probably describing its shape as similar to some kind of foot²². In Dinneen's dictionary it is defined as "crabfish", an archaic term for crab²³. In the LASID, the only places giving crúbán for crab are Rathlin Island²⁴, Inishowen, Arran and Kintyre. The DASG also records this usage in other parts of Argyll. Some places (mostly in Ulster, also in Scotland, one place in Clare, two in Mayo) are however recorded as using the similar crúbòg, sometimes only to refer to big crabs.

Distribution of crúb- words for "crab". Additional datapoint in Inishowen from The Schools' Collection. Mayo outlier also from The Schools' Collection. Jura and Colonsay taken from Scouller (2018).

Given the geographical distribution of crúb- words for crabs, I do wonder if the strikingly similar Scottish word crùb might be related, which Macbain (1911) gives as being derived from Norse krjúpa and cognate with English "creep", meaning "to squat, crouch". That certainly fits a frog's resting pose extremely well, and arguably a crab's. If crúbán does refer to the crab's claws, would we expect to hear the crab's claw referred to as crúb in the places that use this term for crabs? On Islay a crab's claw is recorded as ladhar, on Lewis as iongna.

Perhaps in Ireland, Celtic-origin crobh (Scottish crubh, meaning: hoof, clawed foot, etc.) has merged, phonetically and orthographically, with Norse-origin crúb. In Scotland there are some examples of crubhan, clearly distinct from crùban. Dwelly (1918) lists crubhan cait for "cat's paw print", specifically the shape one would make with their fingers inorder to make such an imprint. The same meaning is used in Stewart (1885).

I am personally satisfied by this explanation. I will elect to officially update my translation to "dyke squatter". ↩

Breallach lathaí: a crude comparison? Rated PG

This term was recorded three times in the LASID, all in Galway.

When I first looked up breall in the dictionary, I was met with a surprise:

breall\ means glans penis or clitoris">

Breallach is commonly used for clams. What do frogs, glandes, and clams have in common? Well, they are all "fleshy" and share a certain shiny sliminess to their opaque surface. I will note that open clams and mussels look like a vulva.

The other meanings listed for breall in Ó Dónaill's dictionary are:

(Ugly) protuberance [but is this just referencing the above meaning?]

Blubber lip [again, this could be comparing someone's lips in an insulting way]

Blemish, defect

Rag, clout [presumably meaning patch]

Blunderer, fool [genitals as epithets is common in English at least]

(In phrases) Tá ~ ort, you are making a silly mistake, making a fool of yourself [in English you might say you are making an arse of something, perhaps here they are saying you're making a glans of something]. Fágadh ~ air, he was made to look very foolish. Tá ~ orm le mo chuid oibre, my work is sadly neglected, very much in arrears.

~ a gorma, knapweed.

As per my annotations, I do feel that many of these could be explained via the anatomical meaning. The eDIL lists these meanings: blur, spot, stain, etc.; slur, blemish, etc.; tumour, a hump, knob or botch; the glans penis, etc. a may game, a mocking stock and the round knob at the end of the buailteán or striking part of a flail. The last meaning perhaps explains breall a gorma for knapweed.

The spiky ball on the end of a flail resembles the involucre of the knapweed. Flail image from medievalbritain.com, knapweed image from ulster-wildlife.org

The meanings of "knob" &c. do suggest the frog here could be named for his shape: I suppose a frog sort of looks like a little lump of mud when resting, see also the use of tortán (small clod) for frog at LASID point 35, also in Galway.

So, does breallach really refer to the frog's mucusy skin? Or is it an insult to the frog, calling him a blemish on the bog? Perhaps the "protuberance" meaning could refer to the frog's vocal sac, a suggestion from my teacher Dubhán Ó Longáin. Or perhaps it is just calling the frog a wee knob. For now, the origin of this term will remain mysterious. ↩

Lúbóg lathaí and lúbar lathaí: for the frog's bendy legs?

Collectively I found three usages of these terms, all in Galway.

My best guess is that these lúb- words refer to the frog's bendy legs. De Bhaldraithe (1945) shows usage of the verb lúb meaning "to bend", and De Bhaldraithe (1985) shows usage for a purl stitch when knitting, the feeling of a twist in one's intestines when scared, and the ability to bend joints.

I would translate lúbóg lathaí as "wee bent one of the mud". The variant lúbar was a bit more mysterious to me, particularly as one of the transcriptions from the LASID was [ˈlɑbər ˈlɑhiː] which doesn't look like "ú" at all. Another transcription of [Lu̢.bər ˈLɑhiː] convinced me they are the same word, and a derivation from lúb seems most likely. I wasn't sure what suffix had been applied; my rendering of -ar does not represent any standard suffix. Davis Sandefur suggested this was probably a realisation of -óir, thus we would have lúbóir meaning "bender".

Not included on in the map data is lúbán díge, listed in O'Neill-Lane (1917) as being found in Oriel (South Armagh, North Louth, South Monaghan, North-West Meath, East Cavan). I couldn't find any other examples of this usage. I would translate it as "bent one of the ditch". ↩

Frús: found only in the LASID. Another foreign loan?

This word was only found once, in LASID point 37 in Carnmore, Galway. It is corroborated as being used in Carnmore at LASID point 35. I could find no written attestations.

In imagining ways to write the LASID transcription [frus] (standard IPA [fɾˠusˠ]), I tried fr[i][u, ú, o, ó, a, á]s with various declensions, and the most likely match I found was fras or fros used to mean a shower of rain. This feels tenuous, although we do have the example of fliuchán above for a frog word used for rain elsewhere.

More compelling to me is the idea that this might be another foreign loan, perhaps from an earlier form of "frog". Wiktionary lists various forms in Middle English, including frosk, frossh and (most attractively) fross. ↩

Preabaire na lathaighe: mud hopper

I found only one attestation of this, in Mayo.

Another jumping term is preabaire na lathaighe: "mud hopper", or "mud bouncer". Other uses I found of preabaire in The Schools' Collection appeared to refer to magpies: see this familiar superstition from Tipperary, and this riddle from Clare. Ó Dónaill's dictionary gives as prebaire na mbánta as a possibility for magpie. ↩

Athadán: Conamara creature

I found only one written attestation of this word, and one phonetic in the LASID, both in Conamara.

I have seen this riddle repeated across Galway and Mayo in The Schools' Collection and the LASID²⁵. The version above is from a collection of Conamara folklore (O'Fothartha, 1892). It is a longer version than the later ones I have seen in the previously mentioned sources. I might inexpertly translate it as:

I seen through to the puddle/pond [assuming locán is lochán]
Timmy McHands and his sore leg [because his legs are bent funny]
The top of his shoe in his arsehole [because of how frogs sit]
And his two big eyes going out his head

I can see how it describes a frog, but if there is any of the wordplay that I usually associate with riddles, it is not apparent to me. Regardless of my suspicions about the quality of this riddle, the answer in all six other examples of this riddle is always a word meaning "frog". In the fuller example here, the answer is "athadán or frog swimming". I do not see how the former could be an alternative answer — I think it is an alternative name for the same meaning.

The only other usage of this word I've been able to find is in the LASID. Point 35, South of Tuam, for some reason lists alternative words for "frog" from different areas than the one at hand. A word from Conamara is given as [ɑːdɑːn]. I have read that intervocalic /h/ is deleted in parts of Conamara, so this would appear to be our word.

I was perplexed as to what it could mean. I am grateful to Davis Sandefur for investigating. He asked Criostóir Ó Loingsigh, who had heard eathadán for "tadpole" from a Kerry speaker. The root of the word is spelt variously athaid, aithid, eathaid, feithid. The initial f- is not etymological. The eDIL lists various related usages: "A bird, fowl; a winged creature; a living creature", "a serpent, any venomous little creature", "a beast". It would seem to be applied in a similar way to "beastie", though it seems in Conamara it was used to mean a very specific beastie: the frog. ↩

Tortán: clod?

I only found this in Ballyglooneen, LASID point 35, in Galway. The similar torpán is listed in Dinneen's dictionary with "frog" as a possible meaning.

Tortán is listed in Ó Dónaill's dictionary as meaning "clump, tussock", or "dumpy person". Similarly, torpán is listed as "(small) clump or clod" or "roundish thing; lumpish person, pot-bellied person". Perhaps it is used for frogs to compare them to clods of turf, or refer generically to small lumps of creatures.

Interestingly, in the context of the crúbán claidhe term, Dinneen's dictionary lists both "crab" and "frog" as possible translations of torpán. ↩

Ceanna-phiullan: usually used for tadpoles

There was only one example of this being used for frogs, in Romasdal on Skye. All other usages found were for tadpoles.

I wonder if this might be better written ceann a' phiullan, or perhaps more familiarly (to me) as ceann a' phollain. To me this would seem to clearly mean "head of the small pool". Dwelly (1918) equates pollan to pollag, defined primarily as little pool, hole, pit, or pond (see also Macbain, 1911 who writes ceann-phollag or ceann-phollan as words for tadpole).

A fun comparison is a dialectal American English word for tadpole: "polliwog". Amusingly, the "poll" here means "head"! All together the word means "head wiggle". In our Gaelic example we have "poll" to mean pool/pond, and another word for head. Both would seem to refer to the tadpole as a little swimming limbless head.

It's harder to make sense of this term applying to frogs. I can't help but wonder if the fieldworker who recorded this made an error! ↩

Words not included in the map, and not discussed above

Rannag on Man

The word rannag seems to be the most popular word for "frog" among Manx revivalists, but I was unable to find any attestations from native speakers. The earliest extant occurrence seems to be in Fargher (1969):

The common frog [...] is rannag, but this word became lost during the course of time yet it was preserved in the place-name 'Poyll Ny Rannagyn' (pool of the frogs). It is strange that this word is obviously connected with the Latin name [rana].

No other mention of the placename "Poyll Ny Rannagyn" seems to be found in other texts. The admission that rannag had "become lost" suggests he had never heard a native speaker use it. Doug Fargher, who was not a native speaker, felt that the revitalisation of Manx required a revision of its vocabulary (and grammar). This took the form of suggesting neologisms "to meet modern needs" (Broderick, 2013)²⁶, and replacing "perceived impurities or corruptions" used by native speakers with his own preferred words (Lewin, 2017). The preface to Fargher's English-Manx dictonary states his approach clearly (Fargher, 1979):

The aim of this dictionary is purely practical. It is largely a prescriptive work and not a descriptive one, that is to say, it does not aim to be a record pure and simple of the language as it was spoken at any time during its history, but tries to provide some sort of basic standard upon which to build the modern Manx language of today and tomorrow, in order that those who feel the need to express themselves in Manx may here find the necessary means to do so.

Although I take a more preservationist approach to my own Gaelic learning, it is clear Fargher's work has played a significant part in the revival of the language, which he dedicated much of his life to. See Lewin (2016, 2017) for more exploration of Fargher's work's impact, context and ideology.

Back to rannag. I admit my first instict was that Fargher might have fabricated this word, but in the preface to his dictionary he openly admits he "borrowed unashamedly from our Gaelic cousins" and "make[s] no apology whatsoever for attempting to restore to the Manx language mutations, genders and certain other characteristics of Gaelic which without doubt existed in pre-literary and classical Manx but which had already disappeared before the final demise of the native speakers"²⁷. Coyly commenting on the strangeness of rannag's Latin root for a word he fabricated would seem to be at odds with this open approach.

In Lewin's work he uses "the term ‘Traditional Manx’ to refer to the now extinct native variety deriving directly by intergenerational transmission from earlier forms of Gaelic, and ‘Revived Manx’ for the variety spoken today, predominantly as an L2 [second language]" (Lewin, 2017). The existence of the latter is a joyous thing to me, but my work here on frogs is concerned with the former, and in the absence of any evidence that the word "rannag" was ever used in Traditional Manx, I have not included it in the map.

Uillichd in Scotland

A curious word I found only in Forbes (1905) is uillichd (it is also in Dwelly, 1918, but sourced from Forbes). I believe this could have been pronounced [ɯʎəçgʲ] though of course this is unattested as I have found no other use of this word! I believe uillic could have the same pronounciation, but that would only suggest that frogs were called some diminutive of "William", and the genitive at that (which does not make sense to me grammatically). Perhaps this word is related to ùill for oil or grease, referring to the frog's mucusy skin. That is the best suggestion I have. I wish I could find other usages!

Cruitín díge in Oriel

Alongside lúbán díge, discussed above, O'Neill-Lane's dictionary lists cruitín díge as a word found in Oriel in Ireland. As well as the meaning of "harp, lyre", Dinneen gives the meanings of "a hump on the back, a little eminence; summit". Various sources from Monaghan and Cavan in The School's Collection list "hump" as the meaning. I suppose once again our froggy friend is being described as a little lump. The use of díge, the genitive of a word for "ditch", seems to have been common when referring to frogs in East Ulster.

Miscellaneous curiosities

"Anybody that lived in rural Ireland remember the frog man?"

"A jumping frog and other creatures of etymological interest"

"An etymological plague of frogs"

"The Etymology of English toad: Effects of the Celtic substrate?" (strongly disagreed with by the previous item)

A frog burned by a German bomb on the Isle of Man during World War II

Celtic etymology for the word "wilky" or "quilkin", used for frogs, from Cornish gwelsken meaning "grass-skin"

"A ribbiting display"

Go rabh maith agaibh

Ciarán Ó Duibhín, ar ábhar misnigh é, agus as acmhainní ar líne a chur ar fáil
Dubhán Ó Longáin, as mo cheisteanna fá fhroganna a fhreagairt, agus as an mhúinteoireacht
Àdhamh Ó Broin, as d'obair ghoirt a roinnt, agus as labhairt fá fhroganna liom
Christopher Lewin, for answering my questions about the possible origins of the Manx word rannag, and providing a copy of The Manx Have a Word for it, Book 4: Insects, Reptiles etc.
Davis Sandefur agus Criostóir Ó Loingsigh, as athadán a deánamh taighde, agus fá laparán a insint domh
Ciarán Dunbar, as labhairt fá fhocla as Oirialla liom
Màiri MacMillan, as labhairt fá fhroganna Uibhist liom
Simon Thoumire, as sonraí teagmhála Mhàiri a thabairt domh
Thank you to all the fieldworkers, the 1930s Irish schoolchildren, the informants who took the time to be interviewed, and everyone who has ever gone to the effort to make knowledge available online for others to access freely.

Appendix: Orthography notes

When illustrating the words for frog above, I wondered whether I should try to use a consistent orthography across the illustrations. The writing systems used in Scotland and Ireland differ somewhat, having once been shared, now are diverged. The Isle of Man's writing system was developed independently and is very different, but the only word I've illustrated from there is "frog", so the difference in orthography was not a concern.

In the end, I have largely written the words in the illustrations as I would expect to see them in the places they were recorded. I did, however, make some choices:

When standard Irish orthography would have "sc" or "sp", I have written "sg" and "sb", as I believe is standard in Scotland (where I understand most surviving dialects have lost voicing contrast on plosives entirely). This is because I think the voicing of the second consonant is phonemically irrelevant in this context even in Ireland, as it is in English (compare "speech" with "sbeech"), and the (lack of) aspiration is what is most salient phonetically. Also the letter "g" looks nice in the font I chose, so this way we get to see it in losgann.

When there were a few variants of a word, the choice of which one to represent in the illustrations was a bit arbitrary. For example, although I had more attestations of leumrachan than leumachan,it seemed more convenient for the headword to be formulated simply from leum + achan, with further explanation of variants later on.

This mostly applies to the datapoints on the map, but I have followed the old Scottish tradition of using "ó" for /oː/ (as in mór Eng. "big") and "ò" for /ɔː/ (as in òran Eng. "song").

When adding datapoints to the map from written sources, I have always used the written form from the source.

When working from sources like the LASID that provide phonetic transcriptions only, I have used a very loose phonetic rendering in the orthography that is most familiar to me, which preserves fortis-lenis contrast on L and N. Hence for LASID responses for the many areas where this contrast is lost and only the lenis consonant remains, I have written a single consonant character even if the standard spelling has a double consonant, e.g. standard "froganna" has been rendered "froganaí" to represent [frɑgəniː]. These spellings are really just here to make the map easier to read, so please don't read too deeply into any of the choices made in rendering the phonetic transcriptions as words.

Appendix: Frogs in Gaelic bibles

Table of translations for "frog" in various Gaelic bibles 1602-1827

The words vary in grammatical case. I believe the -ibh instances are dative plurals, and the rest nominative plurals. The original Hebrew of Exodus and Psalms uses the same word throughout for "frog".

Year of edition	Bible	Exodus 8:2	Exodus 8:3	Exodus 8:4	Exodus 8:5	Exodus 8:6	Exodus 8:7	Exodus 8:8	Psalms 78:45	Psalms 105:30	Revelation 16:13
1602	New Testament translation by various Irish-born Church of Ireland priests										froguibh
1685	Old Testament translation by English bishop William Bedell	froguibh	froguidhe	froguidhe	froguidhe	froguidhe	froguidhe	froguidhe	luisgionn	luisghionna
1690	(as above)	froguibh	froguidhe	froguidhe	froguidhe	froguidhe	froguide	froguidhe	luisgionn	luisghionna
1817	(as above)	lúisgionn	cnadáin	luisgionn	luisgionn	cnadáin	cnadáin	luisgionn	luisgionn	luisgionna
1827	(as above)	lúisgionn	lúisgionna	luisgionna	lúisgionna	lúisgionna	lúisgionna	lúisgionna	luisgion	lúisgionna

1767	New Testament translation by James Stewart and Dugald Buchanan, both Scottish										losguinn
1801	Old Testament translation by John Stewart of Luss, son of James Stewart above	losgannaibh	losgainn	losgainn	losgannaibh	losgainn	losgainn	losgain

1610	Manx translation of Psalms by John Phillips, born in Wales and educated at Oxford								ffroggyn	ffroggyn
1775	Manx bible, led by English bishop Mark Hildesley, with assistance from Manx scholar John Kelly	froggyn	froggyn	froggyn	froggyn	froggyn	froggyn	froggyn	froggyn	froggyn	froggyn

Bibliography

Sources only cited in the datapoints are either directly cited there, or are listed in the introduction (e.g. the LASID). They are not listed here.

Broderick, G. (2013). Neologisms in Revived Manx Gaelic. Studia Celtica Fennica: 7–29.
Cambrensis, G. (1863). The Topography of Ireland (T. Forester, Trans.) . London : H.G. Bohn (Original work published c. 1188)
Carmichael, A. (1928). Carmina Gadelica, Volume II. Edinburgh : Tweeddale Court
Clague, J. (1911). Cooinaghtyn Manninagh. Castletown : M. J. Blackwell.
Cormac (pseudonym) (1909). Frog. An Claidheamh Soluis 11:9 (8/5/1909).
De Bhaldraithe, T. (1945). Gaeilge Chois Fhairrge: An Deilbhíocht. Dublin : Institute of Advanced Studies.
De Bhaldraithe, T. (1985). Foirsiún Focal as Gaillimh. Dublin : Acadamh Ríoga na hÉireann.
de Rochefort, A. J. (1779). Albert Jouvin, de Rochefort, Description of Ireland after the Restoration. In Francis Grose and Thomas Astle (eds.), Antiquarian Repertory, London : for E. Jeffrey. (Original work published 1672)
Dinneen, P. S. (1904). Foclóir Gaedhilge agus Béarla. Irish Texts Society. (also referred to as "Dinneen's dictionary")
Dorian, N. C. (1978). East Sutherland Gaelic: the dialect of the Brora, Golspie, and Embo fishing communities. Dublin : Dublin Institute of Advanced Studies.
Dorian, N. C. (1981). Language Death: Life Cycle of a Scottish Gaelic Dialect. University of Pennsylvania Press Anniversary Collection.
Dubourdieu, J. (1802). Statistical survey of the County of Down. Dublin : Graisberry and Campbell.
Dunbar, C. (2025). Cnuasach Focal as Oirialla. [Online edition]
Dwelly, E. (1918). The illustrated Gaelic dictionary. Fleet, Hampshire : The author.
Fargher, D. C. (1969). The Manx have a word for it, Book 4: Insects, Reptiles, etc.. Reayrt Ny Marrey : The author.
Fargher, D. C. (1979). Fargher's English-Manx Dictionary. Douglas : Shearwater Press
Beckett, C. (1967). Fealsúnacht Aodha Mhic Dhomhnaill. Baile Átha Cliath : An Clóchomhar Tta. (Original manuscript 1853)
Forbes, A. R. (1905). Gaelic names of beasts (Mammalia), birds, fishes, insects, reptiles, etc.. Edinburgh : Oliver and Boyd : Norman Macleod.
Hamilton, J. N. (1974). A phonetic study of the Irish of Tory Island, Co. Donegal. Belfast : Institute of Irish Studies, Queen's University Belfast
Henry, S. (1939). The Cinderella of Rathlin Island. The Belfast Telegraph (18/04/1939)
Holmer, N. M. (1942). The Irish Language in Rathlin Island, Co. Antrim. Dublin : Royal Irish Academy.
Kelly, J. (1866). The Manx Dictionary. Douglas : The Manx Society
Lewin, C. (2016). The revivability of Manx Gaelic: a linguistic description and discussion of Revived Manx. Aberystwyth University.
Lewin, C. (2017). Scholarship and language revival: language ideologies in corpus development for Revived Manx. Studia Celtica Posnaniensia, 2(1), 97–118.
Macbain, Alexander (1911). An Etymylogical Dictionary of the Gaelic Language. Stirling : Eneas Mackay.
Marstrander, C. (1908). Über irisches loscann und einige andere indogermanische Namen der kröte. In Magnus Bernhard Olsen (ed.), Sproglige og historiske afhandlinger viede Sophus Bugges minde, 240-246. Oslo : H. Aschehoug & Co.
Mac Giolla Chearna, P. (1940). Ceachta as Leabhar na Cruinne. Baile Átha Cliath : Oifig an tSoláthair.
Mac Gréagóir, A. (1908). Sean-Ranna Ultacha. An Claidheamh Soluis 10:15 (20/6/1908). [under the pen-name Gréagóirína Nic Gréagóir Gréagach]
Mac Gréagóir, A. (1910). Sgéaltan X Rachreann. Gill, M. H. & a Mhac Teor.
Mac Meanman, S. (1940). Crann an Eolais, An Toradh. Dublin : Brún agus Ó Nualláin Teór.
McKenna, L. (1947). Book of Magauran: Leabhar Méig Shamhradháin. Dublin : Dublin Institute for Advanced Studies. [HTML version]. Retrieved from https://celt.ucc.ie/published/G402561/header.html. (Original manuscript 1330s)
O'Clery, M., & Miller, A. W. K. (1883). O'Clery's Irish glossary: Printed at Louvrain in 1643. s.n.. Revue Celtique, 5 (1881-1883). 16. (Original work published 1643 as Foclóir nó Sanasán Nua) (also referred to as "O'Clery's glossary")
Ó Dónaill, N. (1977). Foclóir Gaeilge–Béarla. Dublin: An Gúm
O'Fothartha, D. (1892). Siamsa an gheimhridh: no Cois an teallaigh in Iar gConnachta. Baile Átha Cliath : O'Brien Patrick
Mac Aingil, A. (1952). Scáthán Shacramuinte na hAithridhe (C. Ó Maonaigh, Trans.). Dublin : Dublin Institute for Advanced Studies. (Original work 1618)
O'Neill-Lane, T. (1917). Larger English-Irish Dictionary. New York : Funk & Wagnalls Co.
O'Reilly, E. (1864). An Irish-English dictionary. Dublin : James Duffy.
Quiggin, E. C. (1906). A Dialect of Donegal. Cambridge : University Press.
Robertson, C. M. (1898). Skye Gaelic. In: Transactions of The Gaelic Society of Inverness, 23 (1898-1899). 54-89
Robertson, C. M. (1900). The Gaelic of the West of Ross-shire. In: Transactions of The Gaelic Society of Inverness, 24 (1899-1901). 321-69
Scharff, R. F. (1893). Is The Frog a Native of Ireland?. The Irish Naturalist, 2(1), 1–6.
Scouller, A. M. (2018). The Gaelic Dialect of Colonsay. The University of Edinburgh
Sinclair, A. (1879). The Gaelic songster. Glasgow : The author.
Sjoestedt, M. L. (1930). Phonétique d’un parler irlandais de Kerry. In: Annales de Bretagne. Book 40, number 3, 1932. 570-571
Stewart, A. (1885). Twixt Ben Nevis and Glencoe. Edinburgh : W. Paterson
Stockman, G. (1974). The Irish of Achill, Co. Mayo. Belfast : Institute of Irish Studies, Queen's University of Belfast.
Wentworth, R. (1993). Faclan is Abairtean à Ros an Iar. Clar.
Whitfield, N. (1994). My Grandfather , Dr. Séamus Ó Ceallaigh (1879-1954). In Gleanings from Ulster History, iii-xxiii. Draperstown : Ballinascreen Historical Society. (Reprint of 1951 publication with new introductory material)

Dorian (1981) p. 101:
Precisely because everyone uses such loanwords, and because there is considerable self-consciousness about it, the number of loanwords in a verbal performance seems to have become a marker of degree of formality in ESG [East Sutherland Gaelic]. In a relaxed and casual performance, the number of lexical borrowings will rise [...] the more formal the performance — for example, established narrative routines reproduced for tape recording — the lower the number of lexical borrowings [...]
She gives an example of a tape-recorded narrative, where a speaker replaced the borrowing of poileas ("police") with luchd an lagh ("law people"). Dorian notes this as "elegant Gaelic but otherwise foreign to the lips of any East Sutherlander of my acquaintance". This correlation of formality and loan-word occurrence may be less prevelant in areas with healthier Gaelic. The subjects in the above were of the last couple generations of speakers of a dialect particularly far removed from what was considered standard (which negatively affected some, though not all, of the speakers' perception of the legitimacy of their Gaelic), and were subject to mockery from English monolinguals for their loanword usage. In a healthier community of speakers I imagine loanwords might be used more confidently and less self-consciously. ↩
Something I learnt during this project was that the distinction between frogs and toads is considered part of a folk taxonomy, not precisely aligned with scientific classification. Yet the common frog (rana temporaria) and common toad (bufo bufo) are in different genera, and my reading tells me members of rana are generally wartless, and are all good jumpers. Perhaps in these islands, where we have very few species, it does at least line up with scientific taxonomy. In other parts of the world with more amphibious diversity it seems there is more variation on whether folk and scientific taxonomies align. ↩
Dwelly (1918) p. 457: "1. Hole, chink, niche, nook, cranny. 2. marsh, fen" for fròg. O'Reilly (1864) p. 259: "a fen, a marsh ; a pitfall, a hole, a cleft;" for frog (before also giving the animal). The marsh and hole senses seem to have left Ireland. Dwelly gives "active, energetic" for frog, a meaning I haven't seen in any Irish texts. ↩
You can download a CSV of my collected list here. The list is not exhaustive and was collected by searching the NFC for "frog luck", "frog omen", "frog house", "frog death", "frog bás", "frog good". A common belief stated was that killing a frog would bring you bad luck, but this doesn't really signal anything of the nature of a chance encounter with a frog. Similarly lore that described the frog as blessed in some way was not included; indeed, one of the pieces of lore that stated frogs in the house is an omen of death said this is because frogs are considered "blessed". Being blessed does not equal being looked upon without fear.

My favourite piece of lore found during this search was this one:
The frog was looked upon as something sacred as it was the frog taught Our Lord how to swim.
Did he now... ↩
Scharff (1893). This article explores various historical accounts of frogs being found in Ireland, including Gerard of Wales's. The idea that Trinity students introduced frogs is dismissed by the author for being ecologically unlikely, noting that there are far more frogs on the west coast and the city doesn't seem like an ideal place for frogs to thrive. ↩
O'Reilly (1864) p. 259 states the frog is "an animal not found in Ireland before the reign of William the Third of England, whose Dutch troops first introduced it amongst us". ↩
Dubourdieu (1802) pp. 315-316: "that [frogs] first made their appearance near Moira, in the western parts of this county, can be proved beyond contradiction" but declines to do so himself. He offers an anecdote from a local man about when he first seen a frog. ↩
I have read that Gerard first visited Ireland in 1183, and Topographia Hibernia, containing the account, was circulated in 1188. However, he mentions Robert Poer in the account, who I read died in 1178. The Ossory king in question is said to have died in 1185. ↩
Cambrensis (1863) ↩
Domnall Mac Gilla Pátraic, see this biography of Robert Poer ↩
I think people thought frogs to be very absorbent, hence their ability to remove aches and pains through touch. I don't personally interpret this belief as necessarily attributing mystical powers to the frog. The other Manx sources consulted were The Manx Corpus (containing Clauge, 1911); Sophia Morrison's 1911 Manx Fairy Tales where I found no mention of frogs; Skeealyn Cheeil-Chiollee, edited by Stephen Miller and published in 1993, containing folklore collected by Charles Roeder in the last quarter of the 19th century, and where I found no mention of frogs. ↩
The spelling loscann is used here to mean "burning", as a variant of standard loisceann. I think the only other proposed etymology I've seen is in Carmichael, 1928, p. 332: "Probably the toad is called 'losgan' from 'losg' irruption, leprosy". This seems much less likely to me, based on the various sources found via the eDIL, than the loiscend derivation. I believe the word given for leprosy mostly referred to lameness (which can be a secondary effect of leprosy). I'm not sure what toads would have to do with leprosy; perhaps their bumpy skin was thought to be reminiscent of leprosy nodules. I have seen it suggested that Taddiport, a leper colony in the Middle Ages, was named so because of this. I haven't found much on toads being used to refer to people suffering from leprosy at the time, however, but I only looked briefly. ↩
Comhrag losguinn lasrach mear ná sir—is sé do dhaingean—suail a sheadh i n-armaibh áigh, marbhaidh fear uaidh dá anáil. The text refers to a creature breathing fire. ↩
See this entry in an Anglo-Norman dictionary, and this blog post "Not quite cricket?" from Grammarphobia. This Middle English dictionary shows the converse, criket being used to refer to the fire lizard. Thank you to Grammarphobia for sharing the OED extracts. ↩
I wondered if perhaps the synonyms listed in O'Clery's glossary can provide more clues. Cú cnámha appears to read as "hound of bones", though the eDIL tells us that cú has also been generically used for creatures, particularly insects. In Forbes (1905) this word is cited as meaning "louse", as is the other synonym listed by O'Clery, snasán. I suppose, like salamanders, you might expect to find woodlice in your firewood, if you kept it outside. But these words could easily be referring to crickets also. In the end these synonyms mostly increase my confidence that the glossary is referring to crickets, not to salamanders the lizards. Whether the usage for frogs evolved from the usage for crickets, or alongside it, will remain a mystery. ↩
Thank you to Gerry Oates' article An phéist a chuir an cluiche ar Phádraig in An tUltach which directed me to this, via the National Corpus of Irish. Mac Giolla Ceara, 1940, p. 42: "An préachán dubh ar an chrann, an traona san choirce, agus an liospán san pholl [...]" ↩
This was the school my granny went to :) and my granda's parents etc. ↩
The schoolchild actually wrote lisbín lacha, which I don't think makes grammatical sense (lacha is the nominative case of the word meaning "duck", but the genitive would be needed here. An association with ducks (the animals) makes a lot less sense than with bodies of water). So I assume this was a spelling error on the child's part. ↩
In Welsh, the cognate llam gives us llamhidydd, similarly meaning "jumper" and used for porpoises. ↩
The introduction of this bible says that the Old Testament is translated by William Bedell and "some changes made from the edition of 1690". I assume one of the changes was changing to use cnadáin, though only in some places. See the appendix on Gaelic bibles for a full table of frog words used in bible editions. ↩
All of my knowledge of this comes from noticing the parenthesised "s" in PIE derivations, and this Wikipedia article. ↩
It's common for body parts (and animals) to be used in placenames to describe geographical features. E.g. droim "back" used for "ridge". ↩
"Crabfish" also meant lobster, but the LASID universally gives gliomach (giomach in Scotland) for that. ↩
The word crúbán is used in the Rathlin retelling of Cinderella recorded in Mac Gréagóir (1910). This is translated in the Belfast Telegraph 18/04/1939 by Sam Henry and titled "The Cinderella of Rathlin Island", where crúbán seems to be translated as "pig's feet" — however, I don't think this translation is trustworthy. Ciarán Ó Duibhín thinks Sam Henry likely didn't have much Irish, let alone knowledge of Rathlin's dialect. It seems schoolteacher Andrew Dooey often did translation for him.

Onto the usage of crúbán in the Cinderella telling. There's not a huge amount of context. First we are told of her sisters' activities:
Tosuigh iad ag gearradh a saltann is luiríní móra daoibh ag feitheamh an bheireochadh an bróg carnóg sin orra
I think saltann is "heels (n.)", given as sáltan in Holmer (1942). I think luiríní refers to digits, in this case toes, some kind of diminutive of ladhar. The word is also used in another story in the same collection where it seems to be referring to fingers. Ciarán has glossed it as "toes" in his East Ulster Dictionary. So I believe this describes the sisters cutting their heels and toes in order to fit into the shoe. Cinderella is then forced to hide under a tub while the prince visits. She cries out:
Saltann móra lobhtha
Is ['s = agus] ladhra gearrtha crúbán
Is ['s = agus] an té beag buidheach [Cinderella]
Síos faoi an tubhán
Perhaps this is "Big rotten heels and cut crab claws, and the little yellow one [referring to Cinderella] under the tub". It was not easy for me to arrive at this translation. Lobhtha is "rotten" (modern spelling lofa). We already have saltann as "heels" above. I assumed ladhra is the nominative plural of ladhar for toes/claws. And I am assuming crúbán is genitive plural of crúbán. The use of ladhar, which can mean both toes (Holmer, 1942) and claws (Ó Dónaill, 1977) right after talking about the sisters cutting their toes made me assume she was still talking about her sister's toes. But I can't reconcile that with the use of crúbán.

Thank you to Ciarán Ó Duibhín for helping me with this translation. I did not twig (did you know twig is from tuig?) that is probably wasn't the copula here, but a shortened form of agus ("and") that I have usually seen rendered 's. I also forgot that the genitive plural is identical to the nominative singular for first declension nouns with weak plurals. These two oversights meant I could make no sense of it, despite having identified the meaning of the nouns. Go rabh maith agad a chara. ↩
It is interesting comparing this 1892 recording of the riddle with versions from the The Schools' Collection (1930s) and the LASID (1950s). Most of the later versions are significantly truncated, with all except one missing the first line and some missing enough that it evokes a child making a barely passable attempt at repeating something they've learnt. All of the examples in The Schools' Collection subsitute i gcúl for a' dul, changing the meaning from "eyes coming out of his head" to "eyes on the back of his head", which makes a lot less sense to me. The version from point 40 of the LASID:
Brian O Slupáin agus a chois tinn,
barr a bhróige i bpoll a thóna,
agus a dhá shúil mhóra amuigh ós a chionn
The versions I found in The Schools' Collection:
- An Trá Bháin, Contae na Gaillimhe. This is the fullest version in The Schools' Collection. The frog is named Seán Ó Lupáin, "Johnny McHands" perhaps.
- An Spidéal, Contae na Gaillimhe. This is very truncated. The frog is named Mach Uí Stíopháin. It is a little hard to make out of the "t" in Stíopháin is indeed a "t".
- Gaillimh. This one varies the most from the others.
- An tInbhear, Contae Mhaigh Eo. Also very truncated. The frog is called Mach Uí Stiopháin.
- Béal Feirste, Contae Mhaigh Eo. Also very truncated. The frog is called Mac Ui Shliop.
- Béal Feirste, Contae Mhaigh Eo. The riddle is (presumably accidentally) repeated twice. The frog is called Mac I Shliopán.
Vaguely similar riddles elsewhere:
- Baile Uí Dhuinn, Contae Chiarraí
↩
Dorian (1981) pp. 111-112:
There are at least five aspects of linguistic behaviour [...] in which the dominance of English over Gaelic is less complete than might be anticipated. First, despite the association of English with modernity and technology and the public spheres of life, no topic connected with these aspects of life forces a choice of English. If the setting and the interlocutor permit, any topic, no matter how sophisticated or remote from local life, can be discussed in Gaelic. Closely related to this aspect of resistance to English dominance is the thorough-going integration of English lexical borrowings into Gaelic; this integration makes possible the use of Gaelic for all topics."
Emphasis my own. The idea that an expanded "native" lexicon is required for a language to expand its spheres of usage is also rejected in Lewin (2016):
"[on a quote declaring Fargher's dictionary as making it possible for Manx speakers to discuss topics like atomic physics] This passage implies that it was impossible to discuss subjects like atomic physics etc. before the appearance of the dictionary, ignoring the fact that many neologisms had been developed and were in use within the small community of speakers in earlier decades, not to mention the fact that Manx speakers are at liberty to borrow from English specific lexis where no pre-existing Manx word exists or is remembered."
↩
This replacement of native speakers' grammar, erasing a unique history of language contact and adaptation, is something I can see only as cultural vandalism. However, for more nuanced and detailed thoughts on Fargher's work I will again refer to Lewin's work. As he puts it in Lewin (2017):
[it is perhaps] problematic if the native Manx of the past is implicitly (or explicitly) rejected as being not Manx enough. Efforts to purge Manx of grammatical and lexical influence from English arguably constitute a purism of a simplistic and unnecessarily xenophobic kind, which disregards the lived experience of centuries of Manx speakers, for whom some contact with English and borrowing of English forms was an inherent part of their linguistic world, and reflects a discourse which comes close to blaming the traditional speakers for letting their language become ‘impure’. It also makes the native Manx texts of the past less accessible to new speakers.
↩

"The most common vowel in English"?

2025-10-20T00:00:00+01:00

[hʉz̥ ɪ̞̠̃ŋgɫɪ̞̠ʃ]?

Popular factoids about the English language often leave me feeling contrarian, as a native speaker of a variety of English often not included in these broad, unqualified statements. "English has no second person plural"? What do yous mean? And the seemingly ever popular: "schwa is the most common vowel in English".

This last statement has often left me puzzled, as I've never been able to confidently perceive this sound in my own speech. Is this a lack of skill, a misunderstanding, or is my phonemic intuition pointing at some truth about my English that can make me feel superiorly contrarian once again?

My English

In the Tom Scott video linked above (which you should watch if you don't know what "schwa" is) he says to the viewer "[when you name the letter "a"] you're actually making two separate vowel sounds, /eɪ/". A bold statement, because I say it with a monophthong: /e/.

Compare a Southern Standard British English recording of "face" [fɛjs]¹:

to me saying "face" [fes]:

They sound quite different², and you can see in the spectrogram (which shows frequency content over time) that the formants (the most prominent frequencies) of the SSBE vowel vary, but are very steady in mine:

So where do you think I'm from? If you know much about accents of English then there are only a few options based on my pronunciation of "face" and my being a native speaker, and I don't think my being disgruntled by an English person incorrectly telling me how I speak does much to narrow it down. Here's a bit more of my speech, taken from my reading of "Comma Gets a Cure", before I tell you more:

"that itchy goose" [ðaʔ ɪ̞̠t͡ʃe gʉs]

Your browser does not support the audio element.

And here's a clip from a voice note sent to some pals, for a sample of some more spontaneous speech: Your browser does not support the audio element.

That's right, I'm Scottish! But despite this being a post about my speech, I'm not going to share too many more clips, because I am shy, and because I don't want you to make a clone of my voice.

Here are some known and possible influences on my speech:

I grew up in Edinburgh in the east of Scotland.
I was raised by my parents who are both from Clydebank in the west of Scotland.
I went to university in Cambridge in England 2010-2014, living there about half the year.
I lived in Cambridge full-time 2014-2019.
I have lived in Oxford since 2019.
My partner is English, from Surrey.
My maternal grandmother was from Donegal in Ireland, as were my maternal grandfather's parents. I spent most summers in Donegal as a child.
I was born in the early 1990s.

Any city has a wide range of speech, and I wouldn't say my speech is representative, but I would say it's not atypical of where I'm from³. I think living in England has undoubtedly changed my accent, which makes me sad, but it's still distinctively Scottish. I think any Irish influence is not phonetic, but shows up in some turns of phrase and syntax, like use of Hiberno-English "would"⁴ and "so"⁵. This is the main influence on my mother's speech also, though she also makes pulmonic ingressive sounds like the inhaled "yeah"s here.

Common transcriptions of schwa /ə/

There are a few places where SSBE and many American accents⁶ have schwa. Making reference to Wells' lexical sets:

COMMA: words that end with an open syllable (i.e. with a vowel) are transcribed as ending in schwa in both SSBE and in General American, e.g. /kɔmə/ (SSBE) and /kɑmə/ (Am)
NURSE: stressed syllables with Middle English /i/, /ɛ/, /u/ followed by /r/. E.g. /nəːs/ (SSBE) and /nərs/ (Am).
In weak (unstressed) forms of certain common single syllable words like "the", "a", "at".
In many unstressed syllables, for example in these SSBE transcriptions⁷: "villain" /vɪlən/; "patent" /patənt/; "synthesis" /sɪnθəsɪs/.
Some accents of English (including many Americans, and perhaps increasingly speakers whose speech could be described as SSBE) use schwa in even more unstressed syllables where older southern English accents would have /ɪ/, for example "private" as /praɪvət/
Some accents of English (including many Americans, but also some northwest English and Welsh accents) use schwa for the STRUT lexical set (e.g. "gun", "love", "much" "blood").

So what about my English? Intuitively I can say:

My COMMA vowel is far too open to be schwa
Like all Scottish people I know, the NURSE vowels didn't all merge for me. I think everyone I know (biased to the central belt⁸) has /fʌr/⁹ for "fir" and "fur". I say /fɛrn/ for "fern", often realised [fɛɾɪ̆n]. Similarly I say "world" as [wʌɾʌ̆ɫd]¹⁰.
I'm less sure about the remaining examples, but some of them I would identify with my KIT vowel rather than schwa.

I did some crude formant analysis¹¹ comparing my vowels in the KIT, STRUT, and COMMA lexical sets, and weak forms of non-content words.

What I'm taking from this:

My commA vowel is equivalent to my STRUT vowel
My KIT vowel is used in weak forms of non-content words

What about unstressed syllables in words like "villain" and "synthesis"? The passageI used for most of my analysis had very few incidences of these syllables¹², so I recorded myself saying individual words¹³. There they are for your enjoyment and analysis:

Your browser does not support the audio element.

These words, along with "woman" (from my passage reading), are plotted here against my KIT and STRUT vowels:

At last! A distinct schwa vowel. So it does exist! The outlier among the KIT vowels is "woman" which I pronounce with /ɪ/. In fact, many of the KIT examples I used were unstressed and would have been schwa in an accent with a complete weak vowel merger. But I'm not going to redo the analysis, I feel like it doesn't materially affect it.

With weak forms:

And with COMMA:

So in summary:

My STRUT vowel is distinct from schwa
My COMMA vowel is equivalent to my STRUT vowel, though perhaps sometimes goes more central towards schwa
My KIT vowel is used in weak forms of non-content words
I have an incomplete weak vowel merger, where some unstressed syllables that might be pronounced /ɪ/ are instead /ə/

So, is schwa the most common vowel in my English? It certainly doesn't seem like it. In my reading of "Comma Gets a Cure", I think the only word I use a schwa in is in the second syllable of "millionaire". (See this footnote¹².) One incidence in the entire passage doesn't sound like much to me! I think my having schwa only in some places in one of the many categories of syllables where schwa is usually pronounced results in this relatively rare incidence. Perhaps /ɪ/ is my most common vowel, on account of my using it for weak forms.

Superior contrarian feeling achieved 😌.

Appendix A: How mid-central is the vowel I've labelled "schwa"?

Something I haven't pointed out elsewhere in this post is that phonetic symbols and names like "schwa" have somewhat ambiguous and highly contextual meanings.

Take my KIT vowel, for example. I've seen vowel diagrams for Scottish English that put the KIT vowel much closer to schwa than the IPA chart shows [ɪ]. Similarly this "modern RP" vowel chart has a slightly lowered vowel.

Here they are superimposed, with the IPA's reference vowels shown in pink:

I'm not sure if this is an accurate plot of where my KIT vowel is, but it seems plausible.

There's an implicit assumption in my blog post that this difference between the IPA's definition of [ɪ] and my realisation of /ɪ/ is irrelevant to our discussions.

In a similar vein, when people repeat the meme of "schwa is the most common vowel in English", it can be unclear exactly what vowel they mean, and whether they are even aware of what they mean¹⁴. Do they mean any unstressed reduced vowel in their English? Specifically something in the near vicinity of the mid-central vowel on the IPA chart? Or just any sound they've seen transcribed as /ə/?

Anyway, here is me attempting a perfectly mid-central unrounded vowel, followed by my KIT vowel:

Formant analysis shows /ɪ/ with a slightly higher F1 and a more noticeably higher F2. This would make sense, as it would suggest a slightly less open, and noticeably more fronted vowel.

But how do the formants for my "perfect" mid-central vowel compare to the ones analysed in my speech?

Lol! It's hard to know if this is because my attempt at a phonetically perfect mid-central vowel was poor, or because the vowels I labelled schwa live somewhere else on the vowel chart. Regardless, using /ə/ to transcribe them is in keeping with tradition, particularly as they seem to contrast with my KIT vowel (which if it was my only mid-central vowel, you could argue would be sensibly transcribed as /ə/).

Appendix B: But what about, eeh, what's it called, "the hesitation vowel"?

Schwa is also sometimes called "the hesitation vowel", the vowel that English speakers use when they're trying to figure out what to say next. But I think I generally use my DRESS (or maybe FACE?) vowel if I'm going to make a vocalic hesitation noise while speaking, or maybe STRUT. Here are some examples taken from voice notes I sent friends:

/ɛ/

Your browser does not support the audio element. Your browser does not support the audio element. Your browser does not support the audio element.

/ɛm/? /ɛrm/?

Your browser does not support the audio element.

I think there's an idea that because the tongue position for schwa is "neutral", i.e. the tongue is at the mid-point of both the open-closed and front-back axes, that it's natural for speakers to default to it when reaching for what to say next.

I think what's natural is of course dependent on your native language(s). Take a look at these vowel diagrams for Arabic (three vowels), Japanese (five vowels), and Italian (seven vowels)¹⁵.

None of these show a schwa vowel. In Japanese it's most common to hear ええっと[e̞ːt̚to̞]¹⁶. The two vowels used there are both central, though they are front and back, respectively. My hesitation vowel is also mid. Is there something cross-linguistic at play here?

A brief look at this Reddit thread suggests some variation, but a lot of languages are listed as having mid vowel sounds, if I'm interpreting the crude transcription correctly: German, Kyrgyz, Finnish, Spanish. Notable exceptions appear to be Mandarin, Korean and Polish. This is quite a crude source of information however.

I love learning about phonetics and phonology: I love learning how speech sounds are made, about differences and similarities between the sounds of different languages, and how some differences in speech are immediately perceptible depending on context and your native language, and others are much harder to perceive.

I haven't posted on my blog in a while, and none of my previous posts have reflected this interest. I have a few fun ideas for projects and blog posts around these topics. Some of them are cross-language, some are specific to the second languages I am learning: Irish Gaelic and Japanese.

This post was my first try at posting about phonetics. If this is something you have expertise in, and you have any thoughts on my analysis, please do e-mail me at h@mcla.ug! I am not an expert and am very keen to learn.

If you're interested in why I've used a different transcription to Tom Scott for the SSBE pronunciation of "face", I recommend this video from Geoff Lindsey ↩
Mine is also shorter mostly because it is clipped from a longer utterance, whereas the SSBE recording is from a dictionary where the speaker has uttered a single word. ↩
Apart from my pronuncation of words like "stair" with /ɛ/ instead of /e/. Compare my pronunciation of Sarah Perry [sɛɾʌ pʰɛɾe]:
Your browser does not support the audio element.
to my school pal's [seɾʌ pʰɛɾe].
Your browser does not support the audio element.
My mother's is similar to mine:
Your browser does not support the audio element.
In Wells' "Accents of English" he says: "There are some Scots who have /ɛr/ rather than /er/ in SQUARE: they will say upst[ɛː]rs, not upst[eː]rs. I have heard the claim that this pronuncation is used only by Roman Catholics in the Glasgow conurbation, and that it is due to Irish influence. I am not in a position to substantiate or disconfirm this claim." My mother is indeed from Glasgow and we are indeed Fenians. ↩
Example: "I'd be a fan of that now" instead of "I am a fan". Or "she wouldn't be rich" instead of "she isn't rich". This feels natural to me, and I think I use it to indicate a certain subjectiveness or personal perspective. I do come across more objective usages that are less natural to me. Recently my cousin asked me "would you wear make-up". For the same meaning I would have said "do you wear make-up". So I wouldn't say I use it as broadly as people in Ireland. ↩
Example: "I'll go do that then so", not really sure what meaning the "so" adds but I think I say this all the time. Looking this up, it seems it's common in Ireland to replace "then" with "so" in such phrases, so perhaps I'm doubling up! But this is what I say. I also say "ok so" but don't think I really say "ok then". ↩
I don't know enough about American English accents to go into much detail about cultural and geographical factors that might affect the usage of schwa, despite being constantly subjected to American voices by media that I choose to consume of my own volition. I'm sorry if you are American and what I write here does not represent your accent. I have tried to make it clear that I am talking about some American accents and talking in broad terms of what dictionaries often transcribe things as. ↩
Taken from the CUBE dictionary ↩
I have read speakers from other areas have /fɪr/ for "fir". It's not like I've never met or heard anyone from outside the central belt! But not since I gained the sort of phonetic awareness that might cause me to notice this difference in pronunciation. ↩
My STRUT vowel has definitely changed a bit from living in England. When I am chatting to my Scottish pals or speaking loudly (e.g. over a noisy pub), my vowel changes to (I think) further back and more open. ↩
I haven't included any formant analysis for this set. It's harder to segment the vowels next to approximants, and I think some of my realisations are r-coloured vowels, which skews the F3 formant in a way that I think is distracting. ↩
I manually segmented the vowels and used the default formant analysis in Praat's vocal toolkit. I visually inspected the spectrograms to ensure the formants looked sensible. Most of the tokens are from my reading of "Comma Gets a Cure". I conceived the vowel distance plots myself from my understanding that relative difference between formants was most important for perception, so if you're a linguist and have thoughts on their usefulness I'd be grateful. I think they match what is done in the Bark Difference metric described here, without cross-speaker normalisation (as it's just me speaking). ↩
The words I picked out were: "woman" (two incidences, one of which had indistinct formants), "millionaire" (indistinct formants, perhaps due to pharyngealised /l/), "beautiful" (I have no intervening vowel between /f/ and /l/), "suffering" (I have no intervening vowel between /f/ and /r/). So only one usable token. In retrospect words like "private" could also have been used here, but as the CUBE dictionary transcribes it prɑjvɪt I had some impression that there was a difference between this and the other words. But I think it's just reflecting an incomplete weak vowel merger. I also use /ɪ/ in "private". ↩↩
This is less desirable as there's always a chance I might self-consciously pronounce the words differently than normal, or just stating them in isolation might be different from saying them in connected speech. But I think the recording sounds very normal to me. ↩
There are many linguists I respect, like Geoff Lindsey, who have said schwa is the most common vowel in English. I am not questioning whether he knows what he's talking about, more pointing out how much of a meme the "fact" has become, hence it is repeated without necessarily being understood. ↩
All of these languages have "non-standard" varieties, where I'm sure the vowels vary significantly. Certainly there are varieties of Japanese with more or less vowels than shown here. My knowledge of Arabic and Italian is much less. ↩
Japanese has a lot of "filler" words that are quite important parts of holding a conversation. I feel like ええっと or ええと or えっと is the best analogy for the places I would usually hestitate and go "eee" or "eem". One of the Reddit comments on the linked thread is about Japanese and lists some of these but I feel like only あの and ええと are used for unconscious hesitation, and the others are more expressive of specific sentiments. I would use あの more if I was shyly interrupting or about to say something I felt shy about, and えっと for stalling while I think of the next word to say. I am not a native speaker, however. ↩

Intro to Quantum Computing

2024-07-27T00:00:00+01:00

I work at a trapped ion quantum computing company writing compiler and control software in Rust and Python. I've had to learn about quantum computing for my work, and I have found it hard to find introductory literature that is both informative and accessible to me.

I thought it would be nice to put together my own introductory guide, and in the process improve my own understanding. After a lot of reading, and a lot of questions answered by my excellent colleague Dr Amy Hughes, I've put something together that covers some of what I was hoping.

I think the first section should be accessible even without much maths or physics knowledge. After that, some basic linear algebra knowledge will be helpful, as well as some basic knowledge of atomic structure.

I hope this will elucidate the basic idea of how quantum algorithms work, what "superposition" and "entanglement" mean and why they are useful, and give a concrete physical illustration of how these abstract ideas can be realised on an actual qubit.

Unpacking the hype

There are two properties of quantum computers that you might have heard about, expressed variously:

Qubits can be in many states at once! Each qubit exists in a superposition of 0 and 1!
We can entangle qubits together, so that the state of one qubit determines the state of others!

Somehow we are to believe that these properties allow quantum computers to be large and efficient parallel machines. In some sense this is true: superposition allows quantum computers to explore multiple computational paths simultaneously, and entanglement creates a state space that grows exponentially with the number of qubits. But when you measure a qubit, you get a value of $0$ or $1$. So what good are our vast parallelised computations if our output is compact, encoded in the same binary digits we get out of a classical computation?

A small amount of classical information becomes a large amount of quantum information during the quantum computation. But the result is again a small amount of classic information. How can this be useful?

One of the things quantum computers are useful for is extracting some property of the large superposed state. So rather than quantum computers being useful for calculating lots of numbers in parallel, they can be useful for calculating, say, one number that describes some structure in a vast collection of many other numbers.

Shor's algorithm uses quantum computers in this way. Public-key cryptography methods such as RSA multiply two large prime numbers together to generate the encryption key. Those two large prime numbers are kept secret, as the decryption key can be derived from them. Hence, the security of such encryption methods relies on it being infeasible for classical computers to find prime factors of a large integer. In Shor's algorithm, the problem of factoring that integer is reduced to finding the period of a repeating sequence. That sequence is then encoded into the qubits' state and the period is computed as the compact output of the computation.

Factoring an $n$-bit integer with Shor's algorithm requires something like $2n + 3$ logical¹ qubits², depending on the implementation. So for an 2048-bit integer, as often used for RSA keys, something like 5099 logical qubits would be required. At writing, the most powerful quantum computer in the world has the equivalent of 20³.

Re-visualising the flow of information

We can now update our image above:

Many quantum algorithms exploit the large quantum state space to encode information that has some kind of large pattern or structure. That structure is then efficiently extracted.

Importantly, quantum computers are not equivalent to many parallel classical computers. The quantum state space may be vast, but the result of our computation is compact. This makes them suitable for computations that can be formulated into the general structure shown in the image above, but not for simply parallelising many classical computations.

How exactly do we go from lots of quantum information to a small amount of classical information?

As we've previously stated, when you measure a qubit you get a compact result of 0 or 1. Before that measurement, we have a great deal more information. Don't we want that information? How do we distill the information we're interested in into our compact output?

As we'll explore further in a later section, a qubit's state is expressed using complex numbers that represent measurement probabilities. A qubit in superposition is one that has <100% probability of being measured as 0 or 1. If our algorithm resulted in every qubit having a 50% probability of being measured as 0 or 1, it would be indistinguishable from noise. So probabilistic quantum algorithms must manipulate the probabilities such that we have a high probability of measuring something useful.

Manipulation of qubit state is done via quantum logic gates, or simply gates. All gates are linear operators: each output is some linear combination of every input. So when we perform a multi-qubit gate, each qubit's state becomes a weighted sum of the input qubit states. When doing this sum, the qubit states can cancel each other out (destructive interference) or amplify each other (constructive interference).

We can think of our quantum algorithms as exploring many computational paths, then pruning off those that aren't of interest, leaving us with a high probability of measuring the result we desire.

What does the quantum state actually look like?

For a single qubit

The state of a single qubit can be described by two complex numbers, which encode the probability of measuring $0$ or $1$. If you can forgive the introduction of some notation without it being fully explained, we'll use $\ket{0}$ to describe 100% probability of measuring $0$, and $\ket{1}$ for $1$'s equivalent. Our qubit state $\ket{\psi}$ is then described by a linear combination of these:

$$ \ket{\psi} = a_0\ket{0} + a_1\ket{1}, a_i \in \mathbb{C} $$

The complex numbers $a_i$ are known as probability amplitudes, and their square magnitude gives the probability of measuring the corresponding output. For example, the probability of measuring $0$ is given by ${\left|a_0\right|}^2$.

We cannot directly observe the probability amplitudes, only the binary result of measurement. Why? Intuitively: how could you measure a probability directly? More honestly: well, why does an electron have charge? There are many things in the world that we can observe (whether directly or through complex experimentation) and describe with mathematics -- but ultimately they are "just the way it is".

For multiple qubits

For every $n$ qubits, we have $2^n$ possible measurement outcomes. For example, for 3 qubits we have possible results of $000, 001, 010, 011, 100, 101, 110, 111$. Each of these outcomes has a probability amplitude associated with it:

$$ \ket{\psi} = a_0\ket{000} + a_1\ket{001} + a_2\ket{010} + \dots a_7\ket{111} $$

Why is it necessary to describe the joint probability distribution across all qubits? Why can't we factor these into independent distributions for each qubit, giving us $2n$ probability amplitudes instead of $2^n$?

When qubits are entangled, their measurement outcomes are linked. Therefore, a general description of the state for multiple qubits must describe a joint probability distribution over the qubit measurement outcomes, rather than independent distributions for each qubit.

Hence, entanglement is what creates the exponential growth of the state space with the number of qubits.

How exactly does the state scale compared to classical computers?

It's not obvious how best to quantify the difference in scale between our $\mathbb{C}^{2^n}$ quantum state space and our $\mathbb{Z}_{2}^{n}$ classical state space . One way we can directly compare them is by considering degrees of freedom.

In a classic computer, we have as many degrees of freedom as we have bits. You can fully describe the state of $n$ bits with $n$ values of 0 or 1.

In a quantum computer, the degrees of freedom scale exponentially with the number of qubits. How?

Comparing how the degrees of freedom in classical and quantum computers scale with the number of bits

From our equation for multi-qubit state, we know that the state of $n$ qubits is described by $2^n$ complex numbers. Absent any constraints, $2^n$ complex numbers would have $2 \times 2^n = 2^{n+ 1}$ degrees of freedom: each complex number is minimally and fully defined by two real numbers, an amplitude and a phase. As the square magnitudes of our complex numbers represent probabilities, we have the constraint $\sum_{i = 0}^{i = 2^n - 1}\left|a_i\right|^2 = 1$, which removes one degree of freedom. We eliminate another degree of freedom due to the fact that the relative phase of $a_i$ are observable, but the global phase of $\psi$ is not: constraining $a_0$ to be real (or, arbitrarily, imaginary) does not change the physical meaning of $\psi$. That leaves us with $2^{n+1} - 2$ degrees of freedom.

Visualising qubit state

We can visualise a single qubit's state on a unit sphere, known as the Bloch sphere:

The qubit's state vector always has magnitude one, hence it always touches the surface of the unit sphere. The angles $\theta$ and $\phi$ are one way of expressing our two degrees of freedom. We can write:

$$ \ket{0} = \begin{bmatrix} 1 \\ 0 \end{bmatrix} \equiv \begin{bmatrix} \cos\frac{\theta}{2} \\ 0 \end{bmatrix} $$

$$ \ket{1} = \begin{bmatrix} 0 \\ 1 \end{bmatrix} \equiv \begin{bmatrix} 0 \\ e^{i\phi}\sin\frac{\theta}{2} \end{bmatrix} $$

We will call the states $\ket{0}$ and $\ket{1}$ our computational basis, or simply our basis states.

But what about visualising multiple qubits?

The Bloch sphere gives us a convenient way of visualising the state of a single qubit, but what about multiple qubits? As previously described, if there is no entanglement, then the state of a multi-qubit system can be factored into separate individual qubit states. In that case, we can visualise the state of $n$ qubits on $n$ Bloch spheres. If there is entanglement, we cannot factor our many-dimensional state into multiple 2-dimensional states, and so visualisation can be challenging. We won't provide any visualisations here, but there are several proposed methods⁴⁵.

Manipulating qubit state

Now that we can visualise a single qubit's state on the Bloch Sphere, we can more easily imagine that state being manipulated. What would it mean for the state vector to be aligned with the positive $x$ axis? That's $90^{\circ}$ rotated around the $y$ axis from either of our basis states. So it's half way between them! This is superposition.

Superposition on the Bloch sphere

We can write the state vector in terms of $\ket{0}$ and $\ket{1}$:

$$ \ket{\psi} = \frac{1}{\sqrt{2}}\left(\ket{0} + \ket{1}\right) $$

Remember, the square magnitude of the coefficients of the basis states gives us the probability of measuring them. In this case, $\left|\frac{1}{\sqrt{2}}\right|^2 = \frac{1}{2}$: we have an equal probability of measuring either $0$ or $1$.

Manipulating qubit state is also described as executing a quantum logic gate, or gate for short. We can write a matrix operator for a gate that would take a qubit from $\ket{0}$ to the superposed state shown in the images above (although via a different rotation than described above):

$$ \frac{1}{\sqrt{2}}\begin{bmatrix} 1 & 1 \\ 1 & -1 \end{bmatrix}\ket{0} = \frac{1}{\sqrt{2}}\left(\ket{0} + \ket{1}\right) $$

This gate is known as the Hadamard gate, is shown graphically as a square with an H in it:

Creating entanglement

Let's demonstrate how entanglement is created between two qubits. Similar to our single and multi-qubit equations above, if we have two qubits we can write:

$$ \ket{\psi} = a_0\ket{00} + a_1\ket{01} + a_2\ket{10} + a_3\ket{11} $$

Where e.g. $a_1$ is the probability amplitude associated with measuring $0$ for the first qubit and $1$ for the second. How would we find the coefficients ${a_0,a_1,a_2,a_3}$ given the state vectors of the individual qubits? For two qubits $c$ and $t$:

$$ \begin{aligned} \ket{\psi_c} &= c_0 \ket{0} + c_1 \ket{1} \\ \ket{\psi_t} &= t_0 \ket{0} + t_1 \ket{1} \end{aligned} $$

we compute the state vector $\ket{\psi}$ of the two qubit system using the tensor product of the individual qubits' state vectors:

$$ \begin{aligned} \ket{\psi} &= \ket{\psi_c} \otimes \ket{\psi_t} \\ &= \begin{bmatrix} c_0 \\ c_1 \end{bmatrix} \otimes \begin{bmatrix} t_0 \\ t_1 \end{bmatrix} \\ &= \begin{bmatrix} c_0 t_0 \\ c_0 t_1 \\ c_1 t_0 \\ c_1 t_1 \end{bmatrix} = \begin{bmatrix} a_0 \\ a_1 \\ a_2 \\ a_3 \end{bmatrix} \end{aligned} $$

We can now apply two-qubit operators to this vector, in the same way we applied the Hadamard gate matrix to the single qubit state vector. The controlled NOT or CNOT gate operates on two qubits: a control qubit ($c$) and a target qubit ($t$). It is defined by this matrix:

$$ CNOT = \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \end{bmatrix} $$

and performs this transformation:

$$ \begin{aligned} &a_0\ket{00} + a_1\ket{01} + a_2\ket{10} + a_3\ket{11} \\ \rightarrow \hspace{0.5em} &a_0\ket{00} + a_1\ket{01} + a_3\ket{10} + a_2\ket{11} \end{aligned} $$

In other words, the probability amplitudes for the measurement outcomes $\ket{10}$ and $\ket{11}$ are swapped. If the control qubit is purely $\ket{1}$, then the target qubit is flipped. If the control qubit is purely $\ket{0}$, then $a_2$ and $a_3$ equal $0$, and there is no effect. If the controls qubit is in superposition, then the effect on the target qubit will be correspondingly superposed.

Let's apply a CNOT gate to our qubits $c$ (for control) and $t$ (for target):

$$ \begin{aligned} \psi &= \begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \end{bmatrix} \begin{bmatrix} c_0 t_0 \\ c_0 t_1 \\ c_1 t_0 \\ c_1 t_1 \end{bmatrix} &= \begin{bmatrix} c_0 t_0 \\ c_0 t_1 \\ c_1 t_1 \\ c_1 t_0 \end{bmatrix} \end{aligned} $$

If $C$ is $\ket{0}$, then ${c_0, c_1} = {1, 0}$:

$$ \psi = \begin{bmatrix} t_0 \\ t_1 \\ 0 \\ 0 \end{bmatrix} $$

and if $C$ is $\ket{1}$, then ${c_0, c_1} = {0, 1}$:

$$ \psi = \begin{bmatrix} 0 \\ 0 \\ t_1 \\ t_0 \end{bmatrix} $$

By inspection, we can see that these are factorisable into separate qubit states:

$$ \begin{aligned} \begin{bmatrix} 1 \\ 0 \end{bmatrix} \otimes \begin{bmatrix} t_0 \\ t_1 \end{bmatrix} &= \begin{bmatrix} t_0 \\ t_1 \\ 0 \\ 0 \end{bmatrix} \\ \begin{bmatrix} 0 \\ 1 \end{bmatrix} \otimes \begin{bmatrix} t_1 \\ t_0 \end{bmatrix} &= \begin{bmatrix} 0 \\ 0 \\ t_1 \\ t_0 \end{bmatrix} \end{aligned} $$

But what if our control qubit $C$ was in superposition? E.g. ${c_0, c_1} = {\frac{1}{\sqrt{2}}, \frac{1}{\sqrt{2}}}$. If our target qubit is $\ket{0}$ then we get:

$$ \psi = \begin{bmatrix} \frac{1}{\sqrt{2}} \\ 0 \\ 0 \\ \frac{1}{\sqrt{2}} \end{bmatrix} $$

What happens if we try to factor this into two separate qubit states? Using a $'$ to denote the new states of the qubits:

$$ \begin{bmatrix} \frac{1}{\sqrt{2}} \\ 0 \\ 0 \\ \frac{1}{\sqrt{2}} \end{bmatrix} \stackrel{?}{=} \begin{bmatrix} c_0' t_0' \\ c_0' t_1' \\ c_1' t_0' \\ c_1' t_1' \end{bmatrix} $$

It's not possible for these to be equal: for the first entries and last entries of each vector to be equal, all of the coefficients $c_0', c_1', t_0', t_1'$ must be non-zero. But for the middle entries of the vectors to be equal, at least two of the coefficients must be zero. Hence it is not possible for us to factorise this state vector into two separate qubit states.

We have created an entangled state. We can only describe the state of the two qubit system: we cannot meaningfully describe the qubits separately.

How do you actually make a qubit?

Making a quantum computer requires extremely fine control of the quantum state. The larger an object is, the harder that control becomes. Even a simple molecule presents challenges, as the state is affected by minute changes in the relative position of its component atoms due to thermal vibration.

There are a variety of different qubit types used, but we'll use trapped ions as an example below.

Trapped ion qubits

What do $\ket{0}$ and $\ket{1}$ correspond to physically?

In a trapped ion qubit, we map discrete excitation states of an ion to our computational basis states $\ket{0}$ and $\ket{1}$. Which excitation states you choose depends on various properties, including how stable the states are, and how they can be measured. We'll give an example below of a specific architecture that might be used.

How do we measure the qubits to get the output of our computation?

As an example, let's take single-charge ions of an element from Group 2 of the periodic table. Neutral atoms would have 2 electrons in their outermost electron shell, so our +1 charge ions have a single electron in that shell. In the below diagram, the labelled horizontal lines are energy levels (e.g. S1/2) of this electron, increasing in energy vertically. Each of the letters (S, P, D) represent an electron sub-shell, and the numbers are a measure of momentum.

    P1/2____________________
               )     ^
              (      |
               )     |               ________________________D5/2
              (      |                   (          ^
               )     |                    )         |
              (      |                   (          |
               )     |                    )         |
              (      |                   (          |
               )     |                    )         |
    S1/2_______v_____v____________________v_________v________S1/2
         |                       |                         |
         |   fluorescence        |       shelving and      |
         |   cycle               |       de-shelving       |
         |_______________________|_________________________|

     )                        ^
    (  = spontaneous decay    | = laser-driven
     v                        v

Within each energy level there are multiple excitation states. For ions with no nuclear spin, there are two states in S1/2, which correspond to the two possible spin states of the electron. If we map our computational bases $\ket{0}$ and $\ket{1}$ to these two states, how could we then measure the result at the end of our computation?

When ions decay from a higher energy state to a lower energy state, the lost energy is emitted as a photon. Photons are something we can measure. In our example, both of our computational basis states are in S1/2. We can make the ions fluoresce by hitting them with a laser with the appropriate wavelength to drive transitions between P1/2 and S1/2. The laser drives transitions in both directions, so if we keep the laser on, the ions will continuously swap between P1/2 and S1/2, emitting photons when they move from the higher energy state to the lower.

However, because both of our computational bases are in S1/2, we won't be able to differentiate between measuring a 0 and a 1! The properties of this transition are such that it's not feasible to have a laser that could select one of our two states within S1/2. Luckily, the transitions between S1/2 and D5/2 can be driven selectively. So, prior to measurement we "shelve" by mapping one of our bases only to an excitation state in D5/2. Measurement is then done when inducing fluorescence: this is when we get a final 0 or 1 measurement out from each qubit. The ions will be in a superposition of a state in S1/2 and a state in D5/2. Some will be measured to have been in S1/2 (as these will fluoresce, which we measure as 1) and others will be in D5/2 (as these will not fluoresce, which we measure as 0).

The D5/2 is stable enough for us to keep the ions there until we've collected enough photons to make a measurement. We can tune our light detection to photons of the frequency that will be emitted by P1/2 -> S1/2 transitions, so that other spontaneous decay does not affect our measurements.

Will quantum computers replace classical computers?

Quantum computers are only well-suited to certain classes of problems, so I don't think it's likely that they'd replace classical computers. The goal is to enable solving of computational problems we can't solve today, not to solve the same problems with a new kind of computation.

Are quantum computers useful?

Not yet! Lol.

But hopefully they will one day enable us to do useful things we can't do today. The most exciting one for me is that quantum computers should enable more simulation of quantum mechanics, which in turn will enable better drug discovery.

Designing a RISC-V CPU, Part 2: Successfully executing (some) instructions

2021-03-01T00:00:00+00:00

The previous instalment of this series was "basically an explanation of what FPGAs are and a 'hello world' nMigen example."¹ In this post, I will be detailing the design of my CPU as it currently stands, and going over the various mistakes I made along the way. As with the previous post, I am primarily aiming this at software engineers who are new to hardware design – but I hope it will be interesting to anyone interested in nMigen, RISC-V, or CPU design generally.

I hope the mistakes I made along the way will be a useful frame for considering these questions:

What about digital logic design is fundamentally different from software design?
What about digital logic design is similar to software design?

You can see the code for my CPU at the time of writing here or an up to date version here.

An introduction to RISC-V

RISC-V ("risk five") is an open standard instruction set architecture (ISA). "RISC" means "reduced instruction set computer", broadly meaning that the ISA prioritises simple instructions. In contrast, CISC (complex instruction set computer) ISAs are optimised to perform actions in as few instructions as possible, hence their instructions are often more complex. ARM architectures are RISC; x86-related architectures are CISC.

Usually in industry, ISAs are patented, so in order to implement the ISA you need an (expensive) license from the vendor. Often, commercial ISAs are poorly documented, with the motivation behind design details not always being available even after such a license agreement.

From the RISC-V spec ²:

Our goals in defining RISC-V include:

A completely open ISA that is freely available to academia and industry

a real ISA suitable for direct native hardware implementation, not just simulation or binary translation.

An ISA that avoids "over-architecting" for a particular microarchitecture style, but which allows efficient implementation in any of these.

Additionally, a lot of commercial architectures are complex and burdened with backwards-compatibility constraints. RISC-V offers a fresh start!

The ISA doesn't explain the details of how to design a CPU – it just defines an abstract model of the CPU, mostly by defining what instructions the CPU must support, including:

The encoding of the instructions (i.e. how to construct the machine code that the CPU will run)
The registers (the very fast, very small storage locations accessed directly by the CPU)³

How to actually create a CPU that realises these requirements is up to us \o/

A quick note (feel free to skip if you don't have opinions about CPUs)

I'm trying to design a single-stage CPU; that is, I'm trying to design a CPU that retires one instruction per clock cycle with no pipelining. Usually CPUs have pipelining in place to maximise efficiency. I am hoping that avoiding this will result in a simpler design more suitable to my learning. Perhaps it will complicate other aspects of the design (like my program counter having 3 outputs), but I'm certainly finding it easier to hold the design in my head when I only have to think about this clock cycle and the next. I will likely discuss this in more detail in the next blog post where I implement the load instructions. I have a plan for how to make these work in a single cycle, but they do pose a particular challenge and I may change my design as a consequence.

Designing a CPU

RISC-V defines various ISA modules; I will be implementing RV32I, the base 32-bit integer instruction set.

To design my CPU, I first looked at the JAL (jump and link) and the ADDI (add immediate) instructions, and drew a block diagram of what hardware would be needed to decode those instructions. I think the ADDI instruction is easier to grasp if you're not used to thinking about how machine code is encoded, so we'll start with that. If this all totally foreign to you, you might enjoy my introduction to ARM assembly.

Decoding ADDI

ADDI adds the sign-extended 12-bit immediate to register rs1

Let's break some of this down, imagining we're decoding such an instruction:

An immediate is analogous to a literal value in source code; the value itself is encoded in the instruction, rather than e.g. retrieved from a register.
The opcode field is the same value for all the instructions listed here.
Once we've read the opcode, we know that bits 12-14 contain the funct3 field (3 for 3 bits), which encodes whether this is an ADDI instruction (or SLTI, ANDI &c.)

So, somehow we will have to:

Retrieve the value stored in register rs1
- Therefore, our register file needs an input for selecting this register to read, and an output for the data read from that register.
Add that to the immediate value
- An arithmetic logic unit (ALU) will be helpful
Store the result in register rd
- Our register file also needs write select and write data inputs.

Sign-extension will be necessary too – this is just the process of taking a number narrower than (in our case) 32 bits, and filling in the remaining bits such that two's complement arithmetic will be performed correctly. I won't include this in the diagram below.

Implicit in all this is that we'll need some way to retrieve the instruction itself and pass it to the instruction decoder. The program counter is what tells the instruction memory which address to retrieve an instruction from.

I'm using thick cyan lines for data flow and thin magenta lines for control flow.

JAL

Now let's try doing the same for JAL.

The jump and link (JAL) instruction [...] immediate encodes a signed offset in multiples of 2 bytes. The offset is sign-extended and added to the pc to form the jump target address. [...] JAL stores the address of the instruction following the jump (pc + 4) into register rd.

There's a lot more going on here, particularly if you aren't familiar with machine code. We noted above that the program counter sets which instruction will be executed next. Usually the program counter simply increments to the next address each cycle – that's how we continue to execute our program! However, say our program calls a subroutine stored elsewhere in memory; we'd need a way to jump to the subroutine address. Or, say we wanted an infinite loop (ubiquitous in embedded software!); we'd need a way to jump⁴ back to the address at the start of the loop. JAL allows for these situations.

The "link" part of JAL is the part where the next instruction is stored in the destination register. This is convenient when the jump is used to execute a subroutine: once the subroutine completes, we can jump back to that stored instruction address.

Here's the encoding for JAL:

Note:

The opcode uniquely defines the JAL instruction (no other instructions share this opcode)
We need to unshuffle the immediate to get the offset
The LSB⁵ of the immediate is not encoded because it must be 0: only offsets in multiples of 2 bytes are supported.

The unshuffling caused me some pain in my code, so it's amusing to me that it won't be part of the block diagram below. But it's part of the internals of the instruction decoder, not its interface, which is what we are determining with these diagrams. The shuffled bits might seem nonsensical, but they're chosen to maximise overlap with other instruction formats in RISC-V.

Putting ADDI and JAL together

The next challenge is to draw a block diagram that implements both ADDI and JAL. The first obvious problem: the inputs to the ALU are different in both cases, as is the wiring of the output. We need some kind of logic block that can pick between them depending on some control signal: a multiplexer (mux).

We also need a way to tell the program counter whether the next instruction address should come from a set address or from incrementing the current address.

Here's what my design looks like at the moment (excluding a few things I have because I know I'll need them later, like two read select/data signals on the register file):

Implementing the design

As covered in my previous blog post, I'm using nMigen to implement my design. As I'm currently designing a single-stage CPU, more of my design is combinatorial, rather than synchronous, because I don't require the additional state that pipelining necessitates. This most likely means my design is unable to run quickly, but that's not a concern of mine.

I don't think it's helpful to post all the source code of my implementation in this blog, but I will include some code here to illustrate mistakes that I made and what I learned from them.

Mistake #1: thinking about my logic circuit sequentially

I initially implemented my program counter incorrectly after I got really confused about when synchronous updates would take effect. I initially only had the pc and pc_inc outputs because I didn't really understand the difference between pc and pc_next. It's taken some getting used to thinking about the whole logic circuit "happening at once"⁷, rather thinking sequentially like I would when writing software. This is what led to my confusion. Properly conceptualising your circuit in this way is key, and a challenge if you're used to writing software.

 1 """Program Counter"""
 2 import nmigen as nm
 3 
 4 INSTR_BYTES = 4
 5 
 6 
 7 class ProgramCounter(nm.Elaboratable):
 8     """
 9     Program Counter
10 
11     * load (in): low to increment, high to load an address
12     * input_address (in): the input used when loading an address
13 
14     * pc (out): the address of the instruction being executed this clock cycle
15     * pc_next (out): the address of the instruction being executed next clock
16       cycle
17     * pc_inc (out): the address after that of the instruction being executed
18       this clock cycle
19     """
20 
21     def __init__(self, width=32):
22         self.load = nm.Signal()
23         self.input_address = nm.Signal(width)
24         self.pc = nm.Signal(width)
25         self.pc_next = nm.Signal(width)
26         self.pc_inc = nm.Signal(width)
27 
28     def elaborate(self, _):
29         m = nm.Module()
30 
31         m.d.comb += self.pc_inc.eq(self.pc + INSTR_BYTES)
32         m.d.sync += self.pc.eq(self.pc_next)
33 
34         with m.If(self.load):
35             m.d.comb += self.pc_next.eq(self.input_address)
36         with m.Else():
37             m.d.comb += self.pc_next.eq(self.pc_inc)
38 
39         return m

When thinking about my implementation, I now want to answer these questions:

What is my state?
How are the outputs computed?
How is the state updated?

This sounds simple, but it has been clarifying. For this case:

pc is my state (you'll note it is assigned synchronously, so its value is updated at the start of the next clock cycle).
pc, pc_inc, and pc_next are the outputs:
- the pc output is the current state
- pc_inc is just pc + 4
- pc_next swaps between pc_inc and the input_address based on load
Each clock cycle, pc takes on the value of pc_next

Mistake #2: Creating a combinatorial loop

This isn't really an additional mistake, as the incorrect program counter implementation described above caused this. I felt this particular consequence deserved its own subsection.

When I only had the pc and pc_inc outputs from my program counter, I created the following combinatorial loop:

the pc output was an input to the ALU
but the pc output was computed from the output of the ALU

Both of these signals were in the combinatorial domain, so they were effectively wired together in a loop.

The creation of this feedback loop resulted in my tests hanging as my combinatorial simulations never settled. If I'd tried to synthesise my design, the synthesis tools would have refused. If you were able to synthesise such a design, the output would be constantly changing.

Mistake #3: Not creating the block diagram correctly

True Fans™ of this blog might notice that the block diagram above has a notable difference from the one shown at the end of the previous blog post: previously I didn't mux the input of the ALU. I was wondering why JAL wasn't working, and tried to trace it through my block diagram, like we did above. A re-enactment:

Computer, show my original sketch of the block diagram.

Computer, enhance:

Me:

The above is a bit frivolous, but I'd say the lesson here is to think actively about your block diagram (or whatever reference you are using while implementing your design), making sure it actually makes sense to you and does what you want it to. This applies to software design too when viewing any requirements or other design documentation, of course.

Miscellaneous mistakes

I made a lot of other mistakes that aren't that interesting to cover – most notably really messing up the unshuffling of the immediate in the JAL instruction. But that was just a programming error without an interesting lesson to be learnt from it.

Running my first program!

It was a very exciting moment when I figured out the last of the mistakes I had made in my implementation, with the help of my tests and of gtkwave.

For convenience in tests, my instruction decoding code also has code for assembling instructions. I use it here to create a simple program with two instructions:

An ADDI instruction where rd and rs1 are the same register, and the immediate is 1. This means it will increment the value in rs1.
A JAL instruction with an offset of -4, meaning it jumps back to our ADDI instruction. This creates an infinite loop where the value in a register is incremented each clock cycle.

The LED code is specific to my board. I'm selecting 4 bits (one for each LED) in the register and displaying them on the board's LEDs. I pick bits in the middle so they don't change too quickly to see (as would be the case if I picked the LSBs) or too slow to look cool (as would be the case if I picked the MSBs).

 1         program = [encoding.IType.encode(
 2                         1,
 3                         reg,
 4                         encoding.IntRegImmFunct.ADDI,
 5                         reg,
 6                         encoding.Opcode.OP_IMM),
 7                    # jump back to the previous instruction for infinite loop
 8                    encoding.JType.encode(0x1ffffc, link_reg)]
 9 
10         imem = nm.Memory(width=32, depth=256, init=program)
11         imem_rp = m.submodules.imem_rp = imem.read_port()
12         m.d.comb += [
13                 imem_rp.addr.eq(cpu_inst.imem_addr),
14                 cpu_inst.imem_data.eq(imem_rp.data),
15         ]
16 
17         colours = ["b", "g", "o", "r"]
18         leds = nm.Cat(platform.request(f"led_{c}") for c in colours)
19         m.d.sync += leds.eq(cpu_inst.debug_out[13:17])

And here is a poor quality gif of the LEDs! Very exciting.

The next stage will be to implement the rest of the RV32I instructions. Probably I will start with the load instructions, as I think they will pose a challenge in my current single-stage architecture. I have a plan for how to address that. If you'd like to see future instalments of this blog series, you can follow me on Twitter or subscribe to my RSS feed.

Differences and commonalities between software design and digital logic design

Now that I've completed a lot more of the design and implementation of my CPU, I have some clearer thoughts on this topic. I thought there would be some clear differences in kind between software design and digital logic design. After much thought, I wonder if there are merely differences in degree.

Concurrency

First, let's consider concurrency. This is a topic that's sometimes misunderstood, so let's be clear: concurrency happens whenever different parts of your system might execute at different times or out of order⁶. A system is concurrent if it can support having multiple tasks in progress at the same time; this could be in parallel, or it could involve switching between the tasks while only actually executing one at any given moment.

Arguably, the default state for software is to have no concurrency – it often needs explicitly created (e.g. by creating a thread), or at the very least, it needs explicitly handled (e.g. in an interrupt handler). I think any software engineer who has worked on concurrent software would agree that dealing with concurrency is a singular challenge that creates room for difficult and subtle bugs. For these two reasons, software generally has limited concurrency.

Now imagine concurrency is your default state, and that every single piece of state is updating all at once every step of your program.

That is the default state of digital logic. While in software you generally have to explicitly create (or at least explicitly handle) concurrency, in hardware you have to deliberately make something sequential.

I said above that concurrency in software is challenging. If digital hardware has more concurrency, is it more challenging to design? Perhaps! It's hard for me to comment on this due to my lack of experience in hardware design.

Perhaps one reason that concurrency is so difficult in software is the annoying habit of a lot of software⁸ to be dependent on a colossal amount of state. How many possible states does a mere kilo-bit of memory have? 2^{1024} is too big a number for me to conceptualise. And yet a kilo-bit is nothing by many program's standards.

In hardware, state is more precious. My FPGA is only so large. I have an ice40hx8k, which has 8000 logic cells. Each cell has one 4-input LUT and one flip-flop: so let's say 8000 bits of state. Pathetic! Watch me create millions of bits of pure chaos with a single call to malloc.

And of course, if you were designing for silicon, the size of your design would be directly related to cost!

Verification

So, we've considered concurrency. Another thing I wondered is whether digital hardware has some fundamental property that makes it easier to formally verify, or at least to demonstrate equivalence with a model. When I worked on a system that could kill people if it malfunctioned, in our risk assessments we had to assume 100% chance of software failure. Practically this generally meant that software mitigation alone was not enough. I found it strange that the FPGA component of our system was considered much more trusted. Did hardware have some fundamental property that made it "better"?

Once again, I don't think there is a fundamental difference here. After all, software exists that has been formally verified. In general, functional programming lends itself better to this due to the separation of state and behaviour. It seems more likely that the difference is in the careful management of state. The properties of digital hardware described above encourage this, but it's not impossible to do in software.

The huge teams of verification engineers that work on silicon design might also suggest some fundamental difference, given you might not have seen the same applied to software. However, there are software projects that are given this level of rigour! Most famously, much of NASA's software, like software for space shuttles⁹. The sad truth is that most companies don't consider it worth it to apply this rigour to their software (it's hugely expensive!). When sufficient lives and/or money are on the line, software can and is written and tested with the same level of rigour as a lot of hardware..

If you have thoughts to share on what you think the differences and commonalities between hardware and software design are, please share them via email or in Hacker News comments if you have come from there. It's been really interesting to ponder, and I'd be interested in different perspectives.

Hacker News comment, 2021 ↩
https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf ↩
Just a note: the word "register" is pretty overloaded. You may have heard it in the context used above (the small storage accessed directly by the CPU); for memory-mapped IO in a microcontroller; you may have also heard "register" used as a verb to describe saving state in hardware. ↩
I think generally "branch" is used to describe conditional instructions, whereas "jump" is used to describe unconditional instructions. Certainly this is the case in RISC-V, but I think it very much depends on the particular architecture, and sometimes they are used interchangeably. ↩
Least Significant Bit ↩
wording from https://docs.rust-embedded.org/book/concurrency/ ↩
Of course in analogue reality things are not happening at exactly the same time, but our abstraction is the discrete time period of our clock. ↩
functional programmers, we don't need your smugness here! ↩
https://www.fastcompany.com/28121/they-write-right-stuff ↩

Designing a RISC-V CPU, Part 1: Learning hardware design as a software engineer

2021-02-16T00:00:00+00:00

I have no experience in digital logic design. That is, I didn't until I recently decided that I would like to try designing my own CPU and running it on an FPGA! If you too are a software engineer with a vague interest in hardware design, I hope this series of posts about what I've learnt will be helpful and interesting. In this first installment, I hope to answer these questions:

What is digital logic design?
How do I get started, and what tools might I use?

In future installments, I will go into more detail about my CPU design and the RISC-V architecture, as well as hopefully answering these questions:

What about digital logic design is fundamentally different from software design?
What about digital logic design is similar to software design?

You can see the code for my CPU at the time of writing here or an up to date version here.

What is digital logic design?

Digital logic design is designing logic circuits that operate on binary values. The elementary components are logic gates: an AND gate, for example, has two inputs and one output. The output is 1 iff¹ both inputs are 1.

Typically, we design synchronous circuits which use flip-flops to store state, and thereby synchronise the operation of the circuit to a common clock. Flip-flops are composed of logic gates.

Analogue circuit design is concerned with the electronic components that make up logic gates, like transistors and diodes. This level of abstraction is often needed for applications dealing directly with signals derived from analogue sensors, like radio receivers. When designing a CPU, this level of abstraction would not be feasible: modern CPUs can have billions of transistors!

Instead, we use tools that can translate our digital logic design into different useful formats: the configuration of an FPGA (see below); a simulation; silicon layout.

What is an FPGA and why are they used?

We noted above that the same digital logic design tools can be used whether we are creating a custom ASIC to be made into silicon, or configuring an FPGA. A Field-Programmable Gate Array is an integrated circuit containing an array of programmable logic blocks. You could imagine it is as a big array of logic gates that can be connected together in various ways.

Making a custom chip generally costs millions, and of course once your chip is manufactured it cannot be changed. Thus, generally FPGAs are used when:

You cannot afford to create a custom ASIC due to lack of capital (e.g. if you're just some hacker like me and not ARM or Intel)
You cannot afford to create a custom ASIC because your volume is too low to make it worth the high one-off costs (e.g. if you are making a small quantity of MRI machines with custom data acquisition hardware)
You need the flexibility

The downsides? FPGAs have a much higher per-chip cost, and they are generally much slower as a consequence of being able to connect logic blocks together in very flexible ways. In contrast, a custom design can be reduced to the minimum number of transistors, with no concern for flexibility.

I think it's helpful context to compare the custom ASIC design process against that of an FPGA design:

Logic design: just like we'd do for an FPGA, the logic design of an ASIC is done in a hardware description language.
Verification: FPGA designs may well be verified, but you might expect the process for an ASIC design to be more rigorous – after all, the design can't be changed once manufactured! Often verification will involve formally verifying² parts of the design.
Synthesis: This creates a netlist: a list of logic blocks and their connections. The connections are called nets, and the blocks are called cells. For both FPGAs and ASICs, the cells are vendor-specific.
Placement and routing (P&R): for an FPGA, this involves mapping the logic blocks described in the netlist to actual blocks in the FPGA. The resulting binary is often called a bitstream. For an ASIC, this involves deciding where to place the cells on the silicon, and how to connect them up. Both applications generally use automated optimisation tools for this.

What tools do I need?

A hardware description language: I am using nMigen³

You may have heard of Verilog or VHDL: both popular hardware description languages (HDLs). I use "popular" here to mean widely used, not widely loved.

I won't pretend to know much about these tools: I only know that smarter people than me with vast logic design experience have a lot of hate for them. Due to the problems with Verilog and other similar tools, there have been various attempts at making more useful and friendlier alternatives. nMigen is one such project, which creates a domain-specific language in Python. In their own words:

Despite being faster than schematics entry, hardware design with Verilog and VHDL remains tedious and inefficient for several reasons. The event-driven model introduces issues and manual coding that are unnecessary for synchronous circuits, which represent the lion's share of today's logic designs. Counterintuitive arithmetic rules result in steeper learning curves and provide a fertile ground for subtle bugs in designs. Finally, support for procedural generation of logic (metaprogramming) through "generate" statements is very limited and restricts the ways code can be made generic, reused and organized.

To address those issues, we have developed the nMigen FHDL, a library that replaces the event-driven paradigm with the notions of combinatorial and synchronous statements, has arithmetic rules that make integers always behave like mathematical integers, and most importantly allows the design's logic to be constructed by a Python program. This last point enables hardware designers to take advantage of the richness of the Python language—object oriented programming, function parameters, generators, operator overloading, libraries, etc.—to build well organized, reusable and elegant designs.

If, like me, you've never used Verilog, then not all of this will have more than abstract meaning to you. But it certainly sounds promising, and I can attest that it has been very straightforward to get started with logic design without the reportedly large barrier of grappling with Verilog. I would recommend it, particularly if you are already familiar with Python!

The only downside I can think of is that nMigen is still in development, and in particular the documentation is not complete. There is a helpful community at #nmigen on chat.freenode.net.

A wave viewer for inspecting simulations: I am using GTKWave

nMigen provides simulation tooling: I use it in my tests, written using pytest. I record the signals during these tests and view them in a wave viewer to help debug.

Optional: An FPGA dev board. I am using a myStorm BlackIce II

You don't need an FPGA dev board to create your own CPU. You could do everything in simulation! The fun of having a board to work with, for me, is being able to flash LEDs and see my design in action.

Of course, if you were creating something more useful than my very basic CPU, then you would probably want some hardware to run it on, and this would be less "optional"!

Getting started with nMigen

Rather than immediately trying to design a CPU, I started by making an Arithmetic Logic Unit (ALU) in nMigen. The ALU is a key piece of any CPU design that I have seen: it performs arithmetic operations.

Why start with this? I knew I would need an ALU for my CPU; I knew I could make a simple one; I knew that the feeling of making something is an important motivator when starting a new project!

My design looked something like this:

 1 """Arithmetic Logic Unit"""
 2 import enum
 3 
 4 import nmigen as nm
 5 
 6 
 7 class ALUOp(enum.IntEnum):
 8     """Operations for the ALU"""
 9     ADD = 0
10     SUB = 1
11 
12 
13 class ALU(nm.Elaboratable):
14     """
15     Arithmetic Logic Unit
16 
17     * op (in): the opcode
18     * a (in): the first operand
19     * b (in): the second operand
20 
21     * o (out): the output
22     """
23 
24     def __init__(self, width):
25         """
26         Initialiser
27 
28         Args:
29             width (int): data width
30         """
31         self.op = nm.Signal()
32         self.a = nm.Signal(width)
33         self.b = nm.Signal(width)
34         self.o = nm.Signal(width)
35 
36     def elaborate(self, _):
37         m = nm.Module()
38 
39         with m.Switch(self.op):
40             with m.Case(ALUOp.ADD):
41                 m.d.comb += self.o.eq(self.a + self.b)
42             with m.Case(ALUOp.SUB):
43                 m.d.comb += self.o.eq(self.a - self.b)
44         return m

As you can see, we've created a lot of nMigen Signal instances to represent well...the signals that define the interface to our ALU! But what is this elaborate method? My understanding is that "elaboration" is the name for the first step in synthesising the netlist (see above). The idea in the nMigen code above is that we've created some elaboratable structure (by inheriting from nm.Elaboratable), i.e. something that describes digital logic we want to synthesise. The elaborate method describes that digital logic. It has to return an nMigen Module.

Let's have a closer look at the contents of the elaborate method. The Switch will create some kind of decision logic in the synthesised design. But what is m.d.comb? nMigen has the concept of synchronous (m.d.sync) and combinatorial⁴ (m.d.comb) control domains. From the nMigen docs:

A control domain is a named group of signals that change their value in identical conditions.

All designs have a single predefined combinatorial domain, containing all signals that change immediately when any value used to compute them changes. The name comb is reserved for the combinatorial domain.

A design can also have any amount of user-defined synchronous domains, also called clock domains, containing signals that change when a specific edge occurs on the domain’s clock signal or, for domains with asynchronous reset, on the domain’s reset signal. Most modules only use a single synchronous domain[...]

The behavior of assignments differs for signals in combinatorial and synchronous domains. Collectively, signals in synchronous domains contain the state of a design, whereas signals in the combinatorial domain cannot form feedback loops or hold state.

Let's think about a shift register as an example piece of logic that we wish to design. Let's say our shift register has 8 bits, and every clock cycle the bit values are shifted one bit along (with the left-most value coming from an input signal). This is necessarily synchronous: you couldn't create this functionality by simply wiring the bits together, which in nMigen is what assigning them in the combinatorial domain would represent.

In the next installment of this blog series, I'll have more detail on my CPU design. As it stands at the moment, I'm trying to retire one instruction per cycle with no pipelining – this is unusual, but my hope was that it would make various aspects of the CPU simpler. A consequence of this is that much of my logic is combinatorial, rather than synchronous, as I have very little state to maintain between clock cycles. At the moment, something is wrong with my register file design, and there's a chance I'll have to reassess my "no pipelining" idea in order to fix it.

Writing tests

I like using pytest for Python tests, but you can of course use whatever framework appeals to you. Here are my tests for the ALU code above:

 1 """ALU tests"""
 2 import nmigen.sim
 3 import pytest
 4 
 5 from riscy_boi import alu
 6 
 7 
 8 @pytest.mark.parametrize(
 9         "op, a, b, o", [
10             (alu.ALUOp.ADD, 1, 1, 2),
11             (alu.ALUOp.ADD, 1, 2, 3),
12             (alu.ALUOp.ADD, 2, 1, 3),
13             (alu.ALUOp.ADD, 258, 203, 461),
14             (alu.ALUOp.ADD, 5, 0, 5),
15             (alu.ALUOp.ADD, 0, 5, 5),
16             (alu.ALUOp.ADD, 2**32 - 1, 1, 0),
17             (alu.ALUOp.SUB, 1, 1, 0),
18             (alu.ALUOp.SUB, 4942, 0, 4942),
19             (alu.ALUOp.SUB, 1, 2, 2**32 - 1)])
20 def test_alu(comb_sim, op, a, b, o):
21     alu_inst = alu.ALU(32)
22 
23     def testbench():
24         yield alu_inst.op.eq(op)
25         yield alu_inst.a.eq(a)
26         yield alu_inst.b.eq(b)
27         yield nmigen.sim.Settle()
28         assert (yield alu_inst.o) == o
29 
30     comb_sim(alu_inst, testbench)

and my conftest.py:

 1 """Test configuration"""
 2 import os
 3 import shutil
 4 
 5 import nmigen.sim
 6 import pytest
 7 
 8 
 9 VCD_TOP_DIR = os.path.join(
10         os.path.dirname(os.path.realpath(__file__)),
11         "tests",
12         "vcd")
13 
14 
15 def vcd_path(node):
16     directory = os.path.join(VCD_TOP_DIR, node.fspath.basename.split(".")[0])
17     os.makedirs(directory, exist_ok=True)
18     return os.path.join(directory, node.name + ".vcd")
19 
20 
21 @pytest.fixture(scope="session", autouse=True)
22 def clear_vcd_directory():
23     shutil.rmtree(VCD_TOP_DIR, ignore_errors=True)
24 
25 
26 @pytest.fixture
27 def comb_sim(request):
28 
29     def run(fragment, process):
30         sim = nmigen.sim.Simulator(fragment)
31         sim.add_process(process)
32         with sim.write_vcd(vcd_path(request.node)):
33             sim.run_until(100e-6)
34 
35     return run
36 
37 
38 @pytest.fixture
39 def sync_sim(request):
40 
41     def run(fragment, process):
42         sim = nmigen.sim.Simulator(fragment)
43         sim.add_sync_process(process)
44         sim.add_clock(1 / 10e6)
45         with sim.write_vcd(vcd_path(request.node)):
46             sim.run()
47 
48     return run

Every test generates a vcd file for me to view in a wave viewer, like GTKWave, for debugging purposes. You'll notice that the combinatorial simulation fixture runs for an arbitrary small time period, whereas the synchronous simulation feature runs for a defined number of clock cycles.

Yielding a signal in the test function requests its current value from the simulator. For combinatorial logic, we yield nmigen.sim.Settle() to ask the simulation to complete.

For synchronous logic, you can also yield without an argument to start a new clock cycle.

Designing a CPU

Once I'd gotten familiar with nMigen, I started trying to draw a block diagram for my CPU. I will go into much more detail on this on the next installment of this blog series, but I will briefly say that I started by drawing out the logic required for one instruction, then drew out the logic for another instruction, then figured out how to combine them. Here's the first messy sketch:

This block diagram step was extremely valuable in figuring out what the interfaces of different components needed to be, but I wouldn't have wanted to do it before playing around in nMigen first and learning a bit about digital logic design in the process. The jazzed up block diagram currently looks like this:

Stay tuned for the next installment where I actually delve into RISC-V and CPU design. I expect there to be a third installment of me reworking my design and getting it working on the entire instruction set (RV32I) that I am implementing :)

"if and only if" ↩
If you're a software engineer who has worked on high assurance software, such as that for a high risk medical device, you might think "formal verification" refers to any formalised verification process. Here I use formal verification to refer to mathematically proving correctness, see https://en.wikipedia.org/wiki/Formal_verification ↩
Note that you want the nmigen project under the nmigen organisation on GitHub. You do not want the one under the m-labs organisation. The situation is a bit unfortunate and complicated, but just know that the former is only one under active development. It's possible that the active project might change name soon – I'll do my best to update this blog post should that happen. ↩
also known as combinational ↩

Emulating an STM32F4 in QEMU to test ARM assembly

2020-04-04T00:00:00+01:00

I recently published a blog post titled How to flash an LED about writing ARM assembly for an STM32. I was running my code on a 1bitsy development board, but I wanted anyone to be able to have a go at writing the assembly and testing it – even if they didn't have the right hardware. You can find the repo on my Github.

Finding the specific QEMU tools I needed took a while, so I wanted to document it in this blog post.

The quest for a QEMU STM32F4 machine

QEMU is a "generic and open source machine emulator and virtualizer". An example where emulation is useful: if you are writing software for an embedded target, reliable automated tests can be a challenge. Emulating your embedded target on your host computer makes allows for easier testing, and for isolating problems to do with the real hardware from problems to do with the software.

The 1bitsy has a STM32F415 microcontroller, so I was looking for emulation for a development board with a similar MCU. QEMU comes with a set of built-in machines, and you can write your own machines to emulate the hardware you desire.

Unfortunately, none of the built-in machines suited my purposes. There were multiple Cortex M3 machines, but none of them were STM32s, and there were no Cortex M4 machines. I wanted to use an STM32F4 so as to avoid confusion for people going from my assembly blog post to the emulation. I also gave the blog post as a talk at work, and didn't want my coworkers to be confused by the inconsistency. Creating my own QEMU machine was not remotely feasible on the timescales I was working on for my work talk, and I believe it is a lot of work! So, I searched the internet for an available STM32F4 QEMU machine.

Enter GNU MCU Eclipse...maybe

During this search, I came across many mentions of GNU MCU Eclipse, a suite of tools for the Eclipse IDE which included an STM32F4 Discovery board.

I am a vim die-hard with no desire to use Eclipse, so I was hopeful to find a way to be able to extract these tools and easily use them outside of Eclipse.

It turns out the fork of QEMU that this toolsuite is using is available separately as xPack QEMU ARM.

xPack QEMU ARM has an STM32F4 Discovery machine

xPack recommend using xpm to install their QEMU ARM fork, but I found the manual installation instructions worked fine on Ubuntu. This gives us, among other things, the qemu-system-gnuarmeclipse binary.

Connecting to the emulator via gdb

We can run our target executable on the emulator like this, with the gdb switch telling QEMU to wait for a connection from gdb before continuing the program's execution. Here, we tell it listen on TCP port 3333.

1 qemu-system-gnuarmeclipse \
2     -cpu cortex-m4 \
3     -machine STM32F4-Discovery \
4     -gdb tcp::3333 \
5     -nographic \
6     -kernel "${TARGET}"

Then we can connect from gdb:

1 gdb-multiarch \
2     -q "${TARGET}" \
3     -ex "target remote :3333"

Automated testing of ARM assembly on the STM32F4 emulator

I put all this together into a bash script so I could test that assembly for toggling a GPIO pin was doing what it should, by reading register values from gdb at breakpoints set in the assembly file:

 1 #!/usr/bin/env bash
 2 set -euo pipefail
 3 TARGET=$1
 4 
 5 qemu-system-gnuarmeclipse \
 6     -cpu cortex-m4 \
 7     -machine STM32F4-Discovery \
 8     -gdb tcp::3333 \
 9     -nographic \
10     -kernel "${TARGET}" > /dev/null &
11 QEMU_PID=$!
12 
13 if [ ! -d "/proc/${QEMU_PID}" ]
14 then
15     echo -ne "\033[31m Failed to start QEMU"
16     echo -e "\033[0m"
17     exit 1
18 fi
19 
20 function read_address() {
21     local ADDRESS=$1
22     VALUE=$(gdb-multiarch \
23         -q "${TARGET}" \
24         -ex "target remote :3333" \
25         -ex "x/1xw ${ADDRESS}" \
26         --batch | tail -1 | cut -f 2)
27 }
28 
29 function test_address() {
30     local ADDRESS=$1
31     local REGISTER_NAME=$2
32     local EX_VALUE=$3
33 
34     read_address "${ADDRESS}"
35     if [ "$VALUE" = "${EX_VALUE}" ]
36     then
37         echo -ne "\033[32m✓ ${REGISTER_NAME} correctly set to ${EX_VALUE}"
38     else
39         echo -ne "\033[31m✘ ${REGISTER_NAME} was ${VALUE}, want ${EX_VALUE}"
40     fi
41 
42     echo -e "\033[0m"
43 }
44 
45 test_address "0x40023830" "AHB1ENR" "0x00000001"
46 test_address "0x40020000" "GPIOA_MODER" "0xa8010000"
47 test_address "0x40020014" "GPIOA_ODR" "0x00000100"
48 
49 kill ${QEMU_PID} &> /dev/null

The output looks like this for correct assembly, which you can view here.

This testing is limited, but I'm pleased with it! I put everything in a Dockerfile in the Github repo to make life easier for people trying this out.

Bonus 1337 screenshot

This is a screenshot from when I finally got all this working after a couple evenings of trials:

Clockwise from left is the assembly, the bash script, a gdb session where I'd been poking around, and me running the bash script.

I hope this is post helpful to anyone wanting to emulate an STM32F4 without having to do it all themselves, and that the tools in my GPIO toggling exercise are useful to anyone who wants to play with ARM assembly but doesn't have the hardware.

How to flash an LED

2020-03-27T00:00:00+00:00

Today we are going to be learning how to flash an LED on a microcontroller by writing ARM assembly.

If you write software but are unfamiliar with basic electronics or embedded software development, there will be explanations of some fundamentals – I expect you will not feel left behind :).

If you'd like to skip the fundamentals and go straight to the assembly writing, click here.

We'll be using a 1bitsy, which is an STM32 development board. We'll be reading the STM32 reference manual to figure out what assembly to write. If you want to try out the coding yourself, but don't have a 1bitsy or anything similar, check out this Github repo where you can run the code on an emulator in a Docker container.

Some basics

Let's get some basics out of the way. How do you flash an LED?

Hardware

As you may know, an LED is a "light-emitting diode". LEDs are increasingly popular in torches, bulbs and various other lighting due to their ability to be very bright with relatively low power. What we need to know is that they emit light when current passes through them. So: we need some current.

This is just a simple electronics circuit with current flowing through the LED. We have low voltage at the bottom, and higher voltage at the top: that difference causes current to flow, lighting up our LED. But this is no good for us – we want to control the flow of current so that we can flash our LED on and off.

In order to control the current in our LED, we can connect it to a GPIO pin on our microcontroller:

GPIO just stands for "general purpose input/output". It's a pin on a microchip that you can configure at runtime: for example, you can say "I want this pin to be an output, and I want to turn it on", or "I want this pin to be an input" and then read data from it.

A microcontroller is a small computer used for embedded software – we'll learn more about the specific microcontroller we're using later. Embedded software is software that isn't written for a general purpose computer, but instead targets specific hardware used in some physical device: for example, the software that runs on an MRI scanner to control its operation, or the software in modern cars that controls things like the anti-lock braking system.

Software

If GPIO pins are configurable at runtime, then we need to write some code that will tell our little computer how to configure the GPIO. This is how that would usually look:

Usually, you'd expect that code to be written in C. You need a language that allows you control over memory the way that C does: when you have small limited memory, as is generally the case on small embedded computers, it's important to be able to understand how much memory is being used by your program. Languages that rely on dynamic allocation and garbage collection are a bad fit, partly for this reason.

Rust and C++ are also used for embedded work. The C++ you'd write for embedded would be quite different from what you might write for a desktop application – you likely wouldn't use any of the STL containers as they all rely on dynamic memory allocation. Eliminating dynamic memory allocation is safer: the risk of memory allocation failing is much higher when there isn't much memory to begin with. And a failure could be much more catastrophic: many embedded systems are designed to run autonomously, without any human there to restart them. Many control safety-critical physical systems.

Dynamic allocation is generally not needed anyway: a desktop application might have to dynamically allocate resources to accommodate a user opening an unknown number of tabs in a GUI; an embedded application will know at compile time how many motors it has to control, or how many sensors it will read from. This allows a lot of memory to be allocated statically.

So, for the sake of example let's say that you would write your code to flash an LED in C. You'd probably use a hardware abstraction library (aka a HAL) to abstract over memory addresses and such. This makes the code more portable as well as more readable.

But today, we're going to do stuff a little differently from how you might normally: we'll be writing all our code in assembly.

What is assembly?

When you compile a C program, say, you compile it to machine code. Machine code is the lowest level of software – it's the binary code that the CPU executes. This machine code consists of instructions. For example, you might have one instruction that says "copy value 42 into register 0", and that is our smallest unit of executable code.

Assembly is the next level of software up – it's a lot like writing human readable machine code, where you write out each instruction in text form. This is very different to writing a C program which is much further abstracted, which means compiling C to machine code is a lot more complicated. When we write assembly today, that's exactly what our CPU is going to be executing: there's a very close mapping to the actual machine code.

Why write our code in assembly?

The usual reasons: for fun and learning! Writing code in assembly means really getting to know your target hardware. Plus, we'll know exactly what code is running on our processor.

Although this isn't something you might usually do, understanding assembly code is a big part of many developers' jobs: reading the assembly is often the only way to debug optimised code, and it's crucial to reverse engineering and exploit development. It's also key to compiler development, and used for making specific optimisations to embedded code. It's often the only way to access specialised CPU features, and to run special instructions like DSP instructions.

Getting to know our hardware

Doing embedded development means really getting to know your target hardware. So, what hardware are we using?

We have an ARM development board called a 1bitsy. It has an STM32F4 on it, which is our microcontroller unit, or MCU. This microcontroller is basically the CPU plus about a megabyte of flash and 200 kilobytes of RAM, and what are called peripherals: some of these are for communicating via various protocols, and some are for general purposes usage, like the GPIOs we talked about earlier. The MCU has everything you need to make the CPU actually be a useful computer. Our STM32 contains a Cortex M4 CPU – the picture above is of the die of the STM32, it's basically what's inside the black plastic on the outside of the chip. The CPU is on the top right of the die, with RAM top left, flash bottom left, and peripherals bottom right.

I've included lists of the documentation associated with these. Today we're exclusively going to be looking at the schematic for the board and the reference manual for the STM32.

To program the 1bitsy, we will also need a prorgrammer board like the Black Magic probe.

A brief introduction to assembly

What does assembly look like?

Before we get onto writing some code, what does ARM assembly look like?

Here is an example instruction: mov r0, #5. This means move the literal value 5 into register 0. But what's a register? A register is the last key concept we're going to need to know before we write any assembly.

Our ARM processor has a small number of very fast, very small storage locations, and they're called registers. These are directly accessed by the CPU, and they aren't accessible via main memory. Some are used for general purpose storage, others have specific purposes, like the program counter register (PC). The CPU is hardwired to execute whatever instruction is at the memory location stored in the PC. The stack pointer is used to keep track of the call stack.

On a separate memory bus, our STM32 also has about a thousand configuration and status registers – also often called memory-mapped IO. These are basically pre-defined structs that live somewhere in memory, and you read & write to them in order to configure the hardware. In our case, we'll be writing to these to configure a GPIO, which will be connected to our LED.

RISC vs CISC

I think it's important context to note that the assembly we'll be writing today is a little different than what you would likely write for your PC. Broadly, you can divide computer architectures into complex instruction set computers (CISC) and reduced instruction set computers (RISC). CISC is what Intel chips use, and it is optimised to perform actions in as few instructions as possible – as a consequence each instruction itself can be very complex. RISC, on the other hand, prioritises having simple instructions, and you'll be glad to know that's what we'll be writing today.

I couldn't resist including a screenshot from Hackers, my favourite movie, which is from 1995, a much more hopeful time in software.

Here the hacker Acid Burn is saying that RISC architecture is going to change everything – and in many ways she's right! I don't know of any mobile phone, Apple or Android, that doesn't use an ARM core, and mobile phones are everywhere. Sadly, most laptops and desktops use Intel CISC processors. This makes no difference to my life at all, but I like to pretend it matters to me so I can feel like I'm as cool as Acid Burn.

Let's write some code!

At last...it is time to get down to business. First we need to briefly look at the schematic for the 1bitsy, our development board. The schematic tells us what is on the board, and how it is connected. We're interested in how the status LED is connected.

Because the 1bitsy is quite simple, there is only one page to the schematic. If we look at the top of the schematic, centre-right, we can see that there's a status LED connected to GPIO port A, pin 8, which we'll call PA8 for short.

There are three things we're going to need to do:

Turn on the GPIOA clock
Set GPIOA8 to an output
Toggle GPIOA8

Turning on the clock

Before we can do anything with this GPIO pin, we need to set up its clock. Inside our chip, and inside the CPUs in our work laptops, there's a oscillator providing a clock signal that is used to synchronise different parts of the complicated integrated circuit that is our computer.

If we are going to use our GPIO pin, it needs to have its clock enabled, otherwise it is effectively off, and won't respond to any reads or writes. It defaults to being off because the peripheral consumes power when it's on.

To find out how to setup the GPIOA clock, we need to look at the STM32F415 reference manual, or ref man for short. We want to look at the memory map, to see what the start address is for the Reset and Clock Control (RCC) registers.

We're going to need a bit more information in order to set the clock, but this memory address is something we'll need in our code, so let's make a note of it (0x40023800).

Let's go to the RCC register map next – this is how we're going to find exactly which RCC register we need to write to in order to turn on the GPIOA clock.

The first column in this table shows the address offset from the base address we noted earlier. The numbers from 31 to 0 show the bits of the 32-bit registers.

If we look closely, we can see the field GPIOA_ENR for enabling GPIOA's clock – so, we want to set bit 0 in the AHB1ENR register. I realise that might seem very obscure; I think there are two things to note: firstly, there's actually a lot of additional documentation about this elsewhere in the ref man, showing the different memory buses and the clock tree. It would be too dense to show in this blog post.

Secondly, when you create a software API, a huge priority is making something that is useable and clear to developers (I should hope it is, anyway). When designing hardware, there are physical constraints, and the design has to be cheap and simple to mass manufacture. Consequently, clarity for us chumps cannot be a priority, and instead of a method call with helpfully named arguments, we have dense manuals like this...

Reading this sort of documentation does get easier the more you get to know your architecture, and the more experience you have reading similar manuals – as with anything :)

Actually writing code for real

Now: we're finally going to write some actual code. I am sorry I said "let's write some code" further up. We couldn't do it until we had this information from the ref man!

Let's copy that RCC base address into register 0. Our registers are all 32 bits wide, but we can only copy 16 bits at a time, otherwise we'd have no room for the rest of our instruction. So, we copy 0x00003800 into the register using the mov instruction, and then copy 0x4002 into the top half, hence the t in movt below.

Then, we want to set the 0th bit in the AHB1ENR register. First, let's copy 0x01 into r1. Then, let's store the contents of r1 in the memory address contained in r0, offset by 0x30 using the str instruction.

1     @ Store RCC base address in r0
2     movw r0, #0x3800
3     movt r0, #0x4002
4 
5     @ Turn on GPIOA clock by setting bit 0 in AHB1ENR register
6     movw r1, #0x01
7     str  r1, [r0, #0x30]

With these runes, we can enable the clock!

All the mov instructions are about moving data into registers. The str instruction moves data from registers and into memory.

You can read more detail about these instructions in the User Guide for our CPU.

Setting GPIOA8 to an output

Next on our list is configuring GPIOA8 to be an output. As before, we can look up the base address of GPIOA registers in the ref man. It's 0x40020000. Then, we can have a read of the GPIO registers to find out which one we need to write to.

It looks like we want GPIOA_MODER, and you can see above that the reset value is 0xA8000000 for GPIOA. I understand this is because some of the GPIOA pins are used for the debug interface of the STM32, otherwise the reset value would be all zeroes. We want to change the two-bit field MODER8 to be 01, so we want to set the register value to 0xA8010000. There is no offset this time as the mode register is the first GPIO register.

1     @ Store start address of GPIOA registers
2     movw r0, #0x0000
3     movt r0, #0x4002
4 
5     @ Use GPIOA_MODER to make GPIOA8 an output
6     movw r1, #0x0000
7     movt r1, #0xA801
8     str  r1, [r0]

Toggling the GPIO

If we look at the GPIO documentation, it tells us that there is an output data register, but access to it isn't atomic. That's not a big problem for us here as we don't have any concurrency, but maybe we will later on! We can use the bit-set-reset register for atomic access instead. This also allows us to set individual bits in the output data register, instead of overwriting any values on other GPIO pins.

The direction our LED has been wired up means it's active low, so it will turn on when the GPIO output is cleared, and off when it is set.

So, to turn on our LED we want to set the BR8 field, and to turn it off, we want to set the BS8 field.

1     @ Set BR8 field in GPIOA_BSRR, to clear GPIOA8
2     movw r1, #0x0000
3     movt r1, #0x0100
4     str  r1, [r0, #0x18]
5 
6     @ Set BS8 field in GPIOA_BSRR, to set GPIOA8
7     movw r1, #0x0100
8     str  r1, [r0, #0x18]

Looping

The last code snippet will just turn the LED off and on once. To create an infinite loop instead, we simply create a label (let's call it .loop) and then use the branch instruction to go back to that label!

 1 .loop:
 2     @ Set BR8 field in GPIOA_BSRR, to clear GPIOA8
 3     movw r1, #0x0000
 4     movt r1, #0x0100
 5     str  r1, [r0, #0x18]
 6 
 7     @ Set BS8 field in GPIOA_BSRR, to set GPIOA8
 8     movw r1, #0x0100
 9     str  r1, [r0, #0x18]
10 
11     b .loop

Adding a delay

Now for something that is hopefully a lot more interesting than just shoving values into memory addresses. We want to do this in a loop, with a delay between turning the LED off an on!

There are a few ways you could do this delay. If precise timing was important, the timer peripherals of the STM32 can be used. We could also just add a lot of nop (no operation) over and over again -- that doesn't feel very sophisticated, and would give us a really large binary!

We're going to do this by putting a big number in a register and decrementing it until it hits zero. So, we're creating another loop, but this time with an exit condition.

 1 .loop:
 2     @ Set BR8 field in GPIOA_BSRR, to clear GPIOA8
 3     movw r1, #0x0000
 4     movt r1, #0x0100
 5     str  r1, [r0, #0x18]
 6 
 7     @ Delay
 8     movw r2, #0x3500
 9     movt r2, #0x000c
10 .L1:
11     subs r2, #0x0001
12     bne .L1
13 
14     @ Set BS8 field in GPIOA_BSRR, to set GPIOA8
15     movw r1, #0x0100
16     str  r1, [r0, #0x18]
17 
18     @ Delay
19     movw r2, #0x3500
20     movt r2, #0x000c
21 .L2:
22     subs r2, #0x0001
23     bne .L2
24 
25     b .loop

The subs instruction here is subtracting, and the s suffix means that a flag will be set in the Program Status Register if the result of the operation is zero. The bne instruction means "branch if not equal (to zero)", so we'll jump back to the start of our delay loop if that zero flag isn't set.

Putting the pieces together

We now have everything we need to flash our LED – almost.

There's some boilerplate that needs added to our assembly file. We need to give our a name to the entry point, let's call it main.

There are two instruction encodings for ARM: ARM and Thumb. The encoding defines how the assembly is translated to machine code. It used to be that you needed different syntax for each of these, until ARM brought out their unified assembly language. Line 1 below is telling the assembler (the tool that turns the assembly into machine code) which syntax we are using.

Then, line 3 is telling the assembler that we are using the Thumb encoding for main, which is the only encoding our target (the STM32F4) supports. Then line 4 is exposing the symbol main to the linker.

1 .syntax unified
2 
3 .thumb_func
4 .global main
5 main:

Lastly, we need to make sure our program is what runs when our microcontroller powers on. The reset vector is the location the CPU will go to find the first instruction it will execute after being reset.

What we’re doing below is putting the address of main into the reset vector so that when our board turns on, it will go to that address and start running our code to flash the LED.

1 .section .vector_table.reset_vector
2 .word main

We now have our final asm file:

 1 .syntax unified
 2 
 3 .thumb_func
 4 .global main
 5 main:
 6     @ Store RCC base address in r0
 7     movw r0, #0x3800
 8     movt r0, #0x4002
 9 
10     @ Turn on GPIOA clock by setting bit 0 in AHB1ENR register
11     movw r1, #0x01
12     str  r1, [r0, #0x30]
13 
14     @ Store start address of GPIOA registers
15     movw r0, #0x0000
16     movt r0, #0x4002
17 
18     @ Use GPIOA_MODER to make GPIOA8 an output
19     movw r1, #0x0000
20     movt r1, #0xA801
21     str  r1, [r0]
22 
23 .loop:
24     @ Set BR8 field in GPIOA_BSRR, to clear GPIOA8
25     movw r1, #0x0000
26     movt r1, #0x0100
27     str  r1, [r0, #0x18]
28 
29     @ Delay
30     movw r2, #0x3500
31     movt r2, #0x000c
32 .L1:
33     subs r2, #0x0001
34     bne .L1
35 
36     @ Set BS8 field in GPIOA_BSRR, to set GPIOA8
37     movw r1, #0x0100
38     str  r1, [r0, #0x18]
39 
40     @ Delay
41     movw r2, #0x3500
42     movt r2, #0x000c
43 .L2:
44     subs r2, #0x0001
45     bne .L2
46 
47     b .loop
48 
49 .section .vector_table.reset_vector
50 .word main

Building our code and flashing our target

We use an assembler to turn our assembly into an object file, e.g.

arm-none-eabi-as -mcpu=cortex-m4 toggle.s -c -o output/toggle.o

Then we use a linker to make an executable. We need a custom linker script to tell the linker where RAM and flash start on our target. Here's what I used:

 1 ENTRY(main)
 2 
 3 MEMORY {
 4     FLASH   : ORIGIN = 0x08000000, LENGTH = 128K
 5     RAM     : ORIGIN = 0x20000000, LENGTH = 128K
 6 }
 7 
 8 SECTIONS {
 9     /\* Vector table is first thing in flash \*/
10     .vector_table ORIGIN(FLASH) :
11     {
12         /\* Initial stack pointer \*/
13         LONG(ORIGIN(RAM) + LENGTH(RAM));
14 
15         /\* Rest of vector table \*/
16         KEEP(\*(.vector_table));
17     } > FLASH
18 
19     /\* text section contains executable code \*/
20     .text ADDR(.vector_table) + SIZEOF(.vector_table) :
21     {
22         \*(.text .text.\*);
23     } > FLASH
24 }

Then we can call the linker: arm-none-eabi-ld -T link.ld output/toggle.o -o output/toggle

I'm using a Black Magic probe to flash my 1bitsy. I can talk to the probe over gdb:

gdb-multiarch -n --batch                    \
    -ex 'tar ext /dev/serial/by-id/example' \
    -ex 'mon tpwr en'                       \
    -ex 'mon swdp_scan'                     \
    -ex 'att 1'                             \
    -ex 'load'                              \
    -ex 'start'                             \
    -ex 'detach'                            \
    output/toggle

Voila:

Resources

You can check out my GPIO toggling exercise which talks you through the assembly here in a little more detail, and provides a Dockerfile for emulating the target chip. I'll have a (shorter) blog post about the emulation soon.
Azeria Labs have an excellent guide to ARM assembly that goes into more detail than I have, though assumes a bit more knowledge about computer architecture.
The Cortex M4 User Guide is a good technical reference for the assembly written here

Let's break CPython together, for fun and mischief

2019-10-13T00:00:00+01:00

I promise that nothing we do here will be useful.

But I promise it will be entertaining, and (hopefully) educational:

if you don't know anything about the CPython internals, you're about to learn (a bit)
if you do know about the CPython internals, you're hopefully about to learn some new ways to abuse them 😉

Clarification

Before we proceed to hackage, let me make sure it's clear what I'm talking about when I say "CPython internals". CPython is the reference implementation of Python, and it's what most people use. It's what comes as standard on any system I've ever used.

A Python implementation includes the interpreter, the built-in types and the standard library. With CPython, apart from much of the standard library which is in Python, this is all written in C. There are other implementations:

PyPy is written in Python itself and has a JIT compiler, it's really fast
Jython runs on the JVM
IronPython runs on .NET the Microsoft framework

Everything we do here is exploiting the specific implementation details of CPython.

YMMV

Please bear in mind that Python was not designed to do the things we're going to do, and some of the fun things that worked with the version of Python I used here, my operating system, &c., might end up segfaulting for you. Running stuff in ipython rather than the standard REPL will also likely end up with more issues occurring when things are hacked.

To whet your appetite

Let's have a look at the Python language reference. The first two sentences of the data model say this:

Objects are Python’s abstraction for data. All data in a Python program is represented by objects or by relations between objects.

In CPython a Python object is defined in the PyObject struct:

1 typedef struct _object {
2     _PyObject_HEAD_EXTRA
3     Py_ssize_t ob_refcnt;
4     struct _typeobject *ob_type;
5 } PyObject;

(The first bit here, _PyObject_HEAD_EXTRA, is only valid when compiling Python with a special tracing debugging feature, so don't worry about it.)

We have the reference count ob_refcnt, which is used for memory management and tells us how many other objects are referencing this one. When the reference count of an object is zero, its memory and resources can be freed by the garbage collector.

We also have the type information, ob_type, which tells us how to interact with the object, what its behaviour is, what data it contains.

Going back to the data model:

Every object has an identity, a type and a value. An object’s identity never changes once it has been created; you may think of it as the object’s address in memory. The ‘is’ operator compares the identity of two objects; the id() function returns an integer representing its identity.

CPython implementation detail: For CPython, id(x) is the memory address where x is stored.

So what I'd expect CPython to do is dynamically allocate memory for a new PyObject each time we create a new object.

Let's test this out with some integers:

1 >>> x = 500
2 >>> y = 500
3 >>> x is y
4 False

That makes sense: a new PyObject has been allocated for each variable we've made here, and so they are at different places in memory. But what if we use smaller integers?

1 >>> x = 5
2 >>> y = 5
3 >>> x is y
4 True

How surprising! Let's have a look in the CPython source to see why this might be:

 1 #ifndef NSMALLPOSINTS
 2 #define NSMALLPOSINTS           257
 3 #endif
 4 #ifndef NSMALLNEGINTS
 5 #define NSMALLNEGINTS           5
 6 #endif
 7 
 8 /* Small integers are preallocated in this array so that they
 9    can be shared.
10    The integers that are preallocated are those in the range
11    -NSMALLNEGINTS (inclusive) to NSMALLPOSINTS (not inclusive).
12 */
13 static PyLongObject small_ints[NSMALLNEGINTS + NSMALLPOSINTS];

So it seems integers between -5 and 256 inclusive are statically allocated in a big old array! This is an optimisation that CPython has chosen to do -- the idea is that these integers are going to be used a lot, and it would be time consuming to allocate new memory every time.

But...if that means some integers have a defined place in memory, can we...corrupt that memory?

import ctypes

Most good CPython shenanigans begins with importing ctypes, which is Python's standard C foreign function interface. An FFI allows different languages to interoperate. ctypes provides C compatible data types and allows calling functions from shared libraries and such.

The ctypes docs tell us about the function memmove:

ctypes.memmove(dst, src, count)

Same as the standard C memmove library function: copies count bytes from src to dst. dst and src must be integers or ctypes instances that can be converted to pointers.

So what if we copied the memory where 6 is to where 5 is?

1 >>> import ctypes
2 >>> import sys
3 >>> ctypes.memmove(id(5), id(6), sys.getsizeof(5))
4 >>> 5 + 5
5 12

What fun! But this is small fry stuff. We can do more. We have ambition.

Ambition

I don't what to change one integer. I want to change ALL the integers.

What if we changed what happens when you add integers together? What if we made it subtract instead?

The way operator resolution works in Python is that the corresponding "magic method" or "dunder method" (for double underscores) is called. For example x + y will become x.__add__(y). So the int.__add__ method is going to be our target for mischevious hackage.

1 def fake_add(x, y):
2     return x - y
3 >>> int.__add__ = fake_add
4 TypeError: can't set attributes of built-in/extension type 'int'

Annoying, but unsurprising. Python is permissive in the sense that it doesn't have access modifiers like C++ or Java – you can't really define private attributes of a class. But you can't do just anything, and patching built-ins like this is one of the things Python prevents us from doing – unless we try very hard.

So what can we try instead? All attribute resolution comes down to looking up attribute names in an object's dictionary. For example, x.y would resolve to x.__dict__["y"]¹. What if we try accessing int.__add__ that way?

1 >>> int.__dict__["__add__"] = fake_add
2 TypeError: 'mappingproxy' object does not support item assignment

Tarnation. But of course, we knew it would not be as easy as this. Perhaps lesser programmers would give up here. "It's not allowed," they might say. But we are strong and we are determined.

What is this mappingproxy the interpreter speaks of?

Read-only proxy of a mapping.

Ok, so this is just some cast over the actual dictionary. If we can cast it to a dictionary, we can assign to it. But doing this with a Python cast is just creating a copy:

1 >>> dict(int.__dict__)["__add__"] = fake_add
2 >>> 1 + 5
3 6
4 >>> (1).__add__(5)
5 6
6 >>> int.__add__ == fake_add
7 False

We need to go deeper. Let's look at the CPython source for the mappingproxy type.

 1 typedef struct {
 2     PyObject_HEAD
 3     PyObject *mapping;
 4 } mappingproxyobject;
 5 
 6 static PyMappingMethods mappingproxy_as_mapping = {
 7     (lenfunc)mappingproxy_len,                  /* mp_length */
 8     (binaryfunc)mappingproxy_getitem,           /* mp_subscript */
 9     0,                                          /* mp_ass_subscript */
10 };

The PyMappingMethods of a type tell us how it behaves as a mapping: what does x[key] do (mp_subscript)? What does x[key] = y do (mp_ass_subscript)?

What this is telling us is that the mapping proxy is basically a wrapper around a normal dictionary with the function pointer to the subscript assignment method set to NULL.

We can use ctypes to cast this and reveal the underlying dictionary.

 1 import ctypes
 2 
 3 
 4 class PyObject(ctypes.Structure):
 5     pass
 6 
 7 
 8 PyObject._fields_ = [
 9     ('ob_refcnt', ctypes.c_ssize_t)
10     ('ob_type', ctypes.POINTER(PyObject))
11 ]
12 
13 
14 class MappingProxy(PyObject):
15     _fields_ = [('dict', ctypes.POINTER(PyObject))]

The trouble is, once we have the dict as a PyObject pointer, how do we get it back to being a plain old Python dict? It's no good doing this:

1 >>> MappingProxy.from_address(id(int.__dict__)).dict
2 <LP_PyObject at 0x7f6e98c8e7b8>

if we have no way to interpret this as a dict. We can use this pleasing wee trick from the CPython API, courtesy of Armin Ronacher² which will put it as a value into another existing dictionary where it will be interpreted the same as any other object, then we can extract it!

 1 def pyobj_cast(obj):
 2     return ctypes.cast(id(obj), ctypes.POINTER(PyObject)
 3 
 4 
 5 def get_dict(proxy):
 6     dict_as_pyobj = MappingProxy.from_address(id(proxy)).dict
 7     fence = {}
 8     ctypes.pythonapi.PyDict_SetItem(
 9             pyobj_cast(fence),
10             pyobj_cast("victory"),
11             dict_as_pyobj)
12     return fence["victory"]
13 
14 int_dict = get_dict(int.__dict__)
15 int_dict["__add__"] = fake_add

Have we done it???

1 >>> 1 + 1
2 2

D'oh! But wait a minute...

1 >>> (1).__add__(1)
2 0

What! But the data model says:

to evaluate the expression x + y, where x is an instance of a class that has an __add__() method, x.__add__(y) is called

We've been lied to...this is clearly not true! It seems CPython has some shortcut in place.

To be fair, they probably didn't think we'd ever find out this "lie" by performing these shenanigans. We need to go yet deeper still to fulfill our pointless quest. We will have control of the builtins.

Full type mappings

Back to the CPython source. What is in this type information that's in the PyObject struct we looked at earlier? The answer: lots of stuff that I am not going to put here, but the most interesting parts for our purposes are the method suites:

1 typedef struct _typeobject {
2     ...
3     PyNumberMethods *tp_as_number;
4     PySequenceMethods *tp_as_sequence;
5     PyMappingMethods *tp_as_mapping;
6     ...
7 } PyTypeObject;

This struct contains other structs defining the behaviour of the type via function pointers. We're specifically interested in this tp_as_number member. Its first member, nb_add, is the function pointer to the add method. This is what we want to overwrite. This is our new target.

1 typedef struct {
2     binaryfunc nb_add;
3     binaryfunc nb_subtract;
4     binaryfunc nb_multiply;
5     ...
6 } PyNumberMethods;

So, like we made the ctypes mappings before, I want to do it for this entire PyTypeObject struct. Which is big...so I'm not putting it all here!

 1 import ctypes
 2 
 3 
 4 class PyObject(ctypes.Structure):
 5     pass
 6 
 7 
 8 class PyTypeObject(ctypes.Structure):
 9     pass
10 
11 
12 Py_ssize_t = ctypes.c_ssize_t
13 binaryfunc = ctypes.CFUNCTYPE(
14         ctypes.POINTER(PyObject),
15         ctypes.POINTER(PyObject),
16         ctypes.POINTER(PyObject))
17 
18 
19 class PyNumberMethods(ctypes.Structure):
20     _fields_ = [
21             ("nb_add", binaryfunc),
22             ("nb_subtract", binaryfunc),
23             ("nb_multiply", binaryfunc),
24             ...
25 
26 PyTypeObject._fields_ = [
27         ...
28         ("tp_as_number", ctypes.POINTER(PyNumberMethods)),
29         ...
30 
31 
32 PyObject._fields_ = [
33         ("ob_refcnt", Py_ssize_t),
34         ("ob_type", ctypes.POINTER(PyTypeObject))]

So here we've basically made a Python mapping of the structs we have in C. If we cast our Python int type to the equivalent type struct, we'll reveal the secrets usually hidden from us.

1 >>> PyLong_Type = ctypes.cast(id(int), ctypes.POINTER(PyTypeObject)).contents
2 >>> PyLong_Type.tp_as_number.contents.nb_add = PyLong_Type.tp_as_number.contents.nb_subtract
3 >>> 10 + 4
4 6
5 >>> 1 + 1
6 0
7 >>> 1 + 3
8 -2

We did it!!! Incredible.

But now we know how to patch built-ins...what if we went further? What if we added functionality that wasn't there before, rather than altering existing functionality?

Nice immutable string you got there. It would be a shame if something should...happen to it 😏

In Python, strings are immutable. You can't go in and change one of the characters – you have to create a new string object. When you add characters to an existing string variable, a new string object is created.³

What if we made strings mutable?

Let's have a look at PyUnicode_Type in the CPython source...and then swiftly look away from all 16k lines of it cos it's distressingly complex as it has to handle unicode and all its complexities as well as ASCII: good times. We want to find the tp_as_mapping member of the PyUnicode_Type struct:

1 static PyMappingMethods unicode_as_mapping = {
2     (lenfunc)unicode_length,        /* mp_length */
3     (binaryfunc)unicode_subscript,  /* mp_subscript */
4     (objobjargproc)0,               /* mp_ass_subscript */
5 };

We want to create a new function to point to from the mp_ass_subscript member. Here's my extremely hacked one which wouldn't handle every case, not at all. But I think it's going to allow us to do what we want.

 1 static int
 2 unicode_ass_subscript(PyUnicodeObject* self, PyObject* item, PyObject* value)
 3 {
 4     Py_ssize_t i = ((PyLongObject*)(item))->ob_digit[0];
 5     unsigned int kind = ((PyASCIIObject*)(self))->state.kind;
 6     char* data = ((char*)((PyASCIIObject*)(self) + 1));
 7     char* new_data = ((char*)((PyASCIIObject*)(value) + 1));
 8     *(data + kind * i) = *new_data;
 9     return 0;
10 }
11 
12 static PyMappingMethods unicode_as_mapping = {
13     (lenfunc)unicode_length,                 /* mp_length */
14     (binaryfunc)unicode_subscript,           /* mp_subscript */
15     (objobjargproc)unicode_ass_subscript,    /* mp_ass_subscript */
16 };

I don't want to just change the source code of the Python binary I'm using. That is cheating. I want to break Python from the inside.

But I can use this to get the machine code that I want to replace the subscript assignment function with. (This is now just stupid compared to what we were doing before...and not at all portable. But we are doing it.).

First, I built CPython with this new source code in there. I can retrieve the machine code generated by our new function using objdump:

1 objdump Objects/unicodeobject.o

 1 00000000000000f4 <unicode_ass_subscript>:
 2       f4:   8b 4e 18                mov    0x18(%rsi),%ecx
 3       f7:   0f b6 47 20             movzbl 0x20(%rdi),%eax
 4       fb:   c0 e8 02                shr    $0x2,%al
 5       fe:   83 e0 07                and    $0x7,%eax
 6      101:   48 0f af c1             imul   %rcx,%rax
 7      105:   0f b6 52 30             movzbl 0x30(%rdx),%edx
 8      109:   88 54 07 30             mov    %dl,0x30(%rdi,%rax,1)
 9      10d:   b8 00 00 00 00          mov    $0x0,%eax
10      112:   c3                      retq

Then, in a standard un-patched Python session, let's copy the machine codes we've just compiled from the C, and make a new function pointer that points to them:

 1 import ctypes
 2 import mmap
 3 
 4 PyUnicode_Type = ctypes.cast(id(str), ctypes.POINTER(PyTypeObject)).contents
 5 
 6 payload = (
 7         b"\x8b\x4e\x18\x0f\xb6\x47\x20\xc0\xe8\x02\x83\xe0\x07\x48\x0f\xaf"
 8         b"\xc1\x0f\xb6\x52\x30\x88\x54\x07\x30\xb8\x00\x00\x00\x00\xc3")
 9 buf = mmap.mmap(
10         -1,
11         len(payload),
12         prot=mmap.PROT_READ | mmap.PROT_WRITE | mmap.PROT_EXEC)
13 buf.write(payload)
14 fpointer = ctypes.c_void_p.from_buffer(buf)
15 bad_boi = objobjargproc(ctypes.addressof(fpointer))
16 PyUnicode_Type.tp_as_mapping.contents.mp_ass_subscript = bad_boi

Before we scored this righteous hack, this would happen:

1 >>> x = "hack the planet"
2 >>> x[1] = "4"
3 TypeError: 'str' object does not support item assignment

but now...

1 >>> x = "hack the planet"
2 >>> x[1] = "4"
3 >>> print(x)
4 "h4ck the planet"

And so our pointless quest is over. I hope you had fun. Sometimes it is good to remember that computers can be just for fun. 😊

More information about this is in the Data Model. In short, there is a defined resolution order for class hierarchies. So if x.__dict__ didn't have the key "y", then we'll next look in base classes of x, &c. ↩
I first seen Armin Ronacher do this on Twitter, so a lot of credit is due to him for this great trick. Someone has uploaded his code here (I can't find original tweet) ↩
There is a good explanation as to why here ↩

C++ is not a superset of C

2019-09-02T00:00:00+01:00

If you're not familiar with both languages, you might have heard people say that C++ is a superset of C. If you're experienced in both languages, you'll know that this is not true at all.

Of course, C++ has many features that C does not; but there are also a few features that only C has. And, perhaps most importantly, there is code that compiles in both languages but does different things.

There's a lot of information about the differences between the two languages available, but a lot of it seems scattered. I wanted to have a go at creating a concise guide for the details that are often overlooked, with excerpts from the language standards to back these up.

Notes

This is primarily aimed at people who are familiar with at least one of C or C++.

When I refer to C++, I mean C++11 onwards, though much of this will apply to earlier standards. I'll be referencing the C++17 standard¹.

When I refer to C, I mean C99 onwards. I'll be referencing the C11 standard².

It's worth noting that a lot of compilers aren't fully compliant, or have extensions that aren't part of the standard. To me, this is part of what makes it difficult to pick apart what is standard, what is non-compliant, and what is implementation defined. I recommend Compiler Explorer if you want to see what other compilers might output if you are experimenting with any examples.

Update

I've made some updates after some helpful feedback:

fixing mistakes in the const section
clarifying the use of implicit int in the auto section

The original post is on the Internet Archive.

Code that compiles in both languages, but does different things in each

This is the category of differences that I think is most important. Not everything that C and C++ appear to share is as it seems.

const

What can be a constant expression?

The keyword const has a different semantic meaning in C++ than in C, but it's more subtle than I originally thought when first writing this blog post.

The differences come down to what each language allows to be a constant expression. A constant expression can be evaluated at compile time. Compile-time evaluation is needed for e.g. the size of a static array, as in the following example which will compile in C++, but whether it compiles in C will be implementation defined:

1 const size_t buffer_size = 5;
2 int buffer[buffer_size];
3 
4 // int main() {
5     // ...
6 // }

We'll need to piece together a few different pieces of the C11 standard to understand why this is implementation defined.

C11 6.6 paragraph 6 defines an integer constant expression:

An integer constant expression shall have integer type and shall only have operands that are integer constants, enumeration constants, character constants, sizeof expressions whose results are integer constants, and floating constants that are the immediate operands of casts. Cast operators in an integer constant expression shall only convert arithmetic types to integer types, except as part of an operand to the sizeof operator.

But what is an "integer constant"? From 6.4.4, these are literal values, not variables, e.g. 1.

What this boils down to is that only expressions like 1 or 5 + 7 can be constant expressions in C. Variables can't be constant expressions. As expected, this example doesn't compile with gcc. But it does compile with Clang: why?

The answer is one final piece of the puzzle, C11 6.6 paragraph 10:

An implementation may accept other forms of constant expressions.

A portable version of the code above in C would have to use a preprocessor macro:

1 #define BUFFER_SIZE (5)
2 int buffer[BUFFER_SIZE];

The keyword const was created for this very purpose by Bjarne Stroustrop³: to reduce the need for macros. C++ is much more permissive about what can be a constant expression, making const variables more powerful.

It was a surprise to me to learn that const originated in what would become C++, and was then adopted by C. I had assumed that const came from C, and C++ took the same concept and extended it in order to reduce the need for macros. I understand macros are embraced by C, but it seems a shame to deliberately reduce the usefulness of const when standardising C.

Linkage

Another difference is that file-scope const variables have internal linkage by default in C++. This is so that you can make a const declaration in a header without having multiple definition errors⁴

Modifying const variables

The following code is a constraint violation in C:

1 const int foo = 1;
2 int* bar = &foo;
3 *bar = 2;

C11 6.5.16.1 paragraph 1 lists some constraints, one of which must be true for an assignment to be valid. The relevant constraint for our example:

the left operand has atomic, qualified, or unqualified pointer type, and (considering the type the left operand would have after lvalue conversion) both operands are pointers to qualified or unqualified versions of compatible types, and the type pointed to by the left has all the qualifiers of the type pointed to by the right

To be conformant, the compiler must generate a diagnostic if there's a constraint violation. This could be a warning or an error. I've found that it is generally a warning, meaning this can often be compiled in C, though would give undefined behaviour⁵:

This is would not compile as C++. I think this is because in C++ const T is a distinct type from T, and the implicit conversion is not allowed. In C, the const is just a qualifier. I could be misunderstanding, however.

C++17 6.7.3:

The cv-qualified or cv-unqualified versions of a type are distinct types

Function declarations with no arguments

1 int func();

In C++, this declares a function that takes no arguments. But in C, this declares a function that could take any number of arguments of any type.

From the C11 standard 6.7.6.3 paragraphs 10 and 14:

The special case of an unnamed parameter of type void as the only item in the list specifies that the function has no parameters.

An empty list in a function declarator that is part of a definition of that function specifies that the function has no parameters. The empty list in a function declarator that is not part of a definition of that function specifies that no information about the number or types of the parameters is supplied.

So the following would be legit C:

1 // func.h
2 int func();

1 // func.c
2 int func(int foo, int bar) {
3     return foo + bar;
4 }

1 // main.c
2 #include "func.h"
3 
4 int main() {
5     return func(5, 6);
6 }

This would result in a compiler error in C++:

 main.c:5:12: error: no matching function for call to 'func'
   return func(5, 6);
          ^~~~
 ./func.h:2:5: note: candidate function not viable:
 requires 0 arguments, but 2 were provided

The effect of name mangling

There are some common implementation details that allow us to take this further. On my Linux machine using Clang, the following C compiles and links (though the result would of course be undefined):

1 // func.h
2 int func(int foo, int bar);

1 #include <stdio.h>
2 
3 // func.c
4 int func(float foo, float bar) {
5     return printf("%f, %f\n", foo, bar);
6 }

1 // main.c
2 #include "func.h"
3 
4 int main() {
5     return func(5, 6);
6 }

This does not compile in C++. C++ compilers commonly use name mangling to enable function overloading. They "mangle" the names of functions in order to encode their arguments, e.g. by appending the argument types to the function name. Generally, C compilers just store the function name as the symbol. We can see this by comparing the symbol table of func.o when compiled as C and C++.

As C:

╰─λ objdump -t func.o

func.o:     file format elf64-x86-64

SYMBOL TABLE:
0000000000000000 l    df *ABS*  0000000000000000 foo.c
0000000000000000 l    d  .text  0000000000000000 .text
0000000000000000 l    d  .rodata.str1.1 0000000000000000 .rodata.str1.1
0000000000000000 g     F .text  000000000000002e func
0000000000000000         *UND*  0000000000000000 printf

As C++:

╰─λ objdump -t func.o

func.o:     file format elf64-x86-64

SYMBOL TABLE:
0000000000000000 l    df *ABS*  0000000000000000 foo.c
0000000000000000 l    d  .text  0000000000000000 .text
0000000000000000 l    d  .rodata.str1.1 0000000000000000 .rodata.str1.1
0000000000000000 g     F .text  000000000000003b _Z4funcff
0000000000000000         *UND*  0000000000000000 printf

These implementation details are not part of the standards, but I'd be surprised to see an implementation that did something wildly different.

auto

I mostly include this for fun, as I think it's not as well known as it could be. auto is used for type-inference in C++, but is also a C keyword, just one that I've never actually seen used.

auto is used to declare something with automatic storage class. It's rarely seen because this is the default storage class for all variables declared within a block.

The following C has a constraint violation, namely not specifying a type⁶. This could error, but I've never found a compiler to give it anything but a warning about implicit conversion:

1 int main() {
2     auto x = "actually an int";
3     return x;
4 }

Before C99, it was legal to have no type specifiers, and the type would be assumed to be int. This is what happens when I compile this with Clang and gcc, and so we get a warning due to implicitly converting a char array to int.

In C++ this wouldn't compile, as the type of x is inferred to be const char*:

error: cannot initialize return object of type 'int' with an lvalue of type 'const char *'
    return x;

Features C has that C++ doesn't have

Despite C being a very small language, and C++ being huge, there are a few features that C has that C++ does not.

Variable length arrays

VLAs allow you to define an array of automatic storage duration with variable length. E.g.

1 void f(int n) {
2   int arr[n];
3   // ......
4 }

VLAs were actually made optional in the C11 standard, which makes them not very portable.

These aren't part of C++, probably in part because the C++ standard library relies heavily on dynamic memory allocation to create containers like std::vector that can be used similarly. There are reasons you might not want this dynamic allocation, but then perhaps you would not be using C++.

Restricted pointers

C defines a third type qualifier (in addition to const and volatile): restrict⁷. This is only used with pointers. Making a pointer restricted is telling the compiler "I will only access the underlying object via this pointer for the scope of this pointer". Consequently it can't be aliased. If you break this promise you will get undefined behaviour.

This exists to aid optimisation. A classic example is memmove where you can tell the compiler that the src and dst do not overlap.

From C11 6.7.3 paragraph 8:

An object that is accessed through a restrict-qualified pointer has a special association with that pointer. This association, defined in 6.7.3.1 below, requires that all accesses to that object use, directly or indirectly, the value of that particular pointer.135)The intended use of the restrict qualifier (like the register storage class) is to promote optimization, and deleting all instances of the qualifier from all preprocessing translation units composing a conforming program does not change its meaning (i.e., observable behavior)

Restricted pointers aren't part of the C++ standard but are actually supported as extensions by many compilers⁸.

I'm suspicious of restrict. It seems like playing with fire, and anecdotally it seems common to run into compiler optimisation bugs when using it because it's exercised so little⁹. But it's easy to be suspicious of something I've never actually used.

Designated initialisers

C99 brought in an incredibly useful way to initialise structs, and I do not understand why it has not been adopted by C++.

 1 typedef struct {
 2     float red;
 3     float green;
 4     float blue;
 5 } Colour;
 6 
 7 int main() {
 8     Colour c = { .red = 0.1, .green = 0.5, .blue = 0.9 };
 9     return 0;
10 }

In C++ you would have to initialise like this: Colour c = { 0.1, 0.5, 0.9 }; which is harder to read and not robust to changes in the definition of Colour. You could instead define a constructor but why should we have to do this for a simple aggregate type? I hear designated initialisers are now coming in C++20. It only took 21 years...

The closest working draft I could find for free online: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/n4713.pdf ↩
http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1548.pdf ↩
Sibling Rivalry, 2002, Bjarne Stroustrup ↩
C++11 standard appendix C.1.2 ↩
From C11 6.7.3 paragraph 6: If an attempt is made to modify an object defined with a const-qualified type through use of an lvalue with non-const-qualified type, the behavior is undefined. ↩
C11 6.7.2 ↩
C11 also defines type qualifier _Atomic but I didn't include it here for reasons of: conciseness; it's ugly (it's a shame it couldn't be atomic, too much existing code uses that); I don't know how common it is as a lot of people still use C99; C++ also has atomic types as part of the STL so it wasn't an interesting example. ↩
https://gcc.gnu.org/onlinedocs/gcc-6.4.0/gcc/Restricted-Pointers.html ↩
https://software.intel.com/en-us/forums/intel-c-compiler/topic/474141 ↩

C++20 concepts are not like Rust traits

2019-08-21T00:00:00+01:00

At writing, Rust's Wikipedia currently says the following:

Functions can be given generic parameters, which usually require the generic type to implement a certain trait or traits. Within such a function, the generic value can only be used through those traits. This means that a generic function can be type-checked as soon as it is defined. This is in contrast to C++ templates, which are fundamentally duck typed and cannot be checked until instantiated with concrete types. C++ concepts address the same issue and are expected to be part of C++20 (2020).

But C++ concepts (as currently proposed) are very different from Rust traits, and do not allow for the parameterised function to be type-checked only once.

Rust traits are implemented explicitly, whereas C++ concept constraints are implicitly met. This means that concept-constrained templates can legally invoke behaviour not defined by the concept. So, the following code compiles in g++ v9.2 with flags --std=c++2a -fconcepts:¹

 1 #include <string>
 2 
 3 template<typename T>
 4 concept bool Stringable = requires(T a) {
 5     {a.stringify()} -> std::string;
 6 };
 7 
 8 class Cat {
 9  public:
10     std::string stringify() {
11         return "meow";
12     }
13 
14     void pet() {
15     }
16 };
17 
18 template<Stringable T>
19 void f(T a) {
20     a.pet();
21 }
22 
23 int main() {
24     f(Cat());
25     return 0;
26 }

The Rust equivalent would not compile:

 1 trait Stringable {
 2     fn stringify() -> String;
 3 }
 4 
 5 struct Cat {
 6 }
 7 
 8 impl Cat {
 9     fn pet() {}
10 }
11 
12 impl Stringable for Cat {
13     fn stringify() -> String {
14         "meow".to_string()
15     }
16 }
17 
18 fn f<T: Stringable>(a: T) {
19     a.pet();  // error[E0599]: no method named `pet` found for type `T` in the current scope
20 }
21 
22 fn main() {
23     let cat = Cat{};
24     f(cat);
25 }

C++ concept-constrained templates are still only type checked when concrete instantiation is attempted – they just give better, sooner error messages for types that don't comply with the constraint, rather than the long stream of nonsense that failed template instantiations output in C++ without concepts.

I think it's quite common for people to think that concepts are the same as traits. They look similar syntactically, and also the realities of them aren't well known because they aren't yet in a standard. I hope this can clarify things for anyone curious, and help anyone adjust expectations before the C++20 standard is released.

Rust traits comparisons with other language constructs

Although Rust traits are very different from C++20 concepts, they have similarities to a lot of other language constructs for polymorphism:

Haskell typeclasses: Rust traits are based on these, but Rust does not have higher kinded types², and Rust enforces global uniqueness on trait implementations³⁴. This means that there is at most one implementation of a trait for any given type. This is not enforced in Haskell, but it is discouraged to take advantage of this.⁵
Java interfaces: when Rust traits are used dynamically, they are analogous to Java interfaces, except without the extend functionality available in Java.⁶

Rust: a future for real-time and safety-critical software without C or C++

2019-08-20T00:00:00+01:00

Overview

Rust is a fairly new programming language that I'm really excited about. I gave a talk about it to my coworkers, primarily aimed at C++ programmers. This is that talk translated to a blog post. I hope you will be excited about Rust too by the end of this blog post!

A quick overview: Rust is syntactically similar to C++, but semantically very different. It's heavily influenced by functional programming languages like Haskell and OCaml. It's statically typed, with full type inference, rather than the partial type inference that C++ has. It's as fast as C and C++ while making guarantees about memory safety that are impossible to make in those languages.

house[-1]

Before we look at Rust in any more detail, I want you to imagine yourself in a scenario. Imagine that you are a builder setting up the gas supply in a new house. Your boss tells you to connect the gas pipe in the basement to the gas main on the pavement. You go downstairs, and find that there's a glitch: this house doesn't have a basement!

So, what do you do? Perhaps you do nothing, or perhaps you decide to whimsically interpret your instruction by attaching the gas main to some other nearby fixture, like the air conditioning intake for the office next door. Either way, suppose you report back to your boss that you're done.

KWABOOM! When the dust settles from the explosion, you would be guilty of criminal negligence.[^1]

Yet this is exactly what happens in some programming languages. In C you could have an array, or in C++ you could have a vector, ask for the -1 index, and anything could happen. The result could be different any time you run the program, and you might not realise that something is wrong. This is called undefined behaviour, and the possibility of it can't be eliminated entirely, because low-level hardware operations are inherently unsafe, but it's something that is protected against in many languages, just not C and C++.

The lack of memory safety guarantees from these languages, and the ease with which undefined behaviour can be invoked, is terrifying when you think of how much of the world runs on software. Heartbleed, the famous SSL vulnerability, was due to this lack of memory safety; Stagefright, a famous Android vulnerability, was due to undefined behaviour from signed integer overflow in C++.

Memory safety is crucial to both the correctness and reliability of a program.

Vulnerabilities aren't the only concern. Memory safety is crucial to both the correctness and reliability of a program. No one wants their program to crash out of nowhere, no matter how minor the application: reliability matters. As for correctness, I have a friend who used to work on rocket flight simulation software and they found passing in the same initialisation data but with a different filename gave you a different result, because some uninitialised memory was being read, it happened to read the program argument's memory, and so the simulation was seeded with garbage values based on the filename. Arguably their entire business was a lie. # So why not use memory safe languages like Python or Java? Languages like Python and Java use garbage collection to automatically protect us from bad memory accesses, like * use-after-frees (when you access memory that has been deallocated) * double frees (when you release memory that's already been released, potentially corrupting the heap) * memory leaks (when memory that isn't being used is never released. This isn't necessarily dangerous but can cause your system to crash and destroy performance.) Languages like Python and Java protect from these situations automatically. A garbage collector will run as part of the JVM or the Python interpreter, and periodically check memory to find unused objects, releasing their associated resources and memory. But it does this at great cost. Garbage collection is slow, it uses a lot of memory, and crucially it means that at any point – you don't know when – the program will halt – for how long, you don't know – to clean up the garbage.

**Python and Java**
memory safe at the cost of speed and determinism

**C and C++**
fast and deterministic at the cost of memory safety

This lack of predictability makes it impossible to use Python or Java for real-time applications, where you must guarantee that operations will complete within a specified period of time. It's not about being as fast as possible, it's about guaranteeing you will be fast enough every single time. So of course, there are social reasons why C and C++ are popular: it's what people know and they've been around a long time. But they are also popular because they are fast and deterministic. Unfortunately, this comes at the cost of memory safety. Even worse, many real-time applications are also safety critical, like control software in cars and surgical robots. As a result, safety critical applications often use these dangerous languages. For a long time, this has been a fundamental trade-off. You either get speed and predictability, or you get memory safety. Rust completely overturns this, which is what makes it so exciting and notable. # What this blog post will cover These are the questions I hope to answer in this post: * What are Rust's design goals? * How does Rust achieve memory safety? * What does polymorphism look like in Rust? * What is Rust tooling like? # What are Rust's design goals? * Concurrency without data races * Concurrency happens whenever different parts of your program might execute at different times or out of order. * We'll discuss data races more later, but they're a common hazard when writing concurrent programs, as many of you will know. * Abstraction without overhead * This just means that the conveniences and expressive power that the language provides don't come at a run time cost, it doesn't slow your program down to use them. * Memory safety without garbage collection * We've just talked about what these two terms mean. Let's have a look at how Rust achieves this previously contradictory pairing. # Memory safety without garbage collection How Rust achieves memory safety is simultaneously really simple and really complex. It's simple because all it involves is enforcing a few simple rules, which are really easy to understand. In Rust, all objects have an _owner_, tracked by the compiler. There can only be one owner at a time, which is very different to how things work in most other programming languages. It ensures that there is exactly one binding to any given resource. This alone would be very restrictive, so of course we can also give out references according to strict rules. Taking a reference is often called "borrowing" in Rust and I'm going to use that language here. The rules for borrowing are: > Any borrow must last for a scope no greater than that of the owner. > > You may have one or the other of these two kinds of borrows, but not both at > the same time: > one or more immutable references to a resource > OR > exactly one mutable reference. The first rule eliminates use-after-frees. The second rule eliminates data races. A data race happens when: * two or more pointers access the same memory location at the same time * at least one of them is writing * and the operations aren't synchronised. The memory is left in an unknown state. We didn't have a heap when I worked as an embedded engineer, and we had a hardware trap for null pointer derefs. So a lot of common memory safety issues weren't a major concern. Data races were the main type of bug I was really scared of. Races can be difficult to detect until you make a seemingly insignificant change to the code, or there's a slight change in the external conditions, and suddenly the winner of the race changes. A data race caused multiple deaths in Therac-25 when patients were given lethal doses of radiation during cancer treatment.

Rust's key innovation is enforcing its memory safety rules at compile time.

As I said, these rules are simple and shouldn't be surprising for anyone who's ever had to deal with the possibility of data races before – but when I said that they are also complex, I meant it is incredibly smart that Rust is able to enforce these rules at compile time. This is Rust's key innovation. There are some memory-safety checks that have to be runtime – like array bounds checking. But if you are writing idiomatic Rust you'll almost never need these – you wouldn't usually be directly indexing an array. Instead you'd be using higher-order functions like fold, map and filter – you will be familiar with this type of function if you've written Haskell/Scala or even Python. ## unsafe Rust I mentioned earlier that the possibility of undefined behaviour isn't something that can be eliminated entirely, due to the inherently unsafe nature of low level operations. Rust allows you to do such operations within specific unsafe blocks. I believe C# and Ada have similar constructs for disabling certain safety checks. You'll often need this in Rust when doing embedded programming, or low level systems programming. The ability to isolate the potentially unsafe parts of your code is incredibly useful – those parts will be subject to a higher level of scrutiny, and if you have a bug that looks like a memory problem, those will be the only place that can be causing it, rather than absolutely anywhere in your code. The unsafe block doesn't disable the borrow checker, which is the part of the compiler that enforces the borrowing rules we just talked about – it just allows you to dereference raw pointers, or access/modify mutable static variables. The benefits of the ownership system are still there. # Revisiting ownership Speaking of the ownership system, I want to compare it with ownership in C++. Ownership semantics in C++ changed the language drastically when C++11 came out. But the language paid such a high price for backwards compatibility. Ownership, to me, feels unnaturally tacked onto C++. The previously simple value taxonomy was butchered by it[^2]. In many ways it was a great achievement to massively modernise such a widely used language, but Rust shows us what a language can look like when ownership is a core design concept from the beginning.

C++ smart pointers are just a library on top of an outdated system, and as such can be misused and abused in ways that Rust just does not allow.

C++'s type system does not model object lifetime at all. You can't check for use-after-frees at compile time. Smart pointers are just a library on top of an outdated system, and as such can be misused and abused in ways that Rust just does not allow. Let's take a look at some (simplified) C++ code I wrote at work, where this misuse occurs. Then we can look at a Rust equivalent, which (rightly) doesn't compile. # Abusing smart pointers in C++

 1 #include <functional>
 2 #include <memory>
 3 #include <vector>
 4 
 5 std::vector<DataValueCheck> createChecksFromStrings(
 6         std::unique_ptr<Data> data,
 7         std::vector<std::string> dataCheckStrs) {
 8 
 9     auto createCheck = [&](std::string checkStr) {
10         return DataValueCheck(checkStr, std::move(data));
11     };
12 
13     std::vector<DataValueCheck> checks;
14     std::transform(
15             dataCheckStrs.begin(),
16             dataCheckStrs.end(),
17             std::back_inserter(checks),
18             createCheck);
19 
20     return checks;
21 }

The idea of this code is that we take some strings defining some checks to be performed on some data, e.g. is a value within a particular range. We then create a vector of check objects by parsing these strings. First, we create a lambda that captures by reference, hence the ampersand. The unique pointer to the data is moved in this lambda, which was a mistake. We then fill our vector with checks constructed from moved data. The problem is that only the first move will be successful. Unique pointers are move-only. So after the first loop in `std::transform`, probably the unique pointer is nulled (the standard only specifies that it will be left in a valid but unknown state, but in my experience with Clang it's generally nulled). Using that null pointer later results in undefined behaviour! In my case, I got a segmentation fault, which is what will happen on a nullptr deref on most hosted systems, because the zero memory page is usually reserved. But this behaviour certainly isn't guaranteed. A bug like this could in theory lie dormant for a while, and then your application would crash out of nowhere. The use of the lambda here is a large part of what makes this dangerous. The compiler just sees a function pointer at the call-site. It can't inspect the lambda the way it might a standard function. For context on understanding how this bug came about, originally, we were using a shared_ptr to store the data, which would have made this code fine. We wrongly thought we could store it in a unique_ptr instead, and this bug came about when we made the change. It went unnoticed in part because the compiler didn't complain. I'm glad this happened because it means I can show you a real example of a C++ memory safety bug that went unnoticed by both me and my code reviewer, until it later showed up in a test[^3]. It doesn't matter if you're an experienced programmer – these bugs happen! And the compiler can't save you. We must demand better tools, for our sanity and for public safety. This is an ethical concern. With that in mind, let's look at a Rust version. # In Rust, that bad move is not allowed

1 pub fn create_checks_from_strings(
2         data: Box<Data>,
3         data_check_strs: Vec<String>)
4     -> Vec<DataValueCheck>
5 {
6     let create_check = |check_str: &String| DataValueCheck::new(check_str, data);
7     data_check_strs.iter().map(create_check).collect()
8 }

This is our first look at some Rust code. Now is a good time for me to mention that variables are immutable by default. For something to be modifiable, we need to use the `mut` keyword – kind of like the opposite of `const` in C and C++. The Box type just means that we've allocated on the heap. I chose it here because unique_ptrs are also heap allocated. We don't need anything else to be analogous with unique_ptr because of Rust's rule about each object having only one owner at a time. We're then creating a closure, and then using the higher order function `map` to apply it to the strings. It's very similar to the C++ version, but less verbose. But! This doesn't compile, and here's the error message.

 1 error[E0525]: expected a closure that 
implements the `FnMut` trait, but this closure only implements `FnOnce`
 2   --> bad_move.rs:1:8
 3    |
 4  6 |     let create_check = |check_str: &String| DataValueCheck::new(check_str, data);
 5    |                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^----^
 6    |                        |                                                     |
 7    |                        |                                 closure is `FnOnce` because it moves
 8    |                        |                                 the variable `data` out of its environment
 9    |                        this closure implements `FnOnce`, not `FnMut`
10  7 |     data_check_strs.iter().map(create_check).collect()
11    |                            --- the requirement to implement `FnMut` derives from here
12 
13 error: aborting due to previous error
14 
15 For more information about this error, try `rustc --explain E0525`.

One really great thing about the Rust community is there's a really strong focus on making sure there's lots of resources for people to learn, and on having readable error messages. You can even ask the compiler for more information about the error message, and it will show you a minimal example with explanations. When we create our closure, the data variable is moved inside it because of the one owner rule. The compiler then infers that the closure can only be run once: further calls are illegal as we no longer own the variable. Then, the function `map` requires a callable that can be called repeatedly and mutate state, so the compilation fails. I think this snippet shows how powerful the type system is in Rust compared to C++, and how different it is to program in a language where the compiler tracks object lifetime. You'll notice that the error message here mentions traits: "expected a closure that implements FnMut trait", for example. Traits are a language feature that tell the compiler what functionality a type must provide. Traits are Rust's mechanism for polymorphism. # Polymorphism In C++ there's a lot of different ways of doing polymorphism, which I think contributes to how bloated the language can feel. There's templates, function & operator overloading for static polymorphism, and subtyping for dynamic polymorphism. These can have major downsides: subtyping can lead to very high coupling, and templates can be unpleasant to use due to their lack of parameterisation. In Rust, traits provide a unified way of specifying both static and dynamic interfaces. They are Rust's sole notion of interface. They only support the "implements" relationship, not the "extends" relationship. This encourages designs that are based on composition, not implementation inheritance, leading to less coupling. Let's have a look at an example.

 1 trait Rateable {
 2     /// Rate fluff out of 10
 3     /// Ratings above 10 for exceptionally soft bois
 4     fn fluff_rating(&self) -> f32;
 5 }
 6 
 7 struct Alpaca {
 8     days_since_shearing: f32,
 9     age: f32
10 }
11 
12 impl Rateable for Alpaca {
13     fn fluff_rating(&self) -> f32 {
14         10.0 * 365.0 / self.days_since_shearing
15     }
16 }

There's nothing complicated going on here, I decided a simple but fun example was best. First, we're defining a trait called `Rateable`. For a type to be `Rateable`, it has to implement a function called `fluff_rating` that returns a float. Then we define a type called `Alpaca` and implement this interface for it. We could do the same for another type, say `Cat`!

 1 enum Coat {
 2     Hairless,
 3     Short,
 4     Medium,
 5     Long
 6 }
 7 
 8 struct Cat {
 9     coat: Coat,
10     age: f32
11 }
12 
13 impl Rateable for Cat {
14     fn fluff_rating(&self) -> f32 {
15         match self.coat {
16             Coat::Hairless => 0.0,
17             Coat::Short => 5.0,
18             Coat::Medium => 7.5,
19             Coat::Long => 10.0
20         }
21     }
22 }

Here you can see me using pattern matching, another Rust feature. It's similar in usage to a switch statement in C but semantically very different. Cases in switch blocks are just gotos; pattern matching has required coverage completeness. You have to cover every case for it to compile. Plus you can match on ranges and other constructs that makes it a lot more flexible. So, now that we've implemented this trait for these two types, we can have a generic function[^4].

1 fn pet<T: Rateable>(boi: T) -> &str {
2     match boi.fluff_rating() {
3         0.0...3.5 => "naked alien boi...but precious nonetheless",
4         3.5...6.5 => "increased floof...increased joy",
5         6.5...8.5 => "approaching maximum fluff",
6         _ => "sublime. the softest boi!"
7 }

Like in C++, the stuff inside the angle brackets is our type arguments. But unlike C++ templates, we are able to parametrise the function. We're able to say "this function is only for types that are Rateable". That's not something you can do in C++![^5] This has consequences beyond readability. Trait bounds on type arguments means the Rust compiler can type check the function once, rather than having to check each concrete instantiation separately. This means faster compilation and clearer compiler error messages. You can also use traits dynamically, which isn't preferred as it has a runtime penalty, but is sometimes necessary. I decided it was best not to cover that in this post. One other big part of traits is the interoperability that comes from standard traits, like `Add` and `Display`. Implementing add means you can add a type together with the + operator, implementing Display means you can print it. # Rust tools C and C++ don't have a standard way to manage dependencies. There's a few different tools for doing this, I haven't heard great things about any of them. Using plain Makefiles for your build system is very flexible, but can be rubbish to maintain. CMake reduces the maintenance burden but is less flexible which can be frustrating. Rust really shines in this respect. Cargo is the one and only tool used in the Rust community for dependency management, packaging and for building and running your code. It's similar in many ways to Pipenv and Poetry in Python. There's an official package repository to go along with it. I don't have a lot more to say about this! It's really nice to use and it makes me sad that C and C++ don't have the same thing. ![cargo](/images/rust-talk/cargo.png "cargo usage screenshot") # Should we all use Rust? There's no universal answer for this. It depends on your application, as with any programming language. Rust is already being used very successfully in many different places. Microsoft use it for Azure IoT stuff, Mozilla sponsor Rust and use it for parts of the Firefox web browser, and many smaller companies are using it too. So depending on your application, it's very much production ready.

Rust is already being used in production successfully

But for some applications you might find support immature or lacking.

### Embedded In the embedded world, how ready Rust is depends on what you are doing. There are mature resources for Cortex-M that are used in production, and there's a developing but not yet mature RISC-V toolchain. For x86 and arm8 bare metal the story is also good, like for Raspberry Pis. For more vintage architectures like PIC and AVR there isn't great support but I don't think for most new projects that should be a big issue. Cross compilation support is good for all LLVM targets because the Rust compiler uses LLVM as its backend. One thing where embedded Rust is lacking is there are no production grade RTOSs, and HALs are less developed. This isn't an insurmountable issue for many projects, but it would certainly hamper many too. I expect this to continue growing in the next couple years. ### Async One thing that definitely isn't ready is language async support which is still in development. They're still deciding what the async/await syntax should look like. ### Interoperability As for interoperability with other languages, there's a good C FFI in Rust, but you have to go through that if you want to call Rust from C++ or vice versa. That's very common in many languages, I don't expect it to change. I mention it because it would make it a bit of a pain to incorporate Rust into an existing C++ project: you'd need a C layer between the Rust and C++ and that would potentially be adding a lot of complexity. ### Final thoughts Were I starting from scratch on a new project at work I would definitely vouch for Rust. I'm really hopeful that it represents a better future for software – one that's more reliable, more secure and more enjoyable to write. [^1]: from Ian Barland's ["Why C and C++ are Awful Programming Languages"](http://www.radford.edu/ibarland/Manifestoes/whyC++isBad.shtml) [^2]: The value categories used to just be lvalues (which has an identifiable place in memory) and rvalues (which do no not, like literals). It is now [much more complicated](https://en.cppreference.com/w/cpp/language/value_category). [^3]: Yes...I should have had a test already. But for various unjustified reasons I didn't write a test that covered this particular code until later. [^4]: Note: cheekily, I included this code that would not actually compile. You’d need the return type to be `&’static str`. This is “lifetime annotation” and was outside the scope of my talk, and this blog post. Read about it [here](https://doc.rust-lang.org/1.9.0/book/lifetimes.html). [^5]: I hear a lot of people say that Concepts in C++20 are analogous to traits, but this isn't true. I explain why [here](https://mcla.ug/blog/cpp20-concepts-are-not-like-rust-traits.html)