crash.subsystem.storage.decoders module

class crash.subsystem.storage.decoders.BadBHDecoder(bh: Value)

Bases: Decoder

Placeholder decoder for bad buffer_head pointers

Rather than raise a gdb.NotAvailableError during decoding, we use a BadBHDecoder decoder to annotate where in the chain there was an invalid buffer_head.

Parameters:

bh – The struct buffer_head to be decoded. The value must be of type struct buffer_head.

bh

The struct buffer head that was referenced from the bio. The value is of type struct buffer_head.

Type:

gdb.Value

class crash.subsystem.storage.decoders.BadBioDecoder(bio: Value)

Bases: Decoder

Placeholder decoder for bad bio pointers

Rather than raise a NotAvailableError during decoding, we use a BadBioDecoder decoder to annotate where in the chain there was an invalid bio.

Parameters:

bio – The bio to decode. The value must be of type struct bio.

bio

The bio being decoded. The value is of type struct bio.

Type:

gdb.Value

class crash.subsystem.storage.decoders.Decoder(value: Value = None)

Bases: object

Decoder objects are used to unwind the storage stack

They are relatively lightweight at runtime, meaning that the object is initialized but not decoded until it’s needed. The string will be formatted each time, but each Decoder’s interpret() method will be called once.

interpreted

Whether the contents of this Decoder have already been interpreted

Type:

bool

interpret() → None

Interpret the Decoder object

Rather than populate all the fields when they may not be used, we delay interpreting the object until the fields are needed.

This method will examine the object passed to the derived class’s constructor and produce the attributes required for each object.

classmethod register() → None

Registers a decoder with the storage decoder subsystem.

Each Decoder contains the name of an endio routine. When an object that needs decoding is encountered, the endio routine contained in the object is used to look up the decoder for that object.

class crash.subsystem.storage.decoders.GenericBHDecoder(bh: Value)

Bases: Decoder

Decodes a bio that references a struct buffer_head

This method decodes a generic struct buffer_head, when no implementation-specific decoder is available

Parameters:

bh – The struct buffer_head to be decoded. The value must be of type struct buffer_head.

bh

The struct buffer head that was referenced from the bio. The value is of type struct buffer_head.

Type:

gdb.Value

interpret() → None

Interpret the Decoder object

Rather than populate all the fields when they may not be used, we delay interpreting the object until the fields are needed.

This method will examine the object passed to the derived class’s constructor and produce the attributes required for each object.

class crash.subsystem.storage.decoders.GenericBioDecoder(bio: Value)

Bases: Decoder

Placeholder decoder for when we have a valid bio but nothing to decode it

Parameters:

bio – The bio to decode. The value must be of type struct bio.

bio

The bio being decoded. The value is of type struct bio.

Type:

gdb.Value

crash.subsystem.storage.decoders.decode_bh(bh: Value) → Decoder

Decodes a single buffer_head, if possible

This method will return a Decoder object describing a single struct buffer_head after decoding it using a registered decoder, if available.

If no decoder is registered, a generic decoder will be used.

If an invalid object is encountered, a handler decoder will be used.

Parameters:

bh – The buffer_head to decode. The value must be of type struct buffer_head.

Returns:

The decoder appropriate for this buffer_head type

Return type:

Decoder

crash.subsystem.storage.decoders.decode_bio(bio: Value) → Decoder

Decodes a single bio, if possible

This method will return a Decoder object describing a single bio after decoding it using a registered decoder, if available.

If no decoder is registered, a generic decoder will be used.

If an invalid object is encountered, a handler decoder will be used.

Parameters:

bio – The bio to decode. The value must be of type struct bio.

Returns:

The decoder appropriate for this bio type.

Return type:

Decoder

crash.subsystem.storage.decoders.for_each_bio_in_stack(bio: Value) → Iterable[Decoder]

Iterates and decodes each bio involved in a stacked storage environment

This method will yield a Decoder object describing each level in the storage stack, starting with the provided bio, as processed by each level’s decoder. The stack will be interrupted if an encountered object doesn’t have a decoder specified.

Parameters:

bio – The initial struct bio to start decoding. The value must be of type struct bio.

Yields:

Decoder – The next Decoder in the stack, if any remain.

crash.subsystem.storage.decoders.register_decoder(endio: int | str | List[str] | Value | Symbol, decoder: Type[Decoder]) → None

Registers a bio/buffer_head decoder with the storage subsystem.

A decoder is a class that accepts a bio, buffer_head, or other object, potentially interprets the private members of the object, and returns a Decoder object that describes it.

The only mandatory part of a Decoder is the __str__() method to format the description.

If the bio is part of a stack, the __next__() method will contain the next Decoder object in the stack. It does not necessarily need to be a bio. The Decoder does not need to be registered unless it will be a top-level decoder.

Other attributes can be added as-needed to allow informed callers to obtain direct information.

Parameters:

• endio –

  The function(s) used as endio callback(s).

  The str or list of str arguments are used to register a callback such that the Decoder is registered when the symbol is available.

  The gdb.Symbol, gdb.Value, and int versions are to be used once the symbol is available for resolution.

  If in doubt, use the names instead of the gdb.Symbol objects.

• decoder – The decoder class used to handle this object.