examples/dac/dac_main.c

/****************************************************************************
 * apps/examples/dac/dac_main.c
 *
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.  The
 * ASF licenses this file to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance with the
 * License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
 * License for the specific language governing permissions and limitations
 * under the License.
 *
 ****************************************************************************/

/****************************************************************************
 * Included Files
 ****************************************************************************/

#include <nuttx/config.h>

#include <errno.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include <sys/ioctl.h>
#include <sys/param.h>
#include <nuttx/analog/dac.h>
#include <nuttx/arch.h>

/****************************************************************************
 * Pre-processor Definitions
 ****************************************************************************/

#ifndef CONFIG_DAC
#  error "DAC device support is not enabled (CONFIG_DAC)"
#endif

#ifndef CONFIG_EXAMPLES_DAC_DEVPATH
#  define CONFIG_EXAMPLES_DAC_DEVPATH "/dev/dac0"
#endif

#define DEFAULT_COUNT          1
#define DEFAULT_DELAY          0
#define DEFAULT_CHANNEL        0
#define DEFAULT_TEST_BIT_RES   8
#define DEFAULT_TEST_STEP      8
#define DEFAULT_INITIALIZED    true

/****************************************************************************
 * Private Types
 ****************************************************************************/

struct command
{
  FAR const char *name;
  CODE int (* const cmd)(int argc, FAR const char *argv[]);
  FAR const char *args;
};

struct dac_state_s
{
  FAR char *devpath;
  int count;
  int delay;
  uint8_t channel;
  int test_bit_res;
  int test_step;
  bool initialized;
};

/****************************************************************************
 * Private Function Prototypes
 ****************************************************************************/

static int cmd_dac_put(int argc, FAR const char *argv[]);
static int cmd_dac_putv(int argc, FAR const char *argv[]);
static int cmd_dac_test(int argc, FAR const char *argv[]);

/****************************************************************************
 * Private Data
 ****************************************************************************/

static const struct command commands[] =
{
  { "put", cmd_dac_put, "DATA [DELAY]" },
  { "putv", cmd_dac_putv, "DATA [DATA...]" },
  { "test", cmd_dac_test, "" },
};

static struct dac_state_s g_dacstate;

/****************************************************************************
 * Private Functions
 ****************************************************************************/

/****************************************************************************
 * Name: dac_devpath
 *
 * Description:
 *   Update the DAC device path in the DAC state structure. This function
 *   manages memory allocation for the device path and frees the previous
 *   path if it exists.
 *
 * Input Parameters:
 *   dac     - Pointer to the DAC state structure.
 *   devpath - New DAC device path to be set.
 *
 * Operation:
 *   - Frees the existing DAC device path if it exists.
 *   - Allocates memory for the new DAC device path.
 *   - Updates the device path in the DAC state structure.
 *
 ****************************************************************************/

static void dac_devpath(FAR struct dac_state_s *dac,
                        FAR const char *devpath)
{
  if (dac->devpath)
    {
      free(dac->devpath);
    }

  dac->devpath = strdup(devpath);
}

/****************************************************************************
 * Name: print_cmds
 *
 * Description:
 *   Print a list of commands with their names, arguments, and a given header
 *   and trailer. This function is used to display available
 *   commands and their usage information.
 *
 * Input Parameters:
 *   header  - Header string to be printed before the command list.
 *   cmds    - Pointer to an array of command structures.
 *   ncmds   - Number of commands in the array.
 *   trailer - Trailer string to be printed after the command list.
 *
 * Operation:
 *   - Prints the header.
 *   - Iterates through the array of command structures and prints
 *     their names, arguments, and a newline character after each command.
 *   - Prints the trailer.
 *
 ****************************************************************************/

static void print_cmds(FAR const char *header,
                       FAR const struct command *cmds,
                       size_t ncmds,
                       FAR const char *trailer)
{
  printf("%s", header);
  while (ncmds--)
    {
      printf("  %s %s %c", cmds->name, cmds->args,
                           (ncmds > 0) ? '\n' : ' ');
      cmds++;
    }

  printf("%s", trailer);
}

