6.6. soam — Simba OAM

Simba Operation And Maintenence (SOAM) is a framed debug protocol with enumerated format strings and file system commands. This both saves memory and makes the communication more reliable.

Two macros are defined; OSTR() and CSTR(), both required by the SOAM build system. It is considered good practice to always use these macros, even if SOAM is not used.

  • The OSTR() macro.

    An output format string.

    /* Log object. */
    log_object_print(NULL, LOG_INFO, OSTR("Hello %s!\r\n"), "Erik");
    
    /* File system command output. */
    static int cmd_foo_cb(...)
    {
        std_fprintf(chout_p, OSTR("Foo %d!\r\n"), 1);
    
        return (0);
    }
    
    /* Regular printf. */
    std_printf(OSTR("Hello 0x%x!\r\n"), 0xbabe);
    
  • The CSTR() macro.

    A file system command string.

    fs_command_init(&cmd_foo, CSTR("/foo"), cmd_foo_cb, NULL);
    

6.6.1. Usage

Enable SOAM by adding SOAM=yes to the application makefile.

Connect to the board with soam.py instead of a serial terminal program. The only required argument is the string database file.

Here is an example usage of the script. Ctrl-D is pressed to exit the script.

> soam.py --port /dev/arduino --baudrate 115200 \
      build/arduino_due/soam.soamdb
Welcome to the SOAM shell.

Type help or ? to list commands.

$ kernel/sys/info
app:    soam-master built 2017-03-05 21:26 CET by erik.
board:  Arduino Due
mcu:    Atmel SAM3X8E Cortex-M3 @ 84MHz, 96k sram, 512k flash
OK
$ kernel/thrd/list
            NAME        STATE  PRIO   CPU   SCHEDULED  MAX-STACK-USAGE  LOGMASK
            soam      current    30    0%         112       748/  1542     0x0f
         monitor    suspended   -80    0%          22       176/   518     0x0f
            idle        ready   127   99%         594       276/   390     0x0f
            main    suspended     0    0%         305       540/ 88898     0x00
OK
$ kernel/thrd/set_log_mask foo 0
ERROR(-3)
$ <Ctrl-D>

Bye!
>

OK is printed by the shell if the file system command returned zero(0), otherwise ERROR(error code) is printed.


Source code: src/oam/soam.h, src/oam/soam.c

Test code: tst/oam/soam/main.c

Test coverage: src/oam/soam.c

Example code: examples/soam/main.c


Functions

int soam_module_init(void)

Initialize the soam module. This function must be called before calling any other function in this module.

The module will only be initialized once even if this function is called multiple times.

Return
zero(0) or negative error code.

int soam_init(struct soam_t *self_p, void *buf_p, size_t size, void *chout_p)

Initialize given soam object.

Return
zero(0) or negative error code.
Parameters
  • self_p: Object to initialize.
  • buf_p: Transmission buffer.
  • size: Transmission buffer size.
  • chout_p: Soam packets are written to this channel.

int soam_input(struct soam_t *self_p, uint8_t *buf_p, size_t size)

Process given soam packet.

Return
zero(0) or negative error code.
Parameters
  • self_p: Soam object.
  • buf_p: Buffer to input.
  • size: Size to input in bytes.

ssize_t soam_write_begin(struct soam_t *self_p, int type)

Start outputting a soam packet of given type.

Return
zero(0) or negative error code.
Parameters
  • self_p: Soam object.
  • type: Packet type.

ssize_t soam_write_chunk(struct soam_t *self_p, const void *buf_p, size_t size)

Add given chunk of data to current packet.

Return
zero(0) or negative error code.
Parameters
  • self_p: Soam object.
  • buf_p: Buffer to output.
  • size: Size to output in bytes.

ssize_t soam_write_end(struct soam_t *self_p)

Finalize current packet and transmit it.

Return
zero(0) or negative error code.
Parameters
  • self_p: Soam object.

ssize_t soam_write(struct soam_t *self_p, int type, const void *buf_p, size_t size)

Create and transmit a soam packet of given type and data.

Return
zero(0) or negative error code.
Parameters
  • self_p: Soam object.
  • type: Packet type.
  • buf_p: Buffer to output.
  • size: Size to output in bytes.

void *soam_get_log_input_channel(struct soam_t *self_p)

Get the log input channel. This channel can be set as output channel of the log module with log_set_default_handler_output_channel().

Return
Log input channel.
Parameters
  • self_p: Soam object.

void *soam_get_stdout_input_channel(struct soam_t *self_p)

Get the standard output input channel. This channel can be set as standard output channel of the sys module with sys_set_stdout().

Return
Standard output input channel.
Parameters
  • self_p: Soam object.

struct soam_t
#include <soam.h>

Public Members

int is_printf
uint8_t transaction_id
uint8_t *buf_p
size_t size
ssize_t pos
struct sem_t sem
void *chout_p
uint8_t packet_index
struct soam_t::@101 soam_t::tx
struct chan_t stdout_chan
struct chan_t log_chan
struct chan_t command_chan