rt-thread/documentation/6.components/device-driver/syscon/syscon.md

@page page_device_syscon System controller (Syscon)

Syscon (system control registers)

Syscon is a small DM helper for a shared MMIO register block that several drivers touch (reboot magic, boot mode, LED bits, strap latches). One struct rt_syscon maps the region once and serializes 32-bit accesses with a per-instance spinlock.

Piece	Path
API	components/drivers/include/drivers/syscon.h
Provider	components/drivers/mfd/mfd-syscon.c
Kconfig	RT_USING_MFD → RT_MFD_SYSCON (needs RT_USING_DM, RT_USING_OFW)

---

End-to-end flow

DT: compatible "syscon" (+ reg)
        ↓
INIT_SUBSYS: platform driver "mfd-syscon" registered
        ↓
INIT_PLATFORM: platform device probe → syscon_probe()
        ├─ rt_ofw_get_address → rt_ioremap
        ├─ insert on global _syscon_nodes list
        └─ rt_ofw_data(np) = syscon
        ↓
Consumer (reboot, LED, …) in its probe:
        rt_syscon_find_by_ofw_phandle(np, "regmap")
        or rt_syscon_find_by_ofw_node(parent_np)
        ↓
rt_syscon_read / write / update_bits (spinlock, HWREG32)

Lazy probe: If a node was not probed at init but is compatible = "syscon" or "simple-mfd", rt_syscon_find_by_ofw_node can run syscon_probe on a stack rt_platform_device and then return rt_ofw_data(np). Prefer normal DT probe for the syscon node so iomem_base exists before consumers start.

---

struct rt_syscon

struct rt_syscon {
    rt_list_t list;
    struct rt_ofw_node *np;
    void *iomem_base;
    rt_size_t iomem_size;      /* byte size of mapped region */
    struct rt_spinlock rw_lock;
};

Field	Set by
np	Syscon DT node
iomem_base / iomem_size	First reg region in syscon_probe
list	Global registry _syscon_nodes (lookup under _syscon_nodes_lock)

Published to OFW: rt_ofw_data(syscon_np) = syscon after probe.

---

Provider driver (mfd-syscon.c)

static const struct rt_ofw_node_id syscon_ofw_ids[] = {
    { .compatible = "syscon" },
    { /* sentinel */ },
};

static struct rt_platform_driver syscon_driver = {
    .name = "mfd-syscon",
    .ids = syscon_ofw_ids,
    .probe = syscon_probe,
    .remove = syscon_remove,
};
INIT_SUBSYS_EXPORT(syscon_drv_register);

Step (syscon_probe)	Action
Map	rt_ofw_get_address(np, 0, &addr, &size) → rt_ioremap
Register	Insert into _syscon_nodes, init rw_lock
Publish	rt_ofw_data(np) = syscon, pdev->parent.user_data = syscon

compatible = "simple-mfd" is not in syscon_ofw_ids; those nodes are only handled via rt_syscon_find_by_ofw_node lazy probe (or as parent of children that call find on the parent).

---

Access API

All three functions use byte offset into iomem_base (must satisfy offset < iomem_size). Each access is one 32-bit HWREG32 — offsets are not auto-scaled to word index.

rt_err_t rt_syscon_read(struct rt_syscon *syscon, rt_off_t offset, rt_uint32_t *out_val);
rt_err_t rt_syscon_write(struct rt_syscon *syscon, rt_off_t offset, rt_uint32_t val);
rt_err_t rt_syscon_update_bits(struct rt_syscon *syscon, rt_off_t offset,
        rt_uint32_t mask, rt_uint32_t val);

rt_syscon_update_bits (under spinlock):

new = (old & ~mask) | (val & mask)

Only bits set in mask are changed; val bits outside mask are ignored. Safe for typical RMW glue; W1C / hardware that ignores read data may need a dedicated driver instead of blind update_bits.

Callable from thread or ISR context (spinlock-based); keep critical sections short.