/****************************************************************************
 * Name: find_cmd
 *
 * Description:
 *   Find a command structure in an array of commands by comparing command
 *   names.
 *
 * Input Parameters:
 *   name  - Name of the command to be found.
 *   cmds  - Pointer to an array of command structures.
 *   ncmds - Number of commands in the array.
 *
 * Returned Value:
 *   Returns a pointer to the found command structure if successful; NULL
 *   if the command is not found.
 *
 * Operation:
 *   - Iterates through the array of command structures.
 *   - Compares the name of each command with the specified name.
 *   - Returns a pointer to the found command structure or NULL if not found.
 *
 ****************************************************************************/

static const struct command *find_cmd(FAR const char *name,
                                      FAR const struct command *cmds,
                                      size_t ncmds)
{
  while (ncmds--)
    {
      if (!strcmp(cmds->name, name))
        {
          return cmds;
        }

      cmds++;
    }

  return NULL;
}

/****************************************************************************
 * Name: execute_cmd
 *
 * Description:
 *   Execute a command function based on the command name.
 *   This function finds the corresponding command structure in the
 *   array and invokes the associated function.
 *
 * Input Parameters:
 *   argc  - Number of command-line arguments.
 *   argv  - Array of command-line argument strings.
 *   cmds  - Pointer to an array of command structures.
 *   ncmds - Number of commands in the array.
 *
 * Returned Value:
 *   Returns the result of the executed command function.
 *
 * Operation:
 *   - Finds the command structure for the specified command name.
 *   - Invokes the associated command function with the provided arguments.
 *   - Prints an error message if the command is not found.
 *
 ****************************************************************************/

static int execute_cmd(int argc,
                       FAR const char *argv[],
                       FAR const struct command *cmds,
                       size_t ncmds)
{
  FAR const struct command *cmd;

  cmd = find_cmd(argv[0], cmds, ncmds);
  if (!cmd)
    {
      fprintf(stderr, "ERROR: unknown command: %s\n", argv[0]);
      print_cmds("", cmds, ncmds, "\n");
      return -EINVAL;
    }

  return cmd->cmd(argc - 1, argv + 1);
}

/****************************************************************************
 * Name: dac_put
 *
 * Description:
 *   Write DAC messages to the specified DAC device. This function writes
 *   multiple DAC messages, allowing the configuration of DAC channel and
 *   data values. It handles potential write retries in case of non-blocking
 *   write operations and provides debug information about the write process.
 *
 * Input Parameters:
 *   devpath - Path to the DAC device.
 *   msg     - Pointer to an array of DAC messages to be written.
 *   nmsgs   - Number of DAC messages in the array.
 *   delay   - Delay between writes in milliseconds.
 *
 * Returned Value:
 *   Returns the number of successfully written messages on success; a
 *   negated errno value on failure.
 *
 * Operation:
 *   - Opens the specified DAC device for writing.
 *   - Iterates through the array of DAC messages and writes
 *       them to the device.
 *   - Handles non-blocking writes, retries on EAGAIN, and provides
 *       debug output.
 *   - Closes the DAC device after completing the write operations.
 *
 ****************************************************************************/

static int dac_put(FAR const char *devpath,
                   FAR struct dac_msg_s *msg,
                   size_t nmsgs,
                   int delay)
{
  size_t retries;
  size_t i;
  int fd;
  int ret = OK;

  fd = open(devpath, O_WRONLY | O_NONBLOCK);
  if (fd < 0)
    {
      fprintf(stderr, "ERROR: open() failed: %d\n", errno);
      return -ENODEV;
    }

  i = retries = 0;
  while (i < nmsgs && retries < 3)
    {
      errno = 0;
      ret = write(fd, &msg[i], sizeof(*msg));
      printf("write: ret=%d, errno=%d\n", ret, errno);
      if (ret != sizeof(*msg))
        {
          if (errno == EAGAIN)
            {
              retries++;
              continue;
            }

          fprintf(stderr, "write failed: ret=%d, errno=%d\n", ret, errno);
          ret = -errno;
          break;
        }
      else
        {
          printf("wrote: chan=%d, data=%" PRId32 "\n", msg[i].am_channel,
                 msg[i].am_data);
          i++;
          retries = 0;
          ret = OK;
          usleep(1000 * delay);
        }
    }

  close(fd);
  return (i > 0) ? i : ret;
}

