From patchwork Wed Oct 11 13:01:03 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Suzuki K Poulose X-Patchwork-Id: 115549 Delivered-To: patch@linaro.org Received: by 10.140.22.163 with SMTP id 32csp729088qgn; Wed, 11 Oct 2017 06:02:30 -0700 (PDT) X-Google-Smtp-Source: AOwi7QCNlLo35S+mz6CpdWBmzWLmI6R6AwVg8ArwTperjJWFmRgyNPp8qjltg2b9r2QUTuphYVcY X-Received: by 10.99.185.18 with SMTP id z18mr5485627pge.212.1507726950379; Wed, 11 Oct 2017 06:02:30 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1507726950; cv=none; d=google.com; s=arc-20160816; b=QllygbBLhhsN6nNagGuQDQhtPLQX7G6CBVGzvh5GNJT6Ocs1Ku/rJthNj9R6/xYAxL 3HZSLXIw9XVewTHeO72BaCQa+m5+OQ1/vvxnISFtqR15Nqc5hpF2J59b8fkTGfDNtUcu 4cv0urmUINVv2zV/f2MwMoOvkSn+mh6y2fgbT94bS/zSCIBCq09310g0iSRZvh3USlS1 Y+oVft+6duvDClV4mjGN924AMHX0fDlj0Fg2y/MbrFqLyiiY7Y0yjbnGd/w1/P5NZMmc a4VmuJOmkHVfLkwyQ52rSVPnzXfdI/ctvHwgSTlZdxuMf0ZF1tQeUuV3shgQguH2j+a8 /qPA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:arc-authentication-results; bh=WIKir9qFyS6PyGX45L2GJJ9QpCiJL4P+avFHvlx092s=; b=cjn6vjmOAylUnwlV6Irp0LJJZawIEFWCuLhTvvcf53xNySTCNiOwI5IrLMf6xouSZl /KI27Lib79E51NJHVDv5D+MC2eEcbotYcYphhwxfcm8Ejtj0ctfDigFHNtKdv9V2G18R lz4nzUlYxlfsUE39fGTVbSYuG6eb5l+o94w7qPOVODUSt9J988VTuDrEQW20oMhC24IG rkRb7J+/FJC4F5VzMtiorgGvk/kTQsVe92oEGGAliqfBJTPARO5bNtgb3o+58v3zH9sR GzPmtsmy2kpn925uZB6CVnTZcACnIIBE3sbIO1PFK+HbkvJpOSATrcRmJq4Ncdu0aWcY caTA== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id r10si9842186pgq.332.2017.10.11.06.02.29; Wed, 11 Oct 2017 06:02:30 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756608AbdJKNC1 (ORCPT + 26 others); Wed, 11 Oct 2017 09:02:27 -0400 Received: from foss.arm.com ([217.140.101.70]:60454 "EHLO foss.arm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751991AbdJKNCW (ORCPT ); Wed, 11 Oct 2017 09:02:22 -0400 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 8E87B1529; Wed, 11 Oct 2017 06:02:22 -0700 (PDT) Received: from e107814-lin.cambridge.arm.com (e107814-lin.cambridge.arm.com [10.1.206.28]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id E5E033F483; Wed, 11 Oct 2017 06:02:20 -0700 (PDT) From: Suzuki K Poulose To: linux-arm-kernel@lists.infradead.org Cc: linux-kernel@vger.kernel.org, catalin.marinas@arm.com, will.deacon@arm.com, mark.rutland@arm.com, marc.zyngier@arm.com, dave.martin@arm.com, Dave Martin , Suzuki K Poulose Subject: [PATCH v3 2/2] arm64: docs: describe ELF hwcaps Date: Wed, 11 Oct 2017 14:01:03 +0100 Message-Id: <20171011130103.18362-2-suzuki.poulose@arm.com> X-Mailer: git-send-email 2.13.6 In-Reply-To: <20171011130103.18362-1-suzuki.poulose@arm.com> References: <20171011130103.18362-1-suzuki.poulose@arm.com> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Mark Rutland We don't document our ELF hwcaps, leaving developers to interpret them according to hearsay, guesswork, or (in exceptional cases) inspection of the current kernel code. This is less than optimal, and it would be far better if we had some definitive description of each of the ELF hwcaps that developers could refer to. This patch adds a document describing the (native) arm64 ELF hwcaps. Cc: Catalin Marinas Cc: Dave Martin Cc: Will Deacon Signed-off-by: Mark Rutland [ Updated new hwcap entries in the document ] Signed-off-by: Suzuki K Poulose --- Documentation/arm64/elf_hwcaps.txt | 156 +++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 Documentation/arm64/elf_hwcaps.txt -- 2.13.6 diff --git a/Documentation/arm64/elf_hwcaps.txt b/Documentation/arm64/elf_hwcaps.txt new file mode 100644 index 000000000000..0ba180522e3c --- /dev/null +++ b/Documentation/arm64/elf_hwcaps.txt @@ -0,0 +1,156 @@ +ARM64 ELF hwcaps +================ + +This document describes the usage and semantics of the arm64 ELF hwcaps. + + +1. Introduction +--------------- + +Some hardware or software features are only available on some CPU +implementations, and/or with certain kernel configurations, but have no +architected discovery mechanism available to userspace code at EL0. The +kernel exposes the presence of these features to userspace through a set +of flags called hwcaps, exposed in the auxilliary vector. + +Userspace software can test for features by acquiring the AT_HWCAP entry +of the auxilliary vector, and testing whether the relevant flags are +set, e.g. + +bool floating_point_is_present(void) +{ + unsigned long hwcaps = getauxval(AT_HWCAP); + if (hwcaps & HWCAP_FP) + return true; + + return false; +} + +Where software relies on a feature described by a hwcap, it should check +the relevant hwcap flag to verify that the feature is present before +attempting to make use of the feature. + +Features cannot be probed reliably through other means. When a feature +is not available, attempting to use it may result in unpredictable +behaviour, and is not guaranteed to result in any reliable indication +that the feature is unavailable, such as a SIGILL. + + +2. Interpretation of hwcaps +--------------------------- + +The majority of hwcaps are intended to indicate the presence of features +which are described by architected ID registers inaccessible to +userspace code at EL0. These hwcaps are defined in terms of ID register +fields, and should be interpreted with reference to the definition of +these fields in the ARM Architecture Reference Manual (ARM ARM). + +Such hwcaps are described below in the form: + + Functionality implied by idreg.field == val. + +Such hwcaps indicate the availability of functionality that the ARM ARM +defines as being present when idreg.field has value val, but do not +indicate that idreg.field is precisely equal to val, nor do they +indicate the absence of functionality implied by other values of +idreg.field. + +Other hwcaps may indicate the presence of features which cannot be +described by ID registers alone. These may be described without +reference to ID registers, and may refer to other documentation. + + +3. The hwcaps exposed in AT_HWCAP +--------------------------------- + +HWCAP_FP + + Functionality implied by ID_AA64PFR0_EL1.FP == 0b0000. + +HWCAP_ASIMD + + Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0000. + +HWCAP_EVTSTRM + + The generic timer is configured to generate events at a frequency of + approximately 100KHz. + +HWCAP_AES + + Functionality implied by ID_AA64ISAR1_EL1.AES == 0b0001. + +HWCAP_PMULL + + Functionality implied by ID_AA64ISAR1_EL1.AES == 0b0010. + +HWCAP_SHA1 + + Functionality implied by ID_AA64ISAR0_EL1.SHA1 == 0b0001. + +HWCAP_SHA2 + + Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0001. + +HWCAP_CRC32 + + Functionality implied by ID_AA64ISAR0_EL1.CRC32 == 0b0001. + +HWCAP_ATOMICS + + Functionality implied by ID_AA64ISAR0_EL1.Atomic == 0b0010. + +HWCAP_FPHP + + Functionality implied by ID_AA64PFR0_EL1.FP == 0b0001. + +HWCAP_ASIMDHP + + Functionality implied by ID_AA64PFR0_EL1.AdvSIMD == 0b0001. + +HWCAP_CPUID + + EL0 access to certain ID registers is available, to the extent + described by Documentation/arm64/cpu-feature-registers.txt. + + These ID registers may imply the availability of features. + +HWCAP_ASIMDRDM + + Functionality implied by ID_AA64ISAR0_EL1.RDM == 0b0001. + +HWCAP_JSCVT + + Functionality implied by ID_AA64ISAR1_EL1.JSCVT == 0b0001. + +HWCAP_FCMA + + Functionality implied by ID_AA64ISAR1_EL1.FCMA == 0b0001. + +HWCAP_LRCPC + + Functionality implied by ID_AA64ISAR1_EL1.LRCPC == 0b0001. + +HWCAP_DCPOP + + Functionality implied by ID_AA64ISAR1_EL1.DPB == 0b0001. + +HWCAP_SHA3 + + Functionality implied by ID_AA64ISAR0_EL1.SHA3 == 0b0001. + +HWCAP_SM3 + + Functionality implied by ID_AA64ISAR0_EL1.SM3 == 0b0001. + +HWCAP_SM4 + + Functionality implied by ID_AA64ISAR0_EL1.SM4 == 0b0001. + +HWCAP_ASIMDDP + + Functionality implied by ID_AA64ISAR0_EL1.DP == 0b0001. + +HWCAP_SHA512 + + Functionality implied by ID_AA64ISAR0_EL1.SHA2 == 0b0002.