MFD M5PM1 Interface

M5Stack M5PM1 power management companion MCU interface. More...

Files
file	m5pm1.h
	Header file for the M5Stack M5PM1 MFD driver.

Enumerations
enum	m5pm1_pin_func {   M5PM1_PIN_FUNC_GPIO = 0 , M5PM1_PIN_FUNC_IRQ , M5PM1_PIN_FUNC_ADC , M5PM1_PIN_FUNC_PWM ,   M5PM1_PIN_FUNC_NEOPIXEL }
	Semantic function of an M5PM1 multiplexed pin. More...

Functions
int	mfd_m5pm1_read_reg (const struct device *dev, uint8_t reg, uint8_t *val)
	Read a single 8-bit M5PM1 register.
int	mfd_m5pm1_write_reg (const struct device *dev, uint8_t reg, uint8_t val)
	Write a single 8-bit M5PM1 register.
int	mfd_m5pm1_update_reg (const struct device *dev, uint8_t reg, uint8_t mask, uint8_t val)
	Read-modify-write selected bits of an M5PM1 register.
int	mfd_m5pm1_toggle_reg (const struct device *dev, uint8_t reg, uint8_t mask)
	Toggle selected bits of an M5PM1 register.
int	mfd_m5pm1_burst_read (const struct device *dev, uint8_t reg, uint8_t *buf, size_t len)
	Read multiple consecutive M5PM1 registers in a single I2C transaction.
int	mfd_m5pm1_burst_write (const struct device *dev, uint8_t reg, const uint8_t *buf, size_t len)
	Write multiple consecutive M5PM1 registers in a single I2C transaction.
int	mfd_m5pm1_pin_request (const struct device *dev, const struct device *client, uint8_t pin, enum m5pm1_pin_func func)
	Claim a pin for a given function on behalf of a sibling driver.
int	mfd_m5pm1_pin_release (const struct device *dev, const struct device *client, uint8_t pin)
	Release a pin previously claimed with mfd_m5pm1_pin_request().

Detailed Description

M5Stack M5PM1 power management companion MCU interface.

Since

4.5

Version

0.1.0

The M5PM1 is a small companion microcontroller used on M5Stack boards to provide power management (battery charging, switchable rails), a small bank of GPIOs and an on-chip ADC. This MFD driver owns the I2C transport and serializes register access; sibling GPIO, ADC and regulator drivers implement their domain-specific functionality on top of these primitives.

Enumeration Type Documentation

m5pm1_pin_func

enum m5pm1_pin_func

#include <zephyr/drivers/mfd/m5pm1.h>

Semantic function of an M5PM1 multiplexed pin.

Each pin selects its function through a 2-bit field in GPIO_FUNC0/GPIO_FUNC1. The standard GPIO and IRQ functions exist on every pin, but the "special" function (register value 0b11) means a different peripheral on each pin, so validity is checked per-pin (see mfd_m5pm1_pin_request()):

• IO0: M5PM1_PIN_FUNC_NEOPIXEL
• IO1, IO2: M5PM1_PIN_FUNC_ADC
• IO3, IO4: M5PM1_PIN_FUNC_PWM

Enumerator
M5PM1_PIN_FUNC_GPIO	Standard GPIO (FUNC field 0b00).
M5PM1_PIN_FUNC_IRQ	IRQ input (FUNC field 0b01).
M5PM1_PIN_FUNC_ADC	ADC input (FUNC field 0b11, IO1/IO2 only).
M5PM1_PIN_FUNC_PWM	PWM output (FUNC field 0b11, IO3/IO4 only).
M5PM1_PIN_FUNC_NEOPIXEL	NeoPixel output (FUNC field 0b11, IO0 only).

Function Documentation

mfd_m5pm1_burst_read()

int mfd_m5pm1_burst_read	(	const struct device *	dev,
		uint8_t	reg,
		uint8_t *	buf,
		size_t	len )

#include <zephyr/drivers/mfd/m5pm1.h>

Read multiple consecutive M5PM1 registers in a single I2C transaction.

Uses a single repeated-start I2C transfer so the device sees the read as atomic, which matters for register pairs latched on the low-byte read (e.g. ADC sample registers).

Important

The M5PM1 only allows continuous reads of certain register ranges, please refer to the datasheet for more details.

Parameters

	dev	M5PM1 MFD device.
	reg	Address of the first register to read.
[out]	buf	Buffer that receives len consecutive register values.
	len	Number of bytes to read.

Return values

0	Success.
-errno	I2C transfer error (see i2c_burst_read_dt()).

mfd_m5pm1_burst_write()

int mfd_m5pm1_burst_write	(	const struct device *	dev,
		uint8_t	reg,
		const uint8_t *	buf,
		size_t	len )

