DEV Community: moonlitpath

Submitting a DT Schema Patch for Rockchip RK3399-GRU Sound — A Dev Journal

moonlitpath — Mon, 30 Mar 2026 13:51:40 +0000

Note: The earlier parts of this series were part of my GSoC application for DT bindings. While I started this patch during that phase, I ended up submitting it afterward—so this became my first independent contribution to the community.

Mistake in previous patch
I realized that I had overlooked a major check in my first patch.. I hadn't checked for active users! And... turns out.. OLPC is quite an old device with minimal userbase..

How could I make such a crucial mistake? It seems I was so excited to start the last time, that I had forgotten to check whether the file has active users. Working on a file with active users doing so will actually benefit the community and be considered more meaningful. Old devices without active users can also be wrong, it's harder for the maintainers to manage such devices.

So this time around, I made sure to check whether this file has active users. To do that, we have to check whether this file has any active users that was built by arm64 defconfig.

The DT Binding that I chose to convert this time around was ROCKCHIP with MAX98357A/RT5514/DA7219 codecs on GRU boards.

This is the file:

ROCKCHIP with MAX98357A/RT5514/DA7219 codecs on GRU boards.

Required properties:
- compatible: "rockchip,rk3399-gru-sound"
- rockchip,cpu: The phandle of the Rockchip I2S controller that's
  connected to the codecs
- rockchip,codec: The phandle of the audio codecs

Optional properties:
- dmic-wakeup-delay-ms : specify delay time (ms) for DMIC ready.
  If this option is specified, which means it's required dmic need
  delay for DMIC to ready so that rt5514 can avoid recording before
  DMIC send valid data

Example:

sound {
        compatible = "rockchip,rk3399-gru-sound";
        rockchip,cpu = <&i2s0>;
        rockchip,codec = <&max98357a &rt5514 &da7219>;
        dmic-wakeup-delay-ms = <20>;
};

To check if there are any active users, I search the compatible property in the above file to check if there's a .dtsi or .dts file available that uses my controller.

And..

anu@laptop:~/kernel-dev/source/linux$ git grep "rockchip,rk3399-gru-sound" -- arch/arm64
arch/arm64/boot/dts/rockchip/rk3399-gru.dtsi:           compatible = "rockchip,rk3399-gru-sound";

It is in use!

I checked lore, and didn't find anyone working on this file so, it's mine now~
I'll start working!

Understanding the hardware
Rockchip SoC (system on chip) processors are ARM-based processors commonly used in Chromebooks, Tablets, embedded systems, etc.

This device is the sound subsystem machine that orchestrates multiple codecs. It gives audio capabilities to Rockchip RK3399 SoC.

Rockchip RK3399 SoC by itself doesnt have audio capabilites. It has to be paired with external codecs, like Realtek codec, etc, in order to gain these capabilites.

Working on the code

A thing that I found useful while writing the code, was -- I first filled my empty yaml file with everything I was 100% sure of (like the header and compatible property) , and then slowly worked on towards the things I was unsure of, i.e the vendor properties.

Understanding the vendor properties

rockchip,cpu: phandle of the Rockchip I2S controller
I2S is standard audio protocol to send/recieve digital audio data between chips.
So, this means that this property contains a pointer (phandle) to another device in the device tree - specifically I2S controller chip.
rockchip,codec: phandle of the audio codecs
it is a pointer (phandle) to the audio codec devices. The sound driver needs to know which codec is available and how to control them.

Understanding the codecs
- MAX98357A — Class D speaker amplifier (typically for built-in speakers)
- RT5514 — Microphone codec (input path, often includes DSP for voice detection)
- DA7219 — Full-featured audio codec (can do both input/output, often handles headphone/headset)

I started looking if the vendor properties that were defined here were already defined elsewhere, in which case, I should refer to those.

I used the search tool rg because I found it much faster than grep or git grep.

anu@laptop:~/kernel-dev/source/linux$ rg "rockchip,codec" Documentation/devicetree/bindings/ -t yaml
anu@laptop:~/kernel-dev/source/linux$ rg "rockchip,cpu" Documentation/devicetree/bindings/ -t yaml

As the result shows, no. they weren't used before.

So, I decided to refer to a rockchip schema, Documentation/devicetree/bindings/sound/rockchip,rk3328-codec.yaml here, there was a vendor property rockchip,grf defined.
I also opened the example schema to understand how to define such properties.

  rockchip,cpu:
    $ref: /schemas/types.yaml#/definitions/phandle
    description:
      The phandle of the Rockchip I2S controller that's connected to the codecs

  rockchip,codec:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    description: The phandle of the audio codecsi

to confirm the type, I had referred to the example given in my original DT binding txt file

rockchip,cpu = <&i2s0>;                          # <--- phandle
rockchip,codec = <&max98357a &rt5514 &da7219>;   # <---phandle-array

Understanding the optional property
dmic-wakeup-delay-ms: specify delay time for DMIC ready
DMIC: Digital Microphone -- for the microphone codec (RT5514)
The DMIC requires a small amount of time after waking up to stabilize and start recording to produce valid audio data, else it can record garbage data.

So, this property tells that it's required for DMIC to wait for X ms before starting to record.

Thus, I checked out the dmic codec in Documentation/devicetree/bindings/sound/dmic-codec.yaml and checked out it's wakeup property.

I found this defined in that file:

  wakeup-delay-ms:
    description: Delay (in ms) after enabling the DMIC

Searching for parent files for my schema

It seems that in the above code, this property does the same thing as the property I defined..
Does this file need to be inherited.. ?

so I searched for the files that had used the wakeup-delay-ms property, and I found:
Documentation/devicetree/bindings/sound/adi,adau7002.yaml

  wakeup-delay-ms:
    description:
      Delay after power up needed for device to settle.

however.. for this file.. the dmic file wasnt included.. why?

So, I looked up this device:
ADAU7002 is Analog Devices' audio converter chip. It converts PDM (pulse density modulation) to I2S. It's a codec, but it's not a DMIC.

This means that their property having the same names.... means nothing.

Then I noticed something:
This property... it seemed to not be a core DT property since I had not seen it in the example-schema.yaml .. is this a clue?

Answer: no. it isn't. It's just a property. I had this concept in my internal mind that the referring to the parent properties (using allOf: $ref:) are somewhat like "inheritence" in OOPS. That is why I had thought that if a property has a same name, then it must be "imported" from another file. This is not the case at all.

A file being a parent simply means that along with the rules defined in the current schema, the DTS should also satisfy all the rules defined by the parent schema.
No inheritence, the OOP concepts have no relation to this concept.

Then, I noticed another thing, while going through similar files.
All the yaml schema files that I had checked from this folder seemed to inherit the dai-common.yaml
even the DT Binding converstion patch about Maxim integrated Audio Codec that I had analysed while learning about DT schemas had this file as a parent...

I had learnt at that time:
DAI = Digital Audio Interface
codec needs to handle separate i/o (mic, speaker, etc) -- so each device would have a separate DAI port

Does that mean my file will need it though?
My device just needs to orchestrate multiple codecs which will manage the DAI. I needn't do that.

i checked in the dtsi file with rockchip,rk3399-gru-sound keyword to find where my file is referenced, and no it does not reference any 'sound-dai-cells' property. This proves that I should not include it in my file.

it does however contains maxim,max98357a -- that refeneces the dai property, but that's a difference audio codec file. not related to me

sound: sound {
                compatible = "rockchip,rk3399-gru-sound";
                rockchip,cpu = <&i2s0 &spdif>;
        };

thus my driver does not require the soudn dai property

now, i have to prevent the schema from allowing any extra properties, so i referred to example-schema.yaml

# Ideally, the schema should have this line otherwise any other properties
# present are allowed. There's a few common properties such as 'status' and
# 'pinctrl-*' which are added automatically by the tooling.
#   
# This can't be used in cases where another schema is referenced
# (i.e. allOf: [{$ref: ...}]).
# If and only if another schema is referenced and arbitrary children nodes can
# appear, "unevaluatedProperties: false" could be used.  A typical example is
# an I2C controller where no name pattern matching for children can be added.
additionalProperties: false

Thus, I set additionalProperties: false

and done!

final file:

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/sound/rockchip,rk3399-gru-sound.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: ROCKCHIP with MAX98357A/RT5514/DA7219 codecs on GRU boards

maintainers:
  - Heiko Stuebner <heiko@sntech.de>

properties:
  compatible:
    const: rockchip,rk3399-gru-sound

  rockchip,cpu:
    $ref: /schemas/types.yaml#/definitions/phandle
    description:
      The phandle of the Rockchip I2S controller that's connected to the codecs

  rockchip,codec:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    description: The phandle of the audio codecs

  dmic-wakeup-delay-ms:
    description:
      specify delay time (ms) for DMIC ready.
      If this option is specified, which means it's required dmic need
      delay for DMIC to ready so that rt5514 can avoid recording before
      DMIC sends valid data

required:
  - compatible
  - rockchip,cpu
  - rockchip,codec

additionalProperties: false

examples:
  - |
    sound {
      compatible = "rockchip,rk3399-gru-sound";
      rockchip,cpu = <&i2s0>;
      rockchip,codec = <&max98357a &rt5514 &da7219>;
      dmic-wakeup-delay-ms = <20>;
    };

Testing

Now it's time to test it!

So, following the same steps as the last time,

I first test it against the core DT schema, to check if the binding is correct --

anu@laptop:~/kernel-dev/source/linux$ make -j8 dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.yaml
make[1]: Entering directory '/home/anu/kernel-dev/source/linux/out'
  SCHEMA  Documentation/devicetree/bindings/processed-schema.json
  CHKDT   ../Documentation/devicetree/bindings
  LINT    ../Documentation/devicetree/bindings
  DTEX    Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.example.dts
  DTC [C] Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.example.dtb
make[1]: Leaving directory '/home/anu/kernel-dev/source/linux/out'

and it is!

now it's time to validate it against the specified dtb schema

(note: i had not been able to try this in the past file because that file had no DTB file for it..)

I tried this:

anu@laptop:~/kernel-dev/source/linux$ ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make CHECK_DTBS=y DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.yaml rockchip/rk3399-gru-kevin.dtb
***
*** Configuration file ".config" not found!
***
*** Please run some configurator (e.g. "make oldconfig" or
*** "make menuconfig" or "make xconfig").
***
/home/anu/kernel-dev/source/linux/Makefile:844: include/config/auto.conf.cmd: No such file or directory
make[1]: *** [/home/anu/kernel-dev/source/linux/Makefile:853: .config] Error 1
make: *** [Makefile:248: __sub-make] Error 2

the reason was that I had not built a .config file using defconfig first.

for searching for the answer, I had referred this post by Krzysztof Kozlowski: https://www.linaro.org/blog/tips-and-tricks-for-validating-devicetree-sources-with-the-devicetree-schema/

first, I cleaned the directory. I hadn't done this at the start, and got an error while building in the next steps, where I was pointed to run make mrproper

anu@laptop:~/kernel-dev/source/linux$ make mrproper
make[1]: Entering directory '/home/anu/kernel-dev/source/linux/out'
  CLEAN   Documentation/devicetree/bindings
  CLEAN   scripts/basic
  CLEAN   scripts/dtc
make[1]: Leaving directory '/home/anu/kernel-dev/source/linux/out'

I set up my environment

anu@laptop:~/kernel-dev/source/linux$ export ARCH=arm64
export CROSS_COMPILE=aarch64-linux-gnu-
export KBUILD_OUTPUT=out/

this builds the .config file:

anu@laptop:~/kernel-dev/source/linux$ make defconfig
make[1]: Entering directory '/home/anu/kernel-dev/source/linux/out'
  GEN     Makefile
*** Default configuration is based on 'defconfig'
#
# configuration written to .config
#
make[1]: Leaving directory '/home/anu/kernel-dev/source/linux/out'

now for this step, I had run a full make dtbs_check.. however it took a lot of time, almost 20 mins to finish.

when I first ran this command, I got this error:

$ ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- make CHECK_DTBS=y 
DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.yaml rockchip/rk3399-gru-kevin.dtb DTC 
[C] arch/arm64/boot/dts/rockchip/rk3399-gru-kevin.dtb 
/home/anu/kernel-dev/source/linux/arch/arm64/boot/dts/rockchip/rk3399-gru-kevin.dtb:
sound (rockchip,rk3399-gru-sound): 
rockchip,cpu:0: [211, 212] is too long from schema $id: http://devicetree.org/schemas/sound/rockchip,rk3399-gru-sound.yaml

look at this part:

rockchip,cpu:0: [211, 212] is too long from schema $id:

this means that the property rockchip,cpu should be a phandle-array and not a phandle, that I had set it to.

So, I went to the DT Schema, changed it and ran make dtbs_check again.
This time, it passed.
make[1]: Leaving directory '/home/anu/kernel-dev/source/linux/out'

make dtbs_check had taken way too much time the last time around. Now, I decided to test it against a dtb file.

When I had searched for the dts file before to find active users, there was a .dtsi file, but no .dts file.
it was this one: arch/arm64/boot/dts/rockchip/rk3399-gru.dtsi

so, i decided to see whether there are any dts files that import this dtsi file.

anu@laptop:~/kernel-dev/source/linux$ rg "rk3399-gru.dtsi"
arch/arm64/boot/dts/rockchip/rk3399-gru-scarlet.dtsi
8:#include "rk3399-gru.dtsi"

arch/arm64/boot/dts/rockchip/rk3399-gru-chromebook.dtsi
8:#include "rk3399-gru.dtsi"
248:     * set this here, because rk3399-gru.dtsi ensures we can generate this

and I found.. 2 more .dtsi files.. I didn't give up and kept digging

anu@laptop:~/kernel-dev/source/linux$ rg "rk3399-gru-scarlet.dtsi"
arch/arm64/boot/dts/rockchip/rk3399-gru-scarlet-kd.dts
10:#include "rk3399-gru-scarlet.dtsi"

arch/arm64/boot/dts/rockchip/rk3399-gru-scarlet-inx.dts
10:#include "rk3399-gru-scarlet.dtsi"

arch/arm64/boot/dts/rockchip/rk3399-gru-scarlet-dumo.dts
10:#include "rk3399-gru-scarlet.dtsi"


anu@laptop:~/kernel-dev/source/linux$ rg "rk3399-gru-chromebook.dtsi"
arch/arm64/boot/dts/rockchip/rk3399-gru-kevin.dts
9:#include "rk3399-gru-chromebook.dtsi"

arch/arm64/boot/dts/rockchip/rk3399-gru-bob.dts
9:#include "rk3399-gru-chromebook.dtsi"

and I found .dts files!
now, I can test them!

anu@laptop:~/kernel-dev/source/linux$ make CHECK_DTBS=y DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.yaml  rockchip/rk3399-gru-kevin.dtb
make[1]: Entering directory '/home/anu/kernel-dev/source/linux/out'
  HOSTCC  scripts/dtc/dtc.o
  HOSTCC  scripts/dtc/flattree.o
  HOSTCC  scripts/dtc/fstree.o
  HOSTCC  scripts/dtc/data.o
  HOSTCC  scripts/dtc/livetree.o
  HOSTCC  scripts/dtc/treesource.o
  HOSTCC  scripts/dtc/srcpos.o
  HOSTCC  scripts/dtc/checks.o
  HOSTCC  scripts/dtc/util.o
  LEX     scripts/dtc/dtc-lexer.lex.c
  YACC    scripts/dtc/dtc-parser.tab.[ch]
  HOSTCC  scripts/dtc/dtc-lexer.lex.o
  HOSTCC  scripts/dtc/dtc-parser.tab.o
  HOSTLD  scripts/dtc/dtc
  HOSTCC  scripts/dtc/libfdt/fdt.o
  HOSTCC  scripts/dtc/libfdt/fdt_ro.o
  HOSTCC  scripts/dtc/libfdt/fdt_wip.o
  HOSTCC  scripts/dtc/libfdt/fdt_sw.o
  HOSTCC  scripts/dtc/libfdt/fdt_rw.o
  HOSTCC  scripts/dtc/libfdt/fdt_strerror.o
  HOSTCC  scripts/dtc/libfdt/fdt_empty_tree.o
  HOSTCC  scripts/dtc/libfdt/fdt_addresses.o
  HOSTCC  scripts/dtc/libfdt/fdt_overlay.o
  HOSTCC  scripts/dtc/fdtoverlay.o
  HOSTLD  scripts/dtc/fdtoverlay
  SCHEMA  Documentation/devicetree/bindings/processed-schema.json
  UPD     include/config/kernel.release
  DTC [C] arch/arm64/boot/dts/rockchip/rk3399-gru-kevin.dtb
