sx9324: a table that was half as long as it should be

The SX9324 polls for new samples when it has no interrupt line. To decide how long to sleep, the driver reads the scan period code from a register and uses it as an index into a table:

static int sx9324_wait_for_sample(struct sx_common_data *data)
{
    ...
    val = FIELD_GET(SX9324_REG_GNRL_CTRL0_SCANPERIOD_MASK, val);

    msleep(sx9324_scan_period_table[val]);
    ...
}

The SCANPERIOD field is 5 bits wide, so it has 32 possible codes. The table had 16 entries. It had been copied from the SX9310 driver, where the same field is only 4 bits wide. Every code from 0x10 to 0x1f read past the end of the array, and the chip’s reset default is 0x16 (100 ms). In other words, a polled SX9324 with the default configuration slept for whatever number happened to sit in memory after the table.

The fix seemed simple: fill in all 32 periods, which the driver already documented in the comments of its sx9324_samp_freq_table[], and add a static_assert() so the two tables can never disagree in length again. My v1 packed the 32 values into three lines, as tightly as they would fit. Andy’s reply was short:

NAK to this hunk.
Homework:
read my comments regarding formatting such arrays in linux-iio@ mailing list
for last calendar year or so and summarize the idea.

That was my first NAK. To be honest it stung for a minute, and then I realised it was one of the most useful replies I had received. Andy hadn’t rewritten the table for me. He told me where the answer was and trusted me to find it. I replied within a few minutes to say I would do the homework.

I keep a local git mirror of the linux-iio archive, so the homework was a search through a year of Andy’s reviews. The idea turned up again and again, most clearly in a November 2025 review of a new frequency driver:

Make it power-of-two items per line, even with the comments to show the indexing, like
810, 1620, 2430, 3240, 4050, 4860, 5670, 6480, /* 0 - 7 */

Once I saw it, the reason was obvious. This table is indexed by a register value, so a reader has to be able to answer “what is entry 0x13?” at a glance. With eight entries per line and the code range in a comment, you can. With values packed to fill the line, you have to count, and a typo can hide for years. The v2 looked like this:

static const unsigned int sx9324_scan_period_table[] = {
    1, 2, 4, 6, 8, 10, 14, 18,          /* 0x00 - 0x07 */
    22, 26, 30, 34, 38, 42, 46, 50,         /* 0x08 - 0x0f */
    56, 62, 68, 74, 80, 90, 100, 200,       /* 0x10 - 0x17 */
    300, 400, 600, 800, 1000, 2000, 3000, 4000, /* 0x18 - 0x1f */
};

static_assert(ARRAY_SIZE(sx9324_scan_period_table) == ARRAY_SIZE(sx9324_samp_freq_table));

I also put the static_assert() on one line, as Andy suggested (“I would dare make it a single line”), added the Fixes: tag and Cc: stable, and rebased on fixes-togreg. Jonathan applied it a few hours after I sent it:

Looks good and matches what Andy asked about.

Applied to the fixes-togreg branch of iio.git.

Andy’s review of v2 arrived later that day. It had one more nit (“5 bit wide” should be “5-bit wide”) and ended with:

Haven’t checked if this is part of any ABI. Otherwise LGTM,
Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>

Jonathan didn’t ask me for a v3 to fix a hyphen. He replied “Tweaked and tagged.” and fixed it himself in his tree. Going from NAK to Reviewed-by: in two days, with the maintainer cleaning up the last nit for me, felt like a real reward for doing the homework properly.

mcp3564: a NULL pointer behind a fallback

The MCP3564 driver identifies its chip by reading ID registers. If the ID is not one it knows, for example on a newer part number, it falls back to the match data from the device tree:

