From patchwork Mon Sep 14 08:12:19 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Heinrich Schuchardt X-Patchwork-Id: 1363396 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; dmarc=none (p=none dis=none) header.from=gmx.de 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=U6hIyYzj; 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 4BqfH54VfPz9sTM for ; Mon, 14 Sep 2020 18:12:33 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id D8B8081996; Mon, 14 Sep 2020 10:12:30 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (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="U6hIyYzj"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 0482481BDF; Mon, 14 Sep 2020 10:12:30 +0200 (CEST) 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_MSPIKE_H2,SPF_HELO_NONE,URIBL_BLOCKED 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 0D0658174F for ; Mon, 14 Sep 2020 10:12:27 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=none (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=1600071144; bh=5FLmwi4mUskrRIRCd61kosy40c1eFpNvHbiBLXcbsQ0=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date; b=U6hIyYzjqxHwESul5KVaOpVpvyu4mUrlP//TQe/LhjFoKJJmUc5L6KB7FZ7zIUasQ kIAWrMYtMYkYde1zn7gYAO+uPDBBPINnkybxTuCTEPkPOblgFaCqVca+SQg4S62MPy ZLz6Q+XXKfaWaRzASPdlDv2kl/KCWXwVJx7PZq34= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from LT02.fritz.box ([178.202.41.107]) by mail.gmx.com (mrgmx005 [212.227.17.184]) with ESMTPSA (Nemesis) id 1Mf0BM-1kjwoM0iew-00gcXE; Mon, 14 Sep 2020 10:12:24 +0200 From: Heinrich Schuchardt To: Tom Rini Cc: Simon Glass , Patrick Delaunay , u-boot@lists.denx.de, Heinrich Schuchardt Subject: [PATCH 1/1] doc: remove redundant doc/README.log Date: Mon, 14 Sep 2020 10:12:19 +0200 Message-Id: <20200914081219.119188-1-xypron.glpk@gmx.de> X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 X-Provags-ID: V03:K1:Z6gtlwCBTbPjPZw4bLVr19muCoLkacPR2mrUMRvG7D0eooB6qxB pA5lGymQSOCpVP74Whvp7tOkr1twYrTU7M+RfotI0whPpVG0Z1Q444amdb1nfEuFNcYKyVr a1N84uwS49YDpxfCvCPmf8qZW+Tvc6yfekOrK0e3QmNYUb2pP79zNw/aABndwpX+rl5zCzu f0Od+e/9vpMThwrNnOyQw== X-UI-Out-Filterresults: notjunk:1;V03:K0:3iZF97hxjAg=:mf6UZbx+o6TszV18eDSRf2 A3n1+f3TtIDC8vZ/iSHd0XHxblfMUNTaYgTqPPrmijGWlPvQ2+xNiCSBR9X/7DVLhhi9jyfdD PWC5HdFxSNmxTMt3bEcQ1DbugAN7Dqq4oMjO9owDhcJDq1MRzfno/7SpPCx9mpyRrdI15Dzv/ LDYqzz3ugI7FZ/kJu0z4L7Ba3zDcz4Oi2KDjVtKPYT3DadLdEAVcwVwhWZOdaSLnK5JVVxYYo R41gMFk3i08Mepahyfn6xfV9aU6FJxAmF8A/2NwXJATsmmeTON10Wv63YBVyqgsgmanHP7z+W w3SKb/EzqvuOk3ndb48rvAienXkT6L00QfZOF5Rg0oD4ESh/QqcbD0tnTlEyr77qvAWCptDRS Y3K19G/aEMXVI+fqfbBEpSByiF3pw5jajpJbfNinJH0WZO7c0HP/AnrCMAbVkYO2SBxJiXy5h iaRZ8Aoxs3N1NLLy0mUeoDsJwa74LtaH89wHagpVU4y4q+IOMvXu+VUsb+fbz1ZZsc0tLCgwl TXdPnzaefUZ4LYAa+ymeDDmloi50vH0cjaXpdLGfJLcJAXY+ULGmPDEe3P3RgICnq8HfLj/8R k/WxHSy8rWspQNNnSBrWIOViPGt0yuPtxY84/WjhWUQFLhA+uZU7UMjNuLMzkWmPuTaBGj4hj aImJRfaZPJIoPkyqELSJ4n8OzoNmkLemewFfX6Db2zqFvsFXQH57lEjh5lZvq0jM/OXZJnAR1 0TE9Iv2dHHLxnVBUZVJ188T9ytRee1uRc9Si0HVTgK+YMv9eCb/9jq3kULltBOKchrysYNaNa X9A+cPO3bCTIUxgSRUfOxwvWgb3uxxCZTLuq0Bm3mO5LIf4mG9oAQbziY5F0AjGWG7cXWXJ1R nFLKGWT6yZ+nWrxtD3UwaC7PAq/kYUbWO6K1DqVAWMXOh9f+aVllbZCAoiczXLdufMEgoPcW+ AfuIJP9ff1/TjLtPAdWOKt3hFsyTGpZoYarXmQ4A3qek3x4OZzK3OdMqFSWjJAZVuPj6C1DkE NuUIxIVieMHCf8DZ5pQhC/JSF/GCCOS3seSvdsdJqb6LUB6f47AqYd8xGuFaImQrYBBIQ4qSD hUdAYEHoaQ4mbNG/806SzFE2438rRZTo7t/j7aun/dEDbRqXKCF1CEC3p8/ToLdnp5zolFR1c ra1fIcDs9KhW/DTlQl4JrQRIx+4hJ0KPIZTIMnM1v9mPJvXx204/ZyoC0L5bAB9t0y5ptq91B fDYCTw2XNCMeD3kUb3OBxNPrcrx3QNh42WD5vGQ== 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 doc/README.log was already moved to doc/develop/logging.rst but has been recreated by an incorrect merge. Signed-off-by: Heinrich Schuchardt Reviewed-by: Simon Glass --- doc/README.log | 286 ------------------------------------------------- 1 file changed, 286 deletions(-) delete mode 100644 doc/README.log -- 2.28.0 diff --git a/doc/README.log b/doc/README.log deleted file mode 100644 index ba838824a9..0000000000 --- a/doc/README.log +++ /dev/null @@ -1,286 +0,0 @@ -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_EMERG - Printed before U-Boot halts - LOGL_ALERT - Indicates action must be taken immediate or U-Boot will crash - LOGL_CRIT - Indicates a critical error that will cause boot failure - LOGL_ERR - Indicates an error that may cause boot failure - LOGL_WARNING - Warning about an unexpected condition - LOGL_NOTE - Important information about progress - LOGL_INFO - Information about normal boot progress - LOGL_DEBUG - Debug information (useful for debugging a driver or subsystem) - LOGL_DEBUG_CONTENT - Debug message showing full message content - LOGL_DEBUG_IO - Debug message showing hardware I/O access - - -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 - LOGC_EFI - Related to EFI implementation - - -Enabling logging ----------------- - -The following options are used to enable logging at compile time: - - CONFIG_LOG - Enables the logging system - CONFIG_LOG_MAX_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 and TPL versions also, e.g. CONFIG_SPL_LOG_MAX_LEVEL and -CONFIG_TPL_LOG_MAX_LEVEL. - - -Temporary logging within a single file --------------------------------------- - -Sometimes it is useful to turn on logging just in one file. You can use this: - - #define LOG_DEBUG - -to enable building in of all logging statements in a single file. Put it at -the top of the file, before any #includes. - -To actually get U-Boot to output this you need to also set the default logging -level - e.g. set CONFIG_LOG_DEFAULT_LEVEL to 7 (LOGL_DEBUG) or more. Otherwise -debug output is suppressed and will not be generated. - - -Convenience functions ---------------------- - -A number of convenience functions are available to shorten the code needed -for logging: - - log_err(_fmt...) - log_warning(_fmt...) - log_notice(_fmt...) - log_info(_fmt...) - log_debug(_fmt...) - log_content(_fmt...) - log_io(_fmt...) - -With these the log level is implicit in the name. The category is set by -LOG_CATEGORY, which you can only define once per file, above all #includes: - - #define LOG_CATEGORY LOGC_ALLOC - -or - - #define LOG_CATEGORY UCLASS_SPI - -Remember that all uclasses IDs are log categories too. - - -Log commands ------------- - -The 'log' command provides access to several features: - - level - access the default log level - format - access the console log format - rec - output a log record - test - run tests - -Type 'help log' for details. - - -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 - syslog - broadcast RFC 3164 messages to syslog servers on UDP port 514 - -The syslog driver sends the value of environmental variable 'log_hostname' as -HOSTNAME if available. - -Log format ----------- - -You can control the log format using the 'log format' command. The basic -format is: - - LEVEL.category,file.c:123-func() message - -In the above, file.c:123 is the filename where the log record was generated and -func() is the function name. By default ('log format default') only the -function name and message are displayed on the console. You can control which -fields are present, but not the field order. - - -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. - -You can also define CONFIG_LOG_ERROR_RETURN to enable the log_ret() macro. This -can be used whenever your function returns an error value: - - return log_ret(uclass_first_device(UCLASS_MMC, &dev)); - -This will write a log record when an error code is detected (a value < 0). This -can make it easier to trace errors that are generated deep in the call stack. - - -Code size ---------- - -Code size impact depends largely on what is enabled. The following numbers are -generated by 'buildman -S' for snow, which is a Thumb-2 board (all units in -bytes): - -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 - -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