[Xenomai] doc for xeno-config skins

[Xenomai] doc for xeno-config skins

[Giulio Moro]

What is the difference between the Posix and Cobalt skin, as far as xeno-config is concerned??

Difference between
  xeno-config --skin posix --cflags
  xeno-config --skin cobalt --cflags
is that the former declares -D__COBALT_WRAP__ (which in turn adds fwd declarations for clock_nanosleep() and pthread_setname_np() in boilerplate/libc.h).

difference between 
  xeno-config --skin posix --ldflags
  xeno-config --skin cobalt --ldflags
is that the former adds `-Wl,@/usr/xenomai/lib/cobalt.wrappers`

So it seems to me that `--skin posix` expects you to call, e.g.: pthread_create(), while `--skin cobalt` expects you to call, e.g.: __wrap_pthread_create()

Is this correct?
Is that it?
What are the intended uses?
I don't think this is documented anywhere? Where would be the best place to have this written down? Perhaps the --help of xeno-config? Also, while we are at it, --skin alchemy vs --skin native and the effect of --compat could use some description.

Best,
Giulio

Re: [Xenomai] doc for xeno-config skins

[Philippe Gerum]

On 04/04/2018 10:15 PM, Giulio Moro wrote:
> What is the difference between the Posix and Cobalt skin, as far as xeno-config is concerned??
> 
> Difference between
>   xeno-config --skin posix --cflags
>   xeno-config --skin cobalt --cflags
> is that the former declares -D__COBALT_WRAP__ (which in turn adds fwd declarations for clock_nanosleep() and pthread_setname_np() in boilerplate/libc.h).
> 
> difference between 
>   xeno-config --skin posix --ldflags
>   xeno-config --skin cobalt --ldflags
> is that the former adds `-Wl,@/usr/xenomai/lib/cobalt.wrappers`
> 
> So it seems to me that `--skin posix` expects you to call, e.g.: pthread_create(), while `--skin cobalt` expects you to call, e.g.: __wrap_pthread_create()
> 
> Is this correct?
> Is that it?
> What are the intended uses?
> I don't think this is documented anywhere? Where would be the best place to have this written down? Perhaps the --help of xeno-config? Also, while we are at it, --skin alchemy vs --skin native and the effect of --compat could use some description.
> 

http://www.xenomai.org/documentation/xenomai-3/html/man1/xeno-config/index.html



-- 
Philippe.

Re: [Xenomai] doc for xeno-config skins

[Giulio Moro]

Thanks and sorry for overlooking that. I thought if there was some docs on xeno-config it would have been inlined in its source, so that is where I looked for it. I guess the man folder should have been a more obvious choice.

Is it correct that calling `xeno-config --skin cobalt` expects you to call, POSIX functions prefixed with `__wrap_` ? Does this mean that the *actual* "Cobalt POSIX interface" consists of __wrap_fn() calls as opposed to fn() calls?
If yes,  is this documented somewhere obvious? I kind of figured this out over time by reading http://xenomai.org/2014/08/porting-a-linux-application-to-xenomai-dual-kernel/  and looking at the wrappers files and at the source code, but is it stated clearly somewhere? 
This is a place where I would have looked for that, for instance: http://www.xenomai.org/documentation/xenomai-3/html/xeno3prm/group__cobalt__api.html .

(incidentally, these two images (referenced by the xeno-config man page) are missing
http://www.xenomai.org/documentation/xenomai-3/html/man1/asciidoc-icons/note.png
http://www.xenomai.org/documentation/xenomai-3/html/man1/asciidoc-icons/caution.png
)

Thanks,
Giulio
________________________________________
From: Philippe Gerum <rpm@xenomai.org>
Sent: 05 April 2018 07:36
To: Giulio Moro; xenomai@xenomai.org
Subject: Re: [Xenomai] doc for xeno-config skins

