Hi, I share Dave's opinion regarding API documentation. It is hard to keep it up to date. In my opinion this applies to wiki pages as well. Often tests are often much better source of information. Dave mentioned "make test" framework. Other good source of information are CSIT tests, which also use binary api.
Honeycomb provides YANG models for vpp features. To design such model we need to know which binary APIs to use for creating/reading/updating/deleting feature configuration. We need to know correct order of api call invocation (if more than one is needed), what are valid input parameters, which parameters are optional, etc. Here is my usual workflow: 1) check binary api documentation if exists 2) check make test / CSIT to see what combinations of parameters and api calls actually work 3) check documentation for corresponding CLI cmd (these are usually much better documented) 4) compare parameter handling for CLI and api handler (it can differ!) 5) ask vpp-dev Regards, Marek From: vpp-dev-boun...@lists.fd.io [mailto:vpp-dev-boun...@lists.fd.io] On Behalf Of Dave Wallace Sent: 21 lutego 2017 18:34 To: Jon Loeliger <j...@netgate.com>; Matus Fabian -X (matfabia - PANTHEON TECHNOLOGIES at Cisco) <matfa...@cisco.com> Cc: vpp-dev <vpp-dev@lists.fd.io> Subject: Re: [vpp-dev] SNAT API Question Jon, Comments inline... On 02/20/2017 03:14 PM, Jon Loeliger wrote: Hi Matus, Thanks for your answers here. On Sat, Feb 18, 2017 at 12:36 AM, Matus Fabian -X (matfabia - PANTHEON TECHNOLOGIES at Cisco) <matfa...@cisco.com<mailto:matfa...@cisco.com>> wrote: If external_sw_if_index value is ~0 (-1) external_ip_address is ussed from API (snat.c line 363). OK, I see that in the code, but it is nowhere described in the API itself. That is my issue here. Magic values like this *are* part of the API as they will affect changes on the VPP-side of the API interface. The lack of comprehensive VPP-API documentation is a known issue. In my experience this has been a universal condition with every system I've ever worked on. Any contributions to improve the VPP-API documentation would be very greatly appreciated. snat_add_address_range - add address range to SNAT address pool snat_add_del_interface_addr - add address of the interface to SNAT address pool (address is added/removed automatically when interface address is changed by configuration or DHCP) So one could use either or both, as they wish? I guess I'm having a bit of hard time trying to figure out what the canonical API call sequence would be to set up various useful and standard NAT situations. Yes, I've read the Wiki page; No it isn't clear on the proper, expected sequence of the API calls. This is another variation on the theme of VPP-API documentation (or lack thereof). I recently added the saving of the api trace log and dump to the "make test" infrastructure specifically to be able to data mine the API sequences embedded in the test cases. After running "make test" you will now find the binary api trace log (/tmp/vpp-unittest-TEST*/vpp_api_trace.<test name>.log) and a dump of the api trace in the test log (search for "api trace" in /tmp/vpp-unittest-TEST*/log.txt). You can recreate the configuration using the vpp_api_trace.<test name>.log and the custom-dump mechanism to re-create the configuration as described in https://wiki.fd.io/view/VPP/How_To_Use_The_API_Trace_Tools While not perfect solution to the problem, it is the most pragmatic approach I could think of to address this issue. Hopefully this will help encourage feature developers to expand the number of use cases in the "make test" framework. Of course, converting the api trace data into usable documentation is another task to be done. Automating this task is probably the best way to attack this issue, otherwise the documentation will go stale over time. Just a matter of a little more typing ;^) How does those API sequences change for the different values of the config variables "static_mapping_only" and "static_mapping_connection_tracking"? And on that note -- How do you change the value of those config varaibles at run time? I know how to alter the config file and re-read them in VAT. I'm not using VAT. I'm writing a totally different system. Can those values be changed at run-time? There is no API to do so, so at this point in time the answer must be "no." Is it expected that the sequence to change these configuration values at run time is to: 1) Stop VPP, 2) write a new config file with the new desired values, 3) restart VPP? That seems bad to me. I'll let Matus address the SNAT specifics, but in general appropriate VPP-API interfaces should be developed to allow dynamic configuration of VPP features. That being said, it is less work to develop basic functionality using configuration variables prior to creating a comprehensive debug CLI + VPP-API interface. Prototyping can be a good thing, but is no substitute for developing a production interface. I think 1024 is not significant, it's just a warning that you add a lot of addresses to SNAT address pool, it was here before I started work on SNAT plugin. Well, 1024 is arbitrary. Who is to say that I don't need 2048 and don't care about the warning in my environment? To be clear, I'm not blaming you (Matus), or anyone for that matter. I'm merely pointing out that it is an arbitrary and undocumented limit in the current system. Yep. At the very least this should be documented. If there is a need to configure this, then the appropriate code should be added to do so. Thanks, -daw- Matus Thanks, jdl _______________________________________________ vpp-dev mailing list vpp-dev@lists.fd.io<mailto:vpp-dev@lists.fd.io> https://lists.fd.io/mailman/listinfo/vpp-dev
_______________________________________________ vpp-dev mailing list vpp-dev@lists.fd.io https://lists.fd.io/mailman/listinfo/vpp-dev
