Understanding renode and custom peripherals

# Renode

Renode is a simulation environment for embedding systems. It allows us emulate hardware with peripherals and run a firmware binary on THAT instead. To set this up you can refer to this guide.

In this blog, I will be trying my best to explain renode as I understood it when I was reading through the documentation.

The basics are of course that we need to give it an elf binary. Something that you will flash onto your MCU. There is support for different kinds of MCUs which you can find here. To find a more exhaustive list, check this one.

One cool thing to note is that renode supports all of STM32 types. That’s the golden zone. And no ESPs or RPis (except Pico) make it in there. If you want to emulate ESP32 and family, then your best bet is the espressif fork of QEMU. You can check the code out here, or use this blog post as a reference for setting that up and running with it.

You either make your own class in C# or figure out something better to do -> Replace with a stub if its a sensor data (essentially mock it?). Easier wins come from: Zephyr-supported STM32/nRF/RISC-V board, logic/protocol/state-machine testing, common peripherals.

# RESD file format

You can mock the sensor data using the .resd format. This is the renode sensor data format and renode also has tools to convert from CSV to .resd, so that’s good. Read this to understand how this exactly works: https://github.com/renode/renode/blob/master/tools/csv2resd/csv2resd.py. This will show how the csv needs to be structured.

We can mock both regular and irregular sensors because there are two kinds of valid data formats for .resd files as well.

1. Arbitrary timestamp sample blocks -> add a timestamp and a value -> For irregular sensor simulation
2. Constant frequency sample blocks -> let’s you add a metadata to specify the intiail timestamp and period between timestamps. This is for a regular sensor data testing.

Timestamps are unsigned 8-byte values expressed in virtual nanoseconds counted from the beginning of the file.

Read this documentation carefully for .resd.

# Writing custom peripheral models

To make writing peripherals easy, we can use this tool called peakrdl-renode.

The peakrdl-renode tool works by parsing a peripheral’s memory map described in the SystemRDL file, and outputting an autogenerated file containing a partial class.

We’ll see what this class means in a second but the idea is that, all the register management will then be handled by the tool, we just need to write the core logic.

You can take a look at the sample autogenerated part and the logic part to get a better understanding.

Its awesome that the larger file is the one which is autogenerated (which actually also means that its easier to write that too cause its a set of predefined logic anyways)

Source: Writing Peripherals

Renode allows the user to “model” HW peripherals in several ways:

1. automatic tags from the SVD file used mainly for logging purposes,
2. manual tags with return value used for logging and trivial flow control,
3. Python peripherals used for implementing very simple logic,
4. C# models, used to describe advanced peripheral logic and interconnect

The C# part is what we’re looking at right now. How does the access to the system bus work?

• Read and write by the CPU are either gonna go to internal memory (maybe this is important for this?) or passed to the C# implementation to handle.

There are two types of memory (is that the right way to say this?) and the fundamental difference between these two is how the memory is backed and whether the CPU can access them directly or not.

• ArrayMemory: ArrayMemory stores everything in a single garbage collector managed array. It cannot be handed to the translation engine. It’s mostly intended to be used for memory smaller than page size. It’s not the main RAM.

(If you’re confused about that last statement it means that given your page size, say 4kb or 16kb for newer architectures, you can hold until that much in the ArrayMemory. Page size is a single unit of the page table. Its a contiguous block of virtual memory)

• MappedMemory: To understand this, we’ll have to understand what tlib is how it works. Let’s park it for now and move on.

┌──────────────┐  C to C   ┌─────────────┐
│ MappedMemory │ ◀──────── │     CPU     │
└──────────────┘           └─────────────┘
                             │
                             │ C to C#
                             ▼
┌──────────────┐           ┌─────────────┐     ┌─────────────┐
│ Peripheral1  │ ◀──────── │  SystemBus  │ ──▶ │ Peripheral2 │
└──────────────┘           └─────────────┘     └─────────────┘
                             │
                             │
                             ▼
                           ┌─────────────┐
                           │ ArrayMemory │
                           └─────────────┘

All MappedMemory access is handled in C whle ArrayMemory access requires conversion to C# (why? No clue).

Now referencing https://renode.readthedocs.io/en/latest/advanced/writing-peripherals.html#writing-a-peripheral-model-in-c

• Must implement an IPeripheral interface.

This is the first thing to notice here:

