Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Quan Nguyen <quan@os.amperecomputing.com>
To:     Lee Jones <lee.jones@linaro.org>, Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Jean Delvare <jdelvare@suse.com>,
        Guenter Roeck <linux@roeck-us.net>,
        Jonathan Corbet <corbet@lwn.net>,
        Derek Kiernan <derek.kiernan@xilinx.com>,
        Dragan Cvetic <dragan.cvetic@xilinx.com>,
        Arnd Bergmann <arnd@arndb.de>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        Quan Nguyen <quan@os.amperecomputing.com>,
        Thu Nguyen <thu@os.amperecomputing.com>,
        linux-kernel@vger.kernel.org, devicetree@vger.kernel.org,
        linux-hwmon@vger.kernel.org, linux-doc@vger.kernel.org,
        OpenBMC Maillist <openbmc@lists.ozlabs.org>
Cc:     Open Source Submission <patches@amperecomputing.com>,
        Phong Vo <phong@os.amperecomputing.com>,
        "Thang Q . Nguyen" <thang@os.amperecomputing.com>
Subject: [PATCH v8 9/9] docs: ABI: testing: Document the Ampere Altra Family's SMpro sysfs interfaces
Date:   Fri, 22 Apr 2022 09:46:53 +0700
Message-Id: <20220422024653.2199489-10-quan@os.amperecomputing.com>
In-Reply-To: <20220422024653.2199489-1-quan@os.amperecomputing.com>
References: <20220422024653.2199489-1-quan@os.amperecomputing.com>
Content-Transfer-Encoding: 8bit
Content-Type: text/plain
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?JKxtAaoYVY8LRLued8o3R8S6NDPNYLOHuP118n4MS2PTFgjbkE+RaQhF2I4C?=
 =?us-ascii?Q?7U1aU3fPXiGeG/jg9VoECEiSfXTpc/bmQkIkouiut25+4rOYteQBuXLHl79x?=
 =?us-ascii?Q?7T2t6Bl44LVoY3Fz4HJW7AgxMhvnhCWiJjczs0yhRub/piDvrQKhZNqL4xeO?=
 =?us-ascii?Q?nYgavSO7Q2OgYramgHdbj/IB9UfdHYrFoJwVoyIWuGLObcLbW+nE6wzjXL2Z?=
 =?us-ascii?Q?qW1re7/Tq/mbZnx1poSPzqPijCIF2quL1ZAbbhJ+KR6n405NnjoeaQClcgAF?=
 =?us-ascii?Q?fOtmXEr58aR3+1s6ShBAEbMNsUNhXS4MeyeeyTEMSAaEbSuldL7A9kym+C0L?=
 =?us-ascii?Q?Fy3Lef2WeT1ShmYzaanblYDGxIpYxME0Bjiua/RRAkShlmpHFkLfTnzwuuKS?=
 =?us-ascii?Q?loGB8bQ//f2tNxHsKkJJRAAnI9v9iGwwYyygTW04csZ4nu0zqS/oS3ChRyba?=
 =?us-ascii?Q?vMF9TQAdW308eSI08lYfLq0wzmvFKXVXRiMGzbYG1oo9ws5kx7rIgwKRUPPS?=
 =?us-ascii?Q?dZidovry3IRDuOcqaD/boKJeBicTElNXLZ/eiCmOFrsHaKyRsFwdhQr/933a?=
 =?us-ascii?Q?yoLcpXKeIc4qEIMAt+YvCoFaOizKO1WMLq+DCXOHXplATtj9dEdgONRBiFh4?=
 =?us-ascii?Q?H9y7aMuZEp5kc5b8r9Pt2ZrYcTHRGhz22VVXOvHe+qRTwbQu5BCuVixb5FDe?=
 =?us-ascii?Q?XXaINIo3A+lw+6hAW3anPy5ASU5F2KgKToWqkvCm+Q6tXxsqla8hLv9OjmLq?=
 =?us-ascii?Q?5i7GafOwmsu//aAXZWEFFoGSGJd3sBJiyldL6DL5PPNAmCQ8YfNT02V+6ghv?=
 =?us-ascii?Q?aFeC2IyO2x5aygsOsg61lRzCOg+nfUnQ9999erTFONpseGhzV0F48Dv+arlJ?=
 =?us-ascii?Q?jAvOiNAzbtGhJrsLUovU8suaFBH+yTIg0lFzdJIHsQ6CGJ0b+wwHVIzqUiPM?=
 =?us-ascii?Q?lsq40xZDi4r/H2E5bLhJSThJLvi/a5hcCrcCmL/M6EHPA6ykD/wU2Llr03VH?=
 =?us-ascii?Q?ZcRLLZqYeVDzdAsvdpxBfS0usaLNgwqeCqePhm8k0nkJj5rYS41Yg3XH3roS?=
 =?us-ascii?Q?wFztjS7lcPC7prjqDCTJNUBWEsKVQkMaUjerel1rzZvbkOkLSFUSbw1iSpgB?=
 =?us-ascii?Q?6ZilIxfOU8caCjZbdWzpm9YvdgjugBWTD36JYwtuFi0VUyI98r/30bhCGNpn?=
 =?us-ascii?Q?gIoIKjWxmYQcRbbmdjmoMqljy9o0Y5eCuwN6J2krDAikD5RVMN/tjExjwDue?=
 =?us-ascii?Q?mDQMSqzFWGla10P3w8RShCZEZTAYjpvE1c/ISk0jUsu03NbOZ6OcQiyM1lH/?=
 =?us-ascii?Q?QiteU5tam9Ll5PX7JuJzD9NiK4Pugn6AzHO7o7LbNrTZVDAZMlFQMyFVvi2V?=
 =?us-ascii?Q?/+Bj8BCiXfz5MlDsVHWfGy2Uls4Rwp6SlaTod/aBcSRe8YxI7/zMOQJmjjxq?=
 =?us-ascii?Q?s7tpD1VoU2uJcq2gDQAod7mlefPXnq1kroKM0bc4Odp8LGWJzcH3KGZLAbKq?=
 =?us-ascii?Q?tlcb5KlnoXX13zip3zPelaxn8ZbeISdwUg+k920g3vD+gdb0GZUJxAkqh26y?=
 =?us-ascii?Q?pQMDISlknde/NVnQm0ptAU09+VzEIJSwE2pzU0pWmyioZ8CPR3qW8ujIQgwG?=
 =?us-ascii?Q?yAGDLdhh1QWFAnKFRmycaskDmKz8iIUq7t95Y+4dxOh45pY1eCAsBhRi8Icm?=
 =?us-ascii?Q?QubEa3jFH6ekiM4rE+YIi5YOEoKdBpUiS+3cLIFce3P1wWOPNFT6H605sMlM?=
 =?us-ascii?Q?8QrOlXC6FMgYaBqAUtwsXzqpRxdsIOfBnkK5O/8AilhtnysQ1H+d?=
