Device model

Common core of every hardware device: controllers, buses and the peripherals on them. More...

Data Structures
struct	pbl_device_state
	Runtime state of a device. More...
struct	pbl_device
	A hardware device. More...

Macros
#define	PBL_DEVICE_DEPS(...)   ((const struct pbl_device *const[]){__VA_ARGS__, nullptr})
	Static dependency list for struct pbl_device::deps.
#define	PBL_DEVICE_STATE_DEFINE(sym)   static struct pbl_device_state sym##_device_state
	Define the runtime state of device instance sym.
#define	PBL_DEVICE_INIT(sym, _name, _init, _parent, _deps)
	Initializer for the struct pbl_device of device instance sym.
#define	PBL_DEVICE_TABLE_SECTION   PBL_SECTION(".pbl_devices")
#define	PBL_DEVICE_REGISTER(sym, dev)    static const struct pbl_device *const sym##_device_entry PBL_USED PBL_DEVICE_TABLE_SECTION = (dev)
	Add a device to the table pbl_device_init_all() walks.

Enumerations
enum	pbl_device_status { PBL_DEVICE_UNINIT , PBL_DEVICE_INITIALIZING , PBL_DEVICE_READY , PBL_DEVICE_FAILED }
	Device status. More...

Functions
int	pbl_device_init (const struct pbl_device *dev)
	Initialize a device, its parent and deps first.
bool	pbl_device_is_ready (const struct pbl_device *dev)
	Check whether a device is initialized.
int	pbl_device_init_all (void)
	Initialize every registered device.
int	pbl_device_init_children (const struct pbl_device *parent)
	Initialize every registered device whose parent is parent.

Detailed Description

Common core of every hardware device: controllers, buses and the peripherals on them.

A device class embeds struct pbl_device, a driver embeds the class struct, and container_of() walks back out. Devices are const and live in flash; the only RAM is the state they point to.

Instances are defined with the PBL_<DRIVER>_DEFINE() macro of their driver, built from PBL_DEVICE_STATE_DEFINE(), PBL_DEVICE_INIT() and PBL_DEVICE_REGISTER(). pbl_device_init_all() brings every registered device up, dependencies first: a device's parent and deps are initialized before it, and a driver's init calls pbl_device_init() on the devices it uses.

An init returning -ENODEV means the device is not present: that is not logged as an error.

struct foo {
  struct pbl_device dev;
  uint8_t addr;
};
 
static int prv_foo_init(const struct pbl_device *dev) {
  const struct foo *foo = container_of(dev, const struct foo, dev);
  return prv_probe(foo->addr) ? 0 : -ENODEV;
}
 
PBL_DEVICE_STATE_DEFINE(s_foo);
static const struct foo s_foo = {
  .dev = PBL_DEVICE_INIT(s_foo, "foo", prv_foo_init, &s_bus.dev, PBL_DEVICE_DEPS(&s_ldo.dev)),
  .addr = 0x18,
};
PBL_DEVICE_REGISTER(s_foo, &s_foo.dev);

---

Data Structure Documentation

pbl_device_state

struct pbl_device_state

Runtime state of a device.

Data Fields
int	res	Result of the initialization.
uint8_t	status	One of pbl_device_status.

Macro Definition Documentation

PBL_DEVICE_DEPS

#define PBL_DEVICE_DEPS

(

...

)

((const struct pbl_device *const[]){__VA_ARGS__, nullptr})

Static dependency list for struct pbl_device::deps.

PBL_DEVICE_INIT

#define PBL_DEVICE_INIT	(		sym,
			_name,
			_init,
			_parent,
			_deps
	)

Value:

  {                                                        \
    .name = (_name),                                       \
    .init = (_init),                                       \
    .parent = (_parent),                                   \
    .deps = (_deps),                                       \
    .state = &sym##_device_state,                          \
  }

Initializer for the struct pbl_device of device instance sym.

Parameters

sym	Symbol of the device instance, with its state defined by PBL_DEVICE_STATE_DEFINE().
_name	Name.
_init	Init function, or NULL.
_parent	Parent device, or NULL.
_deps	Dependencies from PBL_DEVICE_DEPS(), or NULL.

PBL_DEVICE_REGISTER

#define PBL_DEVICE_REGISTER	(		sym,
			dev
	)		static const struct pbl_device *const sym##_device_entry PBL_USED PBL_DEVICE_TABLE_SECTION = (dev)

Add a device to the table pbl_device_init_all() walks.

Parameters

sym	Symbol of the device instance.
dev	Pointer to its struct pbl_device.

PBL_DEVICE_STATE_DEFINE

#define PBL_DEVICE_STATE_DEFINE

(

sym

)

static struct pbl_device_state sym##_device_state

Define the runtime state of device instance sym.

Parameters

sym	Symbol of the device instance.

PBL_DEVICE_TABLE_SECTION

#define PBL_DEVICE_TABLE_SECTION   PBL_SECTION(".pbl_devices")

Enumeration Type Documentation

pbl_device_status

enum pbl_device_status

Device status.

Enumerator
PBL_DEVICE_UNINIT	Not initialized yet.
PBL_DEVICE_INITIALIZING	Initialization in progress.
PBL_DEVICE_READY	Initialized.
PBL_DEVICE_FAILED	Initialization failed, or the device is not present.

Function Documentation

pbl_device_init()

int pbl_device_init

(

const struct pbl_device *

dev

)

Initialize a device, its parent and deps first.

A no-op once the device is ready or has failed. A dependency cycle asserts.

Parameters

dev

Device.

Returns

0, the error its init returned, or -ENODEV if its parent or a dep failed.

pbl_device_init_all()

int pbl_device_init_all

(

void

)

Initialize every registered device.

Returns

Number of devices that failed or are not present.

pbl_device_init_children()

int pbl_device_init_children

(

const struct pbl_device *

parent

)

Initialize every registered device whose parent is parent.

For a multi-function device to bring its functions up from its own init.

Parameters

parent

Parent device.

Returns

Number of devices that failed or are not present.

pbl_device_is_ready()

bool pbl_device_is_ready

(

const struct pbl_device *

dev

)

Check whether a device is initialized.

Parameters

dev

Device.

Returns

True if the device is ready.