public interface IPeripheral : IEmulationElement, IAnalyzable
{
    void Reset();
}

This is the actual contract, and this states the claim that “I am a peripheral” and hence whatever works on a peripheral, works on this.

There are two base inferences. IEmulationElement is the root of everything that’s part of the emulation. This carries identify and the logging parts.

using Antmicro.Renode.Utilities;

namespace Antmicro.Renode
{
	public interface IEmulationElement
	{
	}
}

And the IAnalyzable is basically to attach an analyzer (like a backend or an observer). So, by just declaring your peripheral with IPeripheral, it already means: nameable, loggable, observable.

Reset must be defined by us! This tells what exactly the return to power-on state must mean, whether you want to clear the registers or what.

But only by this you cannot become readable and writable by the CPU. For that you need to implement atleast these three:

• for reading (e.g., ReadDoubleWord) - called by the system bus in order to read a value from the peripheral,

• for writing (e.g., WriteDoubleWord) - called by the system bus in order to write a value to the peripheral,

• for resetting (Reset) - called by the framework to restore the state of the peripheral to the initial state. (Yeah same thing I mentioned before, this NEEDS to be implemented by us)

Here is a list of various Renode peripheral models that can be used as an inspiration:

1. UART
2. Timer
3. GPIO controller
4. I2C controller
5. SPI controller
6. I2C sensor
7. SPI sensor

Let’s look at the repl for x86.

biosMemory: Memory.MappedMemory @ {
        sysbus 0x0;
        sysbus <0xFF0000, +0x10000>;
        sysbus <0xFFFF0000, +0x10000>
    }
    size: 0xFF0000

sdram: Memory.MappedMemory @ sysbus 0x1000000
    size: 0x20000000

uart: UART.NS16550 @ sysbus 0xE00003F8

cpu: CPU.X86 @ sysbus
    cpuType: "n270"
    lapic: lapic

lapic: IRQControllers.LAPIC @ sysbus 0xFEE00000
    IRQ -> cpu@0

hpet: Timers.HPET @ sysbus 0xFED00000

sysbus:
    init:
        Tag <0xE0000020 1> "PIC1_CMD"
        Tag <0xE0000021 1> "PIC1_DATA"
        Tag <0xE00000A0 1> "PIC2_CMD"
        Tag <0xE00000A1 1> "PIC2_DATA"
        Tag <0xE0000040 1> "PIT_CHANNEL0"
        Tag <0xE0000041 1> "PIT_CHANNEL1"
        Tag <0xE0000042 1> "PIT_CHANNEL2"
        Tag <0xE0000043 1> "PIT_CMDREG"
        Tag <0xE0000CF8 4> "PCI_ADDRESS"
        Tag <0xE0000CFC 4> "PCI_DATA"
        Tag <0xE0000070 1> "CMOS_ADDRESS"
        Tag <0xE0000071 1> "CMOS_DATA"

This uses a timer called HPET (High Precision Event Timer) which is common for modern x86. Let’s see what the C# module tells us.

//
// Copyright (c) 2010-2026 Antmicro
//
// This file is licensed under the MIT License.
// Full license text is available in 'licenses/MIT.txt'.
//
using System.Collections.Generic;

using Antmicro.Renode.Core;
using Antmicro.Renode.Core.Structure.Registers;
using Antmicro.Renode.Exceptions;
using Antmicro.Renode.Logging;
using Antmicro.Renode.Peripherals.Bus;
using Antmicro.Renode.Time;

