• mvServerLoggingInit()
• mvServerLog()

All of the functions described below return a 32-bit integer that is one of the values from the standard Microvisor enumeration MvStatus. All possible error values for a given system call are provided with each function's description.

Success is always signaled by a return value of zero (MV_STATUS_OKAY).

Establish application logging via the Microvisor cloud

Declaration

1
extern enum MvStatus mvServerLoggingInit(uint8_t *buffer, 
2
                                         uint32_t size);

Parameters

Possible errors

Description

The application calls mvServerLoggingInit() to initiate application logging. It passes a pointer to a suitably sized and aligned block of memory, and the size of the block. Microvisor will take ownership of this memory and use it as holding space for messages subsequently posted using mvServerLog() and as a buffer from which to transmit those messages one at a time over a connection it establishes when application logging is started.

The store must be at least 512 bytes in size and aligned to 512 bytes.

static uint8_t log_buffer[LOG_BUFFER_SIZE] __attribute__((aligned(512))) = {0} ;

While the device remains disconnected, the store will accumulate messages until it is full or there is insufficient space for the subsequent message. Pending messages will be issued when the device reconnects provided it has not been power-cycled. Power-cycling the device or restarting the application — for example, by deploying updated application code — will eliminate the buffer and any messages it contains.

If the device disconnects and later reconnects while the application is still running, it is not necessary to restart application logging.

The buffer cannot be reconfigured on the fly. If you need to resize the buffer, close the current buffer and then re-call mvServerLoggingInit() with a new, larger buffer.

To close a buffer and cease application logging, call mvServerLoggingInit() and pass null as the buffer pointer. Any unsent messages will be lost on closure. The buffer memory will be returned to the application.

Example

This code sets up logging with a suitably sized (for our hypothetical application) and aligned buffer.

1
const uint32_t log_buffer_size = 2048;
2
static uint8_t log_buffer[2048] __attribute__((aligned(512))) = {0} ;
3

4
// Initialize logging with the standard system call
5
enum MvStatus status = mvServerLoggingInit(log_buffer, log_buffer_size);
6
assert(status == MV_STATUS_OKAY);

Issue an application log message

Declaration

1
extern enum MvStatus mvServerLog(uint8_t *message, 
2
                                 uint16_t length);

Parameters

Possible errors

Description

Call mvServerLog() to post a message to the application log. The message is a sequence of bytes for which you must also specify its length — Microvisor does not rely on the use of the nul character as a string terminator. Messages can be no more than 1024 bytes in size.

The call will fail immediately if application logging has not been initiated with an earlier call to mvServerLoggingInit(), if the application logging buffer is full or has insufficient space for the message, or the message is longer than the permitted maximum size.

Example

This code traps the standard C function printf() so that its output is routed via Microvisor application logging.

1
const uint32_t log_buffer_size = 2048;
2
static uint8_t log_buffer[2048] __attribute__((aligned(512))) = {0} ;
3

4
bool initiate_logging() {
5
  enum MvStatus status = mvServerLogInit(log_buffer, log_buffer_size);
6
  return (status == MV_STATUS_OKAY);
7
}
8

9
void end_logging() {
10
  // Pass in a null buffer pointer to end logging
11
  enum MvStatus status = mvServerLogInit(NULL, 0);
12
}
13

14
// Patch printf() to use the new logging mechanism
15
int _write(int file, char *ptr, int length) {
16
  if (file != STDOUT_FILENO) {
17
    errno = EBADF;
18
    return -1;
19
  }
20

21
  // Write out the message string. Confirm that Microvisor
22
  // has accepted the request to write data to the channel.
23
  enum MvStatus status = mvServerLog((const uint8_t*)ptr, length);
24
  while (status != MV_STATUS_OKAY) {
25
    if (status == MV_STATUS_NO_LOGGING) {
26
      if (initiate_logging()) {
27
        status = mvServerLog((const uint8_t*)ptr, length);
28
      }
29
      continue;
30
    } else {
31
      // Can't write to the log -- fail
32
      errno = EIO;
33
      return -1;
34
    }
35
  }
36

37
  // Written the string; return the length to indicate success
38
  return length;
39
}