diff --git a/spa/include/spa/param/audio/raw.h b/spa/include/spa/param/audio/raw.h index a890cb5b3..0b1fe19f6 100644 --- a/spa/include/spa/param/audio/raw.h +++ b/spa/include/spa/param/audio/raw.h @@ -62,47 +62,27 @@ extern "C" { #define SPA_TYPE_AUDIO_FORMAT__F64LE SPA_TYPE_AUDIO_FORMAT_BASE "F64LE" #define SPA_TYPE_AUDIO_FORMAT__F64BE SPA_TYPE_AUDIO_FORMAT_BASE "F64BE" -/** - * spa_audio_flags: - * @SPA_AUDIO_FLAG_NONE: no valid flag - * @SPA_AUDIO_FLAG_UNPOSITIONED: the position array explicitly - * contains unpositioned channels. - * - * Extra audio flags - */ +/** Extra audio flags */ enum spa_audio_flags { - SPA_AUDIO_FLAG_NONE = 0, - SPA_AUDIO_FLAG_UNPOSITIONED = (1 << 0) + SPA_AUDIO_FLAG_NONE = 0, /*< no valid flag */ + SPA_AUDIO_FLAG_UNPOSITIONED = (1 << 0), /*< the position array explicitly + * contains unpositioned channels. */ }; -/** - * spa_audio_layout: - * @SPA_AUDIO_LAYOUT_INTERLEAVED: interleaved audio - * @SPA_AUDIO_LAYOUT_NON_INTERLEAVED: non-interleaved audio - * - * Layout of the audio samples for the different channels. - */ +/** Layout of the audio samples for the different channels. */ enum spa_audio_layout { - SPA_AUDIO_LAYOUT_INTERLEAVED = 0, - SPA_AUDIO_LAYOUT_NON_INTERLEAVED + SPA_AUDIO_LAYOUT_INTERLEAVED = 0, /*< interleaved audio */ + SPA_AUDIO_LAYOUT_NON_INTERLEAVED /*< non-interleaved audio */ }; -/** - * spa_audio_info_raw: - * @format: the format - * @flags: extra flags - * @layout: the sample layout - * @rate: the sample rate - * @channels: the number of channels - * @channel_mask: the channel mask - */ +/** Audio information description */ struct spa_audio_info_raw { - uint32_t format; - enum spa_audio_flags flags; - enum spa_audio_layout layout; - uint32_t rate; - uint32_t channels; - uint32_t channel_mask; + uint32_t format; /*< format, one of SPA_TYPE__AudioFormat */ + enum spa_audio_flags flags; /*< extra flags */ + enum spa_audio_layout layout; /*< sample layout */ + uint32_t rate; /*< sample rate */ + uint32_t channels; /*< number of channels */ + uint32_t channel_mask; /*< channel mask */ }; #ifdef __cplusplus diff --git a/spa/include/spa/param/video/chroma.h b/spa/include/spa/param/video/chroma.h index 7c296f75a..7d38346ce 100644 --- a/spa/include/spa/param/video/chroma.h +++ b/spa/include/spa/param/video/chroma.h @@ -24,8 +24,7 @@ extern "C" { #endif -/** - * spa_video_chroma_site: +/** Various Chroma sitings. * @SPA_VIDEO_CHROMA_SITE_UNKNOWN: unknown cositing * @SPA_VIDEO_CHROMA_SITE_NONE: no cositing * @SPA_VIDEO_CHROMA_SITE_H_COSITED: chroma is horizontally cosited @@ -35,8 +34,6 @@ extern "C" { * @SPA_VIDEO_CHROMA_SITE_JPEG: jpeg style cositing, also for mpeg1 and mjpeg * @SPA_VIDEO_CHROMA_SITE_MPEG2: mpeg2 style cositing * @SPA_VIDEO_CHROMA_SITE_DV: DV style cositing - * - * Various Chroma sitings. */ enum spa_video_chroma_site { SPA_VIDEO_CHROMA_SITE_UNKNOWN = 0, diff --git a/spa/include/spa/support/log.h b/spa/include/spa/support/log.h index f11142f72..260f6339a 100644 --- a/spa/include/spa/support/log.h +++ b/spa/include/spa/support/log.h @@ -41,40 +41,33 @@ enum spa_log_level { }; /** - * struct spa_log: - * * The Log interface */ struct spa_log { - /* the version of this log. This can be used to expand this + /** the version of this log. This can be used to expand this * structure in the future */ #define SPA_VERSION_LOG 0 uint32_t version; /** - * struct spa_log::info - * * Extra information about the log */ const struct spa_dict *info; /** - * struct spa_log::level - * * Logging level, everything above this level is not logged */ enum spa_log_level level; /** - * struct spa_log::log - * @log: a #struct spa_log - * @level: a #enum spa_log_level - * @file: the file name - * @line: the line number - * @func: the function name - * @fmt: printf style format - * @...: format arguments - * * Log a message with the given log level. + * + * \param log a spa_log + * \param level a spa_log_level + * \param file the file name + * \param line the line number + * \param func the function name + * \param fmt printf style format + * \param ... format arguments */ void (*log) (struct spa_log *log, enum spa_log_level level, @@ -84,16 +77,15 @@ struct spa_log { const char *fmt, ...) SPA_PRINTF_FUNC(6, 7); /** - * struct spa_log::logv - * @log: a #struct spa_log - * @level: a #enum spa_log_level - * @file: the file name - * @line: the line number - * @func: the function name - * @fmt: printf style format - * @args: format arguments - * * Log a message with the given log level. + * + * \param log a spa_log + * \param level a spa_log_level + * \param file the file name + * \param line the line number + * \param func the function name + * \param fmt printf style format + * \param args format arguments */ void (*logv) (struct spa_log *log, enum spa_log_level level, diff --git a/spa/include/spa/support/loop.h b/spa/include/spa/support/loop.h index 52094b017..4c1f76228 100644 --- a/spa/include/spa/support/loop.h +++ b/spa/include/spa/support/loop.h @@ -67,8 +67,6 @@ typedef int (*spa_invoke_func_t) (struct spa_loop *loop, void *user_data); /** - * spa_loop: - * * Register sources and work items to an event loop */ struct spa_loop { @@ -114,8 +112,6 @@ struct spa_loop_control_hooks { }; /** - * spa_loop_control: - * * Control an event loop */ struct spa_loop_control { @@ -154,8 +150,6 @@ typedef void (*spa_source_timer_func_t) (void *data, uint64_t expirations); typedef void (*spa_source_signal_func_t) (void *data, int signal_number); /** - * struct spa_loop_utils: - * * Create sources for an event loop */ struct spa_loop_utils { diff --git a/spa/include/spa/support/plugin.h b/spa/include/spa/support/plugin.h index 82f3ee07f..bd13e9550 100644 --- a/spa/include/spa/support/plugin.h +++ b/spa/include/spa/support/plugin.h @@ -38,26 +38,22 @@ struct spa_handle { /* user_data that can be set by the application */ void *user_data; /** - * spa_handle::get_interface: - * @handle: a #spa_handle - * @interface_id: the interface id - * @interface: result to hold the interface. + * Get the interface provided by \a handle with \a interface_id. * - * Get the interface provided by @handle with @interface_id. - * - * Returns: #SPA_RESULT_OK on success - * #SPA_RESULT_NOT_IMPLEMENTED when there are no extensions - * #SPA_RESULT_INVALID_ARGUMENTS when handle or info is %NULL + * \param handle a spa_handle + * \param interface_id the interface id + * \param interface result to hold the interface. + * \return 0 on success + * -ENOTSUP when there are no interfaces + * -EINVAL when handle or info is NULL */ int (*get_interface) (struct spa_handle *handle, uint32_t interface_id, void **interface); /** - * spa_handle::clear - * @handle: a pointer to memory - * - * Clean up the memory of @handle. After this, @handle should not be used + * Clean up the memory of \a handle. After this, \a handle should not be used * anymore. * - * Returns: #SPA_RESULT_OK on success + * \param handle a pointer to memory + * \return 0 on success */ int (*clear) (struct spa_handle *handle); }; @@ -66,29 +62,24 @@ struct spa_handle { #define spa_handle_clear(h) (h)->clear((h)) /** - * struct spa_interface_info: - * @type: the type of the interface, can be used to get the interface - * * This structure lists the information about available interfaces on * handles. */ struct spa_interface_info { - const char *type; + const char *type; /*< the type of the interface, can be + * used to get the interface */ }; /** - * struct spa_support: - * @type: the type of the support item - * @data: specific data for the item - * * Extra supporting infrastructure passed to the init() function of * a factory. It can be extra information or interfaces such as logging. */ struct spa_support { - const char *type; - void *data; + const char *type; /*< the type of the support item */ + void *data; /*< specific data for the item */ }; +/** Find a support item of the given type */ static inline void *spa_support_find(const struct spa_support *support, uint32_t n_support, const char *type) @@ -107,42 +98,33 @@ struct spa_handle_factory { #define SPA_VERSION_HANDLE_FACTORY 0 uint32_t version; /** - * spa_handle_factory::name - * * The name */ const char *name; /** - * spa_handle_factory::info - * * Extra information about the handles of this factory. */ const struct spa_dict *info; /** - * spa_handle_factory::size - * * The size of handles from this factory */ const size_t size; /** - * spa_handle_factory::init - * @factory: a #spa_handle_factory - * @handle: a pointer to memory - * @info: extra handle specific information, usually obtained - * from a #spa_monitor. This can be used to configure the handle. - * @support: support items - * @n_support: number of elements in @support - * * Initialize an instance of this factory. The caller should allocate - * memory at least spa_handle_factory::size bytes and pass this as @handle. + * memory at least size bytes and pass this as \a handle. * - * @support can optionally contain extra interfaces or data ites that the + * \a support can optionally contain extra interfaces or data items that the * plugin can use such as a logger. * - * Returns: #SPA_RESULT_OK on success - * #SPA_RESULT_NOT_IMPLEMENTED when an instance can't be made - * #SPA_RESULT_INVALID_ARGUMENTS when factory or handle are %NULL + * \param factory a spa_handle_factory + * \param handle a pointer to memory + * \param info extra handle specific information, usually obtained + * from a spa_monitor. This can be used to configure the handle. + * \param support support items + * \param n_support number of elements in \a support + * \return 0 on success + * < 0 errno type error */ int (*init) (const struct spa_handle_factory *factory, struct spa_handle *handle, @@ -152,15 +134,15 @@ struct spa_handle_factory { /** * spa_handle_factory::enum_interface_info: - * @factory: a #spa_handle_factory - * @info: result to hold spa_interface_info. - * @index: index to keep track of the enumeration, 0 for first item + * \param factory: a #spa_handle_factory + * \param info: result to hold spa_interface_info. + * \param index: index to keep track of the enumeration, 0 for first item * - * Enumerate the interface information for @factory. + * Enumerate the interface information for \a factory. * - * Returns: 1 when an item is available - * 0 when no more items are available - * -errno on error + * \return 1 when an item is available + * 0 when no more items are available + * < 0 errno type error */ int (*enum_interface_info) (const struct spa_handle_factory *factory, const struct spa_interface_info **info, @@ -171,15 +153,13 @@ struct spa_handle_factory { #define spa_handle_factory_enum_interface_info(h,...) (h)->enum_interface_info((h),__VA_ARGS__) /** - * spa_handle_factory_enum_func_t: - * @factory: a location to hold the factory result - * @index: index to keep track of the enumeration - * * The function signature of the entry point in a plugin. * - * Returns: #SPA_RESULT_OK on success - * #SPA_RESULT_INVALID_ARGUMENTS when factory is %NULL - * #SPA_RESULT_ENUM_END when there are no more factories + * \param factory a location to hold the factory result + * \param index index to keep track of the enumeration + * \return 1 on success + * 0 when there are no more factories + * -EINVAL when factory is NULL */ typedef int (*spa_handle_factory_enum_func_t) (const struct spa_handle_factory **factory, uint32_t *index); @@ -187,15 +167,13 @@ typedef int (*spa_handle_factory_enum_func_t) (const struct spa_handle_factory * #define SPA_HANDLE_FACTORY_ENUM_FUNC_NAME "spa_handle_factory_enum" /** - * spa_handle_factory_enum: - * @factory: a location to hold the factory result - * @index: index to keep track of the enumeration - * * The entry point in a plugin. * - * Returns: 1 on success - * 0 when no more items are available - * -errno on error + * \param factory a location to hold the factory result + * \param index index to keep track of the enumeration + * \return 1 on success + * 0 when no more items are available + * < 0 errno type error */ int spa_handle_factory_enum(const struct spa_handle_factory **factory, uint32_t *index); diff --git a/spa/include/spa/support/type-map.h b/spa/include/spa/support/type-map.h index eb688bcb8..9e5335000 100644 --- a/spa/include/spa/support/type-map.h +++ b/spa/include/spa/support/type-map.h @@ -30,18 +30,14 @@ extern "C" { #define SPA_TYPE__TypeMap SPA_TYPE_INTERFACE_BASE "TypeMap" /** - * spa_type_map: - * * Maps between string types and their type id */ struct spa_type_map { - /* the version of this structure. This can be used to expand this + /** the version of this structure. This can be used to expand this * structure in the future */ #define SPA_VERSION_TYPE_MAP 0 uint32_t version; /** - * spa_type_map::info - * * Extra information about the type map */ const struct spa_dict *info; diff --git a/spa/include/spa/utils/ringbuffer.h b/spa/include/spa/utils/ringbuffer.h index d164aea0b..b563c9703 100644 --- a/spa/include/spa/utils/ringbuffer.h +++ b/spa/include/spa/utils/ringbuffer.h @@ -33,27 +33,23 @@ struct spa_ringbuffer; #include /** - * spa_ringbuffer: - * @readindex: the current read index - * @writeindex: the current write index - * @size: the size of the ringbuffer - * @mask: mask as @size - 1 + * A ringbuffer type. */ struct spa_ringbuffer { - uint32_t readindex; - uint32_t writeindex; - uint32_t size; - uint32_t mask; + uint32_t readindex; /*< the current read index */ + uint32_t writeindex; /*< the current write index */ + uint32_t size; /*< the size of the ringbuffer */ + uint32_t mask; /*< mask as \a size - 1, only valid if \a size is + * a power of 2. */ }; #define SPA_RINGBUFFER_INIT(size) (struct spa_ringbuffer) { 0, 0, (size), (size)-1 } /** - * spa_ringbuffer_init: - * @rbuf: a #struct spa_ringbuffer - * @size: the number of elements in the ringbuffer + * Initialize a spa_ringbuffer with \a size. * - * Initialize a #struct spa_ringbuffer with @size. + * \param rbuf a spa_ringbuffer + * \param size the number of elements in the ringbuffer */ static inline void spa_ringbuffer_init(struct spa_ringbuffer *rbuf, uint32_t size) { @@ -61,10 +57,9 @@ static inline void spa_ringbuffer_init(struct spa_ringbuffer *rbuf, uint32_t siz } /** - * spa_ringbuffer_clear: - * @rbuf: a #struct spa_ringbuffer + * Clear \a rbuf, sets the pointers so that the ringbuffer is empty. * - * Clear @rbuf + * \param rbuf a spa_ringbuffer */ static inline void spa_ringbuffer_clear(struct spa_ringbuffer *rbuf) { @@ -73,53 +68,46 @@ static inline void spa_ringbuffer_clear(struct spa_ringbuffer *rbuf) } /** - * spa_ringbuffer_get_read_index: - * @rbuf: a #struct spa_ringbuffer - * @index: the value of readindex, should be masked to get the - * offset in the ringbuffer memory + * Get the read index and available bytes for reading. * - * Returns: number of available bytes to read. values < 0 mean - * there was an underrun. values > rbuf->size means there - * was an overrun. + * \param rbuf a spa_ringbuffer + * \param index the value of readindex, should be masked to get the + * offset in the ringbuffer memory + * \return number of available bytes to read. values < 0 mean + * there was an underrun. values > rbuf->size means there + * was an overrun. */ static inline int32_t spa_ringbuffer_get_read_index(struct spa_ringbuffer *rbuf, uint32_t *index) { - int32_t avail; - *index = __atomic_load_n(&rbuf->readindex, __ATOMIC_RELAXED); - avail = (int32_t) (__atomic_load_n(&rbuf->writeindex, __ATOMIC_ACQUIRE) - *index); - - return avail; + return (int32_t) (__atomic_load_n(&rbuf->writeindex, __ATOMIC_ACQUIRE) - *index); } /** - * spa_ringbuffer_read_data: - * @rbuf: a #struct spa_ringbuffer - * @buffer: memory to read from - * @offset: offset in @buffer to read from - * @data: destination memory - * @len: number of bytes to read + * Read \a len bytes from \a rbuf starting \a offset. \a offset must be masked + * with the size of \a rbuf and len should be smaller than the size. * - * Read @len bytes from @rbuf starting @offset. @offset must be masked - * with the size of @rbuf and len should be smaller than the size. + * \param rbuf a #struct spa_ringbuffer + * \param buffer memory to read from + * \param offset offset in \a buffer to read from + * \param data destination memory + * \param len number of bytes to read */ static inline void spa_ringbuffer_read_data(struct spa_ringbuffer *rbuf, - void *buffer, uint32_t offset, void *data, uint32_t len) + const void *buffer, uint32_t offset, void *data, uint32_t len) { uint32_t first = SPA_MIN(len, rbuf->size - offset); memcpy(data, buffer + offset, first); - if (SPA_UNLIKELY(len > first)) { + if (SPA_UNLIKELY(len > first)) memcpy(data + first, buffer, len - first); - } } /** - * spa_ringbuffer_read_update: - * @rbuf: a #struct spa_ringbuffer - * @index: new index + * Update the read pointer to \a index. * - * Update the read pointer to @index + * \param rbuf a spa_ringbuffer + * \param index new index */ static inline void spa_ringbuffer_read_update(struct spa_ringbuffer *rbuf, int32_t index) { @@ -127,44 +115,47 @@ static inline void spa_ringbuffer_read_update(struct spa_ringbuffer *rbuf, int32 } /** - * spa_ringbuffer_get_write_index: - * @rbuf: a #struct spa_ringbuffer - * @index: the value of writeindex, should be masked to get the - * offset in the ringbuffer memory + * Get the write index and the number of bytes inside the ringbuffer. * - * Returns: the fill level of @rbuf. values < 0 mean - * there was an underrun. values > rbuf->size means there - * was an overrun. Subtract from the buffer size to get - * the number of bytes available for writing. + * \param rbuf a spa_ringbuffer + * \param index the value of writeindex, should be masked to get the + * offset in the ringbuffer memory + * \return the fill level of \a rbuf. values < 0 mean + * there was an underrun. values > rbuf->size means there + * was an overrun. Subtract from the buffer size to get + * the number of bytes available for writing. */ static inline int32_t spa_ringbuffer_get_write_index(struct spa_ringbuffer *rbuf, uint32_t *index) { - int32_t filled; - *index = __atomic_load_n(&rbuf->writeindex, __ATOMIC_RELAXED); - filled = (int32_t) (*index - __atomic_load_n(&rbuf->readindex, __ATOMIC_ACQUIRE)); - - return filled; -} - -static inline void -spa_ringbuffer_write_data(struct spa_ringbuffer *rbuf, - void *buffer, uint32_t offset, void *data, uint32_t len) -{ - uint32_t first = SPA_MIN(len, rbuf->size - offset); - memcpy(buffer + offset, data, first); - if (SPA_UNLIKELY(len > first)) { - memcpy(buffer, data + first, len - first); - } + return (int32_t) (*index - __atomic_load_n(&rbuf->readindex, __ATOMIC_ACQUIRE)); } /** - * spa_ringbuffer_write_update: - * @rbuf: a #struct spa_ringbuffer - * @index: new index + * Write \a len bytes to \a rbuf starting \a offset. \a offset must be masked + * with the size of \a rbuf and len should be smaller than the size. * - * Update the write pointer to @index + * \param rbuf a spa_ringbuffer + * \param buffer memory to write to + * \param offset offset in \a buffer to write to + * \param data source memory + * \param len number of bytes to write + */ +static inline void +spa_ringbuffer_write_data(struct spa_ringbuffer *rbuf, + void *buffer, uint32_t offset, const void *data, uint32_t len) +{ + uint32_t first = SPA_MIN(len, rbuf->size - offset); + memcpy(buffer + offset, data, first); + if (SPA_UNLIKELY(len > first)) + memcpy(buffer, data + first, len - first); +} + +/** + * Update the write pointer to \a index * + * \param rbuf a spa_ringbuffer + * \param index new index */ static inline void spa_ringbuffer_write_update(struct spa_ringbuffer *rbuf, int32_t index) { diff --git a/spa/plugins/alsa/alsa-monitor.c b/spa/plugins/alsa/alsa-monitor.c index 5a275f360..e887613a4 100644 --- a/spa/plugins/alsa/alsa-monitor.c +++ b/spa/plugins/alsa/alsa-monitor.c @@ -68,9 +68,6 @@ struct impl { uint32_t index; struct udev_list_entry *devices; -// uint8_t item_buffer[4096]; -// struct spa_monitor_item *item; - snd_ctl_t *ctl_hndl; struct udev_device *dev; char card_name[16];