namespace Antmicro.Renode.Peripherals.Timers
{
    [AllowedTranslations(AllowedTranslation.DoubleWordToQuadWord)]
    // Based on IA-PC HPET (High Precision Event Timers) Specification
    public class HPET : LimitTimer, IQuadWordPeripheral, IKnownSize
    {
        public HPET(IMachine machine, ulong frequency = 100000000)
            : base(machine.ClockSource, frequency, direction: Direction.Ascending, limit: uint.MaxValue)
        {
            if(frequency < MinimumFrequency)
            {
                throw new ConstructionException($"Provided frequency = {frequency}, but it should be at least {MinimumFrequency}");
            }

            var registersMap = new Dictionary<long, QuadWordRegister>
            {
                {(long)Registers.GeneralCapabilitiesAndID, new QuadWordRegister(this)
                    .WithValueField(32, 32, FieldMode.Read, name: "COUNTER_CLK_PERIOD",
                        valueProviderCallback: _ => (ulong)(1e15 / Frequency))
                    .WithTag("VENDOR_ID", 16, 16)
                    .WithTaggedFlag("LEG_RT_CAP", 15)
                    .WithReservedBits(14, 1)
                    .WithTaggedFlag("COUNT_SIZE_CAP", 13)
                    .WithTag("NUM_TIM_CAP", 8, 4)
                    .WithTag("REV_ID", 0, 8)
                },
                {(long)Registers.GeneralConfiguration, new QuadWordRegister(this)
                    .WithReservedBits(2, 62)
                    .WithTaggedFlag("LEG_RT_CNF", 1)
                    .WithFlag(0, valueProviderCallback: _ => Enabled,
                        writeCallback: (_, value) => Enabled = value, name: "ENABLE_CNF")
                },
                {(long)Registers.GeneralInterruptStatus, new QuadWordRegister(this)
                    .WithReservedBits(32, 32)
                    .WithTag("Tn_INT_STS", 0, 32)
                },
                {(long)Registers.MainCounterValue, new QuadWordRegister(this)
                    .WithValueField(0, 64, valueProviderCallback: _ =>
                    {
                        if(machine.SystemBus.TryGetCurrentCPU(out var cpu))
                        {
                            cpu.SyncTime();
                        }
                        return (uint)Value;
                    },
                    writeCallback: (_, val) =>
                    {
                        if(Enabled)
                        {
                            this.WarningLog("Setting timer value when timer is enabled is not permited, ignoring");
                            return;
                        }
                        Value = val;
                    })
                },
            };
            for(var i = 0; i < NumberOfComparators; i++)
            {
                registersMap.Add(
                    (long)Registers.Timer0ConfigurationAndCapability + 0x20 * i,
                    new QuadWordRegister(this)
                        .WithTag($"T{i}_INT_ROUTE_CAP", 32, 32)
                        .WithReservedBits(16, 16)
                        .WithTaggedFlag($"T{i}_FSB_INT_DEL_CAP", 15)
                        .WithTaggedFlag($"T{i}_FSB_EN_CNF", 14)
                        .WithTag($"T{i}_INT_ROUTE_CNF", 9, 5)
                        .WithTaggedFlag("Tn_32MODE_CNF", 8)
                        .WithReservedBits(7, 1)
                        .WithTaggedFlag($"T{i}_VAL_SET_CNF", 6)
                        .WithTaggedFlag($"T{i}_SIZE_CAP", 5)
                        .WithTaggedFlag($"T{i}_PER_INT_CAP", 4)
                        .WithTaggedFlag($"T{i}_TYPE_CNF", 3)
                        .WithTaggedFlag($"T{i}_INT_ENB_CNF", 2)
                        .WithTaggedFlag($"T{i}_INT_TYPE_CNF", 1)
                        .WithReservedBits(0, 1)
                );
                registersMap.Add(
                    (long)Registers.Timer0ComparatorValue + 0x20 * i,
                    new QuadWordRegister(this)
                        .WithTag($"T{i}_COMPARATOR_VALUE", 0, 64)
                );
                registersMap.Add(
                    (long)Registers.Timer0FSBInterruptRoute + 0x20 * i,
                    new QuadWordRegister(this)
                        .WithTag($"T{i}_FSB_INT_ADDR", 32, 32)
                        .WithTag($"T{i}_FSB_INT_VAL", 0, 32)
                );
            }
            registers = new QuadWordRegisterCollection(this, registersMap);
        }

        public ulong ReadQuadWord(long offset)
        {
            return registers.Read(offset);
        }

        public void WriteQuadWord(long offset, ulong value)
        {
            registers.Write(offset, value);
        }

        public override void Reset()
        {
            base.Reset();
            registers.Reset();
        }

        public long Size => 0x158;

        private readonly QuadWordRegisterCollection registers;

        private const int NumberOfComparators = 3;

        // According to HPET Specification (2.4),
        // COUNTER_CLK_PERIOD should be at most 10^8, so frequency must be at least 10^7.
        private const ulong MinimumFrequency = (ulong)1e7;