make[1]: Leaving directory '/home/anu/kernel-dev/source/linux/out'

and done!

I also checked it against a few other .dts files that I found, and they also succeeded!

anu@laptop:~/kernel-dev/source/linux$ make CHECK_DTBS=y DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.yaml  rockchip/rk3399-gru-scarlet-dumo.dtb
make[1]: Entering directory '/home/anu/kernel-dev/source/linux/out'
  DTC [C] arch/arm64/boot/dts/rockchip/rk3399-gru-scarlet-dumo.dtb
make[1]: Leaving directory '/home/anu/kernel-dev/source/linux/out'

I also tested
arch/arm64/boot/dts/rockchip/rk3399-gru-bob.dts

arch/arm64/boot/dts/rockchip/rk3399-gru-scarlet-kd.dts

and they both succeeded!

My patch is ready to submit!

Note: This patch was not a part of GSoC application, it was submitted after the application period. I submitted the patch directly to the mailing list, it didn't go through internal review with mentors like my previous patches.

[4-4-26]
I got a response from maintainer Krzysztof!

> Convert the rockchip,rk3399-gru-sound.txt DT binding to YAML Schema.  

DT Schema, not YAML Schema.  

Same in subject.  

[https://elixir.bootlin.com/linux/v6.17-rc3/source/Documentation/devicetree/bindings/submitting-patches.rst#L18](https://elixir.bootlin.com/linux/v6.17-rc3/source/Documentation/devicetree/bindings/submitting-patches.rst#L18)  

...  

> +---  
> +$id: [http://devicetree.org/schemas/sound/rockchip,rk3399-gru-sound.yaml#](http://devicetree.org/schemas/sound/rockchip,rk3399-gru-sound.yaml#)  
> +$schema: [http://devicetree.org/meta-schemas/core.yaml#](http://devicetree.org/meta-schemas/core.yaml#)  
> +  
> +title: ROCKCHIP with MAX98357A/RT5514/DA7219 codecs on GRU boards  

Rockchip  

> +  
> +maintainers:  
> +  - Heiko Stuebner <[heiko@sntech.de](mailto:heiko@sntech.de)>  
> +  
> +properties:  
> +  compatible:  
> +    const: rockchip,rk3399-gru-sound  
> +  
> +  rockchip,cpu:  
> +    $ref: /schemas/types.yaml#/definitions/phandle-array  

Need to list items. See msm/gpu.yaml,  
allwinner,sun4i-a10-display-engine.yaml and others.  

And read the driver code to understand what is supposed to be here.  


> +    description:  
> +      The phandle of the Rockchip I2S controller that's connected to the codecs  
> +  
> +  rockchip,codec:  
> +    $ref: /schemas/types.yaml#/definitions/phandle-array  

Same here.  

> +    description: The phandle of the audio codecs

The first 2 changes are clear. My naming was wrong. I can correct those easily. The next 2 were confusing.
I began exploring the files that he told me.
I started off with the yaml files (msm/gpu.yaml and allwinner,sun4i-a10-display-engine.yaml)

This is what I noticed:
both files had this structure-

subproperty:
  minItems: 1
  maxItems: 4
    items:
      maxItems: 1

maxItems and minItems tell the valididator the maximum and minimum
items: maxItems:1 tells the schema validator that each individual entry in the phandle is a single phandle with no extra cells or arguments.

(example of phandle array entry with extra args: <&clk 3>)
This is true for both properties rockchip,cpu and rockchip,codec.

Next, I looked into the driver code. sound/soc/rockchip/rk3399_gru_sound.c

Inside this code, I observed the properties rockchip,cpu and rockchip,codec

I found that they were used in this function:

static int rockchip_sound_of_parse_dais(struct device *dev,
                    struct snd_soc_card *card)
{
    struct device_node *np_cpu, *np_cpu0, *np_cpu1;
    struct device_node *np_codec;
    struct snd_soc_dai_link *dai;
    struct snd_soc_dapm_route *routes;
    int i, index;
    int num_routes;

    card->dai_link = devm_kzalloc(dev, sizeof(rockchip_dais),
                      GFP_KERNEL);
    if (!card->dai_link)
        return -ENOMEM;

    num_routes = 0;
    for (i = 0; i < ARRAY_SIZE(rockchip_routes); i++)
        num_routes += rockchip_routes[i].num_routes;
    routes = devm_kcalloc(dev, num_routes, sizeof(*routes),
                  GFP_KERNEL);
    if (!routes)
        return -ENOMEM;
    card->dapm_routes = routes;

// 💡💡 rockchip,cpu defined here
    np_cpu0 = of_parse_phandle(dev->of_node, "rockchip,cpu", 0);
    np_cpu1 = of_parse_phandle(dev->of_node, "rockchip,cpu", 1);

    card->num_dapm_routes = 0;
    card->num_links = 0;

// 💡💡 rockchip,codec defined here
    for (i = 0; i < ARRAY_SIZE(rockchip_dais); i++) {
        np_codec = of_parse_phandle(dev->of_node,
                        "rockchip,codec", i);
        if (!np_codec)
            break;

        if (!of_device_is_available(np_codec))
            continue;

        index = rockchip_sound_codec_node_match(np_codec);
        if (index < 0)
            continue;

// 💡💡 the values for rockchip,codec and rockchip,cpu are used here. 
        switch (index) {
        case DAILINK_CDNDP:
            np_cpu = np_cpu1;
            break;
        case DAILINK_RT5514_DSP:
            np_cpu = np_codec;
            break;
        default:
            np_cpu = np_cpu0;
            break;
        }

        if (!np_cpu) {
            dev_err(dev, "Missing 'rockchip,cpu' for %s\n",
                rockchip_dais[index].name);
            return -EINVAL;
        }

        dai = &card->dai_link[card->num_links++];
        *dai = rockchip_dais[index];

        if (!dai->codecs->name)
            dai->codecs->of_node = np_codec;
        dai->platforms->of_node = np_cpu;
        dai->cpus->of_node = np_cpu;

        if (card->num_dapm_routes + rockchip_routes[index].num_routes >
            num_routes) {
            dev_err(dev, "Too many routes\n");
            return -EINVAL;
        }

        memcpy(routes + card->num_dapm_routes,
               rockchip_routes[index].routes,
               rockchip_routes[index].num_routes * sizeof(*routes));
        card->num_dapm_routes += rockchip_routes[index].num_routes;
    }

    return 0;
}

Deduction:

rockchip,cpu can have 2 values at max and 1 value minimum.

I checked out array rockchip_dais[]

static const struct snd_soc_dai_link rockchip_dais[] = {
        [DAILINK_CDNDP] = {
        .name = "DP",
        .stream_name = "DP PCM",
        .init = rockchip_sound_cdndp_init,
        .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF |
            SND_SOC_DAIFMT_CBC_CFC,
        SND_SOC_DAILINK_REG(cdndp),
    },
    [DAILINK_DA7219] = {
        .name = "DA7219",
        .stream_name = "DA7219 PCM",
        .init = rockchip_sound_da7219_init,
        .ops = &rockchip_sound_da7219_ops,
        /* set da7219 as slave */
        .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF |
            SND_SOC_DAIFMT_CBC_CFC,
        SND_SOC_DAILINK_REG(da7219),
    },
    [DAILINK_DMIC] = {
        .name = "DMIC",
        .stream_name = "DMIC PCM",
        .ops = &rockchip_sound_dmic_ops,
        .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF |
            SND_SOC_DAIFMT_CBC_CFC,
        SND_SOC_DAILINK_REG(dmic),
    },
    [DAILINK_MAX98357A] = {
        .name = "MAX98357A",
        .stream_name = "MAX98357A PCM",
        .ops = &rockchip_sound_max98357a_ops,
        /* set max98357a as slave */
        .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF |
            SND_SOC_DAIFMT_CBC_CFC,
        SND_SOC_DAILINK_REG(max98357a),
    },
    [DAILINK_RT5514] = {
        .name = "RT5514",
        .stream_name = "RT5514 PCM",
        .ops = &rockchip_sound_rt5514_ops,
        /* set rt5514 as slave */
        .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF |
            SND_SOC_DAIFMT_CBC_CFC,
        SND_SOC_DAILINK_REG(rt5514),
    },
    /* RT5514 DSP for voice wakeup via spi bus */
    [DAILINK_RT5514_DSP] = {
        .name = "RT5514 DSP",
        .stream_name = "Wake on Voice",
        SND_SOC_DAILINK_REG(rt5514_dsp),
    },
};

there are 6 elements in this array. however, the codec values accepted, as per the original txt binding title are:

ROCKCHIP with MAX98357A/RT5514/DA7219 codecs on GRU boards.

that means that this property can accept just 3 values at max.

looking at the switch case program in the driver code where the values are actually assigned:

        switch (index) {
        case DAILINK_CDNDP:
            np_cpu = np_cpu1;
            break;
        case DAILINK_RT5514_DSP:
            np_cpu = np_codec;
            break;
        default:
            np_cpu = np_cpu0;
            break;
        }

we can make out that the order of elements for rockchip,cpu matters
but for rockchip,codec it does not matter. (look at the driver code and array.

Now, since the order of elements for rockchip,cpu matters, we need to write description for each item.

According to the code,
The 2nd element of the array is for DAILINK_CDNDP -- this is for the Cadence DisplayPort (cdn dp), -- the spdif controller
and the 1st element is for all the other options - I2S controllers connected to the codecs.

However, I noticed that the original txt binding had not contained any mention of the spdif controller, so i checked the .dtsi file for this binding: arch/arm64/boot/dts/rockchip/rk3399-gru.dtsi

        sound: sound {
                compatible = "rockchip,rk3399-gru-sound";
                rockchip,cpu = <&i2s0 &spdif>;
        };

This proved that the spdif property indeed exists for the device RK3399-gru-sound

Thus, I can add it to my DT Schema in peace.
This is how I added it

  rockchip,cpu:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    minItems: 1
    maxItems: 2
    items:
      - items:
          - description: Phandle to I2S controller connected to codecs
      - items:
        - description: Phandle to SPDIF controller

I remember I had said this before:

there are 6 elements in this array. however, the codec values accepted, as per the original txt binding title are:

ROCKCHIP with MAX98357A/RT5514/DA7219 codecs on GRU boards.
that means that this property can accept just 3 values at max.

I realized that I should test this properly and prove that. So, I began carding through the files that used the rockchip,codec property

These were the files that had it:

arch/arm64/boot/dts/rockchip/rk3399-gru-scarlet.dtsi

rockchip,codec = <&max98357a &dmic &codec &cdn_dp>

arch/arm64/boot/dts/rockchip/rk3399-gru-chromebook.dtsi

&sound {
        rockchip,codec = <&max98357a &headsetcodec
                          &codec &wacky_spi_audio &cdn_dp>;
};

notice that there are some additional properties.

for this, i went back to the driver code:

index = rockchip_sound_codec_node_match(np_codec);
if (index < 0)
        continue;

switch (index) {
case DAILINK_CDNDP:

static int rockchip_sound_codec_node_match(struct device_node *np_codec)
{
        struct device *dev;
        int i;

        for (i = 0; i < ARRAY_SIZE(dailink_match); i++) {
                if (!of_device_is_compatible(np_codec,
                                             dailink_match[i].compatible))
                        continue;

                if (dailink_match[i].bus_type) {
                        dev = bus_find_device_by_of_node(dailink_match[i].bus_type,
                                                         np_codec);
                        if (!dev)
                                continue;
                        put_device(dev);
                }

                return i;
        }
        return -1;
}

so if the element is not found -1 is returned to the index, and is index < 0, the loop is simply continued.

now in order to understand the maximum entries,

for (i = 0; i < ARRAY_SIZE(rockchip_dais); i++) {
        np_codec = of_parse_phandle(dev->of_node, "rockchip,codec", i);

the size of rockchip_dais is 6. thus, max 6 elements can be parsed, properties >6 will be ignored.
Thus, my assumption was wrong. the max_size of t he array should be 6.

However, looking at the code, it's clear that the order of the properties does not matter. i have no need to explicitly declare them.

After that, I did some touch ups to the descriptions of the properties to refine them a bit.
And done!

This is how my final v2 looks like:

# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/sound/rockchip,rk3399-gru-sound.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Rockchip with MAX98357A/RT5514/DA7219 codecs on GRU boards

maintainers:
  - Heiko Stuebner <heiko@sntech.de>

properties:
  compatible:
    const: rockchip,rk3399-gru-sound

  rockchip,cpu:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    description: |
      List of phandles to the Rockchip CPU DAI controllers connected to codecs
    minItems: 1
    items:
      - items:
          - description: Phandle to the Rockchip I2S controllers
      - items:
          - description: |
              Phandle to the Rockchip SPDIF controller. Required when a
              DisplayPort audio codec is referenced in rockchip,codec

  rockchip,codec:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    description: |
      The phandles of the audio codecs connected to the Rockchip CPU DAI
      controllers
    minItems: 1
    maxItems: 6
    items:
      maxItems: 1

  dmic-wakeup-delay-ms:
    description: |
      specify delay time (ms) for DMIC ready.
      If this option is specified, a delay is required for DMIC to get ready
      so that rt5514 can avoid recording before DMIC sends valid data

required:
  - compatible
  - rockchip,cpu
  - rockchip,codec

additionalProperties: false

examples:
  - |
    sound {
      compatible = "rockchip,rk3399-gru-sound";
      rockchip,cpu = <&i2s0 &spdif>;
      rockchip,codec = <&max98357a &rt5514 &da7219 &cdn_dp>;
      dmic-wakeup-delay-ms = <20>;
    };

Now it's time for testing.

[x] dt_binding_check
[x] dtbs_check

for this, I realized that i dont have to do such a long procedure of commands, as shown in the previous one, there is a shorter way:

make mrproper

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- KBUILD_OUTPUT=out/ defconfig

make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- KBUILD_OUTPUT=out/ CHECK_DTBS=y DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/rockchip,rk3399-gru-sound.yaml rockchip/rk3399-gru-kevin.dtb

both checks are completed successfully, the patch v2 is ready to submit!

I submitted v2!

[12-04-26 14:48:36]

YAY!!!! Krzysztof reviewed my patch, and didn't mention any changes!! It means my patch is correct right? :)) >.<

[13-04-26 00:12:08]

Omggggg!!!! I just recieved a mail from maintainer Mark Brown!!
It's applied!!!!!!

On Fri, 10 Apr 2026 11:25:32 +0530, Anushka Badhe wrote:  
> ASoC: dt-bindings: rockchip: convert rk3399-gru-sound to DT Schema  

Applied to  

   [https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git](https://git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git) for-7.1  

Thanks!  

[1/1] ASoC: dt-bindings: rockchip: convert rk3399-gru-sound to DT Schema  
      [https://git.kernel.org/broonie/sound/c/115e7d764dad](https://git.kernel.org/broonie/sound/c/115e7d764dad)  

All being well this means that it will be integrated into the linux-next  
tree (usually sometime in the next 24 hours) and sent to Linus during  
the next merge window (or sooner if it is a bug fix), however if  
problems are discovered then the patch may be dropped or reverted.  

You may get further e-mails resulting from automated or manual testing  
and review of the tree, please engage with people reporting problems and  
send followup patches addressing any issues that are reported if needed.  

If any updates are required or you are submitting further changes they  
should be sent as incremental updates against current git, existing  
patches will not be replaced.  

Please add any relevant lists and maintainers to the CCs when replying  
to this mail.  

Thanks,  
Mark

OMGG!!! I am SO excited!!! My patch will actually be merged!! OMG! sfkafjsfdaajfnfkjsdfhbaewkfhawsljkshfkf

git.kernel.org/pub/scm/linux/kernel/git/broonie/sound.git

OMGGGGG!!! My patch is in the tree!!! _My patch is in the tree!!! aaaaaaaaa!!!!! I am SO excited!

I can't wait to start with my next patch! Looking into the driver code was so much fun! The entire process of exploration, observing existing code was SO interesting!
It's such a pity I have my exams coming up, so I won't be able to work on a new patch, or post for a while... :')

I'll resume contributing and my exploration once my exams are done :)

Submitting My First Device Tree Binding Patch While Applying for GSoC 2026 — And It Got ACKed!

moonlitpath — Fri, 27 Mar 2026 06:23:10 +0000

Introduction:
A short introduction about me:
Hey! I'm Anushka. I'm a UG college student, majoring in Information Technology, from India. I absolutely love learning about how systems work under the hood.

This year, I am applying to GSoC, specifically the Project under Device Tree Bindings, which involves converting Device Tree Bindings to DT Schema.

Note: This is not a tutorial, just my own devjournal documenting my learning process.

For the a patch for the task of converting a DT binding to a DT Schema, I looked through many drivers, and first, I had chosen Multi-Inno MI0283QT display panel
However, I found out that this device relied on a lot of complex properties that will probably depend on other files...

So, I decided to temporarily put it aside, and work on a simple file to get the hang of what should be done, and then come back to the bigger file, and work on it.

After looking through all the DT binding files, I decided to settle with this simple DT Bindings file

OLPC XO-1 RTC

OLPC XO-1 RTC
~~~~~~~~~~~~~

Required properties:
 - compatible : "olpc,xo1-rtc"

Understanding the Hardware:

RTC - Real Time Clock
A RTC is an electronic device that measures and tracks time, often in hours, minutes, and seconds. Unlike regular clocks, an RTC is specifically designed to operate within computing systems, even when the device is turned off or disconnected from power. Its primary function is to provide accurate time and date, which is crucial for various applications such as event logging, timestamping, and time-sensitive operations in computing and embedded systems. 1

OLPC = One Laptop Per Child
The OLPC XO (colloquially known as $100 Laptop,Children's Machineis a low cost laptop computer intended to be distributed to children in developing countries around the world,to provide them with access to knowledge, and opportunities to "explore, experiment and express themselves" (constructionist learning).2

So, OLPC XO-1 RTC is basically an RTC that was developed specially for OLPC XO laptops.

Making a patch

I had already analyzed a patch while understanding Device Trees.
I also referred to the example-schema.yaml found in Documentation/devicetree/bindings

And I started working on my DT Schema patch, it was quite simple and didn't require much time

# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
%YAML 1.2
---
$id: [http://devicetree.org/schemas/rtc/olpc-xo1-rtc.yaml](http://devicetree.org/schemas/rtc/olpc-xo1-rtc.yaml)#
$schema: [http://devicetree.org/meta-schemas/core.yaml](http://devicetree.org/meta-schemas/core.yaml)#

title: OLPC XO-1 RTC

maintainers:
  - Alexandre Belloni <alexandre.belloni@bootlin.com>

properties:
  compatible:
    enum:
      - olpc,xo1-rtc

required:
  - compatible

additionalProperties: false

examples:
  - |
    rtc {
       compatible = "olpc,xo1-rtc";
    };

link: https://lore.kernel.org/linux-devicetree/20260325084708.40629-1-anushkabadhe@gmail.com/

I checked if this works and it does!

anu@laptop:~/kernel-dev/source/linux$ make clean && make -j8 \
  dt_binding_check \
  DT_SCHEMA_FILES=Documentation/devicetree/bindings/rtc/olpc-xo1-rtc.yaml
CLEAN   Documentation/devicetree/bindings
HOSTCC  scripts/basic/fixdep
HOSTCC  scripts/dtc/dtc.o
HOSTCC  scripts/dtc/flattree.o
HOSTCC  scripts/dtc/fstree.o
HOSTCC  scripts/dtc/data.o
HOSTCC  scripts/dtc/livetree.o
HOSTCC  scripts/dtc/treesource.o
HOSTCC  scripts/dtc/srcpos.o
HOSTCC  scripts/dtc/checks.o
HOSTCC  scripts/dtc/util.o
SCHEMA  Documentation/devicetree/bindings/processed-schema.json
LEX     scripts/dtc/dtc-lexer.lex.c
YACC    scripts/dtc/dtc-parser.tab.[ch]
HOSTCC  scripts/dtc/dtc-lexer.lex.o
HOSTCC  scripts/dtc/dtc-parser.tab.o
HOSTLD  scripts/dtc/dtc
CHKDT   ./Documentation/devicetree/bindings
LINT    ./Documentation/devicetree/bindings
DTEX    Documentation/devicetree/bindings/rtc/olpc-xo1-rtc.example.dts
DTC [C] Documentation/devicetree/bindings/rtc/olpc-xo1-rtc.example.dtb

I validated DTB against my schema

Reply

I got a reply from the maintainer, Alexandre Belloni!
He told me that this should be moved in trivial-rtc

What is trivial-rtc?
trivial-rtc.yaml is a file where minimal or generic RTC devices' schema are written. These devices are very simple and have generic properties, so instead of creating a separate DT Schema file, they are added to a common file called trivial-rtc.yaml

Thus, I added my device to the file,

index a2891ceb6344..000000000000
--- a/Documentation/devicetree/bindings/rtc/olpc-xo1-rtc.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-OLPC XO-1 RTC
-~~~~~~~~~~~~~
-
-Required properties:
- - compatible : "olpc,xo1-rtc"
[diff](https://lore.kernel.org/linux-devicetree/20260325093003.44051-1-anushkabadhe@gmail.com/#iZ31Documentation:devicetree:bindings:rtc:trivial-rtc.yaml) --git a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
index b47822370d6f..722176c831aa 100644
--- a/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
+++ b/Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
@@ -65,6 +65,8 @@ properties:
       - microcrystal,rv3029
       # Real Time Clock
       - microcrystal,rv8523
+      # OLPC XO-1 RTC
+      - olpc,xo1-rtc
       # I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC
       - ricoh,r2025sd
       # I2C bus SERIAL INTERFACE REAL-TIME CLOCK IC
--

I checked if the schema is valid and it is!

anu@laptop:~/kernel-dev/source/linux$ make -j4 dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/rtc/trivial-rtc.yaml
  SCHEMA  Documentation/devicetree/bindings/processed-schema.json
  CHKDT   ./Documentation/devicetree/bindings
  LINT    ./Documentation/devicetree/bindings

I went ahead submitted my patch
https://lore.kernel.org/linux-devicetree/20260325093003.44051-1-anushkabadhe@gmail.com/

[25-03-26 23:19:39] HOLY SHIT!!!!!!!!
MY PATCH GOT ACKED!!!!!!!!!!!!!!!
OMGGGGGG!!!!
I AM LITERALLY SCREAMING IN THE MIDDLE OF THE NIGHT!!
I HAVE NEVER FELT SO HAPPY!!!
I AM SO EXCITED THAT I AM JUMPING!
YAY!

I also got a piece of advice by the maintainer who accepted my patch, Conor Dooley:
I had been sending patches of the next version in response to the original patches, inside the same thread,

and that isn't how it's done
I should create a different thread in order to send new patches.

Thank you so much Conor! I'll definitely remember that for my future patches.

Right now, as I write, I am still so excited, my fingers are trembling, lol
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
;lkdsjgsoegnhgkesjrgnhbseikgujhiu sfkjslfkjaf

[3-4-26 20:27:46]
I got an email from maintainer Alexander Belloni that it's been applied!!!
YAY!!!

End note:
This was my first patch, and making it was a truly enjoyable process, I can't wait to start working on another patch again!
Although I am a currently beginner, I am learning through my mistakes, that I document on these post series. Someday, I won't be a beginner and a seasoned contributer. I really look forward to it.
I will definitely continue contributing to the kernel and open source!

References

Device Tree Bindings — What They Are and Why They Matter

moonlitpath — Fri, 27 Mar 2026 06:12:04 +0000

written: 15th March, 2026

Motivation:

I was applying for GSoC 2026 - DT Bindings Project. In order to understand this project more, I decided to start off my learning about them first. I had also learnt about ACPI tables in this post while investigating my laptop's low power bug, and had encountered device trees. This made me curious about the GSoC project and so, I decided to learn about Device trees.

Along the way, I started finding them really interesting and worked on a patch to convert a DT binding to a DT Schema too! (i will talk about that in the next post)

What is a device tree?

A device tree is a data structure that describes hardware.

Hardware can be discoverable or non discoverable.

Discoverable -- some buses like PCI(e) and USB are discoverable -- can enumerate and identify connected devices at runtime
Non discoverable -- Buses like I2C, SPI, 1-Wire arent -- system must know how the devices are configured and what devices are connected --> this is where device trees are useful

Non discoverable devices hardware descriptions needed:-

CPU Cores
device specific details -- like memory addresses and interrupt requests.
board level componets like clock sources, reset signals etc These details OS/bootloader cannot guess

How to discover non discoverable components:

1) Modify OS/Bootloader directly to include the required information to discover devices--- but after ARM32 architecture -- too tedious to do..
2) ACPI tables -- mainly used on x86 architectures (pc, laptop), and some ARM64 platforms
3) Device trees -- used for embedded CPU arch, like ARM, RISC-V, MIPS, etc

Device Tree

it's a tree data structure that descibes hardware
described in --> Device Tree Source (.dts) files
compiled to --> Device Tree Blob (.dtb) format
by --> Device tree Compiler (dtc)

DTB can be directly linked to the bootloader, or passed to the OS by the bootloader

Device Tree Bindings

These are the sets of rules that check if the devicetree provided by the hardware are valid or not?
Eg. Arduino has temperature sensor. Temp sensors has hardware descriptions and device tree. these are validated against device tree bindings, and then identified.

Device Trees bindings are written in YAML format. These are machine readable,

The patch I will analyze is written by Krzysztof Kozlowski. It was provided as a reference in the GSoC Device Tree Bindings Project

Patch Link GSoC Project Details Link

YAML

Extra stuff added later:
This device is supported by only I2C bus. (it's explained in the next image)
But, some devices are supported by SPI protocol only. SPI protocol has 4 wires. There is no addressing system, and each chip gets a dedicated chip wire.

reg helps answer the question how a CPU identifies and reaches this specific chip of the bus

reg on I2C is the slave address.
Each chip has a dedicated slave address hardwired into it by the manufacturer.
Eg. here, reg=<0x11>

reg on spi identity of chip is the chip select line number. CPU has physical wires, there is no addressing, and reg is the number of wires connected.
Eg. here, reg=<0> --> connected to chip select line 0

maxItems can be > 1 in case of memory mapped peripherals -- that live directly inside the CPU's memory address space, and occupy separate regions of memory.
Eg. A display controller that has config registers at address1
and framebuffer memory at address2

TXT file -- old

Traditionally, they used to be written in txt format. These were just documentations written by the developer. These aren't machine readable, can't be verified quickly, and the documentation can be incomplete

Things I figured out along the way

DTS (device tree sources) -- describes the hardware
DT bindings -- how DTS should be constructed

Previously -- DT bindings were written in text in past
DT schema -- new format -- yaml
--new format which follows validation of bindings itself against meta schema
--validation of DTS against bindings

rules for writing bindings -- all new bindings must come in DT Schema

rules ->

adding new properties to DT bindings is not acceptable.
no adding linux specific subsystem names
don't describe software policies -- what OS should do
no need for properties for discoverable hardware
dual licence should be mentioned at start (GPL-2.0-only OR BSD-2-Clause)
bindings file name should be like -> vendor,device.yaml or vendor,soc-ip.yaml
binding patches and driver patches should be different
compatible --> should be specific -- no bus suffixes (if bus is there)
simple-mfd
---> simple multi functional device -- children does not depend on any features of parent
no reset lines -- no clocks -
for very simple devices
syscon - simple -- generic register range -- many pieces -- no 1 specific device
aka system controller -- has different bits for different pieces
dont use it to replace imp drivers
properties represent hardware characteristics

Resources:

Submitting my second cleanup patch While Applying for GSoC 2026 — Still Messy, Still Learning

moonlitpath — Fri, 27 Mar 2026 06:01:18 +0000

A short introduction about me:
Hey! I'm Anushka. I'm a UG college student, majoring in Information Technology, from India. I absolutely love learning about how systems work under the hood.

This year, I am applying to GSoC, specifically the Project under Device Tree Bindings, which involves converting Device Tree Bindings to DT Schema.
One of the prerequisites is to create a small patch that fixes a trivial issue in drivers/staging. So, in this post, I am documenting my process of doing exactly that.

Note: This is not a tutorial, just my own devjournal documenting my learning process.

In my last post, I wrote about how I submitted my first patch, and why it got rejected -- Someone else was already actively working on fixing the same issue. I learnt to check lore.kernel.org to see the latest updates and patches.

I continued looking for more patches to convert.

So, after going through the entire drivers/staging directory, and running checkpatch script in each, plus checking on [lore.kernel.org] to see if anyone is already working the file, I found that almost all subsystems are free of warnings.
There are minor CHECK issues like camelcase, or blank space issues, but most of them have nothing.
The ones which have are already being actively fixed by another person.

So, after a long time of searching, I found this file drivers/staging/media/atomisp/pci/system_local.c

These were the warnings checkpatch showed me:

anu@laptop:~/kernel-dev/source/linux$ scripts/checkpatch.pl -f --terse --strict drivers/staging/media/atomisp/pci/system_local.c
drivers/staging/media/atomisp/pci/system_local.c:59: WARNING: Block comments use * on subsequent lines
drivers/staging/media/atomisp/pci/system_local.c:74: WARNING: Block comments use * on subsequent lines
drivers/staging/media/atomisp/pci/system_local.c:88: WARNING: Block comments use a trailing */ on a separate line
drivers/staging/media/atomisp/pci/system_local.c:90: WARNING: please, no spaces at the start of a line
total: 0 errors, 4 warnings, 0 checks, 170 lines checked

And then, I checked lore

.png]

It seems no one is actively working on this file. I can start with this one!

I decided to work with the whitespace issue, since the comments issue was related to commented out code, which would have been a logical issue, requiring thorough knowledge to fix.

The issue was that the coder had indented using spaces instead of tabs. I fixed the issue and sent it to the mentors to review.

snippet from git diff

-    (hrt_address)0x0000000000000600ULL;
+       (hrt_address)0x0000000000000600ULL;

[24-03-26 01:42:35]
Okay. I have sent my new patch!!
[[https://lore.kernel.org/linux-media/20260324081007.23165-1-anushkabadhe@gmail.com/T/#u]]

I got a reply, from maintainer Andy Shevchenko!

My whitespace patch, as you can see, is very small, it doesn't add value to the main code. I was advised that I can improve readabilty of the code by merging the split variable declaration on 2 lines.

That's so nice of him!! He guided me on how I can make a useful contribution!

So, I made the changes, and i noticed that the comment block position seemed to be wrong.. I fixed that too, and then sent them both in v2.

[25-03-26]

Mistake: One patch should address just one type of a change. My file now had 2 types of changes: comment */ position modification as well as improving readability.

I cant believe I forgot about that, I will definetely remember to check my patch changes carefully in the future!

Thus, my patch was marked NAK.. and I was told to make just 1 change.

So, I removed the change and sent it as v3

[26-03-26]

This time, I got a "Nice" from Andy as a review! That made me really happy.
He told me that since this constant GP_TIMER_BASE is used in just one file -- gp_timer.c, I should remove that constant from this file along with it's comment to there and remove it's mentioning from the other header files.

And this will make my patch gain value!!

So, now, I am doing just that.

First, I searched for all the places where the constant was defined:

anu@laptop:~/kernel-dev/source/linux$ rg "GP_TIMER_BASE"
drivers/staging/media/atomisp/pci/system_local.h
59:extern const hrt_address GP_TIMER_BASE;

drivers/staging/media/atomisp/pci/system_local.c
89:const hrt_address GP_TIMER_BASE = (hrt_address)0x0000000000000600ULL;

drivers/staging/media/atomisp/pci/hive_isp_css_common/host/gp_timer.c
28:        GP_TIMER_BASE +
35: ia_css_device_store_uint32((GP_TIMER_BASE +

drivers/staging/media/atomisp/pci/hive_isp_css_include/gp_timer.h
24:#include "system_local.h"    /*GP_TIMER_BASE address */

It seems that it's inside 1 header file (system_local.h) as an extern,which is imported in another header file (gp_timer.h) and then this header file is imported in gp_timer.c where it is actually used.

Wow, that's so unnecessarily complicated. He's right, moving that file directly to where it's used, will make it much more useful.

Understanding the subsystem and what the file does
I should have done this from the start, but ig, better late than never. I will remember to always to this in the future though.

media/atomisp/pci/system_local.c

media/atomisp -> part of the media subsystem -- this handles camera drivers -- Intel’s Atom Image Signal Processor (ISP)

pci -> communicates over the PCI

system_local.c -> this file is the main file that basically handles the interaction between the hardware and the internal code for the device

drivers/staging/media/atomisp/pci/hive_isp_css_common/host/gp_timer.c

hive_isp_css_common -> intel isp's camera support system

host -> code running on cpu (not isp firmware)

gp_timer.c -> general purpose timer -- it is used by the driver to measure time, delays, schedule commands, etc

after examining all the files once to confirm it's safe, i proceeded with moving the variable GP_TIMER_BASE to gp_timer.c

Here's what i did:
1) copied the declaration of GP_TIMER_BASE along with the function declaration from system_local.c to gp_timer.c and pasted it at the top, before function declaration

now the next question is whether or not I should remove system_local.h from gp_timer.h .....

I just noticed something really interesting here... system_local.h had been imported in both gp_timer.c as well as gp_timer.h ...
and gp_timer.h has been included in gp_timer.c .. obviously

so i conclude that system_local.h had been imported twice in gp_timer.c, and it is redundant

so here is the question: how to solve this redundancy?
I will get back here once i confirm whether or not removing system_local.h does not affect the code. Only if there are errors, is the redundancy question to be solved, else, it doesnt need to be solved.

I plan to comment out the
#include "system_local.h" line in both gp_timer.c and gp_timer.h
and then compile the code and check for errors.

I know that the code for gp_timer.h had a comment beside importing system_local.h for GP_TIMER_BASEaddress, still it's better to be safe than sorry.

okay, i have run the code.

make -j8 drivers/staging/media/atomisp/pci/system_local.o

there was one error, but it isn't related tp my code:

drivers/staging/media/atomisp/pci/system_global.h:47:10: fatal error: hive_isp_css_defs.h: No such file or directory
   47 | #include <hive_isp_css_defs.h>
      |          ^~~~~~~~~~~~~~~~~~~~~
compilation terminated.

i ran the make command in the master branch and this error showed up there too.

here it seems that someone imported this header using < > instead of " "... since they are in the same file.. they should be imported as " "
maybe i can submit that as a patch, but that's for later.
it's not a part of my patch.

Each patch should fix just 1 issue

now, back to task, i can go ahead and delete those lines directly.

I ran make -j8 and let it process

[27-03-26]

I sent the patch, and the following night, I got a mail from the Media CI bot:


# Test static:test-sparse  
drivers/staging/media/atomisp/pci/hive_isp_css_common/host/gp_timer.c:19:19: warning: symbol 'GP_TIMER_BASE' was not declared. Should it be static?

of course! how could i have forgotten this? I should have remembered this myself, I had used static for this very reason in my mini malloc.c series!

Functions or variables that are going to be used only within that file should be called static!

This is the link for the official rules for contributing the patch for media subsystem:
https://docs.kernel.org/driver-api/media/maintainer-entry-profile.html

This is something that they had mentioned

Also, please notice that we build the Kernel with:

make CF=-D__CHECK_ENDIAN__ CONFIG_DEBUG_SECTION_MISMATCH=y C=1 W=1 CHECK=check_script

Where the check script is:

#!/bin/bash
/devel/smatch/smatch -p=kernel $@ >&2
/devel/sparse/sparse $@ >&2

Be sure to not introduce new warnings on your patches without a very good reason.

I had no idea about this checking method. I will remember to check out the docs for that subsystem before working on a patch.

Now, I plan to fix this issue and send a v6

[27-06-26]
i added static as a property for the variable, to modify it's scope to stay only in the file and sent the patch.

[28-06-26]
So, I received a reply and I am in quite the pickle..

Andy Shevchenko replied:

Now you also may fix the multi-line comment style and amend the text.

/*
 * All timer registers are inter-twined, so having multiple base addresses
 * for different timers does not help.
 */

With that being fixed, you may add

Sakari Ailus replied:

Please don't move the defition here. There's a reason for keeping it in the
same location with the rest of the offsets. There's a lot to cleanup here
but what should be done is roughly:

- Make these constants macros (with IPU2_ or ATOMISP2_ prefix?) and move
  them into a separate header (perhaps with register definitions?).

- Remove my_env and make struct device (or maybe struct atomisp_device?) as
  a parameter for register access functions.

This may get a bit complicated due to the amount of cleanup needed so
having the hardware for testing would be rather essential.
.
.
.
> -/*GP TIMER , all timer registers are inter-twined,
> - * so, having multiple base addresses for
> - * different timers does not help*/
This comment could benefit from fixing, regarding both formatting and
language.

And this completely confused me on what to do. Since this small patch had just become way more complicated, and would even required hardware for testing.

I decided to mail my GSoC mentors to ask them advice on this issue, and after that, I realized:
My Mistake:
I had assumed that I had to mail the mentors for review for the first patch to ask them what changes to make, but didn't know that for each subsequent versions I had made, I should first mail my mentors first before sending it upstream. I had assumed that since these were just small fixes, I needed to just make them, and send them.

The biggest learning: Communication is very important. DO NOT ASSUME. If you don't know, ask explicitly. It will help much more before you land in a pickle due to miscommunications.

I feel so guilty for not realizing this before, (reviewing with mentors first), and making assumptions.. I will remember to communicate properly in the future.

At this point, I’m pausing to align with mentors before proceeding further. This experience taught me that communication is just as important as code in open source

Submitting My First Linux Kernel Patch While Applying for GSoC 2026 — The Real, Messy Process

moonlitpath — Mon, 23 Mar 2026 15:10:37 +0000

A short introduction about me:
Hey! I'm Anushka. I'm a UG college student, majoring in Information Technology, from India. I absolutely love learning about how systems work under the hood.

Note: This is not a tutorial, just my own devjournal documenting my learning process.

This patch was about fixing formatting issues given by checkpatch.pl

Steps to find an issue and submit a patch

cript to find files have formatting issues within drivers/staging

checkpatch.pl is a super useful script, found within the /scripts folder, that patches or code files for style violations and, in some cases, functional issues.
It categorizes issues into -

ERROR (strict, must fix)
WARNING (requires review)
CHECK (mild/stylistic) levels

script:

find ./drivers/staging/ -name '*.c' | xargs ./scripts/checkpatch.pl -f

script to check formatting within just 1 file

./scripts/checkpatch.pl --strict -f drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c

the output i got

./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c
--------------------------------------------------------------------------
ERROR: open brace '{' following function definitions go on the next line
#48: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:48:
+int
+sh_css_vf_downscale_log2(
+    const struct ia_css_frame_info *out_info,
+    const struct ia_css_frame_info *vf_info,
+    unsigned int *downscale_log2) {

WARNING: please, no spaces at the start of a line
#50: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:50:
+    const struct ia_css_frame_info *out_info,$

WARNING: please, no spaces at the start of a line
#51: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:51:
+    const struct ia_css_frame_info *vf_info,$

WARNING: please, no spaces at the start of a line
#52: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:52:
+    unsigned int *downscale_log2) {$

WARNING: Block comments should align the * on each line
#65: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:65:
+   /* downscale until width smaller than the viewfinder width. We don't
+   * test for the height since the vmem buffers only put restrictions on

ERROR: that open brace { should be on the previous line
#68: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:68:
+   while (out_width >= vf_info->res.width)
+   {

ERROR: open brace '{' following function definitions go on the next line
#83: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:83:
+static int
+configure_kernel(
+    const struct ia_css_binary_info *info,
+    const struct ia_css_frame_info *out_info,
+    const struct ia_css_frame_info *vf_info,
+    unsigned int *downscale_log2,
+    struct ia_css_vf_configuration *config) {

WARNING: please, no spaces at the start of a line
#85: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:85:
+    const struct ia_css_binary_info *info,$

WARNING: please, no spaces at the start of a line
#86: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:86:
+    const struct ia_css_frame_info *out_info,$

WARNING: please, no spaces at the start of a line
#87: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:87:
+    const struct ia_css_frame_info *vf_info,$

WARNING: please, no spaces at the start of a line
#88: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:88:
+    unsigned int *downscale_log2,$

WARNING: please, no spaces at the start of a line
#89: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:89:
+    struct ia_css_vf_configuration *config) {$

WARNING: please, no spaces at the start of a line
#109: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:109:
+    struct ia_css_vf_configuration *config,$

WARNING: please, no spaces at the start of a line
#110: FILE: ./drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c:110:
+    const struct ia_css_frame_info *vf_info)$

total: 3 errors, 11 warnings, 134 lines checked

My Mistake:

I saw multiple types of issues and fixed all of them, which turned out to be my first mistake. Thus, my patch was rejected by my mentor.

The issues I fixed were all of different types as you can see above.

One commit should fix only one type of issue.
Fix either whitespace issue, or braces issue. Don't fix all issues in one file.

I had also mailed my patch as a regular Gmail attachment, which was wrong. The Linux Kernel Community requires patches sent via git send-email, which preserves the patch formatting as raw plain text, regular email clients can corrupt whitespace and formatting
You can configure thunderbird to send mails in plain text, and send patches using git send-mail

So, I fixed only the brace placement issue for functions and while loop this time.

After fixing, you have to stage it

git add drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c

Then we commit the file

git commit -s

-s means signed by

inside git commit, write this message

title --- subsystem name and issue fixed
short description of issues fixed
signed off by

    staging: atomisp: vf_1.0: fix open brace placement

    Fix open brace placement on function definitions and control statements to comply with kernel coding style.

    Signed-off-by: Anushka Badhe <anushkabadhe@gmail.com>

now we make a patch

$ git format-patch -1

0001-staging-atomisp-vf_1.0-fix-open-brace-placement.patch

check the patch with checkpatch one last time

./scripts/checkpatch.pl --strict 0001-*.patch

after checking the patch, the next step is to mail the patch to the maintainers.

in order to find the maintainers of a file, there is a handy script called get-maintainer.pl

this is how i found maintainers for my file

./scripts/get_maintainer.pl -f drivers/staging/media/atomisp/pci/isp/kernels/vf/vf_1.0/ia_css_vf.host.c

note the name and mail of maintainers

to mail, this is the format:

git send-email --to=email1@gmail.com --cc=email2.gmail.com 0001-your-patch-name.patch

add all maintainers to --cc when you mail them

After I created my new patch that fixed just 1 issue cleanly and sent my patch to be reviewed by my mentors, it was approved by them. So, I sent it to the kernel community

Extra -- aka just me screaming my head off

[23-03-26 14:56:32]
OMG! My mentors gave me a go ahead with my new patch!! I am ACTUALLY submitting my first patch to the Community!!

[23-03-26 15:01:26]
THIS IS MY FIRST EMAIL TO THE COMMUNITY!!!! OMGGGGG

anu@laptop:~/kernel-dev/source/linux$ git send-email 0001-staging-atomisp-vf_1.0-fix-open-brace-placement.patch \
  --to=hansg@kernel.org \
  --to=mchehab@kernel.org \
  --to=gregkh@linuxfoundation.org \
  --cc=andy@kernel.org \
  --cc=sakari.ailus@linux.intel.com \
  --cc=linux-media@vger.kernel.org \
  --cc=linux-staging@lists.linux.dev
0001-staging-atomisp-vf_1.0-fix-open-brace-placement.patch

(mbox) Adding cc: Anushka Badhe <anushkabadhe@gmail.com> from line 'From: Anushka Badhe <anushkabadhe@gmail.com>'
(body) Adding cc: Anushka Badhe <anushkabadhe@gmail.com> from line 'Signed-off-by: Anushka Badhe <anushkabadhe@gmail.com>'

From: Anushka Badhe <anushkabadhe@gmail.com>
To: hansg@kernel.org,
    mchehab@kernel.org,
    gregkh@linuxfoundation.org
Cc: andy@kernel.org,
    sakari.ailus@linux.intel.com,
    linux-media@vger.kernel.org,
    linux-staging@lists.linux.dev,
    Anushka Badhe <anushkabadhe@gmail.com>
Subject: [PATCH] staging: atomisp: vf_1.0: fix open brace placement
Date: Mon, 23 Mar 2026 15:00:24 +0530
.
.
.
Send this email? ([y]es|[n]o|[e]dit|[q]uit|[a]ll): y
OK. Log says:
.
.

Result: OK

[23-03-26 15:09:10]
AAAAHHHHHHHHHHHH
safj;esfeas;gnaeg;jeagneianaerijgnlk;lnsdpkfpegflefm
I can see my patch on the lkml!!!!
https://lore.kernel.org/linux-media/20260323093024.38704-1-anushkabadhe@gmail.com/T/#Z2e.:..:20260323093024.38704-1-anushkabadhe::40gmail.com:1atomisp:pci:isp:kernels:vf:vf_1.0:ia_css_vf.host.c

[23-03-26 15:31:30]
I GOT A REPLY!!
Dan Carpenter replied to my patch!!
On Mon, Mar 23, 2026 at 03:00:24PM +0530, Anushka Badhe wrote:

Fix open brace placement on function definitions and control statements to comply with kernel coding style.

Line wrap your commit message at 74 characters. Also run your
patches through checkpatch.pl. (Ignore the space character
warning since that was there in the original code).

regards,
dan carpenter

Mistake
My commit message is over 73 characters...
this like was the issue..
Fix open brace placement on function definitions and control statements to comply with kernel coding style.

i have to split message so there are under 73 chars per line

I edited the commit message line and sent it again again
How I did that:

changing commit message:

git commit --amend

edit the commit message so it follows the commit message.

send the mail, replying to the message.
Find the patch in lore.kernel.org, and go to the reply button, you can see

[23-02-26 04:29:52]
OMG! OMGGGGGG! OMGGG!!!!

he approved it!!!!!!! He actually approved it!!!!!
OMGGGGGGGG!!!!!! AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAaaaaaaaaAAA!!!!!!!!!!!!

[16:50:20]
I got a reply from Andy Shevchenko

On Mon, Mar 23, 2026 at 03:51:04PM +0530, Anushka Badhe wrote:

> Fix open brace placement on function definitions and control statements
> to comply with kernel coding style.

...

>  sh_css_vf_downscale_log2(
>      const struct ia_css_frame_info *out_info,
>      const struct ia_css_frame_info *vf_info,
> -    unsigned int *downscale_log2) {
> +    unsigned int *downscale_log2)
> +{

The indentation of the entire function is broken and needs to be fixed.
And IIRC there were already 3+ patches on the same, so please try instead
helping with reviewing existing stream on AtomISP patches.

-- 
With Best Regards,
Andy Shevchenko

awwh, I feel a bit disappointed, but honestly I'm still very happy seeing my patch was acknowledged by the kernel community! It's such an honor!

After getting the reply, I checked [[lore.kernel.org]] under all categories and searched for my file ia_css_vf

and as Andy said.. there were 3-4 other submission like mine, fixing the exact same issue. -_-

Lesson Learned: Always check the lkml for similar patches in staging before starting working on that issue.

Ending Note:
Honestly, this experience was very very valuable, and I plan to submit a new patch soon, ofc after checking whether my issue was already fixed by someone else or not.

Optimizing Memory usage with mmap - Phase 6 Mini Malloc

moonlitpath — Sun, 22 Mar 2026 19:20:12 +0000

This is Phase 6 of creating a mini malloc! Here, I will implement mmap

Note:
The clues and guidance I mention below were given to me by an AI assistant, used purely to guide my understanding of concepts and syntax. The entire code is written by me, referencing the official glibc documentation throughout.
I'm mentioning this explicitly because I believe in being honest about the learning process.

The entire process and my code has been uploaded on my github account: [https://github.com/moonlitpath1/mini-malloc]

For large allocations, mmap is better than sbrk since while freeing, mmap block with munmap returns memory back to the kernel unlike sbrk blocks which stay in your heap forever.

To observe this in person, I created a simple test_threshold.c code that i traced with strace

#include<stdlib.h>
int main()
{
    void *ptr = malloc(256 * 1024); //256kb
    free(ptr);
    return 0;
}

Result:

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ gcc test_threshold.c -o out && strace -e trace=brk,mmap ./out 2>&1 | grep -E "brk|mmap"

--------- library loading -------

brk(NULL)                               = 0x555555559000
mmap(NULL, 8192, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7ffff7fbb000
mmap(NULL, 81463, PROT_READ, MAP_PRIVATE, 3, 0) = 0x7ffff7fa7000
mmap(NULL, 2170256, PROT_READ, MAP_PRIVATE|MAP_DENYWRITE, 3, 0) = 0x7ffff7c00000
mmap(0x7ffff7c28000, 1605632, PROT_READ|PROT_EXEC, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0x28000) = 0x7ffff7c28000
mmap(0x7ffff7db0000, 323584, PROT_READ, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0x1b0000) = 0x7ffff7db0000
mmap(0x7ffff7dff000, 24576, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_DENYWRITE, 3, 0x1fe000) = 0x7ffff7dff000
mmap(0x7ffff7e05000, 52624, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_FIXED|MAP_ANONYMOUS, -1, 0) = 0x7ffff7e05000
mmap(NULL, 12288, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7ffff7fa4000

---- glibc heap setup
brk(NULL)                               = 0x555555559000
brk(0x55555557a000)                     = 0x55555557a000



-----my allocation starts from here -----------

mmap(NULL, 266240, PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) = 0x7ffff7f63000

mmap maps appx 260KB memory, the extra 4KB is due to page size rounding. The OS only gives memory in 4KB page chunks.

The Threshold on the System

glibc's default MMAP_THRESHOLD starts at 128KB and is dynamic — it adjusts upward based on the largest freed mmap chunk.

#include <malloc.h>
#include <stdlib.h>

int main()
{
    void *p1 = malloc(64 * 1024);   // 64 KB
    malloc_stats();

    void *p2 = malloc(256 * 1024);  // 256 KB
    malloc_stats();

    free(p1);
    free(p2);
}

Output:

Arena 0:
system bytes     =     135168
in use bytes     =      66208
Total (incl. mmap):
system bytes     =     135168
in use bytes     =      66208
max mmap regions =          0
max mmap bytes   =          0

Arena 0:
system bytes     =     135168
in use bytes     =      66208
Total (incl. mmap):
system bytes     =     401408
in use bytes     =     332448
max mmap regions =          1
max mmap bytes   =     266240

In the first malloc(64)
Glibc requested for 132 KB, and allocated 66KB( extra allocator metadata) using malloc.
Since the requested allocation size is lesser than threshold
64 < 128
thus, we can see that mmap reigions are 0

In the second malloc(256)
Glibc uses mmap for allocation here, since the value is above threshold.
256 > 128

The concept:

For large allocations (above a threshold), sbrk is wasteful. mmap is better because freeing an mmap block with munmap actually returns memory to the OS — unlike sbrk blocks which stay in your heap forever.

Three clues for the implementation:

If size >= MMAP_THRESHOLD, call mmap(NULL, size + sizeof(struct block_meta), PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0) instead of sbrk. This asks the kernel to create a new anonymous private memory mapping of the requested size (plus metadata) with read/write permissions, placed at an address chosen by the kernel and not backed by any file. The mapping is separate from the heap and is typically page-aligned.
mmap'd blocks should NOT be added to your free list — they live outside the heap and get returned directly to the OS via munmap in free()
How does free() know if a pointer came from mmap vs sbrk? Clue: add a field to block_meta — int is_mmap — and check it in free()

Implementation

`Malloc` allocates when size > 128 KB

#define MMAP_THRESHOLD (128*1024)

void* malloc(size_t size)
{
    struct block_meta *block;
    if(block = find_free_block(size))
    {
        block->is_free = 0;
        if(block->size > sizeof(struct block_meta) + sizeof(size_t) + 16)
            split_block(block, size);
    }
    else
    {
        if(size >= MMAP_THRESHOLD)
        {
            block = mmap(NULL, size + sizeof(struct block_meta), PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0);
            if(block == MAP_FAILED) return NULL;
            block->is_mmap = 1;

            return block;
        }


        block = sbrk(0);
        //allocting space for user data, meta data and footer
            if( sbrk(size + sizeof(struct block_meta) + sizeof(size_t)) == (void *)-1 ) return NULL;
        block->is_mmap = 0;

        size_t *footer = (size_t*)((char*)(block+1) + size);
        *footer = size;


            //meta data struct would start at the heap top
            block->size = size;
            block->is_free=0;
            block->next=NULL;

            //adding to metadata linkedlist 
            if(tail == NULL)
            {
                    head = block;
                    tail = block;
            }
             else
            {
                tail->next = block;
                    tail = block;
            }

    }

    return (void*)(block+1);

}

Free function frees block using `munmap` if it was allocated with `mmap`

struct block_meta
{
    size_t size;
    int is_free;
    int is_mmap;
    struct block_meta *next;
} __attribute__((aligned(16)));

void free(void *ptr)
{  
    if(ptr == NULL) return;

    //ptr points to the user data
    //find the meta block and set is_free=1
    struct block_meta *curr_block = (struct block_meta*)ptr - 1;

    if(curr_block->is_mmap == 1) 
    {
        munmap(curr_block, curr_block->size + sizeof(struct block_meta) );
        return;
    }


    curr_block->is_free=1;

    //coalescing
    backward_coalesce(curr_block);
    forward_coalesce(curr_block);

}

Testing program

Created simple program: test_threshold.c

int main()
{
    void *ptr = malloc(128 * 1024);
    heap_dump();

    void *ptr2 = malloc(1);
    heap_dump();

    free(ptr);
    free(ptr2);

    return 0;
}

Output:

Block 1: | Free: 0 | Size: 131072 | MMAP: 1
Block 2: | Free: 0 | Size: 1024 | MMAP: 0

Block 1: | Free: 0 | Size: 131072 | MMAP: 1
Block 2: | Free: 0 | Size: 1024 | MMAP: 0
Block 3: | Free: 0 | Size: 1 | MMAP: 0

During my first allocation, 2 blocks were allocated.
The first block is from my program. I will explain Block2 later.

As expected,
Block 1, due to it's big size was allocated by mmap()
and Block 3, due to it's small size was allocated using sbrk()

The second block is a mystery though...
The second block was probably formed because of printf() that was used in my heap_dump() function creating a 1024 byte 1024 buffer.

To verify this, I added a printf(" ") statement before calling malloc to see if it becomes the first block.

and as expected:

 Block 1: | Free: 0 | Size: 1024 | MMAP: 0
Block 2: | Free: 0 | Size: 131072 | MMAP: 1

Block 1: | Free: 0 | Size: 1024 | MMAP: 0
Block 2: | Free: 0 | Size: 131072 | MMAP: 1
Block 3: | Free: 0 | Size: 1 | MMAP: 0

The first block is 1024 bytes now, which was allocated by printf's buffer.

Complete code

//mmap

#include<stdio.h>
#include<unistd.h>
#include<stddef.h>
#include<sys/mman.h>

#define MMAP_THRESHOLD (128*1024)

/**
* struct block_meta - metadata header for each allocated block 
* @size: size of user data reigion in bytes
* @is_free: nonzero if free, 0 if allocated 
* @next: pointer to the next metadata block in the list
 */
struct block_meta
{
    size_t size;
    int is_free;
    int is_mmap;
    struct block_meta *next;
} __attribute__((aligned(16)));

static struct block_meta *head = NULL;
static struct block_meta *tail = NULL;


/**
 * find_free_block - finds a free block large enough for allocation 
 * @size: size of user data
 * 
 * Performs a first-fit search over the block list starting at @head and 
 * returns the first free block whose size is greater than or equal to @size
 *
 * Return:
 * Pointer to a suitable free block on success, or NULL if no such block exists
*/
static struct block_meta* find_free_block(size_t size)
{
        //search if free block of enough size is available to reuse -- first fit
        struct block_meta *curr = head;
    while(curr != NULL)
        {
            if(curr->is_mmap) { curr = curr->next; continue; }
            if(curr->is_free==1 && curr->size >= size)
            {
                return curr;
            }
            curr = curr->next;
        }
    return NULL;
}


/**
 * split_block - splits a block into required size 
 * @block - pointer to free block header
 * @size - required size
 */

static void split_block(struct block_meta *block, size_t size)
{
    //block splitting
        // |      free     |   ---->  |   required_size   |   remainder   |

        struct block_meta *remainder = (struct block_meta*)((char*)(block + 1) + size + sizeof(size_t));
        // assigning meta data to new block
        remainder->size = block->size - size - sizeof(struct block_meta) - sizeof(size_t);
        remainder->is_free = 1;
        remainder->next = block->next;

    //editing footer
    size_t *footer = (size_t*)((char*)(remainder+1) + remainder->size);
    *footer = remainder->size;
        //editing free block's meta data
        block->size = size;
        block->next = remainder;
    footer = (size_t*)((char*)(block+1) + block->size);
    *footer = block->size;

    if(block == tail) 
        tail = remainder;
}



//foward coalescing
void forward_coalesce(struct block_meta *curr_block)
{
        //check if it's the last block in physical memory
        if((void*)((char*)(curr_block+1)+curr_block->size) >= sbrk(0)) return;

    struct block_meta *next_block = (struct block_meta*)((char*)(curr_block+1)+curr_block->size + sizeof(size_t));
        if(!next_block->is_free) return; 

        curr_block->size = curr_block->size + sizeof(size_t) + sizeof(struct block_meta) + next_block->size;
        curr_block->next = next_block->next;

    size_t *footer = (size_t*)((char*)(curr_block+1) + curr_block->size);
    *footer = curr_block->size;
}




//backward coalescing
void backward_coalesce(struct block_meta *curr_block)
{
    if(curr_block == head) return;

    size_t *footer = (size_t*)((char*)curr_block - sizeof(size_t));
    struct block_meta *prev_block = (struct block_meta*)((char*)footer - *footer - sizeof(struct block_meta));
    if(!prev_block->is_free) return;

    prev_block->size = prev_block->size + sizeof(size_t) + sizeof(struct block_meta) + curr_block->size;
    prev_block->next = curr_block->next;

    if(curr_block == tail) tail = prev_block;

    footer = (size_t*)((char*)(prev_block+1) + prev_block->size);
    *footer = prev_block->size;

}
/**
 * malloc - allocates heap memory 
 * @size: memory in bytes to be allocated
 *
 * Allocates memory block of at least @size bytes. If free block is available,
 * then the allocator reuses that, else the heap is extended using sbrk() and a new 
 * block is created.
 *
 * Returns: 
 * Pointer to the start of the memory block 
*/

void* malloc(size_t size)
{
    struct block_meta *block;
    if(block = find_free_block(size))
    {
        block->is_free = 0;
        if(block->size > sizeof(struct block_meta) + sizeof(size_t) + 16)
            split_block(block, size);
    }
    else
    {
        if(size >= MMAP_THRESHOLD)
        {
            block = mmap(NULL, size + sizeof(struct block_meta), PROT_READ|PROT_WRITE, MAP_PRIVATE|MAP_ANONYMOUS, -1, 0);
            if(block == MAP_FAILED) return NULL;
            block->is_mmap = 1;

            return block;
        }


        block = sbrk(0);
        //allocting space for user data, meta data and footer
            if( sbrk(size + sizeof(struct block_meta) + sizeof(size_t)) == (void *)-1 ) return NULL;
        block->is_mmap = 0;

        size_t *footer = (size_t*)((char*)(block+1) + size);
        *footer = size;


            //meta data struct would start at the heap top
            block->size = size;
            block->is_free=0;
            block->next=NULL;

            //adding to metadata linkedlist 
            if(tail == NULL)
            {
                    head = block;
                    tail = block;
            }
             else
            {
                tail->next = block;
                    tail = block;
            }

    }

    return (void*)(block+1);

}




/**
 *free
 *@ptr: pointer to memory location to be freed
 *returns: void
*/
void free(void *ptr)
{  
    if(ptr == NULL) return;

    //ptr points to the user data
    //find the meta block and set is_free=1
    struct block_meta *curr_block = (struct block_meta*)ptr - 1;

    if(curr_block->is_mmap == 1) 
    {
        munmap(curr_block, curr_block->size + sizeof(struct block_meta) );
        return;
    }


    curr_block->is_free=1;

    //coalescing
    backward_coalesce(curr_block);
    forward_coalesce(curr_block);

}


/*prints heap contents */
void heap_dump()
{
    struct block_meta *curr = head;
    int i=0;
    while(curr != NULL)
    {
        i++;
        printf("Block %d: | Free: %d | Size: %zu | MMAP: %d\n",i, curr->is_free, curr->size, curr->is_mmap); 
        curr = curr->next;
    }

}

And that's it! I am currently working on Phase 7: Bins, and will post it as soon as it's finished :)

Coalescing - Phase 5 Mini Malloc

moonlitpath — Sun, 22 Mar 2026 19:12:30 +0000

This is the fifth phase of malloc. Here, I have implemented block coalescing. This was very interesting and a fun phase. Block coalescing helps in reusing memory

Note:
The clues and guidance I mention below were given to me by an AI assistant, used purely to guide my understanding of concepts and syntax. The entire code is written by me, referencing the official glibc documentation throughout.
I'm mentioning this explicitly because I believe in being honest about the learning process.

The entire process and my code has been uploaded on my github account: [https://github.com/moonlitpath1/mini-malloc]

Clues:

This is the most intellectually satisfying phase. You're about to fix the opposite problem — **external fragmentation: adjacent free blocks that could be one big block but aren't.

[meta|FREE 64][meta|FREE 128][meta|USED 32]

If someone asks for malloc(100) — your find_free_block skips both free blocks since neither is ≥ 100 alone. But together they're 192 bytes. Coalescing **merges adjacent free blocks* when freeing.*

The key insight to think about before writing any code:

When free(ptr) is called and you mark a block free — how do you find the block that comes **immediately after* it in memory (not in the linked list, but physically adjacent)? You know the block's address and its size. Where does the next block's header start?*

The Implication for Coalescing

Since the heap is flat and you control all structure, you can **walk forward* from any block by doing address + sizeof(meta) + size and you'll land precisely on the next block's header — guaranteed.*

The only edge case: what if you walk past the END of the heap? What value would next_physical have then, and how do you detect it?

📚 Flow:

In free() function:-
1) use existing logic to find *meta_curr
2) check if it's the last block in physical memory
(char*)(meta_curr+1) + meta_curr->size >= sbrk(0)
3) y -> check if next_block in physical memory is free
4) y -> update meta_curr->size = meta_curr->size + sizeof(*meta_curr) + next_block->size
5) update meta_curr->is_free
6) update meta_curr->next = next_block->next

Implementation and results:

implemented the above logic

void free(void *ptr)
{
    if(ptr == NULL) return;

    //ptr points to the user data
    //find the meta block and set is_free=1
    struct block_meta *curr_block = (struct block_meta*)ptr - 1;
    curr_block->is_free=1;

    //coalescing
    //check if it's the last block in physical memory   
    if((void*)((char*)(curr_block+1)+curr_block->size) >= sbrk(0)) return;
    struct block_meta *next_block = (struct block_meta*)((char*)(curr_block+1)+curr_block->size);
    if(next_block->is_free == 0) return;

    curr_block->size = curr_block->size + sizeof(struct block_meta) + next_block->size;
    curr_block->next = next_block->next;
}


/*prints heap contents */
void heap_dump()
{
    struct block_meta *curr = head;
    int i=0;
    while(curr != NULL)
    {
        i++;
        printf("Block %d: | Free: %d | Size: %zu\n",i, curr->is_free, curr->size); 
        curr = curr->next;
    }

}

Tested if the code works for ls

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ gcc -shared -fPIC -o malloc_v5.so malloc_v5.c && LD_PRELOAD=./malloc_v5.so ls
'\'                    images         malloc_v3.so   og_malloc.c
 dump                  malloc_v1.c    malloc_v4.c    out
 faulty_heap_spy.c     malloc_v1.so   malloc_v4.so   test_coalescing.c
 git_push.sh           malloc_v2.c    malloc_v5.c    test_fragmentation.c
 heap_spy.c            malloc_v2.so   malloc_v5.so   test_split.c
 heap_spy_modified.c   malloc_v3.c    notes

This was my C code test_coalescing.c used to test the allocator

#include<stdio.h>
#include<stdlib.h>
void heap_dump(void);
int main()
{
    void *a, *b, *c, *d;
    a = malloc(32);
    b = malloc(64);
    c = malloc(64); 

    heap_dump();

    free(b);    
    free(a);

    heap_dump();


    return 0;
}

Built and compiled the code:

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ gcc test_coalescing.c ./malloc_v5.so -o out

Ran program

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ LD_PRELOAD=./malloc_v5.so ./out
Block 1: | Free: 0 | Size: 32
Block 2: | Free: 0 | Size: 64
Block 3: | Free: 0 | Size: 64
Block 4: | Free: 0 | Size: 1024

Block 1: | Free: 1 | Size: 128
Block 2: | Free: 0 | Size: 64
Block 3: | Free: 0 | Size: 1024

As we can see, after freeing a and b, there are only 3 blocks in total. This means that Coalesing was successful.

Issues

In the above code, I have implemented only forward coalescing. Backward Coalescing is also necessary.
In the next section, I shall implement that.

I tested this using test_coalescing.c

        void *a, *b, *c, *d;
        a = malloc(32);
        b = malloc(64);
        c = malloc(64);
        heap_dump();
        free(a);
        free(b);
        heap_dump();
        return 0;

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ LD_PRELOAD=./malloc_v5.so ./out
Block 1: | Free: 0 | Size: 32
Block 2: | Free: 0 | Size: 64
Block 3: | Free: 0 | Size: 64
Block 4: | Free: 0 | Size: 1024

Block 1: | Free: 1 | Size: 32
Block 2: | Free: 1 | Size: 64
Block 3: | Free: 0 | Size: 64
Block 4: | Free: 0 | Size: 1024

We can see that backward coalescing isnt happening, and 4 blocks remained in part 2

Extra:
What is Block 4: | Free: 0 | Size: 1024
This memory comes from the startup allocations that run before main()

Backward Coalescing involves, going back and checking if the previous block is free, and then merging the two blocks using similar logic as before.

Checking the previous block's availability would require the size of the previous block to reach to the meta data of the prev block.

At this point I went and read glibc's actual malloc.c source to understand how they solve this.

Reading glibc's `malloc.c`

glibc's malloc contains a clever trick to identify whether the previous block is free or not.
All blocks are aligned, so each block's size is always a multiple of 8 or 16. This means that in binary the last 3 digits are always 0.
Eg. size = 96 → binary: 01100000

So, since the last bit is always 0, glibc decides to use it to store something useful in it.
Thus, the last 0 of the current chunk's size field stores whether the previous block is free (0) or in use (1).

What does this mean?

This is how glibc's memory allocation looks like:

chunk A:
[ prev_size (8 bytes) | size+flags (8 bytes) | user data... ]

chunk B (immediately after A):
[ prev_size (8 bytes) | size+flags (8 bytes) | user data... ]

there is no footer here that stores the current chunk's size. instead, the prev chunk's size is stored in the next chunk as a variable (prev_size).
And this is the variable whose last bit we manipulate for storing whether the previous chunk is free or not.

This is really clever as it not only stores a lot of space, it also increases simplicity.

glibc maintains a macro PREV_INUSE

#define PREV_INUSE 0x1

When glibc wants to check if the previous chunk is in use:

if (chunk->size & PREV_INUSE)   // AND operation

When it wants to set it:

chunk->size |= PREV_INUSE;      // OR operation

When it wants to clear it:

chunk->size &= ~PREV_INUSE;     // AND + NOT operation

In this manner, glibc cleverly maintains whether the previous block is free or not, using bit manipulation.

I definitely plan to implement glibc's logic in the future, however, for now, I want to keep it simple. Baby steps.

Footer Logic

For my current program, I am going to implement a simple footer which will maintain the current block's size.

So, if I want to go to the previous block, I can calculate the prev block's footer location, see it's size and calculate location of the previous block's meta header.

[-A header | A user data | A footer=32-] [-B header | B user data | B footer=64-]

current position: B user data
to go to: A header

Version 1 of backwards coalesce

void backward_coalesce(struct block_meta *curr_block)
{
        if((struct block_meta*)curr_block == head) return;

        size_t *prev_footer = (size_t*)((char*)curr_block - sizeof(size_t));
        struct block_meta *prev_block = (struct block_meta*)((char*)prev_footer - *prev_footer - sizeof(struct block_meta));
        if(!prev_block->is_free) return;

        prev_block->size = prev_block->size + sizeof(struct block_meta) + curr_block->size;
        prev_block->next = curr_block->next;
}

There is segmentation fault here..

Clues I got:
Clue 1: You maintain two global pointers about the list. Your function updates one of them in the merge. What about the other one — what happens if curr_block happens to be at the very end of the list?

Clue 2: After merging, future backward_coalesce calls on blocks that come AFTER curr_block will need to read something to find their previous block. Is that something still accurate after your merge? 🔨

However, after fixing those bugs, my code still wont compile. After carefully going through the code, I realized that I had not considered the space taken by footer (the new addition) in many other places throughout the code, such as block splitting and new block creation.

Upon fixing the issues, the code was successfully compiled for both cases!
Forward as well as backward

Same test_coalescing.c code
b freed before a

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ # forward coaslescing
LD_PRELOAD=./malloc_v5.so ./out
Block 1: | Free: 0 | Size: 32
Block 2: | Free: 0 | Size: 64
Block 3: | Free: 0 | Size: 64
Block 4: | Free: 0 | Size: 1024

Block 1: | Free: 1 | Size: 136
Block 2: | Free: 0 | Size: 64
Block 3: | Free: 0 | Size: 1024

test_coalescing.ccode where a is freed before b

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ # backward coaslescing
LD_PRELOAD=./malloc_v5.so ./out
Block 1: | Free: 0 | Size: 32
Block 2: | Free: 0 | Size: 64
Block 3: | Free: 0 | Size: 64
Block 4: | Free: 0 | Size: 1024

Block 1: | Free: 1 | Size: 136
Block 2: | Free: 0 | Size: 64
Block 3: | Free: 0 | Size: 1024

Full Code:

//coalescing
#include<stdio.h>
#include<unistd.h>
#include<stddef.h>

/**
* struct block_meta - metadata header for each allocated block 
* @size: size of user data reigion in bytes
* @is_free: nonzero if free, 0 if allocated 
* @next: pointer to the next metadata block in the list
 */
struct block_meta
{
    size_t size;
    int is_free;
    struct block_meta *next;
} __attribute__((aligned(16)));

static struct block_meta *head = NULL;
static struct block_meta *tail = NULL;


/**
 * find_free_block - finds a free block large enough for allocation 
 * @size: size of user data
 * 
 * Performs a first-fit search over the block list starting at @head and 
 * returns the first free block whose size is greater than or equal to @size
 *
 * Return:
 * Pointer to a suitable free block on success, or NULL if no such block exists
*/
static struct block_meta* find_free_block(size_t size)
{
        //search if free block of enough size is available to reuse -- first fit
        struct block_meta *curr = head;
    while(curr != NULL)
        {
        if(curr->is_free==1 && curr->size >= size)
                {
                       return curr;
                }
                curr = curr->next;
        }
    return NULL;
}


/**
 * split_block - splits a block into required size 
 * @block - pointer to free block header
 * @size - required size
 */

static void split_block(struct block_meta *block, size_t size)
{
    //block splitting
        // |      free     |   ---->  |   required_size   |   remainder   |

        struct block_meta *remainder = (struct block_meta*)((char*)(block + 1) + size + sizeof(size_t));
        // assigning meta data to new block
        remainder->size = block->size - size - sizeof(struct block_meta) - sizeof(size_t);
        remainder->is_free = 1;
        remainder->next = block->next;

    //editing footer
    size_t *footer = (size_t*)((char*)(remainder+1) + remainder->size);
    *footer = remainder->size;
        //editing free block's meta data
        block->size = size;
        block->next = remainder;
    footer = (size_t*)((char*)(block+1) + block->size);
    *footer = block->size;

    if(block == tail) 
        tail = remainder;
}



//foward coalescing
void forward_coalesce(struct block_meta *curr_block)
{
        //check if it's the last block in physical memory
        if((void*)((char*)(curr_block+1)+curr_block->size) >= sbrk(0)) return;

    struct block_meta *next_block = (struct block_meta*)((char*)(curr_block+1)+curr_block->size + sizeof(size_t));
        if(!next_block->is_free) return; 

        curr_block->size = curr_block->size + sizeof(size_t) + sizeof(struct block_meta) + next_block->size;
        curr_block->next = next_block->next;

    size_t *footer = (size_t*)((char*)(curr_block+1) + curr_block->size);
    *footer = curr_block->size;
}




//backward coalescing
void backward_coalesce(struct block_meta *curr_block)
{
    if(curr_block == head) return;

    size_t *footer = (size_t*)((char*)curr_block - sizeof(size_t));
    struct block_meta *prev_block = (struct block_meta*)((char*)footer - *footer - sizeof(struct block_meta));
    if(!prev_block->is_free) return;

    prev_block->size = prev_block->size + sizeof(size_t) + sizeof(struct block_meta) + curr_block->size;
    prev_block->next = curr_block->next;

    if(curr_block == tail) tail = prev_block;

    footer = (size_t*)((char*)(prev_block+1) + prev_block->size);
    *footer = prev_block->size;

}
/**
 * malloc - allocates heap memory 
 * @size: memory in bytes to be allocated
 *
 * Allocates memory block of at least @size bytes. If free block is available,
 * then the allocator reuses that, else the heap is extended using sbrk() and a new 
 * block is created.
 *
 * Returns: 
 * Pointer to the start of the memory block 
*/

void* malloc(size_t size)
{
    struct block_meta *block;
    if(block = find_free_block(size))
    {
        block->is_free = 0;
        if(block->size > sizeof(struct block_meta) + 1)
            split_block(block, size);
    }
    else
    {
        block = sbrk(0);
        //allocting space for user data, meta data and footer
            if( sbrk(size + sizeof(struct block_meta) + sizeof(size_t)) == (void *)-1 ) return NULL;

            //meta data struct would start at the heap top
            block->size = size;
            block->is_free=0;
            block->next=NULL;


            //adding to metadata linkedlist 
            if(tail == NULL)
            {
                    head = block;
                    tail = block;
            }
             else
            {
                tail->next = block;
                    tail = block;
            }


        size_t *footer = (size_t*)((char*)(block+1) + size);
        *footer = size;

    }

    return (void*)(block+1);

}




/**
 *free
 *@ptr: pointer to memory location to be freed
 *returns: void
*/
void free(void *ptr)
{  
    if(ptr == NULL) return;

    //ptr points to the user data
    //find the meta block and set is_free=1
    struct block_meta *curr_block = (struct block_meta*)ptr - 1;
    curr_block->is_free=1;

    //coalescing
    //Backward runs first — if we forward-coalesced first and merged curr_block into its next, we'd lose the curr_block pointer that backward_coalesce needs
    backward_coalesce(curr_block);
    forward_coalesce(curr_block);

}


/*prints heap contents */
void heap_dump()
{
    struct block_meta *curr = head;
    int i=0;
    while(curr != NULL)
    {
        i++;
        printf("Block %d: | Free: %d | Size: %zu\n",i, curr->is_free, curr->size); 
        curr = curr->next;
    }

}

This marks the completion of phase 5! Phase 6 will be posted soon!

Block Splitting - Phase 4 Mini Malloc

moonlitpath — Sun, 22 Mar 2026 17:12:22 +0000

This is Phase 4 of my journey. Here, I will implement Block Splitting to reduce memory wastage.

Note:
The clues and guidance I mention below were given to me by an AI assistant, used purely to guide my understanding of concepts and syntax. The entire code is written by me, referencing the official glibc documentation throughout.
I'm mentioning this explicitly because I believe in being honest about the learning process.

The entire process and my code has been uploaded on my github account: [https://github.com/moonlitpath1/mini-malloc]

Clues

The one insight for Phase 4: when find_free_block returns a block of say 200 bytes but you only need 64 — instead of handing over all 200, cut it in two:

BEFORE split:
[meta: size=200, free=1 | ....200 bytes..........]

AFTER split:
[meta: size=64, free=0 | ..64 bytes..][meta: size=104, free=1 | ...104 bytes...]

Clue 1: The second block's meta header goes at: (char*)(block + 1) + size — right after the user data of the first block. What type do you cast that to?

Clue 2: After splitting, the first block's next should point to the new second block, and the second block's next should point to what the first block's next was originally.

Clue 3: Only split if there's enough room — you need at least size + sizeof(struct block_meta) + 1 bytes in the free block, otherwise there's no point.*
*Go! 🔨

My understanding of the clue and planning

Version 1

First, I wrote the logic directly in the malloc() function.

if (free_block->size == size)
    return (void *)(free_block + 1); 👾👾//hadn't changed value of is_free
else
{
    // block splitting

    struct block_meta *new =
        (struct block_meta *)((char *)(free_block + 1) + size);

    // assigning meta data to new block
    new->size = free_block->size - size;  👾👾//forgot to consider size of meta block (look in diagram)
    new->is_free = 1; 
    new->next = free_block->next;

    // editing free block's meta data
    free_block->size = size;
    free_block->is_free = 0;
    free_block->next = new;

    return (void *)((char *)(free_block + 1));
}

Issues here:

malloc() became very complex. -- i should create a helper function for it
note that bugs are highlighted in the code by 👾👾

Extra:
I referred to the kernel coding style and learnt this rule:

The maximum length of a function is inversely proportional to its complexity. Use helper functions with descriptive names when a less-than-gifted first-year student might not understand what the function is about.

This means that my malloc() function which is complex should be short and crisp. helper functions should be used by me to make my code more readable.

So, I decided to improve my code.

Version 2

Created a new helper function split_block() and decided to add the static keyword to my helper functions, to ensure they are private to my file.

static void split_block(struct block_meta *block, size_t size)
{
    //block splitting
        // |      free     |   ---->  |   size   |   new   |

        struct block_meta *remainder = (struct block_meta*)((char*)(block + 1) + size);
        // assigning meta data to new block
        remainder->size = block->size - size - sizeof(struct block_meta);   👾👾//BUG
        remainder->is_free = 1;
        remainder->next = block->next;

        //editing free block's meta data
        block->size = size;
        block->next = remainder;

    if(block == tail) 
    {
            tail->next = remainder; 
        tail = remainder;
    }
}

void* malloc(size_t size)
{
    //search if free block of enough size is available to reuse -- first fit 
    struct block_meta *free_block = find_free_block(size);
    if(free_block)
    {

        free_block->is_free = 0;
        if(free_block->size == size)    
            return (void*)(free_block+1);   

        else
        {
            split_block(free_block, size);
            return (void*)((char*)(free_block+1));
        }   
    }

    .
    .
    .
}

This code has a major BUG that i had failed to notice:
size_t Underflow

remainder->size = block->size - size - sizeof(struct block_meta);

size_t is unsigned. this means that if the result is negative.. it underflows.

for example:

block->size = 65
size = 64
sizeof(meta)= 32

65 - 64 - 32 = -31 ← mathematically
But since size_t is unassigned, -31 wraps to 18446744073709551585 which is huge!
remainder->size is set to that! and so my allocator tries to write that to memory 👾👾

So, it is crucial to check if there's enough room to split before calling split_block.

    if(free_block)
    {

        free_block->is_free = 0;
        if(free_block->size == size)    
            return (void*)(free_block+1);   

        else if(free_block->size >= size + sizeof(struct block_meta) + 1)
        {
            split_block(free_block, size);
            return (void*)((char*)(free_block+1));
        }   
    }

this fixed the segmentation fault.

Full code:

//block splitting

#include<unistd.h>
#include<stddef.h>

/**
* struct block_meta - metadata header for each allocated block 
* @size: size of user data region in bytes
* @is_free: nonzero if free, 0 if allocated 
* @next: pointer to the next metadata block in the list
 */
struct block_meta
{
    size_t size;
    int is_free;
    struct block_meta *next;
} __attribute__((aligned(16)));

static struct block_meta *head = NULL;
static struct block_meta *tail = NULL;



/**
 * find_free_block - finds a free block large enough for allocation 
 * @size: size of user data
 * 
 * Performs a first-fit search over the block list starting at @head and 
 * returns the first free block whose size is greater than or equal to @size
 *
 * Return:
 * Pointer to a suitable free block on success, or NULL if no such block exists
*/
static struct block_meta* find_free_block(size_t size)
{
        //search if free block of enough size is available to reuse -- first fit
        struct block_meta *curr = head;
    while(curr != NULL)
        {
        if(curr->is_free==1 && curr->size >= size)
                {
                       return curr;
                }
                curr = curr->next;
        }
    return NULL;
}


/**
 * split_block - splits a block into required size 
 * @block - pointer to free block header
 * @size - required size
 */

static void split_block(struct block_meta *block, size_t size)
{
    //block splitting
        // |      free     |   ---->  |   size   |   new   |

        struct block_meta *remainder = (struct block_meta*)((char*)(block + 1) + size);
        // assigning meta data to new block
        remainder->size = block->size - size - sizeof(struct block_meta);
        remainder->is_free = 1;
        remainder->next = block->next;

        //editing free block's meta data
        block->size = size;
        block->next = remainder;

    if(block == tail) 
        tail = remainder;
}




/**
 * malloc - allocates heap memory 
 * @size: memory in bytes to be allocated
 *
 * Allocates memory block of at least @size bytes. If free block is available,
 * then the allocator reuses that, else the heap is extended using sbrk() and a new 
 * block is created.
 *
 * Returns: 
 * Pointer to the start of the memory block 
*/

void* malloc(size_t size)
{
    //search if free block of enough size is available to reuse -- first fit 
    struct block_meta *free_block = find_free_block(size);
    if(free_block)
    {

        free_block->is_free = 0;
        if(free_block->size == size)    
            return (void*)(free_block+1);   

        else if(free_block->size >= size + sizeof(struct block_meta) + 1)
        {
            split_block(free_block, size);
            return (void*)((char*)(free_block+1));
        }   
    }


    //getting top of the heap
    void *top = sbrk(0);

    //allocting space for user data and meta data
    if( sbrk(size + sizeof(struct block_meta) ) == (void *)-1 ) return NULL;

    //meta data struct would start at the heap top
    struct block_meta *meta_data = (struct block_meta*)top;
    meta_data->size = size;
    meta_data->is_free=0;
    meta_data->next=NULL;

    //adding to metadata linkedlist 
    if(tail == NULL)
    {
        head = meta_data;
        tail=meta_data;
    }
    else
    {
        tail->next = meta_data;
        tail=meta_data;
    }

    //userdata memory starts after metadata
    top = (char*)top+sizeof(*meta_data);
    return top;
}






/**
 *free
 *@ptr: pointer to memory location to be freed
 *returns: void
*/
void free(void *ptr)
{
    if(ptr == NULL) return;

    //ptr points to the user data
    //find the meta block and set is_free=1
    struct block_meta *meta = (struct block_meta*)ptr - 1;
    meta->is_free=1;    
}

i tested it with this code

//@laptop:~/anu/programming/systems_progg/mini-malloc$ cat test_split.c 

#include <stdio.h>
#include <stdlib.h>

int main() {
    void *a = malloc(200);  
    free(a);               

    void *b = malloc(64);   

    return 0;
}

and it works.

 anu@laptop:~/anu/programming/systems_progg/mini-malloc$ LD_PRELOAD=./malloc_v4.so strace -e trace=brk ./out 2>&1
brk(NULL)                               = 0x555555559000
brk(NULL)                               = 0x555555559000
brk(0x5555555590e8)                     = 0x5555555590e8
+++ exited with 0 +++

Note: in this version, if a free block exists but is too small to split and not an exact match, malloc falls through and allocates a new block anyway, wasting the found block. This is a known limitation to fix in a future phase.

Implementing free - Phase 3 Mini Malloc

moonlitpath — Sun, 22 Mar 2026 16:56:20 +0000

This is the third phase. Here, I will write the free logic.
This code is written in the file malloc_v3.c

Note:
The clues and guidance that I mention below were given to me by an AI assistant, used purely to guide my understanding of concepts and syntax. The entire code is written by me, referencing the official glibc documentation throughout.
I'm mentioning this explicitly because I believe in being honest about the learning process.

The entire process and my code has been uploaded on my github account: [https://github.com/moonlitpath1/mini-malloc]

Clues

3.1 — Make free() Actually Do Something

Right now free() ignores its argument completely. It needs to do one thing: find the meta block for that pointer and set is_free = 1.

You already know how to go from user pointer → meta block. You did it in reverse in Phase 2.

malloc() returned this:   [ meta | user data ]
                                   ^
                          caller holds this ptr

free() receives that ptr → go back to meta → set is_free = 1

**Clue:* If ptr is typed as struct block_meta *, then ptr - 1 gives you the meta block. But ptr comes in as void * — what do you cast it to first?*

Implement this and move on.

3.2 — Make malloc() Search Before Asking OS

Right now your malloc() always calls sbrk. It needs a new first step: **walk the list looking for a free block big enough to reuse.**

This is called **first-fit* — grab the first free block where is_free == 1 AND size >= requested_size.*

malloc(80) is called →
  walk list from head:
    block 1: is_free=0 → skip
    block 2: is_free=1, size=32 → too small, skip
    block 3: is_free=1, size=200 → fits! mark is_free=0, return it
  if nothing found → sbrk as before

Three clues:

Write a helper find_free_block(size_t size) that returns a `struct block_meta or NULL`*
Inside it, loop from head while curr != NULL, checking both conditions
Back in malloc(): if the helper returns non-NULL, mark that block is_free = 0 and return its user pointer — NO sbrk needed

First-fit vs Best-fit — Pick One

First-fit	Best-fit
Strategy	First block big enough	Smallest block that fits
Speed	Fast — stops at first match	Slow — must scan entire list
Fragmentation	Leaves large blocks intact	Leaves many tiny unusable scraps

Use first-fit. It's simpler and actually performs better in practice. glibc's unsorted bin is essentially first-fit too.

Build both halves, then inject into ls again. If it still works, your free() is now real. Come back and we'll run Experiment 3.1 to watch fragmentation happen live. 🔨

My Code

I implemented the free() code, adding feature to reuse memory that has been freed (is_free = 1 ).

Notice that in the below code, I have done:

return (void*)(free_block+1);

why "free_block+1"?
--> this uses the concept of pointer arithmetic. The pointer is moved forward by the sizeof(free_block) number of spaces, landing exactly at user data.

// in v2, we assigned metadata headers
//we will give free() some work to do here

#include<unistd.h>
#include<stddef.h>

/**
* struct block_meta - metadata header for each allocated block 
* @size: size of user data reigion in bytes
* @is_free: nonzero if free, 0 if allocated 
* @next: pointer to the next metadata block in the list
 */
struct block_meta
{
    size_t size;
    int is_free;
    struct block_meta *next;
} __attribute__((aligned(16)));

struct block_meta *head = NULL;
struct block_meta *tail = NULL;

/**
 * find_free_block - finds a free block large enough for allocation 
 * @size: size of user data
 * 
 * Performs a first-fit search over the block list starting at @head and 
 * returns the first free block whose size is greater than or equal to @size
 *
 * Return:
 * Pointer to a suitable free block on success, or NULL if no such block exists
*/
struct block_meta* find_free_block(size_t size)
{
        //search if free block of enough size is available to reuse -- first fit
        struct block_meta *curr = head;
    while(curr != NULL)
        {
        if(curr->is_free==1 && curr->size >= size)
                {
                       return curr;
                }
                curr = curr->next;
        }
    return NULL;
}

/**
 * malloc - allocates heap memory 
 * @size: memory in bytes to be allocated
 *
 * Allocates memory block of at least @size bytes. If free block is available,
 * then the allocator reuses that, else the heap is extended using sbrk() and a new 
 * block is created.
 *
 * Returns: 
 * Pointer to the start of the memory block 
*/

void* malloc(size_t size)
{
    //search if free block of enough size is available to reuse -- first fit 
    struct block_meta *free_block = find_free_block(size);
    if(free_block)
    {
        free_block->is_free=0;  
        return (void*)(free_block+1); 
    }


    //getting top of the heap
    void *top = sbrk(0);

    //allocting space for user data and meta data
    if( sbrk(size + sizeof(struct block_meta) ) == (void *)-1 ) return NULL;

    //meta data struct would start at the heap top
    struct block_meta *meta_data = (struct block_meta*)top;
    meta_data->size = size;
    meta_data->is_free=0;
    meta_data->next=NULL;

    //adding to metadata linkedlist 
    if(tail == NULL)
    {
        head = meta_data;
        tail=meta_data;
    }
    else
    {
        tail->next = meta_data;
        tail=meta_data;
    }

    //userdata memory starts after metadata
    top = (char*)top+sizeof(*meta_data);
    return top;
}

void free(void *ptr)
{
    if(ptr == NULL) return;

    //ptr points to the user data
    //find the meta block and set is_free=1
    struct block_meta *meta = (struct block_meta*)ptr - 1;
    meta->is_free=1;    
}

Output:
And the code works!

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ gcc -shared -fPIC -o malloc_v3.so malloc_v3.c && LD_PRELOAD=./malloc_v3.so ls
'\'                  heap_spy.c            malloc_v1.so   malloc_v3.c    og_malloc.c
 faulty_heap_spy.c   heap_spy_modified.c   malloc_v2.c    malloc_v3.so   out
 git_push.sh         malloc_v1.c           malloc_v2.so   notes

Issue: Block Fragmentation.

Memory blocks in free space that are too small can't be reused.

To experience this, I wrote a simple code:

#include <stdio.h>
#include <stdlib.h>

int main() {
    void *ptrs[10];

    // allocating 10 blocks of 32 bytes
    for(int i = 0; i < 10; i++)
        ptrs[i] = malloc(32);

    // free only the even-indexed ones
    for(int i = 0; i < 10; i += 2)
        free(ptrs[i]);

    //allocate 64 bytes... will it create new block or reuse??
    void *big = malloc(64);

    return 0;
}

I ran this code using my malloc and traced it with strace

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ gcc test_fragmentation.c -o out LD_PRELOAD=./malloc_v3.so strace -e trace=brk ./out 2>&1 | grep brk

brk(NULL)                               = 0x555555559000    
brk(NULL)                               = 0x555555559000    
brk(0x555555559040)                     = 0x555555559040  ← malloc(32)
brk(0x555555559080)                     = 0x555555559080  ← malloc(32)
brk(0x5555555590c0)                     = 0x5555555590c0  ← malloc(32)
brk(0x555555559100)                     = 0x555555559100  ← malloc(32)
brk(0x555555559140)                     = 0x555555559140  ← malloc(32)
brk(0x555555559180)                     = 0x555555559180  ← malloc(32)
brk(0x5555555591c0)                     = 0x5555555591c0  ← malloc(32)
brk(0x555555559200)                     = 0x555555559200  ← malloc(32)
brk(0x555555559240)                     = 0x555555559240  ← malloc(32)
brk(0x555555559280)                     = 0x555555559280  ← malloc(32)

brk(0x5555555592e0)                     = 0x5555555592e0  ← malloc(64)⚠️

As expected, for allocating 64 bytes, malloc() could not reuse the memory of 32 bytes, since they were all fragmented, and had to create a new block instead

Diagram

+----+----+----+----+----+----+----+----+----+----+--------+
| ✅ | A  | ✅ | A  | ✅ | A  | ✅ | A  | ✅ | A  |  64B   |
|32B |32B |32B |32B |32B |32B |32B |32B |32B |32B |  NEW   |
+----+----+----+----+----+----+----+----+----+----+--------+



✅ = freed (is_free=1), A = allocated (is_free=0)

This is an issue and will be fixed in the future phases.

Metadata header - Phase 2 Mini Malloc

moonlitpath — Sun, 22 Mar 2026 13:58:35 +0000

This is Phase 2 of the project -- adding a header that stores info about the user block

The C file created here is called malloc_v2.c

Note:
The clues I mention below were given to me by an AI assistant, used purely to guide my understanding of concepts and syntax. The entire code is written by me, referencing the official glibc documentation throughout.
I'm mentioning this explicitly because I believe in being honest about the learning process.

The entire process and my code has been uploaded to my github account:
[https://github.com/moonlitpath1/mini-malloc]

Clues

The jump from v1 to v2 is **one new concept: a struct hidden just before the pointer you return.

Your v1 returned raw memory with zero metadata. v2 will secretly store a small header before the user's data. That header is what will eventually let free() do real work.

Here's the shape of the struct you need to define — fill in the field types yourself:

struct block_meta {
    _______ size;      // how big is this block?
    _______ is_free;   // is this block available to reuse?
    _______ *next;     // pointer to the next block in the list
};

The key question to think about: if this struct sits before the user data in memory, and your malloc() needs to return the address of the user data (not the struct) — what arithmetic do you do on the pointer that sbrk() gives you before returning it?

What I learnt:

Every time malloc(N) is called, you carve this out of the heap

  ┌─────────────────────┬──────────────────────────────┐
  │     block_meta      │        user data             │
  │  size | free | next │  ← N bytes the caller uses   │
  └─────────────────────┴──────────────────────────────┘
  ^                     ^
  sbrk() gives you      THIS is what malloc() returns
  this address          (this is what you called *top)

Use of *next:
Each meta-block's *next points to the next meta-block's address

aka, if you call 3 malloc()s in your code,
A linked list of 3 nodes would be formed by the meta-blocks.

This is used to reuse memory. For example, if you have freed a block of 80 bytes, then it can be reused by the next code. Just check if is_free for each node.

you need 1 global variable here that will act as the head of the LL, and one as tail
struct block_meta *head = NULL;
struct block_meta *tail = NULL;

My first attempt:

// in v1 we returned raw memory and 0 metadata 
// v2 will store a small header before user data -- this will help free()

#include<unistd.h>
#include<stddef.h>

struct block_meta
{
    size_t size;
    int is_free;
    struct block_meta *next;
};

struct block_meta *head = NULL;
struct block_meta *tail = NULL;

void* malloc(size_t size)
{
    //getting top of the heap
    void *top = sbrk(0);

    //allocting space for user data and meta data
    if( sbrk(size + sizeof(struct block_meta) ) == (void *)-1 ) return NULL;

    //meta data struct would start at the heap top
    struct block_meta *meta_data = (struct block_meta*)top;
    meta_data->size = size;
    meta_data->is_free=0;
    meta_data->next=NULL;

    //adding to metadata linkedlist 
    if(tail == NULL)
    {
        head = meta_data;
        tail=meta_data;
    }
    else
    {
        tail->next = meta_data;
        tail=meta_data;
    }

    //userdata memory starts after metadata
    top = (char*)top+sizeof(*meta_data);
    return top;
}

void free(void *ptr)
{
    (void)ptr;
    //intentionally empty for now -- we are going to test it on `ls` 
}

It ran successfully!

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ gcc -shared -fPIC -o malloc_v2.so malloc_v2.c && LD_PRELOAD=./malloc_v2.so ls
faulty_heap_spy.c  heap_spy_modified.c  malloc_v1.so  malloc_v2.so  og_malloc.c
heap_spy.c         malloc_v1.c          malloc_v2.c   notes         out

Issue: The Alignment trap
The struct block_meta occupies 24 bytes.

The CPU reads in fixed sized chunks, typically 64 bytes at a time, and within those chunks, it wants data to start at clean boundaries.

For example,
you have a double (8 bytes) that starts at 0 will be read cleanly

slot 0    slot 8    slot 16   slot 24
[........][........][........][........]

however, if the double starts at 5 bytes, it will span 2 slots, needing 2 reads.
This is slow and may cause crashes.

malloc() must be stable and return memory addresses for any type of variable. The maximum size of a var in C is 16 bytes (max_align_t).
So, malloc must return 16 byte aligned addresses.

My current code does not do that.

to fix it,

struct block_meta 
{
    size_t size;
    int is_free;
    struct block_meta *next;
} __attribute__((aligned(16)));

this aligns the chunks properly.
and now, the size of the struct is 32 bytes.
Original size was 24 bytes and 8 bytes have been added as padding to make it a multiple of 1

Creating my first malloc - Phase 1 Mini Malloc

moonlitpath — Sun, 22 Mar 2026 13:37:19 +0000

In this part, I am going to make a simple bump allocator that just allocates memory.

The file created is called malloc_v1.c

Note:
The clues I mention below were given to me by an AI assistant, used purely to guide my understanding of concepts and syntax. The entire code is written by me, referencing the official glibc documentation throughout.
I'm mentioning this explicitly because I believe in being honest about the learning process.

The entire process and my code has been uploaded on my github account: [https://github.com/moonlitpath1/mini-malloc]

Clues that I've got:

Create mymalloc.c. You need **two* functions (not one):*

#include <unistd.h>
#include <stddef.h>

void *malloc(size_t size) {
    // your 3-line bump allocator here
}

void free(void *ptr) {
    // intentionally empty for now — but must exist
}

Why does free need to exist even empty? When ls runs, it calls free() on memory it allocated. If you don't provide free, your .so has no free symbol, so the linker falls back to glibc's free — which will try to read metadata from a pointer your malloc never wrote, and segfault. A stub that does nothing is safer for now.

Your 3 clues for malloc:

sbrk(0) → returns current heap end → **this is what you return to the caller**
sbrk(size) → shoves the heap forward by size bytes
Do step 1 first, step 2 second — one line each

**Failure check clue:* sbrk() returns (void *)-1 on failure. Real malloc returns NULL on failure. Handle it.*

Compile + inject:

gcc -shared -fPIC -o mymalloc.so mymalloc.c
LD_PRELOAD=./mymalloc.so ls

What success looks like: ls prints your files. No segfault.

What to watch for: Run it with strace -e trace=brk too. You'll see something very different from glibc's single big-grab behavior — your allocator hits brk on every single call. That's the inefficiency you're building toward fixing in Phase 3.

My Notes

sbrk(5)

moves the heap pointer by 5 bytes
allocates 5 bytes of memory
returns previous program break

Mistake 1

I created a main() function and tried running a test code in it, while creating the malloc() and free() functions and leaving them empty.

However, this lead to segfault.

Reason:
My code's malloc() was overriding the original malloc's and free's code, since it was named malloc.c...
Also,printf() depends upon malloc() to create space since it uses the output buffer, etc.
So, when it encountered the empty malloc() it ran into a frenzy and this lead to a segfault.

#include<stdio.h>
#include<unistd.h>
#include<stddef.h>

void* malloc(size_t size)
{
    /* void *top = sbrk(0); */
    /* printf("Print %p\n", top); */
}

void free(void *ptr)
{
    /*
    intentionally empty for now
    */
}

int main()
{
    printf("%p\n", sbrk(0));
    return 0;
}

I learnt that the main() function is not needed here, and to never use printf()s inside an malloc.

Creating my first bump allocator

This is the most basic malloc ever aka bump allocator -- since the ptr can only move forward like a bump on a counter --- your heap can only grow. never shrink.

no memory reusability.

My code:

#include<unistd.h>
#include<stddef.h>

void* malloc(size_t size)
{
    void *top = sbrk(0);
    if(sbrk(size) == (void *)-1) return NULL;
    return top;
}

void free(void *ptr)
{
    (void)ptr;
    //intentionally empty for now -- we are going to test it on `ls` 
    //but ls calls free() on memory, 
    //if we dont provide the function the .so file has no free symbol,
    //so the linkter falls back to glibc's free
    //which tries to read metadata from a pointer malloc never wrote
    //and segfault. 
}

Notes:
(void*)-1 is typecasting the number -1 to a memory address that is of the type void* so that the compiler can recognize it.

(void*)-1 points to the location of the end of the possible memory range.

(void* )1 points to the address 1 in virtual memory, an almost-certainly invalid address that no real allocation would ever return. Dereferencing it causes a segfault.

(void*)0 points to NULL, aka nothing.

Testing my custom malloc() on ls

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ gcc -shared -fPIC -o mymalloc.so mymalloc.c

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ LD_PRELOAD=./malloc_v1.so ls
faulty_heap_spy.c  heap_spy_modified.c  malloc_v1.so  og_malloc.c
heap_spy.c         malloc_v1.c          notes         out

IT WORKED!!!
It displayed all the files in my directory!!

strace of running ls using my malloc()
There were 51 malloc() calls. My bump allocator asked the OS for memory on every single malloc() call. every tiny filename, string, struct that ls allocates needed a call to the kernel.

Every brk() call is a context switch. the program has to stop, go to the kernel, wait, then come back.

We can see that even tiny allocations of 12 b needed a special brk syscall.

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ LD_PRELOAD=./malloc_v1.so strace -e trace=brk ls 2>&1 | grep brk
brk(NULL)                              = 0x555555579000
brk(NULL)                              = 0x555555579000
brk(0x5555555791d8)                    = 0x5555555791d8
brk(0x555555579250)                    = 0x555555579250
brk(0x555555579650)                    = 0x555555579650
brk(0x555555579655)                    = 0x555555579655
brk(0x5555555796cd)                    = 0x5555555796cd
brk(0x5555555796d9)                    = 0x5555555796d9
brk(0x5555555799f1)                    = 0x5555555799f1
brk(0x555555579a59)                    = 0x555555579a59
brk(0x555555579f89)                    = 0x555555579f89
brk(0x55555557a059)                    = 0x55555557a059
brk(0x55555557a201)                    = 0x55555557a201
brk(0x55555557a261)                    = 0x55555557a261
brk(0x55555557a2b1)                    = 0x55555557a2b1
brk(0x55555557a321)                    = 0x55555557a321
brk(0x55555557a3c1)                    = 0x55555557a3c1
brk(0x55555557a421)                    = 0x55555557a421
brk(0x55555557a469)                    = 0x55555557a469
brk(0x55555557a521)                    = 0x55555557a521
brk(0x55555557a52d)                    = 0x55555557a52d
brk(0x55555557a539)                    = 0x55555557a539
brk(0x55555557a545)                    = 0x55555557a545
brk(0x55555557a551)                    = 0x55555557a551  ←  12b
brk(0x55555557a55d)                    = 0x55555557a55d  ←  12b
brk(0x55555557a569)                    = 0x55555557a569
brk(0x55555557a575)                    = 0x55555557a575
brk(0x55555557a581)                    = 0x55555557a581
brk(0x55555557a58d)                    = 0x55555557a58d
brk(0x55555557a599)                    = 0x55555557a599
brk(0x55555557a5a5)                    = 0x55555557a5a5
brk(0x55555557a5b1)                    = 0x55555557a5b1
brk(0x55555557a5bd)                    = 0x55555557a5bd
brk(0x55555557a5df)                    = 0x55555557a5df
brk(0x55555557a5e9)                    = 0x55555557a5e9
brk(0x55555557a621)                    = 0x55555557a621
brk(0x55555557a659)                    = 0x55555557a659
brk(0x55555557a6d9)                    = 0x55555557a6d9
brk(0x55555559b6d9)                    = 0x55555559b6d9 
brk(0x55555559c000)                    = 0x55555559c000
brk(0x55555559c020)                    = 0x55555559c020
brk(0x55555559c022)                    = 0x55555559c022
brk(0x5555555a4052)                    = 0x5555555a4052
brk(0x5555555a405e)                    = 0x5555555a405e
brk(0x5555555a4062)                    = 0x5555555a4062
brk(0x5555555a4068)                    = 0x5555555a4068
brk(0x5555555a407c)                    = 0x5555555a407c
brk(0x5555555a4087)                    = 0x5555555a4087
brk(0x5555555a4093)                    = 0x5555555a4093
brk(0x5555555a40a0)                    = 0x5555555a40a0
brk(0x5555555a40b2)                    = 0x5555555a40b2
brk(0x5555555a50b2)                    = 0x5555555a50b2

strace of running ls using regular malloc
just 3 brk calls -_-.
glibc had asked for a huge chunk of memory at once, and then it handled all those 51 allocations by itself, internally, not disturbing the kernel.

anu@laptop:~/anu/programming/systems_progg/mini-malloc$ strace -e trace=brk ls 2>&1 | grep brk
brk(NULL)                               = 0x555555579000
brk(NULL)                               = 0x555555579000
brk(0x55555559a000)                     = 0x55555559a000

This is the biggest limitation of my bump allocator.
There's no memory re-usability.

Observing Malloc - Phase 0 Mini Malloc

moonlitpath — Sun, 22 Mar 2026 13:12:57 +0000

This is a journey of how I built my first memory allocator.

Note:
The clues and guidance I mention below were given to me by an AI assistant, used purely to guide my understanding of concepts and syntax. The entire code is written by me, referencing the official glibc documentation throughout.
I'm mentioning this explicitly because I believe in being honest about the learning process.

This entire process and my code has been uploaded on my github account: [https://github.com/moonlitpath1/mini-malloc]

Let's start!

First, I'll build a mental model of what malloc does at the systems level by observing it's behavior.

0.1 : Using `strace` to see how kernel manages memory for `ls`

Command to run

anu@laptop:~$ strace -e trace=brk,mmap,munmap ls 2>&1 | head -40

[[dump/strace mmap, brk, munmap|Actual code output]]

there are 2 ways to give memory to a program
- brk: extending the heap
- mmap: maps all the shared library files .so (that ls depends on)

── PHASE 1: Library Loading ──────────────────────────────────
brk(NULL)  = 0x555555579000          ← "where does my heap end?" (just a question, heap doesn't grow yet)
mmap(NULL, 8192,  ..., -1, 0)        ← anonymous memory for the loader itself
mmap(NULL, 81463, ...,  3, 0)        ← loading a .so file (fd=3 means a library file)
mmap(NULL, 181960,...,  3, 0)        ← loading another .so file
mmap(...,  118784,...,  3, 0x6000)   ← loading another .so file
... (10 more mmap lines, all fd=3) ...

── PHASE 2: Heap Actually Grows ──────────────────────────────
brk(NULL)            = 0x555555579000   ← asking again: "where is my heap?"
brk(0x55555559a000)  = 0x55555559a000   ← NOW the heap actually moves forward ✅

── PHASE 3: Last Big mmap (locale/directory data) ────────────
mmap(NULL, 5719296, PROT_READ, MAP_PRIVATE, 3, 0) = 0x7ffff7600000

── OUTPUT ────────────────────────────────────────────────────
anu
backup.log
Desktop
...

0.2 Watching the heap using a C program

Theory:
brk() is a kernel syscall. The kernel maintains a pointer called program break - the official boundary marking the end of the process' heap segment in the virtual memory

Virtual Memory Layout (kernel's view):
┌─────────────┐
│    stack    │  ← grows downward
│      ↓      │
│   (gap)     │
│      ↑      │
│    heap     │  ← grows upward
│─────────────│ ← PROGRAM BREAK (brk moves this line)
│ data/bss    │
│    text     │
└─────────────┘

brk() moves that line up or down. the kernel just manages this boundary.

sbrk(0) is a C library wrapper that asks the kernel where the program break is rn.

	What it is
`brk` / program break	End of the heap segment in virtual memory
Top chunk end	End of glibc's usable unallocated space
`sbrk(0)` return value	Just reads the program break

These all point to the same address, but for different reasons.

The heap that we refer to here is both the Cs heap and the kernel's heap. According to the kernel, we are accessing the data segment, that's a range of addresses owned by the processor
glibc calls it heap and imposes structures on it - chunks, bins, top chunk

The kernel has no knowledge of the internal structures made by glibc. It's just a collection of bytes for it.

This was my C program:

#include<stdio.h>
#include<unistd.h>
#include<stdlib.h>

int main()
{
        printf("Heap Pointer locataion:\nBefore:%p", sbrk(0));
        malloc(1000);

        printf("\nAfter:%p", sbrk(0));
        return 0;

}

and this is my what my compiled file when traced with strace looks like

strace -e trace=brk ./heap_spy

brk(NULL)                               = 0x555555559000
brk(NULL)                               = 0x555555559000
brk(0x55555557a000)                     = 0x55555557a000

Heap Pointer locataion:
Before:0x555555559000
After:0x55555557a000+++ exited with 0 +++

I asked for 1000 bytes using malloc however, the difference:

0x55555557a000 - 0x555555559000 = 0x21000 = 135,168 bytes ≈ 132 KB

I got wayyy more than what I asked for!
this is because glibc is greedy. system calls are expensive so it stocks up some more memory for future use.

aka glibc buys memory in wholesale, and stores it in its private stock.

Why were there 2 brk calls?

brk(NULL)  = 0x555555559000   ← not from your code
brk(NULL)  = 0x555555559000   ← your sbrk(0) call
brk(...)   = 0x55555557a000   ← your malloc(1000)

The 1st brk happened before my code ran. it a part of glibc's startup routine to check where the current heap pointer is.
//notice glibc is doing stuff before main

Experiment 0.3 - Breaking the pattern

#include<stdio.h>
#include<unistd.h>
#include<stdio.h>
#include<unistd.h>
#include<stdlib.h>

int main()
{
    printf("Heap Pointer locataion:\nBefore:%p", sbrk(0));

    printf("\n1st malloc\nMalloc Pointer Address: %p\n", malloc(1000));
    printf("Heap Pointer location:%p", sbrk(0));

    printf("\n2nd malloc\nMalloc Pointer Address: %p\n", malloc(1000));
    printf("Heap Pointer location:%p", sbrk(0));

    printf("\n3rd malloc\nMalloc Pointer Address: %p\n", malloc(1000));
    printf("Heap Pointer location:%p", sbrk(0));


    char cmd[64]; //creates a character buffer

    //proc -- linux virtual file system -- you are getting memory mappings of a process that containt the word "heap" using current pid

    sprintf(cmd, "cat /proc/%d/maps | grep heap", getpid()); 
    system(cmd); //executes the command using /bin/sh

        return 0;

}

OUTPUT traced with strace:

strace -e trace=brk ./out
brk(NULL)                               = 0x555555559000
brk(NULL)                               = 0x555555559000
brk(0x55555557a000)                     = 0x55555557a000
Heap Pointer locataion:
Before:0x555555559000

--- 1st malloc
Malloc Pointer Address: 0x5555555596b0
Heap Pointer location:0x55555557a000

--- 2nd malloc
Malloc Pointer Address: 0x555555559aa0
Heap Pointer location:0x55555557a000

--- 3rd malloc
Malloc Pointer Address: 0x555555559e90

555555559000-55555557a000 rw-p 00000000 00:00 0                          [heap]
--- SIGCHLD {si_signo=SIGCHLD, si_code=CLD_EXITED, si_pid=11441, si_uid=1000, si_status=0, si_utime=0, si_stime=0} ---
Heap Pointer location:0x55555557a000+++ exited with 0 +++

We notice that all 3 malloc pointer addresses are within the initial 132kb reigion.

The 132KB call had set up the arena, wherein my data was packed neatly. the memory malloc got was from the arena's top chunk

brk() was called just once to set up the arena, and after that glibc gave the memory as needed to malloc.

Extra:
Previously, my code looked like this:

#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>

int main()
{
    printf("Heap Pointer location:\nBefore:%p", sbrk(0));
    printf("\n1st malloc\nMalloc Pointer Address: %p\nHeap Pointer location:%p", malloc(1000), sbrk(0));
    printf("\n2nd malloc\nMalloc Pointer Address: %p\nHeap Pointer location:%p", malloc(1000), sbrk(0));
    printf("\n3rd malloc\nMalloc Pointer Address: %p\nHeap Pointer location:%p", malloc(1000), sbrk(0));

    return 0;
}

and for some reason, the strace looked like this when I ran it, after rebooting however, looked like the previous strace, no brk() calls after malloc(). I have absolutely no clue why as of now, but I'll explore it in the future.

Heap Pointer locataion:
Before:0x555555559000
1st malloc
Malloc Pointer Address: 0x5555555596b0
Heap Pointer location:0x55555557a000
2nd malloc
Malloc Pointer Address: 0x555555559aa0
Heap Pointer location:0x55555557a3e8
3rd malloc
Malloc Pointer Address: 0x555555559e90
Heap Pointer location:0x55555557a7d0
Press ENTER or type command to continue
brk(NULL)                               = 0x555555559000
brk(NULL)                               = 0x555555559000
brk(0x55555557a000)                     = 0x55555557a000
Heap Pointer locataion:
brk(0x55555557a3e8)                     = 0x55555557a3e8
Before:0x555555559000
1st malloc
Malloc Pointer Address: 0x5555555596b0
brk(0x55555557a7d0)                     = 0x55555557a7d0
Heap Pointer location:0x55555557a000
2nd malloc
Malloc Pointer Address: 0x555555559aa0
brk(0x55555557abb8)                     = 0x55555557abb8
Heap Pointer location:0x55555557a3e8
3rd malloc
Malloc Pointer Address: 0x555555559e90
Heap Pointer location:0x55555557a7d0+++ exited with 0 +++
Heap Pointer locataion:
Before:0x555555559000
1st malloc
Malloc Pointer Address: 0x5555555596b0
Heap Pointer location:0x55555557a000
2nd malloc
Malloc Pointer Address: 0x555555559aa0
Heap Pointer location:0x55555557a3e8
3rd malloc
Malloc Pointer Address: 0x555555559e90
Heap Pointer location:0x55555557a7d0

DEV Community: moonlitpath

Submitting a DT Schema Patch for Rockchip RK3399-GRU Sound — A Dev Journal

Testing

Submitting My First Device Tree Binding Patch While Applying for GSoC 2026 — And It Got ACKed!

OLPC XO-1 RTC

Understanding the Hardware:

Making a patch

Reply

Device Tree Bindings — What They Are and Why They Matter

Motivation:

What is a device tree?

Non discoverable devices hardware descriptions needed:-

How to discover non discoverable components:

Device Tree

Device Tree Bindings

YAML

TXT file -- old

Things I figured out along the way

Submitting my second cleanup patch While Applying for GSoC 2026 — Still Messy, Still Learning

Submitting My First Linux Kernel Patch While Applying for GSoC 2026 — The Real, Messy Process

Steps to find an issue and submit a patch

My Mistake:

Extra -- aka just me screaming my head off

Optimizing Memory usage with mmap - Phase 6 Mini Malloc

The Threshold on the System

The concept:

Three clues for the implementation:

Implementation

Malloc allocates when size > 128 KB

Free function frees block using munmap if it was allocated with mmap

Testing program

Complete code

Coalescing - Phase 5 Mini Malloc

Clues:

📚 Flow:

Implementation and results:

Issues

Reading glibc's malloc.c

Footer Logic

Version 1 of backwards coalesce

Full Code:

Block Splitting - Phase 4 Mini Malloc

Clues

My understanding of the clue and planning

Version 1

Version 2

Full code:

Implementing free - Phase 3 Mini Malloc

Clues

My Code

Issue: Block Fragmentation.

Metadata header - Phase 2 Mini Malloc

Clues

What I learnt:

My first attempt:

Creating my first malloc - Phase 1 Mini Malloc

Clues that I've got:

My Notes

Mistake 1

Creating my first bump allocator

Observing Malloc - Phase 0 Mini Malloc

0.1 : Using strace to see how kernel manages memory for ls

0.2 Watching the heap using a C program

Experiment 0.3 - Breaking the pattern

`Malloc` allocates when size > 128 KB

Free function frees block using `munmap` if it was allocated with `mmap`

Reading glibc's `malloc.c`

0.1 : Using `strace` to see how kernel manages memory for `ls`