meminfo

Usage

>> meminfo [ dataset | used | remaining | capacity | size ]

Security

Open.

Description

Reports information about the usage and characteristics of the data memory.

  • dataset [= <index>] is the index of the dataset being queried - see below for details.

  • used is the number of bytes actually used to store data in this dataset.

  • remaining is the number of bytes still available for data storage.

  • size is the maximum total size in bytes of the dataset.

  • capacity is the maximum number of bytes which will be stored in data memory if all of the 'remaining' bytes are fully used. This parameter is not reported by default, but must be requested explicitly.

The dataset argument is present to support the EasyParse data storage format, which assigns different types of deployment data to different datasets as follows:

  • the deployment header is in dataset 2

  • the sample data is in dataset 1

  • events are in dataset 0

  • the sample data generated by postprocessing is in dataset 4

In Standard data storage format, everything is in dataset 1. For a full discussion of data storage formats, refer to the section Format of Stored Data.

If the dataset argument is omitted then dataset 1 is assumed, and no <dataset> value is reported in the command’s response, either: it is assumed that dataset 1 is implicitly understood.

In Standard format, only one dataset is used, and so the remaining parameters have physical interpretations which are not too hard to understand. The size parameter is a fixed number for a given flash memory device. Because of the way these devices store data, it is sometimes not possible to use the entire device in order to reliably store small amounts of information. In such cases small areas of the device are not used to store data, but are no longer available for storage, either. Over the course of a deployment these uncommitted areas can accumulate, so (used + remaining) < size. However, (used + remaining) = capacity should always be true.

In EasyParse format, the relationship between the parameter values and the characteristics of the physical storage device become more complicated. For the curious, this is discussed in detail in the "Technical note" below, but this should not be considered required reading. Although the numbers will not be completely accurate, a reasonable guide to the state of the memory can be obtained by looking at the values for dataset 1 alone, since it contains the sample data, and there will typically be far more sample data than anything else.

Examples

>> meminfo
<< meminfo used = 1528, remaining = 134216192, size = 134217728
>> meminfo capacity
<< meminfo capacity = 134217720
>> meminfo dataset = 1
<< meminfo dataset = 1, used = 1528, remaining = 134216192, size = 134217728
>> meminfo dataset = 0, used
<< meminfo dataset = 0, used = 362

Errors

Error E0108 invalid argument to command: '<invalid-argument>'
The supplied argument was not recognized.

Technical note
This note discusses the relationships between the parameter values for used, remaining, size and capacity when more than one dataset in the memory is in use; for example, when using the EasyParse data storage format.
To understand this, the concept of memory 'blocks' must be introduced. A block is the smallest amount of memory in the physical device which can be erased, and is relatively large; a typical size might be 128KB.
All datasets start off empty, and all blocks are initially available to any dataset. As soon as a dataset is written to, the modified block is assigned to that dataset. The memory within it is available to that dataset, but to no others, so for all the other datasets, the size of the memory appears to shrink by one block. If this strategy were not followed, datasets could not be erased independently of each other.
Therefore, as multiple datasets are opened and written to, each can report a different size for the memory, because as far as each dataset is concerned any blocks assigned to other datasets do not exist. Further, as blocks are assigned to each dataset, the size according to other datasets appears to change.
In fact, then, size is the maximum possible amount of memory which could be used by the specified (or default) dataset, not the entire physical device. It is reported in bytes, but will always be a multiple of the block size. If only one dataset exists, then size does also give the physical device size, because no other datasets will use any blocks.
Mercifully, used is a bit simpler to understand; it is just the number of bytes which have actually had data written to them in the specified dataset.
The value of remaining is the maximum possible number of bytes which could be written to this dataset in the future. It includes all bytes in unallocated blocks, as well as all available bytes in any partially used block assigned to this dataset.
Finally, capacity is the maximum possible number of bytes of data that the specified dataset could end up holding if all remaining bytes get used: in other words, (used + remaining). In general, capacity may be less than size for any data set, but never more. The reason for this is that sometimes a 'partial page' of data may be flushed from a RAM cache to the actual flash device before the cache is full. When this happens, the unused bytes in that page have no data in them, but they are no longer available for storage either; they are 'lost'. The accumulation of such lost bytes is the difference between capacity and size.