| Message ID | 1461794375-15214-2-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | New |
| Headers | show |
Part 1 applies OK, but Part 2 needs a rebase: bill@Ubuntu15:~/linaro/mikedoc2$ git am --reject ~/Mail/Incoming/Mike/2 Applying: doc: reference odp_pktio_open and don't copy it Checking patch doc/users-guide/users-guide-pktio.adoc... Checking patch include/odp/api/spec/packet_io.h... error: while searching for: odp_pktio_set_op_t set_op; } odp_pktio_capability_t; /** * Open a packet IO interface * error: patch failed: include/odp/api/spec/packet_io.h:244 Hunk #2 succeeded at 474 (offset 173 lines). Applied patch doc/users-guide/users-guide-pktio.adoc cleanly. Applying patch include/odp/api/spec/packet_io.h with 1 reject... Rejected hunk #1. Hunk #2 applied cleanly. Patch failed at 0001 doc: reference odp_pktio_open and don't copy it The copy of the patch that failed is found in: /home/bill/linaro/mikedoc2/.git/rebase-apply/patch When you have resolved this problem, run "git am --continue". On Wed, Apr 27, 2016 at 4:59 PM, Mike Holmes <mike.holmes@linaro.org> wrote: > this patch shows how to reference the doxygen api specification and not > cut and paste it into the asciidoc source. > > it does this for just the odp_pktio_open api > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > doc/users-guide/users-guide-pktio.adoc | 57 > +--------------------------------- > include/odp/api/spec/packet_io.h | 2 ++ > 2 files changed, 3 insertions(+), 56 deletions(-) > > diff --git a/doc/users-guide/users-guide-pktio.adoc > b/doc/users-guide/users-guide-pktio.adoc > index 2dd0b15..bfd588d 100644 > --- a/doc/users-guide/users-guide-pktio.adoc > +++ b/doc/users-guide/users-guide-pktio.adoc > @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to return > the PktIO to the > PktIO objects begin life by being _opened_ via the call: > [source,c] > ----- > -/** > - * Open a packet IO interface > - * > - * An ODP program can open a single packet IO interface per device, > attempts > - * to open an already open device will fail, returning ODP_PKTIO_INVALID > with > - * errno set. Use odp_pktio_lookup() to obtain a handle to an already open > - * device. Packet IO parameters provide interface level configuration > options. > - * > - * Packet input queue configuration must be setup with > - * odp_pktin_queue_config() before odp_pktio_start() is called. When > packet > - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() call is > - * optional and will ignore all parameters. > - * > - * Packet output queue configuration must be setup with > - * odp_pktout_queue_config() before odp_pktio_start() is called. When > packet > - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, > - * odp_pktout_queue_config() call is optional and will ignore all > parameters. > - * > - * Packet receive and transmit on the interface is enabled with a call to > - * odp_pktio_start(). If not specified otherwise, any interface level > - * configuration must not be changed when the interface is active > (between start > - * and stop calls). > - * > - * In summary, a typical pktio interface setup sequence is ... > - * * odp_pktio_open() > - * * odp_pktin_queue_config() > - * * odp_pktout_queue_config() > - * * odp_pktio_start() > - * > - * ... and tear down sequence is: > - * * odp_pktio_stop() > - * * odp_pktio_close() > - * > - * @param name Packet IO device name > - * @param pool Default pool from which to allocate storage for packets > - * received over this interface, must be of type > ODP_POOL_PACKET > - * @param param Packet IO parameters > - * > - * @return Packet IO handle > - * @retval ODP_PKTIO_INVALID on failure > - * > - * @note The device name "loop" is a reserved name for a loopback device > used > - * for testing purposes. > - * > - * @note Packets arriving via this interface assigned to a CoS by the > - * classifier are received into the pool associated with that CoS. > This > - * will occur either because this pktio is assigned a default CoS via > - * the odp_pktio_default_cos_set() routine, or because a matching PMR > - * assigned the packet to a specific CoS. The default pool specified > - * here is applicable only for those packets that are not assigned > to a > - * more specific CoS. > - * > - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() > - */ > -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, > - const odp_pktio_param_t *param); > +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] > ----- > +odp_pktio_open()+ takes three arguments: a *name*, which is an > implementation-defined string that identifies the logical interface to be > diff --git a/include/odp/api/spec/packet_io.h > b/include/odp/api/spec/packet_io.h > index 7dd10cd..c3945f0 100644 > --- a/include/odp/api/spec/packet_io.h > +++ b/include/odp/api/spec/packet_io.h > @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { > odp_pktio_set_op_t set_op; > } odp_pktio_capability_t; > > +// Asciidoc tag::odp_pktio_open[] > /** > * Open a packet IO interface > * > @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { > */ > odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, > const odp_pktio_param_t *param); > +// Asciidoc end::odp_pktio_open[] > > /** > * Query packet IO interface capabilities > -- > 2.7.4 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
On Thu, Apr 28, 2016 at 9:58 AM, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Part 1 applies OK, but Part 2 needs a rebase: > > bill@Ubuntu15:~/linaro/mikedoc2$ git am --reject ~/Mail/Incoming/Mike/2 > Applying: doc: reference odp_pktio_open and don't copy it > Checking patch doc/users-guide/users-guide-pktio.adoc... > Checking patch include/odp/api/spec/packet_io.h... > error: while searching for: > odp_pktio_set_op_t set_op; > } odp_pktio_capability_t; > > /** > * Open a packet IO interface > * > > error: patch failed: include/odp/api/spec/packet_io.h:244 > Hunk #2 succeeded at 474 (offset 173 lines). > Applied patch doc/users-guide/users-guide-pktio.adoc cleanly. > Applying patch include/odp/api/spec/packet_io.h with 1 reject... > Rejected hunk #1. > Hunk #2 applied cleanly. > Patch failed at 0001 doc: reference odp_pktio_open and don't copy it > The copy of the patch that failed is found in: > /home/bill/linaro/mikedoc2/.git/rebase-apply/patch > When you have resolved this problem, run "git am --continue". > > > On Wed, Apr 27, 2016 at 4:59 PM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> this patch shows how to reference the doxygen api specification and not >> cut and paste it into the asciidoc source. >> >> it does this for just the odp_pktio_open api >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> doc/users-guide/users-guide-pktio.adoc | 57 >> +--------------------------------- >> include/odp/api/spec/packet_io.h | 2 ++ >> 2 files changed, 3 insertions(+), 56 deletions(-) >> >> diff --git a/doc/users-guide/users-guide-pktio.adoc >> b/doc/users-guide/users-guide-pktio.adoc >> index 2dd0b15..bfd588d 100644 >> --- a/doc/users-guide/users-guide-pktio.adoc >> +++ b/doc/users-guide/users-guide-pktio.adoc >> @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to return >> the PktIO to the >> PktIO objects begin life by being _opened_ via the call: >> [source,c] >> ----- >> -/** >> - * Open a packet IO interface >> - * >> - * An ODP program can open a single packet IO interface per device, >> attempts >> - * to open an already open device will fail, returning ODP_PKTIO_INVALID >> with >> - * errno set. Use odp_pktio_lookup() to obtain a handle to an already >> open >> - * device. Packet IO parameters provide interface level configuration >> options. >> - * >> - * Packet input queue configuration must be setup with >> - * odp_pktin_queue_config() before odp_pktio_start() is called. When >> packet >> - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() call >> is >> - * optional and will ignore all parameters. >> - * >> - * Packet output queue configuration must be setup with >> - * odp_pktout_queue_config() before odp_pktio_start() is called. When >> packet >> - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, >> - * odp_pktout_queue_config() call is optional and will ignore all >> parameters. >> - * >> - * Packet receive and transmit on the interface is enabled with a call to >> - * odp_pktio_start(). If not specified otherwise, any interface level >> - * configuration must not be changed when the interface is active >> (between start >> - * and stop calls). >> - * >> - * In summary, a typical pktio interface setup sequence is ... >> - * * odp_pktio_open() >> - * * odp_pktin_queue_config() >> - * * odp_pktout_queue_config() >> - * * odp_pktio_start() >> - * >> - * ... and tear down sequence is: >> - * * odp_pktio_stop() >> - * * odp_pktio_close() >> - * >> - * @param name Packet IO device name >> - * @param pool Default pool from which to allocate storage for packets >> - * received over this interface, must be of type >> ODP_POOL_PACKET >> - * @param param Packet IO parameters >> - * >> - * @return Packet IO handle >> - * @retval ODP_PKTIO_INVALID on failure >> - * >> - * @note The device name "loop" is a reserved name for a loopback device >> used >> - * for testing purposes. >> - * >> - * @note Packets arriving via this interface assigned to a CoS by the >> - * classifier are received into the pool associated with that CoS. >> This >> - * will occur either because this pktio is assigned a default CoS >> via >> - * the odp_pktio_default_cos_set() routine, or because a matching >> PMR >> - * assigned the packet to a specific CoS. The default pool specified >> - * here is applicable only for those packets that are not assigned >> to a >> - * more specific CoS. >> - * >> - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() >> - */ >> -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >> - const odp_pktio_param_t *param); >> +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] >> ----- >> +odp_pktio_open()+ takes three arguments: a *name*, which is an >> implementation-defined string that identifies the logical interface to be >> diff --git a/include/odp/api/spec/packet_io.h >> b/include/odp/api/spec/packet_io.h >> index 7dd10cd..c3945f0 100644 >> --- a/include/odp/api/spec/packet_io.h >> +++ b/include/odp/api/spec/packet_io.h >> @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { >> odp_pktio_set_op_t set_op; >> } odp_pktio_capability_t; >> >> +// Asciidoc tag::odp_pktio_open[] >> > Aside from the rebase issue, isn't this going to cause checkpatch issues since we prohibit C++ style comments in C source files? Can Asciidoc use standard C comments? > /** >> * Open a packet IO interface >> * >> @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { >> */ >> odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >> const odp_pktio_param_t *param); >> +// Asciidoc end::odp_pktio_open[] >> >> /** >> * Query packet IO interface capabilities >> -- >> 2.7.4 >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> > >
Patch 2 can be dropped, it was as much an example as anything. If checkpatch complains it can be ignored, this is in an asciidoc file, it is not code, but no ascidoctor does not like /* */ that is why I had to change them - http://asciidoctor.org/docs/user-manual/ Here are the line comments that are supported: ---- line of code // <1> line of code # <2> line of code ;; <3> ---- <1> A callout behind a line comment for C-style languages. <2> A callout behind a line comment for Ruby, Python, Perl, etc. <3> A callout behind a line comment for Clojure. On 28 April 2016 at 11:01, Bill Fischofer <bill.fischofer@linaro.org> wrote: > > > On Thu, Apr 28, 2016 at 9:58 AM, Bill Fischofer <bill.fischofer@linaro.org > > wrote: > >> Part 1 applies OK, but Part 2 needs a rebase: >> >> bill@Ubuntu15:~/linaro/mikedoc2$ git am --reject ~/Mail/Incoming/Mike/2 >> Applying: doc: reference odp_pktio_open and don't copy it >> Checking patch doc/users-guide/users-guide-pktio.adoc... >> Checking patch include/odp/api/spec/packet_io.h... >> error: while searching for: >> odp_pktio_set_op_t set_op; >> } odp_pktio_capability_t; >> >> /** >> * Open a packet IO interface >> * >> >> error: patch failed: include/odp/api/spec/packet_io.h:244 >> Hunk #2 succeeded at 474 (offset 173 lines). >> Applied patch doc/users-guide/users-guide-pktio.adoc cleanly. >> Applying patch include/odp/api/spec/packet_io.h with 1 reject... >> Rejected hunk #1. >> Hunk #2 applied cleanly. >> Patch failed at 0001 doc: reference odp_pktio_open and don't copy it >> The copy of the patch that failed is found in: >> /home/bill/linaro/mikedoc2/.git/rebase-apply/patch >> When you have resolved this problem, run "git am --continue". >> >> >> On Wed, Apr 27, 2016 at 4:59 PM, Mike Holmes <mike.holmes@linaro.org> >> wrote: >> >>> this patch shows how to reference the doxygen api specification and not >>> cut and paste it into the asciidoc source. >>> >>> it does this for just the odp_pktio_open api >>> >>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >>> --- >>> doc/users-guide/users-guide-pktio.adoc | 57 >>> +--------------------------------- >>> include/odp/api/spec/packet_io.h | 2 ++ >>> 2 files changed, 3 insertions(+), 56 deletions(-) >>> >>> diff --git a/doc/users-guide/users-guide-pktio.adoc >>> b/doc/users-guide/users-guide-pktio.adoc >>> index 2dd0b15..bfd588d 100644 >>> --- a/doc/users-guide/users-guide-pktio.adoc >>> +++ b/doc/users-guide/users-guide-pktio.adoc >>> @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to return >>> the PktIO to the >>> PktIO objects begin life by being _opened_ via the call: >>> [source,c] >>> ----- >>> -/** >>> - * Open a packet IO interface >>> - * >>> - * An ODP program can open a single packet IO interface per device, >>> attempts >>> - * to open an already open device will fail, returning >>> ODP_PKTIO_INVALID with >>> - * errno set. Use odp_pktio_lookup() to obtain a handle to an already >>> open >>> - * device. Packet IO parameters provide interface level configuration >>> options. >>> - * >>> - * Packet input queue configuration must be setup with >>> - * odp_pktin_queue_config() before odp_pktio_start() is called. When >>> packet >>> - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() call >>> is >>> - * optional and will ignore all parameters. >>> - * >>> - * Packet output queue configuration must be setup with >>> - * odp_pktout_queue_config() before odp_pktio_start() is called. When >>> packet >>> - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, >>> - * odp_pktout_queue_config() call is optional and will ignore all >>> parameters. >>> - * >>> - * Packet receive and transmit on the interface is enabled with a call >>> to >>> - * odp_pktio_start(). If not specified otherwise, any interface level >>> - * configuration must not be changed when the interface is active >>> (between start >>> - * and stop calls). >>> - * >>> - * In summary, a typical pktio interface setup sequence is ... >>> - * * odp_pktio_open() >>> - * * odp_pktin_queue_config() >>> - * * odp_pktout_queue_config() >>> - * * odp_pktio_start() >>> - * >>> - * ... and tear down sequence is: >>> - * * odp_pktio_stop() >>> - * * odp_pktio_close() >>> - * >>> - * @param name Packet IO device name >>> - * @param pool Default pool from which to allocate storage for packets >>> - * received over this interface, must be of type >>> ODP_POOL_PACKET >>> - * @param param Packet IO parameters >>> - * >>> - * @return Packet IO handle >>> - * @retval ODP_PKTIO_INVALID on failure >>> - * >>> - * @note The device name "loop" is a reserved name for a loopback >>> device used >>> - * for testing purposes. >>> - * >>> - * @note Packets arriving via this interface assigned to a CoS by the >>> - * classifier are received into the pool associated with that CoS. >>> This >>> - * will occur either because this pktio is assigned a default CoS >>> via >>> - * the odp_pktio_default_cos_set() routine, or because a matching >>> PMR >>> - * assigned the packet to a specific CoS. The default pool >>> specified >>> - * here is applicable only for those packets that are not assigned >>> to a >>> - * more specific CoS. >>> - * >>> - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() >>> - */ >>> -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>> - const odp_pktio_param_t *param); >>> +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] >>> ----- >>> +odp_pktio_open()+ takes three arguments: a *name*, which is an >>> implementation-defined string that identifies the logical interface to >>> be >>> diff --git a/include/odp/api/spec/packet_io.h >>> b/include/odp/api/spec/packet_io.h >>> index 7dd10cd..c3945f0 100644 >>> --- a/include/odp/api/spec/packet_io.h >>> +++ b/include/odp/api/spec/packet_io.h >>> @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { >>> odp_pktio_set_op_t set_op; >>> } odp_pktio_capability_t; >>> >>> +// Asciidoc tag::odp_pktio_open[] >>> >> > Aside from the rebase issue, isn't this going to cause checkpatch issues > since we prohibit C++ style comments in C source files? Can Asciidoc use > standard C comments? > > >> /** >>> * Open a packet IO interface >>> * >>> @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { >>> */ >>> odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>> const odp_pktio_param_t *param); >>> +// Asciidoc end::odp_pktio_open[] >>> >>> /** >>> * Query packet IO interface capabilities >>> -- >>> 2.7.4 >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> https://lists.linaro.org/mailman/listinfo/lng-odp >>> >> >> > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs "Work should be fun and collaborative, the rest follows"
No, the issue is putting // style comments in the ODP API files to mark them for AsciiDoctor. Aside from adding cruft, it's hard to see how we can say // is OK here but not elsewhere in ODP .c and .h files. I looked at the asciidoctor doc and they seem to require "line comments" rather than "comments" so I'm not sure if there's anyway to avoid using // here. This is not something I'm comfortable dropping in while Petri is away. I don't think this will be an issue for RC3 since it doesn't change any API definitions or documentation. So let's discuss this next week after Petri returns. On Thu, Apr 28, 2016 at 10:12 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > Patch 2 can be dropped, it was as much an example as anything. > > If checkpatch complains it can be ignored, this is in an asciidoc file, it > is not code, but no ascidoctor does not like /* */ that is why I had to > change them - > > http://asciidoctor.org/docs/user-manual/ > > Here are the line comments that are supported: > > ---- > line of code // <1> > line of code # <2> > line of code ;; <3> > ---- > <1> A callout behind a line comment for C-style languages. > <2> A callout behind a line comment for Ruby, Python, Perl, etc. > <3> A callout behind a line comment for Clojure. > > > On 28 April 2016 at 11:01, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > >> >> >> On Thu, Apr 28, 2016 at 9:58 AM, Bill Fischofer < >> bill.fischofer@linaro.org> wrote: >> >>> Part 1 applies OK, but Part 2 needs a rebase: >>> >>> bill@Ubuntu15:~/linaro/mikedoc2$ git am --reject ~/Mail/Incoming/Mike/2 >>> Applying: doc: reference odp_pktio_open and don't copy it >>> Checking patch doc/users-guide/users-guide-pktio.adoc... >>> Checking patch include/odp/api/spec/packet_io.h... >>> error: while searching for: >>> odp_pktio_set_op_t set_op; >>> } odp_pktio_capability_t; >>> >>> /** >>> * Open a packet IO interface >>> * >>> >>> error: patch failed: include/odp/api/spec/packet_io.h:244 >>> Hunk #2 succeeded at 474 (offset 173 lines). >>> Applied patch doc/users-guide/users-guide-pktio.adoc cleanly. >>> Applying patch include/odp/api/spec/packet_io.h with 1 reject... >>> Rejected hunk #1. >>> Hunk #2 applied cleanly. >>> Patch failed at 0001 doc: reference odp_pktio_open and don't copy it >>> The copy of the patch that failed is found in: >>> /home/bill/linaro/mikedoc2/.git/rebase-apply/patch >>> When you have resolved this problem, run "git am --continue". >>> >>> >>> On Wed, Apr 27, 2016 at 4:59 PM, Mike Holmes <mike.holmes@linaro.org> >>> wrote: >>> >>>> this patch shows how to reference the doxygen api specification and not >>>> cut and paste it into the asciidoc source. >>>> >>>> it does this for just the odp_pktio_open api >>>> >>>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >>>> --- >>>> doc/users-guide/users-guide-pktio.adoc | 57 >>>> +--------------------------------- >>>> include/odp/api/spec/packet_io.h | 2 ++ >>>> 2 files changed, 3 insertions(+), 56 deletions(-) >>>> >>>> diff --git a/doc/users-guide/users-guide-pktio.adoc >>>> b/doc/users-guide/users-guide-pktio.adoc >>>> index 2dd0b15..bfd588d 100644 >>>> --- a/doc/users-guide/users-guide-pktio.adoc >>>> +++ b/doc/users-guide/users-guide-pktio.adoc >>>> @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to >>>> return the PktIO to the >>>> PktIO objects begin life by being _opened_ via the call: >>>> [source,c] >>>> ----- >>>> -/** >>>> - * Open a packet IO interface >>>> - * >>>> - * An ODP program can open a single packet IO interface per device, >>>> attempts >>>> - * to open an already open device will fail, returning >>>> ODP_PKTIO_INVALID with >>>> - * errno set. Use odp_pktio_lookup() to obtain a handle to an already >>>> open >>>> - * device. Packet IO parameters provide interface level configuration >>>> options. >>>> - * >>>> - * Packet input queue configuration must be setup with >>>> - * odp_pktin_queue_config() before odp_pktio_start() is called. When >>>> packet >>>> - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() >>>> call is >>>> - * optional and will ignore all parameters. >>>> - * >>>> - * Packet output queue configuration must be setup with >>>> - * odp_pktout_queue_config() before odp_pktio_start() is called. When >>>> packet >>>> - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, >>>> - * odp_pktout_queue_config() call is optional and will ignore all >>>> parameters. >>>> - * >>>> - * Packet receive and transmit on the interface is enabled with a call >>>> to >>>> - * odp_pktio_start(). If not specified otherwise, any interface level >>>> - * configuration must not be changed when the interface is active >>>> (between start >>>> - * and stop calls). >>>> - * >>>> - * In summary, a typical pktio interface setup sequence is ... >>>> - * * odp_pktio_open() >>>> - * * odp_pktin_queue_config() >>>> - * * odp_pktout_queue_config() >>>> - * * odp_pktio_start() >>>> - * >>>> - * ... and tear down sequence is: >>>> - * * odp_pktio_stop() >>>> - * * odp_pktio_close() >>>> - * >>>> - * @param name Packet IO device name >>>> - * @param pool Default pool from which to allocate storage for >>>> packets >>>> - * received over this interface, must be of type >>>> ODP_POOL_PACKET >>>> - * @param param Packet IO parameters >>>> - * >>>> - * @return Packet IO handle >>>> - * @retval ODP_PKTIO_INVALID on failure >>>> - * >>>> - * @note The device name "loop" is a reserved name for a loopback >>>> device used >>>> - * for testing purposes. >>>> - * >>>> - * @note Packets arriving via this interface assigned to a CoS by the >>>> - * classifier are received into the pool associated with that >>>> CoS. This >>>> - * will occur either because this pktio is assigned a default CoS >>>> via >>>> - * the odp_pktio_default_cos_set() routine, or because a matching >>>> PMR >>>> - * assigned the packet to a specific CoS. The default pool >>>> specified >>>> - * here is applicable only for those packets that are not >>>> assigned to a >>>> - * more specific CoS. >>>> - * >>>> - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() >>>> - */ >>>> -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>> - const odp_pktio_param_t *param); >>>> +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] >>>> ----- >>>> +odp_pktio_open()+ takes three arguments: a *name*, which is an >>>> implementation-defined string that identifies the logical interface to >>>> be >>>> diff --git a/include/odp/api/spec/packet_io.h >>>> b/include/odp/api/spec/packet_io.h >>>> index 7dd10cd..c3945f0 100644 >>>> --- a/include/odp/api/spec/packet_io.h >>>> +++ b/include/odp/api/spec/packet_io.h >>>> @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { >>>> odp_pktio_set_op_t set_op; >>>> } odp_pktio_capability_t; >>>> >>>> +// Asciidoc tag::odp_pktio_open[] >>>> >>> >> Aside from the rebase issue, isn't this going to cause checkpatch issues >> since we prohibit C++ style comments in C source files? Can Asciidoc use >> standard C comments? >> >> >>> /** >>>> * Open a packet IO interface >>>> * >>>> @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { >>>> */ >>>> odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>> const odp_pktio_param_t *param); >>>> +// Asciidoc end::odp_pktio_open[] >>>> >>>> /** >>>> * Query packet IO interface capabilities >>>> -- >>>> 2.7.4 >>>> >>>> _______________________________________________ >>>> lng-odp mailing list >>>> lng-odp@lists.linaro.org >>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>> >>> >>> >> > > > -- > Mike Holmes > Technical Manager - Linaro Networking Group > Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs > "Work should be fun and collaborative, the rest follows" > > >
On 28 April 2016 at 11:37, Bill Fischofer <bill.fischofer@linaro.org> wrote: > No, the issue is putting // style comments in the ODP API files to mark > them for AsciiDoctor. Aside from adding cruft, it's hard to see how we can > say // is OK here but not elsewhere in ODP .c and .h files. > My bad, yes you are right, in the spec is also a "//" not sure of a better way to do it. > > I looked at the asciidoctor doc and they seem to require "line comments" > rather than "comments" so I'm not sure if there's anyway to avoid using // > here. > > This is not something I'm comfortable dropping in while Petri is away. I > don't think this will be an issue for RC3 since it doesn't change any API > definitions or documentation. So let's discuss this next week after Petri > returns. > > On Thu, Apr 28, 2016 at 10:12 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> Patch 2 can be dropped, it was as much an example as anything. >> >> If checkpatch complains it can be ignored, this is in an asciidoc file, >> it is not code, but no ascidoctor does not like /* */ that is why I had to >> change them - >> >> http://asciidoctor.org/docs/user-manual/ >> >> Here are the line comments that are supported: >> >> ---- >> line of code // <1> >> line of code # <2> >> line of code ;; <3> >> ---- >> <1> A callout behind a line comment for C-style languages. >> <2> A callout behind a line comment for Ruby, Python, Perl, etc. >> <3> A callout behind a line comment for Clojure. >> >> >> On 28 April 2016 at 11:01, Bill Fischofer <bill.fischofer@linaro.org> >> wrote: >> >>> >>> >>> On Thu, Apr 28, 2016 at 9:58 AM, Bill Fischofer < >>> bill.fischofer@linaro.org> wrote: >>> >>>> Part 1 applies OK, but Part 2 needs a rebase: >>>> >>>> bill@Ubuntu15:~/linaro/mikedoc2$ git am --reject ~/Mail/Incoming/Mike/2 >>>> Applying: doc: reference odp_pktio_open and don't copy it >>>> Checking patch doc/users-guide/users-guide-pktio.adoc... >>>> Checking patch include/odp/api/spec/packet_io.h... >>>> error: while searching for: >>>> odp_pktio_set_op_t set_op; >>>> } odp_pktio_capability_t; >>>> >>>> /** >>>> * Open a packet IO interface >>>> * >>>> >>>> error: patch failed: include/odp/api/spec/packet_io.h:244 >>>> Hunk #2 succeeded at 474 (offset 173 lines). >>>> Applied patch doc/users-guide/users-guide-pktio.adoc cleanly. >>>> Applying patch include/odp/api/spec/packet_io.h with 1 reject... >>>> Rejected hunk #1. >>>> Hunk #2 applied cleanly. >>>> Patch failed at 0001 doc: reference odp_pktio_open and don't copy it >>>> The copy of the patch that failed is found in: >>>> /home/bill/linaro/mikedoc2/.git/rebase-apply/patch >>>> When you have resolved this problem, run "git am --continue". >>>> >>>> >>>> On Wed, Apr 27, 2016 at 4:59 PM, Mike Holmes <mike.holmes@linaro.org> >>>> wrote: >>>> >>>>> this patch shows how to reference the doxygen api specification and not >>>>> cut and paste it into the asciidoc source. >>>>> >>>>> it does this for just the odp_pktio_open api >>>>> >>>>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >>>>> --- >>>>> doc/users-guide/users-guide-pktio.adoc | 57 >>>>> +--------------------------------- >>>>> include/odp/api/spec/packet_io.h | 2 ++ >>>>> 2 files changed, 3 insertions(+), 56 deletions(-) >>>>> >>>>> diff --git a/doc/users-guide/users-guide-pktio.adoc >>>>> b/doc/users-guide/users-guide-pktio.adoc >>>>> index 2dd0b15..bfd588d 100644 >>>>> --- a/doc/users-guide/users-guide-pktio.adoc >>>>> +++ b/doc/users-guide/users-guide-pktio.adoc >>>>> @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to >>>>> return the PktIO to the >>>>> PktIO objects begin life by being _opened_ via the call: >>>>> [source,c] >>>>> ----- >>>>> -/** >>>>> - * Open a packet IO interface >>>>> - * >>>>> - * An ODP program can open a single packet IO interface per device, >>>>> attempts >>>>> - * to open an already open device will fail, returning >>>>> ODP_PKTIO_INVALID with >>>>> - * errno set. Use odp_pktio_lookup() to obtain a handle to an already >>>>> open >>>>> - * device. Packet IO parameters provide interface level configuration >>>>> options. >>>>> - * >>>>> - * Packet input queue configuration must be setup with >>>>> - * odp_pktin_queue_config() before odp_pktio_start() is called. When >>>>> packet >>>>> - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() >>>>> call is >>>>> - * optional and will ignore all parameters. >>>>> - * >>>>> - * Packet output queue configuration must be setup with >>>>> - * odp_pktout_queue_config() before odp_pktio_start() is called. When >>>>> packet >>>>> - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, >>>>> - * odp_pktout_queue_config() call is optional and will ignore all >>>>> parameters. >>>>> - * >>>>> - * Packet receive and transmit on the interface is enabled with a >>>>> call to >>>>> - * odp_pktio_start(). If not specified otherwise, any interface level >>>>> - * configuration must not be changed when the interface is active >>>>> (between start >>>>> - * and stop calls). >>>>> - * >>>>> - * In summary, a typical pktio interface setup sequence is ... >>>>> - * * odp_pktio_open() >>>>> - * * odp_pktin_queue_config() >>>>> - * * odp_pktout_queue_config() >>>>> - * * odp_pktio_start() >>>>> - * >>>>> - * ... and tear down sequence is: >>>>> - * * odp_pktio_stop() >>>>> - * * odp_pktio_close() >>>>> - * >>>>> - * @param name Packet IO device name >>>>> - * @param pool Default pool from which to allocate storage for >>>>> packets >>>>> - * received over this interface, must be of type >>>>> ODP_POOL_PACKET >>>>> - * @param param Packet IO parameters >>>>> - * >>>>> - * @return Packet IO handle >>>>> - * @retval ODP_PKTIO_INVALID on failure >>>>> - * >>>>> - * @note The device name "loop" is a reserved name for a loopback >>>>> device used >>>>> - * for testing purposes. >>>>> - * >>>>> - * @note Packets arriving via this interface assigned to a CoS by the >>>>> - * classifier are received into the pool associated with that >>>>> CoS. This >>>>> - * will occur either because this pktio is assigned a default >>>>> CoS via >>>>> - * the odp_pktio_default_cos_set() routine, or because a >>>>> matching PMR >>>>> - * assigned the packet to a specific CoS. The default pool >>>>> specified >>>>> - * here is applicable only for those packets that are not >>>>> assigned to a >>>>> - * more specific CoS. >>>>> - * >>>>> - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() >>>>> - */ >>>>> -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>>> - const odp_pktio_param_t *param); >>>>> +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] >>>>> ----- >>>>> +odp_pktio_open()+ takes three arguments: a *name*, which is an >>>>> implementation-defined string that identifies the logical interface >>>>> to be >>>>> diff --git a/include/odp/api/spec/packet_io.h >>>>> b/include/odp/api/spec/packet_io.h >>>>> index 7dd10cd..c3945f0 100644 >>>>> --- a/include/odp/api/spec/packet_io.h >>>>> +++ b/include/odp/api/spec/packet_io.h >>>>> @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { >>>>> odp_pktio_set_op_t set_op; >>>>> } odp_pktio_capability_t; >>>>> >>>>> +// Asciidoc tag::odp_pktio_open[] >>>>> >>>> >>> Aside from the rebase issue, isn't this going to cause checkpatch issues >>> since we prohibit C++ style comments in C source files? Can Asciidoc use >>> standard C comments? >>> >>> >>>> /** >>>>> * Open a packet IO interface >>>>> * >>>>> @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { >>>>> */ >>>>> odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>>> const odp_pktio_param_t *param); >>>>> +// Asciidoc end::odp_pktio_open[] >>>>> >>>>> /** >>>>> * Query packet IO interface capabilities >>>>> -- >>>>> 2.7.4 >>>>> >>>>> _______________________________________________ >>>>> lng-odp mailing list >>>>> lng-odp@lists.linaro.org >>>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>>> >>>> >>>> >>> >> >> >> -- >> Mike Holmes >> Technical Manager - Linaro Networking Group >> Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs >> "Work should be fun and collaborative, the rest follows" >> >> >> > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs "Work should be fun and collaborative, the rest follows"
I would be OK with allowing // style comments throughout ODP. It has the advantage of being able to highlight things differently that catch the eye. Just have to mix things judiciously. But it's something we'd have to get agreement on. Perhaps this is a sufficient justification for changing our rule? On Thu, Apr 28, 2016 at 11:06 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > > > On 28 April 2016 at 11:37, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > >> No, the issue is putting // style comments in the ODP API files to mark >> them for AsciiDoctor. Aside from adding cruft, it's hard to see how we can >> say // is OK here but not elsewhere in ODP .c and .h files. >> > > My bad, yes you are right, in the spec is also a "//" not sure of a better > way to do it. > > >> >> I looked at the asciidoctor doc and they seem to require "line comments" >> rather than "comments" so I'm not sure if there's anyway to avoid using // >> here. >> >> This is not something I'm comfortable dropping in while Petri is away. I >> don't think this will be an issue for RC3 since it doesn't change any API >> definitions or documentation. So let's discuss this next week after Petri >> returns. >> >> On Thu, Apr 28, 2016 at 10:12 AM, Mike Holmes <mike.holmes@linaro.org> >> wrote: >> >>> Patch 2 can be dropped, it was as much an example as anything. >>> >>> If checkpatch complains it can be ignored, this is in an asciidoc file, >>> it is not code, but no ascidoctor does not like /* */ that is why I had to >>> change them - >>> >>> http://asciidoctor.org/docs/user-manual/ >>> >>> Here are the line comments that are supported: >>> >>> ---- >>> line of code // <1> >>> line of code # <2> >>> line of code ;; <3> >>> ---- >>> <1> A callout behind a line comment for C-style languages. >>> <2> A callout behind a line comment for Ruby, Python, Perl, etc. >>> <3> A callout behind a line comment for Clojure. >>> >>> >>> On 28 April 2016 at 11:01, Bill Fischofer <bill.fischofer@linaro.org> >>> wrote: >>> >>>> >>>> >>>> On Thu, Apr 28, 2016 at 9:58 AM, Bill Fischofer < >>>> bill.fischofer@linaro.org> wrote: >>>> >>>>> Part 1 applies OK, but Part 2 needs a rebase: >>>>> >>>>> bill@Ubuntu15:~/linaro/mikedoc2$ git am --reject >>>>> ~/Mail/Incoming/Mike/2 >>>>> Applying: doc: reference odp_pktio_open and don't copy it >>>>> Checking patch doc/users-guide/users-guide-pktio.adoc... >>>>> Checking patch include/odp/api/spec/packet_io.h... >>>>> error: while searching for: >>>>> odp_pktio_set_op_t set_op; >>>>> } odp_pktio_capability_t; >>>>> >>>>> /** >>>>> * Open a packet IO interface >>>>> * >>>>> >>>>> error: patch failed: include/odp/api/spec/packet_io.h:244 >>>>> Hunk #2 succeeded at 474 (offset 173 lines). >>>>> Applied patch doc/users-guide/users-guide-pktio.adoc cleanly. >>>>> Applying patch include/odp/api/spec/packet_io.h with 1 reject... >>>>> Rejected hunk #1. >>>>> Hunk #2 applied cleanly. >>>>> Patch failed at 0001 doc: reference odp_pktio_open and don't copy it >>>>> The copy of the patch that failed is found in: >>>>> /home/bill/linaro/mikedoc2/.git/rebase-apply/patch >>>>> When you have resolved this problem, run "git am --continue". >>>>> >>>>> >>>>> On Wed, Apr 27, 2016 at 4:59 PM, Mike Holmes <mike.holmes@linaro.org> >>>>> wrote: >>>>> >>>>>> this patch shows how to reference the doxygen api specification and >>>>>> not >>>>>> cut and paste it into the asciidoc source. >>>>>> >>>>>> it does this for just the odp_pktio_open api >>>>>> >>>>>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >>>>>> --- >>>>>> doc/users-guide/users-guide-pktio.adoc | 57 >>>>>> +--------------------------------- >>>>>> include/odp/api/spec/packet_io.h | 2 ++ >>>>>> 2 files changed, 3 insertions(+), 56 deletions(-) >>>>>> >>>>>> diff --git a/doc/users-guide/users-guide-pktio.adoc >>>>>> b/doc/users-guide/users-guide-pktio.adoc >>>>>> index 2dd0b15..bfd588d 100644 >>>>>> --- a/doc/users-guide/users-guide-pktio.adoc >>>>>> +++ b/doc/users-guide/users-guide-pktio.adoc >>>>>> @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to >>>>>> return the PktIO to the >>>>>> PktIO objects begin life by being _opened_ via the call: >>>>>> [source,c] >>>>>> ----- >>>>>> -/** >>>>>> - * Open a packet IO interface >>>>>> - * >>>>>> - * An ODP program can open a single packet IO interface per device, >>>>>> attempts >>>>>> - * to open an already open device will fail, returning >>>>>> ODP_PKTIO_INVALID with >>>>>> - * errno set. Use odp_pktio_lookup() to obtain a handle to an >>>>>> already open >>>>>> - * device. Packet IO parameters provide interface level >>>>>> configuration options. >>>>>> - * >>>>>> - * Packet input queue configuration must be setup with >>>>>> - * odp_pktin_queue_config() before odp_pktio_start() is called. When >>>>>> packet >>>>>> - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() >>>>>> call is >>>>>> - * optional and will ignore all parameters. >>>>>> - * >>>>>> - * Packet output queue configuration must be setup with >>>>>> - * odp_pktout_queue_config() before odp_pktio_start() is called. >>>>>> When packet >>>>>> - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, >>>>>> - * odp_pktout_queue_config() call is optional and will ignore all >>>>>> parameters. >>>>>> - * >>>>>> - * Packet receive and transmit on the interface is enabled with a >>>>>> call to >>>>>> - * odp_pktio_start(). If not specified otherwise, any interface level >>>>>> - * configuration must not be changed when the interface is active >>>>>> (between start >>>>>> - * and stop calls). >>>>>> - * >>>>>> - * In summary, a typical pktio interface setup sequence is ... >>>>>> - * * odp_pktio_open() >>>>>> - * * odp_pktin_queue_config() >>>>>> - * * odp_pktout_queue_config() >>>>>> - * * odp_pktio_start() >>>>>> - * >>>>>> - * ... and tear down sequence is: >>>>>> - * * odp_pktio_stop() >>>>>> - * * odp_pktio_close() >>>>>> - * >>>>>> - * @param name Packet IO device name >>>>>> - * @param pool Default pool from which to allocate storage for >>>>>> packets >>>>>> - * received over this interface, must be of type >>>>>> ODP_POOL_PACKET >>>>>> - * @param param Packet IO parameters >>>>>> - * >>>>>> - * @return Packet IO handle >>>>>> - * @retval ODP_PKTIO_INVALID on failure >>>>>> - * >>>>>> - * @note The device name "loop" is a reserved name for a loopback >>>>>> device used >>>>>> - * for testing purposes. >>>>>> - * >>>>>> - * @note Packets arriving via this interface assigned to a CoS by the >>>>>> - * classifier are received into the pool associated with that >>>>>> CoS. This >>>>>> - * will occur either because this pktio is assigned a default >>>>>> CoS via >>>>>> - * the odp_pktio_default_cos_set() routine, or because a >>>>>> matching PMR >>>>>> - * assigned the packet to a specific CoS. The default pool >>>>>> specified >>>>>> - * here is applicable only for those packets that are not >>>>>> assigned to a >>>>>> - * more specific CoS. >>>>>> - * >>>>>> - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() >>>>>> - */ >>>>>> -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>>>> - const odp_pktio_param_t *param); >>>>>> +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] >>>>>> ----- >>>>>> +odp_pktio_open()+ takes three arguments: a *name*, which is an >>>>>> implementation-defined string that identifies the logical interface >>>>>> to be >>>>>> diff --git a/include/odp/api/spec/packet_io.h >>>>>> b/include/odp/api/spec/packet_io.h >>>>>> index 7dd10cd..c3945f0 100644 >>>>>> --- a/include/odp/api/spec/packet_io.h >>>>>> +++ b/include/odp/api/spec/packet_io.h >>>>>> @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { >>>>>> odp_pktio_set_op_t set_op; >>>>>> } odp_pktio_capability_t; >>>>>> >>>>>> +// Asciidoc tag::odp_pktio_open[] >>>>>> >>>>> >>>> Aside from the rebase issue, isn't this going to cause checkpatch >>>> issues since we prohibit C++ style comments in C source files? Can >>>> Asciidoc use standard C comments? >>>> >>>> >>>>> /** >>>>>> * Open a packet IO interface >>>>>> * >>>>>> @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { >>>>>> */ >>>>>> odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>>>> const odp_pktio_param_t *param); >>>>>> +// Asciidoc end::odp_pktio_open[] >>>>>> >>>>>> /** >>>>>> * Query packet IO interface capabilities >>>>>> -- >>>>>> 2.7.4 >>>>>> >>>>>> _______________________________________________ >>>>>> lng-odp mailing list >>>>>> lng-odp@lists.linaro.org >>>>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>>>> >>>>> >>>>> >>>> >>> >>> >>> -- >>> Mike Holmes >>> Technical Manager - Linaro Networking Group >>> Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM >>> SoCs >>> "Work should be fun and collaborative, the rest follows" >>> >>> >>> >> > > > -- > Mike Holmes > Technical Manager - Linaro Networking Group > Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs > "Work should be fun and collaborative, the rest follows" > > >
On 29 April 2016 at 17:58, Bill Fischofer <bill.fischofer@linaro.org> wrote: > I would be OK with allowing // style comments throughout ODP. It has the > advantage of being able to highlight things > differently that catch the eye. Just have to mix things judiciously. But > it's something we'd have to get agreement on. Perhaps this is a sufficient > justification for changing our rule? > Lets bring it up on Mondays call, I hope the switch to asciidoctor can happen regardless of tagging from the spec to the user-guide as in this patch, asciidoctor is superior. > > On Thu, Apr 28, 2016 at 11:06 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> >> >> On 28 April 2016 at 11:37, Bill Fischofer <bill.fischofer@linaro.org> >> wrote: >> >>> No, the issue is putting // style comments in the ODP API files to mark >>> them for AsciiDoctor. Aside from adding cruft, it's hard to see how we can >>> say // is OK here but not elsewhere in ODP .c and .h files. >>> >> >> My bad, yes you are right, in the spec is also a "//" not sure of a >> better way to do it. >> >> >>> >>> I looked at the asciidoctor doc and they seem to require "line comments" >>> rather than "comments" so I'm not sure if there's anyway to avoid using // >>> here. >>> >>> This is not something I'm comfortable dropping in while Petri is away. I >>> don't think this will be an issue for RC3 since it doesn't change any API >>> definitions or documentation. So let's discuss this next week after Petri >>> returns. >>> >>> On Thu, Apr 28, 2016 at 10:12 AM, Mike Holmes <mike.holmes@linaro.org> >>> wrote: >>> >>>> Patch 2 can be dropped, it was as much an example as anything. >>>> >>>> If checkpatch complains it can be ignored, this is in an asciidoc file, >>>> it is not code, but no ascidoctor does not like /* */ that is why I had to >>>> change them - >>>> >>>> http://asciidoctor.org/docs/user-manual/ >>>> >>>> Here are the line comments that are supported: >>>> >>>> ---- >>>> line of code // <1> >>>> line of code # <2> >>>> line of code ;; <3> >>>> ---- >>>> <1> A callout behind a line comment for C-style languages. >>>> <2> A callout behind a line comment for Ruby, Python, Perl, etc. >>>> <3> A callout behind a line comment for Clojure. >>>> >>>> >>>> On 28 April 2016 at 11:01, Bill Fischofer <bill.fischofer@linaro.org> >>>> wrote: >>>> >>>>> >>>>> >>>>> On Thu, Apr 28, 2016 at 9:58 AM, Bill Fischofer < >>>>> bill.fischofer@linaro.org> wrote: >>>>> >>>>>> Part 1 applies OK, but Part 2 needs a rebase: >>>>>> >>>>>> bill@Ubuntu15:~/linaro/mikedoc2$ git am --reject >>>>>> ~/Mail/Incoming/Mike/2 >>>>>> Applying: doc: reference odp_pktio_open and don't copy it >>>>>> Checking patch doc/users-guide/users-guide-pktio.adoc... >>>>>> Checking patch include/odp/api/spec/packet_io.h... >>>>>> error: while searching for: >>>>>> odp_pktio_set_op_t set_op; >>>>>> } odp_pktio_capability_t; >>>>>> >>>>>> /** >>>>>> * Open a packet IO interface >>>>>> * >>>>>> >>>>>> error: patch failed: include/odp/api/spec/packet_io.h:244 >>>>>> Hunk #2 succeeded at 474 (offset 173 lines). >>>>>> Applied patch doc/users-guide/users-guide-pktio.adoc cleanly. >>>>>> Applying patch include/odp/api/spec/packet_io.h with 1 reject... >>>>>> Rejected hunk #1. >>>>>> Hunk #2 applied cleanly. >>>>>> Patch failed at 0001 doc: reference odp_pktio_open and don't copy it >>>>>> The copy of the patch that failed is found in: >>>>>> /home/bill/linaro/mikedoc2/.git/rebase-apply/patch >>>>>> When you have resolved this problem, run "git am --continue". >>>>>> >>>>>> >>>>>> On Wed, Apr 27, 2016 at 4:59 PM, Mike Holmes <mike.holmes@linaro.org> >>>>>> wrote: >>>>>> >>>>>>> this patch shows how to reference the doxygen api specification and >>>>>>> not >>>>>>> cut and paste it into the asciidoc source. >>>>>>> >>>>>>> it does this for just the odp_pktio_open api >>>>>>> >>>>>>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >>>>>>> --- >>>>>>> doc/users-guide/users-guide-pktio.adoc | 57 >>>>>>> +--------------------------------- >>>>>>> include/odp/api/spec/packet_io.h | 2 ++ >>>>>>> 2 files changed, 3 insertions(+), 56 deletions(-) >>>>>>> >>>>>>> diff --git a/doc/users-guide/users-guide-pktio.adoc >>>>>>> b/doc/users-guide/users-guide-pktio.adoc >>>>>>> index 2dd0b15..bfd588d 100644 >>>>>>> --- a/doc/users-guide/users-guide-pktio.adoc >>>>>>> +++ b/doc/users-guide/users-guide-pktio.adoc >>>>>>> @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to >>>>>>> return the PktIO to the >>>>>>> PktIO objects begin life by being _opened_ via the call: >>>>>>> [source,c] >>>>>>> ----- >>>>>>> -/** >>>>>>> - * Open a packet IO interface >>>>>>> - * >>>>>>> - * An ODP program can open a single packet IO interface per device, >>>>>>> attempts >>>>>>> - * to open an already open device will fail, returning >>>>>>> ODP_PKTIO_INVALID with >>>>>>> - * errno set. Use odp_pktio_lookup() to obtain a handle to an >>>>>>> already open >>>>>>> - * device. Packet IO parameters provide interface level >>>>>>> configuration options. >>>>>>> - * >>>>>>> - * Packet input queue configuration must be setup with >>>>>>> - * odp_pktin_queue_config() before odp_pktio_start() is called. >>>>>>> When packet >>>>>>> - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() >>>>>>> call is >>>>>>> - * optional and will ignore all parameters. >>>>>>> - * >>>>>>> - * Packet output queue configuration must be setup with >>>>>>> - * odp_pktout_queue_config() before odp_pktio_start() is called. >>>>>>> When packet >>>>>>> - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, >>>>>>> - * odp_pktout_queue_config() call is optional and will ignore all >>>>>>> parameters. >>>>>>> - * >>>>>>> - * Packet receive and transmit on the interface is enabled with a >>>>>>> call to >>>>>>> - * odp_pktio_start(). If not specified otherwise, any interface >>>>>>> level >>>>>>> - * configuration must not be changed when the interface is active >>>>>>> (between start >>>>>>> - * and stop calls). >>>>>>> - * >>>>>>> - * In summary, a typical pktio interface setup sequence is ... >>>>>>> - * * odp_pktio_open() >>>>>>> - * * odp_pktin_queue_config() >>>>>>> - * * odp_pktout_queue_config() >>>>>>> - * * odp_pktio_start() >>>>>>> - * >>>>>>> - * ... and tear down sequence is: >>>>>>> - * * odp_pktio_stop() >>>>>>> - * * odp_pktio_close() >>>>>>> - * >>>>>>> - * @param name Packet IO device name >>>>>>> - * @param pool Default pool from which to allocate storage for >>>>>>> packets >>>>>>> - * received over this interface, must be of type >>>>>>> ODP_POOL_PACKET >>>>>>> - * @param param Packet IO parameters >>>>>>> - * >>>>>>> - * @return Packet IO handle >>>>>>> - * @retval ODP_PKTIO_INVALID on failure >>>>>>> - * >>>>>>> - * @note The device name "loop" is a reserved name for a loopback >>>>>>> device used >>>>>>> - * for testing purposes. >>>>>>> - * >>>>>>> - * @note Packets arriving via this interface assigned to a CoS by >>>>>>> the >>>>>>> - * classifier are received into the pool associated with that >>>>>>> CoS. This >>>>>>> - * will occur either because this pktio is assigned a default >>>>>>> CoS via >>>>>>> - * the odp_pktio_default_cos_set() routine, or because a >>>>>>> matching PMR >>>>>>> - * assigned the packet to a specific CoS. The default pool >>>>>>> specified >>>>>>> - * here is applicable only for those packets that are not >>>>>>> assigned to a >>>>>>> - * more specific CoS. >>>>>>> - * >>>>>>> - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() >>>>>>> - */ >>>>>>> -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>>>>> - const odp_pktio_param_t *param); >>>>>>> +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] >>>>>>> ----- >>>>>>> +odp_pktio_open()+ takes three arguments: a *name*, which is an >>>>>>> implementation-defined string that identifies the logical interface >>>>>>> to be >>>>>>> diff --git a/include/odp/api/spec/packet_io.h >>>>>>> b/include/odp/api/spec/packet_io.h >>>>>>> index 7dd10cd..c3945f0 100644 >>>>>>> --- a/include/odp/api/spec/packet_io.h >>>>>>> +++ b/include/odp/api/spec/packet_io.h >>>>>>> @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { >>>>>>> odp_pktio_set_op_t set_op; >>>>>>> } odp_pktio_capability_t; >>>>>>> >>>>>>> +// Asciidoc tag::odp_pktio_open[] >>>>>>> >>>>>> >>>>> Aside from the rebase issue, isn't this going to cause checkpatch >>>>> issues since we prohibit C++ style comments in C source files? Can >>>>> Asciidoc use standard C comments? >>>>> >>>>> >>>>>> /** >>>>>>> * Open a packet IO interface >>>>>>> * >>>>>>> @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { >>>>>>> */ >>>>>>> odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, >>>>>>> const odp_pktio_param_t *param); >>>>>>> +// Asciidoc end::odp_pktio_open[] >>>>>>> >>>>>>> /** >>>>>>> * Query packet IO interface capabilities >>>>>>> -- >>>>>>> 2.7.4 >>>>>>> >>>>>>> _______________________________________________ >>>>>>> lng-odp mailing list >>>>>>> lng-odp@lists.linaro.org >>>>>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>>>>> >>>>>> >>>>>> >>>>> >>>> >>>> >>>> -- >>>> Mike Holmes >>>> Technical Manager - Linaro Networking Group >>>> Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM >>>> SoCs >>>> "Work should be fun and collaborative, the rest follows" >>>> >>>> >>>> >>> >> >> >> -- >> Mike Holmes >> Technical Manager - Linaro Networking Group >> Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs >> "Work should be fun and collaborative, the rest follows" >> >> >> > -- Mike Holmes Technical Manager - Linaro Networking Group Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM SoCs "Work should be fun and collaborative, the rest follows"
diff --git a/doc/users-guide/users-guide-pktio.adoc b/doc/users-guide/users-guide-pktio.adoc index 2dd0b15..bfd588d 100644 --- a/doc/users-guide/users-guide-pktio.adoc +++ b/doc/users-guide/users-guide-pktio.adoc @@ -30,62 +30,7 @@ or *Closed* via the +odp_pktio_close()+ API to return the PktIO to the PktIO objects begin life by being _opened_ via the call: [source,c] ----- -/** - * Open a packet IO interface - * - * An ODP program can open a single packet IO interface per device, attempts - * to open an already open device will fail, returning ODP_PKTIO_INVALID with - * errno set. Use odp_pktio_lookup() to obtain a handle to an already open - * device. Packet IO parameters provide interface level configuration options. - * - * Packet input queue configuration must be setup with - * odp_pktin_queue_config() before odp_pktio_start() is called. When packet - * input mode is ODP_PKTIN_MODE_DISABLED, odp_pktin_queue_config() call is - * optional and will ignore all parameters. - * - * Packet output queue configuration must be setup with - * odp_pktout_queue_config() before odp_pktio_start() is called. When packet - * output mode is ODP_PKTOUT_MODE_DISABLED or ODP_PKTOUT_MODE_TM, - * odp_pktout_queue_config() call is optional and will ignore all parameters. - * - * Packet receive and transmit on the interface is enabled with a call to - * odp_pktio_start(). If not specified otherwise, any interface level - * configuration must not be changed when the interface is active (between start - * and stop calls). - * - * In summary, a typical pktio interface setup sequence is ... - * * odp_pktio_open() - * * odp_pktin_queue_config() - * * odp_pktout_queue_config() - * * odp_pktio_start() - * - * ... and tear down sequence is: - * * odp_pktio_stop() - * * odp_pktio_close() - * - * @param name Packet IO device name - * @param pool Default pool from which to allocate storage for packets - * received over this interface, must be of type ODP_POOL_PACKET - * @param param Packet IO parameters - * - * @return Packet IO handle - * @retval ODP_PKTIO_INVALID on failure - * - * @note The device name "loop" is a reserved name for a loopback device used - * for testing purposes. - * - * @note Packets arriving via this interface assigned to a CoS by the - * classifier are received into the pool associated with that CoS. This - * will occur either because this pktio is assigned a default CoS via - * the odp_pktio_default_cos_set() routine, or because a matching PMR - * assigned the packet to a specific CoS. The default pool specified - * here is applicable only for those packets that are not assigned to a - * more specific CoS. - * - * @see odp_pktio_start(), odp_pktio_stop(), odp_pktio_close() - */ -odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, - const odp_pktio_param_t *param); +include::../../include/odp/api/spec/packet_io.h[tags=odp_pktio_open] ----- +odp_pktio_open()+ takes three arguments: a *name*, which is an implementation-defined string that identifies the logical interface to be diff --git a/include/odp/api/spec/packet_io.h b/include/odp/api/spec/packet_io.h index 7dd10cd..c3945f0 100644 --- a/include/odp/api/spec/packet_io.h +++ b/include/odp/api/spec/packet_io.h @@ -244,6 +244,7 @@ typedef struct odp_pktio_capability_t { odp_pktio_set_op_t set_op; } odp_pktio_capability_t; +// Asciidoc tag::odp_pktio_open[] /** * Open a packet IO interface * @@ -300,6 +301,7 @@ typedef struct odp_pktio_capability_t { */ odp_pktio_t odp_pktio_open(const char *name, odp_pool_t pool, const odp_pktio_param_t *param); +// Asciidoc end::odp_pktio_open[] /** * Query packet IO interface capabilities
this patch shows how to reference the doxygen api specification and not cut and paste it into the asciidoc source. it does this for just the odp_pktio_open api Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/users-guide/users-guide-pktio.adoc | 57 +--------------------------------- include/odp/api/spec/packet_io.h | 2 ++ 2 files changed, 3 insertions(+), 56 deletions(-)