| Message ID | 20240426042851.333269-1-pvorel@suse.cz |
|---|---|
| State | Accepted |
| Headers | show |
| Series | [1/1] doc: libltpswap: Add kerneldoc | expand |
Hi! On 4/26/24 06:28, Petr Vorel wrote: > Signed-off-by: Petr Vorel <pvorel@suse.cz> > --- > doc/developers/api_c_tests.rst | 4 +++ > include/libswap.h | 61 +++++++++++++++++++++++++++------- > 2 files changed, 53 insertions(+), 12 deletions(-) > > diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst > index 2c0c8419d..ec53ab33c 100644 > --- a/doc/developers/api_c_tests.rst > +++ b/doc/developers/api_c_tests.rst > @@ -31,3 +31,7 @@ Capabilities > ------------ > > .. kernel-doc:: ../../include/tst_capability.h > + > +libltpswap > +---------- > +.. kernel-doc:: ../../include/libswap.h > diff --git a/include/libswap.h b/include/libswap.h > index f757073cc..681849166 100644 > --- a/include/libswap.h > +++ b/include/libswap.h > @@ -1,11 +1,12 @@ > // SPDX-License-Identifier: GPL-2.0-or-later > /* > * Copyright (c) 2013 Oracle and/or its affiliates. All Rights Reserved. > + * Copyright (c) Linux Test Project, 2021-2024 > * Author: Stanislav Kholmanskikh <stanislav.kholmanskikh@oracle.com> > */ > > /* > - * Contains common content for all swapon/swapoff tests > + * Contains common content for all swapon/swapoff tests. > */ > > #ifndef __LIBSWAP_H__ > @@ -27,60 +28,96 @@ int make_swapfile(const char *file, const int lineno, > #define MINIMAL_SWAP_SIZE_MB 1 > > /** > - * Macro to create minimal swapfile. > + * MAKE_SMALL_SWAPFILE - create small swap file. > + * > + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. "small small" sounds weird. Maybe "really small" > + * > + * @swapfile: swap filename. > */ > #define MAKE_SMALL_SWAPFILE(swapfile) \ > make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, 0, \ > SWAPFILE_BY_SIZE) > > /** > - * Macro to create minimal swapfile. > + * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version). > + * > + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. > * Includes safety checks to handle potential errors. Same here > + * > + * @swapfile: swap filename. > */ > #define SAFE_MAKE_SMALL_SWAPFILE(swapfile) \ > make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, 1, \ > SWAPFILE_BY_SIZE) > > /** > - * Macro to create swapfile size in megabytes (MB). > + * MAKE_SWAPFILE_SIZE - create swap file (MB). > + * > + * Macro to create swap file, size specified in megabytes (MB). > + * > + * @swapfile: swap filename. > + * @size: swap size in MB. > */ > #define MAKE_SWAPFILE_SIZE(swapfile, size) \ > make_swapfile(__FILE__, __LINE__, swapfile, size, 0, SWAPFILE_BY_SIZE) > > /** > - * Macro to create swapfile size in block numbers. > + * MAKE_SWAPFILE_BLKS - create swap file (blocks). > + * > + * Macro to create swap file, size specified in block numbers. > + * > + * @swapfile: swap filename. > + * @blocks: number of blocks. > */ > #define MAKE_SWAPFILE_BLKS(swapfile, blocks) \ > make_swapfile(__FILE__, __LINE__, swapfile, blocks, 0, SWAPFILE_BY_BLKS) > > /** > - * Macro to safely create swapfile size in megabytes (MB). > + * SAFE_MAKE_SWAPFILE_SIZE - create swap file (MB, safe version). > + * > + * Macro to safely create swap file, size specified in megabytes (MB). > * Includes safety checks to handle potential errors. > + * > + * @swapfile: swap file name. > + * @size: swap size in MB. > */ > #define SAFE_MAKE_SWAPFILE_SIZE(swapfile, size) \ > make_swapfile(__FILE__, __LINE__, swapfile, size, 1, SWAPFILE_BY_SIZE) > > /** > - * Macro to safely create swapfile size in block numbers. > + * SAFE_MAKE_SWAPFILE_BLKS - create swap file (block, safe version) > + * > + * Macro to safely create swap file, size specified in block numbers. > * Includes safety checks to handle potential errors. > + * > + * @swapfile: swap file name. > + * @blocks: number of blocks. > */ > #define SAFE_MAKE_SWAPFILE_BLKS(swapfile, blocks) \ > make_swapfile(__FILE__, __LINE__, swapfile, blocks, 1, SWAPFILE_BY_BLKS) > > -/* > +/** > + * is_swap_supported() - Check swapon/swapoff support. > + * > * Check swapon/swapoff support status of filesystems or files > * we are testing on. > + * > + * @filename: swap file name. > + * Return: true if swap is supported, false if not. > */ > bool is_swap_supported(const char *filename); > > -/* > - * Get kernel constant MAX_SWAPFILES value. > +/** > + * tst_max_swapfiles() - Get kernel constant MAX_SWAPFILES value. > * > + * Return: MAX_SWAPFILES value. > */ > int tst_max_swapfiles(void); > > -/* > - * Get the used swapfiles number. > +/** > + * tst_count_swaps() - Get the used swapfiles number. > + * > + * Return: used swapfiles number. > */ > int tst_count_swaps(void); > Andrea
On Fri, Apr 26, 2024 at 3:44 PM Andrea Cervesato via ltp <ltp@lists.linux.it> wrote: > Hi! > > On 4/26/24 06:28, Petr Vorel wrote: > > Signed-off-by: Petr Vorel <pvorel@suse.cz> > > --- > > doc/developers/api_c_tests.rst | 4 +++ > > include/libswap.h | 61 +++++++++++++++++++++++++++------- > > 2 files changed, 53 insertions(+), 12 deletions(-) > > > > diff --git a/doc/developers/api_c_tests.rst > b/doc/developers/api_c_tests.rst > > index 2c0c8419d..ec53ab33c 100644 > > --- a/doc/developers/api_c_tests.rst > > +++ b/doc/developers/api_c_tests.rst > > @@ -31,3 +31,7 @@ Capabilities > > ------------ > > > > .. kernel-doc:: ../../include/tst_capability.h > > + > > +libltpswap > > +---------- > > +.. kernel-doc:: ../../include/libswap.h > > diff --git a/include/libswap.h b/include/libswap.h > > index f757073cc..681849166 100644 > > --- a/include/libswap.h > > +++ b/include/libswap.h > > @@ -1,11 +1,12 @@ > > // SPDX-License-Identifier: GPL-2.0-or-later > > /* > > * Copyright (c) 2013 Oracle and/or its affiliates. All Rights > Reserved. > > + * Copyright (c) Linux Test Project, 2021-2024 > > * Author: Stanislav Kholmanskikh <stanislav.kholmanskikh@oracle.com> > > */ > > > > /* > > - * Contains common content for all swapon/swapoff tests > > + * Contains common content for all swapon/swapoff tests. > > */ > > > > #ifndef __LIBSWAP_H__ > > @@ -27,60 +28,96 @@ int make_swapfile(const char *file, const int lineno, > > #define MINIMAL_SWAP_SIZE_MB 1 > > > > /** > > - * Macro to create minimal swapfile. > > + * MAKE_SMALL_SWAPFILE - create small swap file. > > + * > > + * Macro to create small small swap file. Size defined with > MINIMAL_SWAP_SIZE_MB. > "small small" sounds weird. Maybe "really small" > +1 I guess that might be one typo. Otherwise looks good to me, thanks! > > + * > > + * @swapfile: swap filename. > > */ > > #define MAKE_SMALL_SWAPFILE(swapfile) \ > > make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, > 0, \ > > SWAPFILE_BY_SIZE) > > > > /** > > - * Macro to create minimal swapfile. > > + * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version). > > + * > > + * Macro to create small small swap file. Size defined with > MINIMAL_SWAP_SIZE_MB. > > * Includes safety checks to handle potential errors. > Same here > > + * > > + * @swapfile: swap filename. > > */ > > #define SAFE_MAKE_SMALL_SWAPFILE(swapfile) \ > > make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, > 1, \ > > SWAPFILE_BY_SIZE) > > > > /** > > - * Macro to create swapfile size in megabytes (MB). > > + * MAKE_SWAPFILE_SIZE - create swap file (MB). > > + * > > + * Macro to create swap file, size specified in megabytes (MB). > > + * > > + * @swapfile: swap filename. > > + * @size: swap size in MB. > > */ > > #define MAKE_SWAPFILE_SIZE(swapfile, size) \ > > make_swapfile(__FILE__, __LINE__, swapfile, size, 0, > SWAPFILE_BY_SIZE) > > > > /** > > - * Macro to create swapfile size in block numbers. > > + * MAKE_SWAPFILE_BLKS - create swap file (blocks). > > + * > > + * Macro to create swap file, size specified in block numbers. > > + * > > + * @swapfile: swap filename. > > + * @blocks: number of blocks. > > */ > > #define MAKE_SWAPFILE_BLKS(swapfile, blocks) \ > > make_swapfile(__FILE__, __LINE__, swapfile, blocks, 0, > SWAPFILE_BY_BLKS) > > > > /** > > - * Macro to safely create swapfile size in megabytes (MB). > > + * SAFE_MAKE_SWAPFILE_SIZE - create swap file (MB, safe version). > > + * > > + * Macro to safely create swap file, size specified in megabytes (MB). > > * Includes safety checks to handle potential errors. > > + * > > + * @swapfile: swap file name. > > + * @size: swap size in MB. > > */ > > #define SAFE_MAKE_SWAPFILE_SIZE(swapfile, size) \ > > make_swapfile(__FILE__, __LINE__, swapfile, size, 1, > SWAPFILE_BY_SIZE) > > > > /** > > - * Macro to safely create swapfile size in block numbers. > > + * SAFE_MAKE_SWAPFILE_BLKS - create swap file (block, safe version) > > + * > > + * Macro to safely create swap file, size specified in block numbers. > > * Includes safety checks to handle potential errors. > > + * > > + * @swapfile: swap file name. > > + * @blocks: number of blocks. > > */ > > #define SAFE_MAKE_SWAPFILE_BLKS(swapfile, blocks) \ > > make_swapfile(__FILE__, __LINE__, swapfile, blocks, 1, > SWAPFILE_BY_BLKS) > > > > -/* > > +/** > > + * is_swap_supported() - Check swapon/swapoff support. > > + * > > * Check swapon/swapoff support status of filesystems or files > > * we are testing on. > > + * > > + * @filename: swap file name. > > + * Return: true if swap is supported, false if not. > > */ > > bool is_swap_supported(const char *filename); > > > > -/* > > - * Get kernel constant MAX_SWAPFILES value. > > +/** > > + * tst_max_swapfiles() - Get kernel constant MAX_SWAPFILES value. > > * > > + * Return: MAX_SWAPFILES value. > > */ > > int tst_max_swapfiles(void); > > > > -/* > > - * Get the used swapfiles number. > > +/** > > + * tst_count_swaps() - Get the used swapfiles number. > > + * > > + * Return: used swapfiles number. > > */ > > int tst_count_swaps(void); > > > > Andrea > > > -- > Mailing list info: https://lists.linux.it/listinfo/ltp > >
Hi Li, > > > /** > > > - * Macro to create minimal swapfile. > > > + * MAKE_SMALL_SWAPFILE - create small swap file. > > > + * > > > + * Macro to create small small swap file. Size defined with > > MINIMAL_SWAP_SIZE_MB. > > "small small" sounds weird. Maybe "really small" > +1 I guess that might be one typo. > Otherwise looks good to me, thanks! Thanks a lot for catching these (on 2 places, diff below). I'm travelling for a few days, thus I'll leave it for others to see before merge. Kind regards, Petr +++ include/libswap.h @@ -30,7 +30,7 @@ int make_swapfile(const char *file, const int lineno, /** * MAKE_SMALL_SWAPFILE - create small swap file. * - * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. + * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. * * @swapfile: swap filename. */ @@ -41,7 +41,7 @@ int make_swapfile(const char *file, const int lineno, /** * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version). * - * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. + * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. * Includes safety checks to handle potential errors. * * @swapfile: swap filename.
Hi Andrea, > > - * Macro to create minimal swapfile. > > + * MAKE_SMALL_SWAPFILE - create small swap file. > > + * > > + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. > "small small" sounds weird. Maybe "really small" +1, my typo, thanks! > > + * > > + * @swapfile: swap filename. > > */ > > #define MAKE_SMALL_SWAPFILE(swapfile) \ > > make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, 0, \ > > SWAPFILE_BY_SIZE) > > /** > > - * Macro to create minimal swapfile. > > + * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version). > > + * > > + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. > > * Includes safety checks to handle potential errors. > Same here Yeah. BTW we need to have CI job which tries to generate our docs with sphinx. Kind regards, Petr
Hi! LGTM with fix Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com> On 4/26/24 20:25, Petr Vorel wrote: > Hi Li, > >>>> /** >>>> - * Macro to create minimal swapfile. >>>> + * MAKE_SMALL_SWAPFILE - create small swap file. >>>> + * >>>> + * Macro to create small small swap file. Size defined with >>> MINIMAL_SWAP_SIZE_MB. >>> "small small" sounds weird. Maybe "really small" > >> +1 I guess that might be one typo. >> Otherwise looks good to me, thanks! > Thanks a lot for catching these (on 2 places, diff below). I'm travelling for a > few days, thus I'll leave it for others to see before merge. > > Kind regards, > Petr > > +++ include/libswap.h > @@ -30,7 +30,7 @@ int make_swapfile(const char *file, const int lineno, > /** > * MAKE_SMALL_SWAPFILE - create small swap file. > * > - * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. > + * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. > * > * @swapfile: swap filename. > */ > @@ -41,7 +41,7 @@ int make_swapfile(const char *file, const int lineno, > /** > * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version). > * > - * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. > + * Macro to create small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. > * Includes safety checks to handle potential errors. > * > * @swapfile: swap filename.
Hi Andrea, Li, > Hi! > LGTM with fix Thanks for your review, merged! Kind regards, Petr
diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst index 2c0c8419d..ec53ab33c 100644 --- a/doc/developers/api_c_tests.rst +++ b/doc/developers/api_c_tests.rst @@ -31,3 +31,7 @@ Capabilities ------------ .. kernel-doc:: ../../include/tst_capability.h + +libltpswap +---------- +.. kernel-doc:: ../../include/libswap.h diff --git a/include/libswap.h b/include/libswap.h index f757073cc..681849166 100644 --- a/include/libswap.h +++ b/include/libswap.h @@ -1,11 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-or-later /* * Copyright (c) 2013 Oracle and/or its affiliates. All Rights Reserved. + * Copyright (c) Linux Test Project, 2021-2024 * Author: Stanislav Kholmanskikh <stanislav.kholmanskikh@oracle.com> */ /* - * Contains common content for all swapon/swapoff tests + * Contains common content for all swapon/swapoff tests. */ #ifndef __LIBSWAP_H__ @@ -27,60 +28,96 @@ int make_swapfile(const char *file, const int lineno, #define MINIMAL_SWAP_SIZE_MB 1 /** - * Macro to create minimal swapfile. + * MAKE_SMALL_SWAPFILE - create small swap file. + * + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. + * + * @swapfile: swap filename. */ #define MAKE_SMALL_SWAPFILE(swapfile) \ make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, 0, \ SWAPFILE_BY_SIZE) /** - * Macro to create minimal swapfile. + * SAFE_MAKE_SMALL_SWAPFILE - create small swap file (safe version). + * + * Macro to create small small swap file. Size defined with MINIMAL_SWAP_SIZE_MB. * Includes safety checks to handle potential errors. + * + * @swapfile: swap filename. */ #define SAFE_MAKE_SMALL_SWAPFILE(swapfile) \ make_swapfile(__FILE__, __LINE__, swapfile, MINIMAL_SWAP_SIZE_MB, 1, \ SWAPFILE_BY_SIZE) /** - * Macro to create swapfile size in megabytes (MB). + * MAKE_SWAPFILE_SIZE - create swap file (MB). + * + * Macro to create swap file, size specified in megabytes (MB). + * + * @swapfile: swap filename. + * @size: swap size in MB. */ #define MAKE_SWAPFILE_SIZE(swapfile, size) \ make_swapfile(__FILE__, __LINE__, swapfile, size, 0, SWAPFILE_BY_SIZE) /** - * Macro to create swapfile size in block numbers. + * MAKE_SWAPFILE_BLKS - create swap file (blocks). + * + * Macro to create swap file, size specified in block numbers. + * + * @swapfile: swap filename. + * @blocks: number of blocks. */ #define MAKE_SWAPFILE_BLKS(swapfile, blocks) \ make_swapfile(__FILE__, __LINE__, swapfile, blocks, 0, SWAPFILE_BY_BLKS) /** - * Macro to safely create swapfile size in megabytes (MB). + * SAFE_MAKE_SWAPFILE_SIZE - create swap file (MB, safe version). + * + * Macro to safely create swap file, size specified in megabytes (MB). * Includes safety checks to handle potential errors. + * + * @swapfile: swap file name. + * @size: swap size in MB. */ #define SAFE_MAKE_SWAPFILE_SIZE(swapfile, size) \ make_swapfile(__FILE__, __LINE__, swapfile, size, 1, SWAPFILE_BY_SIZE) /** - * Macro to safely create swapfile size in block numbers. + * SAFE_MAKE_SWAPFILE_BLKS - create swap file (block, safe version) + * + * Macro to safely create swap file, size specified in block numbers. * Includes safety checks to handle potential errors. + * + * @swapfile: swap file name. + * @blocks: number of blocks. */ #define SAFE_MAKE_SWAPFILE_BLKS(swapfile, blocks) \ make_swapfile(__FILE__, __LINE__, swapfile, blocks, 1, SWAPFILE_BY_BLKS) -/* +/** + * is_swap_supported() - Check swapon/swapoff support. + * * Check swapon/swapoff support status of filesystems or files * we are testing on. + * + * @filename: swap file name. + * Return: true if swap is supported, false if not. */ bool is_swap_supported(const char *filename); -/* - * Get kernel constant MAX_SWAPFILES value. +/** + * tst_max_swapfiles() - Get kernel constant MAX_SWAPFILES value. * + * Return: MAX_SWAPFILES value. */ int tst_max_swapfiles(void); -/* - * Get the used swapfiles number. +/** + * tst_count_swaps() - Get the used swapfiles number. + * + * Return: used swapfiles number. */ int tst_count_swaps(void);
Signed-off-by: Petr Vorel <pvorel@suse.cz> --- doc/developers/api_c_tests.rst | 4 +++ include/libswap.h | 61 +++++++++++++++++++++++++++------- 2 files changed, 53 insertions(+), 12 deletions(-)