Re: [PATCH vV 2/2] ipmi: add StarFive KCS BMC driver
From: Corey Minyard
Date: Wed Nov 18 2026 - 09:01:10 EST
Adding Andrew, hopefully he's still available to review.
A few questions inline, but I don't see any big issues in first
review.
-corey
On Wed, Nov 18, 2026 at 02:25:26PM +0800, Mason Huo wrote:
> This driver exposes the Keyboard Controller Style (KCS) interface on
> StarFive SoCs as a character device. Such SOCs are commonly used
> as a BaseBoard Management Controller (BMC) on a server board, and KCS
> interface is commonly used to perform the in-band IPMI communication
> between the server and its BMC.
>
> Signed-off-by: Mason Huo <mason.huo@xxxxxxxxxxxxxxxx>
> ---
> MAINTAINERS | 6 +
> drivers/char/ipmi/Kconfig | 15 ++
> drivers/char/ipmi/Makefile | 1 +
> drivers/char/ipmi/kcs_bmc_starfive.c | 311 +++++++++++++++++++++++++++
> 4 files changed, 333 insertions(+)
> create mode 100644 drivers/char/ipmi/kcs_bmc_starfive.c
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ccbcdc0799b9..b238fc730c51 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -26923,6 +26923,12 @@ S: Maintained
> F: Documentation/devicetree/bindings/pinctrl/starfive,jhb1*.yaml
> F: drivers/pinctrl/starfive/pinctrl-starfive-jhb1*
>
> +STARFIVE KCS-BMC DRIVER
> +M: Mason Huo <mason.huo@xxxxxxxxxxxxxxxx>
> +S: Supported
> +F: Documentation/devicetree/bindings/ipmi/starfive,kcs-bmc.yaml
> +F: drivers/char/ipmi/kcs_bmc_starfive.c
> +
> STATIC BRANCH/CALL
> M: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
> M: Josh Poimboeuf <jpoimboe@xxxxxxxxxx>
> diff --git a/drivers/char/ipmi/Kconfig b/drivers/char/ipmi/Kconfig
> index 538a7d3c65bf..8b51e67d3ac4 100644
> --- a/drivers/char/ipmi/Kconfig
> +++ b/drivers/char/ipmi/Kconfig
> @@ -149,6 +149,21 @@ config NPCM7XX_KCS_IPMI_BMC
> This support is also available as a module. If so, the module
> will be called kcs_bmc_npcm7xx.
>
> +config STARFIVE_KCS_IPMI_BMC
> + depends on ARCH_STARFIVE || COMPILE_TEST
> + select IPMI_KCS_BMC
> + select MFD_SYSCON
> + tristate "StarFive KCS IPMI BMC driver"
> + help
> + Provides a driver for the KCS (Keyboard Controller Style) IPMI
> + interface found on StarFive SoCs.
> +
> + The driver implements the BMC side of the KCS controller, it
> + provides the access of KCS IO space for BMC side.
> +
> + This support is also available as a module. If so, the module
> + will be called kcs_bmc_starfive.
> +
> config IPMI_KCS_BMC_CDEV_IPMI
> depends on IPMI_KCS_BMC
> tristate "IPMI character device interface for BMC KCS devices"
> diff --git a/drivers/char/ipmi/Makefile b/drivers/char/ipmi/Makefile
> index 4ea450a82242..800d570dd4dc 100644
> --- a/drivers/char/ipmi/Makefile
> +++ b/drivers/char/ipmi/Makefile
> @@ -27,5 +27,6 @@ obj-$(CONFIG_IPMI_KCS_BMC_CDEV_IPMI) += kcs_bmc_cdev_ipmi.o
> obj-$(CONFIG_ASPEED_BT_IPMI_BMC) += bt-bmc.o
> obj-$(CONFIG_ASPEED_KCS_IPMI_BMC) += kcs_bmc_aspeed.o
> obj-$(CONFIG_NPCM7XX_KCS_IPMI_BMC) += kcs_bmc_npcm7xx.o
> +obj-$(CONFIG_STARFIVE_KCS_IPMI_BMC) += kcs_bmc_starfive.o
> obj-$(CONFIG_IPMB_DEVICE_INTERFACE) += ipmb_dev_int.o
> obj-$(CONFIG_SSIF_IPMI_BMC) += ssif_bmc.o
> diff --git a/drivers/char/ipmi/kcs_bmc_starfive.c b/drivers/char/ipmi/kcs_bmc_starfive.c
> new file mode 100644
> index 000000000000..bff7bdd5ad1c
> --- /dev/null
> +++ b/drivers/char/ipmi/kcs_bmc_starfive.c
> @@ -0,0 +1,311 @@
> +// SPDX-License-Identifier: GPL-2.0
> +/*
> + * Copyright (C) 2024 StarFive Technology Co., Ltd.
> + */
> +
> +#include <linux/bits.h>
> +#include <linux/errno.h>
> +#include <linux/interrupt.h>
> +#include <linux/io.h>
> +#include <linux/mfd/syscon.h>
> +#include <linux/module.h>
> +#include <linux/of.h>
> +#include <linux/of_address.h>
> +#include <linux/platform_device.h>
> +#include <linux/regmap.h>
> +#include <linux/spinlock.h>
> +
> +#include "kcs_bmc_device.h"
> +
> +#define DEVICE_NAME "starfive-kcs-bmc"
> +
> +/*
> + * Every SIO block of the SoC provides KCS_CHANNELS_PER_SIO KCS channels, each
> + * occupying a KCS_CHANNEL_STRIDE byte register window, starting at offset
> + * KCS_CHANNEL_BASE of the SIO register space.
> + */
> +#define KCS_CHANNELS_PER_SIO 4
> +#define KCS_CHANNEL_BASE 0x200
> +#define KCS_CHANNEL_STRIDE 0x100
> +#define KCS_SIO_MAX 2
> +
> +#define KCS_DO 0x0
> +#define KCS_DI 0x4
> +#define KCS_STS 0x8
> +
> +#define KCS_INT 0xc
> +#define KCS_INT_IBF_EN BIT(0)
> +#define KCS_INT_IBF_STS BIT(1)
> +
> +struct starfive_kcs_bmc {
> + struct kcs_bmc_device kcs_bmc;
> + struct regmap *map;
> + /* Protects ie_en and serialises every write to KCS_INT */
> + spinlock_t ie_lock;
> + /* Shadow of the KCS_INT enable bits, restored after eSPI bus reset */
> + u32 ie_en;
> +};
> +
> +static inline struct starfive_kcs_bmc *
> +to_starfive_kcs_bmc(struct kcs_bmc_device *kcs_bmc)
> +{
> + return container_of(kcs_bmc, struct starfive_kcs_bmc, kcs_bmc);
> +}
> +
> +static u8 starfive_kcs_inb(struct kcs_bmc_device *kcs_bmc, u32 reg)
> +{
> + struct starfive_kcs_bmc *priv = to_starfive_kcs_bmc(kcs_bmc);
> + u32 val = 0;
> + int rc;
> +
> + rc = regmap_read(priv->map, reg, &val);
> + WARN(rc != 0, "regmap_read() failed: %d\n", rc);
The WARNs here seem a little heavy, but there is precedent, so I'm ok
with it.
You probably want to print the register, though, on all of these.
> +
> + return rc == 0 ? (u8)val : 0;
> +}
> +
> +static void starfive_kcs_outb(struct kcs_bmc_device *kcs_bmc, u32 reg, u8 data)
> +{
> + struct starfive_kcs_bmc *priv = to_starfive_kcs_bmc(kcs_bmc);
> + int rc;
> +
> + rc = regmap_write(priv->map, reg, data);
> + WARN(rc != 0, "regmap_write() failed: %d\n", rc);
> +}
> +
> +static void starfive_kcs_updateb(struct kcs_bmc_device *kcs_bmc,
> + u32 reg, u8 mask, u8 data)
> +{
> + struct starfive_kcs_bmc *priv = to_starfive_kcs_bmc(kcs_bmc);
> + int rc;
> +
> + rc = regmap_update_bits(priv->map, reg, mask, data);
> + WARN(rc != 0, "regmap_update_bits() failed: %d\n", rc);
> +}
> +
> +/*
> + * Write the shadow of the enable bits to KCS_INT. KCS_INT_IBF_STS is a
> + * read-only mirror of the IBF flag in KCS_STS, which the hardware clears
> + * once KCS_DI has been read, so only the enable bits are ever written.
> + */
> +static void starfive_kcs_write_ie(struct starfive_kcs_bmc *priv)
> +{
> + int rc;
> +
> + lockdep_assert_held(&priv->ie_lock);
> +
> + rc = regmap_write(priv->map, KCS_INT, priv->ie_en);
> + WARN(rc != 0, "regmap_write() failed: %d\n", rc);
> +}
> +
> +static void starfive_kcs_irq_mask_update(struct kcs_bmc_device *kcs_bmc,
> + u8 mask, u8 state)
> +{
> + struct starfive_kcs_bmc *priv = to_starfive_kcs_bmc(kcs_bmc);
> + unsigned long flags;
> +
> + /* The hardware has no OBE interrupt */
> + if (!(mask & KCS_BMC_EVENT_TYPE_IBF))
> + return;
> +
> + spin_lock_irqsave(&priv->ie_lock, flags);
> + if (state & KCS_BMC_EVENT_TYPE_IBF)
> + priv->ie_en |= KCS_INT_IBF_EN;
> + else
> + priv->ie_en &= ~KCS_INT_IBF_EN;
> + starfive_kcs_write_ie(priv);
> + spin_unlock_irqrestore(&priv->ie_lock, flags);
> +}
> +
> +static void starfive_kcs_hw_init(struct starfive_kcs_bmc *priv)
> +{
> + unsigned long flags;
> +
> + /* Restore the enables, e.g. after an eSPI bus reset */
> + spin_lock_irqsave(&priv->ie_lock, flags);
> + starfive_kcs_write_ie(priv);
> + spin_unlock_irqrestore(&priv->ie_lock, flags);
> +}
> +
> +static irqreturn_t starfive_kcs_irq(int irq, void *arg)
> +{
> + /* The interrupt deasserts once the client has read IDR */
> + return kcs_bmc_handle_event(arg);
> +}
> +
> +/*
> + * "espi_rst" is a dedicated interrupt line which carries a single event: the
> + * host has de-asserted the eSPI bus reset of the SIO block this channel
> + * belongs to. The line is requested with IRQF_SHARED only because every
> + * function of that SIO block (KCS, BT, mailbox, ...) listens to the same
> + * event and has to reprogram its own registers when it fires. It is not
> + * shared with unrelated interrupt sources and there is no per-function
> + * status bit to test, so each occurrence is relevant to all handlers and is
> + * claimed unconditionally. Rewriting KCS_INT from the shadow is idempotent.
> + */
> +static irqreturn_t starfive_espi_rst_deassert_irq(int irq, void *arg)
> +{
> + struct kcs_bmc_device *kcs_bmc = arg;
> + struct starfive_kcs_bmc *priv = to_starfive_kcs_bmc(kcs_bmc);
> +
I'm not sure what the hardware does, just making sure you don't want
to set ie_en to zero or something here.
> + starfive_kcs_hw_init(priv);
> +
> + return IRQ_HANDLED;
> +}
> +
> +static int starfive_kcs_config_irq(struct kcs_bmc_device *kcs_bmc,
> + struct platform_device *pdev)
> +{
> + struct device *dev = &pdev->dev;
> + int rc, irq;
> +
> + irq = platform_get_irq_byname(pdev, "kcs");
> + if (irq < 0)
> + return irq;
> +
> + rc = devm_request_irq(dev, irq, starfive_kcs_irq, 0,
> + dev_name(dev), kcs_bmc);
> + if (rc < 0)
> + return dev_err_probe(dev, rc,
> + "Unable to request kcs IRQ %d\n", irq);
> +
> + irq = platform_get_irq_byname(pdev, "espi_rst");
> + if (irq < 0)
> + return irq;
> +
> + rc = devm_request_irq(dev, irq, starfive_espi_rst_deassert_irq,
> + IRQF_SHARED | IRQF_TRIGGER_RISING,
> + dev_name(dev), kcs_bmc);
> + if (rc < 0)
> + return dev_err_probe(dev, rc,
> + "Unable to request espi reset IRQ %d\n", irq);
> +
> + return 0;
> +}
> +
> +static const struct kcs_bmc_device_ops starfive_kcs_ops = {
> + .irq_mask_update = starfive_kcs_irq_mask_update,
> + .io_inputb = starfive_kcs_inb,
> + .io_outputb = starfive_kcs_outb,
> + .io_updateb = starfive_kcs_updateb,
> +};
> +
> +/*
> + * The channel number is not described in the devicetree, it follows from the
> + * position of the channel in the SIO block and from the id of that block.
> + */
> +static int starfive_kcs_of_get_channel(struct device *dev, u32 *chan)
> +{
> + struct device_node *np = dev->of_node;
> + u32 sio_id, idx;
> + u64 offset;
> + int rc;
> +
> + struct device_node *sio __free(device_node) = of_get_parent(np);
> +
> + /* Don't translate the address, the offset in the SIO block is wanted */
> + rc = of_property_read_reg(np, 0, &offset, NULL);
> + if (rc)
> + return rc;
> +
> + if (offset < KCS_CHANNEL_BASE ||
> + offset >= KCS_CHANNEL_BASE + KCS_CHANNELS_PER_SIO * KCS_CHANNEL_STRIDE ||
> + offset % KCS_CHANNEL_STRIDE)
> + return -EINVAL;
> +
> + idx = ((u32)offset - KCS_CHANNEL_BASE) / KCS_CHANNEL_STRIDE;
> +
> + rc = of_property_read_u32(sio, "starfive,sio-id", &sio_id);
> + if (rc)
> + return rc;
> +
> + if (sio_id >= KCS_SIO_MAX)
> + return -EINVAL;
> +
> + *chan = sio_id * KCS_CHANNELS_PER_SIO + idx;
> +
> + return 0;
> +}
> +
> +static int starfive_kcs_probe(struct platform_device *pdev)
> +{
> + struct device *dev = &pdev->dev;
> + struct starfive_kcs_bmc *priv;
> + struct kcs_bmc_device *kcs_bmc;
> + u32 chan;
> + int rc;
> +
> + rc = starfive_kcs_of_get_channel(dev, &chan);
> + if (rc)
> + return dev_err_probe(dev, rc, "Unable to determine the channel\n");
> +
> + priv = devm_kzalloc(dev, sizeof(*priv), GFP_KERNEL);
> + if (!priv)
> + return -ENOMEM;
> +
> + spin_lock_init(&priv->ie_lock);
> +
> + priv->map = device_node_to_regmap(dev->of_node);
> + if (IS_ERR(priv->map))
> + return dev_err_probe(dev, PTR_ERR(priv->map),
> + "Couldn't get regmap\n");
> +
> + kcs_bmc = &priv->kcs_bmc;
> + kcs_bmc->dev = dev;
> + kcs_bmc->channel = chan;
> + kcs_bmc->ioreg.idr = KCS_DI;
> + kcs_bmc->ioreg.odr = KCS_DO;
> + kcs_bmc->ioreg.str = KCS_STS;
> + kcs_bmc->ops = &starfive_kcs_ops;
> +
> + platform_set_drvdata(pdev, priv);
> +
> + starfive_kcs_hw_init(priv);
> + rc = starfive_kcs_config_irq(kcs_bmc, pdev);
> + if (rc)
> + return rc;
Can order matter here? Can an interrupt come in between the above
and below calls?
> +
> + rc = kcs_bmc_add_device(kcs_bmc);
> + if (rc)
> + return dev_err_probe(dev, rc, "Failed to register channel %u\n",
> + kcs_bmc->channel);
> +
> + dev_dbg(dev, "Channel=%u idr=0x%x odr=0x%x str=0x%x\n", chan,
> + kcs_bmc->ioreg.idr, kcs_bmc->ioreg.odr, kcs_bmc->ioreg.str);
> +
> + return 0;
> +}
> +
> +static void starfive_kcs_remove(struct platform_device *pdev)
> +{
> + struct starfive_kcs_bmc *priv = platform_get_drvdata(pdev);
> + struct kcs_bmc_device *kcs_bmc = &priv->kcs_bmc;
> +
> + kcs_bmc_remove_device(kcs_bmc);
> +
> + starfive_kcs_irq_mask_update(kcs_bmc,
> + (KCS_BMC_EVENT_TYPE_IBF |
> + KCS_BMC_EVENT_TYPE_OBE),
> + 0);
Would order matter in the above two? Can an interrupt come in after
the BMC has been removed?
Also, starfive_espi_rst_deassert_irq()?
> +}
> +
> +static const struct of_device_id starfive_kcs_bmc_match[] = {
> + { .compatible = "starfive,jhb100-kcs-bmc" },
> + { }
> +};
> +MODULE_DEVICE_TABLE(of, starfive_kcs_bmc_match);
> +
> +static struct platform_driver starfive_kcs_bmc_driver = {
> + .driver = {
> + .name = DEVICE_NAME,
> + .of_match_table = starfive_kcs_bmc_match,
> + .suppress_bind_attrs = true,
> + },
> + .probe = starfive_kcs_probe,
> + .remove = starfive_kcs_remove,
> +};
> +module_platform_driver(starfive_kcs_bmc_driver);
> +
> +MODULE_LICENSE("GPL");
> +MODULE_AUTHOR("Mason Huo <mason.huo@xxxxxxxxxxxxxxxx>");
> +MODULE_DESCRIPTION("StarFive device interface to the KCS BMC device");
> --
> 2.50.1
>