Command System

Overview

The command system provides an standard interface for a module to provide commands for other modules or communication protocols to control it. A command consists of the following parts:

  • Opcode: An integer that uniquely identifies the command.

  • Immediate Handler: An optional function that is called when the command is invoked, which is used to execute the command in the same context of the invocation or to validate the operand if the command has a deffered handler.

  • Deferred Handler: An optional function that is queued to be executed in a dedicated thread when the command requires a longer execution time or cannot be executed in ISRs.

Usage

Design

Architecture

API Reference

group Command

Defines

CMD_NO_HANDLER

Indicate that the command has no handler of this type.

CMD_DEFINE(opcode, immed, deffered, user_data)

Define a command.

Note

Since the name of the command is automatically generated using opcode , the name would be illegal if opcode contains characters other than alphanumericals or underscores. To avoid this, _CMD_DEFINE can be used directly by providing a unique name.

Parameters:
cmd_invoke_typed(_opcode, _operand, _operand_type)

Invoke a command with specific operand type.

Parameters:

  • _opcode – [in] Command opcode.

  • _operand – [in] Operand for the command.

  • _operand_type – [in] Type of the operand.

Returns:

Same as cmd_invoke.

cmd_invoke_auto(opcode, operand)

Invoke a command with operand type inferred from operand .

Parameters:

  • opcode – [in] Command opcode.

  • operand – [in] Operand for the command.

Returns:

Same as cmd_invoke.

Typedefs

typedef int (*cmd_immed_handler_t)(uint32_t opcode, const void *operand, size_t operand_size, void *user_data)

Immediate handler of a command.

Param opcode:

[in] Command opcode.

Param operand:

[in] Operand for the command.

Param user_data:

[in] Custom data of the command.

Retval 0:

For success.

Retval -EINVAL:

If the operand is invalid.

Retval others:

Negative error number.

typedef void (*cmd_deffered_handler_t)(uint32_t opcode, const void *operand, size_t operand_size, void *user_data)

Deffered handler of a command.

Param opcode:

[in] Command opcode.

Param operand:

[in] Operand for the command.

Param user_data:

[in] Custom data of the command.

Functions

int cmd_invoke(uint32_t opcode, void *operand, size_t operand_size)

Invoke a command.

Parameters:

  • opcode – [in] Command opcode.

  • operand – [in] Operand for the command.

  • operand_size – [in] Size of the operand.

Return values:

  • 0 – For success.

  • -ENOENT – If the opcode does not exist.

  • -EINVAL – If the operand is invalid.

  • -ENOMEM – If the buffer for deffered handler is full.

  • others – Negative error number returned by immediate handler.

static inline int cmd_invoke_void(uint32_t opcode)

Invoke a command without operand.

Parameters:

  • opcode – [in] Command opcode.

Returns:

Same as cmd_invoke.

struct cmd
#include <nturt/cmd.h>

Command.

Public Members

const uint32_t opcode

Opcode of the command.

const cmd_immed_handler_t immed

Immediate handler.

const cmd_deffered_handler_t deffered

Deffered handler.

void *const user_data

Custom data of the command.