On 04/04/2018 10:15 PM, Giulio Moro wrote:
> What is the difference between the Posix and Cobalt skin, as far as xeno-config is concerned??
>
> Difference between
>   xeno-config --skin posix --cflags
>   xeno-config --skin cobalt --cflags
> is that the former declares -D__COBALT_WRAP__ (which in turn adds fwd declarations for clock_nanosleep() and pthread_setname_np() in boilerplate/libc.h).
>
> difference between
>   xeno-config --skin posix --ldflags
>   xeno-config --skin cobalt --ldflags
> is that the former adds `-Wl,@/usr/xenomai/lib/cobalt.wrappers`
>
> So it seems to me that `--skin posix` expects you to call, e.g.: pthread_create(), while `--skin cobalt` expects you to call, e.g.: __wrap_pthread_create()
>
> Is this correct?
> Is that it?
> What are the intended uses?
> I don't think this is documented anywhere? Where would be the best place to have this written down? Perhaps the --help of xeno-config? Also, while we are at it, --skin alchemy vs --skin native and the effect of --compat could use some description.
>

http://www.xenomai.org/documentation/xenomai-3/html/man1/xeno-config/index.html



--
Philippe.

Re: [Xenomai] doc for xeno-config skins

[Philippe Gerum]

On 04/05/2018 01:39 PM, Giulio Moro wrote:
> Thanks and sorry for overlooking that. I thought if there was some docs on xeno-config it would have been inlined in its source, so that is where I looked for it. I guess the man folder should have been a more obvious choice.
> 
> Is it correct that calling `xeno-config --skin cobalt` expects you to call, POSIX functions prefixed with `__wrap_` ? Does this mean that the *actual* "Cobalt POSIX interface" consists of __wrap_fn() calls as opposed to fn() calls?

__RT(fn()) and __COBALT(fn()) hide this ugly __wrap prefix inside an
ugly macro. __STD() keeps consistent with such ugliness for __real calls.

> If yes,  is this documented somewhere obvious?
 I kind of figured this out over time by reading
http://xenomai.org/2014/08/porting-a-linux-application-to-xenomai-dual-kernel/
 and looking at the wrappers files and at the source code, but is it
stated clearly somewhere?

Of course not. Proper documentation hinders fruitful imagination.

> This is a place where I would have looked for that, for instance: http://www.xenomai.org/documentation/xenomai-3/html/xeno3prm/group__cobalt__api.html .
> 

Makes sense, added to my todo list. This is part of a larger
documentation work.

> (incidentally, these two images (referenced by the xeno-config man page) are missing
> http://www.xenomai.org/documentation/xenomai-3/html/man1/asciidoc-icons/note.png
> http://www.xenomai.org/documentation/xenomai-3/html/man1/asciidoc-icons/caution.png
> )
>

Ok, thanks.

-- 
Philippe.

Re: [Xenomai] doc for xeno-config skins

[Philippe Gerum]

On 04/05/2018 03:25 PM, Philippe Gerum wrote:
> On 04/05/2018 01:39 PM, Giulio Moro wrote:
>> Thanks and sorry for overlooking that. I thought if there was some docs on xeno-config it would have been inlined in its source, so that is where I looked for it. I guess the man folder should have been a more obvious choice.
>>
>> Is it correct that calling `xeno-config --skin cobalt` expects you to call, POSIX functions prefixed with `__wrap_` ? Does this mean that the *actual* "Cobalt POSIX interface" consists of __wrap_fn() calls as opposed to fn() calls?
> 
> __RT(fn()) and __COBALT(fn()) hide this ugly __wrap prefix inside an
> ugly macro. __STD() keeps consistent with such ugliness for __real calls.
> 
>> If yes,  is this documented somewhere obvious?
>  I kind of figured this out over time by reading
> http://xenomai.org/2014/08/porting-a-linux-application-to-xenomai-dual-kernel/
>  and looking at the wrappers files and at the source code, but is it
> stated clearly somewhere?
> 
> Of course not. Proper documentation hinders fruitful imagination.
> 
>> This is a place where I would have looked for that, for instance: http://www.xenomai.org/documentation/xenomai-3/html/xeno3prm/group__cobalt__api.html .
>>
> 
> Makes sense, added to my todo list. This is part of a larger
> documentation work.
> 

This commit is an attempt to clarify the matter of symbol wrapping:

http://git.xenomai.org/xenomai-3.git/commit/?id=e28d2631154d26e00715a5ef0f952ceb5df7ef59

-- 
Philippe.