        private enum Registers : long
        {
            GeneralCapabilitiesAndID = 0x0,
            GeneralConfiguration = 0x10,
            GeneralInterruptStatus = 0x20,
            MainCounterValue = 0xf0,
            Timer0ConfigurationAndCapability = 0x100,
            Timer0ComparatorValue = 0x108,
            Timer0FSBInterruptRoute = 0x110,
            Timer1ConfigurationAndCapability = 0x120,
            Timer1ComparatorValue = 0x128,
            Timer1FSBInterruptRoute = 0x130,
            Timer2ConfigurationAndCapability = 0x140,
            Timer2ComparatorValue = 0x148,
            Timer2FSBInterruptRoute = 0x150,
        }
    }
}

The first step is to clearly look at the specification cause this heavily references it. This is the actual specification and this is an overview.

# Notes from this specification

• A comparator register and a value register is a hardware component used to trigger an action when a live tracking metric matches a pre-configured target value.

For a timer to have a comparator and value register, it means that it holds the current count in the value register and compares the current value with a match register (via the comparator). This is to implement a trigger.

Motherboard architecture was split into two parts:

• Northbridge -> High speed communication
• Southbridge -> Slower I/O capabilities (Audio, SATA ports, USB, PCI slots)

Nowadays, northbridge is IN the chip itself, and the Southbridge evolved into the PCH (Platform Controller Hub). The PCH acts as the coordinator for almost every other component on the motherboard.

• It communicates CPU via a high-speed bus called DMI (Direct Media Interface).

Each individual timer can generate an interrupt when the value in its value register matches the value in the main counter. That’s the point! The comparator and value register is to generate an interrupt.

• The main counter uses the PCH’s 24-MHz crystal as its clock. The accuracy of the main counter is as accurate as the crystal that is used in the system.

Stuff you can use the timer for:

1. Scheduling -> Threads, tasks, processes
2. Synchronizing -> Digital Audio/Video
3. Time stamping

HPET, Multimedia Timer, MMT and MM Timer should be treated as the same timer hardware. The terms Timer, Event Timer, HPET, MMT and MM Timer refer to the combination of a Value, Comparator, and Match Register. Intel HPET allows 32 compare/match registers per counter.

• Fmin = 10 MHz -> Note how this is the same value used in the module
• Number of comparators = 3 -> This is also what is written in the code above
• Periodic capable timers = 1 -> This is probably not modeled in the C# module
• Interrupt Delivery via IOxAPIC -> This is a requirement according to the specs, how are we doing this in the C# module?

Okay turns out that this is ancient technology. 2005. No one does this anymore. And the reason I realized this is because HPET implements Interrupts via a specific required delivery mechanism, Interrupt Delivery via IOxAPIC -> But this C# module doesn’t implement any output from this timer at all! Its only a query me module. That’s all there is to this. And its not its fault. No one really needed this.

Let me actually look at the base class before anything else now, cause all timers inherit from it:

//
// Copyright (c) 2010-2026 Antmicro
// Copyright (c) 2011-2015 Realtime Embedded
//
// This file is licensed under the MIT License.
// Full license text is available in 'licenses/MIT.txt'.
//

using System;

using Antmicro.Renode.Core;
using Antmicro.Renode.Exceptions;
using Antmicro.Renode.Peripherals.CPU;
using Antmicro.Renode.Time;

namespace Antmicro.Renode.Peripherals.Timers
{
    public class LimitTimer : ITimer, IPeripheral
    {
        public LimitTimer(IClockSource clockSource, ulong frequency, IPeripheral owner, string localName, ulong limit = ulong.MaxValue, Direction direction = Direction.Descending, bool enabled = false, WorkMode workMode = WorkMode.Periodic, bool eventEnabled = false, bool autoUpdate = false, ulong divider = 1)
        {
            if(limit <= 0)
            {
                throw new ConstructionException("Limit must be greater than 0");
            }
            if(divider <= 0)
            {
                throw new ConstructionException("Divider must be greater than 0");
            }
            if(frequency <= 0)
            {
                throw new ConstructionException("Frequency must be greater than 0");
            }

            irqSync = new object();
            this.clockSource = clockSource;

            initialFrequency = frequency;
            initialLimit = limit;
            initialDirection = direction;
            initialEnabled = enabled;
            initialWorkMode = workMode;
            initialEventEnabled = eventEnabled;
            initialAutoUpdate = autoUpdate;
            initialDivider = divider;
            this.owner = this is IPeripheral && owner == null ? this : owner;
            this.localName = localName;
            InternalReset();
        }