---

Lookup helpers

API	Use
rt_syscon_find_by_ofw_node(np)	Direct syscon (or simple-mfd) node; walks global list, else lazy syscon_probe
rt_syscon_find_by_ofw_phandle(np, "regmap")	Consumer node property → target syscon (Linux-style regmap phandle)
rt_syscon_find_by_ofw_compatible("vendor,foo-syscon")	First matching compatible in DT

Returns RT_NULL if map fails or compatible is not syscon / simple-mfd (for lazy path).

---

Device tree

Provider node

syscon: syscon@10000000 {
    compatible = "syscon";
    reg = <0x10000000 0x1000>;
};

Consumer: reboot (syscon-reboot)

reboot {
    compatible = "syscon-reboot";
    regmap = <&syscon>;
    offset = <0x200>;
    mask = <0x1>;
    value = <0x1>;
};

Kconfig: RT_POWER_RESET_SYSCON_REBOOT. Installs rt_dm_machine_reset hook that calls rt_syscon_update_bits.

Consumer: poweroff (syscon-poweroff)

Same pattern with compatible = "syscon-poweroff" → rt_dm_machine_poweroff.

Consumer: reboot mode (syscon-reboot-mode)

Child under syscon (or parent resolved via rt_ofw_get_parent); writes boot mode magic via reboot-mode helper.

Consumer: LED (register-bit-led)

syscon: syscon@10000000 {
    compatible = "syscon";
    reg = <0x10000000 0x100>;

    led0 {
        compatible = "register-bit-led";
        offset = <0x4>;
        mask = <0x10>;
        default-state = "off";
    };
};

led-syscon.c: rt_syscon_find_by_ofw_node(parent), rt_syscon_read / update_bits for on/off. See @ref page_device_led_dm.

---

Kconfig and related drivers

Option	Role
RT_USING_MFD	MFD menu (requires RT_USING_DM)
RT_MFD_SYSCON	Build mfd-syscon.c
RT_POWER_RESET_SYSCON_REBOOT	power/reset/syscon-reboot.c
RT_POWER_RESET_SYSCON_POWEROFF	power/reset/syscon-poweroff.c
RT_POWER_RESET_SYSCON_REBOOT_MODE	power/reset/syscon-reboot-mode.c
RT_LED_SYSCON	led/led-syscon.c

---

Writing a consumer driver

1. In probe, obtain struct rt_syscon * via phandle or parent node — do not rt_ioremap the same reg again.
2. Parse offset, mask, value (or chip-specific properties) from your DT node.
3. Use rt_syscon_read for status; rt_syscon_update_bits for controlled bit changes.
4. Coordinate with @ref page_device_power_board_reset if you hook rt_dm_machine_reset / rt_dm_machine_poweroff (only one handler).

---

Pitfalls

• Offset vs register index: API uses byte offset; register N is often N * 4 depending on TRM.
• Region size: offset >= iomem_size → -RT_EINVAL — extend reg in DTS if layout needs more space.
• 64-bit / 16-bit only registers: not supported by this API — use a dedicated MMIO driver.
• Lazy vs platform probe: consumers that find before syscon INIT_PLATFORM probe may rely on lazy probe; ordering bugs are easier if the syscon node is a normal platform device probed first.
• Mask/value: update_bits(..., mask, val) clears all mask bits then sets val & mask — do not use for status bits that clear on read (W1C).
• Duplicate mapping: multiple drivers ioremap the same physical address without syscon → races; centralize on one rt_syscon.

---

See also

• @ref page_device_platform — RT_PLATFORM_DRIVER_EXPORT, probe order
• @ref page_device_power_board_reset — machine reset / poweroff hooks
• @ref page_device_led_dm — register-bit-led
• @ref page_device_ofw — phandles, rt_ofw_data
• components/drivers/include/drivers/syscon.h
• components/drivers/mfd/mfd-syscon.c