From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id B8374A0C45 for ; Fri, 23 Jul 2021 14:04:17 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A8FDE40DF5; Fri, 23 Jul 2021 14:04:12 +0200 (CEST) Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by mails.dpdk.org (Postfix) with ESMTP id A50AA4003C; Fri, 23 Jul 2021 14:04:09 +0200 (CEST) X-IronPort-AV: E=McAfee;i="6200,9189,10053"; a="199068868" X-IronPort-AV: E=Sophos;i="5.84,264,1620716400"; d="scan'208";a="199068868" Received: from orsmga005.jf.intel.com ([10.7.209.41]) by orsmga101.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 23 Jul 2021 05:04:08 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.84,264,1620716400"; d="scan'208";a="633322091" Received: from fmsmsx604.amr.corp.intel.com ([10.18.126.84]) by orsmga005.jf.intel.com with ESMTP; 23 Jul 2021 05:04:07 -0700 Received: from fmsmsx603.amr.corp.intel.com (10.18.126.83) by fmsmsx604.amr.corp.intel.com (10.18.126.84) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10; Fri, 23 Jul 2021 05:04:06 -0700 Received: from FMSEDG603.ED.cps.intel.com (10.1.192.133) by fmsmsx603.amr.corp.intel.com (10.18.126.83) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2242.10 via Frontend Transport; Fri, 23 Jul 2021 05:04:06 -0700 Received: from NAM12-MW2-obe.outbound.protection.outlook.com (104.47.66.42) by edgegateway.intel.com (192.55.55.68) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2242.10; Fri, 23 Jul 2021 05:04:06 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=obVStOii0338JfFweZzN3LGZoHvZxwcdFtYKX9DaomE7l+t3wFKVKM0aheRdt9QE/jiGZ2KFRUV9zkYXD99O87UQ2onLLGvoEf0n+zzffD1f04sW4M6C9wx4c18BlNqSgpgLXiZrQZrdVUeZ+TV2lSY11KMeE4b4eMPmmO02Y43bBtz0XibH0acvijw/6iBerhT1kfIKiS4KnhZcwHhQde2JF0aNkr8zXjOE9XTZQkCzfSALaJZ8krBH1UGCmdt08OSF1cnGhDXK5Im6kxLWhK22lLfwQs35G0NVq2TAcgCf+uflH1+svzzP2ElwTwVSjTgfBc0+LSdCqWu3VTqGEw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=1Y3fugPD3LXkMu5Y1jWYNvOgZYqYKqmVcppqJrpHEUo=; b=glbcX2+tc0+ztjK//1wRaDPZKtXmMBNpohp/7RtUEOCgm+vZ05+3AfRW/AAn56sDS96Muu2poLaaptpGHaRhAmepzX+Wx/RePHa4N0OOKCRTQ3BaDwdz1rlYdVaVUhEgi2uc3F+4aAoDLCDwMc9WZH/Tvm7ffpmmgY89/WK3I0iBRiQuhi1ruQKeu/sdDr67kfu5DUve0zUBoAxKQAybIIHbyo46axdrvTFVYWPPzWRFIAuXZUcpJleJmZWAyl5PZdRKyycW1adoa12meyf3UUrnY/ZsqX2Q7l8TDSSVJ8dNFVLfl58fw7Cr9KFocsgu3aVj+mwaxasTKTBYbtuBAA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com; dkim=pass header.d=intel.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=intel.onmicrosoft.com; s=selector2-intel-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=1Y3fugPD3LXkMu5Y1jWYNvOgZYqYKqmVcppqJrpHEUo=; b=NnU2ZWSzWKzD2XOtHxtGqpRfNWzL5Fsh/A7/gjDz9xMnp3TGRLZxRF9MJGKOghie/z2AX79zoamOWjJmc7yoNB6iLJIi4Ic1s5AjBuuE0cM7f18VGmtEkL2d9vdclOUnZfkNA0csKKPUokkf6hUv7WdR1l42zRtgIAN786NX4FQ= Authentication-Results: intel.com; dkim=none (message not signed) header.d=none;intel.com; dmarc=none action=none header.from=intel.com; Received: from PH0PR11MB5000.namprd11.prod.outlook.com (2603:10b6:510:41::19) by PH0PR11MB4903.namprd11.prod.outlook.com (2603:10b6:510:36::6) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4352.25; Fri, 23 Jul 2021 12:04:05 +0000 Received: from PH0PR11MB5000.namprd11.prod.outlook.com ([fe80::bde5:66de:e755:c5bb]) by PH0PR11MB5000.namprd11.prod.outlook.com ([fe80::bde5:66de:e755:c5bb%5]) with mapi id 15.20.4352.029; Fri, 23 Jul 2021 12:04:05 +0000 To: Ajit Khaparde , Thomas Monjalon CC: Asaf Penso , "users@dpdk.org" , dpdk-dev , David Marchand , Bruce Richardson , Jerin Jacob Kollanukkaran , Akhil Goyal , Maxime Coquelin , Honnappa Nagarahalli , "Tu, Lijuan" References: <2236865.drsZmlonQt@thomas> From: Ferruh Yigit X-User: ferruhy Message-ID: Date: Fri, 23 Jul 2021 13:03:57 +0100 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit X-ClientProxiedBy: MW4PR04CA0050.namprd04.prod.outlook.com (2603:10b6:303:6a::25) To PH0PR11MB5000.namprd11.prod.outlook.com (2603:10b6:510:41::19) MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 Received: from [192.168.0.206] (37.228.236.146) by MW4PR04CA0050.namprd04.prod.outlook.com (2603:10b6:303:6a::25) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.4352.25 via Frontend Transport; Fri, 23 Jul 2021 12:04:01 +0000 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 0e4b614e-44d4-43cb-3d8e-08d94dd1f7cf X-MS-TrafficTypeDiagnostic: PH0PR11MB4903: X-LD-Processed: 46c98d88-e344-4ed4-8496-4ed7712e255d,ExtAddr X-MS-Exchange-Transport-Forked: True X-Microsoft-Antispam-PRVS: X-MS-Oob-TLC-OOBClassifiers: OLM:8273; X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: VyqkHH08uYiXc0Zy6voGrusblPzUigFPTEFInHvLqDkjQ1MrECJLGnU7EdPYYw2P72uKfUI0cwn53ebkGuo4YK0vlz/rDXAsySIOsOAeKerWkwOcnKFqx+rb6c1ztbFXrEw4Vw/5S7L09DfwNcGe3TWG9mvlam/4Z6rs/yxNTxgTyiIJFuhoMoDky90KuPyDrBmBnpaEStLZwo9r5XoNmQ9qvVT3a9/PBZc75R8uEX16ST4AuHeSjUJ0jZZihGjn2B9tGcYkgwq3SKZdWtDC0iYP5ZqRm+7QWVEYKGcJ68/T1xxM0s5qSavZDEB542bbUAU5yZsHU2VntyUlnBTMnrlAKx2HtptB/wlKThR5lnzaeuEOaOpKJG5/r9F0Sq5T7+xGETij1/eHVklV/GBx6SnH1F+xwpQ3WZzlwSm5AZATQHLFwxCYnP31bfBtNEwdHZQ/rzfIW4MR4+HXfXTrkLlNc2sjzhnkbd28XucSjvTdOumDYl1frBfguC+41mP8orwPrnbo9rpWjWJ0imNEXP0zRyCb9sXd5426qSkLxK+3S0qUf05UObbt21isgEl8ooqG5CNz7B47tzAfOQwLL+y79PzFj69SNqAlfEKatPjohD5WCR9H+WRlcbLoPYOPX3Z+KBCZEEj313/WtPy7I14aBwlIZJ0b6h1DKLmmOA9OcyDGdvaoJWqGC3aubDmEoz1NHa1xNDtFA5h5Rl7owA== X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:PH0PR11MB5000.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(366004)(346002)(136003)(39850400004)(396003)(376002)(8936002)(38100700002)(6486002)(83380400001)(6666004)(16576012)(316002)(53546011)(110136005)(54906003)(66556008)(66946007)(5660300002)(66476007)(31686004)(478600001)(8676002)(186003)(2616005)(44832011)(107886003)(31696002)(956004)(7416002)(36756003)(4326008)(86362001)(2906002)(26005)(45980500001); DIR:OUT; SFP:1102; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?utf-8?B?Ym5CZlZMUGpxcThLa2JnZ1AranNScEFqTmM1YmxZU25lQm5wSDA0akc1Y01w?= =?utf-8?B?YXcyeklKek8rc2lhUVJLUWZxbG5ibDA0Q1J0eTJ0ZGZHTmUrdEZyOXNNU0xs?= =?utf-8?B?ZlVLRFdhc2EyS1ZPSFR1dHM0dUpjNVdIa3JTc0Z6WWpNOXFPWTU3VndiN1VG?= =?utf-8?B?SUhuL0RUN2h1cDFad2JiSUs3czB0MmVobWxsdDF1aVMveTBoQlZydlYySkZh?= =?utf-8?B?RDVIZFR4dTk3QnFTSGhncDFLd0RZV01iVWdiaW1kYlFEckZ3aldZWGhRRjlm?= =?utf-8?B?YmRaZHk5YURxQWJRcDBNSy80SnBEQTl2T0MwWXFKTkp3WHV1MDV6bUJqZkNy?= =?utf-8?B?WnVxbXlZWTcwaGxxQ3pUZFBuNlhqZWpHUUJ6UlQzdWVUYnYwUFI5ZDVIYloy?= =?utf-8?B?K3o0VUd6ZHQ4RXdtK0RvM0duTHdZM3IvcDNpRlloelA4alR5QzBpVG1vNTl4?= =?utf-8?B?OHl0WHdUU2phelcrWUpXcnNKR1BsV2NQbDF3SGRLRWJqSDFsWTVpUXVoVVg5?= =?utf-8?B?bDJFbFNjMGZQMEpMLytrSUxET1EzNUo1aVgvelIwdTYwRUg4a0xlQktCc0pN?= =?utf-8?B?b3ZqMjVZRkJnY0FQVTUrSGc3a25ONGc5Wm15VmZYc3VpaUxaVHdCTml6QkFt?= =?utf-8?B?bkFBU1FVRTAxbEVTSDZUc1M3M0F1cVZGT09DRkVyYkthYktFTmVSWUdSUHl6?= =?utf-8?B?Z3RWK3NIdFBwYjV2MnQxV3AwdDdyUlFYcU1MZjFpTENQeUs1K3QvcUEwcDN5?= =?utf-8?B?MWlsTWpQS3pGQnhBWUt5aUdYalVUQnJ3cHRibWZha1hrTG9aY2ltUEY1dU1O?= =?utf-8?B?VjE1WGJSVjMrYWFKMFhYSVk0aTIrKy82bkNsRzArTkJ4NG1aTXBhbnNFUzV0?= =?utf-8?B?eWJoZ3o0OXNNdURjb25abnR1NVpVUUhyNlo4NmYrK05YSDhXenZVWHZ0MEMr?= =?utf-8?B?bTFLRG1qM1ZET0xlQ1VVbDFuWHM1SEE3L25xTzBDeGZzb0R4M1kxNzJ5NFRG?= =?utf-8?B?bXkwUDVhMHFMYlI4UXVsU2ZrQUs5clY2STZWRW1sYjRtSGE4dkFSRGVyRUd2?= =?utf-8?B?NmpVRHRsNnhMRVNhUEhzcGVvMnQ4WENweGZqOXhkWXk4akt2VlE4OWI5ZHZr?= =?utf-8?B?bDJDMVpmenlTdUxZZWlSSWdpYUdyQk94SWdTaThwNHdMczN0U0h4eVVOVFg1?= =?utf-8?B?Mm9uOFJFeWQxNnFTbjJOOHBiNDVCTnZ0WnIxSUVuL1M3cjJ3SUtUTTlKUUNw?= =?utf-8?B?cWFLVXl1TEFiTGZxSHpUZklUN2RqNGc3Nld5YUpPUXIrQlphTGVOK0pIRU5h?= =?utf-8?B?MzYyWU9UUGRFV2Y4czQ3cGczaTYyK1Q1WmhEbjdzQXhsUTl5NFlKVFFWSmND?= =?utf-8?B?TEJPWEtWSTR0dzRXQ1hCbFRoc2srN29iSnRCb1YvdU5YNXRsZlNDY1U1akhD?= =?utf-8?B?SjlsS0FGVDFGOXNaQUZQVEJwNk5PVzV4YVYwendQUnE3UU9YOU5sTzVGSXcv?= =?utf-8?B?WFVMaWtlR1luRlEyOEo1cHd0MXR6TnV3R0F4UGFiZitvWHFMRHZGbEN4NVJs?= =?utf-8?B?UkJxTEhFUDZWeFpXUlBLR3p0dHgzQVBIRzd1ZFhhMnJ5dmpzbEUyTUNjVVd2?= =?utf-8?B?eDBGakJvZUM3L3pFYXREQnQvMmtkWHNycHRMTnBmVVh6YlkvVEtaVnlGd0Q5?= =?utf-8?B?dExBcXVuUW5Pai95OFNHTG12SmpML3NYZnFNcEpTNU1oc1VCN1EvNGIrYkgx?= =?utf-8?Q?gD0xQDXpnbcGpmPvV+o819wcRBb5LJT5hEzGhSz?= X-MS-Exchange-CrossTenant-Network-Message-Id: 0e4b614e-44d4-43cb-3d8e-08d94dd1f7cf X-MS-Exchange-CrossTenant-AuthSource: PH0PR11MB5000.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 23 Jul 2021 12:04:05.1679 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: SboYN/zGizd6JOLxrEwkRdL6NZ3bjsHKP8G10rPSkzqZm0Ir26CQ+vyxmogqMP7DdCAukcupg5GypgSRPswwcA== X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR11MB4903 X-OriginatorOrg: intel.com Subject: Re: [dpdk-users] [DISCUSSION] code snippet documentation X-BeenThere: users@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK usage discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: users-bounces@dpdk.org Sender: "users" On 7/23/2021 1:02 AM, Ajit Khaparde wrote: > On Thu, Jul 22, 2021 at 1:29 PM Thomas Monjalon wrote: >> >> 15/07/2021 09:01, Asaf Penso: >>> Hello DPDK community, >>> >>> I would like to bring up a discussion about a way to have code snippets as an example for proper usage. >>> The DPDK tree is filled with great pieces of code that are well documented and maintained in high quality. >>> I feel we are a bit behind when we talk about usage examples. >>> >>> One way, whenever we implement a new feature, is to extend one of the test-* under the "app" folder. >>> This, however, provides means to test but doesn't provide a good usage example. >>> >>> Another way is to check the content of the "example" folder and whenever we have a BIG new feature it seems like a good place. >>> This, however, doesn't provide a good option when we talk about small features. >>> If, for example, we extend rte_flow with an extra action then providing a full-blown example application is somewhat an entry barrier. >>> >>> A third option could be to document it in one of the .rst files we have. >>> Obviously, this requires high maintenance and no option to assure it still compiles. >>> >>> I'd like to propose another approach that will address the main two issues: remove the entry barrier and assure compilation. >>> In this approach, inside the "examples" folder we'll create another folder for "snippets". >>> Inside "snippets" we'll have several files per category, for example, rte_flow_snippets.c >>> Each .c file will include a main function that calls the different use cases we want to give as an example. >>> The purpose is not to generate traffic nor read rx/tx packets from the DPDK ports. >>> The purpose is to have a good example that compiles properly. >>> >>> Taking the rte_flow_snippets.c as an example its main function would look like this: >>> >>> int >>> main(int argc, char **argv) >>> { >>> rte_flow_snippet_match_5tuple_and_drop(); >>> rte_flow_snippet_match_geneve_ope_and_rss(); >>> ... >>> Return 0; >>> } >> >> I think we need to have a policy or justification about which snippet >> is worth to have. >> My thought is to avoid creating snippets which have no other value >> than showing a function call. >> I think there is a value if the context is not simple. > > I agree. Otherwise it will be cluttered with snippets. > I sometimes use DTS code as sample for an API, that has limited context (which I believe sometimes needed to understand API properly) and of course compiles fine. What about making mandatory to add a test to DTS for each API/feature, that ensures a reasonable sample for the API call. And if the intent is just to provide sample for API call without context, I believe test-* can help on that, it clarifies good & bad input for an API. >> >> >> Please could you provide a more complex example? >> >>