From patchwork Sat Sep 16 21:23:26 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Simon Glass X-Patchwork-Id: 814559 X-Patchwork-Delegate: sjg@chromium.org Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=lists.denx.de (client-ip=81.169.180.215; helo=lists.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=google.com header.i=@google.com header.b="jyodQwJR"; dkim-atps=neutral Received: from lists.denx.de (dione.denx.de [81.169.180.215]) by ozlabs.org (Postfix) with ESMTP id 3xvlmV3tNHz9sPr for ; Sun, 17 Sep 2017 07:30:18 +1000 (AEST) Received: by lists.denx.de (Postfix, from userid 105) id 45F4DC21DDE; Sat, 16 Sep 2017 21:27:15 +0000 (UTC) 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, RCVD_IN_MSPIKE_H2, T_DKIM_INVALID autolearn=unavailable autolearn_force=no version=3.4.0 Received: from lists.denx.de (localhost [IPv6:::1]) by lists.denx.de (Postfix) with ESMTP id 47A8DC21DA1; Sat, 16 Sep 2017 21:25:46 +0000 (UTC) Received: by lists.denx.de (Postfix, from userid 105) id 0F19DC21D63; Sat, 16 Sep 2017 21:24:23 +0000 (UTC) Received: from mail-oi0-f44.google.com (mail-oi0-f44.google.com [209.85.218.44]) by lists.denx.de (Postfix) with ESMTPS id 1C3ECC21DCE for ; Sat, 16 Sep 2017 21:24:20 +0000 (UTC) Received: by mail-oi0-f44.google.com with SMTP id v66so2372352oig.5 for ; Sat, 16 Sep 2017 14:24:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references; bh=mvvIOIERR+c2AI1tQjTCoPHy52He1JqgtBRBI+OaLj4=; b=jyodQwJRcn+tFZo5+JxLihVHr/UwvexWccZHsHo71YSv+DVRmtSwYdMtcKNhTAPMhi WQwUbUaHDRoqtm3Q9SGnYG2FkXpTp6/E7XWGyYk0pAdQZE7UmtUajuHK/ZBU4Lh7XMk9 Qy9l8UPiHBx2mIY1mWU1wYYUvuyb3eSE0YGkTPQAvOdeYeTcn676hSE1xWapEseXsNOS pFpcY0f2hTJyUgqZEU/z68H2YekfJiObPzu15gBIRzL19555dj7YceTMteVA1K1IzQVm qZ4+IcgT4I96S49R+k3M9m45R+MaUAWqudNp59VHriiNwlmcAFprNinpRqT44qV5bje7 OWcg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references; bh=mvvIOIERR+c2AI1tQjTCoPHy52He1JqgtBRBI+OaLj4=; b=tkJL0Q8bxSINP2eX8OSh1ejGPEBpHuP6wzzCXR9T+XwDTZTF/Y7x9Z2laGEHzuqkXu QND31tdIFaA6aGyXcK8eIpVhMkjjMOJSljLM6u8eRzcTszgoYPx1tLpsODQ3b7h4DY1P /gwBWVQed1oOq0NT+2etql4q9cEeh/kRg13SXOpDabGJhOIYAOmksRUi7uidLch3qwNO BBkyC2MFDUabwZIaKYa5VuDWCiYi9nx5mJ/rUQNdmDPb/orCHzOub7yQBFkAoIxke5Mv i0vTUFIH31IV/QxsiEclqJETvaHjdQUeoRj/iLZQPHdNOiv9fnj29UKY28be5t+COqbV Itmg== X-Gm-Message-State: AHPjjUg/KwGMbShlO8jj1XsKswu4QOBy0cQr8iAWgVT9TET26Nlvfrnq AZKJk2d48+v1bz/Ny/4vfA== X-Google-Smtp-Source: AOwi7QBsKTXFbz5rU7aF/5eNa0pPwkj2YBMWqEK8tAR2u9gwG95n1kqMqa9xjkHlJOXXXJe0Xk23Bw== X-Received: by 10.202.58.2 with SMTP id h2mr12022557oia.38.1505597058572; Sat, 16 Sep 2017 14:24:18 -0700 (PDT) Received: from kiwi.bld.corp.google.com ([100.101.164.89]) by smtp.gmail.com with ESMTPSA id 199sm597664oie.58.2017.09.16.14.24.15 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 16 Sep 2017 14:24:15 -0700 (PDT) Received: by kiwi.bld.corp.google.com (Postfix, from userid 121222) id 3A48C140DF1; Sat, 16 Sep 2017 15:24:15 -0600 (MDT) From: Simon Glass To: U-Boot Mailing List Date: Sat, 16 Sep 2017 15:23:26 -0600 Message-Id: <20170916212331.170463-14-sjg@chromium.org> X-Mailer: git-send-email 2.14.1.690.gbb1197296e-goog In-Reply-To: <20170916212331.170463-1-sjg@chromium.org> References: <20170916212331.170463-1-sjg@chromium.org> Cc: Tom Rini Subject: [U-Boot] [PATCH 13/13] log: Add documentation X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.18 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" Add documentation for the log system. Signed-off-by: Simon Glass Reviewed-by: Bin Meng --- doc/README.log | 220 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 doc/README.log diff --git a/doc/README.log b/doc/README.log new file mode 100644 index 0000000000..0f2d8b84dd --- /dev/null +++ b/doc/README.log @@ -0,0 +1,220 @@ +Logging in U-Boot +================= + +Introduction +------------ + +U-Boot's internal operation involves many different steps and actions. From +setting up the board to displaying a start-up screen to loading an Operating +System, there are many component parts each with many actions. + +Most of the time this internal detail is not useful. Displaying it on the +console would delay booting (U-Boot's primary purpose) and confuse users. + +But for digging into what is happening in a particular area, or for debugging +a problem it is often useful to see what U-Boot is doing in more detail than +is visible from the basic console output. + +U-Boot's logging feature aims to satisfy this goal for both users and +developers. + + +Logging levels +-------------- + +There are a number logging levels available, in increasing order of verbosity: + + LOGL_PANIC - Printed before U-Boot halts + LOGL_CRIT - Indicates a critical error that will cause boot failure + LOGL_ERR - Indicates an error that may cause boot failure + LOGL_WARN - Warning about an unexpected condition + LOGL_NOTE - Important information about progress + LOGL_INFO - Information about normal boot progress + LOGL_DETAIL - Detailed information (e.g. internal operation of drivers) + LOGL_DEBUG - Debug information (useful for debugging a driver or subsystem) + + +Logging category +---------------- + +Logging can come from a wide variety of places within U-Boot. Each log message +has a category which is intended to allow messages to be filtered according to +their source. + +The following main categories are defined: + + LOGC_NONE - Unknown category (e.g. a debug() statement) + UCLASS_... - Related to a particular uclass (e.g. UCLASS_USB) + LOGC_ARCH - Related to architecture-specific code + LOGC_BOARD - Related to board-specific code + LOGC_CORE - Related to core driver-model support + LOGC_DT - Related to device tree control + + +Enabling logging +---------------- + +The following options are used to enable logging at compile time: + + CONFIG_LOG - Enables the logging system + CONFIG_MAX_LOG_LEVEL - Max log level to build (anything higher is compiled + out) + CONFIG_LOG_CONSOLE - Enable writing log records to the console + +If CONFIG_LOG is not set, then no logging will be available. + +The above have SPL versions also, e.g. CONFIG_SPL_MAX_LOG_LEVEL. + + +Using DEBUG +----------- + +U-Boot has traditionally used a #define called DEBUG to enable debugging on a +file-by-file basis. The debug() macro compiles to a printf() statement if +DEBUG is enabled, and an empty statement if not. + +With logging enabled, debug() statements are interpreted as logging output +with a level of LOGL_DEBUG and a category of LOGC_NONE. + +The logging facilities are intended to replace DEBUG, but if DEBUG is defined +at the top of a file, then it takes precedence. This means that debug() +statements will result in output to the console and this output will not be +logged. + + +Logging destinations +-------------------- + +If logging information goes nowhere then it serves no purpose. U-Boot provides +several possible determinations for logging information, all of which can be +enabled or disabled independently: + + console - goes to stdout + + +Filters +------- + +Filters are attached to log drivers to control what those drivers emit. Only +records that pass through the filter make it to the driver. + +Filters can be based on several criteria: + + - maximum log level + - in a set of categories + - in a set of files + +If no filters are attached to a driver then a default filter is used, which +limits output to records with a level less than CONFIG_LOG_MAX_LEVEL. + + +Logging statements +------------------ + +The main logging function is: + + log(category, level, format_string, ...) + +Also debug() and error() will generate log records - these use LOG_CATEGORY +as the category, so you should #define this right at the top of the source +file to ensure the category is correct. + + +Code size +--------- + +Code size impact depends largely on what is enabled. The following numbers are +for snow, which is a Thumb-2 board: + +This series: adds bss +20.0 data +4.0 rodata +4.0 text +44.0 +CONFIG_LOG: bss -52.0 data +92.0 rodata -635.0 text +1048.0 +CONFIG_LOG_MAX_LEVEL=7: bss +188.0 data +4.0 rodata +49183.0 text +98124.0 + +The last option turns every debug() statement into a logging call, which +bloats the code hugely. The advantage is that it is then possible to enable +all logging within U-Boot. + + +To Do +----- + +There are lots of useful additions that could be made. None of the below is +implemented! If you do one, please add a test in test/py/tests/test_log.py + +Convenience functions to support setting the category: + + log_arch(level, format_string, ...) - category LOGC_ARCH + log_board(level, format_string, ...) - category LOGC_BOARD + log_core(level, format_string, ...) - category LOGC_CORE + log_dt(level, format_string, ...) - category LOGC_DT + +Convenience functions to support a category defined for a single file, for +example: + + #define LOG_CATEGORY UCLASS_USB + +all of these can use LOG_CATEGORY as the category, and a log level +corresponding to the function name: + + logc(level, format_string, ...) + pr_panic(format_string, ...) + pr_crit(format_string, ...) + pr_err(format_string, ...) + pr_warn(format_string, ...) + pr_note(format_string, ...) + pr_info(format_string, ...) + pr_detail(format_string, ...) + pr_debug(format_string, ...) + +More logging destinations: + + device - goes to a device (e.g. serial) + buffer - recorded in a memory buffer + +Convert debug() statements in the code to log() statements + +Support making printf() emit log statements a L_INFO level + +Convert error() statements in the code to log() statements + +Figure out what to do with BUG(), BUG_ON() and warn_non_spl() + +Figure out what to do with assert() + +Add a way to browse log records + +Add a way to record log records for browsing using an external tool + +Add commands to add and remove filters + +Add commands to add and remove log devices + +Allow sharing of printf format strings in log records to reduce storage size +for large numbers of log records + +Add a command-line option to sandbox to set the default logging level + +Convert core driver model code to use logging + +Convert uclasses to use logging with the correct category + +Consider making log() calls emit an automatic newline, perhaps with a logn() + function to avoid that + +Passing log records through to linux (e.g. via device tree /chosen) + +Provide a command to access the number of log records generated, and the +number dropped due to them being generated before the log system was ready. + +Add a printf() format string pragma so that log statements are checked properly + +Enhance the log console driver to show level / category / file / line +information + +Add a command to add new log records and delete existing records. + +Provide additional log() functions - e.g. logc() to specify the category + +-- +Simon Glass +15-Sep-17