On 28 April 2016 at 11:37, Bill Fischofer <bill.fischo...@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.hol...@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.fischo...@linaro.org> >> wrote: >> >>> >>> >>> On Thu, Apr 28, 2016 at 9:58 AM, Bill Fischofer < >>> bill.fischo...@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.hol...@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.hol...@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"
_______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org https://lists.linaro.org/mailman/listinfo/lng-odp