flowchart TD
    A[Read chip ID registers] --> B{Known ID?}
    B -- yes --> C[chip_info from the driver's table]
    B -- no --> D["spi_get_device_match_data()"]
    D --> E{NULL?}
    E -- "no: DT or id-table match" --> F[use chip_info]
    E -- "yes: bound via driver_override" --> G["before: oops on chip_info->have_vref<br/>after: return -ENODATA"]

spi_get_device_match_data() returns NULL when the device was bound with driver_override and its name isn’t in the driver’s id table. The driver dereferenced the result unconditionally, so that case ended in a kernel oops. The fix is three lines:

        adc->chip_info = spi_get_device_match_data(adc->spi);
+       if (!adc->chip_info)
+           return -ENODATA;
+
        adc->have_vref = adc->chip_info->have_vref;

Andy gave it a Reviewed-by: on v1, together with a request and a thought about the bigger picture:

Fine, but I hope we will have something to land to actually do it differently for the drivers that don’t want to use driver_override mechanism.

Reviewed-by: Andy Shevchenko <andriy.shevchenko@intel.com>
Please, shrink the commit message to the point.

He was right on both counts. A NULL check in every driver is a stopgap, not a design. And my v1 commit message took four paragraphs to say something that fits in one. The v2 message is half as long:

When the chip can’t be identified from its ID registers, the driver falls back to spi_get_device_match_data() and dereferences the result unconditionally. That returns NULL for a device bound through driver_override whose name isn’t in the id table, causing an oops.

Return -ENODATA in that case.

That taught me to write the shortest message that still explains the bug. Jonathan replied with a single word, “Applied”, which is my favourite word on the list.

sx9360: a frequency that always became zero

The SX9360 stores its scan period in two registers, GNRL_CTRL1 and GNRL_CTRL2, as an 11-bit count of ticks. One tick is 8192 cycles of the 4 MHz oscillator. So the period for a frequency f is

The driver’s write function had the fraction upside down, and it scaled the micro-hertz part of the value wrongly:

reg = val * 8192 / SX9360_FOSC_HZ + val2 * 8192 / (SX9360_FOSC_MHZ);

For any frequency the chip supports, val * 8192 / 4000000 is 0 in integer arithmetic. The val2 term always produces a multiple of 2048, so it never reaches the 11-bit period field, but it does spill into the bits of GNRL_CTRL1 above it. Above about 0.26 Hz of fractional part it also overflows an int. To make sure, I replayed both formulas for every frequency the driver advertises:

The new code computes the period the right way up, rounds to the closest tick, and rejects frequencies the chip can’t represent. While I was there, I noticed the advertised range didn’t match the comments next to it either: 4 MHz / 8192 is 488.28125 Hz, not 448.28125 Hz, and the minimum and step were wrong too. Before sending v1, I also checked in userspace that the default 102 ms period survived the round trip: 9.765625 Hz → period 50 → 9.765625 Hz.

Andy’s review of v1 was a series of short, precise questions:

unsigned int period;

What’s the units for period? Seconds?

u64 freq_uhz;

_uHz

freq_uhz = (u64)val * MICRO + val2;

Read what units.h has for units of Hz.

Missing blank line. Always make guard()() to be standalone in the code.

None of these change what the code does, but each makes it easier to read. A variable called period in a function full of hertz and oscillator cycles should make a reader ask “in what?”. MICRO is a plain number, while MICROHZ_PER_HZ from <linux/units.h> says what it is converting. So v2 renamed the variable to period_ticks, said in a comment what a tick is, switched to freq_uHz and MICROHZ_PER_HZ, and gave guard(mutex) a line of its own:

    freq_uHz = (u64)val * MICROHZ_PER_HZ + val2;
    if (!freq_uHz)
        return -EINVAL;

    /* The register holds the scan period in ticks of 8192 FOSC cycles. */
    period_ticks = DIV64_U64_ROUND_CLOSEST((u64)SX9360_FOSC_HZ * MICROHZ_PER_HZ,
                           freq_uHz * 8192);
    if (!period_ticks || period_ticks > SX9360_REG_GNRL_SCANPERIOD_MAX)
        return -EINVAL;

    buf = cpu_to_be16(period_ticks);

    guard(mutex)(&data->mutex);

Andy also suggested that “at some point” the frequency table should become a plain array of ints. That is a cleanup rather than a fix, so I left it for a separate patch and said so below the --- line. Fifteen minutes after I sent v2, Jonathan replied:

Seems like you’ve addressed Andy’s comments (except for the ‘at some point’ one which is fine to leave for now). Looks good to me, so rather than keep track of this one I’m going to speculatively apply it to the fixes-togreg branch of iio.git and mark it for stable.

“Rather than keep track of this one” is a small phrase, but it says a lot. A maintainer has hundreds of threads to track, and a patch that clearly answers every review comment is one he can take off his list straight away. Writing a precise changelog is how I can make that easier for him.

sx9500: reference counts that drift

The SX9500 driver keeps reference counts of who is using each channel and the close/far interrupt. A channel is powered on when its count goes from 0 to 1, and off when it drops back to 0. sx9500_write_event_config() incremented or decremented these counts on every write to an event’s en attribute, even when the event was already in the requested state.

That lets the counts drift away from reality. Writing 0 to an event that is already disabled takes the count to −1. A following write of 1 brings it back to 0, which is not the 0 → 1 transition that turns the channel on. The event now reads as enabled, but the channel and its interrupt are off. Because raw reads share channel_users[], a raw read can then wait forever for a conversion that never starts. Writing 1 twice and then 0 does the opposite: the event reads as disabled but the channel stays on.

The newer SX9xxx drivers share sx_common_write_event_config(), which already returns early when the state doesn’t change. The SX9500 predates that common code, so the fix brings it in line:

    mutex_lock(&data->mutex);

+   /* The user counts must only change when the state does. */
+   if (data->event_enabled[chan->channel] == state) {
+       ret = 0;
+       goto out_unlock;
+   }
+
    if (state) {

I don’t have SX9500 hardware, so I checked both write sequences with a userspace model of the counting and said exactly that below the --- line. This was the only one of the four that went in as first sent. Jonathan’s reply in full:

Applied and marked for stable.

thanks

Jonathan

I hadn’t added Cc: stable to this one. Jonathan decided it deserved a backport and added the tag himself.

What these reviews taught me

Looking back over the four threads, very few of the review comments were about whether the code worked. They were about whether the next person could read it:

A few habits came out of this week:

• When a reviewer points you at the archive, read the archive. Andy’s homework took me longer than rewriting the table myself would have. But now I know a rule he applies to every indexed table, and I won’t need to be told again.
• Units belong in names. period_ticks, freq_uHz and MICROHZ_PER_HZ make the code document itself.
• The changelog is part of the patch. Each v2 listed every comment and who made it, and said what I hadn’t done and why. That is what let Jonathan apply the sx9360 fix fifteen minutes after it arrived.
• Say what you tested. All four patches say “Compile-tested only” under the --- line, along with whatever checking I could do without the hardware. Maintainers can only judge the risk of a patch if you’re honest about this.

Results

That brings my total to thirteen applied patches. I have a few more SX9xxx patches on the list as I write this, a series that keeps the IRQ balanced across suspend and resume, and a hysteresis fix for the sx9310, so this family of drivers may get one more post.

Acknowledgements

Thank you to Andy Shevchenko, whose reviews are short, exact and always worth reading twice, and to Jonathan Cameron for his patience, his speed, and for fixing my hyphens. Thanks also to Shuah Khan for the mentorship that got me here.

Background: how a patch travels

The Linux kernel has no pull requests. A change is a plain-text email, sent with git send-email to the maintainers and lists that scripts/get_maintainer.pl names for the files it touches. Reviewers reply inline, and they show approval with tags such as Reviewed-by: and Acked-by:. A subsystem maintainer then applies the patch to their own tree. From there it flows into linux-next, then into Linus Torvalds’ mainline tree during a merge window, and, if it is marked for stable, into the stable kernels people already run.

flowchart LR
    A[Prepare<br/>and check] --> B[Send to<br/>the list]
    B --> C{Review}
    C -- v2 --> C
    C -- tags --> D[Maintainer<br/>tree]
    D --> E[linux-next]
    E --> F[Mainline]
    D -. stable .-> G[Stable<br/>kernels]

IIO, maintained by Jonathan Cameron in iio.git, has two main branches. Fixes go to fixes-togreg and reach mainline in the current release cycle. Everything else goes to togreg, through a testing branch, and waits for the next merge window. This distinction matters later in the story.

Learning the process the hard way

My first attempt, in June 2025, did not reach any maintainer: I sent it as an attachment, only to my mentor. A second round, in June 2026, targeted the sm750fb staging driver. I had based it on an old tree, so I was renaming variables that other contributors had already renamed. The kernel test robot reported build failures, and my duplicate resubmissions earned a polite request to stop.

These were useful failures. They set the method I used for every later patch:

1. Start from today’s linux-next or the subsystem tree, never a stale checkout.
2. Build each changed object with make W=1, run scripts/checkpatch.pl --strict, and, for documentation, scripts/kernel-doc -Wall over the whole driver.
3. Search the list archives first. I kept local git mirrors of the linux-iio and netdev archives from lore.kernel.org, so I could check whether someone was already working on the same code.
4. Send each version once, with a changelog under the --- line.

Finding bugs worth fixing

Most of my search time went into static analysis: Smatch, Coccinelle, W=1 builds and kernel-doc. Most of what these tools report is not a bug. I went through Smatch’s 114 warnings on net/ and about 20 in IIO. In every case I checked, the code was correct: a signedness warning caused by a __be16 enum, a pointer that a helper function initialised where Smatch could not see it, and similar. Telling a false positive from a real defect, and dropping it quickly, turned out to be one of the most important skills of the mentorship.

Three real bugs came out of this search. Each of them also taught me something about how C code can hide errors.

Silent truncation in scmi_sensors

The kernel test robot had reported do_div() warnings in the SCMI sensor driver, and Geert Uytterhoeven had noted on the list that most do_div() uses in that driver were broken. Nobody had fixed them.

do_div(n, base) divides a 64-bit dividend by a 32-bit divisor: base is stored in a uint32_t on every architecture. The driver passed 64-bit divisors in seven calls. One of them converts a sensor’s update interval to a sampling frequency:

static void convert_ns_to_freq(u64 interval_ns, u64 *hz, u64 *uhz)
{
    u64 rem, freq;

    freq = NSEC_PER_SEC;
    rem = do_div(freq, interval_ns);   /* interval_ns silently truncated to 32 bits */
    *hz = freq;
    *uhz = rem * 1000000UL;
    do_div(*uhz, interval_ns);
}

For any interval of 2³² ns (about 4.29 s) or longer, the divisor wraps around. Figure 2 shows the result. The reported frequency is correct up to 4.29 s, then jumps by orders of magnitude, and an interval that is an exact multiple of 2³² ns would divide by zero.

The fix replaces each call with div64_u64() or div64_u64_rem(), which take a 64-bit divisor. The functions are not drop-in replacements, though. do_div() modifies its first argument in place and returns the remainder, while div64_u64() returns the quotient. I rewrote each call site separately so it kept its meaning:

-   freq = NSEC_PER_SEC;
-   rem = do_div(freq, interval_ns);
-   *hz = freq;
-   *uhz = rem * 1000000UL;
-   do_div(*uhz, interval_ns);
+   *hz = div64_u64_rem(HZ_PER_GHZ, interval_ns, &rem);
+   *uhz = div64_u64(rem * MICROHZ_PER_HZ, interval_ns);

Andy Shevchenko’s review of v1 pointed out over-long lines, asked for the named unit constants (HZ_PER_GHZ, MICROHZ_PER_HZ) instead of bare literals, and corrected the format of my Assisted-by: tag. The v2 got his Reviewed-by:, and Jonathan applied it to fixes-togreg with Cc: stable (lore, commit).

struct inv_mpu6050_hw {
    ...
    struct {
        unsigned int accel;
        unsigned int gyro;
    } startup_time;
};

-   .startup_time = {INV_MPU6500_GYRO_STARTUP_TIME, INV_MPU6500_ACCEL_STARTUP_TIME},
+   .startup_time = {
+       .accel = INV_MPU6500_ACCEL_STARTUP_TIME,
+       .gyro = INV_MPU6500_GYRO_STARTUP_TIME,
+   },

Documentation, and why reviewers ask for more

The remaining patches fixed kernel-doc comments that no longer matched the code: members that had been renamed or removed in ad5686, inv_icm42600, inv_mpu6050, and sfc. These sound minor, but the review of these patches taught me the most about how maintainers think.

When I sent a one-line fix for a stale @vdd_supply comment in inv_icm42600, Andy gave it a Reviewed-by: and asked whether it was the only kernel-doc problem in the driver. It was not. My v2 became a two-patch series that left the driver clean under kernel-doc -Wall. From then on I checked the whole driver before sending any documentation patch, and the inv_mpu6050 patch fixed all 13 of its warnings at once.

On netdev, Simon Horman noticed that a member next to the ones I had fixed in sfc was also undocumented. Looking closer, it was not used anywhere, so v2 removed it and two other unused members. That patch got Reviewed-by: tags from Alex Austin at AMD and from Simon, and Paolo Abeni applied it to net-next (lore, commit). It was my first patch applied anywhere in the kernel.

Working with the maintainers

I was nervous before every early submission. The names on the To: line were names I knew from MAINTAINERS files and commit logs, and every reply would be public and archived. That nervousness faded as the replies came in, because they were generous and precise.

Jonathan made me feel welcome from the start. When Jean-Baptiste called the startup-time fix “another good catch”, Jonathan replied “Absolutely” and applied it. He then suggested a follow-up, using named initialisers for the neighbouring .temp field, and added “No problem if you have moved onto other things!” It was a small sentence, but it made me feel like a contributor rather than a student.

He was also careful in ways that taught me about stewardship. On the cros_ec_sensors patch he wrote that the driver “tends to be well maintained”, so he would wait for its own maintainers before applying it. Tzung-Bi Shih, a ChromeOS EC maintainer, reviewed it the next morning, and Jonathan applied it that evening. When Joshua Crofts asked me for a Fixes: tag on that patch, I traced the code back to the commit that introduced it and posted the tag in the thread. Andy replied that there was no need to resend, because b4 collects tags from the whole thread. These are small things, but each of them is part of how the community works.

The best moment was a run of emails late on 17 October. Within about twenty minutes, “Applied to the togreg branch of iio.git” and “Applied to the fixes-togreg branch” arrived for seven of my patches. I was thrilled. After the earlier failures, seeing them applied one after another was the high point of the mentorship.

gantt
    dateFormat YYYY-MM-DD
    axisFormat %d %b
    section net-next
    sfc kernel-doc (v1, v2)        :done, 2026-10-03, 2026-10-13
    applied                        :milestone, 2026-10-13, 0d
    section iio fixes-togreg
    scmi_sensors (v1, v2)          :done, 2026-10-03, 2026-10-17
    mpu6050 magnetometer scale     :done, 2026-10-11, 2026-10-17
    mpu6050 startup times          :done, 2026-10-11, 2026-10-17
    cros_ec CALIBSCALE             :done, 2026-10-11, 2026-10-18
    applied                        :milestone, 2026-10-17, 0d
    section iio togreg
    icm42600 kernel-doc (v1, v2)   :done, 2026-10-03, 2026-10-17
    ad5686 kernel-doc              :done, 2026-10-11, 2026-10-17
    mpu6050 kernel-doc             :done, 2026-10-11, 2026-10-17
    section in review
    mpu6050 named .temp            :active, 2026-10-18, 2026-10-22

A lesson in dependencies

The follow-up Jonathan suggested taught me one more thing. I based it on fixes-togreg, because it edits lines that the startup-time fix had just changed. Joshua tried it on the development branch and replied that it did not apply. The patch was fine, but its context lines only exist where the startup-time fix exists. I explained this on the list. The lesson is to always state a patch’s base branch and dependencies below the --- line, especially when it builds on a fix that has not yet reached the development branch.

On using an AI assistant

I used an LLM-based assistant for analysis and to check my reasoning, and I disclosed it with an Assisted-by: tag on each patch, as the kernel’s policy on coding assistants requires. That policy is clear that responsibility stays with the human: I signed off, built and tested every patch, and answered every review myself. The guidance on the tag’s format changed during the mentorship. Andy corrected my early format, and Jonathan later dropped the tag from one patch because the guidance had changed again. It is a policy still being worked out, and the community is working it out in public.

Results

For the next mentee

• Read submitting-patches.rst before your first patch, and the subsystem’s maintainer notes, such as maintainer-netdev.rst, before your first patch to that subsystem.
• Look for code that is wrong, not only code that warns. Tracing a bug to the commit that introduced it, with a Fixes: tag, makes a patch much more useful to maintainers.
• When a reviewer asks for more than you sent, they are usually right. Treat it as the start of a collaboration.
• Be patient. Maintainers batch their work, and my patches waited one to two weeks.

Acknowledgements

I am grateful to Shuah Khan for running the mentorship, and to everyone who reviewed my work: Jonathan Cameron, Andy Shevchenko, Jean-Baptiste Maneyrol, Joshua Crofts, Nuno Sá, Maxwell Doose, Tzung-Bi Shih, Simon Horman, Alex Austin, Paolo Abeni and Geert Uytterhoeven. Each of these patches is better because of them.