Skip to contentSkip to conversation

Add support for PCIe SSD status LED management

PATCH Superseded Stuart Hayes 3 participants 8 messages Apr 16, 2021 – May 24, 2021 1 message not in the archive PCI

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Add support for PCIe SSD status LED management

This patch adds support for the PCIe SSD Status LED Management interface, as described in the "_DSM Additions for PCIe SSD Status LED Management" ECN to the PCI Firmware Specification revision 3.2.

It will add a single (led_classdev) LED for any PCIe device that has the relevant _DSM. The ten possible status states are exposed using attributes current_states and supported_states. Reading current_states (and supported_states) will show the definition and value of each bit:

Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]

--
supported_states = 0x0008

Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/current_states

locate 0x0008 [ ]
--
current_states = 0x0000

---
 .../sysfs-class-led-driver-pcie-ssd-leds      |  30 ++
 drivers/pci/Kconfig                           |  12 +
 drivers/pci/Makefile                          |   1 +
 drivers/pci/pcie-ssd-leds.c                   | 421 ++++++++++++++++++
 4 files changed, 464 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-led-driver-pcie-ssd-leds
 create mode 100644 drivers/pci/pcie-ssd-leds.c
Documentation/ABI/testing/sysfs-class-led-driver-pcie-ssd-leds new file +30 -0
new file mode 100644
index 000000000000..856f5a078568
@@ -0,0 +1,30 @@
+What:		/sys/class/leds/<led>/supported_states
+Date:		April 2021
+Contact:	[email protected]
+Description:
+		This attribute indicates the status states supported by this
+		display.  Reading will show a verbose output with the value on
+		the final line (example below), writing only takes a single
+		numerical value.
+
+		>cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states
+		ok                              0x0004 [ ]
+		locate                          0x0008 [*]
+		fail                            0x0010 [ ]
+		rebuild                         0x0020 [ ]
+		pfa                             0x0040 [ ]
+		hotspare                        0x0080 [ ]
+		criticalarray                   0x0100 [ ]
+		failedarray                     0x0200 [ ]
+		invaliddevice                   0x0400 [ ]
+		disabled                        0x0800 [ ]
+		--
+		supported_states = 0x0008
+
+What:		/sys/class/leds/<led>/current_states
+Date:		April 2021
+Contact:	[email protected]
+Description:
+		This attribute indicates the currently active status states on
+		this display.  Reading will show a verbose output with the value
+		the final line, writing only takes a single numerical value.
drivers/pci/Kconfig +12 -0
index 0c473d75e625..f4acf1ad0fb5 100644
@@ -190,6 +190,18 @@ config PCI_HYPERV
 	  The PCI device frontend driver allows the kernel to import arbitrary
 	  PCI devices from a PCI backend to support PCI driver domains.
 
+config PCIE_SSD_LEDS
+	tristate "PCIe SSD status LED support"
+	depends on ACPI && NEW_LEDS
+	help
+	  Driver for PCIe SSD status LED management as described in a PCI
+	  Firmware Specification, Revision 3.2 ECN.
+
+	  When enabled, an LED interface will be created for each PCIe device
+	  that has the ACPI method described in the referenced specification,
+	  to allow the device status LEDs for that PCIe device (presumably a
+	  solid state storage device or its slot) to be seen and controlled.
+
 choice
 	prompt "PCI Express hierarchy optimization setting"
 	default PCIE_BUS_DEFAULT
drivers/pci/Makefile +1 -0
index d62c4ac4ae1b..ea0a0f351ad2 100644
@@ -29,6 +29,7 @@ obj-$(CONFIG_PCI_PF_STUB)	+= pci-pf-stub.o
 obj-$(CONFIG_PCI_ECAM)		+= ecam.o
 obj-$(CONFIG_PCI_P2PDMA)	+= p2pdma.o
 obj-$(CONFIG_XEN_PCIDEV_FRONTEND) += xen-pcifront.o
+obj-$(CONFIG_PCIE_SSD_LEDS)	+= pcie-ssd-leds.o
 
 # Endpoint library must be initialized before its users
 obj-$(CONFIG_PCI_ENDPOINT)	+= endpoint/
