You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/03/19 08:35:44 UTC
[6/6] incubator-mynewt-site git commit: minor formatting edits to
logs and stats docs.
minor formatting edits to logs and stats docs.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/ecbbe76a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/ecbbe76a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/ecbbe76a
Branch: refs/heads/master
Commit: ecbbe76a17f59732a182a03cda7fe5d79a488193
Parents: 0959206
Author: aditihilbert <ad...@runtime.io>
Authored: Sat Mar 19 00:35:33 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Sat Mar 19 00:35:33 2016 -0700
----------------------------------------------------------------------
docs/os/modules/logs/logs.md | 59 ++++++++++++++---------
docs/os/modules/stats/stats.md | 94 ++++++++++++++++++++++++++++---------
2 files changed, 110 insertions(+), 43 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ecbbe76a/docs/os/modules/logs/logs.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/logs/logs.md b/docs/os/modules/logs/logs.md
index bfbb5cf..7da1a77 100644
--- a/docs/os/modules/logs/logs.md
+++ b/docs/os/modules/logs/logs.md
@@ -1,17 +1,21 @@
-# Mynewt Logging
+## Mynewt Logging
-Mynewt has a logging package (`apache-mynewt-core/sys/log`) to support
-logging of information within a mynewt application.
+Apache Mynewt has a logging package (`apache-mynewt-core/sys/log`) to support
+logging of information within a Mynewt application.
-#Description
+<br>
+
+###Description
Logging API is provided in `apache-mynewt-core/sys/log/include/log/log.h`.
It allows packages to define their own log streams with separate
-names. It also allows application to control the output destinations
+names. It also allows an application to control the output destinations
of logs.
-## Compile Time Settings
+<br>
+
+#### Compile Time Settings
To save space at compile time, there is a compile time log level that
includes/excludes certain logs at compile time, saving image space. For
@@ -37,32 +41,36 @@ or
would both set the compile-time log level to `LOG_LEVEL_ERROR`. All logs
of less than `LOG_LEVEL_ERROR` severity would be disabled at compile
-time and take no space within the mynewt application image.
+time and take no space within the Mynewt application image.
These compile time settings are applicable to all logs registered with the
system.
-## Log
+<br>
+
+### Log
Each log stream requires a log structure to define its logging properties.
-Its typical for modules to extern this structure.
+It is typical for modules to extern this structure.
-## Log Handler
+<br>
+
+### Log Handler
To use logs, a log-handler is required, which is responsible for handling
-the I/O from the log. The log package comes with two pre-build log handlers
+the I/O from the log. The log package comes with two pre-built log handlers.
* console -- streams log events directly to the console port. Does
not support walking and reading.
* cbmem -- writes/reads log events to a circular buffer. Supports walking
-and reading for access by newtmgr and shell commands.
+and reading for access by `newtmgr` and shell commands.
-In addition, its possible to create custom log handlers for other methods.
-Example may include
+In addition, it is possible to create custom log handlers for other methods.
+Examples may include
* Flash file system
* Flat flash buffer
-* streamed over some other interface
+* Streamed over some other interface
To use logging, you will not typically need to create your own log handler.
You can use one of the two supplied above.
@@ -71,9 +79,11 @@ In Mynewt today, each module will register its logs with a default log handler.
Its up to the application to use or override this log handler for its
specific purposes. See below for an example.
-## Typical use of logging when writing an application
+<br>
+
+### Typical use of logging when writing an application
-When writing an application that is using others log modules, you
+When writing an application that is using other's log modules, you
may want to override their log handlers and log levels.
Add the logging to your package file.
@@ -83,9 +93,11 @@ Add the logging to your package file.
- "@apache-mynewt-core/sys/log"
```
+<br>
+
Initialize the logs in your startup code. It may look like this
-```no-highlight
+```c
#include <module1/module1.h>
#include <module3/module2.h>
#include <module3/module3.h>
@@ -116,22 +128,25 @@ void app_log_init(void)
}
```
+<br>
-## Typical use of Logging when writing a module
+### Typical use of Logging when writing a module
When creating a package using its own logging, you can have this type of
structure.
-```no-highlight
+```c
/* my_package.h*/
/* pick a unique name here */
extern struct log my_log;
```
-with an implementation in your module that looks like this
+<br>
-```no-highlight
+with an implementation in your module that looks like this:
+
+```c
/* my_package.c */
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ecbbe76a/docs/os/modules/stats/stats.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/stats/stats.md b/docs/os/modules/stats/stats.md
index 802604b..d4a9911 100644
--- a/docs/os/modules/stats/stats.md
+++ b/docs/os/modules/stats/stats.md
@@ -2,40 +2,56 @@
# Statistics Module
The statistics module allows application, libraries, or drivers to
-record statistics that can be shown via newtmgr and console.
+record statistics that can be shown via the Newtmgr tool and console.
This allows easy integration of statistics for troubleshooting,
maintenance, and usage monitoring.
By creating and registering your statistics, they are automatically
-included in the newtmgr shell and console APIs.
+included in the Newtmgr shell and console APIs.
### Implementation Details
A statistic is an unsigned integer that can be set by the
-code. When building your stats, the implementer chooses the size of the
-statistic from depending on the frequency of the statistic and the
+code. When building stats, the implementer chooses the size of the
+statistic depending on the frequency of the statistic and the
resolution required before the counter wraps.
-Typically the statistics are incremented upon code events, but they are
+Typically the stats are incremented upon code events; however, they are
not limted to that purpose.
Stats are organized into sections. Each section of stats has its own
name and can be queried separately through the API. Each section of stats
also has its own statistic size, allowing the user to separate large (64-bit)
-statistics from small (16 bit statistics). NOTE: its not currently possible
+statistics from small (16 bit statistics). NOTE: It is not currently possible
to group different size stats into the same section. Please ensure all stats
-in the section have the same size.
+in a section have the same size.
Stats sections are currently stored in a single global stats group.
-The statistics are stored in a simple structure which contains a small
-stats header followed by a list of statistics. The stats header contains:
-
-### Compile Time Options
+Statistics are stored in a simple structure which contains a small
+stats header followed by a list of stats. The stats header contains:
+
+```c
+struct stats_hdr {
+ char *s_name;
+ uint8_t s_size;
+ uint8_t s_cnt;
+ uint16_t s_pad1;
+ #ifdef STATS_NAME_ENABLE
+ struct stats_name_map *s_map;
+ int s_map_cnt;
+ #endif
+ STAILQ_ENTRY(stats_hdr) s_next;
+ };
+ ```
+
+ <br>
+
+#### Compile Time Options
When building your app, there is a single compile time option for
-statistics. When querying statistics, they are always queried by name,
+statistics. When querying statistics, they are always queried by number,
but if you want to see the results by name, you need to define
`STATS_NAME_ENABLE`. This is defined using
@@ -52,6 +68,8 @@ in your target definition.
Enabling stat names provides better descriptions in the reported stats,
but takes code space to store the strings within the image.
+<br>
+
### Adding Stats to your code.
Creating new stats table requires the following steps.
@@ -64,6 +82,8 @@ Creating new stats table requires the following steps.
* Initialize the stats
* Register the stats
+<br>
+
#### Include the stats header file
Add the stats library to your pkg.yml file for your package or app by adding
@@ -74,12 +94,16 @@ pkg.deps:
- "@apache-mynewt-core/sys/stats"
```
+<br>
+
Add this include directive to code files using the stats library.
```
#include <stats/stats.h>
```
+<br>
+
#### Define a stats section
You must use the `stats.h` macros to define your stats table. A
@@ -92,6 +116,8 @@ STATS_SECT_START(my_stat_section)
STATS_SECT_END
```
+<br>
+
In this case we chose to make the stats 32-bits each. `stats.h` supports three
different stats sizes through the following macros:
@@ -109,15 +135,19 @@ struct stats_my_stat_section {
};
```
-You can see that the structure is defined that has a small stats structure
+<br>
+
+You can see that the defined structure has a small stats structure
header and the two stats we have defined.
Depending on whether these stats are used in multiple modules, you may need
to include this definition in a header file.
+<br>
+
#### Declaring a variable to hold the stats
-Declare the global variable to hold your statistics. Since its possible to
+Declare the global variable to hold your statistics. Since it is possible to
have multiple copies of the same section (for example a stat section for
each of 5 identical peripherals), the variable name of the stats section
must be unique.
@@ -126,7 +156,9 @@ must be unique.
STATS_SECT_DECL(my_stat_section) g_mystat;
```
-Again if your stats section is used in multiple C files you will need to
+<br>
+
+Again, if your stats section is used in multiple C files you will need to
include the above definition in one of the C files and 'extern' this declaration
in your header file.
@@ -134,6 +166,8 @@ in your header file.
extern STATS_SECT_DECL(my_stat_section) g_mystat;
```
+<br>
+
#### Define the stats section name table
Whether or not you are using `STATS_NAME_ENABLE`, you must define
@@ -148,7 +182,9 @@ STATS_NAME_START(my_stat_section)
STATS_NAME_END(my_stat_section)
```
-When compiled by the preprocessor, it create a structure that looks like this.
+<br>
+
+When compiled by the preprocessor, it creates a structure that looks like this.
```
struct stats_name_map g_stats_map_my_stat_section[] = {
@@ -157,13 +193,17 @@ struct stats_name_map g_stats_map_my_stat_section[] = {
};
```
+<br>
+
This table will allow the UI components to find a nice string name for the
stat.
+<br>
+
#### Implement stats in your code.
You can use the `STATS_INC` or `STATS_INCN` macros to increment your statistics
-within your C-code. For example, code may do this
+within your C-code. For example, your code may do this:
```
STATS_INC(g_mystat, attempt_stat);
@@ -173,10 +213,12 @@ within your C-code. For example, code may do this
}
```
+<br>
+
#### Initialize the statistics
-You must initialize the stats to they can be operated on by the stats
-library. As per our example above, it would look like this.
+You must initialize the stats so they can be operated on by the stats
+library. As per our example above, it would look like the following.
This tells the system how large each statistic is and the number of
statistics in the section. It also initialize the name information for
@@ -190,6 +232,8 @@ the statistics if enabled as shown above.
assert(rc == 0);
```
+<br>
+
#### Register the statistic section
If you want the system to know about your stats, you must register them.
@@ -199,10 +243,14 @@ If you want the system to know about your stats, you must register them.
assert(rc == 0);
```
+<br>
+
There is also a method that does initialization and registration at the
same time, called `stats_init_and_reg`.
-### Retrieving stats through console or newtmgr
+<br>
+
+### Retrieving stats through console or Newtmgr
If you enable console in your project you can see stats through the
serial port defined.
@@ -214,6 +262,8 @@ stat my_stats
12275:error_stat: 0
```
+<br>
+
This is the stats as shown from the example without names enabled.
```
stat my_stats
@@ -221,6 +271,8 @@ stat my_stats
29150:s1: 0
```
+<br>
+
### A note on multiple stats sections
If you are implementing a device with multiple instances, you may
@@ -232,5 +284,5 @@ each device separately.
This works identically to the example above, except you would need to
register each one separately with a unique name. The stats system will
-not let two section be entered with the same name.
+not let two sections be entered with the same name.