From patchwork Mon Dec 5 16:22:11 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 86587 Delivered-To: patch@linaro.org Received: by 10.140.20.101 with SMTP id 92csp1564995qgi; Mon, 5 Dec 2016 08:22:48 -0800 (PST) X-Received: by 10.237.61.98 with SMTP id h31mr56037246qtf.243.1480954968066; Mon, 05 Dec 2016 08:22:48 -0800 (PST) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id m184si9231981qkb.181.2016.12.05.08.22.47; Mon, 05 Dec 2016 08:22:48 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 5A83462C14; Mon, 5 Dec 2016 16:22:47 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id B55EA60DD5; Mon, 5 Dec 2016 16:22:40 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id D75B460DDE; Mon, 5 Dec 2016 16:22:22 +0000 (UTC) Received: from mail-qt0-f174.google.com (mail-qt0-f174.google.com [209.85.216.174]) by lists.linaro.org (Postfix) with ESMTPS id 9CDD96092B for ; Mon, 5 Dec 2016 16:22:20 +0000 (UTC) Received: by mail-qt0-f174.google.com with SMTP id p16so317875286qta.0 for ; Mon, 05 Dec 2016 08:22:20 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=7sHgWON4y0uBFFmaqDXTJ9qSfnaq2y7Bs5uqmEU8+is=; b=nK/l5RB3wNuDE8W9roH7gnG4egMA0v4CJGFqTaYuIXAobo1jKvXrbR1KztjCpNx/G8 MYlmNBwAKHv/rCn+3k7Cpm/ffUJgVQgzIaRkD+yjzyGCc8PqM/3FQpvpJsGZPqNOx2Sv nsna1MCsB1X5wm5Q/N25qJI85eB6Ka1amYdnyiHEU3VDQSpYHBwdCzZ+s8tWXNhaD/cs YxncehRh4qzfsasO5QipRh/UqN+py7Bdp1ujyGJ736eQbyrraODvKj7UKi7+cCGNbD3J hFFcMPy+3q2QuV+tbY025hi79v+llSrfORDULj9sr8x470KfXS2JTa5MnSd1GWdt/vb6 +uqA== X-Gm-Message-State: AKaTC03v7nZ33oY3Fm6P1w/vamzcn9VLtxpOLDIWUm6XIgTUXWwJSvTqzuFUjZCjhFdesRkIpfM= X-Received: by 10.237.36.235 with SMTP id u40mr51130965qtc.110.1480954939909; Mon, 05 Dec 2016 08:22:19 -0800 (PST) Received: from localhost (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id g97sm9733816qkh.11.2016.12.05.08.22.19 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 05 Dec 2016 08:22:19 -0800 (PST) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Mon, 5 Dec 2016 11:22:11 -0500 Message-Id: <20161205162211.7202-2-mike.holmes@linaro.org> X-Mailer: git-send-email 2.9.3 In-Reply-To: <20161205162211.7202-1-mike.holmes@linaro.org> References: <20161205162211.7202-1-mike.holmes@linaro.org> Subject: [lng-odp] [PATCH 2/2] doc: release-guide: detail abi & api tools X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Mike Holmes --- doc/process-guide/release-guide.adoc | 176 +++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) -- 2.9.3 diff --git a/doc/process-guide/release-guide.adoc b/doc/process-guide/release-guide.adoc index 8ea147a..1f77ab2 100644 --- a/doc/process-guide/release-guide.adoc +++ b/doc/process-guide/release-guide.adoc @@ -350,3 +350,179 @@ typedef struct foo_init_t { int num_control; int other_items; ---- +== API & ABI difference tools +=== API difference tool +The API doxygen documentation can be compared with a previous +release to get the basic summary of changes, as shown below between 1.10.1.0 and +1.11.0.0 +[source,bash] +---- +GIT_BRANCH=master COMPARE_BRANCH=v1.10.1.0 ./diff-api.sh +... +... +diff --suppress-common-lines --recursive -t -s -d --unified odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/a_summary.txt odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/a_summary.txt +--- odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/a_summary.txt 2016-12-05 10:10:51.126723616 -0500 ++++ odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/a_summary.txt 2016-12-05 10:10:51.318727901 -0500 +@@ -1,34 +1,36 @@ + +-Generated from /home/mike/git/check-odp/build/odp_diff a details directory called odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module ++Generated from /home/mike/git/check-odp/build/odp_diff_2 a details directory called odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module + + MODULE FUNCTION TYPEDEF DEFINE +- odp_atomic 45 1 0 +- odp_barrier 5 0 0 +- odp_buffer 12 0 0 +- odp_classification 17 1 0 +- odp_compiler_optim 12 0 13 ++ odp_atomic 44 1 0 ++ odp_barrier 4 1 0 ++ odp_buffer 13 1 1 ++ odp_classification 17 1 3 ++ odp_compiler_optim 11 1 18 + odp_cpu 13 0 0 +- odp_cpumask 19 0 0 +- odp_crypto 10 1 0 ++ odp_cpumask 19 1 2 ++ odp_crypto 10 1 1 + odp_errno 4 0 0 +- odp_event 3 0 0 ++ odp_event 3 1 1 + odp_hash 3 1 0 + odp_initialization 6 1 0 +- odp_locks 29 0 0 +- odp_packet 124 0 0 +- odp_packet_io 40 1 0 +- odp_pool 8 1 4 +- odp_queue 18 1 0 ++ odp_locks 29 1 0 ++ odp_packet 124 1 4 ++ odp_packet_io 40 1 4 ++ odp_pool 8 1 5 ++ odp_queue 18 1 3 + odp_random 1 0 0 +- odp_scheduler 18 1 0 +- odp_shared_memory 8 1 3 ++ odp_scheduler 18 1 14 ++ odp_shared_memory 8 1 5 + odp_std_clib 3 0 0 +- odp_system 3 0 0 +- odp_thread 22 1 0 +- odp_time 13 0 3 +- odp_timer 23 0 1 +- odp_traffic_mngr 69 1 3 ++ odp_system 3 1 0 ++ odp_thread 22 1 2 ++ odp_time 13 1 4 ++ odp_timer 23 1 4 ++ odp_traffic_mngr 70 1 18 + odp_version 3 0 3 +- TOTAL 531 12 30 +.... +diff --suppress-common-lines --recursive -t -s -d --unified odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/odp_atomic.txt odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/odp_atomic.txt +--- odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/odp_atomic.txt 2016-12-05 10:13:57.551084481 -0500 ++++ odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/odp_atomic.txt 2016-12-05 10:13:57.723088576 -0500 +@@ -1,4 +1,3 @@ +- void odp_atomic_init_u32(odp_atomic_u32_t * atom, uint32_t val) + uint32_t odp_atomic_load_u32(odp_atomic_u32_t * atom) + void odp_atomic_store_u32(odp_atomic_u32_t * atom, uint32_t val) + uint32_t odp_atomic_fetch_add_u32(odp_atomic_u32_t * atom, uint32_t val) +@@ -44,4 +43,6 @@ + int odp_atomic_cas_acq_rel_u64(odp_atomic_u64_t * atom, uint64_t * old_val, uint64_t new_val) + int odp_atomic_lock_free_u64(odp_atomic_op_t * atomic_op) + union odp_atomic_op_t odp_atomic_op_t ++ struct odp_atomic_u64_s odp_atomic_u64_t ++ struct odp_atomic_u32_s odp_atomic_u32_t +... +Addtional detailed results follow for each summarized difference. +... +---- +If the summary is examined it can be seen that the odp_atomic module lost a function in its API + + MODULE FUNCTION TYPEDEF DEFINE +- odp_atomic 45 1 0 +... ++ odp_atomic 44 1 0 + + +If this tool shows a difference then it is likely that the API version number +must be changed in the configure.ac. +[source,automake] +---- +########################################################################## +# Set correct API version +########################################################################## +m4_define([odpapi_generation_version], [1]) +m4_define([odpapi_major_version], [12]) +m4_define([odpapi_minor_version], [0]) +m4_define([odpapi_point_version], [0]) +---- + +=== ABI difference tool +ABI and source code differences can be discovered using the ABI diff tool. +The tool is is based on the Debian abi-compliance-checker tool. +This tool generates a html detailed analysis and a short text summary as shown +below. In this case between master and the monarch LTS release. + +[source,bash] +---- +COMPARE_BRANCH=v1.11.0.0_monarch ./diff-api.sh +... +comparing ABIs ... +comparing APIs ... +creating compatibility report ... +result: COMPATIBLE +total "Binary" compatibility problems: 0, warnings: 0 +total "Source" compatibility problems: 0, warnings: 0 +see detailed report: + compat_reports/git.linaro.org_lng_odp-git.linaro.org_lng_odp/master_to_v1.11.0.0_monarch/compat_report.html +preparation, please wait ... +comparing ABIs ... +comparing APIs ... +creating compatibility report ... +result: INCOMPATIBLE (Binary: 12%, Source: 12%) +total "Binary" compatibility problems: 62, warnings: 4 +total "Source" compatibility problems: 62, warnings: 0 +see detailed report: + compat_reports/git.linaro.org_lng_odp-git.linaro.org_lng_odp/master_to_v1.11.0.0_monarch/compat_report.html +moved report to ~/git/check-odp/publishing/diff-abi/libodp-compat_report.html + +---- +The html output is quite detailed as seen below + +.An example of the diff-abi html output +image::Screenshot_diff-abi.png[align="center"] + +When it comes to the library version this tool makes things very clear listing +added, changed and removed APIs +[source,bash] +---- +Removed Symbols 62 +atomic_inlines.h, libodp-linux.so.112.0.0 +odp_atomic_add_rel_u32 ( odp_atomic_u32_t* atom, uint32_t val ) +odp_atomic_add_rel_u64 ( odp_atomic_u64_t* atom, uint64_t val ) +odp_atomic_add_u32 ( odp_atomic_u32_t* atom, uint32_t val ) +odp_atomic_add_u64 ( odp_atomic_u64_t* atom, uint64_t val ) +odp_atomic_cas_acq_rel_u32 ( odp_atomic_u32_t* atom, uint32_t* old_val, uint32_t new_val ) +---- + +If this tool shows a difference in the odp or helper library then the library +version number must be changed in the configure.ac +[source,bash] +---- +########################################################################## +# Set platform library version +# +# Follow version rules described here: +# https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html +# Version is Current:Revision:Age +# 1. if there are only source changes, use C:R+1:A +# 2. if interfaces were added use C+1:0:A+1 +# 3. if interfaces were removed, then use C+1:0:0 +########################################################################## + +ODP_LIBSO_VERSION=112:0:0 +AC_SUBST(ODP_LIBSO_VERSION) + +ODPHELPER_LIBSO_VERSION=110:1:1 +AC_SUBST(ODPHELPER_LIBSO_VERSION) +----