__function API

__function API

[Hollis Blanchard]

[resending to the still-active list]

I have a question about function naming conventions in headers. I've been 
assuming that the __ prefix means "internal", i.e. not really part of the 
exported API of a header. But I see code like this in 
include/asm-x86/shadow.h:

#define __translate_gpfn_to_mfn(_d, gpfn)              \
    ( (shadow_mode_translate(_d))                      \
      ? translate_gpfn_to_mfn(_d, gpfn)                \
      : (gpfn) )

static inline unsigned long
translate_gpfn_to_mfn(struct domain *rd, unsigned long gpfn)
{
 ...
}

In this case, __translate_gpfn_to_mfn() is the *only* thing called by common 
code. translate_gpfn_to_mfn() is not.

Another example is _domain in asm-x86/mm.h: it's used in common/page_alloc.c.

As I implement the arch->common API, I've been skipping the __functions, but 
it seems many of them are in fact part of that API (while many others are 
not). In general is it ok for common code to call __functions provided by 
architecture headers, or should that be considered a bug?

-- 
Hollis Blanchard
IBM Linux Technology Center


-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click

Re: __function API

[Anthony Liguori]

Hollis Blanchard wrote:

>[resending to the still-active list]
>
>I have a question about function naming conventions in headers. I've been 
>assuming that the __ prefix means "internal", i.e. not really part of the 
>exported API of a header. But I see code like this in 
>include/asm-x86/shadow.h:
>  
>
Technically, no identifiers should ever begin with a '__' prefix.  This 
prefix is reserved for any use by the C standard (section 7.1.3) and is 
commonly used to generate temporaries by compilers.

Xen does use '__' frequently as a prefix.  I'm not sure it's worth 
removing.  It's probably best to avoid doing this in new code though.

Regards,
Anthony Liguori


-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click

RE: __function API

[Ian Pratt]

> >I have a question about function naming conventions in 
> headers. I've been 
> >assuming that the __ prefix means "internal", i.e. not 
> really part of the 
> >exported API of a header. But I see code like this in 
> >include/asm-x86/shadow.h:

I'd certainly regard that particular example of __foo() calling foo() as
worth fixing. This code is undergoing massive change at the moment
anyhow, so we'll handle the patch.  
  
> Technically, no identifiers should ever begin with a '__' 
> prefix.  This 
> prefix is reserved for any use by the C standard (section 
> 7.1.3) and is 
> commonly used to generate temporaries by compilers.
> 
> Xen does use '__' frequently as a prefix.  I'm not sure it's worth 
> removing.  It's probably best to avoid doing this in new code though.

I guess we should change these to a single _ , but its not critical
path.

Ian


-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_ide95&alloc_id\x14396&op=click