Core dumps

Save the state of the system when it crashes, for analysis after the reset. More...

Modules
	Architecture interface
	What an architecture implements to support core dumps.
	Backends
	Outputs of core dumps.
	Image format
	Layout of a core dump image, parsed by tools/readcore.py.

Data Structures
struct	pbl_coredump_region
	Memory region to dump. More...
struct	pbl_coredump_metadata
	Identification of the system that wrote a dump. More...
struct	pbl_coredump_stored
	Dump stored by a backend. More...

Macros
#define	PBL_COREDUMP__REGION_SECTION(_name)    PBL_ALIGNED(4) PBL_SECTION(".pbl_coredump_regions." #_name)
#define	PBL_COREDUMP_REGION_DEFINE(_name, _start, _size)
	Define a memory region to dump.
#define	PBL_COREDUMP_LATE_REGION_DEFINE(_name, _start, _size, _prepare)
	Define a memory region that is dumped after the threads.

Functions
void	pbl_coredump_trigger (bool forced)
	Write a core dump and reset.
void	pbl_coredump_platform_prepare (struct pbl_coredump_metadata *metadata)
	Prepare the system for a dump, implemented by the platform.
int	pbl_coredump_stored_find (bool unread_only, struct pbl_coredump_stored *stored)
	Find the most recent stored dump of the first backend that has one.
int	pbl_coredump_stored_size (const struct pbl_coredump_stored *stored, uint32_t *size)
	Get the size of a stored dump.
int	pbl_coredump_stored_read (const struct pbl_coredump_stored *stored, uint32_t offset, void *buf, size_t len)
	Read a stored dump.
int	pbl_coredump_stored_mark_read (const struct pbl_coredump_stored *stored)
	Mark a stored dump as read, so it can be replaced.

Detailed Description

Save the state of the system when it crashes, for analysis after the reset.

A dump holds the memory regions defined with PBL_COREDUMP_REGION_DEFINE and the registers of every thread. It is written to every backend, see Backends, and read back after the reset through the pbl_coredump_stored_* functions.

---

Data Structure Documentation

pbl_coredump_metadata

struct pbl_coredump_metadata

Identification of the system that wrote a dump.

Data Fields
char	build_id[64]	Firmware build ID.
char	serial_number[16]	Device serial number.

pbl_coredump_stored

struct pbl_coredump_stored

Dump stored by a backend.

Data Fields
const struct pbl_coredump_backend *	backend	Backend storing the dump.
uint32_t	id	Identifier of the dump in the backend.

Macro Definition Documentation

PBL_COREDUMP__REGION_SECTION

#define PBL_COREDUMP__REGION_SECTION

(

_name

)

PBL_ALIGNED(4) PBL_SECTION(".pbl_coredump_regions." #_name)

PBL_COREDUMP_LATE_REGION_DEFINE

#define PBL_COREDUMP_LATE_REGION_DEFINE	(		_name,
			_start,
			_size,
			_prepare
	)

Value:

  static const struct pbl_coredump_region _pbl_coredump_region_##_name PBL_USED \
  PBL_COREDUMP__REGION_SECTION(                                                 \
      _name) = {.start = (_start), .size = (_size), .prepare = (_prepare), .late = true}

Define a memory region that is dumped after the threads.

For memory whose read could hang or fault, so the rest of the dump is saved first.

Parameters

_name	Region name, also its identifier.
_start	Start address, a constant expression.
_size	Size in bytes, a constant expression.
_prepare	Function that makes the region readable, or NULL.

PBL_COREDUMP_REGION_DEFINE

#define PBL_COREDUMP_REGION_DEFINE	(		_name,
			_start,
			_size
	)

Value:

  static const struct pbl_coredump_region _pbl_coredump_region_##_name PBL_USED \
  PBL_COREDUMP__REGION_SECTION(_name) = {.start = (_start), .size = (_size)}

Define a memory region to dump.

Parameters

_name	Region name, also its identifier.
_start	Start address, a constant expression.
_size	Size in bytes, a constant expression.

Function Documentation

pbl_coredump_platform_prepare()

void pbl_coredump_platform_prepare

(

struct pbl_coredump_metadata *

metadata

)

Prepare the system for a dump, implemented by the platform.

Runs without OS services, once the backends are initialized and before they touch what they store. Drivers that a backend uses, like flash, already work.

Parameters

[out]

metadata

Identification to store in the dump.

pbl_coredump_stored_find()

int pbl_coredump_stored_find	(	bool	unread_only,
		struct pbl_coredump_stored *	stored
	)

Find the most recent stored dump of the first backend that has one.

Parameters

	unread_only	Only consider dumps that have not been marked as read.
[out]	stored	The dump.

Returns

0 on success, or -ENOENT if there is none.

pbl_coredump_stored_mark_read()

int pbl_coredump_stored_mark_read

(

const struct pbl_coredump_stored *

stored

)

Mark a stored dump as read, so it can be replaced.

Parameters

stored

The dump.

Returns

0 on success, or a negative errno.

pbl_coredump_stored_read()

int pbl_coredump_stored_read	(	const struct pbl_coredump_stored *	stored,
		uint32_t	offset,
		void *	buf,
		size_t	len
	)

Read a stored dump.

Parameters

	stored	The dump.
	offset	Offset in the dump.
[out]	buf	Destination.
	len	Number of bytes to read.

Returns

0 on success, or a negative errno.

pbl_coredump_stored_size()

int pbl_coredump_stored_size	(	const struct pbl_coredump_stored *	stored,
		uint32_t *	size
	)

Get the size of a stored dump.

Parameters

	stored	The dump.
[out]	size	Size in bytes.

Returns

0 on success, or a negative errno, -EBADMSG if the dump is corrupted.

pbl_coredump_trigger()

void pbl_coredump_trigger

(

bool

forced

)

Write a core dump and reset.

Can be called from any context. Does not return, unless entering the dump failed.

Parameters

forced

Replace a stored dump that has not been read yet, however recent.