From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 7569DC433EF for ; Thu, 13 Jan 2022 02:28:40 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 46D678355F; Thu, 13 Jan 2022 03:27:21 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; unprotected) header.d=chromium.org header.i=@chromium.org header.b="i9dVGUFl"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 489078326B; Thu, 13 Jan 2022 03:27:05 +0100 (CET) Received: from mail-il1-x12b.google.com (mail-il1-x12b.google.com [IPv6:2607:f8b0:4864:20::12b]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 5EC2A8326B for ; Thu, 13 Jan 2022 03:26:58 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=chromium.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=sjg@chromium.org Received: by mail-il1-x12b.google.com with SMTP id o1so4318547ilo.6 for ; Wed, 12 Jan 2022 18:26:58 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=chromium.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=DpgYf8OgWX3EF+Vq2iUJ+ae4ocOrPsumbwdwvk6l0/g=; b=i9dVGUFlBDw0X1a8RzpAQAD8MWcJhM2a6tPCze+D2zQ+wvTiEmBTyQxnP3AaHLxEu+ f4fWbyCWJhkzyuIfDlikIXSDcsuBCyOsbhAa1FWmohVi9w6D3x4XfQUq46r5fL9zqh5b eCOSx6mMmiiUzn1HdIExNDC0Vv64psD24K0ys= 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=DpgYf8OgWX3EF+Vq2iUJ+ae4ocOrPsumbwdwvk6l0/g=; b=P+PEy+GB10tYZFzcKykLJCibgZ5OMDM4Ot/84HT+FhhxiIg7ug3wuw9+4OZt48P09n cAEs6Peysh/etvF8wAmn63+VMJMVMFaRRrZlgVHKu6hDWae8WLS0Su91GSm0eLL7hvrn OfS097i6aWge1w0HBlVio9OtTzddpiAkTCBZbmq2o6t3I3GTaNLFTPNyRATzSXhKXEoG ijErn4S9UMN1hGUXjaQW8MrA6IFN+nupoXwlDsM1aO83drsTs9oo87CJmPQjAbtsKVc/ vwhUhLaOWiFJhIg3+eBJRFplIllHYzvYi7jsyTpk170ixvhSnoFKdayTz66nMCLq0/+6 bN7Q== X-Gm-Message-State: AOAM53069nKrsbt+T/0eUq0a3RvN2CbIWCzeO2zyLUOu52EeBDodw2GB 8w6966uKtnZVJ7VQxGYD/hglT5RcOBiCog== X-Google-Smtp-Source: ABdhPJypWNdyyBBTwjWJVJ3vmxGEM43A47uftaKZ2+dKkzc9KmYToObzVouhnqLsOLzMV0fbAZwZiA== X-Received: by 2002:a92:cdac:: with SMTP id g12mr1309044ild.83.1642040816843; Wed, 12 Jan 2022 18:26:56 -0800 (PST) Received: from kiwi.bld.corp.google.com (c-67-190-101-114.hsd1.co.comcast.net. [67.190.101.114]) by smtp.gmail.com with ESMTPSA id e17sm965634ili.37.2022.01.12.18.26.56 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 12 Jan 2022 18:26:56 -0800 (PST) From: Simon Glass To: U-Boot Mailing List Cc: Tom Rini , Simon Glass Subject: [PATCH v2 11/12] bloblist: doc: Bring in the API documentation Date: Wed, 12 Jan 2022 19:26:24 -0700 Message-Id: <20220113022625.413990-12-sjg@chromium.org> X-Mailer: git-send-email 2.34.1.575.g55b058a8bb-goog In-Reply-To: <20220113022625.413990-1-sjg@chromium.org> References: <20220113022625.413990-1-sjg@chromium.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean FIx up various minor errors and add the API documentation to the bloblist docs, since it is quite useful to see it in the same place. Signed-off-by: Simon Glass --- (no changes since v1) doc/develop/bloblist.rst | 8 +++- include/bloblist.h | 79 +++++++++++++++++++++++----------------- 2 files changed, 52 insertions(+), 35 deletions(-) diff --git a/doc/develop/bloblist.rst b/doc/develop/bloblist.rst index 47274cf8e26..572aa65d764 100644 --- a/doc/develop/bloblist.rst +++ b/doc/develop/bloblist.rst @@ -31,7 +31,7 @@ Blobs While each blob in the bloblist can be of any length, bloblists are designed to hold small amounts of data, typically a few KB at most. It is not possible to change the length of a blob once it has been written. Each blob is normally -created from a C structure which can beused to access its fields. +created from a C structure which can be used to access its fields. Blob tags @@ -93,6 +93,12 @@ This should move to using bloblist, to avoid having its own mechanism for passing information between U-Boot parts. +API documentation +----------------- + +.. kernel-doc:: include/bloblist.h + + Simon Glass sjg@chromium.org 12-Aug-2018 diff --git a/include/bloblist.h b/include/bloblist.h index d9e108d8618..798babe9235 100644 --- a/include/bloblist.h +++ b/include/bloblist.h @@ -86,8 +86,8 @@ enum bloblist_tag_t { * same place in memory as SPL and U-Boot execute, but it can be safely moved * around. * - * None of the bloblist structures contain pointers but it is possible to put - * pointers inside a bloblist record if desired. This is not encouraged, + * None of the bloblist headers themselves contain pointers but it is possible + * to put pointers inside a bloblist record if desired. This is not encouraged, * since it can make part of the bloblist inaccessible if the pointer is * no-longer valid. It is better to just store all the data inside a bloblist * record. @@ -99,7 +99,7 @@ enum bloblist_tag_t { * @version: BLOBLIST_VERSION * @hdr_size: Size of this header, normally sizeof(struct bloblist_hdr). The * first bloblist_rec starts at this offset from the start of the header - * @flags: Space for BLOBLISTF_... flags (none yet) + * @flags: Space for BLOBLISTF... flags (none yet) * @size: Total size of the bloblist (non-zero if valid) including this header. * The bloblist extends for this many bytes from the start of this header. * When adding new records, the bloblist can grow up to this size. @@ -110,8 +110,8 @@ enum bloblist_tag_t { * @chksum: CRC32 for the entire bloblist allocated area. Since any of the * blobs can be altered after being created, this checksum is only valid * when the bloblist is finalised before jumping to the next stage of boot. - * Note: @chksum is last to make it easier to exclude it from the checksum - * calculation. + * Note that chksum is last to make it easier to exclude it from the + * checksum calculation. */ struct bloblist_hdr { u32 magic; @@ -128,11 +128,11 @@ struct bloblist_hdr { /** * struct bloblist_rec - record for the bloblist * - * NOTE: Only exported for testing purposes. Do not use this struct. - * * The bloblist contains a number of records each consisting of this record * structure followed by the data contained. Each records is 16-byte aligned. * + * NOTE: Only exported for testing purposes. Do not use this struct. + * * @tag: Tag indicating what the record contains * @hdr_size: Size of this header, normally sizeof(struct bloblist_rec). The * record's data starts at this offset from the start of the record @@ -161,7 +161,7 @@ static inline ulong bloblist_addr(void) * bloblist_check_magic() - return a bloblist if the magic matches * * @addr: Address to check - * @return pointer to bloblist, if the magic matches, else NULL + * Return: pointer to bloblist, if the magic matches, else NULL */ static inline void *bloblist_check_magic(ulong addr) { @@ -183,8 +183,8 @@ static inline void *bloblist_check_magic(ulong addr) * * @tag: Tag to search for (enum bloblist_tag_t) * @size: Expected size of the blob, or 0 for any size - * @return pointer to blob if found, or NULL if not found, or a blob was found - * but it is the wrong size + * Return: pointer to blob if found, or NULL if not found, or a blob was found + * but it is the wrong size */ void *bloblist_find(uint tag, int size); @@ -200,8 +200,8 @@ void *bloblist_find(uint tag, int size); * @tag: Tag to add (enum bloblist_tag_t) * @size: Size of the blob * @align: Alignment of the blob (in bytes), 0 for default - * @return pointer to the newly added block, or NULL if there is not enough - * space for the blob + * Return: pointer to the newly added block, or NULL if there is not enough + * space for the blob */ void *bloblist_add(uint tag, int size, int align); @@ -214,8 +214,8 @@ void *bloblist_add(uint tag, int size, int align); * @size: Size of the blob * @blobp: Returns a pointer to blob on success * @align: Alignment of the blob (in bytes), 0 for default - * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack - * of space, or -ESPIPE it exists but has the wrong size + * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack + * of space, or -ESPIPE it exists but has the wrong size */ int bloblist_ensure_size(uint tag, int size, int align, void **blobp); @@ -226,8 +226,8 @@ int bloblist_ensure_size(uint tag, int size, int align, void **blobp); * * @tag: Tag to add (enum bloblist_tag_t) * @size: Size of the blob - * @return pointer to blob, or NULL if it is missing and could not be added due - * to lack of space, or it exists but has the wrong size + * Return: pointer to blob, or NULL if it is missing and could not be added due + * to lack of space, or it exists but has the wrong size */ void *bloblist_ensure(uint tag, int size); @@ -239,8 +239,8 @@ void *bloblist_ensure(uint tag, int size); * @tag: Tag to add (enum bloblist_tag_t) * @sizep: Size of the blob to create; returns size of actual blob * @blobp: Returns a pointer to blob on success - * @return 0 if OK, -ENOSPC if it is missing and could not be added due to lack - * of space + * Return: 0 if OK, -ENOSPC if it is missing and could not be added due to lack + * of space */ int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp); @@ -252,8 +252,8 @@ int bloblist_ensure_size_ret(uint tag, int *sizep, void **blobp); * * @tag: Tag to add (enum bloblist_tag_t) * @new_size: New size of the blob (>0 to expand, <0 to contract) - * @return 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT - * if the tag is not found + * Return: 0 if OK, -ENOSPC if the bloblist does not have enough space, -ENOENT + * if the tag is not found */ int bloblist_resize(uint tag, int new_size); @@ -263,8 +263,8 @@ int bloblist_resize(uint tag, int new_size); * @addr: Address of bloblist * @size: Initial size for bloblist * @flags: Flags to use for bloblist - * @return 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the - * area is not large enough + * Return: 0 if OK, -EFAULT if addr is not aligned correctly, -ENOSPC is the + * area is not large enough */ int bloblist_new(ulong addr, uint size, uint flags); @@ -273,11 +273,11 @@ int bloblist_new(ulong addr, uint size, uint flags); * * @addr: Address of bloblist * @size: Expected size of blobsize, or 0 to detect the size - * @return 0 if OK, -ENOENT if the magic number doesn't match (indicating that - * there problem is no bloblist at the given address), -EPROTONOSUPPORT - * if the version does not match, -EIO if the checksum does not match, - * -EFBIG if the expected size does not match the detected size, -ENOSPC - * if the size is not large enough to hold the headers + * Return: 0 if OK, -ENOENT if the magic number doesn't match (indicating that + * there problem is no bloblist at the given address), -EPROTONOSUPPORT + * if the version does not match, -EIO if the checksum does not match, + * -EFBIG if the expected size does not match the detected size, -ENOSPC + * if the size is not large enough to hold the headers */ int bloblist_check(ulong addr, uint size); @@ -287,7 +287,7 @@ int bloblist_check(ulong addr, uint size); * This sets the correct checksum for the bloblist. This ensures that the * bloblist will be detected correctly by the next phase of U-Boot. * - * @return 0 + * Return: 0 */ int bloblist_finish(void); @@ -305,14 +305,14 @@ void bloblist_get_stats(ulong *basep, ulong *sizep, ulong *allocedp); /** * bloblist_get_base() - Get the base address of the bloblist * - * @returns base address of bloblist + * Return: base address of bloblist */ ulong bloblist_get_base(void); /** * bloblist_get_size() - Get the size of the bloblist * - * @returns the size in bytes + * Return: the size in bytes */ ulong bloblist_get_size(void); @@ -334,7 +334,7 @@ void bloblist_show_list(void); * bloblist_tag_name() - Get the name for a tag * * @tag: Tag to check - * @return name of tag, or "invalid" if an invalid tag is provided + * Return: name of tag, or "invalid" if an invalid tag is provided */ const char *bloblist_tag_name(enum bloblist_tag_t tag); @@ -342,7 +342,7 @@ const char *bloblist_tag_name(enum bloblist_tag_t tag); * bloblist_reloc() - Relocate the bloblist and optionally resize it * * @to: Pointer to new bloblist location (must not overlap old location) - * @to:size: New size for bloblist (must be larger than from_size) + * @to_size: New size for bloblist (must be larger than from_size) * @from: Pointer to bloblist to relocate * @from_size: Size of bloblist to relocate */ @@ -351,8 +351,19 @@ void bloblist_reloc(void *to, uint to_size, void *from, uint from_size); /** * bloblist_init() - Init the bloblist system with a single bloblist * - * This uses CONFIG_BLOBLIST_ADDR and CONFIG_BLOBLIST_SIZE to set up a bloblist - * for use by U-Boot. + * This locates and sets up the blocklist for use. + * + * If CONFIG_BLOBLIST_FIXED is selected, it uses CONFIG_BLOBLIST_ADDR and + * CONFIG_BLOBLIST_SIZE to set up a bloblist for use by U-Boot. + * + * If CONFIG_BLOBLIST_ALLOC is selected, it allocates memory for a bloblist of + * size CONFIG_BLOBLIST_SIZE. + * + * If CONFIG_BLOBLIST_PASSAGE is selected, it uses the bloblist in the incoming + * standard passage. The size is detected automatically so CONFIG_BLOBLIST_SIZE + * can be 0. + * + * Return: 0 if OK, -ve on error */ int bloblist_init(void); -- 2.34.1.575.g55b058a8bb-goog