X-OriginatorOrg: os.amperecomputing.com
X-MS-Exchange-CrossTenant-Network-Message-Id: 0858b4ab-b3e5-40ba-54d9-08da240a8245
X-MS-Exchange-CrossTenant-AuthSource: SJ0PR01MB7282.prod.exchangelabs.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 22 Apr 2022 02:47:58.3326
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 3bc2b170-fd94-476d-b0ce-4229bdc904a7
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: 6Dmkw7r0STh8G6q5IXY2gdeV17IccBj8GRGLWTKSuMt1kk09mNSgl5y6LplQ+GRzCxgwDWMCI8nWgqOkq9JfHQ8QoXuCE7vn09pffEnTpH8=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: SN6PR01MB4653
X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED,
        DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,
        SPF_HELO_PASS,SPF_PASS autolearn=ham autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Add documentation for the Ampere(R)'s Altra(R) SMpro sysfs interfaces

Signed-off-by: Quan Nguyen <quan@os.amperecomputing.com>
---
Changes in v8:
  + Sysfs to return single value in hex format              [Greg]
  + Fix KernelVersion info                                  [Greg]
  + Change errors_* to error_*                              [Quan]
  + Added overflow_[core|mem|pcie|other]_[ce|ue]            [Quan]

Changes in v7:
  + First introduce in v7                                   [Greg]

 .../sysfs-bus-platform-devices-ampere-smpro   | 157 ++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro

