From patchwork Mon Jan 18 20:06:03 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1428297 X-Patchwork-Delegate: trini@ti.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.a=rsa-sha256 header.s=badeba3b8450 header.b=Ih+taYqI; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4DKN8t2HTrz9sWY for ; Tue, 19 Jan 2021 07:06:26 +1100 (AEDT) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id B59DE8288B; Mon, 18 Jan 2021 21:06:16 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=gmx.de 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; secure) header.d=gmx.net header.i=@gmx.net header.b="Ih+taYqI"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id B0EF182890; Mon, 18 Jan 2021 21:06:14 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,FREEMAIL_FROM,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL,SPF_HELO_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from mout.gmx.net (mout.gmx.net [212.227.15.18]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 4E0C282887 for ; Mon, 18 Jan 2021 21:06:11 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1611000369; bh=yDPwcBPKYQ1egEIwvZv7afYmVXtUubD1EAR1j2HnfxM=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date; b=Ih+taYqIcV60FJMMiGmnOO+qx5qCZvVPzDbHrcK0y6YTKc3OCvD19U0hLHFWsz0Wl 0kxtM2vy/FViAhpBqGUKxvEsizKM+TNJSM1My9BzdK+Q/oMxGv2GEtnI6RGW43Hkfo 9Oqup4WOEt6HrArF3uLNbmv7qx0Wnxm5ZWCACudk= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from workstation4.fritz.box ([62.143.246.89]) by mail.gmx.com (mrgmx004 [212.227.17.184]) with ESMTPSA (Nemesis) id 1MRmfo-1lUcvL0VOU-00TEYR; Mon, 18 Jan 2021 21:06:09 +0100 From: Heinrich Schuchardt To: Tom Rini Cc: Jason Hobbs , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH 1/1] doc: move README.menu to HTML documentation Date: Mon, 18 Jan 2021 21:06:03 +0100 Message-Id: <20210118200603.37131-1-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.29.2 MIME-Version: 1.0 X-Provags-ID: V03:K1:LGJkGfcTR+V1AZ8YrMWYPEV0kzTi3RQofoENSJiqh5wnWOS5bc3 lWpNPcaGlortqRsWDvZB+4Cz4Q1bqmRPZRPAzba4lqqvk4BP33LMcDOUT0ujEV/zj4duRGh ohR89MzKJoUaBGewCRdDb8wAotkuR55GUQn3+opEXRHJ7UIhb54tcUYDpvpQySGzukQe+cx N7VCBWbRG/aTfejkcUsGw== X-UI-Out-Filterresults: notjunk:1;V03:K0:qYnoeky2NDE=:ZJzv/R1/CTFb1dgdPFl+Cs S0USnUUPXBo81cjHUInmIiVyMBwYvMfC2baXxYqVgFUNmpZiiOUsB1B0NsYupWNniR0b611/1 MB5KZcSxrkG1epmk/3ouH/TKg5tjXJ+bwphYkvTGZKU6AA/TAjNf0mYXIHyhDHQfviIBbpU/T K3V9+u3g2LFXeADUIH8cjISB77ImINHf4zbKD4jtV8orl86upARawYmdg9wPHj8SAFi0ARg/L Mvrnl86grFe/tp7XHBQl3cDykeHlUxrx8cDhAxmi0k+huf3/4JGC3qjDNe2uskxNPhx6XyBoS Eu/hlil0GgkHUoGmBilDqJ/FyGR1Jqw14j3Xm2u+ucEpJptiYkWq4U5A5Hkymh2h4JQogeses ewUw2twxGqksdDeuTOXPeVFNyX9Te6xnyZ6GZktymlW+lcYVvi3p2EvKZLH3jA2xTdxyu8yR8 jxT79+oCIU6ATxT8XSUqFJy7q2W4Zs+4aoGjapaO4e/PT4YfIlnzBaC4GysqgK9uVEp0riKF2 avDoLvqIgvNb8/budGp8YjFOwcBh1uGmLi6PsDlCl8D1dosZnZOKfIr0gh3/4jYqBUjEj80Zh ZHoWj1JZWIGK9M9/lqCKyNdEqq5fF5JFUju+w3a5A/oy/8s8TwZjA6ndsc2zjkKGdd8Hmhfoq eVEcWjkkaxKh9lEKxYZ332qLXnZu522HctDWcvZhf9lUvbyIWU3vgagAdPfOaHBMi2gdPyzyl pTfUTc58ZjRYjBoVTJgaWOow/pgeoUFiyxD+ZeI1wPO53J7wTRD2BPDeDZ3ybdvhvuiZ1P0vG 3D8RSi1Iw5eeNUnrTHLXVh5HtAZNHZs7oOsQEuYwRPM6AC6Pe9WCbVs4IdfDUIQ+Zrq/nixix 4TwKixU+w6m2deRHp0TA== X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 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.102.3 at phobos.denx.de X-Virus-Status: Clean Convert README.menu to reStructured text and add it to the HTML documentation. Signed-off-by: Heinrich Schuchardt --- doc/README.menu | 124 --------------------------------------- doc/develop/index.rst | 1 + doc/develop/menus.rst | 131 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 132 insertions(+), 124 deletions(-) delete mode 100644 doc/README.menu create mode 100644 doc/develop/menus.rst -- 2.29.2 diff --git a/doc/README.menu b/doc/README.menu deleted file mode 100644 index 0f3d741605..0000000000 --- a/doc/README.menu +++ /dev/null @@ -1,124 +0,0 @@ -SPDX-License-Identifier: GPL-2.0+ -/* - * Copyright 2010-2011 Calxeda, Inc. - */ - -U-Boot provides a set of interfaces for creating and using simple, text -based menus. Menus are displayed as lists of labeled entries on the -console, and an entry can be selected by entering its label. - -To use the menu code, enable CONFIG_MENU, and include "menu.h" where -the interfaces should be available. - -Menus are composed of items. Each item has a key used to identify it in -the menu, and an opaque pointer to data controlled by the consumer. - -If you want to show a menu, instead starting the shell, define -CONFIG_AUTOBOOT_MENU_SHOW. You have to code the int menu_show(int bootdelay) -function, which handle your menu. This function returns the remaining -bootdelay. - -Interfaces ----------- -#include "menu.h" - -/* - * Consumers of the menu interfaces will use a struct menu * as the - * handle for a menu. struct menu is only fully defined in menu.c, - * preventing consumers of the menu interfaces from accessing its - * contents directly. - */ -struct menu; - -/* - * NOTE: See comments in common/menu.c for more detailed documentation on - * these interfaces. - */ - -/* - * menu_create() - Creates a menu handle with default settings - */ -struct menu *menu_create(char *title, int timeout, int prompt, - void (*item_data_print)(void *), - char *(*item_choice)(void *), - void *item_choice_data); - -/* - * menu_item_add() - Adds or replaces a menu item - */ -int menu_item_add(struct menu *m, char *item_key, void *item_data); - -/* - * menu_default_set() - Sets the default choice for the menu - */ -int menu_default_set(struct menu *m, char *item_key); - -/* - * menu_default_choice() - Set *choice to point to the default item's data - */ -int menu_default_choice(struct menu *m, void **choice); - -/* - * menu_get_choice() - Returns the user's selected menu entry, or the - * default if the menu is set to not prompt or the timeout expires. - */ -int menu_get_choice(struct menu *m, void **choice); - -/* - * menu_destroy() - frees the memory used by a menu and its items. - */ -int menu_destroy(struct menu *m); - -/* - * menu_display_statusline(struct menu *m); - * shows a statusline for every menu_display call. - */ -void menu_display_statusline(struct menu *m); - -Example Code ------------- -This example creates a menu that always prompts, and allows the user -to pick from a list of tools. The item key and data are the same. - -#include "menu.h" - -char *tools[] = { - "Hammer", - "Screwdriver", - "Nail gun", - NULL -}; - -char *pick_a_tool(void) -{ - struct menu *m; - int i; - char *tool = NULL; - - m = menu_create("Tools", 0, 1, NULL); - - for(i = 0; tools[i]; i++) { - if (menu_item_add(m, tools[i], tools[i]) != 1) { - printf("failed to add item!"); - menu_destroy(m); - return NULL; - } - } - - if (menu_get_choice(m, (void **)&tool) != 1) - printf("Problem picking tool!\n"); - - menu_destroy(m); - - return tool; -} - -void caller(void) -{ - char *tool = pick_a_tool(); - - if (tool) { - printf("picked a tool: %s\n", tool); - use_tool(tool); - } -} diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 83eb1307ed..beaa64d8d9 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -12,6 +12,7 @@ Implementation commands global_data logging + menus Debugging --------- diff --git a/doc/develop/menus.rst b/doc/develop/menus.rst new file mode 100644 index 0000000000..dda8f963fb --- /dev/null +++ b/doc/develop/menus.rst @@ -0,0 +1,131 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright 2010-2011 Calxeda, Inc. + +Menus +===== + +U-Boot provides a set of interfaces for creating and using simple, text +based menus. Menus are displayed as lists of labeled entries on the +console, and an entry can be selected by entering its label. + +To use the menu code, enable CONFIG_MENU, and include "menu.h" where +the interfaces should be available. + +Menus are composed of items. Each item has a key used to identify it in +the menu, and an opaque pointer to data controlled by the consumer. + +If you want to show a menu, instead starting the shell, define +CONFIG_AUTOBOOT_MENU_SHOW. You have to code the int menu_show(int bootdelay) +function, which handle your menu. This function returns the remaining +bootdelay. + +Interfaces +---------- + +.. code-block:: c + + #include "menu.h" + + /* + * Consumers of the menu interfaces will use a struct menu * as the + * handle for a menu. struct menu is only fully defined in menu.c, + * preventing consumers of the menu interfaces from accessing its + * contents directly. + */ + struct menu; + + /* + * NOTE: See comments in common/menu.c for more detailed documentation on + * these interfaces. + */ + + /* + * menu_create() - Creates a menu handle with default settings + */ + struct menu *menu_create(char *title, int timeout, int prompt, + void (*item_data_print)(void *), + char *(*item_choice)(void *), + void *item_choice_data); + + /* + * menu_item_add() - Adds or replaces a menu item + */ + int menu_item_add(struct menu *m, char *item_key, void *item_data); + + /* + * menu_default_set() - Sets the default choice for the menu + */ + int menu_default_set(struct menu *m, char *item_key); + + /* + * menu_default_choice() - Set *choice to point to the default item's data + */ + int menu_default_choice(struct menu *m, void **choice); + + /* + * menu_get_choice() - Returns the user's selected menu entry, or the + * default if the menu is set to not prompt or the timeout expires. + */ + int menu_get_choice(struct menu *m, void **choice); + + /* + * menu_destroy() - frees the memory used by a menu and its items. + */ + int menu_destroy(struct menu *m); + + /* + * menu_display_statusline(struct menu *m); + * shows a statusline for every menu_display call. + */ + void menu_display_statusline(struct menu *m); + +Example Code +------------ + +This example creates a menu that always prompts, and allows the user +to pick from a list of tools. The item key and data are the same. + +.. code-block:: c + + #include "menu.h" + + char *tools[] = { + "Hammer", + "Screwdriver", + "Nail gun", + NULL + }; + + char *pick_a_tool(void) + { + struct menu *m; + int i; + char *tool = NULL; + + m = menu_create("Tools", 0, 1, NULL); + + for(i = 0; tools[i]; i++) { + if (menu_item_add(m, tools[i], tools[i]) != 1) { + printf("failed to add item!"); + menu_destroy(m); + return NULL; + } + } + + if (menu_get_choice(m, (void **)&tool) != 1) + printf("Problem picking tool!\n"); + + menu_destroy(m); + + return tool; + } + + void caller(void) + { + char *tool = pick_a_tool(); + + if (tool) { + printf("picked a tool: %s\n", tool); + use_tool(tool); + } + }