/****************************************************************************
 * Name: cmd_dac_put
 *
 * Description:
 *   Execute the 'put' command, writing a specified DAC value to the DAC
 *   device.
 *
 * Input Parameters:
 *   argc - Number of command-line arguments.
 *   argv - Array of command-line argument strings.
 *
 * Returned Value:
 *   Returns OK on success; a negated errno value on failure.
 *
 * Operation:
 *   - Parses the command-line arguments to extract the DAC value and delay.
 *   - Overrides the "sticky" delay option if provided in the arguments.
 *   - Repeats the DAC write operation for the specified number of times.
 *
 * Usage:
 *  `put [value] [delay]`: Write the specified DAC value to the device.
 *  - [value]: DAC value to be written (Default: 100).
 *  - [delay]: Delay between writes in milliseconds.
 *
 ****************************************************************************/

static int cmd_dac_put(int argc, FAR const char *argv[])
{
  struct dac_msg_s msgs[1];
  int data;
  int delay;
  int i;
  int ret = OK;

  /* This command allows overriding the "sticky" delay option. */

  data  = (argc > 0) ? atoi(argv[0]) : 100;
  delay = (argc > 1) ? atoi(argv[1]) : g_dacstate.delay;

  printf("devpath=%s data=%d delay=%d\n",
        g_dacstate.devpath, data, delay);

  for (i = 0; i < g_dacstate.count; i++)
    {
      msgs[0].am_channel = g_dacstate.channel;
      msgs[0].am_data = data;
      ret = dac_put(g_dacstate.devpath, msgs, nitems(msgs), delay);
      printf("ret=%d\n", ret);
    }

  return ret;
}

/****************************************************************************
 * Name: cmd_dac_putv
 *
 * Description:
 *   Execute the 'putv' command, writing DAC values specified in the command
 *   arguments to the DAC device. The command supports writing
 *   multiple values in a single execution.
 *
 * Input Parameters:
 *   argc - Number of command-line arguments.
 *   argv - Array of command-line argument strings.
 *
 * Returned Value:
 *   Returns OK on success; a negated errno value on failure.
 *
 * Operation:
 *   - Parses the command-line arguments to extract DAC values.
 *   - Constructs DAC messages with the specified channel and data values.
 *   - Repeats the DAC write operation for the specified number of times.
 *
 ****************************************************************************/

static int cmd_dac_putv(int argc, FAR const char *argv[])
{
  struct dac_msg_s msgs[CONFIG_NSH_MAXARGUMENTS];
  int nmsgs;
  int i;
  int ret = OK;

  for (nmsgs = 0; nmsgs < CONFIG_NSH_MAXARGUMENTS; nmsgs++)
    {
      if (nmsgs >= argc)
        {
          break;
        }

      msgs[nmsgs].am_channel = g_dacstate.channel;
      msgs[nmsgs].am_data = atoi(argv[nmsgs]);
    }

  for (i = 0; i < g_dacstate.count; i++)
    {
      ret = dac_put(g_dacstate.devpath, msgs, nmsgs, g_dacstate.delay);
      printf("ret=%d\n", ret);
    }

  return ret;
}

/****************************************************************************
 * Name: cmd_dac_test
 *
 * Description:
 *   Perform DAC testing by generating a sequence of values and writing them
 *   to the DAC device specified in the global DAC state structure.
 *
 * Input Parameters:
 *   argc - Number of arguments in argv.
 *   argv - Array of command-line argument strings.
 *
 * Returned Value:
 *   Total return value, the sum of return values from write calls. Returns
 *   a negative errno on failure.
 *
 * Note: Utilizing the parameters can make testing much easier. If you are
 *   testing with one config test, you can change the constant definition for
 *   default value at the top and simply run `nsh> dat test`
 * If you want setup for multimeter testing, set appropriate delay between
 *   writes (in ms). Example for 8 bit DAC using step in value of 16
 *   nsh> dac -d 5000 -b 8 -s 16 test
 * Example for oscilloscope test for 12 bit DAC:
 *   nsh> dac -d 10 -b 12 -s 4 test
 *
 ****************************************************************************/