diff --git a/Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro b/Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro
new file mode 100644
index 000000000000..41edab6c3e28
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-platform-devices-ampere-smpro
@@ -0,0 +1,157 @@
+What:		/sys/bus/platform/devices/smpro-errmon.*/error_[core|mem|pcie|other]_[ce|ue]
+KernelVersion:	5.18
+Contact:	quan@os.amperecomputing.com
+Description:
+		(RO) Contains the 48-byte Ampere (Vendor-Specific) Error Record, see [1],
+		printed in hex format as below:
+
+		AABBCCCCDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD\
+		DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD
+		Where:
+		  AA       : Error Type
+		  BB       : Subtype
+		  CCCC     : Instance
+		  DDD...DDD: 44-byte value similar to the Arm RAS standard error record
+
+		See [1] below for the format details.
+
+		The detail of each sysfs entries is as below:
+		+-------------+---------------------------------------------------------+
+		|   Error     |                   Sysfs entry                           |
+		+-------------+---------------------------------------------------------+
+		| Core's CE   | /sys/bus/platform/devices/smpro-errmon.*/error_core_ce |
+		| Core's UE   | /sys/bus/platform/devices/smpro-errmon.*/error_core_ue |
+		| Memory's CE | /sys/bus/platform/devices/smpro-errmon.*/error_mem_ce  |
+		| Memory's UE | /sys/bus/platform/devices/smpro-errmon.*/error_mem_ue  |
+		| PCIe's CE   | /sys/bus/platform/devices/smpro-errmon.*/error_pcie_ce |
+		| PCIe's UE   | /sys/bus/platform/devices/smpro-errmon.*/error_pcie_ue |
+		| Other's CE  | /sys/bus/platform/devices/smpro-errmon.*/error_other_ce|
+		| Other's UE  | /sys/bus/platform/devices/smpro-errmon.*/error_other_ue|
+		+-------------+---------------------------------------------------------+
+		UE: Uncorrect-able Error
+		CE: Correct-able Error
+
+		[1] Section 3.3 Ampere (Vendor-Specific) Error Record Formats,
+		    Altra Family RAS Supplement.
+
+
+What:		/sys/bus/platform/devices/smpro-errmon.*/overflow_[core|mem|pcie|other]_[ce|ue]
+KernelVersion:	5.18
+Contact:	quan@os.amperecomputing.com
+Description:
+		(RO) Return the overflow status of each type HW error reported:
+		  0      : No overflow
+		  1      : There is an overflow and the oldest HW errors are dropped
+
+		The detail of each sysfs entries is as below:
+		+-------------+-----------------------------------------------------------+
+		|   Overflow  |                   Sysfs entry                             |
+		+-------------+-----------------------------------------------------------+
+		| Core's CE   | /sys/bus/platform/devices/smpro-errmon.*/overflow_core_ce |
+		| Core's UE   | /sys/bus/platform/devices/smpro-errmon.*/overflow_core_ue |
+		| Memory's CE | /sys/bus/platform/devices/smpro-errmon.*/overflow_mem_ce  |
+		| Memory's UE | /sys/bus/platform/devices/smpro-errmon.*/overflow_mem_ue  |
+		| PCIe's CE   | /sys/bus/platform/devices/smpro-errmon.*/overflow_pcie_ce |
+		| PCIe's UE   | /sys/bus/platform/devices/smpro-errmon.*/overflow_pcie_ue |
+		| Other's CE  | /sys/bus/platform/devices/smpro-errmon.*/overflow_other_ce|
+		| Other's UE  | /sys/bus/platform/devices/smpro-errmon.*/overflow_other_ue|
+		+-------------+-----------------------------------------------------------+
+		UE: Uncorrect-able Error
+		CE: Correct-able Error
+
+What:           /sys/bus/platform/devices/smpro-errmon.*/error_[smpro|pmpro]
+KernelVersion:	5.18
+Contact:	quan@os.amperecomputing.com
+Description:
+		(RO) Contains the internal firmware error record printed as hex format
+		as below:
+
+		ABBCDDEEEEFFFFFFFF
+		Where:
+		  A       : Firmware Error Type
+		              1: Warning
+		              2: Error
+			      4: Error with data
+		  BB      : Firmware Image Code (8-bit value)
+		  C       : Direction:
+		              0: Enter
+		              1: Exit
+		  DD      : Location, firmware module location code (8-bit value)
+		  EEEE    : Error Code, firmware Error Code (16-bit value)
+		  FFFFFFFF: Extensive data (32-bit value)
+
+		Example:
+		  root@mtjade:~# cat /sys/bus/platform/devices/smpro-errmon.1.auto/error_smpro
+		  109008000a00000000
+
+		The detail of each sysfs entries is as below:
+		+-------------+-------------------------------------------------------+
+		|   Error     |                   Sysfs entry                         |
+		+-------------+-------------------------------------------------------+
+		| SMpro error | /sys/bus/platform/devices/smpro-errmon.*/error_smpro  |
+		| PMpro error | /sys/bus/platform/devices/smpro-errmon.*/error_pmpro  |
+		+-------------+-------------------------------------------------------+
+		See more details in section 5.10 RAS Internal Error Register Definitions,
+		Altra Family Soc BMC Interface Specification.
+
+
+What:           /sys/bus/platform/devices/smpro-errmon.*/event_[vrd_warn_fault|vrd_hot|dimm_hot]
+KernelVersion:	5.18
+Contact:	quan@os.amperecomputing.com
+Description:
+		(RO) Contains the detail information in case of VRD/DIMM warning/hot events
+		in hex format as below:
+
+		AABBBB
+		Where:
+		  AA  : The event channel
+		          00: VRD Warning Fault
+		          01: VRD Hot
+			  02: DIMM host
+		  BBBB: The event detail information data
+
+		See more details in section 5.7 GPI Status Registers,
+		Altra Family Soc BMC Interface Specification.
+
+
+What:		/sys/bus/platform/devices/smpro-misc.*/boot_progress
+KernelVersion:	5.18
+Contact:	quan@os.amperecomputing.com
+Description:
+		(RO) Contains the boot stages information in hex as format below:
+
+		AABBCCCCCCCC
+		Where:
+		  AA      : The boot stages
+		              00: SMpro firmware booting
+		              01: PMpro firmware booting
+		              02: ATF BL1 firmware booting
+		              03: DDR initialization
+		              04: DDR training report status
+		              05: ATF BL2 firmware booting
+		              06: ATF BL31 firmware booting
+		              07: ATF BL32 firmware booting
+		              08: UEFI firmware booting
+		              09: OS booting
+		  BB      : Boot status
+		              00: Not started
+		              01: Started
+		              02: Completed without error
+		              03: Failed.
+		  CCCCCCCC: Boot status information defined for each boot stages
+
+		See more details in section 5.11 Boot Stage Register Definitions,
+		and section 6. Processor Boot Progress Codes, Altra Family Soc BMC
+		Interface Specification.
+
+
+What:           /sys/bus/platform/devices/smpro-misc*/soc_power_limit
+KernelVersion:	5.18
+Contact:	quan@os.amperecomputing.com
+Description:
+		(RW) Contains the desired SoC power limit in Watt.
+		Writes to this sysfs set the desired SoC power limit (W).
+		Reads from this register return the current SoC power limit (W).
+		The value ranges:
+		  Minimum: 120 W
+		  Maximum: Socket TDP power
-- 
2.35.1