drivers/pci/pcie-ssd-leds.c new file +421 -0

421 lines not on this page · raw message

Signature · 1 line
2.27.0
#1 lore raw
Quoted 23 lines · Stuart Hayes

This patch adds support for the PCIe SSD Status LED Management interface, as described in the "_DSM Additions for PCIe SSD Status LED Management" ECN to the PCI Firmware Specification revision 3.2.

It will add a single (led_classdev) LED for any PCIe device that has the relevant _DSM. The ten possible status states are exposed using attributes current_states and supported_states. Reading current_states (and supported_states) will show the definition and value of each bit:

Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]

--
supported_states = 0x0008

Quoted 6 lines
Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/current_states

locate 0x0008 [ ]
--
current_states = 0x0000

Any comments? I think I sent at a bad time originally. Thanks!

#2 lore raw
In reply to Stuart Hayes
Quoted 8 lines · Stuart Hayes

This patch adds support for the PCIe SSD Status LED Management interface, as described in the "_DSM Additions for PCIe SSD Status LED Management" ECN to the PCI Firmware Specification revision 3.2.

It will add a single (led_classdev) LED for any PCIe device that has the relevant _DSM. The ten possible status states are exposed using attributes current_states and supported_states. Reading current_states (and supported_states) will show the definition and value of each bit:

There is significant overlap in this ECN with the PCIe native enclosure management (NPEM) capability. Would it be possible for the sysfs interface to provide an abstraction such that both these implementations could subscribe to?

Quoted 11 lines
Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]
Quoted 2 lines

--
supported_states = 0x0008

This is quite verbose for a sysfs property. The common trend for new properties is that they're consumed by programs as well as humans, so just ouputing a raw number should be sufficient if the values have a well defined meaning.

A message that is not in the archive (sent off-list or not yet received): CAL5oW00Pmnhqi1KZ9-jqFwLXQWBO0ddCyv+dr6qkry7iqZNQsw@mail.gmail.com

#4 lore raw
Quoted 19 lines · Stuart Hayes
Quoted 10 lines · Keith Busch
Quoted 8 lines · Stuart Hayes

This patch adds support for the PCIe SSD Status LED Management interface, as described in the "_DSM Additions for PCIe SSD Status LED Management" ECN to the PCI Firmware Specification revision 3.2.

It will add a single (led_classdev) LED for any PCIe device that has the relevant _DSM. The ten possible status states are exposed using attributes current_states and supported_states. Reading current_states (and supported_states) will show the definition and value of each bit:

Quoted 5 lines

There is significant overlap in this ECN with the PCIe native enclosure management (NPEM) capability. Would it be possible for the sysfs interface to provide an abstraction such that both these implementations could subscribe to?

Quoted 7 lines

It wouldn't be too hard to check for the NPEM capability here and provide access to it as well (or it could be added on later without too much trouble), but it looks like NPEM support is already implemented in user space (in ledmon). (I only wrote a kernel module for this, because it uses a _DSM which can't readily be accessed in user space.)

I've reworked the driver a bit, so it would be very easy to separate it into two parts:

* a generic drive status LED driver/module (in drivers/leds??) that
would handle creating the struct led_classdev and sysfs interface to it

* a PCIe drive status LED driver/module that checks PCI devices for
_DSM or NPEM support, and calls the generic drive status LED driver/module to create an LED when it finds a device that supports it.

My code only supports _DSM, as I don't have any hardware to test NPEM on, but it would be very simple to add NPEM support (much more so than in the patch I sent in this thread).

I'm not sure if it is worth splitting the code into two pieces, though... I don't know if anything other than NPEM or the _DSM would bother to use this, and I think those make more sense in a single module because they are so similar (the _DSM method was created as a way to do the same thing as NPEM but without hardware support, and they need the same code for scanning and detecting added/removed devices).

Maybe I should just leave this all in one file for now, and it could be split later if anyone wanted to add support for SES or some other method in the future?

