Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/patches/818798/?format=api
{ "id": 818798, "url": "http://patchwork.ozlabs.org/api/patches/818798/?format=api", "web_url": "http://patchwork.ozlabs.org/project/uboot/patch/20170926192142.42308-15-sjg@chromium.org/", "project": { "id": 18, "url": "http://patchwork.ozlabs.org/api/projects/18/?format=api", "name": "U-Boot", "link_name": "uboot", "list_id": "u-boot.lists.denx.de", "list_email": "u-boot@lists.denx.de", "web_url": null, "scm_url": null, "webscm_url": null, "list_archive_url": "", "list_archive_url_format": "", "commit_url_format": "" }, "msgid": "<20170926192142.42308-15-sjg@chromium.org>", "list_archive_url": null, "date": "2017-09-26T19:21:42", "name": "[U-Boot,v2,14/14] log: Add documentation", "commit_ref": null, "pull_url": null, "state": "superseded", "archived": false, "hash": "8322a4f58b9f1592b097dec76a96b6fd5a7bbef6", "submitter": { "id": 6170, "url": "http://patchwork.ozlabs.org/api/people/6170/?format=api", "name": "Simon Glass", "email": "sjg@chromium.org" }, "delegate": { "id": 3184, "url": "http://patchwork.ozlabs.org/api/users/3184/?format=api", "username": "sjg", "first_name": "Simon", "last_name": "Glass", "email": "sjg@chromium.org" }, "mbox": "http://patchwork.ozlabs.org/project/uboot/patch/20170926192142.42308-15-sjg@chromium.org/mbox/", "series": [ { "id": 5217, "url": "http://patchwork.ozlabs.org/api/series/5217/?format=api", "web_url": "http://patchwork.ozlabs.org/project/uboot/list/?series=5217", "date": "2017-09-26T19:21:28", "name": "log: Add a new logging feature", "version": 2, "mbox": "http://patchwork.ozlabs.org/series/5217/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/818798/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/818798/checks/", "tags": {}, "related": [], "headers": { "Return-Path": "<u-boot-bounces@lists.denx.de>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@bilbo.ozlabs.org", "Authentication-Results": [ "ozlabs.org;\n\tspf=none (mailfrom) smtp.mailfrom=lists.denx.de\n\t(client-ip=81.169.180.215; helo=lists.denx.de;\n\tenvelope-from=u-boot-bounces@lists.denx.de;\n\treceiver=<UNKNOWN>)", "ozlabs.org;\n\tdkim=fail reason=\"signature verification failed\" (2048-bit key;\n\tunprotected) header.d=google.com header.i=@google.com\n\theader.b=\"ou5xBMRN\"; dkim-atps=neutral" ], "Received": [ "from lists.denx.de (dione.denx.de [81.169.180.215])\n\tby ozlabs.org (Postfix) with ESMTP id 3y1rbv6Rnwz9t3F\n\tfor <incoming@patchwork.ozlabs.org>;\n\tWed, 27 Sep 2017 05:28:59 +1000 (AEST)", "by lists.denx.de (Postfix, from userid 105)\n\tid 52A62C21E57; Tue, 26 Sep 2017 19:26:56 +0000 (UTC)", "from lists.denx.de (localhost [IPv6:::1])\n\tby lists.denx.de (Postfix) with ESMTP id 1F81BC21F70;\n\tTue, 26 Sep 2017 19:24:51 +0000 (UTC)", "by lists.denx.de (Postfix, from userid 105)\n\tid 98D2FC21F7A; Tue, 26 Sep 2017 19:22:36 +0000 (UTC)", "from mail-oi0-f42.google.com (mail-oi0-f42.google.com\n\t[209.85.218.42])\n\tby lists.denx.de (Postfix) with ESMTPS id 29EF1C21F35\n\tfor <u-boot@lists.denx.de>; Tue, 26 Sep 2017 19:22:31 +0000 (UTC)", "by mail-oi0-f42.google.com with SMTP id w65so13466712oia.7\n\tfor <u-boot@lists.denx.de>; Tue, 26 Sep 2017 12:22:31 -0700 (PDT)", "from kiwi.bld.corp.google.com ([2620:0:10f2:0:c194:3fa6:8abc:2569])\n\tby smtp.gmail.com with ESMTPSA id\n\th8sm1547653ote.27.2017.09.26.12.22.28\n\t(version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);\n\tTue, 26 Sep 2017 12:22:28 -0700 (PDT)", "by kiwi.bld.corp.google.com (Postfix, from userid 121222)\n\tid A4054140B5C; Tue, 26 Sep 2017 13:22:27 -0600 (MDT)" ], "X-Spam-Checker-Version": "SpamAssassin 3.4.0 (2014-02-07) on lists.denx.de", "X-Spam-Level": "", "X-Spam-Status": "No, score=-0.0 required=5.0 tests=RCVD_IN_DNSWL_NONE,\n\tRCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL,\n\tT_DKIM_INVALID autolearn=unavailable\n\tautolearn_force=no version=3.4.0", "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com;\n\ts=20161025; \n\th=sender:from:to:cc:subject:date:message-id:in-reply-to:references;\n\tbh=vrksfC3LweOObicePKEeAd0XrD6n/4yU5eQ9t2mDtO4=;\n\tb=ou5xBMRN7g7yZ5tx8AqTpwxMr90g5mQ1rILsja+pp7HzRZwupBHESeY6doveExJ4t9\n\tUtOHoPWSPJwKPjiB8F539uPBkTH8KOZacFIh6kiOiFNiVm77A+3vAVhz9W2VstgbC1gw\n\txt0dKYQ0pOJnExLy+C3DqnM+1ffyOM3XKtdsyu7sB6eSm8Urh29FSRJjn+CH8RQbbJjv\n\tgR46sH8+q834UB13k1DKJjzD4bl+FzvGvSyBy7uAuRf7qQmfeHmHDBgEXn8+v546GpbD\n\tKiNnerPbnxIVbAVzCQG2ml/33aNAjp3HRX/l+8lW/fNjUall8fiklYZ8B8T/lLV3K16z\n\t5J+g==", "X-Google-DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:sender:from:to:cc:subject:date:message-id\n\t:in-reply-to:references;\n\tbh=vrksfC3LweOObicePKEeAd0XrD6n/4yU5eQ9t2mDtO4=;\n\tb=h+ZQdhxkmGxtZzrdewGkPXAvb+WtVPkuJKt8N5iDWc7VjFLlqGTSWY42cXPGtS5E7+\n\tKtuVUn/Nog8zoC6WzPkXJF3flAXTglUag2oVJ7VAQbbYxkXpYJYXTFnY4WtWt0oMhAJ+\n\te3OjUCkl2S12BxzVOHx8fkNNObClEJrZR6WWfotxLRX8o+dyufDl7cJUpUu94sfrTxXn\n\ti2h257BqpSNmTl8Wp/ZlVCVtaZO4uRQTjDEQrrzUC7cZrZj/W2zWTFAq/QLGgAtb0iOD\n\tFUnIGJ+s9+Imd7LF8yRz5IloOMoh0cetTNOIDDXcczUTuZcmtAWsadOUDYQo6+djN7bN\n\tp0UQ==", "X-Gm-Message-State": "AHPjjUhwpNbbYm5pypZUuduAMndafN3NITTCPKGtflLbCJsq/TkiJ3TC\n\tnXrPmdwODWDwzOjDxIxzm9NecQ==", "X-Google-Smtp-Source": "AOwi7QDmJYssWoH6DOCh6rvgkwmnTT4OJFf2OF070PrD4fjGisP++kB1a8aQY+jgB7imi00drOpLjA==", "X-Received": "by 10.157.21.83 with SMTP id z19mr2744402otz.351.1506453749583; \n\tTue, 26 Sep 2017 12:22:29 -0700 (PDT)", "From": "Simon Glass <sjg@chromium.org>", "To": "U-Boot Mailing List <u-boot@lists.denx.de>", "Date": "Tue, 26 Sep 2017 13:21:42 -0600", "Message-Id": "<20170926192142.42308-15-sjg@chromium.org>", "X-Mailer": "git-send-email 2.14.1.992.g2c7b836f3a-goog", "In-Reply-To": "<20170926192142.42308-1-sjg@chromium.org>", "References": "<20170926192142.42308-1-sjg@chromium.org>", "Cc": "Tom Rini <trini@konsulko.com>", "Subject": "[U-Boot] [PATCH v2 14/14] log: Add documentation", "X-BeenThere": "u-boot@lists.denx.de", "X-Mailman-Version": "2.1.18", "Precedence": "list", "List-Id": "U-Boot discussion <u-boot.lists.denx.de>", "List-Unsubscribe": "<https://lists.denx.de/options/u-boot>,\n\t<mailto:u-boot-request@lists.denx.de?subject=unsubscribe>", "List-Archive": "<http://lists.denx.de/pipermail/u-boot/>", "List-Post": "<mailto:u-boot@lists.denx.de>", "List-Help": "<mailto:u-boot-request@lists.denx.de?subject=help>", "List-Subscribe": "<https://lists.denx.de/listinfo/u-boot>,\n\t<mailto:u-boot-request@lists.denx.de?subject=subscribe>", "MIME-Version": "1.0", "Content-Type": "text/plain; charset=\"utf-8\"", "Content-Transfer-Encoding": "base64", "Errors-To": "u-boot-bounces@lists.denx.de", "Sender": "\"U-Boot\" <u-boot-bounces@lists.denx.de>" }, "content": "Add documentation for the log system.\n\nSigned-off-by: Simon Glass <sjg@chromium.org>\nReviewed-by: Bin Meng <bmeng.cn@gmail.com>\n---\n\nChanges in v2:\n- Drop the special log() functions from the README\n\n doc/README.log | 214 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++\n 1 file changed, 214 insertions(+)\n create mode 100644 doc/README.log", "diff": "diff --git a/doc/README.log b/doc/README.log\nnew file mode 100644\nindex 0000000000..f653fe7d79\n--- /dev/null\n+++ b/doc/README.log\n@@ -0,0 +1,214 @@\n+Logging in U-Boot\n+=================\n+\n+Introduction\n+------------\n+\n+U-Boot's internal operation involves many different steps and actions. From\n+setting up the board to displaying a start-up screen to loading an Operating\n+System, there are many component parts each with many actions.\n+\n+Most of the time this internal detail is not useful. Displaying it on the\n+console would delay booting (U-Boot's primary purpose) and confuse users.\n+\n+But for digging into what is happening in a particular area, or for debugging\n+a problem it is often useful to see what U-Boot is doing in more detail than\n+is visible from the basic console output.\n+\n+U-Boot's logging feature aims to satisfy this goal for both users and\n+developers.\n+\n+\n+Logging levels\n+--------------\n+\n+There are a number logging levels available, in increasing order of verbosity:\n+\n+ LOGL_EMERG\t- Printed before U-Boot halts\n+ LOGL_ALERT\t- Indicates action must be taken immediate or U-Boot will crash\n+ LOGL_CRIT\t- Indicates a critical error that will cause boot failure\n+ LOGL_ERR\t- Indicates an error that may cause boot failure\n+ LOGL_WARNING\t- Warning about an unexpected condition\n+ LOGL_NOTE\t- Important information about progress\n+ LOGL_INFO\t- Information about normal boot progress\n+ LOGL_DEBUG\t- Debug information (useful for debugging a driver or subsystem)\n+ LOGL_DEBUG_CONTENT\t- Debug message showing full message content\n+ LOGL_DEBUG_IO\t- Debug message showing hardware I/O access\n+\n+\n+Logging category\n+----------------\n+\n+Logging can come from a wide variety of places within U-Boot. Each log message\n+has a category which is intended to allow messages to be filtered according to\n+their source.\n+\n+The following main categories are defined:\n+\n+ LOGC_NONE\t- Unknown category (e.g. a debug() statement)\n+ UCLASS_...\t- Related to a particular uclass (e.g. UCLASS_USB)\n+ LOGC_ARCH\t- Related to architecture-specific code\n+ LOGC_BOARD\t- Related to board-specific code\n+ LOGC_CORE\t- Related to core driver-model support\n+ LOGC_DT\t- Related to device tree control\n+\n+\n+Enabling logging\n+----------------\n+\n+The following options are used to enable logging at compile time:\n+\n+ CONFIG_LOG\t\t- Enables the logging system\n+ CONFIG_MAX_LOG_LEVEL - Max log level to build (anything higher is compiled\n+\t\t\t\tout)\n+ CONFIG_LOG_CONSOLE\t- Enable writing log records to the console\n+\n+If CONFIG_LOG is not set, then no logging will be available.\n+\n+The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL.\n+\n+\n+Using DEBUG\n+-----------\n+\n+U-Boot has traditionally used a #define called DEBUG to enable debugging on a\n+file-by-file basis. The debug() macro compiles to a printf() statement if\n+DEBUG is enabled, and an empty statement if not.\n+\n+With logging enabled, debug() statements are interpreted as logging output\n+with a level of LOGL_DEBUG and a category of LOGC_NONE.\n+\n+The logging facilities are intended to replace DEBUG, but if DEBUG is defined\n+at the top of a file, then it takes precedence. This means that debug()\n+statements will result in output to the console and this output will not be\n+logged.\n+\n+\n+Logging destinations\n+--------------------\n+\n+If logging information goes nowhere then it serves no purpose. U-Boot provides\n+several possible determinations for logging information, all of which can be\n+enabled or disabled independently:\n+\n+ console - goes to stdout\n+\n+\n+Filters\n+-------\n+\n+Filters are attached to log drivers to control what those drivers emit. Only\n+records that pass through the filter make it to the driver.\n+\n+Filters can be based on several criteria:\n+\n+ - maximum log level\n+ - in a set of categories\n+ - in a set of files\n+\n+If no filters are attached to a driver then a default filter is used, which\n+limits output to records with a level less than CONFIG_LOG_MAX_LEVEL.\n+\n+\n+Logging statements\n+------------------\n+\n+The main logging function is:\n+\n+ log(category, level, format_string, ...)\n+\n+Also debug() and error() will generate log records - these use LOG_CATEGORY\n+as the category, so you should #define this right at the top of the source\n+file to ensure the category is correct.\n+\n+\n+Code size\n+---------\n+\n+Code size impact depends largely on what is enabled. The following numbers are\n+for snow, which is a Thumb-2 board:\n+\n+This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0\n+CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0\n+CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0\n+\n+The last option turns every debug() statement into a logging call, which\n+bloats the code hugely. The advantage is that it is then possible to enable\n+all logging within U-Boot.\n+\n+\n+To Do\n+-----\n+\n+There are lots of useful additions that could be made. None of the below is\n+implemented! If you do one, please add a test in test/py/tests/test_log.py\n+\n+Convenience functions to support setting the category:\n+\n+ log_arch(level, format_string, ...) - category LOGC_ARCH\n+ log_board(level, format_string, ...) - category LOGC_BOARD\n+ log_core(level, format_string, ...) - category LOGC_CORE\n+ log_dt(level, format_string, ...) - category LOGC_DT\n+\n+Convenience functions to support a category defined for a single file, for\n+example:\n+\n+ #define LOG_CATEGORY UCLASS_USB\n+\n+all of these can use LOG_CATEGORY as the category, and a log level\n+corresponding to the function name:\n+\n+ logc(level, format_string, ...)\n+\n+More logging destinations:\n+\n+ device - goes to a device (e.g. serial)\n+ buffer - recorded in a memory buffer\n+\n+Convert debug() statements in the code to log() statements\n+\n+Support making printf() emit log statements a L_INFO level\n+\n+Convert error() statements in the code to log() statements\n+\n+Figure out what to do with BUG(), BUG_ON() and warn_non_spl()\n+\n+Figure out what to do with assert()\n+\n+Add a way to browse log records\n+\n+Add a way to record log records for browsing using an external tool\n+\n+Add commands to add and remove filters\n+\n+Add commands to add and remove log devices\n+\n+Allow sharing of printf format strings in log records to reduce storage size\n+for large numbers of log records\n+\n+Add a command-line option to sandbox to set the default logging level\n+\n+Convert core driver model code to use logging\n+\n+Convert uclasses to use logging with the correct category\n+\n+Consider making log() calls emit an automatic newline, perhaps with a logn()\n+ function to avoid that\n+\n+Passing log records through to linux (e.g. via device tree /chosen)\n+\n+Provide a command to access the number of log records generated, and the\n+number dropped due to them being generated before the log system was ready.\n+\n+Add a printf() format string pragma so that log statements are checked properly\n+\n+Enhance the log console driver to show level / category / file / line\n+information\n+\n+Add a command to add new log records and delete existing records.\n+\n+Provide additional log() functions - e.g. logc() to specify the category\n+\n+--\n+Simon Glass <sjg@chromium.org>\n+15-Sep-17\n", "prefixes": [ "U-Boot", "v2", "14/14" ] }