        public ulong GetValueAndLimit(out ulong currentLimit)
        {
            var clockEntry = clockSource.GetClockEntry(OnLimitReached);
            currentLimit = clockEntry.Period;
            return clockEntry.Value;
        }

        public ulong Increment(ulong incrementBy)
        {
            var incValue = Value + incrementBy;

            Value = incValue % Limit;

            return incValue / Limit;
        }

        public ulong Decrement(ulong decrementBy)
        {
            var timesOverflown = ((Limit - 1 - Value) + decrementBy) / Limit;

            Value = Value + (Limit * timesOverflown) - decrementBy;

            return timesOverflown;
        }

        public virtual void Reset()
        {
            InternalReset();
        }

        public void ResetValue()
        {
            clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry =>
            {
                if(oldEntry.Direction == Direction.Ascending)
                {
                    return oldEntry.With(value: 0);
                }
                return oldEntry.With(value: oldEntry.Period);
            });

            RequestReturnOnCurrentCpu();
        }

        public void ClearInterrupt()
        {
            lock(irqSync)
            {
                rawInterrupt = false;
            }
        }

        public string LocalName => localName;

        public Direction Direction
        {
            get
            {
                return clockSource.GetClockEntry(OnLimitReached).Direction;
            }

            set
            {
                clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry => oldEntry.With(direction: value),
                    () =>
                    {
                        throw new InvalidOperationException("Should not reach here.");
                    });

                RequestReturnOnCurrentCpu();
            }
        }

        public bool RawInterrupt
        {
            get
            {
                lock(irqSync)   // yeah, we're using this as a lock, that was the normal usecase for object() anyway
                {
                    return rawInterrupt;
                }
            }
        }

        public bool EventEnabled
        {
            get
            {
                lock(irqSync)
                {
                    return eventEnabled;
                }
            }

            set
            {
                lock(irqSync)
                {
                    eventEnabled = value;
                }
            }
        }

        public bool Interrupt
        {
            get
            {
                lock(irqSync)
                {
                    return rawInterrupt && eventEnabled;
                }
            }
        }

        public bool AutoUpdate { get; set; }

        public ulong Limit
        {
            get
            {
                return clockSource.GetClockEntry(OnLimitReached).Period;
            }

            set
            {
                clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry =>
                {
                    if(AutoUpdate)
                    {
                        return oldEntry.With(period: value, value: oldEntry.Direction == Direction.Ascending ? 0 : value);
                    }

                    return oldEntry.With(period: value);
                }, () =>
                {
                    throw new InvalidOperationException("Should not reach here.");
                });

                RequestReturnOnCurrentCpu();
            }
        }

        public ulong Divider
        {
            get
            {
                return divider;
            }

            set
            {
                if(value == divider)
                {
                    return;
                }
                if(value <= 0)
                {
                    throw new ArgumentException("Divider must be greater than 0");
                }
                divider = value;
                var effectiveFrequency = Frequency / divider;
                clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry => oldEntry.With(frequency: effectiveFrequency));

                RequestReturnOnCurrentCpu();
            }
        }

        public WorkMode Mode
        {
            get
            {
                return clockSource.GetClockEntry(OnLimitReached).WorkMode;
            }

            set
            {
                clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry => oldEntry.With(workMode: value));
            }
        }

        public ulong Value
        {
            get
            {
                return clockSource.GetClockEntry(OnLimitReached).Value;
            }

            set
            {
                if(value > initialLimit)
                {
                    throw new ArgumentException("Value cannot be larger than limit");
                }

                clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry => oldEntry.With(value: value));

                RequestReturnOnCurrentCpu();
            }
        }

        public ulong Frequency
        {
            get
            {
                return frequency;
            }

            set
            {
                if(value <= 0)
                {
                    throw new ArgumentException("Frequency must be greater than 0");
                }
                frequency = value;
                var effectiveFrequency = frequency / Divider;
                clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry => oldEntry.With(frequency: effectiveFrequency));

                RequestReturnOnCurrentCpu();
            }
        }

        public virtual bool Enabled
        {
            get
            {
                return clockSource.GetClockEntry(OnLimitReached).Enabled;
            }

            set
            {
                clockSource.ExchangeClockEntryWith(OnLimitReached, oldEntry => oldEntry.With(enabled: value),
                    () => { throw new InvalidOperationException("Should not reach here."); });
                // should not reach here - limit should already be set in ctor

                RequestReturnOnCurrentCpu();
            }
        }

        public event Action LimitReached;

        protected LimitTimer(IClockSource clockSource, ulong frequency, ulong limit = ulong.MaxValue, Direction direction = Direction.Descending, bool enabled = false, WorkMode workMode = WorkMode.Periodic, bool eventEnabled = false, bool autoUpdate = false, ulong divider = 1)
            : this(clockSource, frequency, null, null, limit, direction, enabled, workMode, eventEnabled, autoUpdate, divider)
        {
        }

        // Should be used with caution as that clears all the subscriptions from all the sources.
        // Consequences within wider context may be difficult to predict
        protected void ClearSubscriptions()
        {
            LimitReached = null;
        }

        protected virtual void OnLimitReached()
        {
            lock(irqSync)
            {
                rawInterrupt = true;

                if(!eventEnabled)
                {
                    return;
                }

                var alarm = LimitReached;
                if(alarm != null)
                {
                    alarm();
                }
            }
        }

        private void InternalReset()
        {
            frequency = initialFrequency;
            divider = initialDivider;

            var clockEntry = new ClockEntry(initialLimit,  frequency / divider, OnLimitReached, owner, localName, initialEnabled, initialDirection, initialWorkMode)
            { Value = initialDirection == Direction.Ascending ? 0 : initialLimit };

            clockSource.ExchangeClockEntryWith(OnLimitReached, x => clockEntry, () => clockEntry);
            EventEnabled = initialEventEnabled;
            AutoUpdate = initialAutoUpdate;
            rawInterrupt = false;
        }

        private void RequestReturnOnCurrentCpu()
        {
            if(EmulationManager.Instance.CurrentEmulation.TryGetExecutionContext(out var machine, out var cpu))
            {
                (cpu as IControllableCPU)?.RequestReturn();
            }
        }

        private ulong frequency;

        private bool eventEnabled;
        private bool rawInterrupt;
        private ulong divider;

        private readonly ulong initialFrequency;
        private readonly WorkMode initialWorkMode;
        private readonly ulong initialLimit;
        private readonly Direction initialDirection;
        private readonly bool initialEnabled;
        private readonly IClockSource clockSource;
        private readonly object irqSync;
        private readonly bool initialEventEnabled;
        private readonly bool initialAutoUpdate;
        private readonly ulong initialDivider;
        private readonly IPeripheral owner;
        private readonly string localName;
    }
}

