Black Box

Data Structures
struct	BlackBoxEnt

Macros
#define	BLACKBOX_SIZE   65535
	Size of the black box buffer in bytes (64KB)
#define	bboxGetVal(ent)   ((char*)ent + offsetof(BlackBoxEnt, name) + ent->namelen)
#define	bboxEntSize(ent)   (offsetof(BlackBoxEnt, name) + ent->namelen + ent->vallen)

Typedefs
typedef struct BlackBoxEnt	BlackBoxEnt

Enumerations
enum	BLACKBOX_FLAGS { BBox_Private = 0x01 }
	Flags for black box entries. More...

Functions
void	bboxInit ()
void	bboxSet (strref name, strref val, uint8 flags)
void	bboxDelete (strref name)

Variables
char	dbgBlackBox []
	Global black box buffer visible to debuggers and crash dump analyzers.

Detailed Description

Fixed-size key-value data store optimized for post-mortem crash analysis.

The black box is a fixed 64KB buffer that stores debugging metadata as key-value pairs in a custom format designed to be parsed from raw memory dumps. This allows crash analyzers to extract application state even when the process is completely dead.

Design characteristics:

• Fixed 64KB size (BLACKBOX_SIZE) with inline allocation
• Globally accessible symbol (dbgBlackBox) visible to debuggers
• Doubly-linked list structure for sequential traversal
• Best-fit allocation strategy with coalescing
• Thread-safe with internal locking
• Supports in-place updates when values shrink or stay same size

Typical use cases:

• Storing application version, build info, session IDs
• Recording recent operation history or state transitions
• Capturing configuration values that might affect behavior
• Logging error codes or failure conditions

Example:

bboxInit();
bboxSet(_S"version", _S"1.0.3", 0);
bboxSet(_S"session", sessionId, 0);
bboxSet(_S"username", username, BBox_Private);

Macro Definition Documentation

bboxEntSize

#define bboxEntSize

(

ent

)

(offsetof(BlackBoxEnt, name) + ent->namelen + ent->vallen)

Calculate total size of a black box entry in bytes

size_t bboxEntSize(ent)

Parameters

ent	Pointer to BlackBoxEnt structure

Returns

Total size including structure, name, and value

Definition at line 78 of file blackbox.h.

bboxGetVal

#define bboxGetVal

(

ent

)

((char*)ent + offsetof(BlackBoxEnt, name) + ent->namelen)

Get pointer to value string within a black box entry

char* bboxGetVal(ent)

Parameters

ent	Pointer to BlackBoxEnt structure

Returns

Pointer to the null-terminated value string

Definition at line 70 of file blackbox.h.

Typedef Documentation

BlackBoxEnt

typedef struct BlackBoxEnt BlackBoxEnt

Black box entry structure for offline parsing

Internal structure used to parse black box contents from crash dumps. Entries are stored as a doubly-linked list with variable-length name and value.

Enumeration Type Documentation

BLACKBOX_FLAGS

enum BLACKBOX_FLAGS

Flags for black box entries.

Enumerator
BBox_Private	Entry contains potentially private data; allow user opt-out in crash reports.

Definition at line 81 of file blackbox.h.

Function Documentation

bboxDelete()

void bboxDelete

(

strref

name

)

Remove an entry from the black box

Parameters

name	Key name of entry to delete

Frees the space used by the entry. If the entry doesn't exist, this is a no-op.

bboxInit()

void bboxInit

(

)

Initialize the black box system

Must be called before using bboxSet or bboxDelete. Initializes internal mutex, index, and free list.

bboxSet()

void bboxSet	(	strref	name,
		strref	val,
		uint8	flags
	)

Store or update a key-value pair in the black box

Parameters

name	Key name (stored by reference, must remain valid)
val	Value to store (copied into black box)
flags	Optional flags from BLACKBOX_FLAGS enum (0 for none)

If an entry with the same name already exists:

• If new value fits in existing space, updates in-place
• Otherwise, deletes old entry and allocates new space

Uses best-fit allocation strategy. If blackbox is full, the operation silently fails (no error or assertion).