Quoted 14 lines
Quoted 14 lines
Quoted 13 lines
Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]

--
supported_states = 0x0008

Quoted 5 lines
Quoted 5 lines

This is quite verbose for a sysfs property. The common trend for new properties is that they're consumed by programs as well as humans, so just ouputing a raw number should be sufficient if the values have a well defined meaning.

I was able to rework this so it uses a scheduler type of output and eliminate the numbers, since the PCI specs are not public (and methods other than NPEM/_DSM might use different numbers). It only needs a single attribute "states", which shows all supported states, and has brackets on the ones that are active.. for example:

[ok] [locate] fail rebuid ica ifa

To set multiple states, just echo the states separated by spaces or commas:

echo "locate ica" > states

(I renamed criticalarray and failedarray to ica and ifa to match ledmon's state names).

Does this seem better?

Thanks!

#5 lore raw
In reply to Stuart Hayes

[+cc Keith for visibility]

Hi Stuart,

Quoted 11 lines
Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]
Quoted 5 lines

--
supported_states = 0x0008

Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/current_states

locate 0x0008 [ ]

As per what Keith already noted, this is a very elaborate output as far as sysfs goes - very human-readable, but it would be complex to parse should some software would be interested in showing this values in a way or another.

I would propose output similar to this one:

  $ cat /sys/block/sda/queue/scheduler
  mq-deadline-nodefault [bfq] none

If you prefer to show the end-user a string, rather than a numeric value. This approach could support both the supported and current states (similarly to how it works for the I/O scheduler), thus there would be no need to duplicate the code between the two attributes.

What do you think?

Also, and I appreciate it would be more work, it's customary to accept a string value rather than a numeric value when updating state through the sysfs object, especially when the end-user is presented with string values on read. Having said that, this is not a requirement, so I am leaving it at your discretion. :)

[...]

drivers/pci/pcie-ssd-leds.c line 38

Quoted 12 lines
drivers/pci/pcie-ssd-leds.c new file +12 -0
+static struct led_state led_states[] = {
+	{ .name = "ok",			.mask = 1 << 2 },
+	{ .name = "locate",		.mask = 1 << 3 },
+	{ .name = "fail",		.mask = 1 << 4 },
+	{ .name = "rebuild",		.mask = 1 << 5 },
+	{ .name = "pfa",		.mask = 1 << 6 },
+	{ .name = "hotspare",		.mask = 1 << 7 },
+	{ .name = "criticalarray",	.mask = 1 << 8 },
+	{ .name = "failedarray",	.mask = 1 << 9 },
+	{ .name = "invaliddevice",	.mask = 1 << 10 },
+	{ .name = "disabled",		.mask = 1 << 11 },
+};

Just a suggestion: how about using the BIT() macro in the above?

[...]

drivers/pci/pcie-ssd-leds.c line 181

Quoted 13 lines
drivers/pci/pcie-ssd-leds.c new file +13 -0
+static bool pdev_has_dsm(struct pci_dev *pdev)
+{
+	acpi_handle handle;
+
+	handle = ACPI_HANDLE(&pdev->dev);
+	if (!handle)
+		return false;
+
+	return !!acpi_check_dsm(handle, &pcie_ssdleds_dsm_guid, 0x1,
+		1 << GET_SUPPORTED_STATES_DSM ||
+		1 << GET_STATE_DSM ||
+		1 << SET_STATE_DSM);
+}

The acpi_check_dsm() function already returns a bool type, so you can drop the conversion.