Let’s break this motherfucker down:

public LimitTimer(IClockSource clockSource, ulong frequency, IPeripheral owner, string localName, ulong limit = ulong.MaxValue, Direction direction = Direction.Descending, bool enabled = false, WorkMode workMode = WorkMode.Periodic, bool eventEnabled = false, bool autoUpdate = false, ulong divider = 1) 

Arguments:

1. clockSource -> This is a source clock for the timer
2. frequency -> This must be the frequency for the clock
3. owner -> This is a peripheral owner. I think this is related to which peripheral implements a LimitTimer but I am not sure yet. Let’s see.
4. localname -> This is a name. I think its just a refernence for the peripheral which implements this but again not sure
5. limit -> Okay maybe its the max value it can increment upto until it rolls around?
6. direction -> This is weird. Why is this defaulting to decreasing. (note that the defalt limit is also 2^64-1)
7. enabled -> Enabled what? The timer?
8. workMode -> Periodic timer -> This is cool. This was in the HPET specs as well. 1 out of 3 being periodic.
9. eventEnabled -> What event are we enabling? Interrupts?
10. autoUpdate -> Is this the roll around thing? Or is this saying that no relying on RTC at all ever? Always update on the crystal counter.
11. divider -> Not sure what this is for. Let’s see.

if(limit <= 0)
{
    throw new ConstructionException("Limit must be greater than 0");
}
if(divider <= 0)
{
    throw new ConstructionException("Divider must be greater than 0");
}
if(frequency <= 0)
{
    throw new ConstructionException("Frequency must be greater than 0");
}

irqSync = new object(); // I have created some memory here
this.clockSource = clockSource;

initialFrequency = frequency;
initialLimit = limit;
initialDirection = direction;
initialEnabled = enabled;
initialWorkMode = workMode;
initialEventEnabled = eventEnabled;
initialAutoUpdate = autoUpdate;
initialDivider = divider;
this.owner = this is IPeripheral && owner == null ? this : owner;
this.localName = localName;
InternalReset();