static int cmd_dac_test(int argc, FAR const char *argv[])
{
  struct dac_msg_s msg;
  int fd;
  int i;
  bool count_up;
  uint32_t value = 0;
  uint32_t max_value = (1 << g_dacstate.test_bit_res);
  int ret = OK;
  int total_ret = 0;

  fd = open(g_dacstate.devpath, O_WRONLY | O_NONBLOCK);
  if (fd < 0)
    {
      fprintf(stderr, "ERROR: open() failed: %d\n", errno);
      return -ENODEV;
    }

  for (i = 0; i < g_dacstate.count; i++)
    {
      count_up = true;
      value = 0;
      while (count_up || value)
        {
          msg.am_channel = g_dacstate.channel;
          msg.am_data = value;

          if (count_up)
            {
              value += g_dacstate.test_step;
              if (value >= max_value - 1)
                {
                  value = max_value - 1;
                  count_up = false;
                }
            }
          else
            {
              value -= g_dacstate.test_step;

              /* Check if value is underflow */

              if (value > UINT32_MAX - g_dacstate.test_step)
                {
                  value = 0;
                }
            }

            ret = write(fd, &msg, sizeof(struct dac_msg_s));
            total_ret += ret;
            usleep(1000 * g_dacstate.delay);
        }
    }

  close(fd);

  return total_ret;
}

/****************************************************************************
 * Name: dac_help
 *
 * Description:
 *   Display the help message for the DAC testing application.
 *
 * Input Parameters:
 *   None
 *
 * Returned Value:
 *   None
 *
 ****************************************************************************/

static void dac_help(void)
{
  printf("Usage: dac [OPTIONS] command [CMD OPTIONS]\n");
  printf("\nGlobal arguments are \"sticky\".  "
         "For example, once the DAC device is\n");
  printf("specified, that device will be re-used until it is changed.\n");
  printf("\n\"sticky\" OPTIONS include:\n");
  printf("  [-c channel] selects the DAC channel.  "
         "Default: %d Current: %d\n", DEFAULT_CHANNEL, g_dacstate.channel);
  printf("  [-d delay] pause for DELAY ms between writes.  "
         "Default: %d Current: %d\n", DEFAULT_DELAY, g_dacstate.delay);
  printf("  [-n count] repeats device write COUNT times.  "
         "Default: %d Current: %d\n", DEFAULT_COUNT, g_dacstate.count);
  printf("  [-b bit_resolution] Test-specific config - set DAC bit"
         " resolution  Default: %d Current: %d\n",
         DEFAULT_TEST_BIT_RES, g_dacstate.test_bit_res);
  printf("  [-s step] Test-specific config - test loop step  "
         "Default: %d Current: %d\n",
         DEFAULT_TEST_STEP, g_dacstate.test_step);
  printf("  [-p devpath] selects the DAC device.  "
         "Default: %s Current: %s\n",
         CONFIG_EXAMPLES_DAC_DEVPATH,
         g_dacstate.devpath ? g_dacstate.devpath : "NONE");
  printf("  [-h] Print this help and exit.\n");
  print_cmds("\nCommands:\n", commands, nitems(commands), "\n");
}

/****************************************************************************
 * Name: arg_string
 *
 * Description:
 *   Extracts a string argument from a command-line option.
 *
 * Input Parameters:
 *   arg   - Pointer to the current command-line argument being processed.
 *   value - Pointer to store the extracted string argument.
 *
 * Returned Value:
 *   Integer representing the number of arguments consumed
 *   (2 if the option takes an additional argument, 1 otherwise).
 *
 ****************************************************************************/

static int arg_string(FAR const char **arg, FAR const char **value)
{
  FAR const char *ptr = *arg;

  if (ptr[2] == '\0')
    {
      *value = arg[1];
      return 2;
    }
  else
    {
      *value = &ptr[2];
      return 1;
    }
}

/****************************************************************************
 * Name: arg_decimal
 *
 * Description:
 *   Extracts a decimal value from a command-line option.
 *
 * Input Parameters:
 *   arg   - Pointer to the current command-line argument being processed.
 *   value - Pointer to store the extracted decimal value.
 *
 * Returned Value:
 *   Integer representing the number of arguments consumed
 *   (2 if the option takes an additional argument, 1 otherwise).
 *
 * Note:
 *   Utilizes arg_string internally to extract the string argument
 *   and then converts it to a long integer using strtol.
 *
 ****************************************************************************/

