[{"id":3683495,"web_url":"http://patchwork.ozlabs.org/comment/3683495/","msgid":"","list_archive_url":null,"date":"2026-04-28T14:08:05","subject":"Re: [PATCH v3 09/10] ubi: add comments for exported ubi API functions","submitter":{"id":6170,"url":"http://patchwork.ozlabs.org/api/people/6170/","name":"Simon Glass","email":"sjg@chromium.org"},"content":"Hi Weijie,\n\nOn 2026-04-27T07:09:11, Weijie Gao wrote:\n> ubi: add comments for exported ubi API functions\n>\n> This patch adds comments for exported ubi command API functions.\n>\n> Signed-off-by: Weijie Gao \n>\n> include/ubi_uboot.h | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++\n> 1 file changed, 86 insertions(+)\n\n> diff --git a/include/ubi_uboot.h b/include/ubi_uboot.h\n> @@ -47,14 +47,100 @@\n> + * ubi_part() - attach UBI to MTD partition\n> + * @part_name: name of the MTD partition to attach\n> + * @vid_header_offset: VID header offset (string)\n> + *\n> + * This function detaches any existing UBI device, then probes for the\n> + * specified MTD partition, and then scans it to initialize UBI.\n> + *\n> + * @vid_header_offset is optional and is usually set to NULL.\n> + *\n> + * Return: 0 on success, 1 if partition not found, or -ve on error.\n> + */\n> int ubi_part(const char *part_name, const char *vid_header_offset);\n\nMost error paths in this file return positive errno values, so '-ve on\nerror' is not quite right. Please double-check and document the actual\nconvention.\n\n> diff --git a/include/ubi_uboot.h b/include/ubi_uboot.h\n> @@ -47,14 +47,100 @@\n> + * ubi_volume_read() - read data from UBI volume\n> + * @volume: name of the volume to read from\n> + * @buf: buffer to hold the read data\n> + * @offset: start offset for reading\n> + * @size: number of bytes to read\n> + *\n> + * This function reads data from the specified UBI volume. If @size is zero,\n> + * the function reads the entire volume content starting from @offset.\n> + *\n> + * Return: 0 on success, or -ve on error.\n> + */\n> int ubi_volume_read(const char *volume, void *buf, loff_t offset, size_t size);\n\nSame here early-exit paths return positive errno (ENODEV, EBUSY,\nEBADF, ENOMEM) while the read loop negates ubi_eba_read_leb()'s error.\nBetter to normalise to one convention, and please be consistent across\nall of these.\n\n> diff --git a/include/ubi_uboot.h b/include/ubi_uboot.h\n> @@ -47,14 +47,100 @@\n> + * This function creates a new UBI volume with the specified parameters.\n> + * If @size is negative, all available spaces will be used.\n> + * if @vol_id is negative, volume ID will be selected and assigned by UBI.\n> + *\n> + * Return: 0 on success, or -ve on error.\n> + */\n> int ubi_create_vol(const char *volume, int64_t size, bool dynamic, int vol_id,\n\n> bool skipcheck);\n\nCapitlal I on 'If'. Also 'all available spaces' reads better as 'all\navailable space'. Also worth mentioning that @vol_id should be\nUBI_VOL_NUM_AUTO for auto-assignment.\n\n> diff --git a/include/ubi_uboot.h b/include/ubi_uboot.h\n> @@ -47,14 +47,100 @@\n> + * ubi_detach() - detach UBI from MTD partition\n> + *\n> + * This function performs the cleanup of the UBI subsystem to make sure the\n> + * MTD partition can be safely used by other purpose, or be attached again\n> + * with ubi_part().\n> + *\n> + * Any mounted UBIFS will be unmounted automatically.\n> + *\n> + * Return: 0 on success.\n> + */\n> int ubi_detach(void);\n\n'used by other purpose' should be 'used for another purpose'. Since\nthis only ever returns 0, you could say 'Return: 0' and drop 'on\nsuccess'.\n\nRegards,\nSimon","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@legolas.ozlabs.org","Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=chromium.org header.i=@chromium.org header.a=rsa-sha256\n header.s=google header.b=aoA9g3WR;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de\n (client-ip=85.214.62.61; helo=phobos.denx.de;\n envelope-from=u-boot-bounces@lists.denx.de; receiver=patchwork.ozlabs.org)","phobos.denx.de;\n dmarc=pass (p=none dis=none) header.from=chromium.org","phobos.denx.de;\n spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de","phobos.denx.de;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=chromium.org header.i=@chromium.org\n header.b=\"aoA9g3WR\";\n\tdkim-atps=neutral","phobos.denx.de;\n dmarc=pass (p=none dis=none) header.from=chromium.org","phobos.denx.de;\n spf=pass smtp.mailfrom=sjg@chromium.org"],"Received":["from phobos.denx.de (phobos.denx.de [85.214.62.61])\n\t(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n\t key-exchange x25519)\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4g4j2b0xHDz1xrS\n\tfor ; Wed, 29 Apr 2026 00:08:22 +1000 (AEST)","from h2850616.stratoserver.net (localhost [IPv6:::1])\n\tby phobos.denx.de (Postfix) with ESMTP id 5B79E84150;\n\tTue, 28 Apr 2026 16:08:20 +0200 (CEST)","by phobos.denx.de (Postfix, from userid 109)\n id CB95484255; Tue, 28 Apr 2026 16:08:19 +0200 (CEST)","from mail-ej1-x636.google.com (mail-ej1-x636.google.com\n [IPv6:2a00:1450:4864:20::636])\n (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits))\n (No client certificate requested)\n by phobos.denx.de (Postfix) with ESMTPS id CFB7F83FB5\n for ; Tue, 28 Apr 2026 16:08:17 +0200 (CEST)","by mail-ej1-x636.google.com with SMTP id\n a640c23a62f3a-b941762394aso1574091766b.1\n for ; Tue, 28 Apr 2026 07:08:17 -0700 (PDT)"],"X-Spam-Checker-Version":"SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de","X-Spam-Level":"","X-Spam-Status":"No, score=-2.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,\n DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,\n RCVD_IN_DNSWL_BLOCKED,SPF_HELO_NONE,SPF_PASS autolearn=ham\n autolearn_force=no version=3.4.2","ARC-Seal":"i=1; a=rsa-sha256; t=1777385297; cv=none;\n d=google.com; s=arc-20240605;\n b=Ysb4bRskkqkW736tqy1O9evxarBW13mAUxwomLmbCcYgKEg1H1Y7iyBlkWNb6pQHZB\n A8SkTbNMsx9fK2/DwywhgbAuhiu4HeAK5T/5GH1GhooghGpY2ojYq7rr5UUoNLOdSZE9\n uvZuTm4wkf9/Wb1SDAsbaU137ABKBFsYvwdbu88j7Fe1jQNFvMbKLdh1kCffrn1EN3dI\n oN/07RZfxUgLtSDKe4PEmDrd/FHaqIR4bpdHE5ztnwM+3N4LfaMJF688VvIS8sffXTTy\n aSM34q/Rti2hT5HLAiVJ1R/brh4JU6MhQn2BbWX4T2kPcUVkqVTgvdYcObSV0uSbNTbV\n wvYw==","ARC-Message-Signature":"i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com;\n s=arc-20240605;\n h=cc:to:subject:message-id:date:from:in-reply-to:references\n :mime-version:dkim-signature;\n bh=k5TcjNjxERFq6XEmN/dCFs7IU3BVqoH0Db+cUsIq6R8=;\n fh=fJAGB8LvxCJalDRE+ziaXIW21+gD5jSCb0B1QEwHsvE=;\n b=A99AMfXezqa0cfpfDAcog4kn/kqqQb6WX6pAVU3YmahNMqrsQeppK95P2P8U7WDXid\n QqNqDjldJzzp64DVvgBgdFGT6RylZlDErvEevKl5f4M1hF43q7xO+sMAVPs3qsnyazWD\n GDsD1xy4Xfnt8Bk5DmFbC8v4GmeeQ+UBlZuredJTtS3fb9/xwbx8mvauRlrMA1hqBPnm\n JY9kcsmt2QRgsothki1J0zz6fpLE36Pf9Zg2bVjAoSvPCFaWTeCwkRyxmzUhaeXW7mag\n NvEb0ZPfo1m39MRPQLLpVntvRSekLpWxVYm1z1nr/308IT8AtZwMrEr//dr3GlbtZdoe\n 10dQ==; darn=lists.denx.de","ARC-Authentication-Results":"i=1; mx.google.com; arc=none","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=chromium.org; s=google; t=1777385297; x=1777990097; darn=lists.denx.de;\n h=cc:to:subject:message-id:date:from:in-reply-to:references\n :mime-version:from:to:cc:subject:date:message-id:reply-to;\n bh=k5TcjNjxERFq6XEmN/dCFs7IU3BVqoH0Db+cUsIq6R8=;\n b=aoA9g3WRP/O5dWO05V7Ozy2Fr8xD3UReou1m+nPaj53VaOIz7JsdIqk7+3xDOm4QdU\n bgl4S4zZtdvd0ULPyf+zcy0+APeXGTpgZiNqDMuh72YriwoN0/I1iF2d4T5Mt0tWabWl\n P3RSHZRD/e7FqECjHIUGYd7ioU5GpXnzpwMwQ=","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20251104; t=1777385297; x=1777990097;\n h=cc:to:subject:message-id:date:from:in-reply-to:references\n :mime-version:x-gm-gg:x-gm-message-state:from:to:cc:subject:date\n :message-id:reply-to;\n bh=k5TcjNjxERFq6XEmN/dCFs7IU3BVqoH0Db+cUsIq6R8=;\n b=Lu/BULjOmZMEGl092n537rnZTF/abWrZd4SjHEUg5iJpFKC2cALyB/02qRnOcUh2w/\n rg5Bxz4xkgrJ2c5FPzmacWFWQD01D9YD2XnlxzuIrMuozlsiVfcXSTv9kynDGA1vtHi3\n hRZ7/fy9Ub2MvLbXilxsKbCv4AEEGgY5BryyHFvR94vMhzU29JXNkj6IS+thV6CtY2mV\n /9KExxBZ/lqHCeiRM0GsLqnnNPnwwGdTjBw/AAsieqEln4RWutyUNa1pxkF83wwJWlmX\n sjs6verAj9/111+NBEzta3KgjMK9Rol0reyYqQWg4z3br73oKlMLeTDjanvxATI510Pz\n sMOg==","X-Gm-Message-State":"AOJu0YydlZEO516UyLq3TV9lPNzQSxRpAyUFiY2S2HNDTX4pltxRnSYD\n j997EihuptsE0CpZ/8tE/2XJ1Vwm+Z+oqeokLKbNVK5WD8Cj0eybNLHqx5yXW0MttN+sGpKDmon\n ec3V+MRjGCbasFWw0Dpc4pyXfVTv1l5qbhn7XjYvvQ/je+DsoYX4=","X-Gm-Gg":"AeBDievhRIpHCteNwW7JxSbB66hyw/C1wA0Q82UNz/nAhYhfuSW7+WyGvRIx/QVEr5S\n o19p2DFbW6iPSsMRVRQy5rRHIwA8UqdXDWLCx9cWrlmCwxescsjaGxIQ4u/nnB0ffl7GZxJNk1T\n EybuvCHwFhqgS2igprZ4Pzg14MYSogPkiVt/ECF9zO40pza8yR50UkSuUK0IhZlnnkwIlOHsmLn\n N2AVCjQY9mIuJKYEYbmo98/YnrXqHETaRuYie1z4PD0aHFl21hQO5IgyZNrL+1EHX3i6akdKUbR\n cZAmbd4IIUfdLPFW","X-Received":"by 2002:a17:907:874b:b0:ba8:e7d5:6a7a with SMTP id\n a640c23a62f3a-bb804537637mr175179266b.40.1777385297197; Tue, 28 Apr 2026\n 07:08:17 -0700 (PDT)","MIME-Version":"1.0","References":"\n ","In-Reply-To":"\n ","From":"Simon Glass ","Date":"Tue, 28 Apr 2026 08:08:05 -0600","X-Gm-Features":"AVHnY4L4GXKp3qM7-VVdRd8fUCTgRT75oXyITBRiMxwwskAxDTi03nqc9dAEjdA","Message-ID":"\n ","Subject":"Re: [PATCH v3 09/10] ubi: add comments for exported ubi API functions","To":"weijie.gao@mediatek.com","Cc":"u-boot@lists.denx.de","Content-Type":"text/plain; charset=\"UTF-8\"","X-BeenThere":"u-boot@lists.denx.de","X-Mailman-Version":"2.1.39","Precedence":"list","List-Id":"U-Boot discussion ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"u-boot-bounces@lists.denx.de","Sender":"\"U-Boot\" ","X-Virus-Scanned":"clamav-milter 0.103.8 at phobos.denx.de","X-Virus-Status":"Clean"}}]