• This part is chill. It ensures some values are reasonable. Then creates an object called irqSync. This sounds suspiciously like interrupt syncing. The reason you do new object() in C# is when you want to create a lock (to not allow multiple threads to access the same memory) or as a placeholder. So, this creates free memory in the heap and allocates it to this object (its like a malloc which mallocs about 24 bytes of memory just to exist).

• this.clockSource = clockSource; -> This is basically doing self.clockSource = clockSource in python. However, you don’t really have to do this in C# because this is implicit. In python its explicit. So the reason one would do it is to just make this clear (especailly if names are the same as argument).

• Then it says: Set this.owner to myself (this) if I am a peripheral and no owner was provided. Otherwise, set this.owner to the provided owner

• Then it calls InternalReset() I have no idea what this function call does, but we’ll probably figure this out.

public ulong GetValueAndLimit(out ulong currentLimit)
{
    var clockEntry = clockSource.GetClockEntry(OnLimitReached);
    currentLimit = clockEntry.Period;
    return clockEntry.Value;
}

So with my limited C# knowledge I am assuming that this a method. I know, no need to bask in my glory. This is a method which is returning an unsigned long integer AND the currentLimit.

This is some C# hookey-pookey. When we write out ulong currentLimit we’re actually passing a reference (a pointer) to a blank spot in the computer’s memory. Note how the currentLimit is actually assigned a value before we return something. Insane stuff.

Actually now that I am doing this, I think I should go by how the runtime will see this rather than sequential cause these devs they mangle it all. So, remember InternalReset? Let’s look at that.

private void InternalReset()
{
    frequency = initialFrequency;
    divider = initialDivider;

    var clockEntry = new ClockEntry(initialLimit,  frequency / divider, OnLimitReached, owner, localName, initialEnabled, initialDirection, initialWorkMode)
    { Value = initialDirection == Direction.Ascending ? 0 : initialLimit };

    clockSource.ExchangeClockEntryWith(OnLimitReached, x => clockEntry, () => clockEntry);
    EventEnabled = initialEventEnabled;
    AutoUpdate = initialAutoUpdate;
    rawInterrupt = false;
}

Okay so this is a private method, I don’t really care about that but sure. So, there is a new clockEntry and an object initializer. So that Value in there is basically, 0 if initialDirection is ascending (recall how the default is descending), and initialLimit if descending. And initialLimit is limit which cannot be 0 and defaults to 18446744073709551615 -> The largest 64 bit unsigned integer.

So what is the ClockEntry? Did we define it before? I mean in this scope? Because its using new so its assinging some memory in the heap for this. But how is this like a dataclass?

This btw is the GetClockEntry:

public virtual ClockEntry GetClockEntry(Action handler)
{
    lock(sync)      // sync is a new object() -> Which we already know is for a mutex
    {
        var i = clockEntries.IndexOf(x => x.Handler == handler);
        if(i == -1) // This is what index of returns when the handler doesn't exist
        {
            throw new KeyNotFoundException();
        }
        var result = clockEntries[i];

        // Perform a full update of the clock entry we're getting
        if(!result.Enabled)
        {
            return result;
        }
        if(updateAlreadyInProgress.Value)
        {
            return result;
        }
        updateAlreadyInProgress.Value = true;
        try
        {
            var updateHandler = clockEntriesUpdateHandlers[i];
            if(updateHandler(ref result, elapsed + unaccountedTimes[i], ref nearestLimitIn))
            {
                result.Handler();
            }
            // This elapsed time is now accounted for this entry so clear it
            unaccountedTimes[i] = TimeInterval.Empty;
        }
        finally
        {
            updateAlreadyInProgress.Value = false;
        }
        clockEntries[i] = result;

        // Clear elapsed and deposit it as unaccounted time on all other enabled clock entries
        var triggerFullUpdate = false;
        for(int j = 0; j < clockEntries.Count; ++j)
        {
            if(i != j && clockEntries[j].Enabled)
            {
                unaccountedTimes[j] += elapsed;
                triggerFullUpdate |= unaccountedTimes[j] >= nearestLimitIn;
            }
        }
        elapsed = TimeInterval.Empty;

        if(triggerFullUpdate)
        {
            UpdateLimits();
            // unaccountedTimes cleared by Update
            result = clockEntries[i];
        }

        return result;
    }
}