Skip to content

Commit f9eb41d

Browse files
vojtechtrefnyvojtechtrefny
authored
Merge pull request #1053 from vojtechtrefny/master_docs-typos-etc
Docs and grammar fixes
2 parents 1838c4f + 36efaed commit f9eb41d

File tree

6 files changed

+117
-125
lines changed

6 files changed

+117
-125
lines changed

‎docs/libblockdev-sections.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ bd_crypto_opal_is_supported
130130
bd_crypto_opal_wipe_device
131131
bd_crypto_opal_format
132132
bd_crypto_opal_reset_device
133+
BDCryptoLUKSHWEncryptionType
133134
BDCryptoTech
134135
BDCryptoTechMode
135136
bd_crypto_is_tech_avail

‎src/lib/plugin_apis/part.api

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ GType bd_part_spec_get_type();
6060
* @size: size of the partition
6161
* @bootable: whether the bootable flag is set or not (for MSDOS partitions)
6262
* @attrs: partition GPT attributes
63+
* @type_name: human readable representation of @type_guid
6364
*/
6465
typedef struct BDPartSpec {
6566
gchar *path;

‎src/lib/plugin_apis/smart.api

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -669,7 +669,7 @@ gboolean bd_smart_set_enabled (const gchar *device, gboolean enabled, const BDEx
669669
*
670670
* Executes or aborts device self-test.
671671
*
672-
* Returns: %TRUE when the self-test was trigerred successfully or %FALSE in case of an error (with @error set).
672+
* Returns: %TRUE when the self-test was triggered successfully or %FALSE in case of an error (with @error set).
673673
*
674674
* Tech category: %BD_SMART_TECH_ATA-%BD_SMART_TECH_MODE_SELFTEST
675675
*/

‎src/plugins/smart/libatasmart.c

Lines changed: 1 addition & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -31,119 +31,6 @@
3131
#include "smart.h"
3232
#include "smart-private.h"
3333

34-
/**
35-
* SECTION: smart
36-
* @short_description: S.M.A.R.T. device reporting and management.
37-
* @title: SMART plugin
38-
* @include: smart.h
39-
*
40-
* Plugin for ATA and SCSI/SAS S.M.A.R.T. device reporting and management. For NVMe
41-
* health reporting please use the native [`nvme`][libblockdev-NVMe] plugin.
42-
*
43-
* This libblockdev plugin strives to provide good enough abstraction on top of vastly
44-
* different backend implementations. Two plugin implementations are available:
45-
* `libatasmart` (default) and `smartmontools` (experimental).
46-
*
47-
* Not all plugin implementations provide full functionality and it is advised
48-
* to use standard libblockdev tech query functions for feature availability testing.
49-
* For example, the `libatasmart` plugin only provides ATA functionality and error
50-
* is returned when any SCSI function is called.
51-
*
52-
* ## libatasmart plugin #
53-
*
54-
* An implementation proven for over a decade, being essentially a port of UDisks code.
55-
* The `libatasmart` library is reasonably lightweight with minimal dependencies,
56-
* light on I/O and consuming C API directly with clearly defined data types.
57-
* However essentially no quirks or any drive database is present in the library
58-
* (apart from a couple of very old laptop drives).
59-
*
60-
* ## smartmontools plugin #
61-
*
62-
* In contrast to libatasmart, the smartmontools project is a feature-rich
63-
* implementation supporting specialties like vendor-specific data blocks. It is
64-
* a considerably heavier implementation I/O-wise due to device type detection and
65-
* retrieval of more data blocks from the drive.
66-
*
67-
* There's no C API at the moment and the plugin resorts to executing the `smartctl`
68-
* command and parsing its JSON output, that is by nature loosely-defined. This
69-
* presents challenges in data type conversions, interpretation of printed values
70-
* and volatile JSON key presence. Besides, executing external commands always brings
71-
* certain performance overhead and caution is advised when retrieving SMART data
72-
* from multiple drives in parallel.
73-
*
74-
* ## Atribute naming and value interpretation #
75-
*
76-
* Check #BDSmartATAAttribute for the struct members overview first. The plugin
77-
* public API provides both the implementation-specific attribute names/values
78-
* as well as unified ('well-known', translated) interpretation that is preferred
79-
* for general use.
80-
*
81-
* The `well_known_name` property follows the libatasmart-style naming -
82-
* e.g. `'power-on-hours'`. Unknown or untrusted attributes are either provided
83-
* in the form of `'attribute-123'` or by %NULL.
84-
*
85-
* Similarly, value of an attribute is provided in variety of interpretations,
86-
* subject to availability:
87-
* - the `value`, `worst` and `threshold` are normalized values in typical S.M.A.R.T. fashion
88-
* - the `value_raw` as a 64-bit untranslated value with no further context
89-
* of which bits are actually valid for a particular attribute
90-
* - the `pretty_value_string` as an implementation-specific string representation,
91-
* intended for end-user display
92-
* - the `pretty_value` and `pretty_value_unit` as a libatasmart-style of unified value/type pair
93-
*
94-
* Both libblockdev plugins strive for best effort of providing accurate values,
95-
* however there are often challenges ranging from string-to-number conversion,
96-
* multiple values being unpacked from a single raw number or not having enough
97-
* context provided by the underlying library for a trusted value interpretation.
98-
*
99-
* ## Attribute validation #
100-
*
101-
* It may seem obvious to use numerical attribute ID as an authoritative attribute
102-
* identifier, however in reality drive vendors tend not to stick with public
103-
* specifications. Attributes are often reused for vendor-specific values and this
104-
* differs from model to model even for a single vendor. This is more often the case
105-
* with SSD drives than traditional HDDs.
106-
*
107-
* Historically it brought confusion and false alarms on user's end and eventually
108-
* led to some form of quirk database in most projects. Maintaining such database
109-
* is a lifetime task and the only successful effort is the smartmontools' `drivedb.h`
110-
* collection. Quirks are needed for about everything - meaning of a particular
111-
* attribute (i.e. a 'well-known' name), interpretation of a raw value, all this
112-
* filtered by drive model string and firmware revision.
113-
*
114-
* However even there not everything is consistent and slight variations in
115-
* a 'well-known' name can be found. Besides, the attribute naming syntax differs
116-
* from our chosen libatasmart-style form.
117-
*
118-
* For this reason an internal libblockdev translation table has been introduced
119-
* to ensure a bit of consistency. The translation table is kept conservative,
120-
* is by no means complete and may get extended in future libblockdev releases.
121-
* As a result, some attributes may be reported as 'untrusted' or 'unknown'.
122-
*
123-
* The translation table at this point doesn't handle 'moves' where a different
124-
* attribute ID has been assigned for otherwise well defined attribute.
125-
*
126-
* An experimental `drivedb.h` parser is provided for the libatasmart plugin
127-
* as an additional tier of validation based on actual drive model + firmware match.
128-
* Being a C header file, the `drivedb.h` definitions are compiled in the plugin.
129-
* There's no support for loading external `drivedb.h` file though. This however
130-
* only serves for validation. Providing backwards mapping to libatasmart-style
131-
* of attributes is considered as a TODO.
132-
*
133-
* ## Device type detection, multipath #
134-
*
135-
* There's a big difference in how a drive is accessed. While libatasmart performs
136-
* essentially no device type detection and sends a I/O request right away
137-
* (with usual error handling), `smartctl` implements a logic to determine which
138-
* protocol to use, supporting various passthrough mechanisms and interface bridges.
139-
* Such detection is not always reliable though, having known issues with `dm-multipath`
140-
* for example. For this case most plugin functions provide the `'extra'` argument
141-
* allowing consumers to provide specific arguments such as `'--device=' for device
142-
* type override`. This is only supported by the smartmontools plugin and ignored
143-
* by the libatasmart plugin.
144-
*
145-
*/
146-
14734
/**
14835
* bd_smart_is_tech_avail:
14936
* @tech: the queried tech
@@ -615,7 +502,7 @@ gboolean bd_smart_set_enabled (G_GNUC_UNUSED const gchar *device, G_GNUC_UNUSED
615502
*
616503
* Executes or aborts device self-test.
617504
*
618-
* Returns: %TRUE when the self-test was trigerred successfully or %FALSE in case of an error (with @error set).
505+
* Returns: %TRUE when the self-test was triggered successfully or %FALSE in case of an error (with @error set).
619506
*
620507
* Tech category: %BD_SMART_TECH_ATA-%BD_SMART_TECH_MODE_SELFTEST
621508
*/

‎src/plugins/smart/smart-common.c

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,118 @@
2929
#include "smart.h"
3030
#include "smart-private.h"
3131

32+
/**
33+
* SECTION: smart
34+
* @short_description: S.M.A.R.T. device reporting and management.
35+
* @title: SMART
36+
* @include: smart.h
37+
*
38+
* Plugin for ATA and SCSI/SAS S.M.A.R.T. device reporting and management. For NVMe
39+
* health reporting please use the native [`nvme`][libblockdev-NVMe] plugin.
40+
*
41+
* This libblockdev plugin strives to provide good enough abstraction on top of vastly
42+
* different backend implementations. Two plugin implementations are available:
43+
* `libatasmart` (default) and `smartmontools` (experimental).
44+
*
45+
* Not all plugin implementations provide full functionality and it is advised
46+
* to use standard libblockdev tech query functions for feature availability testing.
47+
* For example, the `libatasmart` plugin only provides ATA functionality and error
48+
* is returned when any SCSI function is called.
49+
*
50+
* ## libatasmart plugin #
51+
*
52+
* An implementation proven for over a decade, being essentially a port of UDisks code.
53+
* The `libatasmart` library is reasonably lightweight with minimal dependencies,
54+
* light on I/O and consuming C API directly with clearly defined data types.
55+
* However essentially no quirks or any drive database is present in the library
56+
* (apart from a couple of very old laptop drives).
57+
*
58+
* ## smartmontools plugin #
59+
*
60+
* In contrast to libatasmart, the smartmontools project is a feature-rich
61+
* implementation supporting specialties like vendor-specific data blocks. It is
62+
* a considerably heavier implementation I/O-wise due to device type detection and
63+
* retrieval of more data blocks from the drive.
64+
*
65+
* There's no C API at the moment and the plugin resorts to executing the `smartctl`
66+
* command and parsing its JSON output, that is by nature loosely-defined. This
67+
* presents challenges in data type conversions, interpretation of printed values
68+
* and volatile JSON key presence. Besides, executing external commands always brings
69+
* certain performance overhead and caution is advised when retrieving SMART data
70+
* from multiple drives in parallel.
71+
*
72+
* ## Attribute naming and value interpretation #
73+
*
74+
* Check #BDSmartATAAttribute for the struct members overview first. The plugin
75+
* public API provides both the implementation-specific attribute names/values
76+
* as well as unified ('well-known', translated) interpretation that is preferred
77+
* for general use.
78+
*
79+
* The `well_known_name` property follows the libatasmart-style naming -
80+
* e.g. `'power-on-hours'`. Unknown or untrusted attributes are either provided
81+
* in the form of `'attribute-123'` or by %NULL.
82+
*
83+
* Similarly, value of an attribute is provided in variety of interpretations,
84+
* subject to availability:
85+
* - the `value`, `worst` and `threshold` are normalized values in typical S.M.A.R.T. fashion
86+
* - the `value_raw` as a 64-bit untranslated value with no further context
87+
* of which bits are actually valid for a particular attribute
88+
* - the `pretty_value_string` as an implementation-specific string representation,
89+
* intended for end-user display
90+
* - the `pretty_value` and `pretty_value_unit` as a libatasmart-style of unified value/type pair
91+
*
92+
* Both libblockdev plugins strive for best effort of providing accurate values,
93+
* however there are often challenges ranging from string-to-number conversion,
94+
* multiple values being unpacked from a single raw number or not having enough
95+
* context provided by the underlying library for a trusted value interpretation.
96+
*
97+
* ## Attribute validation #
98+
*
99+
* It may seem obvious to use numerical attribute ID as an authoritative attribute
100+
* identifier, however in reality drive vendors tend not to stick with public
101+
* specifications. Attributes are often reused for vendor-specific values and this
102+
* differs from model to model even for a single vendor. This is more often the case
103+
* with SSD drives than traditional HDDs.
104+
*
105+
* Historically it brought confusion and false alarms on user's end and eventually
106+
* led to some form of quirk database in most projects. Maintaining such database
107+
* is a lifetime task and the only successful effort is the smartmontools' `drivedb.h`
108+
* collection. Quirks are needed for about everything - meaning of a particular
109+
* attribute (i.e. a 'well-known' name), interpretation of a raw value, all this
110+
* filtered by drive model string and firmware revision.
111+
*
112+
* However even there not everything is consistent and slight variations in
113+
* a 'well-known' name can be found. Besides, the attribute naming syntax differs
114+
* from our chosen libatasmart-style form.
115+
*
116+
* For this reason an internal libblockdev translation table has been introduced
117+
* to ensure a bit of consistency. The translation table is kept conservative,
118+
* is by no means complete and may get extended in future libblockdev releases.
119+
* As a result, some attributes may be reported as 'untrusted' or 'unknown'.
120+
*
121+
* The translation table at this point doesn't handle 'moves' where a different
122+
* attribute ID has been assigned for otherwise well defined attribute.
123+
*
124+
* An experimental `drivedb.h` parser is provided for the libatasmart plugin
125+
* as an additional tier of validation based on actual drive model + firmware match.
126+
* Being a C header file, the `drivedb.h` definitions are compiled in the plugin.
127+
* There's no support for loading external `drivedb.h` file though. This however
128+
* only serves for validation. Providing backwards mapping to libatasmart-style
129+
* of attributes is considered as a TODO.
130+
*
131+
* ## Device type detection, multipath #
132+
*
133+
* There's a big difference in how a drive is accessed. While libatasmart performs
134+
* essentially no device type detection and sends a I/O request right away
135+
* (with usual error handling), `smartctl` implements a logic to determine which
136+
* protocol to use, supporting various passthrough mechanisms and interface bridges.
137+
* Such detection is not always reliable though, having known issues with `dm-multipath`
138+
* for example. For this case most plugin functions provide the `'extra'` argument
139+
* allowing consumers to provide specific arguments such as `'--device=' for device
140+
* type override`. This is only supported by the smartmontools plugin and ignored
141+
* by the libatasmart plugin.
142+
*
143+
*/
32144

33145
/**
34146
* bd_smart_error_quark: (skip)

‎src/plugins/smart/smartmontools.c

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -32,15 +32,6 @@
3232
#include "smart.h"
3333
#include "smart-private.h"
3434

35-
/**
36-
* SECTION: smart-smartmontools
37-
* @short_description: SMART device reporting and management.
38-
* @title: SMART
39-
* @include: smart.h
40-
*
41-
* A plugin for SMART device reporting and management, based around smartmontools.
42-
*/
43-
4435
#define SMARTCTL_MIN_VERSION "7.0"
4536

4637
static volatile guint avail_deps = 0;
@@ -1194,7 +1185,7 @@ gboolean bd_smart_set_enabled (const gchar *device, gboolean enabled, const BDEx
11941185
*
11951186
* Executes or aborts device self-test.
11961187
*
1197-
* Returns: %TRUE when the self-test was trigerred successfully or %FALSE in case of an error (with @error set).
1188+
* Returns: %TRUE when the self-test was triggered successfully or %FALSE in case of an error (with @error set).
11981189
*
11991190
* Tech category: %BD_SMART_TECH_ATA-%BD_SMART_TECH_MODE_SELFTEST
12001191
*/

0 commit comments

Comments
 (0)