abi: user: make userspce ABI usage more obvious

src/include/kernel/header.h

@@ -20,7 +20,10 @@
  * \brief Header for all non IPC ABI data.
  *
  * Identifies data type, size and ABI.
- * Used by any bespoke component data structures or binary blobs.
+ * Data header used for all component data structures and binary blobs sent to
+ * firmware as runtime data. This data is typically sent by userspace
+ * applications and tunnelled through any OS kernel (via binary kcontrol on
+ * Linux) to the firmware.
  */
 struct sof_abi_hdr {
 	uint32_t magic;		/**< 'S', 'O', 'F', '\0' */

tools/CMakeLists.txt

@@ -15,6 +15,6 @@ project(SOF_TOOLS C)
 set(SOF_ROOT_SOURCE_DIRECTORY "${PROJECT_SOURCE_DIR}/..")
 
 add_subdirectory(logger)
-add_subdirectory(eqctl)
+add_subdirectory(ctl)
 add_subdirectory(topology)
 add_subdirectory(test)

tools/ctl/CMakeLists.txt

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: BSD-3-Clause
+
+add_executable(sof-ctl
+	ctl.c
+)
+
+target_link_libraries(sof-ctl PRIVATE
+	"-lasound"
+)
+
+target_include_directories(sof-ctl PRIVATE
+	"${SOF_ROOT_SOURCE_DIRECTORY}/src/include"
+	"${SOF_ROOT_SOURCE_DIRECTORY}"
+)
+
+install(TARGETS sof-ctl DESTINATION bin)

tools/eqctl/README → tools/ctl/README

@@ -1,7 +1,7 @@
-How to use sof-eqctl tool
+How to use sof-ctl tool
 =========================
 
 This tool helps to access the ext bytes or tlv bytes control of SOF
-equalizer components eq_iir and eq_fir. Please find the documentation
-in https://thesofproject.github.io/latest/getting_started/index.html
-for more information.
+components (like equalizer eq_iir and eq_fir). Please find the documentation
+in https://thesofproject.github.io/latest/getting_started/index.html for
+more information.

tools/eqctl/eqctl.c → tools/ctl/ctl.c

@@ -9,29 +9,24 @@
 #include <stdint.h>
 #include <errno.h>
 #include <alsa/asoundlib.h>
-
-#define SOF_CTRL_CMD_BINARY 3 /* TODO: From uapi ipc */
+#include "kernel/abi.h"
+#include "kernel/header.h"
+#include "ipc/stream.h"
+#include "ipc/control.h"
 
 static void usage(char *name)
 {
-	fprintf(stdout, "Usage %s <option(s)>\n", name);
-	fprintf(stdout, "Set example %s -Dhw:0 ", name);
-	fprintf(stdout, "-c \"numid=22,name=\\\"EQIIR1.0 EQIIR\\\"\" -s ");
-	fprintf(stdout, "iir.txt\n");
-	fprintf(stdout, "Set example %s -Dhw:0 -n 22 -s iir.txt\n", name);
-	fprintf(stdout, "Get example %s -Dhw:0 -n 22\n", name);
-	fprintf(stdout, "%s:\t \t\tControl SOF equalizers\n", name);
-	fprintf(stdout, "%s:\t -D <dev>\tUse device <dev>, defaults to hw:0\n",
-		name);
-	fprintf(stdout, "%s:\t -c <name>\tGet configuration for EQ <name>\n",
-		name);
-	fprintf(stdout, "%s:\t -n <number>\tGet configuration for ", name);
-	fprintf(stdout, "given numid\n");
-	fprintf(stdout, "%s:\t -s <file>\tSetup equalizer with data", name);
-	fprintf(stdout, "in <file>.\n");
-	fprintf(stdout, "\t\t\t\tThe ASCII text file must contain comma\n");
-	fprintf(stdout, "\t\t\t\tseparated unsigned integers.\n");
-	exit(0);
+	fprintf(stdout, "Usage:\t %s [-D <device>] [-c <control name>]", name);
+	fprintf(stdout, " [-s <data>]\n");
+	fprintf(stdout, "\t %s [-D <device>] [-n <control id>]", name);
+	fprintf(stdout, " [-s <data>]\n");
+	fprintf(stdout, "\t %s -h\n", name);
+	fprintf(stdout, "\nWhere:\n");
+	fprintf(stdout, " -D device name (default is hw:0)\n");
+	fprintf(stdout, " -c control name e.g.");
+	fprintf(stdout, " numid=22,name=\\\"EQIIR1.0 EQIIR\\\"\"\n");
+	fprintf(stdout, " -n control id e.g. 22\n");
+	fprintf(stdout, " -s set data using ASCII CSV input file\n");
 }
 
 static int read_setup(unsigned int *data, char setup[], size_t smax)
@@ -75,6 +70,17 @@ static int read_setup(unsigned int *data, char setup[], size_t smax)
 	return n;
 }
 
+static void header_dump(struct sof_abi_hdr *hdr)
+{
+	fprintf(stdout, "hdr: magic 0x%8.8x\n", hdr->magic);
+	fprintf(stdout, "hdr: type %d", hdr->type);
+	fprintf(stdout, "hdr: size %d bytes\n", hdr->size);
+	fprintf(stdout, "hdr: abi %d:%d:%d\n",
+		SOF_ABI_VERSION_MAJOR(hdr->abi),
+		SOF_ABI_VERSION_MINOR(hdr->abi),
+		SOF_ABI_VERSION_PATCH(hdr->abi));
+}
+
 int main(int argc, char *argv[])
 {
 	snd_ctl_t *ctl;
@@ -202,6 +208,9 @@ int main(int argc, char *argv[])
 			free(user_data);
 			exit(EXIT_FAILURE);
 		}
+
+		header_dump((struct sof_abi_hdr *)&user_data[2]);
+
 		user_data[1] = n * sizeof(unsigned int);
 		ret = snd_ctl_elem_tlv_write(ctl, id, user_data);
 		if (ret) {
@@ -224,6 +233,8 @@ int main(int argc, char *argv[])
 		}
 		fprintf(stdout, "Success.\n");
 
+		header_dump((struct sof_abi_hdr *)&user_data[2]);
+
 		/* Print the read EQ configuration data with similar syntax
 		 * as the input file format.
 		 */