1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
|
Attributes {#attributes}
==========
All meta-information about a dump file is stored in attributes. All attributes
form a tree-like dictionary, where every attribute is placed according to its
path from the root node. The textual representation of this path, where path
elements are delimited by dots, is called _attribute key_.
Some attributes are present in every [kdump_ctx_t] object, although not
necessarily set. They are called _global attributes_. Other attributes may be
created by the library as needed, e.g. CPU registers. It is not possible to
create a new attribute with an arbitrary path through the public API.
Every attribute has a type and an optional value. The type and value can be
queried with `kdump_get_attr`. If the attribute is unset (i.e. it does not
have a value), this function returns `KDUMP_ERR_NODATA`. Attribute value can
be set (or unset) with `kdump_set_attr`, but the type of an attribute cannot
be changed.
Lifetime
--------
Trivial types do not implement reference counting. The attribute value is
always copied. Following types are trivial:
- `KDUMP_NUMBER`
- `KDUMP_ADDRESS`
- `KDUMP_STRING`
Other attribute types refer to objects, and reference counting is used to make
sure that the object does not unexpectedly disappear if the attribute value is
(directly or indirectly) changed. Following types are reference-counted:
- `KDUMP_BITMAP`
- `KDUMP_BLOB`
For historical reasons, the simple attribute API (`kdump_get_attr`,
`kdump_get_attr` and friends) does not increase the reference count of the
returned data. User of this API must not modify the context object while
making use of the returned attribute value. On the other hand, they don't have
to do anything when they are finished.
When a value is returned by the reference-based API (`kdump_attr_ref_get`),
reference count is increased (or a new dynamic string is allocated). Users of
the attribute reference API should release the underlying resources with a
call to `kdump_attr_discard`.
When a new value is set with `kdump_set_attr`, attributes with a trivial type
make a copy of the new value, and attributes with a reference-counted type
take ownership of the reference from the caller.
Well-known Attributes
---------------------
Some attribute keys are available as macros. The intention is to spot mistakes
earlier: A typo in a macro name is detected at build time, whereas a typo in a
key string is not detected until run time.
Implementation
--------------
Internally, there are two types of attributes:
- global, and
- allocated.
Global attributes are allocated at dictionary initialization time, i.e. they
exist in every dictionary object (albeit possibly unset). They can be looked
up directly using a value from [enum global_keyidx] (identifiers with a `GKI_`
prefix) as an index into the `global_attrs` fixed-size array in
[struct attr_dict]. They can also be looked up through the hash table, like
any other attribute, but that's less efficient, of course.
The values of some global attributes are assumed to be always available and
valid. These values are in fact stored in [struct kdump_shared] and can be
accessed from here with zero overhead by inline helper functions. These
attributes are called _static_ and are used for frequently accessed values,
such as `arch.byte_order` or `file.pagemap`.
It is possible to associate attribute operations with static attributes.
However, the `revalidate` hook is not called when the value is accessed
internally by the library using the `get_` or `sget_` helper functions.
It is usually a bug to set `flags.invalid` for a static attribute.
All non-global attributes are dynamically allocated by `new_attr`, and there
is nothing special about them.
Volatile and Persistent Attributes
----------------------------------
Volatile attributes are cleared when a file format probe returns an error.
Persistent attributes are kept. All attributes set through the public API are
persistent. This implementation detail allows to set attribute values while
probing a file format and remove those attributes automatically if it turns
out to be a different file type.
The difference between volatile and persistent attributes is not visible in
the public API.
[kdump_ctx_t]: @ref kdump_ctx_t
[struct kdump_shared]: @ref kdump_shared
[enum global_keyidx]: @ref global_keyidx
[struct attr_dict]: @ref attr_dict
|