static int arg_decimal(FAR const char **arg, FAR long *value)
{
  FAR const char *string;
  int ret;

  ret = arg_string(arg, &string);
  *value = strtol(string, NULL, 10);
  return ret;
}

static int parse_args(FAR struct dac_state_s *dac,
                      int argc,
                      const char *argv[])
{
  FAR const char *ptr; /* Pointer to the current argument in argv */
  FAR const char *str; /* Pointer to a string argument extracted from argv */
  long value;          /* Numerical argument value */
  int nargs;           /* Number of args consumed by the current option */
  int n;               /* Total number of arguments processed */
  int i;               /* Loop counter */

  for (i = n = 1; i < argc; )
    {
      ptr = argv[i];
      if (ptr[0] != '-')
        {
          i++;
          continue;
        }

      switch (ptr[1])
        {
          case 'c':
            nargs = arg_decimal(&argv[i], &value);
            if (value < 0 || value > 255)
              {
                printf("Channel must be in range [0..255]: %ld\n", value);
                exit(1);
              }

            dac->channel = (uint8_t)value;
            i += nargs;
            n += nargs;
            break;

          case 'd':
            nargs = arg_decimal(&argv[i], &value);
            if (value < 0)
              {
                printf("Delay must be non-negative: %ld\n", value);
                exit(1);
              }

            dac->delay = (uint32_t)value;
            i += nargs;
            n += nargs;
            break;

          case 'n':
            nargs = arg_decimal(&argv[i], &value);
            if (value < 0)
              {
                printf("Count must be non-negative: %ld\n", value);
                exit(1);
              }

            dac->count = (uint32_t)value;
            i += nargs;
            n += nargs;
            break;

          case 'b':
            nargs = arg_decimal(&argv[i], &value);
            if (value < 0)
              {
                printf("Bit resolution must be non-negative: %ld\n", value);
                exit(1);
              }

            dac->test_bit_res = (uint32_t)value;
            i += nargs;
            n += nargs;
            break;

          case 's':
            nargs = arg_decimal(&argv[i], &value);
            if (value < 0)
              {
                printf("Step must be non-negative: %ld\n", value);
                exit(1);
              }

            dac->test_step = (uint32_t)value;
            i += nargs;
            n += nargs;
            break;

          case 'p':
            nargs = arg_string(&argv[i], &str);
            dac_devpath(dac, str);
            i += nargs;
            n += nargs;
            break;

          case 'h':
            dac_help();
            exit(0);
            break;

          case '?':
          default:
            printf("Unsupported option: %s\n", ptr);
            dac_help();
            exit(1);
        }
    }

  return n;
}

/****************************************************************************
 * Public Functions
 ****************************************************************************/

/****************************************************************************
 * Name: main
 *
 * Description:
 *   Entry point for the DAC testing application.
 *   Initializes the DAC hardware and processes command-line
 *   arguments to execute DAC testing commands.
 *
 * Input Parameters:
 *   argc - Number of command-line arguments.
 *   argv - Array of command-line argument strings.
 *
 * Returned Value:
 *   EXIT_SUCCESS on success, EXIT_FAILURE on failure.
 *
 ****************************************************************************/

int main(int argc, FAR const char *argv[])
{
  int ret;
  int nargs = 1;

  if (!g_dacstate.initialized)
    {
      /* Initialization of the DAC hardware must be performed by
       * board-specific logic prior to running this test.
       */

      /* Set the default values */

      dac_devpath(&g_dacstate, CONFIG_EXAMPLES_DAC_DEVPATH);
      g_dacstate.delay         = DEFAULT_DELAY;
      g_dacstate.count         = DEFAULT_COUNT;
      g_dacstate.channel       = DEFAULT_CHANNEL;
      g_dacstate.test_bit_res  = DEFAULT_TEST_BIT_RES;
      g_dacstate.test_step     = DEFAULT_TEST_STEP;
      g_dacstate.initialized   = DEFAULT_INITIALIZED;
    }

  /* Parse the command line */

  nargs = parse_args(&g_dacstate, argc, argv);

  argc -= nargs;
  argv += nargs;

  if (argc < 1)
    {
      dac_help();
      return EXIT_FAILURE;
    }
  else
    {
      ret = execute_cmd(argc, argv, commands, nitems(commands));
    }

  return (ret >= 0) ? EXIT_SUCCESS : EXIT_FAILURE;
}