Re: [dpdk-dev] [PATCH 2/2] ABI: Add some documentation

["Mcnamara, John" <john.mcnamara@intel.com>]

> -----Original Message-----
> From: Neil Horman [mailto:nhorman@tuxdriver.com]
> Sent: Tuesday, June 23, 2015 8:34 PM
> To: dev@dpdk.org
> Cc: Neil Horman; Mcnamara, John; thomas.monjalon@6wind.com
> Subject: [PATCH 2/2] ABI: Add some documentation
> 
> People have been asking for ways to use the ABI macros, heres some docs to
> clarify their use.  Included is:

Hi,

Thanks for this.

There are a few minor comments on the RST structure below.

Also, there is a conflict in the doc/guides/guidelines/index.rst file with an addition that just got merged. I just needs a rebase.


> +This file needs to be modified as follows
> +
> +.. code-block:: none
> +
> +   DPDK_2.0 {
> +        global:
> +
> +        rte_acl_add_rules;
> +        rte_acl_build;
> +        rte_acl_classify;
> +        rte_acl_classify_alg;
> +        rte_acl_classify_scalar;
> +        rte_acl_create;
> +        rte_acl_dump;
> +        rte_acl_find_existing;
> +        rte_acl_free;
> +        rte_acl_ipv4vlan_add_rules;
> +        rte_acl_ipv4vlan_build;
> +        rte_acl_list_dump;
> +        rte_acl_reset;
> +        rte_acl_reset_rules;
> +        rte_acl_set_ctx_classify;
> +
> +        local: *;
> + };
> +
> + DPDK_2.1 {
> +        global:
> +        rte_acl_create;
> +
> + } DPDK_2.0;

The last 7 lines of this verbatim section should be indented to the same level as the rest of the section. In general the code blocks should be indented at least 3 spaces to keep the various RST converters happy. That applies in a few places.


> +Note that the base name of the symbol was kept in tact, as this is
> +condusive to the macros used for versioning symbols.  That is our next
> +step, mapping this new symbol name to the initial symbol name at
> +version node 2.0.  Immediately after the function, we add this line of
> +code
> +
> +.. code-block:: c
> +
> +   VERSION_SYMBOL(rte_acl_create, _v20, 2.0);VERSION_SYMBOL(rte_acl_create, _v20, 2.0);

The is a duplicate macro here.


> +
> +Remembering to also add the rte_compat.h header to the requisite c file
> +where these changes are being made.  The above macro instructs the
> +linker to create a new symbol rte_acl_create@DPDK_2.0, which matches

Could you enclose the symbol in RST backquotes ``rte_acl_create@DPDK_2.0`` since some of the renderers treat this as an email address! There is another one a few paragraphs down.


> +the symbol created in older builds, but now points to the above newly
> +named function.  We have now mapped the origional rte_acl_create symbol
> +to the origional function 

There are a few minor typos here and there.


> + };
> +
> + DPDK_2.1 {
> +        global:
> +        rte_acl_create;
> + } DPDK_2.0;

Same comment as above on indentation.


John.
--