From nobody Thu Dec 18 03:20:52 2025 Received: from mail-pf1-f202.google.com (mail-pf1-f202.google.com [209.85.210.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 3675D291174 for ; Wed, 7 May 2025 23:14:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.202 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659653; cv=none; b=F/LSg2deYESZ7cdx8dHztHADC0EUYRGDr7+IACcoCZhWiHTPkgJTDGieJai8KQEoDIm7ae6r93miH7FDpJb+/qOLnik6yJP8yE80U3LX7K5ixmMoR2pepXH22K9sKJ9pbHVwz0mrTZCms0wEztcuH4H0NuG4NNfRf74jyVsQl8k= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659653; c=relaxed/simple; bh=ItNkVSdL7sFyw7FeoSb/Z/olCNf2Je/V/2GQixqVn0M=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=aLeyXxq3YiWjx/AffA5KkH/o6jODzn3/2kvr4BNTofe9Gu+3NJY4v2+efl2N0dH8/aJpTYy/oibNxvhWLjJ0EQsavmKFOYK1jWFP3JJO958hNd9xSqFlzZVq1L8RTn9Jn9XqcL6o1LJnnt60evEZsY8RUVkXvctjxXIZvW13KCY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=aQvnpoyI; arc=none smtp.client-ip=209.85.210.202 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="aQvnpoyI" Received: by mail-pf1-f202.google.com with SMTP id d2e1a72fcca58-73c205898aaso263896b3a.2 for ; Wed, 07 May 2025 16:14:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1746659651; x=1747264451; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=qD57SKkqZaxYs/p61W6exkyQfrWa3L+7RSVvCzVl5yw=; b=aQvnpoyIcU9mKxS+OhHjyrH1X4fkZOAIqMwfyAZRh4nhmi9lZmMBnE5BWAdjiiLKgq MtCROjPyLAiHIA7Nh4ZmmyX4M5mAY5i9UdsEkvY5d6AHcQZNxbIbPsF8Qywi6GwjtzUB 7nEHsSuWvJBhFIi7wHTwrApo7jh2kTxmXGGHGRV/wYWchXLCtDX8dRbQv+Ny1gzjXtSB HFCSWCZ7j8h/+xKEoZNoKdMR+HPU6EGEQ/9CnNCVu+GkqILicgQD2YQxFentfDW1o5DV 94MDfftjygaXLj+1JXl9LolILm51lZBLIn++qB+Ae0k9L4jTN2nPMqDuqdClqFaRPkqg qTsQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1746659651; x=1747264451; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=qD57SKkqZaxYs/p61W6exkyQfrWa3L+7RSVvCzVl5yw=; b=aDIVNGQT/WgqZ/lid0S0onIKZcQ4eH/iB7d7yHvWTWUIlgVN009TV8LaVsyoclrUy0 Rmi6x/u4sv0fUcsvtQlas+ydL0pAtvndeFNczp3sxzYZuxftHybwIfeLKVihJiRKeCWA xUfipXaDUYc8BvJRm/zElRggKqVNMsMcN4N2VM/igD0Lwogbgdn5af7kSaW/4tsmBaaT d9F3LvQFHeuPpg8ZDAWM7s3pYmPCLZ1TlpU8nPlrSbd8DnZBAifOeJeQGvGyvA05teu9 grRQSG4LBDb2niiesH8uhfZPl1eqEiQFYd+9eyOmSED9U967lvtuio6PPA399K6DO6M2 fdfQ== X-Forwarded-Encrypted: i=1; AJvYcCWQ0pNLy20HoxLr2HCZKeLmI6VIK9gAV/1JqssCjE1tpCnMeM9LydfAvI3nNUZC0gXusYYMNbZOSACZIwA=@vger.kernel.org X-Gm-Message-State: AOJu0YwxvDkyYHKpVngly2pPis6w7BotQRwhtUk/iu5Wkmp3gbxoaDPK Htwy9vLY5QBhsiYYDCyLAk+ZOrL14MGUJeJF3ciClaclIgmN3Tm2VPEzA2I7D9SFhvFh3oirZJn R0VLoBRNc+oYnm14xB4gt15WiYw== X-Google-Smtp-Source: AGHT+IEOWq4rkVhHEj/6h7OdAxurwzrVewSgeYGZ1i6oOjodzUNosBj0lPXXFzbN8T5rezmGLTGBnQ6kReQ1r2lDJrY= X-Received: from pfbcj9.prod.google.com ([2002:a05:6a00:2989:b0:736:a70b:53c7]) (user=samitolvanen job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6a00:3394:b0:73d:ff02:8d83 with SMTP id d2e1a72fcca58-7409ced9480mr8536350b3a.3.1746659651362; Wed, 07 May 2025 16:14:11 -0700 (PDT) Date: Wed, 7 May 2025 23:14:05 +0000 In-Reply-To: <20250507231403.377725-7-samitolvanen@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20250507231403.377725-7-samitolvanen@google.com> X-Developer-Key: i=samitolvanen@google.com; a=openpgp; fpr=35CCFB63B283D6D3AEB783944CB5F6848BBC56EE X-Developer-Signature: v=1; a=openpgp-sha256; l=3927; i=samitolvanen@google.com; h=from:subject; bh=ItNkVSdL7sFyw7FeoSb/Z/olCNf2Je/V/2GQixqVn0M=; b=owGbwMvMwCEWxa662nLh8irG02pJDBnSL21iH+bpaC3ov8DEV7Q8bObyh7HGVvf6d01/9HXx9 eTf+ZXqHaUsDGIcDLJiiiwtX1dv3f3dKfXV5yIJmDmsTCBDGLg4BWAiLIyMDP2pG9icypfcSFw/ 86n6woMKzsXtn7j647rK9HoP+xXyVzL8T80+7WbjF94Zzp4u7pV0Z87D3qu9L//zOL2K4r/7+O5 jfgA= X-Mailer: git-send-email 2.49.0.987.g0cc8ee98dc-goog Message-ID: <20250507231403.377725-8-samitolvanen@google.com> Subject: [PATCH v3 1/5] gendwarfksyms: Clean up kABI rule look-ups From: Sami Tolvanen To: Masahiro Yamada Cc: Luis Chamberlain , Petr Pavlu , Daniel Gomez , linux-modules@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, Sami Tolvanen Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Reduce code duplication by moving kABI rule look-ups to separate functions. Signed-off-by: Sami Tolvanen Reviewed-by: Petr Pavlu --- scripts/gendwarfksyms/kabi.c | 101 +++++++++++++++-------------------- 1 file changed, 44 insertions(+), 57 deletions(-) diff --git a/scripts/gendwarfksyms/kabi.c b/scripts/gendwarfksyms/kabi.c index 66f01fcd1607..badf8d46b154 100644 --- a/scripts/gendwarfksyms/kabi.c +++ b/scripts/gendwarfksyms/kabi.c @@ -222,33 +222,55 @@ void kabi_read_rules(int fd) check(elf_end(elf)); } =20 -bool kabi_is_declonly(const char *fqn) +static char *get_enumerator_target(const char *fqn, const char *field) +{ + char *target =3D NULL; + + if (asprintf(&target, "%s %s", fqn, field) < 0) + error("asprintf failed for '%s %s'", fqn, field); + + return target; +} + +static struct rule *find_rule(enum kabi_rule_type type, const char *target) { struct rule *rule; =20 if (!stable) - return false; - if (!fqn || !*fqn) - return false; + return NULL; + if (!target || !*target) + return NULL; =20 hash_for_each_possible(rules, rule, hash, - rule_values_hash(KABI_RULE_TYPE_DECLONLY, fqn)) { - if (rule->type =3D=3D KABI_RULE_TYPE_DECLONLY && - !strcmp(fqn, rule->target)) - return true; + rule_values_hash(type, target)) { + if (rule->type =3D=3D type && !strcmp(target, rule->target)) + return rule; } =20 - return false; + return NULL; } =20 -static char *get_enumerator_target(const char *fqn, const char *field) +static struct rule *find_enumerator_rule(enum kabi_rule_type type, + const char *fqn, const char *field) { - char *target =3D NULL; + struct rule *rule; + char *target; =20 - if (asprintf(&target, "%s %s", fqn, field) < 0) - error("asprintf failed for '%s %s'", fqn, field); + if (!stable) + return NULL; + if (!fqn || !*fqn || !field || !*field) + return NULL; =20 - return target; + target =3D get_enumerator_target(fqn, field); + rule =3D find_rule(type, target); + + free(target); + return rule; +} + +bool kabi_is_declonly(const char *fqn) +{ + return !!find_rule(KABI_RULE_TYPE_DECLONLY, fqn); } =20 static unsigned long get_ulong_value(const char *value) @@ -267,58 +289,23 @@ static unsigned long get_ulong_value(const char *valu= e) =20 bool kabi_is_enumerator_ignored(const char *fqn, const char *field) { - bool match =3D false; - struct rule *rule; - char *target; - - if (!stable) - return false; - if (!fqn || !*fqn || !field || !*field) - return false; - - target =3D get_enumerator_target(fqn, field); - - hash_for_each_possible( - rules, rule, hash, - rule_values_hash(KABI_RULE_TYPE_ENUMERATOR_IGNORE, target)) { - if (rule->type =3D=3D KABI_RULE_TYPE_ENUMERATOR_IGNORE && - !strcmp(target, rule->target)) { - match =3D true; - break; - } - } - - free(target); - return match; + return !!find_enumerator_rule(KABI_RULE_TYPE_ENUMERATOR_IGNORE, fqn, + field); } =20 bool kabi_get_enumerator_value(const char *fqn, const char *field, unsigned long *value) { - bool match =3D false; struct rule *rule; - char *target; =20 - if (!stable) - return false; - if (!fqn || !*fqn || !field || !*field) - return false; - - target =3D get_enumerator_target(fqn, field); - - hash_for_each_possible(rules, rule, hash, - rule_values_hash(KABI_RULE_TYPE_ENUMERATOR_VALUE, - target)) { - if (rule->type =3D=3D KABI_RULE_TYPE_ENUMERATOR_VALUE && - !strcmp(target, rule->target)) { - *value =3D get_ulong_value(rule->value); - match =3D true; - break; - } + rule =3D find_enumerator_rule(KABI_RULE_TYPE_ENUMERATOR_VALUE, fqn, + field); + if (rule) { + *value =3D get_ulong_value(rule->value); + return true; } =20 - free(target); - return match; + return false; } =20 void kabi_free(void) --=20 2.49.0.987.g0cc8ee98dc-goog From nobody Thu Dec 18 03:20:52 2025 Received: from mail-pf1-f202.google.com (mail-pf1-f202.google.com [209.85.210.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id BEB7828DF5B for ; Wed, 7 May 2025 23:14:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.202 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659656; cv=none; b=V0HnLllhPkXXLVpVTUJPXlOVQiVXK4Q90IkPN2QjQvmiStBvYKhDRjXtFl8WDTO0exwSrZKO6LGGENPVS8ITtq6N5Y3qq4dKGM6ARL+u/9ULSqKk2L4yh/FfxHzKln0MOK+TDaaOtnNPU51yjpGKCsLP/5MmkHWhr1KyFL8II5o= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659656; c=relaxed/simple; bh=HgP0jMlO7dsRTimd8uO+TSE4jHCfEpiuqBa4mSyAxIA=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=O88Bbsaq2r3ylt4xftS8hi/mF94CwRvHGAR6356B6MAc7kJAKU7bOjyMKwPV7iqbnTe3y0/9TWi0PfYNlp+6hM/LLg6bp9EXfKW8rFmkQE2KVlAXm3badSk364vjr+wioWxgEPv9/orCedVAhJvm0Y6vUTn41npYRgN3zYind9o= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=FMxsWVxO; arc=none smtp.client-ip=209.85.210.202 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="FMxsWVxO" Received: by mail-pf1-f202.google.com with SMTP id d2e1a72fcca58-74041404f8dso282624b3a.0 for ; Wed, 07 May 2025 16:14:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1746659653; x=1747264453; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=d3FXF6C55XaC+/8qPK9kYbCADSFXqvOZhar+nxLyTg4=; b=FMxsWVxObjjKgVjOrQDfKUniaRF8igkdyCvabXKS4lAYmH7bxqasEnnZjmpgHRpB7F fFFfUCLQN1HY4CvdfJOIR5yNwtUCoizWTOH6D/7+b5vEFCViuUd+oFh0qf1fDmTtCzsv zvUBE4kR+AqKfyHDrT9p57F3vav7wOI58DBoIpBw9coFntIaXAUJfM2xIyQz3qFSCWod JjrsCNEwS+BlcO2n32v5ZN96QCQaffmAB4Vt9sjUbuBqUBTZwXWrIJke6wgQWMSi6ePg 8l6limzFzmEGKuKZXyreDz/BlWMmnfefFDrihczGcusZbiexlLYuxy2vyhq1bZkWExoI ClcQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1746659653; x=1747264453; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=d3FXF6C55XaC+/8qPK9kYbCADSFXqvOZhar+nxLyTg4=; b=i1aHqF80qrwZD2cIWSP3URUzbK1Y5YWSNBNCwpWx3oZ3wr/CydiCG0Q5MHWYZJ8L/8 dg1n3QQMhggY5sVnqmKjsg+kmRqKf/54H8TzV0F5AVaJyW01KzRrzsBxEWude8rvapnr eZjeWziM9PmImogCeLXmuLnfI4gXNzBebKaRKfpwUzs3yQu/NNgATX7DlpXut8Ykr8d4 X1PKJrdv7c0k29uVS3IPBpq5aJ9F5VCJj+f44tBqfwChask/UOvSj8zPEDYgiLRTLf+f wptpBUhB+6uT7RR7KlZ9SC2Qj3J+T6CACiQYn9+9KWQfeG2JApma9ZEjQ8+kocxE3MBR 3I0g== X-Forwarded-Encrypted: i=1; AJvYcCUBaChr74VQyTgSCYVMyVq0RRRN0BgAfoKsYNF8idxufCtCDjNSJRtLmnvvlf81nn8KPzA/CvaZS8teQJc=@vger.kernel.org X-Gm-Message-State: AOJu0Yw8ThPWKxA88n1mJv0R5CuDomfmzJ+rsUmKcxVUMicDASMl7OUD MixqjjSznJhrSDLjRR3eE2ORN52rY0dJYkptJgsOD5qq++CeN6wj+tPTa6+hgS3bmVsbxwN3Dru B7NTlwFpgKFnrj3455vwiYHZSgQ== X-Google-Smtp-Source: AGHT+IF3ZGlTveayJhKo5vhsFU98n/GWEz2r0LKJmBHPOc+IldJXAMZWxkwTENRItS5Z39RtE5JtYm54Q1LwDXbIPLY= X-Received: from pfx51.prod.google.com ([2002:a05:6a00:a473:b0:730:796b:a54a]) (user=samitolvanen job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6a00:410c:b0:736:a540:c9ad with SMTP id d2e1a72fcca58-7409cfdbdddmr7229190b3a.20.1746659653063; Wed, 07 May 2025 16:14:13 -0700 (PDT) Date: Wed, 7 May 2025 23:14:06 +0000 In-Reply-To: <20250507231403.377725-7-samitolvanen@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20250507231403.377725-7-samitolvanen@google.com> X-Developer-Key: i=samitolvanen@google.com; a=openpgp; fpr=35CCFB63B283D6D3AEB783944CB5F6848BBC56EE X-Developer-Signature: v=1; a=openpgp-sha256; l=7598; i=samitolvanen@google.com; h=from:subject; bh=HgP0jMlO7dsRTimd8uO+TSE4jHCfEpiuqBa4mSyAxIA=; b=owGbwMvMwCEWxa662nLh8irG02pJDBnSL22uCPrkq/502c3883ekm9e/6qN64dwaki/+OPQsD f/ildDcUcrCIMbBICumyNLydfXW3d+dUl99LpKAmcPKBDKEgYtTACbSeZPhJ2OtuxfDpnP9jpzZ P9axfdpaJaHKyLpkVsTnJZYTs1rVZzAynP+eaMWpMDVIoV6pQc3ijcjiQI81Pad5vS9bb36SsG4 qDwA= X-Mailer: git-send-email 2.49.0.987.g0cc8ee98dc-goog Message-ID: <20250507231403.377725-9-samitolvanen@google.com> Subject: [PATCH v3 2/5] gendwarfksyms: Add a kABI rule to override byte_size attributes From: Sami Tolvanen To: Masahiro Yamada Cc: Luis Chamberlain , Petr Pavlu , Daniel Gomez , linux-modules@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, Sami Tolvanen Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" A data structure can be partially opaque to modules if its allocation is handled by the core kernel, and modules only need to access some of its members. In this situation, it's possible to append new members to the structure without breaking the ABI, as long as the layout for the original members remains unchanged. For example, consider the following struct: struct s { unsigned long a; void *p; }; gendwarfksyms --stable --dump-dies produces the following type expansion: variable structure_type s { member base_type long unsigned int byte_size(8) encoding(7) a data_member_location(0) , member pointer_type { base_type void } byte_size(8) p data_member_location(8) } byte_size(16) To append new members, we can use the KABI_IGNORE() macro to hide them from gendwarfksyms --stable: struct s { /* old members with unchanged layout */ unsigned long a; void *p; /* new members not accessed by modules */ KABI_IGNORE(0, unsigned long n); }; However, we can't hide the fact that adding new members changes the struct size, as seen in the updated type string: variable structure_type s { member base_type long unsigned int byte_size(8) encoding(7) a data_member_location(0) , member pointer_type { base_type void } byte_size(8) p data_member_location(8) } byte_size(24) In order to support this use case, add a kABI rule that makes it possible to override the byte_size attribute for types: /* * struct s allocation is handled by the kernel, so * appending new members without changing the original * layout won't break the ABI. */ KABI_BYTE_SIZE(s, 16); This results in a type string that's unchanged from the original and therefore, won't change versions for symbols that reference the changed structure. Signed-off-by: Sami Tolvanen Reviewed-by: Petr Pavlu --- scripts/gendwarfksyms/dwarf.c | 14 ++++++++++++- scripts/gendwarfksyms/examples/kabi.h | 7 +++++++ scripts/gendwarfksyms/examples/kabi_ex.c | 2 ++ scripts/gendwarfksyms/examples/kabi_ex.h | 22 +++++++++++++++++++++ scripts/gendwarfksyms/gendwarfksyms.h | 1 + scripts/gendwarfksyms/kabi.c | 25 ++++++++++++++++++++++++ 6 files changed, 70 insertions(+), 1 deletion(-) diff --git a/scripts/gendwarfksyms/dwarf.c b/scripts/gendwarfksyms/dwarf.c index eed247d8abfc..13ea7bf1ae7d 100644 --- a/scripts/gendwarfksyms/dwarf.c +++ b/scripts/gendwarfksyms/dwarf.c @@ -228,12 +228,24 @@ static void process_fqn(struct die *cache, Dwarf_Die = *die) DEFINE_PROCESS_UDATA_ATTRIBUTE(accessibility) DEFINE_PROCESS_UDATA_ATTRIBUTE(alignment) DEFINE_PROCESS_UDATA_ATTRIBUTE(bit_size) -DEFINE_PROCESS_UDATA_ATTRIBUTE(byte_size) DEFINE_PROCESS_UDATA_ATTRIBUTE(encoding) DEFINE_PROCESS_UDATA_ATTRIBUTE(data_bit_offset) DEFINE_PROCESS_UDATA_ATTRIBUTE(data_member_location) DEFINE_PROCESS_UDATA_ATTRIBUTE(discr_value) =20 +static void process_byte_size_attr(struct die *cache, Dwarf_Die *die) +{ + Dwarf_Word value; + unsigned long override; + + if (get_udata_attr(die, DW_AT_byte_size, &value)) { + if (stable && kabi_get_byte_size(cache->fqn, &override)) + value =3D override; + + process_fmt(cache, " byte_size(%" PRIu64 ")", value); + } +} + /* Match functions -- die_match_callback_t */ #define DEFINE_MATCH(type) \ static bool match_##type##_type(Dwarf_Die *die) \ diff --git a/scripts/gendwarfksyms/examples/kabi.h b/scripts/gendwarfksyms/= examples/kabi.h index 97a5669b083d..86f4428e0479 100644 --- a/scripts/gendwarfksyms/examples/kabi.h +++ b/scripts/gendwarfksyms/examples/kabi.h @@ -89,6 +89,13 @@ #define KABI_ENUMERATOR_VALUE(fqn, field, value) \ __KABI_RULE(enumerator_value, fqn field, value) =20 +/* + * KABI_BYTE_SIZE(fqn, value) + * Set the byte_size attribute for the struct/union/enum fqn to + * value bytes. + */ +#define KABI_BYTE_SIZE(fqn, value) __KABI_RULE(byte_size, fqn, value) + /* * KABI_RESERVE * Reserve some "padding" in a structure for use by LTS backports. diff --git a/scripts/gendwarfksyms/examples/kabi_ex.c b/scripts/gendwarfksy= ms/examples/kabi_ex.c index 0b7ffd830541..b73ee5399a59 100644 --- a/scripts/gendwarfksyms/examples/kabi_ex.c +++ b/scripts/gendwarfksyms/examples/kabi_ex.c @@ -28,3 +28,5 @@ struct ex2c ex2c; struct ex3a ex3a; struct ex3b ex3b; struct ex3c ex3c; + +struct ex4a ex4a; diff --git a/scripts/gendwarfksyms/examples/kabi_ex.h b/scripts/gendwarfksy= ms/examples/kabi_ex.h index 1736e0f65208..092c8cb7bcd7 100644 --- a/scripts/gendwarfksyms/examples/kabi_ex.h +++ b/scripts/gendwarfksyms/examples/kabi_ex.h @@ -260,4 +260,26 @@ _Static_assert(sizeof(struct ex3a) =3D=3D sizeof(struc= t ex3c), "ex3a size doesn't ma * STABLE-NEXT: } byte_size(16) */ =20 +/* + * Example: An ignored field added to an end of a partially opaque struct, + * while keeping the byte_size attribute unchanged. + */ + +struct ex4a { + unsigned long a; + KABI_IGNORE(0, unsigned long b); +}; + +/* + * This may be safe if the structure allocation is managed by the core ker= nel + * and the layout remains unchanged except for appended new members. + */ +KABI_BYTE_SIZE(ex4a, 8); + +/* + * STABLE: variable structure_type ex4a { + * STABLE-NEXT: member base_type [[ULONG]] byte_size(8) encoding(7) a da= ta_member_location(0) + * STABLE-NEXT: } byte_size(8) + */ + #endif /* __KABI_EX_H__ */ diff --git a/scripts/gendwarfksyms/gendwarfksyms.h b/scripts/gendwarfksyms/= gendwarfksyms.h index 2feec168bf73..2db49c2ad50e 100644 --- a/scripts/gendwarfksyms/gendwarfksyms.h +++ b/scripts/gendwarfksyms/gendwarfksyms.h @@ -287,6 +287,7 @@ void generate_symtypes_and_versions(FILE *file); * kabi.c */ =20 +bool kabi_get_byte_size(const char *fqn, unsigned long *value); bool kabi_is_enumerator_ignored(const char *fqn, const char *field); bool kabi_get_enumerator_value(const char *fqn, const char *field, unsigned long *value); diff --git a/scripts/gendwarfksyms/kabi.c b/scripts/gendwarfksyms/kabi.c index badf8d46b154..61620ff647bd 100644 --- a/scripts/gendwarfksyms/kabi.c +++ b/scripts/gendwarfksyms/kabi.c @@ -54,11 +54,19 @@ */ #define KABI_RULE_TAG_ENUMERATOR_VALUE "enumerator_value" =20 +/* + * Rule: byte_size + * - For the fqn_field in the target field, set the byte_size + * attribute to the value in the value field. + */ +#define KABI_RULE_TAG_BYTE_SIZE "byte_size" + enum kabi_rule_type { KABI_RULE_TYPE_UNKNOWN, KABI_RULE_TYPE_DECLONLY, KABI_RULE_TYPE_ENUMERATOR_IGNORE, KABI_RULE_TYPE_ENUMERATOR_VALUE, + KABI_RULE_TYPE_BYTE_SIZE, }; =20 #define RULE_HASH_BITS 7 @@ -127,6 +135,10 @@ void kabi_read_rules(int fd) .type =3D KABI_RULE_TYPE_ENUMERATOR_VALUE, .tag =3D KABI_RULE_TAG_ENUMERATOR_VALUE, }, + { + .type =3D KABI_RULE_TYPE_BYTE_SIZE, + .tag =3D KABI_RULE_TAG_BYTE_SIZE, + }, }; =20 if (!stable) @@ -308,6 +320,19 @@ bool kabi_get_enumerator_value(const char *fqn, const = char *field, return false; } =20 +bool kabi_get_byte_size(const char *fqn, unsigned long *value) +{ + struct rule *rule; + + rule =3D find_rule(KABI_RULE_TYPE_BYTE_SIZE, fqn); + if (rule) { + *value =3D get_ulong_value(rule->value); + return true; + } + + return false; +} + void kabi_free(void) { struct hlist_node *tmp; --=20 2.49.0.987.g0cc8ee98dc-goog From nobody Thu Dec 18 03:20:52 2025 Received: from mail-pl1-f202.google.com (mail-pl1-f202.google.com [209.85.214.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 4B774291884 for ; Wed, 7 May 2025 23:14:15 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.202 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659658; cv=none; b=B7ff87Uy74cSPlkMMlKhYat9Al50FguLsB3PJbB0EM4LR91PLpk9LaW3TXaq+35nrPQGyWXz5eKZ1+T688id6m2shjwhzwcb0XXvUFs0VA23I9G9DkvGKqPbIk6f4+bdCCrCR7x43z6PS2mOWkJf9TBrRhpUOmi1SDan6+x31no= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659658; c=relaxed/simple; bh=WJVv+F/IReSeS1dXKSnftol5p1+Kb+p+lY9xAYcCpIE=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=LC6boMs9ewoXqYDsoiFLCDGCPR2vCY4/p1hY2NC9XGOG5iaoZRTzrlZS3BM9VXoNXnqajW73CtQpEVwrKG1desKAONBdXXIUXXCBq3PQaae8jPR+6zOKEpumflp3qr0ypn1SWsIX1HFOtjDtcvaCYoAA7k2uLJyaNIagI11jrrA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=d3RRlhWP; arc=none smtp.client-ip=209.85.214.202 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="d3RRlhWP" Received: by mail-pl1-f202.google.com with SMTP id d9443c01a7336-22e7f041997so5102785ad.3 for ; Wed, 07 May 2025 16:14:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1746659654; x=1747264454; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=7SrY24qH6WEJRs8Tqs5tyNmAdq/M++Or3BPhbb9qRaQ=; b=d3RRlhWPyfu0Wc/3/mzOiWGHsRQedOPZVpR/Z16LW6e/qIqckeaWSZEWgvseuBK0Pj +bb/0NX5j37n7ozB+tH7pwEiGp4FS8v/ZJkHor5ljDVEmGSg0nkno6u5Zo/7FSb9l/T6 wcCmk0l9piZeMf1ihNhJYsTa4EfDQaGZY/ul/tq4vsvg/AqCOmOyZHPBfRvalHM0wKE8 hb86s4VGvxhKBFm9/koYGJqBfnfgGtaxk/5oKPmtt0p3AWYpRGLjgfULrR8u7dq8aeqw oYBsxWxLmqlsaE9zTF8e+UxDCkuHXzQJAtojiV/sCAgRw5a7HJlPEnu/iPeJUlVXKcIo HRYw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1746659654; x=1747264454; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=7SrY24qH6WEJRs8Tqs5tyNmAdq/M++Or3BPhbb9qRaQ=; b=qVBNkRbQ9r6rFy2+Mb/mhvWxUSqn4yJLVIIahvHG2WLgpXrJsEXtBGcFzx5EHYUick DO54COodJVMxSwwaDqR9TpoiotMSjxUetN/Y7Pw+cwvHjr+/PC4f7Y5PbYp7B0UI/j30 93Ac4H3z/nRql8wdIvJiD3Tcwed9OXU+rY9DRoFEQ5kyW4bz+k0gCqabriH2lvb7GHNp soNbNqZ/eHfSz9pQDQE3XauEstRC+/VxE+KpiNsnjryg/MAqTt+z1DiOv0t1usbnGdaL IWwfgKGfCLdtB15+y8vtFV1B5XcU+sgx16ncvtDSnf65b5dYW1VrQb1rhZxnGo3p85B3 uI5Q== X-Forwarded-Encrypted: i=1; AJvYcCVSnk3dYVtyPYIqvP558zOGF9aU2MobSCpdbjY4WWdm8QDNbAmB9ReTXa0W1mKfAkTBTSDeMOrN+XSIjDs=@vger.kernel.org X-Gm-Message-State: AOJu0Ywvj05o+Tikq01foHt6u2xbVHw/bi8YglyQHFYgxGzxheCIH3UV NmrkJ0gL9SyClF5HTGZXsFhgyhtz6M9v5Bo7rI5iUokVMXptDrhJ7z/sX2ZPlYkW2GbRGQlpthE S0B6r4mNhA9KK6avl1vRqNjgOmA== X-Google-Smtp-Source: AGHT+IF+uiiPwr+ynZ4F+9/F2kgvOsuIPPJBbNzOh99Cd5IwSBKieqQGdTkO7dYNGaU/Iybmy2UnXpDvpWP8vY7e8tA= X-Received: from pgly26.prod.google.com ([2002:a63:181a:0:b0:b1f:866e:b28a]) (user=samitolvanen job=prod-delivery.src-stubby-dispatcher) by 2002:a17:903:3bb0:b0:224:1ec0:8a1a with SMTP id d9443c01a7336-22e5ee0f11bmr67283475ad.51.1746659654723; Wed, 07 May 2025 16:14:14 -0700 (PDT) Date: Wed, 7 May 2025 23:14:07 +0000 In-Reply-To: <20250507231403.377725-7-samitolvanen@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20250507231403.377725-7-samitolvanen@google.com> X-Developer-Key: i=samitolvanen@google.com; a=openpgp; fpr=35CCFB63B283D6D3AEB783944CB5F6848BBC56EE X-Developer-Signature: v=1; a=openpgp-sha256; l=16739; i=samitolvanen@google.com; h=from:subject; bh=WJVv+F/IReSeS1dXKSnftol5p1+Kb+p+lY9xAYcCpIE=; b=owGbwMvMwCEWxa662nLh8irG02pJDBnSL23PGRzflP/3cGbZ6pc+yjuMiudGXHtYIMXOyq5gs e7olNr5HaUsDGIcDLJiiiwtX1dv3f3dKfXV5yIJmDmsTCBDGLg4BWAiou6MDL+Yf17d2vDP5s77 WTGiMleWz4yRv82oOe3+5Ldcu+fpBB1lZPjKl5T+veTn64x82cfH6xMWfP+R+Ofg/WeWQdOU/O7 rf2MGAA== X-Mailer: git-send-email 2.49.0.987.g0cc8ee98dc-goog Message-ID: <20250507231403.377725-10-samitolvanen@google.com> Subject: [PATCH v3 3/5] gendwarfksyms: Add a kABI rule to override type strings From: Sami Tolvanen To: Masahiro Yamada Cc: Luis Chamberlain , Petr Pavlu , Daniel Gomez , linux-modules@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, Sami Tolvanen , Giuliano Procida Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" In rare situations where distributions must make significant changes to otherwise opaque data structures that have inadvertently been included in the published ABI, keeping symbol versions stable using the existing kABI macros can become tedious. For example, Android decided to switch to a newer io_uring implementation in the 5.10 GKI kernel "to resolve a huge number of potential, and known, problems with the codebase," requiring "horrible hacks" with genksyms: "A number of the io_uring structures get used in other core kernel structures, only as "opaque" pointers, so there is not any real ABI breakage. But, due to the visibility of the structures going away, the CRC values of many scheduler variables and functions were changed." -- https://r.android.com/2425293 While these specific changes probably could have been hidden from gendwarfksyms using the existing kABI macros, this may not always be the case. Add a last resort kABI rule that allows distribution maintainers to fully override a type string for a symbol or a type. Also add a more informative error message in case we find a non-existent type references when calculating versions. Suggested-by: Giuliano Procida Signed-off-by: Sami Tolvanen Reviewed-by: Petr Pavlu --- scripts/gendwarfksyms/examples/kabi.h | 14 ++- scripts/gendwarfksyms/examples/kabi_ex.c | 5 + scripts/gendwarfksyms/examples/kabi_ex.h | 79 ++++++++++++- scripts/gendwarfksyms/gendwarfksyms.h | 1 + scripts/gendwarfksyms/kabi.c | 25 ++++ scripts/gendwarfksyms/types.c | 140 ++++++++++++++++++++--- 6 files changed, 246 insertions(+), 18 deletions(-) diff --git a/scripts/gendwarfksyms/examples/kabi.h b/scripts/gendwarfksyms/= examples/kabi.h index 86f4428e0479..170733a3fba4 100644 --- a/scripts/gendwarfksyms/examples/kabi.h +++ b/scripts/gendwarfksyms/examples/kabi.h @@ -37,11 +37,14 @@ #define __stringify(x...) __stringify_1(x) #endif =20 -#define __KABI_RULE(hint, target, value) \ +#define ___KABI_RULE(hint, target, value) \ static const char __PASTE(__gendwarfksyms_rule_, \ __COUNTER__)[] __used __aligned(1) \ __section(".discard.gendwarfksyms.kabi_rules") =3D \ - "1\0" #hint "\0" #target "\0" #value + "1\0" #hint "\0" target "\0" value + +#define __KABI_RULE(hint, target, value) \ + ___KABI_RULE(hint, #target, #value) =20 #define __KABI_NORMAL_SIZE_ALIGN(_orig, _new) = \ union { = \ @@ -96,6 +99,13 @@ */ #define KABI_BYTE_SIZE(fqn, value) __KABI_RULE(byte_size, fqn, value) =20 +/* + * KABI_TYPE_STRING(type, str) + * For the given type, override the type string used in symtypes + * output and version calculation with str. + */ +#define KABI_TYPE_STRING(type, str) ___KABI_RULE(type_string, type, str) + /* * KABI_RESERVE * Reserve some "padding" in a structure for use by LTS backports. diff --git a/scripts/gendwarfksyms/examples/kabi_ex.c b/scripts/gendwarfksy= ms/examples/kabi_ex.c index b73ee5399a59..1f799eb7c756 100644 --- a/scripts/gendwarfksyms/examples/kabi_ex.c +++ b/scripts/gendwarfksyms/examples/kabi_ex.c @@ -30,3 +30,8 @@ struct ex3b ex3b; struct ex3c ex3c; =20 struct ex4a ex4a; + +struct ex5a ex5a; +struct ex5b ex5b; + +int ex6a; diff --git a/scripts/gendwarfksyms/examples/kabi_ex.h b/scripts/gendwarfksy= ms/examples/kabi_ex.h index 092c8cb7bcd7..785b211d9c58 100644 --- a/scripts/gendwarfksyms/examples/kabi_ex.h +++ b/scripts/gendwarfksyms/examples/kabi_ex.h @@ -21,6 +21,12 @@ * ./gendwarfksyms --stable --dump-dies \ * examples/kabi_ex.o 2>&1 >/dev/null | \ * FileCheck examples/kabi_ex.h --check-prefix=3DSTABLE + + * $ nm examples/kabi_ex.o | awk '{ print $NF }' | \ + * ./gendwarfksyms --stable --dump-versions \ + * examples/kabi_ex.o 2>&1 >/dev/null | \ + * sort | \ + * FileCheck examples/kabi_ex.h --check-prefix=3DVERSIONS */ =20 #ifndef __KABI_EX_H__ @@ -170,7 +176,7 @@ struct ex2a { /* * STABLE: variable structure_type ex2a { * STABLE-NEXT: member base_type int byte_size(4) encoding(5) a data_mem= ber_location(0) , - * STABLE-NEXT: member base_type [[ULONG:long unsigned int|unsigned long= ]] byte_size(8) encoding(7) b data_member_location(8) + * STABLE-NEXT: member base_type [[ULONG]] byte_size(8) encoding(7) b da= ta_member_location(8) * STABLE-NEXT: member base_type int byte_size(4) encoding(5) c data_mem= ber_location(16) , * STABLE-NEXT: member base_type [[ULONG]] byte_size(8) encoding(7) d da= ta_member_location(24) * STABLE-NEXT: } byte_size(32) @@ -227,7 +233,7 @@ struct ex3a { =20 /* * STABLE: variable structure_type ex3a { - * STABLE-NEXT: member base_type [[ULONG:long unsigned int|unsigned long= ]] byte_size(8) encoding(7) a data_member_location(0) + * STABLE-NEXT: member base_type [[ULONG]] byte_size(8) encoding(7) a da= ta_member_location(0) * STABLE-NEXT: member base_type [[ULONG]] byte_size(8) encoding(7) unus= ed data_member_location(8) * STABLE-NEXT: } byte_size(16) */ @@ -282,4 +288,73 @@ KABI_BYTE_SIZE(ex4a, 8); * STABLE-NEXT: } byte_size(8) */ =20 +/* + * Example: A type string override. + */ + +struct ex5a { + unsigned long a; +}; + +/* + * This may be safe if the structure is fully opaque to modules, even thou= gh + * its definition has inadvertently become part of the ABI. + */ +KABI_TYPE_STRING( + "s#ex5a", + "structure_type ex5a { member pointer_type { s#ex4a } byte_size(8) p data= _member_location(0) } byte_size(8)"); + +/* + * Make sure the fully expanded type string includes ex4a. + * + * VERSIONS: ex5a variable structure_type ex5a { + * VERSIONS-SAME: member pointer_type { + * VERSIONS-SAME: structure_type ex4a { + * VERSIONS-SAME: member base_type [[ULONG:long unsigned int|unsigne= d long]] byte_size(8) encoding(7) a data_member_location(0) + * VERSIONS-SAME: } byte_size(8) + * VERSIONS-SAME: } byte_size(8) p data_member_location(0) + * VERSIONS-SAME: } byte_size(8) + */ + +/* + * Example: A type string definition for a non-existent type. + */ + +struct ex5b { + unsigned long a; +}; + +/* Replace the type string for struct ex5b */ +KABI_TYPE_STRING( + "s#ex5b", + "structure_type ex5b { member pointer_type { s#ex5c } byte_size(8) p data= _member_location(0) } byte_size(8)"); + +/* Define a type string for a non-existent struct ex5c */ +KABI_TYPE_STRING( + "s#ex5c", + "structure_type ex5c { member base_type int byte_size(4) encoding(5) n da= ta_member_location(0) } byte_size(8)"); + +/* + * Make sure the fully expanded type string includes the definition for ex= 5c. + * + * VERSIONS: ex5b variable structure_type ex5b { + * VERSIONS-SAME: member pointer_type { + * VERSIONS-SAME: structure_type ex5c { + * VERSIONS-SAME: member base_type int byte_size(4) encoding(5) n da= ta_member_location(0) + * VERSIONS-SAME: } byte_size(8) + * VERSIONS-SAME: } byte_size(8) p data_member_location(0) + * VERSIONS-SAME: } byte_size(8) + */ + +/* + * Example: A type string override for a symbol. + */ + +KABI_TYPE_STRING("ex6a", "variable s#ex5c"); + +/* + * VERSIONS: ex6a variable structure_type ex5c { + * VERSIONS-SAME: member base_type int byte_size(4) encoding(5) n data_m= ember_location(0) + * VERSIONS-SAME: } byte_size(8) + */ #endif /* __KABI_EX_H__ */ diff --git a/scripts/gendwarfksyms/gendwarfksyms.h b/scripts/gendwarfksyms/= gendwarfksyms.h index 2db49c2ad50e..7dd03ffe0c5c 100644 --- a/scripts/gendwarfksyms/gendwarfksyms.h +++ b/scripts/gendwarfksyms/gendwarfksyms.h @@ -292,6 +292,7 @@ bool kabi_is_enumerator_ignored(const char *fqn, const = char *field); bool kabi_get_enumerator_value(const char *fqn, const char *field, unsigned long *value); bool kabi_is_declonly(const char *fqn); +bool kabi_get_type_string(const char *type, const char **str); =20 void kabi_read_rules(int fd); void kabi_free(void); diff --git a/scripts/gendwarfksyms/kabi.c b/scripts/gendwarfksyms/kabi.c index 61620ff647bd..b3ade713778f 100644 --- a/scripts/gendwarfksyms/kabi.c +++ b/scripts/gendwarfksyms/kabi.c @@ -61,12 +61,20 @@ */ #define KABI_RULE_TAG_BYTE_SIZE "byte_size" =20 +/* + * Rule: type_string + * - For the type reference in the fqn field, use the type string + * in the value field. + */ +#define KABI_RULE_TAG_TYPE_STRING "type_string" + enum kabi_rule_type { KABI_RULE_TYPE_UNKNOWN, KABI_RULE_TYPE_DECLONLY, KABI_RULE_TYPE_ENUMERATOR_IGNORE, KABI_RULE_TYPE_ENUMERATOR_VALUE, KABI_RULE_TYPE_BYTE_SIZE, + KABI_RULE_TYPE_TYPE_STRING, }; =20 #define RULE_HASH_BITS 7 @@ -139,6 +147,10 @@ void kabi_read_rules(int fd) .type =3D KABI_RULE_TYPE_BYTE_SIZE, .tag =3D KABI_RULE_TAG_BYTE_SIZE, }, + { + .type =3D KABI_RULE_TYPE_TYPE_STRING, + .tag =3D KABI_RULE_TAG_TYPE_STRING, + }, }; =20 if (!stable) @@ -333,6 +345,19 @@ bool kabi_get_byte_size(const char *fqn, unsigned long= *value) return false; } =20 +bool kabi_get_type_string(const char *type, const char **str) +{ + struct rule *rule; + + rule =3D find_rule(KABI_RULE_TYPE_TYPE_STRING, type); + if (rule) { + *str =3D rule->value; + return true; + } + + return false; +} + void kabi_free(void) { struct hlist_node *tmp; diff --git a/scripts/gendwarfksyms/types.c b/scripts/gendwarfksyms/types.c index 6f37289104ff..39ce1770e463 100644 --- a/scripts/gendwarfksyms/types.c +++ b/scripts/gendwarfksyms/types.c @@ -100,7 +100,7 @@ static void type_expansion_append(struct type_expansion= *type, const char *s, #define TYPE_HASH_BITS 12 static HASHTABLE_DEFINE(type_map, 1 << TYPE_HASH_BITS); =20 -static int type_map_get(const char *name, struct type_expansion **res) +static int __type_map_get(const char *name, struct type_expansion **res) { struct type_expansion *e; =20 @@ -114,11 +114,12 @@ static int type_map_get(const char *name, struct type= _expansion **res) return -1; } =20 -static void type_map_add(const char *name, struct type_expansion *type) +static struct type_expansion *type_map_add(const char *name, + struct type_expansion *type) { struct type_expansion *e; =20 - if (type_map_get(name, &e)) { + if (__type_map_get(name, &e)) { e =3D xmalloc(sizeof(struct type_expansion)); type_expansion_init(e); e->name =3D xstrdup(name); @@ -130,7 +131,7 @@ static void type_map_add(const char *name, struct type_= expansion *type) } else { /* Use the longest available expansion */ if (type->len <=3D e->len) - return; + return e; =20 type_list_free(&e->expanded); =20 @@ -148,6 +149,34 @@ static void type_map_add(const char *name, struct type= _expansion *type) type_list_write(&e->expanded, stderr); checkp(fputs("\n", stderr)); } + + return e; +} + +static void type_parse(const char *name, const char *str, + struct type_expansion *type); + +static int type_map_get(const char *name, struct type_expansion **res) +{ + struct type_expansion type; + const char *override; + + if (!__type_map_get(name, res)) + return 0; + + /* + * If die_map didn't contain a type, we might still have + * a type_string kABI rule that defines it. + */ + if (stable && kabi_get_type_string(name, &override)) { + type_expansion_init(&type); + type_parse(name, override, &type); + *res =3D type_map_add(name, &type); + type_expansion_free(&type); + return 0; + } + + return -1; } =20 static void type_map_write(FILE *file) @@ -267,15 +296,18 @@ static char *get_type_name(struct die *cache) return name; } =20 -static void __calculate_version(struct version *version, struct list_head = *list) +static void __calculate_version(struct version *version, + struct type_expansion *type) { struct type_list_entry *entry; struct type_expansion *e; =20 /* Calculate a CRC over an expanded type string */ - list_for_each_entry(entry, list, list) { + list_for_each_entry(entry, &type->expanded, list) { if (is_type_prefix(entry->str)) { - check(type_map_get(entry->str, &e)); + if (type_map_get(entry->str, &e)) + error("unknown type reference to '%s' when expanding '%s'", + entry->str, type->name); =20 /* * It's sufficient to expand each type reference just @@ -285,7 +317,7 @@ static void __calculate_version(struct version *version= , struct list_head *list) version_add(version, entry->str); } else { cache_mark_expanded(&expansion_cache, e); - __calculate_version(version, &e->expanded); + __calculate_version(version, e); } } else { version_add(version, entry->str); @@ -293,10 +325,11 @@ static void __calculate_version(struct version *versi= on, struct list_head *list) } } =20 -static void calculate_version(struct version *version, struct list_head *l= ist) +static void calculate_version(struct version *version, + struct type_expansion *type) { version_init(version); - __calculate_version(version, list); + __calculate_version(version, type); cache_free(&expansion_cache); } =20 @@ -372,9 +405,80 @@ static void type_expand(struct die *cache, struct type= _expansion *type, cache_free(&expansion_cache); } =20 +static void type_parse(const char *name, const char *str, + struct type_expansion *type) +{ + char *fragment; + size_t start =3D 0; + size_t end; + size_t pos; + + if (!*str) + error("empty type string override for '%s'", name); + + type_expansion_init(type); + + for (pos =3D 0; str[pos]; ++pos) { + bool empty; + char marker =3D ' '; + + if (!is_type_prefix(&str[pos])) + continue; + + end =3D pos + 2; + + /* + * Find the end of the type reference. If the type name contains + * spaces, it must be in single quotes. + */ + if (str[end] =3D=3D '\'') { + marker =3D '\''; + ++end; + } + while (str[end] && str[end] !=3D marker) + ++end; + + /* Check that we have a non-empty type name */ + if (marker =3D=3D '\'') { + if (str[end] !=3D marker) + error("incomplete %c# type reference for '%s' (string : '%s')", + str[pos], name, str); + empty =3D end =3D=3D pos + 3; + ++end; + } else { + empty =3D end =3D=3D pos + 2; + } + if (empty) + error("empty %c# type name for '%s' (string: '%s')", + str[pos], name, str); + + /* Append the part of the string before the type reference */ + if (pos > start) { + fragment =3D xstrndup(&str[start], pos - start); + type_expansion_append(type, fragment, fragment); + } + + /* + * Append the type reference -- note that if the reference + * is invalid, i.e. points to a non-existent type, we will + * print out an error when calculating versions. + */ + fragment =3D xstrndup(&str[pos], end - pos); + type_expansion_append(type, fragment, fragment); + + start =3D end; + pos =3D end - 1; + } + + /* Append the rest of the type string, if there's any left */ + if (str[start]) + type_expansion_append(type, &str[start], NULL); +} + static void expand_type(struct die *cache, void *arg) { struct type_expansion type; + const char *override; char *name; =20 if (cache->mapped) @@ -399,9 +503,13 @@ static void expand_type(struct die *cache, void *arg) return; =20 debug("%s", name); - type_expand(cache, &type, true); - type_map_add(name, &type); =20 + if (stable && kabi_get_type_string(name, &override)) + type_parse(name, override, &type); + else + type_expand(cache, &type, true); + + type_map_add(name, &type); type_expansion_free(&type); free(name); } @@ -410,6 +518,7 @@ static void expand_symbol(struct symbol *sym, void *arg) { struct type_expansion type; struct version version; + const char *override; struct die *cache; =20 /* @@ -423,11 +532,14 @@ static void expand_symbol(struct symbol *sym, void *a= rg) if (__die_map_get(sym->die_addr, DIE_SYMBOL, &cache)) return; /* We'll warn about missing CRCs later. */ =20 - type_expand(cache, &type, false); + if (stable && kabi_get_type_string(sym->name, &override)) + type_parse(sym->name, override, &type); + else + type_expand(cache, &type, false); =20 /* If the symbol already has a version, don't calculate it again. */ if (sym->state !=3D SYMBOL_PROCESSED) { - calculate_version(&version, &type.expanded); + calculate_version(&version, &type); symbol_set_crc(sym, version.crc); debug("%s =3D %lx", sym->name, version.crc); =20 --=20 2.49.0.987.g0cc8ee98dc-goog From nobody Thu Dec 18 03:20:52 2025 Received: from mail-pf1-f202.google.com (mail-pf1-f202.google.com [209.85.210.202]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0F57429189B for ; Wed, 7 May 2025 23:14:16 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.210.202 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659658; cv=none; b=EvQMn4il++D9gS5UTE8+qWBO83qDUGT8N44h23e+g7W8oqft14nQgZUxPtjl7cll9HEt7AvwsOgp5fSkwsRb6LgGmQ48v8hxhXe3EZDBxsX9v94we4DWRN+1lz1PM6X8qhqV6H2PDMLUGzK/9xaRVvdM0+cySfSK5zk3HICB5z0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659658; c=relaxed/simple; bh=NtbmgkTzn8IARgcBDEgG4o5/FRCG0S2cxfpg5vDT+z4=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=fj8oHUgTF5+mByzJAXHI8XPsI+FkcGML1t63HxBfH+dqz06clIWB5Qo3BQSaFOJZGWyE0bX+n2EQYVZXXyL6Xv8sGDBtQ1Ik6Dwn4JLmrR169pBoIZrg8UtjKJ4zCHWReS0MmpKeT8qM+yChyGo+DoWM1rPJcXrPhncSRl8W2WU= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=HZ4AWLe4; arc=none smtp.client-ip=209.85.210.202 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="HZ4AWLe4" Received: by mail-pf1-f202.google.com with SMTP id d2e1a72fcca58-739764217ecso379441b3a.0 for ; Wed, 07 May 2025 16:14:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1746659656; x=1747264456; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=m7RpuWxwyysfef14AtI+lh3dKsD8m3KYFqA48Pzjpeo=; b=HZ4AWLe4WMVpDYZraWjzSdBHJEi6jG9WbGHDOsF2+LocypTB7NvcGm2cAT+QcA5xUq 3EhHZeEF/ECECzjzSZnXTs1FXaD97n5Mt4BtdXtUz+x8taszoz+7lqLyeswqYfZdsUNa MTh8z/4ue334yyK9o3sWAA3+Xcz33hwnoDADB3gOqpeEFOZUTroYzC78vs/qIAg3jggU 05alJWF5q83GIt1WSGo0UEErt0N700fbJRFOPygEmylDd7pqjUiX4vr7BYX+HHFsQiXy 50ci9QG1xvLtme7ob39X6159IBFRoGI8cHGU4dUp4ueyYPOD5Lutcku2gCt7ChU+0soP o1Lw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1746659656; x=1747264456; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=m7RpuWxwyysfef14AtI+lh3dKsD8m3KYFqA48Pzjpeo=; b=BLD4XzVTmFQM+DYLiIDSk3ybflUEbbAH09oIAZpxh7gwzA9EzMZZ0FWQnPXT1xOubL /pX5ceNwI28OnOYJcNu6Y+AnVYi8Kc4J7msxqkUaAOOy8KwheEjtacIgga5qMG4sBb6t 075pN526aAq4ATrb9Tv9ODiEmgrfE2sZCcH+szbQDSnNIfuVR7tvoA/2uY5KWt31s3i5 FTancN/cteh3W4tawyST24GGQhTPcaKD+RZ137GACRP64MnBww2aZTdf4wxT1Ww5StZe eGhfj8o43tqxfq0ueiktucBtmJJz6POQ7DsRrxAh+7PoXNgwKl2LaGej092EjF/xFGap 3trA== X-Forwarded-Encrypted: i=1; AJvYcCUnEDoujahY3Lx1L7lewrJdobqCAsnTrpesXY5j4tC3UDY1vvEZIbwec6b3BkYlwCl6rgNRl56pg1I0bLE=@vger.kernel.org X-Gm-Message-State: AOJu0YzaPekPfDnPkhmd7EDy06TSBbCSWlO7zhQry1ZRhUaDjD07vS4h 39j9jupxGu9S+YhrJ2XsIpg6q5BDWHuTO/xlfpWQvriIV8imOygVki0b7nuYX6hI5GI7Q3hPHCa fRlbyDo3mVdi4O6g5x0uQdCbCqA== X-Google-Smtp-Source: AGHT+IErf0bIdsCp80jvIgvn+0MFxfMOafuctLvyIXmHAjlWQ0hZisvPYYkFCiDDgnc6Hu7el4zHrf5zvCTzlE/10Q4= X-Received: from pfmx22.prod.google.com ([2002:a62:fb16:0:b0:740:813:f7bb]) (user=samitolvanen job=prod-delivery.src-stubby-dispatcher) by 2002:a05:6a00:1b4c:b0:732:706c:c4ff with SMTP id d2e1a72fcca58-740a94e60d7mr1497047b3a.7.1746659656344; Wed, 07 May 2025 16:14:16 -0700 (PDT) Date: Wed, 7 May 2025 23:14:08 +0000 In-Reply-To: <20250507231403.377725-7-samitolvanen@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20250507231403.377725-7-samitolvanen@google.com> X-Developer-Key: i=samitolvanen@google.com; a=openpgp; fpr=35CCFB63B283D6D3AEB783944CB5F6848BBC56EE X-Developer-Signature: v=1; a=openpgp-sha256; l=5212; i=samitolvanen@google.com; h=from:subject; bh=NtbmgkTzn8IARgcBDEgG4o5/FRCG0S2cxfpg5vDT+z4=; b=owGbwMvMwCEWxa662nLh8irG02pJDBnSL22f2qe/rvGS5Mnt3bl4/q9fUxMuOLv8fHu+868jY 4DOnG1iHaUsDGIcDLJiiiwtX1dv3f3dKfXV5yIJmDmsTCBDGLg4BWAib6oY/tmtfmzreLiHyf8h r3/AvtU73LbqNpt6KFT5TD6iOGPRcVZGhl/bs68sPXQvI0T2YPrzgMU3l1jpV/xhEwhkKVPnlqp 05gMA X-Mailer: git-send-email 2.49.0.987.g0cc8ee98dc-goog Message-ID: <20250507231403.377725-11-samitolvanen@google.com> Subject: [PATCH v3 4/5] Documentation/kbuild: Drop section numbers From: Sami Tolvanen To: Masahiro Yamada Cc: Luis Chamberlain , Petr Pavlu , Daniel Gomez , linux-modules@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, Sami Tolvanen Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Change the gendwarfksyms documentation to use proper chapter, section, and subsection adornments instead of fragile section numbers. Suggested-by: Masahiro Yamada Signed-off-by: Sami Tolvanen --- Documentation/kbuild/gendwarfksyms.rst | 44 +++++++++++++------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/= gendwarfksyms.rst index e4beaae7e456..9694ec99d190 100644 --- a/Documentation/kbuild/gendwarfksyms.rst +++ b/Documentation/kbuild/gendwarfksyms.rst @@ -2,8 +2,8 @@ DWARF module versioning =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -1. Introduction -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Introduction +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 When CONFIG_MODVERSIONS is enabled, symbol versions for modules are typically calculated from preprocessed source code using the @@ -14,8 +14,8 @@ selected, **gendwarfksyms** is used instead to calculate = symbol versions from the DWARF debugging information, which contains the necessary details about the final module ABI. =20 -1.1. Usage -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Usage +----- =20 gendwarfksyms accepts a list of object files on the command line, and a list of symbol names (one per line) in standard input:: @@ -33,8 +33,8 @@ list of symbol names (one per line) in standard input:: -h, --help Print this message =20 =20 -2. Type information availability -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D +Type information availability +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D =20 While symbols are typically exported in the same translation unit (TU) where they're defined, it's also perfectly fine for a TU to export @@ -56,8 +56,8 @@ type for calculating symbol versions even if the symbol i= s defined elsewhere. The name of the symbol pointer is expected to start with `__gendwarfksyms_ptr_`, followed by the name of the exported symbol. =20 -3. Symtypes output format -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D +Symtypes output format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 Similarly to genksyms, gendwarfksyms supports writing a symtypes file for each processed object that contain types for exported @@ -85,8 +85,8 @@ produces C-style type strings, gendwarfksyms uses the sam= e simple parsed DWARF format produced by **--dump-dies**, but with type references instead of fully expanded strings. =20 -4. Maintaining a stable kABI -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D +Maintaining a stable kABI +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D =20 Distribution maintainers often need the ability to make ABI compatible changes to kernel data structures due to LTS updates or backports. Using @@ -104,8 +104,8 @@ for source code annotation. Note that as these features= are only used to transform the inputs for symbol versioning, the user is responsible for ensuring that their changes actually won't break the ABI. =20 -4.1. kABI rules -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +kABI rules +---------- =20 kABI rules allow distributions to fine-tune certain parts of gendwarfksyms output and thus control how symbol @@ -139,8 +139,8 @@ Currently, only the rules discussed in this section are= supported, but the format is extensible enough to allow further rules to be added as need arises. =20 -4.1.1. Managing definition visibility -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Managing definition visibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 A declaration can change into a full definition when additional includes are pulled into the translation unit. This changes the versions of any @@ -168,8 +168,8 @@ Example usage:: =20 KABI_DECLONLY(s); =20 -4.1.2. Adding enumerators -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D +Adding enumerators +~~~~~~~~~~~~~~~~~~ =20 For enums, all enumerators and their values are included in calculating symbol versions, which becomes a problem if we later need to add more @@ -223,8 +223,8 @@ Example usage:: KABI_ENUMERATOR_IGNORE(e, C); KABI_ENUMERATOR_VALUE(e, LAST, 2); =20 -4.3. Adding structure members -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D +Adding structure members +------------------------ =20 Perhaps the most common ABI compatible change is adding a member to a kernel data structure. When changes to a structure are anticipated, @@ -237,8 +237,8 @@ natural method. This section describes gendwarfksyms su= pport for using reserved space in data structures and hiding members that don't change the ABI when calculating symbol versions. =20 -4.3.1. Reserving space and replacing members -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Reserving space and replacing members +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 Space is typically reserved for later use by appending integer types, or arrays, to the end of the data structure, but any type can be used. Each @@ -276,8 +276,8 @@ The examples include `KABI_(RESERVE|USE|REPLACE)*` macr= os that help simplify the process and also ensure the replacement member is correctly aligned and its size won't exceed the reserved space. =20 -4.3.2. Hiding members -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Hiding members +~~~~~~~~~~~~~~ =20 Predicting which structures will require changes during the support timeframe isn't always possible, in which case one might have to resort --=20 2.49.0.987.g0cc8ee98dc-goog From nobody Thu Dec 18 03:20:52 2025 Received: from mail-pl1-f201.google.com (mail-pl1-f201.google.com [209.85.214.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8F1EB2918CA for ; Wed, 7 May 2025 23:14:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659660; cv=none; b=ZA9AayvHqXk1JY78NT/+CqJWsK/61lvS3pDfc4/tcOHTjvmJcUfE7e14BOSPVZaH+qcMfmg0ta3sEBEmD/mFm+rRN4AZVNQ1bYHro5qC/8jWcA6uPvOi93R7VCcZUm/xnHoAZO2mWUyC9Hy6LyzqtaxsxFLW9UvPgx0QRFifHh4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1746659660; c=relaxed/simple; bh=t+KcDYFBubxRjvVzWaCC/X/nGG8YAukt+n1mnpI92hk=; h=Date:In-Reply-To:Mime-Version:References:Message-ID:Subject:From: To:Cc:Content-Type; b=S4AtyADACJR9GtgWyOe/0wt+ZclSsl9eY6PSpJED2JRdVfnBYzlDDSUWZp4M6nHgw8lmmmprj+9PG4mr6dmPASWn5tSg4Au0RFMH2weIGT/11021VtF+VENu2Mxc4iTTUJ3TfCLLRSYaH6ksp8D4tXQqohNz+JUd8Z/DP+1EZto= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b=iVWRwtEf; arc=none smtp.client-ip=209.85.214.201 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=google.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=flex--samitolvanen.bounces.google.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=google.com header.i=@google.com header.b="iVWRwtEf" Received: by mail-pl1-f201.google.com with SMTP id d9443c01a7336-22e45821fd7so3471145ad.0 for ; Wed, 07 May 2025 16:14:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20230601; t=1746659658; x=1747264458; darn=vger.kernel.org; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:from:to:cc:subject:date:message-id:reply-to; bh=efSDC5+Dl7EnH8XUtaWbMs/fjy125/V0busFxh2CY0I=; b=iVWRwtEfE+fnAijWYXXgyPbhMkMFiDLmmd1dwq0F/q7YtTcj3c35V8rsn8PkkLV3rE ZPQKXsRcE+PZ70fifGgi52WYMknwsBCEKLZAa6pcEYnixWKlhbzlVtSXHQqVxuJUMW86 rgvyqR+/wqiOoqa3i3vAuGjbDbcCoPsjByqqbe2S/VbGt5H/pT2wuPQGKkSv+Su7PcMi qtT9U03A5F+P+B2EPbhTS99y3UyOBxUbboVzFigxOcX9DmGBN1Jj9X1NkuWGh9pSZgNv 3BmjeAI2ZHq9ZIo4ARIAG41WZrGcbyIyRfEOzgO/gzsg+OtH0GA7ZUyrWhgbzKNkekeP 41wg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1746659658; x=1747264458; h=cc:to:from:subject:message-id:references:mime-version:in-reply-to :date:x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=efSDC5+Dl7EnH8XUtaWbMs/fjy125/V0busFxh2CY0I=; b=dv1RwuyEnLF2WIWNYsgoxr+N4/xJ9gefSvu4lrzZCfzNfGAhRL5bWeCfU7UDMalmba PLqkALohUcwK+vO0s/dD1galBBVFj4ncKHirPLPCRwQXTISLXpbHMzGS6hqRGdq9vS6J t+hhXsRKmR7iQ4dFGv5KYspmMlKmovARvQGOnybFD5S6IbUdsyA2zLviA20yWGKliOHy Ez4KSrO+8fMSKUW2i9YQIfnUn6/F7xh4BE3TLNQq015lQtbZJkmlzYD5jk8rI0DajG9o NfNMQ3+VtGdytdvl2E1U9lS0FEs4N0u3wVMXXRRjzKoraXv+PjP57Ge9R/4GoMdaJ/la bXfQ== X-Forwarded-Encrypted: i=1; AJvYcCX9+wa75fu0UfE/ukxWhOi0TzedSpRtYQWWmuJCYWHbLWiFCM7f+LjTf3nLebULpW2+W9fIhtGyokgni4U=@vger.kernel.org X-Gm-Message-State: AOJu0Yw9BfGZa9PuRrJOw3w4nXp+eaTu4VPglYcCiDrA3Azftu84tBbi +Y2O6F19X3EfC2jGG+Dg5B7+248ZXmic1u4Z7uqY7leYHgJDHoukv4+ZnmdvF7Dy9v9LVN9gOuA ig9q53C4QcTZ19LGHxTrn+vVBLg== X-Google-Smtp-Source: AGHT+IE3nDZyEO7hL72+sm+zsni9dWKaI13OBOvHRmL3kwKFr3USZq6KDfdsW4gRFAtr0y1Ncxjt9x2Qkeoq6ooxZAU= X-Received: from plbju1.prod.google.com ([2002:a17:903:4281:b0:220:d79f:a9bd]) (user=samitolvanen job=prod-delivery.src-stubby-dispatcher) by 2002:a17:903:f8b:b0:224:1ec0:8a1d with SMTP id d9443c01a7336-22e5ea8c623mr72791025ad.30.1746659658002; Wed, 07 May 2025 16:14:18 -0700 (PDT) Date: Wed, 7 May 2025 23:14:09 +0000 In-Reply-To: <20250507231403.377725-7-samitolvanen@google.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: Mime-Version: 1.0 References: <20250507231403.377725-7-samitolvanen@google.com> X-Developer-Key: i=samitolvanen@google.com; a=openpgp; fpr=35CCFB63B283D6D3AEB783944CB5F6848BBC56EE X-Developer-Signature: v=1; a=openpgp-sha256; l=5208; i=samitolvanen@google.com; h=from:subject; bh=t+KcDYFBubxRjvVzWaCC/X/nGG8YAukt+n1mnpI92hk=; b=owGbwMvMwCEWxa662nLh8irG02pJDBnSL+28GHUdPkxiVtcOjrqdvadx5co1WpP0n1fW3Xnmv +1JkeKLjlIWBjEOBlkxRZaWr6u37v7ulPrqc5EEzBxWJpAhDFycAjCRgwKMDJu0XV0PM6nPOfPa 4tXkBwsWTS06J77swsryw3O3nbMxrX/CyHBDx7T/WIEYO1e5zM38NKNAqR4Xd7YJxw+l/5s9ef2 vC+wA X-Mailer: git-send-email 2.49.0.987.g0cc8ee98dc-goog Message-ID: <20250507231403.377725-12-samitolvanen@google.com> Subject: [PATCH v3 5/5] Documentation/kbuild: Add new gendwarfksyms kABI rules From: Sami Tolvanen To: Masahiro Yamada Cc: Luis Chamberlain , Petr Pavlu , Daniel Gomez , linux-modules@vger.kernel.org, linux-kbuild@vger.kernel.org, linux-kernel@vger.kernel.org, Sami Tolvanen Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Document the "byte_size" and "type_string" kABI stability rules. Signed-off-by: Sami Tolvanen --- Documentation/kbuild/gendwarfksyms.rst | 97 ++++++++++++++++++++++++-- 1 file changed, 92 insertions(+), 5 deletions(-) diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/= gendwarfksyms.rst index 9694ec99d190..ed366250a54e 100644 --- a/Documentation/kbuild/gendwarfksyms.rst +++ b/Documentation/kbuild/gendwarfksyms.rst @@ -125,14 +125,17 @@ the rules. The fields are as follows: qualified name of the DWARF Debugging Information Entry (DIE). - `value`: Provides rule-specific data. =20 -The following helper macro, for example, can be used to specify rules +The following helper macros, for example, can be used to specify rules in the source code:: =20 - #define __KABI_RULE(hint, target, value) \ - static const char __PASTE(__gendwarfksyms_rule_, \ + #define ___KABI_RULE(hint, target, value) \ + static const char __PASTE(__gendwarfksyms_rule_, \ __COUNTER__)[] __used __aligned(1) \ __section(".discard.gendwarfksyms.kabi_rules") =3D \ - "1\0" #hint "\0" #target "\0" #value + "1\0" #hint "\0" target "\0" value + + #define __KABI_RULE(hint, target, value) \ + ___KABI_RULE(hint, #target, #value) =20 =20 Currently, only the rules discussed in this section are supported, but @@ -223,6 +226,87 @@ Example usage:: KABI_ENUMERATOR_IGNORE(e, C); KABI_ENUMERATOR_VALUE(e, LAST, 2); =20 +Managing structure size changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A data structure can be partially opaque to modules if its allocation is +handled by the core kernel, and modules only need to access some of its +members. In this situation, it's possible to append new members to the +structure without breaking the ABI, as long as the layout for the original +members remains unchanged. + +To append new members, we can hide them from symbol versioning as +described in section :ref:`Hiding members `, but we can't +hide the increase in structure size. The `byte_size` rule allows us to +override the structure size used for symbol versioning. + +The rule fields are expected to be as follows: + +- `type`: "byte_size" +- `target`: The fully qualified name of the target data structure + (as shown in **--dump-dies** output). +- `value`: A positive decimal number indicating the structure size + in bytes. + +Using the `__KABI_RULE` macro, this rule can be defined as:: + + #define KABI_BYTE_SIZE(fqn, value) \ + __KABI_RULE(byte_size, fqn, value) + +Example usage:: + + struct s { + /* Unchanged original members */ + unsigned long a; + void *p; + + /* Appended new members */ + KABI_IGNORE(0, unsigned long n); + }; + + KABI_BYTE_SIZE(s, 16); + +Overriding type strings +~~~~~~~~~~~~~~~~~~~~~~~ + +In rare situations where distributions must make significant changes to +otherwise opaque data structures that have inadvertently been included +in the published ABI, keeping symbol versions stable using the more +targeted kABI rules can become tedious. The `type_string` rule allows us +to override the full type string for a type or a symbol, and even add +types for versioning that no longer exist in the kernel. + +The rule fields are expected to be as follows: + +- `type`: "type_string" +- `target`: The fully qualified name of the target data structure + (as shown in **--dump-dies** output) or symbol. +- `value`: A valid type string (as shown in **--symtypes**) output) + to use instead of the real type. + +Using the `__KABI_RULE` macro, this rule can be defined as:: + + #define KABI_TYPE_STRING(type, str) \ + ___KABI_RULE("type_string", type, str) + +Example usage:: + + /* Override type for a structure */ + KABI_TYPE_STRING("s#s", + "structure_type s { " + "member base_type int byte_size(4) " + "encoding(5) n " + "data_member_location(0) " + "} byte_size(8)"); + + /* Override type for a symbol */ + KABI_TYPE_STRING("my_symbol", "variable s#s"); + +The `type_string` rule should be used only as a last resort if maintaining +a stable symbol versions cannot be reasonably achieved using other +means. Overriding a type string increases the risk of actual ABI breakages +going unnoticed as it hides all changes to the type. + Adding structure members ------------------------ =20 @@ -276,6 +360,8 @@ The examples include `KABI_(RESERVE|USE|REPLACE)*` macr= os that help simplify the process and also ensure the replacement member is correctly aligned and its size won't exceed the reserved space. =20 +.. _hiding_members: + Hiding members ~~~~~~~~~~~~~~ =20 @@ -305,4 +391,5 @@ member to a union where one of the fields has a name st= arting with unsigned long b; }; =20 -With **--stable**, both versions produce the same symbol version. +With **--stable**, both versions produce the same symbol version. The +examples include a `KABI_IGNORE` macro to simplify the code. --=20 2.49.0.987.g0cc8ee98dc-goog