Quoted 15 lines
drivers/pci/pcie-ssd-leds.c new file +15 -0
+static ssize_t current_states_show(struct device *dev,
+				   struct device_attribute *attr, char *buf)
+{
+	struct led_classdev *led_cdev = dev_get_drvdata(dev);
+	struct device *dsm_dev = led_cdev->dev->parent;
+	struct ssd_status_dev *ssd;
+	u32 val;
+	int err, i, result = 0;
+
+	ssd = container_of(led_cdev, struct ssd_status_dev, led_cdev);
+
+	err = dsm_get(dsm_dev, GET_STATE_DSM, &val);
+	if (err < 0)
+		return err;
+	for (i = 0; i < ARRAY_SIZE(led_states); i++)

drivers/pci/pcie-ssd-leds.c line 207

Quoted 10 lines
drivers/pci/pcie-ssd-leds.c new file +10 -0
+		if (led_states[i].mask & ssd->supported_states)
+			result += sprintf(buf + result, "%-25s\t0x%04X [%c]\n",
+					  led_states[i].name,
+					  led_states[i].mask,
+					  (val & led_states[i].mask)
+					  ? '*' : ' ');
+
+	result += sprintf(buf + result, "--\ncurrent_states = 0x%04X\n", val);
+	return result;
+}

This show() callback above might benefit from already using the sysfs_emit_at() function instead of using the sprintf() here, see:

https://www.kernel.org/doc/html/latest/filesystems/sysfs.html?highlight=sysfs_emi#reading-writing-attribute-data

[...]

Quoted 10 lines
drivers/pci/pcie-ssd-leds.c new file +10 -0
+static ssize_t supported_states_show(struct device *dev,
+				     struct device_attribute *attr, char *buf)
+{
+	struct led_classdev *led_cdev = dev_get_drvdata(dev);
+	struct ssd_status_dev *ssd;
+	int i, result = 0;
+
+	ssd = container_of(led_cdev, struct ssd_status_dev, led_cdev);
+
+	for (i = 0; i < ARRAY_SIZE(led_states); i++)

drivers/pci/pcie-ssd-leds.c line 254

Quoted 10 lines
drivers/pci/pcie-ssd-leds.c new file +10 -0
+		result += sprintf(buf + result, "%-25s\t0x%04X [%c]\n",
+				  led_states[i].name,
+				  led_states[i].mask,
+				  (ssd->supported_states & led_states[i].mask)
+				  ? '*' : ' ');
+
+	result += sprintf(buf + result, "--\nsupported_states = 0x%04X\n",
+			  ssd->supported_states);
+	return result;
+}

Same as above. This might benefit from using sysfs_emit_at().

[...]

drivers/pci/pcie-ssd-leds.c line 257

Quoted 2 lines
drivers/pci/pcie-ssd-leds.c new file +2 -0
+static DEVICE_ATTR_RW(current_states);
+static DEVICE_ATTR_RO(supported_states);

A small nitpik. These are customary added immediately after the show() and store() functions for a given attribute.

Krzysztof

#6 lore raw
Quoted 27 lines · Krzysztof Wilczyński
Quoted 11 lines
Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]
Quoted 5 lines

--
supported_states = 0x0008

Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/current_states

locate 0x0008 [ ]

As per what Keith already noted, this is a very elaborate output as far as sysfs goes - very human-readable, but it would be complex to parse should some software would be interested in showing this values in a way or another.

I would propose output similar to this one:

  $ cat /sys/block/sda/queue/scheduler
  mq-deadline-nodefault [bfq] none
Quoted 6 lines

If you prefer to show the end-user a string, rather than a numeric value. This approach could support both the supported and current states (similarly to how it works for the I/O scheduler), thus there would be no need to duplicate the code between the two attributes.

What do you think?

Some enclosures may support just one blinky state at a time. Other implementations might have multiple LEDs and colors, so you could, for example, "locate" something that is also "failed", with both states visible simultaneously. You could capture the current states with the "scheduler" type display, but setting new states may be more complicated.

#7 lore raw

Hi Keith,

Quoted 32 lines
Quoted 32 lines
Quoted 11 lines
Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]
Quoted 5 lines

--
supported_states = 0x0008

Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/current_states

locate 0x0008 [ ]

As per what Keith already noted, this is a very elaborate output as far as sysfs goes - very human-readable, but it would be complex to parse should some software would be interested in showing this values in a way or another.

I would propose output similar to this one:

  $ cat /sys/block/sda/queue/scheduler
  mq-deadline-nodefault [bfq] none

