From: Marcin Maka <marcin.maka@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@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@linux.intel.com> */ +/** + * \file include/uapi/abi.h + * \brief ABI definitions + * \author Liam Girdwood <liam.r.girdwood@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@linux.intel.com> */ +/** + * \file include/uapi/ipc.h + * \brief IPC definitions + * \author Liam Girdwood <liam.r.girdwood@linux.intel.com> + * \author Keyon Jie <yang.jie@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@linux.intel.com> */ +/** + * \file include/uapi/ipc.h + * \brief FW Image Manifest definitions. + * \author Liam Girdwood <liam.r.girdwood@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