[Sound-open-firmware] [PATCH] Makefile support for doc target.
Liam Girdwood
liam.r.girdwood at linux.intel.com
Fri Apr 13 15:59:27 CEST 2018
From: Marcin Maka <marcin.maka at linux.intel.com>
Builds uapi documentation in html format using doxygen.
See doc/sof_uapi/html/index.html
First dox samples in the source code provided by the patch.
Signed-off-by: Marcin Maka <marcin.maka at linux.intel.com>
---
.gitignore | 2 ++
Makefile.am | 7 ++++++-
configure.ac | 1 +
doc/Makefile.am | 10 ++++++++++
doc/sof_uapi.doxygen.in | 33 +++++++++++++++++++++++++++++++++
src/include/uapi/abi.h | 30 ++++++++++++++++++++----------
src/include/uapi/ipc.h | 17 ++++++++++++-----
src/include/uapi/manifest.h | 15 ++++++++++++++-
8 files changed, 98 insertions(+), 17 deletions(-)
create mode 100644 doc/Makefile.am
create mode 100644 doc/sof_uapi.doxygen.in
diff --git a/.gitignore b/.gitignore
index 4c5b67bc..c03c83ef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,6 +37,8 @@ m4/lt*
m4/libtool.m4
libtool
src/include/version.h
+doc/sof_uapi
+*.doxygen
autom4te*
config.*
diff --git a/Makefile.am b/Makefile.am
index 1e4de766..ee8df72b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,7 +1,7 @@
if BUILD_RIMAGE
SUBDIRS = rimage
else
-SUBDIRS = src
+SUBDIRS = doc src
endif
ACLOCAL_AMFLAGS = -I m4
@@ -39,5 +39,10 @@ dist-hook:
cat .version > $(distdir)/.tarball-version
cat .version > $(distdir)/.version
+doc-dummy:
+
+doc: doc-dummy
+ $(MAKE) -C doc doc
+
all-local:
rm -f $(top_srcdir)/src/include/version.h
diff --git a/configure.ac b/configure.ac
index 6bd1323c..2765f0e4 100644
--- a/configure.ac
+++ b/configure.ac
@@ -335,6 +335,7 @@ AC_CONFIG_FILES([
Makefile
rimage/Makefile
rimage/keys/Makefile
+ doc/Makefile
src/Makefile
src/tasks/Makefile
src/init/Makefile
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 00000000..200c55bc
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,10 @@
+EXTRA_DIST=sof_uapi.doxygen
+
+AM_CPPFLAGS=-I$(top_srcdir)/include
+
+doc:
+ test -e sof_uapi.doxygen || sed s:[@]top_srcdir[@]:..:g sof_uapi.doxygen.in > sof_uapi.doxygen
+ doxygen sof_uapi.doxygen
+
+doc-clean:
+ rm -rf $(top_srcdir)/doc/sof_uapi/*
diff --git a/doc/sof_uapi.doxygen.in b/doc/sof_uapi.doxygen.in
new file mode 100644
index 00000000..74052f1a
--- /dev/null
+++ b/doc/sof_uapi.doxygen.in
@@ -0,0 +1,33 @@
+PROJECT_NAME = "Sound Open Firmware"
+OUTPUT_DIRECTORY = sof_uapi
+GENERATE_LATEX = NO
+GENERATE_RTF = NO
+GENERATE_MAN = NO
+GENERATE_XML = YES
+
+CASE_SENSE_NAMES = NO
+INPUT = @top_srcdir@/src/include/uapi
+EXCLUDE =
+RECURSIVE = YES
+FILE_PATTERNS = *.c *.h
+EXAMPLE_PATH = ../test
+IMAGE_PATH =
+QUIET = YES
+
+EXTRACT_ALL = NO
+EXTRACT_STATIC = NO
+SHOW_INCLUDE_FILES = NO
+JAVADOC_AUTOBRIEF = NO
+INHERIT_DOCS = YES
+ENABLED_SECTIONS = ""
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+PREDEFINED =
+
+OPTIMIZE_OUTPUT_FOR_C = YES
+TYPEDEF_HIDES_STRUCT = YES
+
+#INPUT_FILTER = inputfilter
+#FILTER_SOURCE_FILES = YES
+
+HTML_TIMESTAMP = NO
diff --git a/src/include/uapi/abi.h b/src/include/uapi/abi.h
index 8b700a89..cb28aea4 100644
--- a/src/include/uapi/abi.h
+++ b/src/include/uapi/abi.h
@@ -28,24 +28,34 @@
* Author: Liam Girdwood <liam.r.girdwood at linux.intel.com>
*/
+/**
+ * \file include/uapi/abi.h
+ * \brief ABI definitions
+ * \author Liam Girdwood <liam.r.girdwood at linux.intel.com>
+ */
+
#ifndef __INCLUDE_UAPI_ABI_H__
#define __INCLUDE_UAPI_ABI_H__
+/** \brief SOF ABI version number. */
#define SOF_ABI_VERSION 1
-#define SOF_ABI_MAGIC 0x00464F53 /* "SOF\0" */
-/*
- * Header for all non IPC ABI data. Identifies data type, size and ABI.
+/** \brief SOF ABI magic number "SOF\0". */
+#define SOF_ABI_MAGIC 0x00464F53
+
+/**
+ * \brief Header for all non IPC ABI data.
+ *
+ * Identifies data type, size and ABI.
* Used by any bespoke component data structures or binary blobs.
*/
-
struct sof_abi_hdr {
- uint32_t magic; /* 'S', 'O', 'F', '\0' */
- uint32_t type; /* component specific type */
- uint32_t size; /* size in bytes of data excluding this struct */
- uint32_t abi; /* SOF ABI version */
- uint32_t comp_abi; /* component specific ABI version */
- char data[0];
+ uint32_t magic; /**< 'S', 'O', 'F', '\0' */
+ uint32_t type; /**< component specific type */
+ uint32_t size; /**< size in bytes of data excl. this struct */
+ uint32_t abi; /**< SOF ABI version */
+ uint32_t comp_abi; /**< component specific ABI version */
+ char data[0]; /**< data */
} __attribute__((packed));
#endif
diff --git a/src/include/uapi/ipc.h b/src/include/uapi/ipc.h
index 396a3c49..7d0a9a44 100644
--- a/src/include/uapi/ipc.h
+++ b/src/include/uapi/ipc.h
@@ -29,6 +29,13 @@
* Keyon Jie <yang.jie at linux.intel.com>
*/
+/**
+ * \file include/uapi/ipc.h
+ * \brief IPC definitions
+ * \author Liam Girdwood <liam.r.girdwood at linux.intel.com>
+ * \author Keyon Jie <yang.jie at linux.intel.com>
+ */
+
#ifndef __INCLUDE_UAPI_IPC_H__
#define __INCLUDE_UAPI_IPC_H__
@@ -219,12 +226,12 @@ struct sof_ipc_compound_hdr {
#define SOF_DAI_FMT_INV_MASK 0x0f00
#define SOF_DAI_FMT_MASTER_MASK 0xf000
-/* types of DAI */
+/** \brief Types of DAI */
enum sof_ipc_dai_type {
- SOF_DAI_INTEL_NONE = 0,
- SOF_DAI_INTEL_SSP,
- SOF_DAI_INTEL_DMIC,
- SOF_DAI_INTEL_HDA,
+ SOF_DAI_INTEL_NONE = 0, /**< None */
+ SOF_DAI_INTEL_SSP, /**< Intel SSP */
+ SOF_DAI_INTEL_DMIC, /**< Intel DMIC */
+ SOF_DAI_INTEL_HDA, /**< Intel HD/A */
};
/* SSP Configuration Request - SOF_IPC_DAI_SSP_CONFIG */
diff --git a/src/include/uapi/manifest.h b/src/include/uapi/manifest.h
index f53a6628..c1dce92f 100644
--- a/src/include/uapi/manifest.h
+++ b/src/include/uapi/manifest.h
@@ -28,6 +28,12 @@
* Author: Liam Girdwood <liam.r.girdwood at linux.intel.com>
*/
+/**
+ * \file include/uapi/ipc.h
+ * \brief FW Image Manifest definitions.
+ * \author Liam Girdwood <liam.r.girdwood at linux.intel.com>
+ */
+
#ifndef SOF_UAPI_MANIFEST_H
#define SOF_UAPI_MANIFEST_H
@@ -211,7 +217,14 @@ struct sof_man_module_manifest {
uint32_t text_size;
};
-/* utility to get module pointer from position */
+/**
+ * \brief Utility to get module pointer from position.
+ * \param [in,out] desc FW descriptor in manifest.
+ * \param [in] index Index of the module.
+ * \return Pointer to module descriptor.
+ *
+ * Note that index is not verified against OOB.
+ */
static inline struct sof_man_module *sof_man_get_module(
struct sof_man_fw_desc *desc, int index)
{
--
2.14.1
More information about the Sound-open-firmware
mailing list