From: Dmitry Rokosov Date: Thu, 17 Oct 2024 14:12:06 +0000 (+0300) Subject: include/android_ab: move ab_select_slot() documentation to @ notation X-Git-Url: http://git.dujemihanovic.xyz/img/static/git-logo.png?a=commitdiff_plain;h=01874ac7c06b8c657e7c3fda5ac555f821ef5b36;p=u-boot.git include/android_ab: move ab_select_slot() documentation to @ notation There are new function documentation requirements in U-Boot, so apply these changes for android_ab. Reviewed-by: Mattijs Korpershoek Reviewed-by: Simon Glass Tested-by: Guillaume La Roque Signed-off-by: Dmitry Rokosov Tested-by: Mattijs Korpershoek # vim3_android Link: https://lore.kernel.org/r/20241017-android_ab_master-v5-1-43bfcc096d95@salutedevices.com Signed-off-by: Mattijs Korpershoek --- diff --git a/boot/android_ab.c b/boot/android_ab.c index 1196a189ed..0045c8133a 100644 --- a/boot/android_ab.c +++ b/boot/android_ab.c @@ -13,13 +13,13 @@ #include /** - * Compute the CRC-32 of the bootloader control struct. + * ab_control_compute_crc() - Compute the CRC32 of the bootloader control. + * + * @abc: Bootloader control block * * Only the bytes up to the crc32_le field are considered for the CRC-32 * calculation. * - * @param[in] abc bootloader control block - * * Return: crc32 sum */ static uint32_t ab_control_compute_crc(struct bootloader_control *abc) @@ -28,14 +28,14 @@ static uint32_t ab_control_compute_crc(struct bootloader_control *abc) } /** - * Initialize bootloader_control to the default value. + * ab_control_default() - Initialize bootloader_control to the default value. + * + * @abc: Bootloader control block * * It allows us to boot all slots in order from the first one. This value * should be used when the bootloader message is corrupted, but not when * a valid message indicates that all slots are unbootable. * - * @param[in] abc bootloader control block - * * Return: 0 on success and a negative on error */ static int ab_control_default(struct bootloader_control *abc) @@ -67,7 +67,13 @@ static int ab_control_default(struct bootloader_control *abc) } /** - * Load the boot_control struct from disk into newly allocated memory. + * ab_control_create_from_disk() - Load the boot_control from disk into memory. + * + * @dev_desc: Device where to read the boot_control struct from + * @part_info: Partition in 'dev_desc' where to read from, normally + * the "misc" partition should be used + * @abc: pointer to pointer to bootloader_control data + * @offset: boot_control struct offset * * This function allocates and returns an integer number of disk blocks, * based on the block size of the passed device to help performing a @@ -75,10 +81,6 @@ static int ab_control_default(struct bootloader_control *abc) * The boot_control struct offset (2 KiB) must be a multiple of the device * block size, for simplicity. * - * @param[in] dev_desc Device where to read the boot_control struct from - * @param[in] part_info Partition in 'dev_desc' where to read from, normally - * the "misc" partition should be used - * @param[out] pointer to pointer to bootloader_control data * Return: 0 on success and a negative on error */ static int ab_control_create_from_disk(struct blk_desc *dev_desc, @@ -122,15 +124,17 @@ static int ab_control_create_from_disk(struct blk_desc *dev_desc, } /** - * Store the loaded boot_control block. + * ab_control_store() - Store the loaded boot_control block. + * + * @dev_desc: Device where we should write the boot_control struct + * @part_info: Partition on the 'dev_desc' where to write + * @abc Pointer to the boot control struct and the extra bytes after + * it up to the nearest block boundary + * @offset: boot_control struct offset * * Store back to the same location it was read from with * ab_control_create_from_misc(). * - * @param[in] dev_desc Device where we should write the boot_control struct - * @param[in] part_info Partition on the 'dev_desc' where to write - * @param[in] abc Pointer to the boot control struct and the extra bytes after - * it up to the nearest block boundary * Return: 0 on success and a negative on error */ static int ab_control_store(struct blk_desc *dev_desc, @@ -160,12 +164,13 @@ static int ab_control_store(struct blk_desc *dev_desc, } /** - * Compare two slots. + * ab_compare_slots() - Compare two slots. + * + * @a: The first bootable slot metadata + * @b: The second bootable slot metadata * * The function determines slot which is should we boot from among the two. * - * @param[in] a The first bootable slot metadata - * @param[in] b The second bootable slot metadata * Return: Negative if the slot "a" is better, positive of the slot "b" is * better or 0 if they are equally good. */ diff --git a/include/android_ab.h b/include/android_ab.h index dbf20343da..1e53879a25 100644 --- a/include/android_ab.h +++ b/include/android_ab.h @@ -18,7 +18,10 @@ struct disk_partition; #define NUM_SLOTS 2 /** - * Select the slot where to boot from. + * ab_select_slot() - Select the slot where to boot from. + * + * @dev_desc: Place to store the device description pointer + * @part_info: Place to store the partition information * * On Android devices with more than one boot slot (multiple copies of the * kernel and system images) selects which slot should be used to boot from and @@ -28,8 +31,6 @@ struct disk_partition; * registered before returning from this function so it isn't selected * indefinitely. * - * @param[in] dev_desc Place to store the device description pointer - * @param[in] part_info Place to store the partition information * Return: The slot number (>= 0) on success, or a negative on error */ int ab_select_slot(struct blk_desc *dev_desc, struct disk_partition *part_info,