#include <zephyr/drivers/mfd/m5pm1.h>

Write multiple consecutive M5PM1 registers in a single I2C transaction.

Counterpart to mfd_m5pm1_burst_read().

Important

The M5PM1 only allows continuous writes of certain register ranges, please refer to the datasheet for more details.

Parameters

dev	M5PM1 MFD device.
reg	Address of the first register to write.
buf	Buffer holding len consecutive register values.
len	Number of bytes to write.

Return values

0	Success.
-errno	I2C transfer error (see i2c_burst_write_dt()).

mfd_m5pm1_pin_release()

int mfd_m5pm1_pin_release	(	const struct device *	dev,
		const struct device *	client,
		uint8_t	pin )

#include <zephyr/drivers/mfd/m5pm1.h>

Release a pin previously claimed with mfd_m5pm1_pin_request().

If client currently owns pin, its function field is reset to standard GPIO and the ownership is cleared. Releasing a pin not owned by client is a no-op.

Parameters

dev	M5PM1 MFD device.
client	Device that owns the pin.
pin	Pin index (0..M5PM1_GPIO_COUNT-1).

Return values

0	Success (including the no-op case).
-EINVAL	pin is out of range.
-errno	I2C transfer error.

mfd_m5pm1_pin_request()

int mfd_m5pm1_pin_request	(	const struct device *	dev,
		const struct device *	client,
		uint8_t	pin,
		enum m5pm1_pin_func	func )

#include <zephyr/drivers/mfd/m5pm1.h>

Claim a pin for a given function on behalf of a sibling driver.

The M5PM1 pins are multiplexed between several peripherals (GPIO, ADC, PWM, NeoPixel) whose sibling drivers all share the GPIO_FUNC0/GPIO_FUNC1 select registers. This routine centralizes that mux: it validates that func is available on pin, programs the pin's function field and records client as the pin's owner. A pin can only be owned by a single client; this guards against a board accidentally wiring the same pin to two incompatible consumers.

Requests are idempotent for the current owner: the same client may call again (e.g. to change its own function) without error.

Parameters

dev	M5PM1 MFD device.
client	Device requesting the pin (used as the ownership token).
pin	Pin index (0..M5PM1_GPIO_COUNT-1).
func	Function to configure (see m5pm1_pin_func).

Return values

0	Success.
-EINVAL	pin is out of range.
-ENOTSUP	func is not available on pin.
-EBUSY	pin is already owned by a different client.
-errno	I2C transfer error.

mfd_m5pm1_read_reg()

int mfd_m5pm1_read_reg	(	const struct device *	dev,
		uint8_t	reg,
		uint8_t *	val )

#include <zephyr/drivers/mfd/m5pm1.h>

Read a single 8-bit M5PM1 register.

Parameters

	dev	M5PM1 MFD device.
	reg	Register address.
[out]	val	Pointer that receives the register value.

Return values

0	On success.
-errno	On I2C transfer error (see i2c_reg_read_byte_dt()).

mfd_m5pm1_toggle_reg()

int mfd_m5pm1_toggle_reg	(	const struct device *	dev,
		uint8_t	reg,
		uint8_t	mask )

#include <zephyr/drivers/mfd/m5pm1.h>

Toggle selected bits of an M5PM1 register.

Performs an atomic (mutex-protected) read-modify-write of reg, inverting the bits selected by mask. Holding the lock across the read and write makes the toggle atomic with respect to the other mfd_m5pm1_*() accessors.

Parameters

dev	M5PM1 MFD device.
reg	Register address.
mask	Bitmask of bits to invert.

Return values

0	Success.
-errno	I2C transfer error.

mfd_m5pm1_update_reg()

int mfd_m5pm1_update_reg	(	const struct device *	dev,
		uint8_t	reg,
		uint8_t	mask,
		uint8_t	val )

#include <zephyr/drivers/mfd/m5pm1.h>

Read-modify-write selected bits of an M5PM1 register.

Performs an atomic (mutex-protected) read-modify-write of reg, replacing the bits selected by mask with the corresponding bits from val.

Parameters

dev	M5PM1 MFD device.
reg	Register address.
mask	Bitmask of bits to update.
val	New value for the bits selected by mask (other bits ignored).

Return values

0	Success.
-errno	I2C transfer error (see i2c_reg_update_byte_dt()).

mfd_m5pm1_write_reg()

int mfd_m5pm1_write_reg	(	const struct device *	dev,
		uint8_t	reg,
		uint8_t	val )

#include <zephyr/drivers/mfd/m5pm1.h>

Write a single 8-bit M5PM1 register.

Parameters

dev	M5PM1 MFD device.
reg	Register address.
val	Value to write.

Return values

0	On Success.
-errno	I2C transfer error (see i2c_reg_write_byte_dt()).