Re: [lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface

[Christophe Milard]

In other words, what I don't like with your proposal, Mike, is that the
term "application" gets two meanings:
in "app", it means the program attached to the north interface.
in "api", (the "a" is for application),it means anything attached to ODP
(either north or south interface)

I dont think having different meanings for the same word is a good start
point. We have that today with "ODP" (somtimes meaning the ODP library,
sometimes meaning its north interface) and this is confusing

Christophe.

On 27 January 2016 at 08:30, Christophe Milard  wrote:

>
>
> On 26 January 2016 at 22:45, Mike Holmes  wrote:
>
>> Inline comment on include structure
>>
>> On 26 January 2016 at 13:04, Christophe Milard <
>> christophe.mil...@linaro.org> wrote:
>>
>>> This patch series implements a new structure in the ODP repo so that new
>>> interfaces can be more easily added to ODP
>>>
>>> Saddly changing the current structure seems needed as just adding to it
>>> results in a quite fuzzy file organisation:
>>>
>>> Today:
>>> include/odp/api is the reference for the ODP API interface.
>>
>> Platform/linux-generic/include/odp is the platform implementation of the
>>> ODP
>>> API interface.  The ODP API interface is simply called ODP there.
>>> Having the same name (ODP) for the whole ODP and one of its API result
>>> in a
>>> quite messy organisation.
>>> Moreover, with the current structure, a new interface cannot be named
>>> the same
>>> on the platform side as on the reference side because the directory name
>>> is
>>> what is used to distinguish the files at include time (hence the 2 names
>>> today):
>>> A new interface (e.g. defined in include/odp/drv) cannot be called
>>> Platform/linux-generic/include/odp/drv on the platform side as the
>>> statement
>>> include  would be ambiguous.
>>> And this make the driver interface appear as a sub interface of the API,
>>> which does not reflect any reality.
>>> I have tried a few variant of this, none of which gave me enough
>>> satisfaction.
>>>
>>> These patches:
>>> Aims to having a way to get following structures
>>> (for two interfaces: api and drv):
>>>
>>>
>>
>> In the repo:
>>> ./
>>> ├── include/
>>> │   └── odp/
>>> │   ├── api/  <-- this was old bad thinking, there is more than
>>> one api now,  so this is the application or app directory
>>> │   │   └── ref/  <- this is the odp/app/api, it is not a reference
>>> it is the api for apps
>>> │   ├── api.h
>>> │   ├── drv/
>>> │   │   └── ref/ <- this is the odp/drv/api, it is not a reference
>>> it is the api for drivers
>>> │   └── drv.h
>>>
>>
>> I don't mind changing api to app if that is more popular.
>
> But, regarding the ref->api change: API stands for Application Programming
> Interface. Isn't it confusing to have an Application Programming Interface
> for drivers and an Application Programming Interface for applications?
> I am not sure why you don't see these files as a reference as this is what
> the implementations should comply to, and I don't mind changing the name
> either, but I don't like API: are drivers applications?
> shouldn't be called DPI then, as this actually is the Driver programming
> interface. not the application
> But of course, we want one single common name: the reference files (or
> whatever we want to call them) should be called:
> include/odp/api/something and include/odp/drv/something. That "something"
> should be the same thing. A name telling that these files comes from the
> Interface reference/public/ definition.
> The path already says what interface we talk about (api/drv)
>
> if "ref", which make more sense for me is not popular, I think "pub" (for
> public) is a better alternative than api. Even if the references files have
> been called api up to now.
>
> Christophe.
>
>
>>
>>> └── platform/
>>> └── linux-generic/
>>> └── include/
>>> └── odp/
>>> ├── api/
>>> │   └── plat/
>>> ├── com/
>>> │   └── plat/
>>> └── drv/
>>> └── plat/
>>>
>>> Once installed:
>>> ./
>>> └── include/
>>> └── odp/
>>> ├── api/
>>> │   ├── plat/
>>> │   └── ref/
>>> ├── api.h
>>> ├── com/
>>> │   └── plat/
>>> ├── drv/
>>> │   ├── plat/
>>> │   └── ref/
>>> └── drv.h
>>>
>>> These patches do not create the drv interface: they just move around
>>> the existing structure (the ODP API includes files) according to the
>>> above
>>> trees. Patch 3 updates the docs with a view of the new structure
>>> (without the
>>> drv interface). New patches will be sent to create the new interface and
>>> update the documentation accordinally if this new structure gets
>>> approved.
>>>
>>> With this new structure, each interface can get its own directory.
>>>
>>> The com/ directory is meant to contain things which can be 

Re: [lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface

[Christophe Milard]

On 26 January 2016 at 22:45, Mike Holmes  wrote:

> Inline comment on include structure
>
> On 26 January 2016 at 13:04, Christophe Milard <
> christophe.mil...@linaro.org> wrote:
>
>> This patch series implements a new structure in the ODP repo so that new
>> interfaces can be more easily added to ODP
>>
>> Saddly changing the current structure seems needed as just adding to it
>> results in a quite fuzzy file organisation:
>>
>> Today:
>> include/odp/api is the reference for the ODP API interface.
>
> Platform/linux-generic/include/odp is the platform implementation of the
>> ODP
>> API interface.  The ODP API interface is simply called ODP there.
>> Having the same name (ODP) for the whole ODP and one of its API result in
>> a
>> quite messy organisation.
>> Moreover, with the current structure, a new interface cannot be named the
>> same
>> on the platform side as on the reference side because the directory name
>> is
>> what is used to distinguish the files at include time (hence the 2 names
>> today):
>> A new interface (e.g. defined in include/odp/drv) cannot be called
>> Platform/linux-generic/include/odp/drv on the platform side as the
>> statement
>> include  would be ambiguous.
>> And this make the driver interface appear as a sub interface of the API,
>> which does not reflect any reality.
>> I have tried a few variant of this, none of which gave me enough
>> satisfaction.
>>
>> These patches:
>> Aims to having a way to get following structures
>> (for two interfaces: api and drv):
>>
>>
>
> In the repo:
>> ./
>> ├── include/
>> │   └── odp/
>> │   ├── api/  <-- this was old bad thinking, there is more than
>> one api now,  so this is the application or app directory
>> │   │   └── ref/  <- this is the odp/app/api, it is not a reference
>> it is the api for apps
>> │   ├── api.h
>> │   ├── drv/
>> │   │   └── ref/ <- this is the odp/drv/api, it is not a reference it
>> is the api for drivers
>> │   └── drv.h
>>
>
> I don't mind changing api to app if that is more popular.

But, regarding the ref->api change: API stands for Application Programming
Interface. Isn't it confusing to have an Application Programming Interface
for drivers and an Application Programming Interface for applications?
I am not sure why you don't see these files as a reference as this is what
the implementations should comply to, and I don't mind changing the name
either, but I don't like API: are drivers applications?
shouldn't be called DPI then, as this actually is the Driver programming
interface. not the application
But of course, we want one single common name: the reference files (or
whatever we want to call them) should be called:
include/odp/api/something and include/odp/drv/something. That "something"
should be the same thing. A name telling that these files comes from the
Interface reference/public/ definition.
The path already says what interface we talk about (api/drv)

if "ref", which make more sense for me is not popular, I think "pub" (for
public) is a better alternative than api. Even if the references files have
been called api up to now.

Christophe.


>
>> └── platform/
>> └── linux-generic/
>> └── include/
>> └── odp/
>> ├── api/
>> │   └── plat/
>> ├── com/
>> │   └── plat/
>> └── drv/
>> └── plat/
>>
>> Once installed:
>> ./
>> └── include/
>> └── odp/
>> ├── api/
>> │   ├── plat/
>> │   └── ref/
>> ├── api.h
>> ├── com/
>> │   └── plat/
>> ├── drv/
>> │   ├── plat/
>> │   └── ref/
>> └── drv.h
>>
>> These patches do not create the drv interface: they just move around
>> the existing structure (the ODP API includes files) according to the above
>> trees. Patch 3 updates the docs with a view of the new structure (without
>> the
>> drv interface). New patches will be sent to create the new interface and
>> update the documentation accordinally if this new structure gets approved.
>>
>> With this new structure, each interface can get its own directory.
>>
>> The com/ directory is meant to contain things which can be shared between
>> two (or more) interfaces. It is only present in the platform side as the
>> definition of each interface is assumed to be "stand alone" (non-leaking)
>>
>> The odp//ref/ directory contains the interface platform
>> agnostic
>> definition, the reference.
>> e.g. include/odp/api/ref/ now contains what used to be located in
>> include/odp/api.
>>
>> The plat directory has the same meaning as before: it is just moved one
>> step
>> down to the interface it belongs to.
>>
>> The advantage of this new structure (compared to adding to the current
>> one)
>> is that things get more clearly defined:
>> * ODP means the whole ODP, not two things (ODP or the API interface of
>> it):
>> There is still an exception to that: the 

[lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface

[Christophe Milard]

This patch series implements a new structure in the ODP repo so that new
interfaces can be more easily added to ODP

Saddly changing the current structure seems needed as just adding to it
results in a quite fuzzy file organisation:

Today:
include/odp/api is the reference for the ODP API interface.
Platform/linux-generic/include/odp is the platform implementation of the ODP
API interface.  The ODP API interface is simply called ODP there.
Having the same name (ODP) for the whole ODP and one of its API result in a
quite messy organisation.
Moreover, with the current structure, a new interface cannot be named the same
on the platform side as on the reference side because the directory name is
what is used to distinguish the files at include time (hence the 2 names today):
A new interface (e.g. defined in include/odp/drv) cannot be called
Platform/linux-generic/include/odp/drv on the platform side as the statement
include  would be ambiguous.
And this make the driver interface appear as a sub interface of the API,
which does not reflect any reality.
I have tried a few variant of this, none of which gave me enough satisfaction.

These patches:
Aims to having a way to get following structures
(for two interfaces: api and drv):

In the repo:
./
├── include/
│   └── odp/
│   ├── api/
│   │   └── ref/
│   ├── api.h
│   ├── drv/
│   │   └── ref/
│   └── drv.h
└── platform/
└── linux-generic/
└── include/
└── odp/
├── api/
│   └── plat/
├── com/
│   └── plat/
└── drv/
└── plat/

Once installed:
./
└── include/
└── odp/
├── api/
│   ├── plat/
│   └── ref/
├── api.h
├── com/
│   └── plat/
├── drv/
│   ├── plat/
│   └── ref/
└── drv.h

These patches do not create the drv interface: they just move around
the existing structure (the ODP API includes files) according to the above
trees. Patch 3 updates the docs with a view of the new structure (without the
drv interface). New patches will be sent to create the new interface and
update the documentation accordinally if this new structure gets approved.

With this new structure, each interface can get its own directory.

The com/ directory is meant to contain things which can be shared between
two (or more) interfaces. It is only present in the platform side as the
definition of each interface is assumed to be "stand alone" (non-leaking)

The odp//ref/ directory contains the interface platform agnostic
definition, the reference.
e.g. include/odp/api/ref/ now contains what used to be located in
include/odp/api.

The plat directory has the same meaning as before: it is just moved one step
down to the interface it belongs to.

The advantage of this new structure (compared to adding to the current one)
is that things get more clearly defined:
* ODP means the whole ODP, not two things (ODP or the API interface of it):
There is still an exception to that: the prefix used by the applications is
still odp_ (and not odpapi_ as a pure logical approach would suggest. Maybe
this is acceptable... as the api remains the ODP "main" interface. If not,
that could be a separate patch). New interfaces, such as drv should surely
get a prefix as odpdrv_* in the future)
* there is some nice symetry between the repo and the installation directories.
* there is one single name per interface (api or drv in the exemple)

Compared to my first RFC, this approach separates more clearly the different
interfaces, in different directories. There will be a small price for that as
functionality common to many interfaces will have to be wrapped,
cross-references or duplicated. This may introduce complexity in each
implementation, but has no reason to leak on the interfaces definition,
as far as I can see.

Patches 1 and 2 touch quite many files, and will probably not apply
nicely. They will apply on hash 9a6e951cbbe99fddd4eb8a4f6dcc810e493f6787.
Patch 3 (doc) is "manual".

The script performing the modifications for the two first patches follows:
(maybe used for review or merging time)


#  PATCH 1:
#  platform/X/includes/odp mv to platform/X/includes/odp/api
#  includes/odp/api mv to includes/odp/api/ref

#Today's platform/X/includes/odp actually describes the API interface of ODP
#and is therefore moved to platform/X/includes/odp/api:

#the reference include/odp/api now moves to include/odp/api/ref
# - create the dir:
mkdir platform/linux-generic/include/odp/api

# - move .../odp/* to .../odp/api/* , omiting errors (api cannot be moved to 
itself)
git mv -k platform/linux-generic/include/odp/* 
platform/linux-generic/include/odp/api

# - change "include " to "include ", so that further 
sed wont affect them:
#   this is changed back to 

Re: [lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface

[Mike Holmes]

Inline comment on include structure

On 26 January 2016 at 13:04, Christophe Milard  wrote:

> This patch series implements a new structure in the ODP repo so that new
> interfaces can be more easily added to ODP
>
> Saddly changing the current structure seems needed as just adding to it
> results in a quite fuzzy file organisation:
>
> Today:
> include/odp/api is the reference for the ODP API interface.

Platform/linux-generic/include/odp is the platform implementation of the ODP
> API interface.  The ODP API interface is simply called ODP there.
> Having the same name (ODP) for the whole ODP and one of its API result in a
> quite messy organisation.
> Moreover, with the current structure, a new interface cannot be named the
> same
> on the platform side as on the reference side because the directory name is
> what is used to distinguish the files at include time (hence the 2 names
> today):
> A new interface (e.g. defined in include/odp/drv) cannot be called
> Platform/linux-generic/include/odp/drv on the platform side as the
> statement
> include  would be ambiguous.
> And this make the driver interface appear as a sub interface of the API,
> which does not reflect any reality.
> I have tried a few variant of this, none of which gave me enough
> satisfaction.
>
> These patches:
> Aims to having a way to get following structures
> (for two interfaces: api and drv):
>
>

In the repo:
> ./
> ├── include/
> │   └── odp/
> │   ├── api/  <-- this was old bad thinking, there is more than
> one api now,  so this is the application or app directory
> │   │   └── ref/  <- this is the odp/app/api, it is not a reference it
> is the api for apps
> │   ├── api.h
> │   ├── drv/
> │   │   └── ref/ <- this is the odp/drv/api, it is not a reference it
> is the api for drivers
> │   └── drv.h
>



> └── platform/
> └── linux-generic/
> └── include/
> └── odp/
> ├── api/
> │   └── plat/
> ├── com/
> │   └── plat/
> └── drv/
> └── plat/
>
> Once installed:
> ./
> └── include/
> └── odp/
> ├── api/
> │   ├── plat/
> │   └── ref/
> ├── api.h
> ├── com/
> │   └── plat/
> ├── drv/
> │   ├── plat/
> │   └── ref/
> └── drv.h
>
> These patches do not create the drv interface: they just move around
> the existing structure (the ODP API includes files) according to the above
> trees. Patch 3 updates the docs with a view of the new structure (without
> the
> drv interface). New patches will be sent to create the new interface and
> update the documentation accordinally if this new structure gets approved.
>
> With this new structure, each interface can get its own directory.
>
> The com/ directory is meant to contain things which can be shared between
> two (or more) interfaces. It is only present in the platform side as the
> definition of each interface is assumed to be "stand alone" (non-leaking)
>
> The odp//ref/ directory contains the interface platform agnostic
> definition, the reference.
> e.g. include/odp/api/ref/ now contains what used to be located in
> include/odp/api.
>
> The plat directory has the same meaning as before: it is just moved one
> step
> down to the interface it belongs to.
>
> The advantage of this new structure (compared to adding to the current one)
> is that things get more clearly defined:
> * ODP means the whole ODP, not two things (ODP or the API interface of it):
> There is still an exception to that: the prefix used by the applications is
> still odp_ (and not odpapi_ as a pure logical approach would suggest. Maybe
> this is acceptable... as the api remains the ODP "main" interface. If not,
> that could be a separate patch). New interfaces, such as drv should surely
> get a prefix as odpdrv_* in the future)
> * there is some nice symetry between the repo and the installation
> directories.
> * there is one single name per interface (api or drv in the exemple)
>
> Compared to my first RFC, this approach separates more clearly the
> different
> interfaces, in different directories. There will be a small price for that
> as
> functionality common to many interfaces will have to be wrapped,
> cross-references or duplicated. This may introduce complexity in each
> implementation, but has no reason to leak on the interfaces definition,
> as far as I can see.
>
> Patches 1 and 2 touch quite many files, and will probably not apply
> nicely. They will apply on hash 9a6e951cbbe99fddd4eb8a4f6dcc810e493f6787.
> Patch 3 (doc) is "manual".
>
> The script performing the modifications for the two first patches follows:
> (maybe used for review or merging time)
>
> 
> #  PATCH 1:
> #  platform/X/includes/odp mv to platform/X/includes/odp/api
> #  includes/odp/api mv to