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 64479A034C; Wed, 22 Jun 2022 22:53:03 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 0925F4069C; Wed, 22 Jun 2022 22:53:03 +0200 (CEST) Received: from mail-pl1-f169.google.com (mail-pl1-f169.google.com [209.85.214.169]) by mails.dpdk.org (Postfix) with ESMTP id 05AA2400D6 for ; Wed, 22 Jun 2022 22:53:02 +0200 (CEST) Received: by mail-pl1-f169.google.com with SMTP id jb13so2803345plb.9 for ; Wed, 22 Jun 2022 13:53:01 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20210112.gappssmtp.com; s=20210112; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=c8q61s8fal2D4syouMqUNJN7pzdT4Rd09pfE4HevjMw=; b=WCeQo0ko1O/EBanJ4blEEK3xQbTa0rrHH/bXQphKQodoszuZmAO4tbxMYVg0lRt0GP i2BY0FT73LY9ZzNYGdZnedWQd8nQ3N6JoBEMzpcRfy7PNl7Kz//3rcBcz0Qb9oSvLDFE ITcbmXw9ZnFlWIJ3oZTSD6RwmV+c/lhtOAhPJ+BRRRc6bWjEfc0s/kvEajFL7mtLq5fo Fh0UqYq1D4Uu/2FPM9CAUBBSA2wHM7QTXW7emUo4J2T99rRyatqDk9DJxHj4+BB7CMJn 2L7TWNLyXSU7wjejI4vqkoe+QKhTTEeHL7arqzXlLHsATdA3A1RZAQyOIVEfoRGGgo3s Zgpw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=c8q61s8fal2D4syouMqUNJN7pzdT4Rd09pfE4HevjMw=; b=4i+kPMREbo6ufric+KlmfsJXnd015iT4K6HQBMPgcJXz5Rx0MuNYF+hId5v7eEx6Zm U5NuFDVtmDoZf7hVxnxlPOy7/B32UBcSQWMPDfqpCw8KNcsFLJKMM3embrAQ/g3zDFnu 54hqfT26gqSWocgyX7BNcc9zNOv3Ub1UvzOuDeTmG3Tn0GnQOT6aVs86wyEXymTIMqrx M3MLl1UqAMLaIOgx0XAFZSX1+s0zfObB0TVue4Zk0HZDcfxpvveVar3i07CpNM2SXCBR mEDLttbNUQhVcYYbNj+XkXKJQrTQk/rZNiRIfMLNTA6nlw14OmJjY1mJlFhdL1MCyFR/ HkOQ== X-Gm-Message-State: AJIora9p09bF6MKTNLZ+EOgWZVoIaf6XDHqueb735em15rov+weFAULN AvzSrEDVytyAsRSIci6aCSd+HkTSsVmpwRAw X-Google-Smtp-Source: AGRyM1uJCsMKnzHHVx4xpRalfMwBY8iJ9BRSGRmcwc9dAJtPf87g44XRM3Z+q7x7jU1US0/1nrGzyg== X-Received: by 2002:a17:903:240e:b0:168:ea13:f9e0 with SMTP id e14-20020a170903240e00b00168ea13f9e0mr36249543plo.6.1655931180830; Wed, 22 Jun 2022 13:53:00 -0700 (PDT) Received: from hermes.local (204-195-112-199.wavecable.com. [204.195.112.199]) by smtp.gmail.com with ESMTPSA id jj4-20020a170903048400b001678898ad06sm7239999plb.47.2022.06.22.13.52.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Jun 2022 13:53:00 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger , Fan Zhang , Ashish Gupta , Akhil Goyal , Harman Kalra , Byron Marohn , Yipeng Wang , Jerin Jacob , Vladimir Medvedkin , Sameh Gobriel , Reshma Pattan , Cristian Dumitrescu , Jasvinder Singh , Olivier Matz , Ciara Power Subject: [PATCH v4] lib: document existing free functions Date: Wed, 22 Jun 2022 13:52:57 -0700 Message-Id: <20220622205257.404945-1-stephen@networkplumber.org> X-Mailer: git-send-email 2.35.1 In-Reply-To: <20220220182147.9750-1-stephen@networkplumber.org> References: <20220220182147.9750-1-stephen@networkplumber.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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 Make sure all functions which use the convention that XXX_free(NULL) is a nop are all documented. The wording is chosen to match the documentation of free(3). "If ptr is NULL, no operation is performed." Signed-off-by: Stephen Hemminger --- lib/bitratestats/rte_bitrate.h | 1 + lib/compressdev/rte_comp.h | 3 ++- lib/cryptodev/rte_crypto.h | 4 +++- lib/eal/include/rte_interrupts.h | 3 ++- lib/efd/rte_efd.h | 3 ++- lib/eventdev/rte_event_ring.h | 3 ++- lib/fib/rte_fib.h | 3 ++- lib/fib/rte_fib6.h | 3 ++- lib/member/rte_member.h | 1 + lib/reorder/rte_reorder.h | 3 ++- lib/rib/rte_rib.h | 3 ++- lib/rib/rte_rib6.h | 3 ++- lib/sched/rte_sched.h | 3 ++- lib/stack/rte_stack.h | 3 ++- lib/telemetry/rte_telemetry.h | 2 +- 15 files changed, 28 insertions(+), 13 deletions(-) diff --git a/lib/bitratestats/rte_bitrate.h b/lib/bitratestats/rte_bitrate.h index e494389b95a0..35cb44be1b7d 100644 --- a/lib/bitratestats/rte_bitrate.h +++ b/lib/bitratestats/rte_bitrate.h @@ -32,6 +32,7 @@ struct rte_stats_bitrates *rte_stats_bitrate_create(void); * * @param bitrate_data * Pointer allocated by rte_stats_bitrate_create() + * If pointer is NULL, no operation is performed. */ void rte_stats_bitrate_free(struct rte_stats_bitrates *bitrate_data); diff --git a/lib/compressdev/rte_comp.h b/lib/compressdev/rte_comp.h index cdb55e5887d3..8cc60bf9e898 100644 --- a/lib/compressdev/rte_comp.h +++ b/lib/compressdev/rte_comp.h @@ -469,7 +469,8 @@ rte_comp_op_bulk_alloc(struct rte_mempool *mempool, * be returned to the mempool. * * @param op - * Compress operation + * Compress operation pointer allocated from rte_comp_op_alloc() + * If pointer is NULL, no operation is performed. */ __rte_experimental void diff --git a/lib/cryptodev/rte_crypto.h b/lib/cryptodev/rte_crypto.h index aeb3bf6e383a..e03bbeceddef 100644 --- a/lib/cryptodev/rte_crypto.h +++ b/lib/cryptodev/rte_crypto.h @@ -347,7 +347,9 @@ __rte_crypto_op_get_priv_data(struct rte_crypto_op *op, uint32_t size) * If operation has been allocate from a rte_mempool, then the operation will * be returned to the mempool. * - * @param op symmetric crypto operation + * @param op + * Pointer to symmetric crypto operation allocated with rte_crypto_op_alloc() + * If pointer is NULL, no operation is performed. */ static inline void rte_crypto_op_free(struct rte_crypto_op *op) diff --git a/lib/eal/include/rte_interrupts.h b/lib/eal/include/rte_interrupts.h index 68ad19c3e742..4361ecc565d3 100644 --- a/lib/eal/include/rte_interrupts.h +++ b/lib/eal/include/rte_interrupts.h @@ -242,7 +242,8 @@ rte_intr_instance_alloc(uint32_t flags); * Free the memory allocated for interrupt handle resources. * * @param intr_handle - * Interrupt handle address. + * Interrupt handle allocated with rte_intr_instance_alloc(). + * If handle is NULL, no operation is performed. * */ __rte_experimental diff --git a/lib/efd/rte_efd.h b/lib/efd/rte_efd.h index d3d7befd0c90..b4ef783b8783 100644 --- a/lib/efd/rte_efd.h +++ b/lib/efd/rte_efd.h @@ -145,7 +145,8 @@ rte_efd_create(const char *name, uint32_t max_num_rules, uint32_t key_len, * Releases the resources from an EFD table * * @param table - * Table to free + * Pointer to table allocated with rte_efd_create(). + * If pointer is NULL, no operation is performed. */ void rte_efd_free(struct rte_efd_table *table); diff --git a/lib/eventdev/rte_event_ring.h b/lib/eventdev/rte_event_ring.h index 0101cc0aa232..34abe8d51831 100644 --- a/lib/eventdev/rte_event_ring.h +++ b/lib/eventdev/rte_event_ring.h @@ -234,7 +234,8 @@ rte_event_ring_lookup(const char *name); * De-allocate all memory used by the ring. * * @param r - * Ring to free + * Pointer to ring to created with rte_event_ring_create(). + * If pointer is NULL, no operation is performed. */ void rte_event_ring_free(struct rte_event_ring *r); diff --git a/lib/fib/rte_fib.h b/lib/fib/rte_fib.h index 90f28b7e11ad..29d99105dcc5 100644 --- a/lib/fib/rte_fib.h +++ b/lib/fib/rte_fib.h @@ -122,7 +122,8 @@ rte_fib_find_existing(const char *name); * Free an FIB object. * * @param fib - * FIB object handle + * FIB object handle created by rte_fib_create(). + * If handle is NULL, no operation is performed. * @return * None */ diff --git a/lib/fib/rte_fib6.h b/lib/fib/rte_fib6.h index 62a425d9afe2..a9a02257ee5c 100644 --- a/lib/fib/rte_fib6.h +++ b/lib/fib/rte_fib6.h @@ -113,7 +113,8 @@ rte_fib6_find_existing(const char *name); * Free an FIB object. * * @param fib - * FIB object handle + * FIB object handle created by rte_fib6_create(). + * If handle is NULL, no operation is performed. * @return * None */ diff --git a/lib/member/rte_member.h b/lib/member/rte_member.h index 567ee0c84bd9..41c730ba76a3 100644 --- a/lib/member/rte_member.h +++ b/lib/member/rte_member.h @@ -443,6 +443,7 @@ rte_member_add(const struct rte_member_setsum *setsum, const void *key, * * @param setsum * Pointer to the set summary. + * If pointer is NULL, no operation is performed. */ void rte_member_free(struct rte_member_setsum *setsum); diff --git a/lib/reorder/rte_reorder.h b/lib/reorder/rte_reorder.h index 9de02403746b..4dedc36b8a80 100644 --- a/lib/reorder/rte_reorder.h +++ b/lib/reorder/rte_reorder.h @@ -114,7 +114,8 @@ rte_reorder_reset(struct rte_reorder_buffer *b); * Free reorder buffer instance. * * @param b - * reorder buffer instance + * Pointer to reorder buffer instance. + * If pointer is NULL, no operation is performed. * @return * None */ diff --git a/lib/rib/rte_rib.h b/lib/rib/rte_rib.h index c18c4ca594c1..7c3d0997244f 100644 --- a/lib/rib/rte_rib.h +++ b/lib/rib/rte_rib.h @@ -263,7 +263,8 @@ rte_rib_find_existing(const char *name); * Free an RIB object. * * @param rib - * RIB object handle + * RIB object handle created with rte_rib_create(). + * If handle is NULL, no operation is performed. * @return * None */ diff --git a/lib/rib/rte_rib6.h b/lib/rib/rte_rib6.h index fa8e9bf7327b..64301776b51f 100644 --- a/lib/rib/rte_rib6.h +++ b/lib/rib/rte_rib6.h @@ -318,7 +318,8 @@ rte_rib6_find_existing(const char *name); * Free an RIB object. * * @param rib - * RIB object handle + * RIB object handle created with rte_rib6_create(). + * If handle is NULL, no operation is performed. * @return * None */ diff --git a/lib/sched/rte_sched.h b/lib/sched/rte_sched.h index 0bd5b72a4a7a..0ba4ef6dec01 100644 --- a/lib/sched/rte_sched.h +++ b/lib/sched/rte_sched.h @@ -328,7 +328,8 @@ rte_sched_port_config(struct rte_sched_port_params *params); * Hierarchical scheduler port free * * @param port - * Handle to port scheduler instance + * Handle to port scheduler instance. + * If handle is NULL, no operation is performed. */ void rte_sched_port_free(struct rte_sched_port *port); diff --git a/lib/stack/rte_stack.h b/lib/stack/rte_stack.h index 91fc5707670f..33ea451223e5 100644 --- a/lib/stack/rte_stack.h +++ b/lib/stack/rte_stack.h @@ -213,7 +213,8 @@ rte_stack_create(const char *name, unsigned int count, int socket_id, * Free all memory used by the stack. * * @param s - * Stack to free + * Pointer to stack created with rte_stack_create(). + * If pointer is NULL, no operation is performed. */ void rte_stack_free(struct rte_stack *s); diff --git a/lib/telemetry/rte_telemetry.h b/lib/telemetry/rte_telemetry.h index 3372b32f38b5..a49a6d1e571b 100644 --- a/lib/telemetry/rte_telemetry.h +++ b/lib/telemetry/rte_telemetry.h @@ -293,7 +293,7 @@ rte_tel_data_alloc(void); * * @param data * Pointer to container. - *. + * If pointer is NULL, no operation is performed. */ void rte_tel_data_free(struct rte_tel_data *data); -- 2.35.1