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.
