Object-like macros are different than function-like macros:
https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html
They are not parsed correctly, generating invalid intermediate
files (xmls) for cases like:
#define BIT_MASK (0xFF << BIT_SHIFT)
where "OxFF <<" is considered to be parameter type.
When parsing, we can differentiate beween these two types of macros by
checking whether there is at least one whitespace b/w "#define" and
first opening paranthesis.
Signed-off-by: Horia Geanta <[email protected]>
---
scripts/kernel-doc | 15 ++++++++++++---
1 file changed, 12 insertions(+), 3 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index da058da413e7..ffd35c9d616a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2073,6 +2073,7 @@ sub check_return_section {
sub dump_function($$) {
my $prototype = shift;
my $file = shift;
+ my $noret = 0;
$prototype =~ s/^static +//;
$prototype =~ s/^extern +//;
@@ -2086,7 +2087,7 @@ sub dump_function($$) {
$prototype =~ s/__init_or_module +//;
$prototype =~ s/__must_check +//;
$prototype =~ s/__weak +//;
- $prototype =~ s/^#\s*define\s+//; #ak added
+ my $define = $prototype =~ s/^#\s*define\s+//; #ak added
$prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
# Yes, this truly is vile. We are looking for:
@@ -2105,7 +2106,15 @@ sub dump_function($$) {
# - atomic_set (macro)
# - pci_match_device, __copy_to_user (long return type)
- if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
+ # This is an object-like macro, it has no return type and no parameter
+ # list.
+ # Function-like macros are not allowed to have spaces between
+ # declaration_name and opening paranthesis (notice the \s+).
+ $return_type = $1;
+ $declaration_name = $2;
+ $noret = 1;
+ } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
@@ -2140,7 +2149,7 @@ sub dump_function($$) {
# of warnings goes sufficiently down, the check is only performed in
# verbose mode.
# TODO: always perform the check.
- if ($verbose) {
+ if ($verbose && !$noret) {
check_return_section($file, $declaration_name, $return_type);
}
--
1.8.3.1
On 06/23/14 05:15, Horia Geanta wrote:
> Object-like macros are different than function-like macros:
> https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
> https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html
>
> They are not parsed correctly, generating invalid intermediate
> files (xmls) for cases like:
> #define BIT_MASK (0xFF << BIT_SHIFT)
> where "OxFF <<" is considered to be parameter type.
>
> When parsing, we can differentiate beween these two types of macros by
> checking whether there is at least one whitespace b/w "#define" and
> first opening paranthesis.
parenthesis.
Where did you see a problem? I tested the patch and all of the
Documentation/DocBook/*.xml files are the same without or with the patch.
>
> Signed-off-by: Horia Geanta <[email protected]>
> ---
> scripts/kernel-doc | 15 ++++++++++++---
> 1 file changed, 12 insertions(+), 3 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index da058da413e7..ffd35c9d616a 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -2073,6 +2073,7 @@ sub check_return_section {
> sub dump_function($$) {
> my $prototype = shift;
> my $file = shift;
> + my $noret = 0;
>
> $prototype =~ s/^static +//;
> $prototype =~ s/^extern +//;
> @@ -2086,7 +2087,7 @@ sub dump_function($$) {
> $prototype =~ s/__init_or_module +//;
> $prototype =~ s/__must_check +//;
> $prototype =~ s/__weak +//;
> - $prototype =~ s/^#\s*define\s+//; #ak added
> + my $define = $prototype =~ s/^#\s*define\s+//; #ak added
> $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
>
> # Yes, this truly is vile. We are looking for:
> @@ -2105,7 +2106,15 @@ sub dump_function($$) {
> # - atomic_set (macro)
> # - pci_match_device, __copy_to_user (long return type)
>
> - if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> + if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
> + # This is an object-like macro, it has no return type and no parameter
> + # list.
> + # Function-like macros are not allowed to have spaces between
> + # declaration_name and opening paranthesis (notice the \s+).
> + $return_type = $1;
> + $declaration_name = $2;
> + $noret = 1;
> + } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
> @@ -2140,7 +2149,7 @@ sub dump_function($$) {
> # of warnings goes sufficiently down, the check is only performed in
> # verbose mode.
> # TODO: always perform the check.
> - if ($verbose) {
> + if ($verbose && !$noret) {
> check_return_section($file, $declaration_name, $return_type);
> }
>
>
--
~Randy
On 6/29/2014 5:52 AM, Randy Dunlap wrote:
> On 06/23/14 05:15, Horia Geanta wrote:
>> Object-like macros are different than function-like macros:
>> https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
>> https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html
>>
>> They are not parsed correctly, generating invalid intermediate
>> files (xmls) for cases like:
>> #define BIT_MASK (0xFF << BIT_SHIFT)
>> where "OxFF <<" is considered to be parameter type.
>>
>> When parsing, we can differentiate beween these two types of macros by
between.
>> checking whether there is at least one whitespace b/w "#define" and
>> first opening paranthesis.
>
> parenthesis.
Thanks, I'll fix both typos in v2.
>
> Where did you see a problem? I tested the patch and all of the
> Documentation/DocBook/*.xml files are the same without or with the patch.
>
Indeed, right now there is no kernel-doc for "object-like" macros in
Docbook.
I am preparing documentation for not-yet-upstreamed code in
drivers/crypto/caam and I thought it would be useful to use kernel-doc
for some of the #defines.
Doc would look like this (no @param list, no "Return" section, only a
description):
/**
* DEFAULT_SEC_ERA - the default value for the SEC era in case the user
* provides an unsupported value.
*/
#define DEFAULT_SEC_ERA 6
Regards,
Horia
On 06/30/14 06:51, Horia Geantă wrote:
> On 6/29/2014 5:52 AM, Randy Dunlap wrote:
>> On 06/23/14 05:15, Horia Geanta wrote:
>>> Object-like macros are different than function-like macros:
>>> https://gcc.gnu.org/onlinedocs/cpp/Object-like-Macros.html
>>> https://gcc.gnu.org/onlinedocs/cpp/Function-like-Macros.html
>>>
>>> They are not parsed correctly, generating invalid intermediate
>>> files (xmls) for cases like:
>>> #define BIT_MASK (0xFF << BIT_SHIFT)
>>> where "OxFF <<" is considered to be parameter type.
>>>
>>> When parsing, we can differentiate beween these two types of macros by
>
> between.
>
>>> checking whether there is at least one whitespace b/w "#define" and
>>> first opening paranthesis.
>>
>> parenthesis.
>
> Thanks, I'll fix both typos in v2.
>
>>
>> Where did you see a problem? I tested the patch and all of the
>> Documentation/DocBook/*.xml files are the same without or with the patch.
>>
>
> Indeed, right now there is no kernel-doc for "object-like" macros in Docbook.
>
> I am preparing documentation for not-yet-upstreamed code in drivers/crypto/caam and I thought it would be useful to use kernel-doc for some of the #defines.
OK, thanks for the explanation. I am applying your patch.
> Doc would look like this (no @param list, no "Return" section, only a description):
>
> /**
> * DEFAULT_SEC_ERA - the default value for the SEC era in case the user
> * provides an unsupported value.
> */
> #define DEFAULT_SEC_ERA 6
--
~Randy