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 1784443A4F; Fri, 2 Feb 2024 12:20:34 +0100 (CET) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 02406402BF; Fri, 2 Feb 2024 12:20:34 +0100 (CET) Received: from mgamail.intel.com (mgamail.intel.com [192.198.163.18]) by mails.dpdk.org (Postfix) with ESMTP id 5DAAE4026E for ; Fri, 2 Feb 2024 12:20:32 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=intel.com; i=@intel.com; q=dns/txt; s=Intel; t=1706872832; x=1738408832; h=date:from:to:cc:subject:message-id:references: content-transfer-encoding:in-reply-to:mime-version; bh=FzT0DPRDWZzr6MvOpmmxn0Es75HFokx2vpnEi65KVlc=; b=a53Q7Q+zJqqiPwxlKDq8PBVeTpvpCr9wR6rKbLvnmw9gAA7j4wiYp3fr +9ztFz6JQEXcPbHXvXIp14TbORLXmMmOTb9EusvZ7XKu/4jVCqV+kHawg wVdaVMLMvzRnMCNlXRg/cUzlpVmDlS3tDU2GFKANTWTaLo+IAwijz8uxu 6VWQ0JxMArU40VcAmwiHmHrNmZ35lVaP5eiHxOP6sx6QMTsJh/RahltHh r+tlUx5aWcYPQ/wijCezgVmxT/iG2lyiVyG8XSdoAFZtFGVGLGUELyA6r lN3eOEdJR6XBtVa7oFv2Wxsocd+uNIEI1bqoQOlMzjPTfFIK36wW3YlLp A==; X-IronPort-AV: E=McAfee;i="6600,9927,10971"; a="42284" X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="42284" Received: from orviesa007.jf.intel.com ([10.64.159.147]) by fmvoesa112.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 02 Feb 2024 03:20:31 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="6.05,238,1701158400"; d="scan'208";a="362449" Received: from orsmsx601.amr.corp.intel.com ([10.22.229.14]) by orviesa007.jf.intel.com with ESMTP/TLS/AES256-GCM-SHA384; 02 Feb 2024 03:20:31 -0800 Received: from orsmsx612.amr.corp.intel.com (10.22.229.25) by ORSMSX601.amr.corp.intel.com (10.22.229.14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35; Fri, 2 Feb 2024 03:20:30 -0800 Received: from orsmsx610.amr.corp.intel.com (10.22.229.23) by ORSMSX612.amr.corp.intel.com (10.22.229.25) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35; Fri, 2 Feb 2024 03:20:30 -0800 Received: from orsedg603.ED.cps.intel.com (10.7.248.4) by orsmsx610.amr.corp.intel.com (10.22.229.23) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.2507.35 via Frontend Transport; Fri, 2 Feb 2024 03:20:30 -0800 Received: from NAM10-MW2-obe.outbound.protection.outlook.com (104.47.55.100) by edgegateway.intel.com (134.134.137.100) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.2507.35; Fri, 2 Feb 2024 03:20:29 -0800 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=MT9BDAtpxt8KJf5pED23MWDINEd4Zr84ztDz9v/r6LWhKMwxPE5d6Rgc2JVABlw4LJdROn1vbJNdY92ManXtv8hOZlftwWB9uGB9A0G3rlKCBCHQZ3cXtU56HjxlJys9LthODiA+LRjG/0OCrQfmbo2wR0S69HUHFSM3ZvVg8/SHYVkK+qGG+X+seBmTkb45bDPRP5CMon8UuVGiM0HIg/85WB1S5heWBrsWowkLvY8VyFLz//OFaUt6FZ+H2wut+Kzy0J37MTrp3qcMXhKXs70BRjd8AqU7fACAiNxx1S3NNqEL8ctqwt2F8GQfnc7FeQ6P221v6s96cLUPlJvv2g== 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-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=bdU14awI/43IlxWkUfrXNFsxBAt14PR60+3jlDkuAa4=; b=Zh0Tyf8lKS36TGEPt3B3Lj4SekegaRgRwxf12YtOTf/j/ZLL4BEbX9ca34oQVGerKafEle/pkCyGRPsCjxExwIka7Qyi+DJ93DStM90gn6l7RhpIpArhkfCvx6EDGZocIMgp00CpQIxbBo2eRcLsNeHzDdT+S+5Ky7GBI2hejQkHz6haowquA6CTCDIqt7DXzrrjKmG/svi9V0Iefpm3AJg2IgRYkAwIZFJV66wx0Bek2f5AyG01XTXJYec5zfXre/Mqp/Ki3LO87b/TI8WQUsVBPNj8XsMS4KW2NqUKmbaNrPK/9DLQxeegjSbRc0/9X85YW9SXzKkg1lSsAmGFOg== 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 Authentication-Results: dkim=none (message not signed) header.d=none;dmarc=none action=none header.from=intel.com; Received: from DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) by PH0PR11MB7613.namprd11.prod.outlook.com (2603:10b6:510:285::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7249.29; Fri, 2 Feb 2024 11:20:22 +0000 Received: from DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::df88:b743:97f8:516c]) by DS0PR11MB7309.namprd11.prod.outlook.com ([fe80::df88:b743:97f8:516c%5]) with mapi id 15.20.7249.027; Fri, 2 Feb 2024 11:20:22 +0000 Date: Fri, 2 Feb 2024 11:20:17 +0000 From: Bruce Richardson To: Mattias =?iso-8859-1?Q?R=F6nnblom?= CC: , , , , , , , Subject: Re: [PATCH v2 03/11] eventdev: update documentation on device capability flags Message-ID: References: <20240118134557.73172-1-bruce.richardson@intel.com> <20240119174346.108905-1-bruce.richardson@intel.com> <20240119174346.108905-4-bruce.richardson@intel.com> <93bed273-2ea3-48fe-adaa-0a546ab03730@lysator.liu.se> <3a6523f4-d95c-4862-b198-1d3dada69478@lysator.liu.se> Content-Type: text/plain; charset="iso-8859-1" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <3a6523f4-d95c-4862-b198-1d3dada69478@lysator.liu.se> X-ClientProxiedBy: DU2P251CA0026.EURP251.PROD.OUTLOOK.COM (2603:10a6:10:230::28) To DS0PR11MB7309.namprd11.prod.outlook.com (2603:10b6:8:13e::17) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: DS0PR11MB7309:EE_|PH0PR11MB7613:EE_ X-MS-Office365-Filtering-Correlation-Id: 07a737dc-eda1-4337-cb26-08dc23e0f1e3 X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: go9PXD9C0KhKrp9muuXgMPtZZsyEEf+wE/rKSfBQbAs9v5eitru+oeaLFOU8Z3ls53DmMu+3dHdpL3PVNIXJ7P4Y097NzbhLA9iPTM5cHgDf9cLbEVQp4nCnVwmtySrYRqfr8HLwVmedriYJTHwm7igVFrt4v+AX+OYG6PQqy8d6Q686CH5jolQYkekbo9h/aUbbI3QSlIDEarP0e0NhqzN+USlYNtoyRBq8HGrofpnf/mIbjdlcoSv3/cPvTRGK68sBZYDIRR+MnQX2PicGGvn6v7PzeSpTMP7K4SiiZMTrXhS4SYg2woCQgXoWb/GrYwnvMMx3343DBiznUBSLJavgbAqlSFJks+lBBknx/HhOl6XjyzVFwniK5Gq9B8J9EYY6KqURIAyw4U9lsCgjajbuiAHCDMPnJ6DtLa4PS5id3WYLS+mYUzyN44MipD5egJcO8RcrpV+7sCg75oIRaLMQ/JVi3WWrpQ1HBbBkjdxyywduOLle4JGKAGOho1ySDopp3P/vuORBEnTgKCp4u7Uwp7jf2HY9iyJF1dKWowpJvmK7ukiLD3Ng2bpUtEbl X-Forefront-Antispam-Report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DS0PR11MB7309.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(13230031)(366004)(346002)(136003)(39860400002)(376002)(396003)(230922051799003)(451199024)(64100799003)(186009)(1800799012)(83380400001)(26005)(107886003)(6512007)(38100700002)(66574015)(4326008)(5660300002)(8936002)(15650500001)(8676002)(44832011)(478600001)(6486002)(6506007)(6666004)(2906002)(53546011)(66946007)(296002)(316002)(6916009)(66476007)(66556008)(41300700001)(86362001)(82960400001); DIR:OUT; SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?iso-8859-1?Q?O707bmniBjnp5D8wVEAQ8WKoTgAUb2NKRKYoDi469Wq8UDaxCVQENuWVIp?= =?iso-8859-1?Q?VrsdKSZqVrdWAPAmpbngcTdn9H/3YKRjSRqJDwCj92R/SM7DpwruDoICFI?= =?iso-8859-1?Q?OO1NT+F6LwaPGPcxlWjYut5921bvIw8U06Iui89tLyK94q4BlnP63Ry5VI?= =?iso-8859-1?Q?udYVO0/3v+tyjmDplMTUT5qHMB2nJgIhSf4VO5/yS2PDw6+w/ZMRTg99f3?= =?iso-8859-1?Q?qYWnk2Tk0DwWpY6xSxTkApS0rax3SvI7CNI/7tEi7HuF1SOweX8PyYTyRh?= =?iso-8859-1?Q?9WiYuzlHX+z2EfT5m68ARqL4qkJFymTj7j0n5NNYI9Nben2wur205GfzAB?= =?iso-8859-1?Q?Wbmpg33YCDIeOKpYz1r08flMgS54OzDG7gB0p2W2T0yleUkjvX4Ulm4mTV?= =?iso-8859-1?Q?Uvplq1Fg8+05cZwypxdUqziHGfRlxwQKNQ+LNNDB5cvSnlaRtru2F4jwEO?= =?iso-8859-1?Q?gUSBrvQbHfYlI0sljhAOSR25RbhGRpmF9cmFpYeVRbzYsXXecxeoD/UQxl?= =?iso-8859-1?Q?u2PQpnJSXfugvHAHnHpadaQsPeK/tmK63Cinwu9VBWjjab0x4235xFkoOh?= =?iso-8859-1?Q?EcWheloS+aXI0Ddu/bJmwut01CFNYpFUeJXL93TPAUrCtPS4rnrlQM2GBq?= =?iso-8859-1?Q?02sdLr6kHjRBXr17Z0L+GObuffpbzzuRVxBNdyrurNta1RLnTs+gbL7rbE?= =?iso-8859-1?Q?4xuR7zX8Eja0OFjYAKqX1ChDPPyNBUziexeIyiyF3+EdX0QvV7f4n+5qI/?= =?iso-8859-1?Q?6OTMC19fOcu6iS9QfzxBhV899qzMHoiAysj3gC1PJYy9iLfhdivO9D9ZnL?= =?iso-8859-1?Q?Sd7fF08iK9rOqSOBjAKERF84GO5EADU91rg0e3yKayPXg80grTwoKNixpF?= =?iso-8859-1?Q?QAF3f2W7JrLjnt4DhQ1CjtJmknAhCPMO5kLRuS768x8xUlKEjC5ryk5rVM?= =?iso-8859-1?Q?lTHiJw1S+encZOWbrXCeXNsrpF7sk0nw3+jU4ARETWxci4QEJp0B7Mr0Or?= =?iso-8859-1?Q?2j9bfM56vbeOz7CDub4mfpm/sN0h/ygsIAH4B9sRYqdKOv+qGTYDeN+KK+?= =?iso-8859-1?Q?biPJc/DLCR1/4ROoWZ1VlWGMy/Vfv2qSCbF4NS6ZRc6U7FjIl1Uh6nnOx3?= =?iso-8859-1?Q?JvJsEM4JBiVUB2TjDu+ZNdd4fkaLjwVG/WanN9kxsECUzy2A6FoK8bv3Va?= =?iso-8859-1?Q?ftOqFknfwAWck02wvglHg6A7a9zTfXrw487LmtXWFiNtx20dOvX7F1fNAb?= =?iso-8859-1?Q?u+2o6JaQINiPLxKxDcsqM+Q0c9MxOU6a4lRF/bZvP90mObx3Y1qcvGYPSi?= =?iso-8859-1?Q?sgpxtLbiAV7EKQn8Hm/1Y/ZXgWb8HEZG11SogXZXHR1JHOOiIKrjE6vN8S?= =?iso-8859-1?Q?W/uPjwDEP0ohGlbhq32HYvcCs+p5ljlXnrfiPJSV6qZfhoIlT5f+kkyW+A?= =?iso-8859-1?Q?3Yd2QeD6ZMVWbm4yZbQBmyv/h96Z80ayYvtmIL6mN6+J6B7qOmzFL+JsC7?= =?iso-8859-1?Q?RmfiBZ3TMcyDqwTiDcLqsRMrFGQlMPCdP/mwbklSIPUPSGKEp7z0eP6kNe?= =?iso-8859-1?Q?MLt/hwWe6rKjUpcUVcZXlD8lQAyBgwXqLbxYRP4ncFvN6kRIZPibzWSfAs?= =?iso-8859-1?Q?bApbOJwHsr7DP7n0GRdiT7XFrqw9pBG71I0Q2YBjML0Jn8fGhNTZIJ3w?= =?iso-8859-1?Q?=3D=3D?= X-MS-Exchange-CrossTenant-Network-Message-Id: 07a737dc-eda1-4337-cb26-08dc23e0f1e3 X-MS-Exchange-CrossTenant-AuthSource: DS0PR11MB7309.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 02 Feb 2024 11:20:21.9044 (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: 1/4QjMY5UjMAnvMB6IMPw9oNSjAnuZ1eTsTCg2nxMOpElFC4fNkX1MxtLYvYaGe8YCBit9KchVJtYytE4sLWtwH7FVl6QA95fV/1DPvEwPQ= X-MS-Exchange-Transport-CrossTenantHeadersStamped: PH0PR11MB7613 X-OriginatorOrg: intel.com X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org On Fri, Feb 02, 2024 at 09:58:25AM +0100, Mattias Rönnblom wrote: > On 2024-01-31 15:09, Bruce Richardson wrote: > > On Tue, Jan 23, 2024 at 10:18:53AM +0100, Mattias Rönnblom wrote: > > > On 2024-01-19 18:43, Bruce Richardson wrote: > > > > Update the device capability docs, to: > > > > > > > > * include more cross-references > > > > * split longer text into paragraphs, in most cases with each flag having > > > > a single-line summary at the start of the doc block > > > > * general comment rewording and clarification as appropriate > > > > > > > > Signed-off-by: Bruce Richardson > > > > --- > > > > lib/eventdev/rte_eventdev.h | 130 ++++++++++++++++++++++++++---------- > > > > 1 file changed, 93 insertions(+), 37 deletions(-) > > > > > > > > > > * If this capability is not set, the queue only supports events of the > > > > - * *RTE_SCHED_TYPE_* type that it was created with. > > > > + * *RTE_SCHED_TYPE_* type that it was created with. > > > > + * Any events of other types scheduled to the queue will handled in an > > > > + * implementation-dependent manner. They may be dropped by the > > > > + * event device, or enqueued with the scheduling type adjusted to the > > > > + * correct/supported value. > > > > > > Having the application setting sched_type when it was already set on a the > > > level of the queue never made sense to me. > > > > > > I can't see any reasons why this field shouldn't be ignored by the event > > > device on non-RTE_EVENT_QUEUE_CFG_ALL_TYPES queues. > > > > > > If the behavior is indeed undefined, I think it's better to just say > > > "undefined" rather than the above speculation. > > > > > > > Updating in v3 to just say it's undefined. > > > > > > * > > > > - * @see RTE_SCHED_TYPE_* values > > > > > > #define RTE_EVENT_DEV_CAP_RUNTIME_QUEUE_ATTR (1ULL << 11) > > > > /**< Event device is capable of changing the queue attributes at runtime i.e > > > > - * after rte_event_queue_setup() or rte_event_start() call sequence. If this > > > > - * flag is not set, eventdev queue attributes can only be configured during > > > > + * after rte_event_queue_setup() or rte_event_dev_start() call sequence. > > > > + * > > > > + * If this flag is not set, eventdev queue attributes can only be configured during > > > > * rte_event_queue_setup(). > > > > > > "event queue" or just "queue". > > > > > Ack. > > > > > > + * > > > > + * @see rte_event_queue_setup > > > > */ > > > > #define RTE_EVENT_DEV_CAP_PROFILE_LINK (1ULL << 12) > > > > -/**< Event device is capable of supporting multiple link profiles per event port > > > > - * i.e., the value of `rte_event_dev_info::max_profiles_per_port` is greater > > > > - * than one. > > > > +/**< Event device is capable of supporting multiple link profiles per event port. > > > > + * > > > > + * > > > > + * When set, the value of `rte_event_dev_info::max_profiles_per_port` is greater > > > > + * than one, and multiple profiles may be configured and then switched at runtime. > > > > + * If not set, only a single profile may be configured, which may itself be > > > > + * runtime adjustable (if @ref RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK is set). > > > > + * > > > > + * @see rte_event_port_profile_links_set rte_event_port_profile_links_get > > > > + * @see rte_event_port_profile_switch > > > > + * @see RTE_EVENT_DEV_CAP_RUNTIME_PORT_LINK > > > > */ > > > > /* Event device priority levels */ > > > > #define RTE_EVENT_DEV_PRIORITY_HIGHEST 0 > > > > -/**< Highest priority expressed across eventdev subsystem > > > > +/**< Highest priority expressed across eventdev subsystem. > > > > > > "The highest priority an event device may support." > > > or > > > "The highest priority any event device may support." > > > > > > Maybe this is a further improvement, beyond punctuation? "across eventdev > > > subsystem" sounds awkward. > > > > > > > Still not very clear. Talking about device support implies that its > > possible some devices may not support it. How about: > > > "highest priority level for events and queues". > > > > Sounds good. I guess it's totally, 100% obvious highest means most urgent? > > Otherwise, "highest (i.e., most urgent) priority level for events queues" I think it's clear enough that highest priority is most urgent.