If you prefer to show the end-user a string, rather than a numeric value. This approach could support both the supported and current states (similarly to how it works for the I/O scheduler), thus there would be no need to duplicate the code between the two attributes.

Quoted 8 lines
Quoted 1 line

What do you think?

Some enclosures may support just one blinky state at a time. Other implementations might have multiple LEDs and colors, so you could, for example, "locate" something that is also "failed", with both states visible simultaneously. You could capture the current states with the "scheduler" type display, but setting new states may be more complicated.

Ah, excellent point. I didn't think about this - the use-case you provided. This would, indeed, be far more complex to deal with when accepting a write. I can see why Stuart did it the way he did currently.

Krzysztof

#8 lore raw
Quoted 10 lines · Keith Busch
Quoted 8 lines · Stuart Hayes

This patch adds support for the PCIe SSD Status LED Management interface, as described in the "_DSM Additions for PCIe SSD Status LED Management" ECN to the PCI Firmware Specification revision 3.2.

It will add a single (led_classdev) LED for any PCIe device that has the relevant _DSM. The ten possible status states are exposed using attributes current_states and supported_states. Reading current_states (and supported_states) will show the definition and value of each bit:

Quoted 5 lines

There is significant overlap in this ECN with the PCIe native enclosure management (NPEM) capability. Would it be possible for the sysfs interface to provide an abstraction such that both these implementations could subscribe to?

It wouldn't be too hard to check for the NPEM capability here and provide access to it as well using the same LED interface, especially since the state bits are the same. The module could just check for NPEM capability at the same time it is checking for the _DSM. I guess that could be added on later without too much trouble, too... I don't think anything about the interface would have to change to add support for NPEM.

FWIW, it looks like NPEM support is already supported in user space in ledmon. (I only wrote a kernel module for this, because it uses a _DSM which can't readily be accessed in user space.)

Quoted 43 lines · Krzysztof Wilczyński

Hi Keith,

Quoted 32 lines
Quoted 32 lines
Quoted 11 lines
Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/supported_states

ok                              0x0004 [ ]
locate                          0x0008 [*]
fail                            0x0010 [ ]
rebuild                         0x0020 [ ]
pfa                             0x0040 [ ]
hotspare                        0x0080 [ ]
criticalarray                   0x0100 [ ]
failedarray                     0x0200 [ ]
invaliddevice                   0x0400 [ ]
disabled                        0x0800 [ ]
Quoted 5 lines

--
supported_states = 0x0008

Quoted 1 line

cat /sys/class/leds/0000:88:00.0::pcie_ssd_status/current_states

locate 0x0008 [ ]

As per what Keith already noted, this is a very elaborate output as far as sysfs goes - very human-readable, but it would be complex to parse should some software would be interested in showing this values in a way or another.

I would propose output similar to this one:

   $ cat /sys/block/sda/queue/scheduler
   mq-deadline-nodefault [bfq] none

If you prefer to show the end-user a string, rather than a numeric value. This approach could support both the supported and current states (similarly to how it works for the I/O scheduler), thus there would be no need to duplicate the code between the two attributes.

Quoted 8 lines
Quoted 1 line

What do you think?

Some enclosures may support just one blinky state at a time. Other implementations might have multiple LEDs and colors, so you could, for example, "locate" something that is also "failed", with both states visible simultaneously. You could capture the current states with the "scheduler" type display, but setting new states may be more complicated.

Quoted 7 lines

Ah, excellent point. I didn't think about this - the use-case you provided. This would, indeed, be far more complex to deal with when accepting a write. I can see why Stuart did it the way he did currently.

Krzysztof

I copied the format of this output from acpi_debug_level / acpi_debug_layer in drivers/acpi/sysfs.c. I thought it might be reasonably easy enough for a machine to parse this for the number, since it is always on the last line and always immediately following the only "=".

I don't object to using just a number, but I submitted an earlier version of this some months ago (which didn't use the LED subsystem) which only had the number, and Bjorn commented that decoding that was a bit of a pain, and that the PCI specs (which contain the bit definitions) isn't public. I guess I could just add the definitions in the documentation if this is too verbose for sysfs.