[lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface
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 what
Re: [lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface
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 includes/odp/api/ref > #
Re: [lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface
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 prefix used by the applic
Re: [lng-odp] [API-NEXT RFC PATCH 0/3] new try for a adding a driver interface
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 shared between >>> two (or more) interfaces. It is only