Add doxygen docs to all calls in the public header

Add a .clang-format file as well

Change-Id: I09a146ebf75f9fdd3b338a3b283e73632e0c6e40

4 files changed, 588 insertions, 23 deletions

diff --git a/.clang-format b/.clang-format
new file mode 100644
index 0000000..1d5da22
--- /dev/null
+++ b/.clang-format
@@ -0,0 +1,428 @@
+# SPDX-License-Identifier: GPL-2.0
+#
+# clang-format configuration file. Intended for clang-format >= 4.
+#
+# For more information, see:
+#
+#   Documentation/process/clang-format.rst
+#   https://clang.llvm.org/docs/ClangFormat.html
+#   https://clang.llvm.org/docs/ClangFormatStyleOptions.html
+#
+---
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+#AlignEscapedNewlines: Left # Unknown to clang-format-4.0
+AlignOperands: true
+AlignTrailingComments: false
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: false
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass: false
+  AfterControlStatement: false
+  AfterEnum: false
+  AfterFunction: true
+  AfterNamespace: true
+  AfterObjCDeclaration: false
+  AfterStruct: false
+  AfterUnion: false
+  #AfterExternBlock: false # Unknown to clang-format-5.0
+  BeforeCatch: false
+  BeforeElse: false
+  IndentBraces: false
+  #SplitEmptyFunction: true # Unknown to clang-format-4.0
+  #SplitEmptyRecord: true # Unknown to clang-format-4.0
+  #SplitEmptyNamespace: true # Unknown to clang-format-4.0
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Custom
+#BreakBeforeInheritanceComma: false # Unknown to clang-format-4.0
+BreakBeforeTernaryOperators: false
+BreakConstructorInitializersBeforeComma: false
+#BreakConstructorInitializers: BeforeComma # Unknown to clang-format-4.0
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: false
+ColumnLimit: 80
+CommentPragmas: '^ IWYU pragma:'
+#CompactNamespaces: false # Unknown to clang-format-4.0
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 8
+ContinuationIndentWidth: 8
+Cpp11BracedListStyle: false
+DerivePointerAlignment: false
+DisableFormat: false
+ExperimentalAutoDetectBinPacking: false
+#FixNamespaceComments: false # Unknown to clang-format-4.0
+
+# Taken from:
+#   git grep -h '^#define [^[:space:]]*for_each[^[:space:]]*(' include/ \
+#   | sed "s,^#define \([^[:space:]]*for_each[^[:space:]]*\)(.*$,  - '\1'," \
+#   | sort | uniq
+ForEachMacros:
+  - 'apei_estatus_for_each_section'
+  - 'ata_for_each_dev'
+  - 'ata_for_each_link'
+  - 'ax25_for_each'
+  - 'ax25_uid_for_each'
+  - 'bio_for_each_integrity_vec'
+  - '__bio_for_each_segment'
+  - 'bio_for_each_segment'
+  - 'bio_for_each_segment_all'
+  - 'bio_list_for_each'
+  - 'bip_for_each_vec'
+  - 'blkg_for_each_descendant_post'
+  - 'blkg_for_each_descendant_pre'
+  - 'blk_queue_for_each_rl'
+  - 'bond_for_each_slave'
+  - 'bond_for_each_slave_rcu'
+  - 'btree_for_each_safe128'
+  - 'btree_for_each_safe32'
+  - 'btree_for_each_safe64'
+  - 'btree_for_each_safel'
+  - 'card_for_each_dev'
+  - 'cgroup_taskset_for_each'
+  - 'cgroup_taskset_for_each_leader'
+  - 'cpufreq_for_each_entry'
+  - 'cpufreq_for_each_entry_idx'
+  - 'cpufreq_for_each_valid_entry'
+  - 'cpufreq_for_each_valid_entry_idx'
+  - 'css_for_each_child'
+  - 'css_for_each_descendant_post'
+  - 'css_for_each_descendant_pre'
+  - 'device_for_each_child_node'
+  - 'drm_atomic_crtc_for_each_plane'
+  - 'drm_atomic_crtc_state_for_each_plane'
+  - 'drm_atomic_crtc_state_for_each_plane_state'
+  - 'drm_for_each_connector_iter'
+  - 'drm_for_each_crtc'
+  - 'drm_for_each_encoder'
+  - 'drm_for_each_encoder_mask'
+  - 'drm_for_each_fb'
+  - 'drm_for_each_legacy_plane'
+  - 'drm_for_each_plane'
+  - 'drm_for_each_plane_mask'
+  - 'drm_mm_for_each_hole'
+  - 'drm_mm_for_each_node'
+  - 'drm_mm_for_each_node_in_range'
+  - 'drm_mm_for_each_node_safe'
+  - 'for_each_active_drhd_unit'
+  - 'for_each_active_iommu'
+  - 'for_each_available_child_of_node'
+  - 'for_each_bio'
+  - 'for_each_board_func_rsrc'
+  - 'for_each_bvec'
+  - 'for_each_child_of_node'
+  - 'for_each_clear_bit'
+  - 'for_each_clear_bit_from'
+  - 'for_each_cmsghdr'
+  - 'for_each_compatible_node'
+  - 'for_each_console'
+  - 'for_each_cpu'
+  - 'for_each_cpu_and'
+  - 'for_each_cpu_not'
+  - 'for_each_cpu_wrap'
+  - 'for_each_dev_addr'
+  - 'for_each_dma_cap_mask'
+  - 'for_each_drhd_unit'
+  - 'for_each_dss_dev'
+  - 'for_each_efi_memory_desc'
+  - 'for_each_efi_memory_desc_in_map'
+  - 'for_each_endpoint_of_node'
+  - 'for_each_evictable_lru'
+  - 'for_each_fib6_node_rt_rcu'
+  - 'for_each_fib6_walker_rt'
+  - 'for_each_free_mem_range'
+  - 'for_each_free_mem_range_reverse'
+  - 'for_each_func_rsrc'
+  - 'for_each_hstate'
+  - 'for_each_if'
+  - 'for_each_iommu'
+  - 'for_each_ip_tunnel_rcu'
+  - 'for_each_irq_nr'
+  - 'for_each_lru'
+  - 'for_each_matching_node'
+  - 'for_each_matching_node_and_match'
+  - 'for_each_memblock'
+  - 'for_each_memblock_type'
+  - 'for_each_memcg_cache_index'
+  - 'for_each_mem_pfn_range'
+  - 'for_each_mem_range'
+  - 'for_each_mem_range_rev'
+  - 'for_each_migratetype_order'
+  - 'for_each_msi_entry'
+  - 'for_each_net'
+  - 'for_each_netdev'
+  - 'for_each_netdev_continue'
+  - 'for_each_netdev_continue_rcu'
+  - 'for_each_netdev_feature'
+  - 'for_each_netdev_in_bond_rcu'
+  - 'for_each_netdev_rcu'
+  - 'for_each_netdev_reverse'
+  - 'for_each_netdev_safe'
+  - 'for_each_net_rcu'
+  - 'for_each_new_connector_in_state'
+  - 'for_each_new_crtc_in_state'
+  - 'for_each_new_plane_in_state'
+  - 'for_each_new_private_obj_in_state'
+  - 'for_each_node'
+  - 'for_each_node_by_name'
+  - 'for_each_node_by_type'
+  - 'for_each_node_mask'
+  - 'for_each_node_state'
+  - 'for_each_node_with_cpus'
+  - 'for_each_node_with_property'
+  - 'for_each_of_allnodes'
+  - 'for_each_of_allnodes_from'
+  - 'for_each_of_pci_range'
+  - 'for_each_old_connector_in_state'
+  - 'for_each_old_crtc_in_state'
+  - 'for_each_oldnew_connector_in_state'
+  - 'for_each_oldnew_crtc_in_state'
+  - 'for_each_oldnew_plane_in_state'
+  - 'for_each_oldnew_private_obj_in_state'
+  - 'for_each_old_plane_in_state'
+  - 'for_each_old_private_obj_in_state'
+  - 'for_each_online_cpu'
+  - 'for_each_online_node'
+  - 'for_each_online_pgdat'
+  - 'for_each_pci_bridge'
+  - 'for_each_pci_dev'
+  - 'for_each_pci_msi_entry'
+  - 'for_each_populated_zone'
+  - 'for_each_possible_cpu'
+  - 'for_each_present_cpu'
+  - 'for_each_prime_number'
+  - 'for_each_prime_number_from'
+  - 'for_each_process'
+  - 'for_each_process_thread'
+  - 'for_each_property_of_node'
+  - 'for_each_reserved_mem_region'
+  - 'for_each_resv_unavail_range'
+  - 'for_each_rtdcom'
+  - 'for_each_rtdcom_safe'
+  - 'for_each_set_bit'
+  - 'for_each_set_bit_from'
+  - 'for_each_sg'
+  - 'for_each_sg_page'
+  - '__for_each_thread'
+  - 'for_each_thread'
+  - 'for_each_zone'
+  - 'for_each_zone_zonelist'
+  - 'for_each_zone_zonelist_nodemask'
+  - 'fwnode_for_each_available_child_node'
+  - 'fwnode_for_each_child_node'
+  - 'fwnode_graph_for_each_endpoint'
+  - 'gadget_for_each_ep'
+  - 'hash_for_each'
+  - 'hash_for_each_possible'
+  - 'hash_for_each_possible_rcu'
+  - 'hash_for_each_possible_rcu_notrace'
+  - 'hash_for_each_possible_safe'
+  - 'hash_for_each_rcu'
+  - 'hash_for_each_safe'
+  - 'hctx_for_each_ctx'
+  - 'hlist_bl_for_each_entry'
+  - 'hlist_bl_for_each_entry_rcu'
+  - 'hlist_bl_for_each_entry_safe'
+  - 'hlist_for_each'
+  - 'hlist_for_each_entry'
+  - 'hlist_for_each_entry_continue'
+  - 'hlist_for_each_entry_continue_rcu'
+  - 'hlist_for_each_entry_continue_rcu_bh'
+  - 'hlist_for_each_entry_from'
+  - 'hlist_for_each_entry_from_rcu'
+  - 'hlist_for_each_entry_rcu'
+  - 'hlist_for_each_entry_rcu_bh'
+  - 'hlist_for_each_entry_rcu_notrace'
+  - 'hlist_for_each_entry_safe'
+  - '__hlist_for_each_rcu'
+  - 'hlist_for_each_safe'
+  - 'hlist_nulls_for_each_entry'
+  - 'hlist_nulls_for_each_entry_from'
+  - 'hlist_nulls_for_each_entry_rcu'
+  - 'hlist_nulls_for_each_entry_safe'
+  - 'ide_host_for_each_port'
+  - 'ide_port_for_each_dev'
+  - 'ide_port_for_each_present_dev'
+  - 'idr_for_each_entry'
+  - 'idr_for_each_entry_continue'
+  - 'idr_for_each_entry_ul'
+  - 'inet_bind_bucket_for_each'
+  - 'inet_lhash2_for_each_icsk_rcu'
+  - 'iov_for_each'
+  - 'key_for_each'
+  - 'key_for_each_safe'
+  - 'klp_for_each_func'
+  - 'klp_for_each_object'
+  - 'kvm_for_each_memslot'
+  - 'kvm_for_each_vcpu'
+  - 'list_for_each'
+  - 'list_for_each_entry'
+  - 'list_for_each_entry_continue'
+  - 'list_for_each_entry_continue_rcu'
+  - 'list_for_each_entry_continue_reverse'
+  - 'list_for_each_entry_from'
+  - 'list_for_each_entry_from_reverse'
+  - 'list_for_each_entry_lockless'
+  - 'list_for_each_entry_rcu'
+  - 'list_for_each_entry_reverse'
+  - 'list_for_each_entry_safe'
+  - 'list_for_each_entry_safe_continue'
+  - 'list_for_each_entry_safe_from'
+  - 'list_for_each_entry_safe_reverse'
+  - 'list_for_each_prev'
+  - 'list_for_each_prev_safe'
+  - 'list_for_each_safe'
+  - 'llist_for_each'
+  - 'llist_for_each_entry'
+  - 'llist_for_each_entry_safe'
+  - 'llist_for_each_safe'
+  - 'media_device_for_each_entity'
+  - 'media_device_for_each_intf'
+  - 'media_device_for_each_link'
+  - 'media_device_for_each_pad'
+  - 'netdev_for_each_lower_dev'
+  - 'netdev_for_each_lower_private'
+  - 'netdev_for_each_lower_private_rcu'
+  - 'netdev_for_each_mc_addr'
+  - 'netdev_for_each_uc_addr'
+  - 'netdev_for_each_upper_dev_rcu'
+  - 'netdev_hw_addr_list_for_each'
+  - 'nft_rule_for_each_expr'
+  - 'nla_for_each_attr'
+  - 'nla_for_each_nested'
+  - 'nlmsg_for_each_attr'
+  - 'nlmsg_for_each_msg'
+  - 'nr_neigh_for_each'
+  - 'nr_neigh_for_each_safe'
+  - 'nr_node_for_each'
+  - 'nr_node_for_each_safe'
+  - 'of_for_each_phandle'
+  - 'of_property_for_each_string'
+  - 'of_property_for_each_u32'
+  - 'pci_bus_for_each_resource'
+  - 'ping_portaddr_for_each_entry'
+  - 'plist_for_each'
+  - 'plist_for_each_continue'
+  - 'plist_for_each_entry'
+  - 'plist_for_each_entry_continue'
+  - 'plist_for_each_entry_safe'
+  - 'plist_for_each_safe'
+  - 'pnp_for_each_card'
+  - 'pnp_for_each_dev'
+  - 'protocol_for_each_card'
+  - 'protocol_for_each_dev'
+  - 'queue_for_each_hw_ctx'
+  - 'radix_tree_for_each_contig'
+  - 'radix_tree_for_each_slot'
+  - 'radix_tree_for_each_tagged'
+  - 'rbtree_postorder_for_each_entry_safe'
+  - 'resource_list_for_each_entry'
+  - 'resource_list_for_each_entry_safe'
+  - 'rhl_for_each_entry_rcu'
+  - 'rhl_for_each_rcu'
+  - 'rht_for_each'
+  - 'rht_for_each_continue'
+  - 'rht_for_each_entry'
+  - 'rht_for_each_entry_continue'
+  - 'rht_for_each_entry_rcu'
+  - 'rht_for_each_entry_rcu_continue'
+  - 'rht_for_each_entry_safe'
+  - 'rht_for_each_rcu'
+  - 'rht_for_each_rcu_continue'
+  - '__rq_for_each_bio'
+  - 'rq_for_each_segment'
+  - 'scsi_for_each_prot_sg'
+  - 'scsi_for_each_sg'
+  - 'sctp_for_each_hentry'
+  - 'sctp_skb_for_each'
+  - 'shdma_for_each_chan'
+  - '__shost_for_each_device'
+  - 'shost_for_each_device'
+  - 'sk_for_each'
+  - 'sk_for_each_bound'
+  - 'sk_for_each_entry_offset_rcu'
+  - 'sk_for_each_from'
+  - 'sk_for_each_rcu'
+  - 'sk_for_each_safe'
+  - 'sk_nulls_for_each'
+  - 'sk_nulls_for_each_from'
+  - 'sk_nulls_for_each_rcu'
+  - 'snd_pcm_group_for_each_entry'
+  - 'snd_soc_dapm_widget_for_each_path'
+  - 'snd_soc_dapm_widget_for_each_path_safe'
+  - 'snd_soc_dapm_widget_for_each_sink_path'
+  - 'snd_soc_dapm_widget_for_each_source_path'
+  - 'tb_property_for_each'
+  - 'udp_portaddr_for_each_entry'
+  - 'udp_portaddr_for_each_entry_rcu'
+  - 'usb_hub_for_each_child'
+  - 'v4l2_device_for_each_subdev'
+  - 'v4l2_m2m_for_each_dst_buf'
+  - 'v4l2_m2m_for_each_dst_buf_safe'
+  - 'v4l2_m2m_for_each_src_buf'
+  - 'v4l2_m2m_for_each_src_buf_safe'
+  - 'zorro_for_each_dev'
+
+#IncludeBlocks: Preserve # Unknown to clang-format-5.0
+IncludeCategories:
+  - Regex: '.*'
+    Priority: 1
+IncludeIsMainRegex: '(Test)?$'
+IndentCaseLabels: false
+#IndentPPDirectives: None # Unknown to clang-format-5.0
+IndentWidth: 8
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+MacroBlockBegin: ''
+MacroBlockEnd: ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: Inner
+#ObjCBinPackProtocolList: Auto # Unknown to clang-format-5.0
+ObjCBlockIndentWidth: 8
+ObjCSpaceAfterProperty: true
+ObjCSpaceBeforeProtocolList: true
+
+# Taken from git's rules
+#PenaltyBreakAssignment: 10 # Unknown to clang-format-4.0
+PenaltyBreakBeforeFirstCallParameter: 30
+PenaltyBreakComment: 10
+PenaltyBreakFirstLessLess: 0
+PenaltyBreakString: 10
+PenaltyExcessCharacter: 100
+PenaltyReturnTypeOnItsOwnLine: 60
+
+PointerAlignment: Right
+ReflowComments: false
+SortIncludes: false
+#SortUsingDeclarations: false # Unknown to clang-format-4.0
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+#SpaceBeforeCtorInitializerColon: true # Unknown to clang-format-5.0
+#SpaceBeforeInheritanceColon: true # Unknown to clang-format-5.0
+SpaceBeforeParens: ControlStatements
+#SpaceBeforeRangeBasedForLoopColon: true # Unknown to clang-format-5.0
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: false
+SpacesInContainerLiterals: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: Cpp03
+TabWidth: 8
+UseTab: Always
+...
diff --git a/aoc_ipc_core.c b/aoc_ipc_core.c
index 013676d..0f7b4d1 100644
--- a/aoc_ipc_core.c
+++ b/aoc_ipc_core.c
@@ -23,7 +23,6 @@
  * very different coding styles, disable automatic formatting
  */
 
-/* clang-format off */
 #define AOC_ASSERT(x)
 #define VALID_DIRECTION(d) ((d == AOC_UP) || (d == AOC_DOWN))
 
@@ -77,9 +76,9 @@ static size_t _difference_with_overflow(struct aoc_ipc_memory_region *r)
 		return tx - rx;
 	} else {
 		/*
-		 * The tx counter has overflowed the 32 bit counter, so calculate the
-		 * difference with a larger type
-		 */
+     * The tx counter has overflowed the 32 bit counter, so calculate the
+     * difference with a larger type
+     */
 		return ((tx + 0x100000000) - rx);
 	}
 }
@@ -111,14 +110,14 @@ static size_t _aoc_ring_read_buffer(const u8 *ring,
 
 	if (available > ring_size) {
 		/*
-		 * Overflow.  Reader has not kept up with the writer
-		 * Move the read pointer up to make the diff ring_size
-		 */
+     * Overflow.  Reader has not kept up with the writer
+     * Move the read pointer up to make the diff ring_size
+     */
 
 		/*
-		 * Drag the rx value up to tx - ring_size, but tx has recently
-		 * wrapped. rx will still be before the wrap value (0xffffffff)
-		 */
+     * Drag the rx value up to tx - ring_size, but tx has recently
+     * wrapped. rx will still be before the wrap value (0xffffffff)
+     */
 		if (tx < ring_size)
 			rx = (tx + 0x100000000 - ring_size);
 		else
@@ -311,18 +310,18 @@ size_t aoc_service_slots_available_to_read(aoc_service *service,
 
 	if (aoc_service_is_ring(service)) {
 		/*
-		 * Rings have one slot and the tx/rx counters specify bytes.  If the
-		 * byte counters match, there is nothing to read
-		 */
+     * Rings have one slot and the tx/rx counters specify bytes.  If the
+     * byte counters match, there is nothing to read
+     */
 		return ioread32(&region->tx) != ioread32(&region->rx) ? 1 : 0;
 	} else {
 		size_t diff = _difference_with_overflow(region);
 
 		/*
-		 * TODO : The API contract says that the difference will never be larger
-		 * than the # of slots on the channel.  Figure out what to do if this
-		 * assumption is ever false.
-		 */
+     * TODO : The API contract says that the difference will never be larger
+     * than the # of slots on the channel.  Figure out what to do if this
+     * assumption is ever false.
+     */
 		return diff > region->slots ? region->slots : diff;
 	}
 }
@@ -407,8 +406,9 @@ void *aoc_service_current_message_pointer(aoc_service *service, void *base,
 {
 	uint8_t *ptr;
 
-	if (!aoc_service_can_read_message(service, dir))
+	if (!aoc_service_can_read_message(service, dir)) {
 		return NULL;
+	}
 
 	ptr = aoc_service_current_read_pointer(service, base, dir);
 	ptr += sizeof(struct aoc_ipc_message_header);
diff --git a/aoc_ipc_core.h b/aoc_ipc_core.h
index 797010e..9c80a7f 100644
--- a/aoc_ipc_core.h
+++ b/aoc_ipc_core.h
@@ -33,37 +33,164 @@ extern "C" {
 
 typedef void aoc_service;
 
+/**
+ * Direction indicates Tx/Rx for each side of the link
+ * AOC UP	FW -> AP communication
+ * AOC_DOWN 	AP -> FW communication
+ */
 typedef enum {
 	AOC_UP = 0,
 	AOC_DOWN = 1,
 } aoc_direction;
 
-/* Primitive functions */
+/**
+ * Check if a passed in service is a ring
+ *
+ * \param[in] service pointer to a service
+ *
+ * \return true if service is a ring service, otherwise false
+ */
 bool aoc_service_is_ring(aoc_service *service);
 
+/**
+ * Return the name of a service
+ *
+ * \param[in] service pointer to a service
+ *
+ * \return the name of the service, or NULL on error
+ */
 const char *aoc_service_name(aoc_service *service);
 
+/**
+ * Return the size of a message slot
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return the size of a message slot, or 0 on error
+ */
 size_t aoc_service_message_size(aoc_service *service, aoc_direction dir);
+
+/**
+ * Return the total number of message slots
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return total number of message slots, or 0 on error
+ */
 size_t aoc_service_message_slots(aoc_service *service, aoc_direction dir);
+
+/**
+ * Return the total size of the IPC region
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return total size for all messages on a service
+ */
 size_t aoc_service_total_size(aoc_service *service, aoc_direction dir);
 
+/**
+ * Return the number of pending messages to be read
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return number of pending messages
+ */
 size_t aoc_service_slots_available_to_read(aoc_service *service,
 					   aoc_direction dir);
+
+/**
+ * Return the number of free slots available to write
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return number of slots available to write
+ */
 size_t aoc_service_slots_available_to_write(aoc_service *service,
 					    aoc_direction dir);
 
-/* High level functions */
+/**
+ * Check if any messages are available to read
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return true if there are pending messages, otherwise false
+ */
 bool aoc_service_can_read_message(aoc_service *service, aoc_direction dir);
+
+/**
+ * Check if there is a free message slot
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return true if a message can be written, otherwise false
+ */
 bool aoc_service_can_write_message(aoc_service *service, aoc_direction dir);
 
+/**
+ * Read one message out of the queue
+ *
+ * \param[in] service pointer to a service
+ * \param[in] base pointer to the base of IPC memory
+ * \param[in] dir direction for the message
+ * \param[out] dst memory to copy the message to
+ * \param[inout] size size of the buffer, then size of the outgoing message
+ *
+ * \return true if a message was read, otherwise false
+ */
 bool aoc_service_read_message(aoc_service *service, void *base,
 			      aoc_direction dir, void *dst, size_t *size);
+
+/**
+ * Write a message to the queue
+ *
+ * \param[in] service pointer to a service
+ * \param[in] base pointer to the base of IPC memory
+ * \param[in] dir direction for the message
+ * \param[in] dst memory to copy the message from
+ * \param[in] size size of the incoming message
+ *
+ * \return true if a message was read, otherwise false
+ */
 bool aoc_service_write_message(aoc_service *service, void *base,
 			       aoc_direction dir, const void *dst, size_t size);
 
+/**
+ * Total number of bytes read from a ring service
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return total number of bytes read from the service, up to UINT32_MAX
+ */
 size_t aoc_ring_bytes_read(aoc_service *service, aoc_direction dir);
+
+/**
+ * Total number of bytes written to a ring service
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return total number of bytes written to the service, up to UINT32_MAX
+ */
 size_t aoc_ring_bytes_written(aoc_service *service, aoc_direction dir);
 
+/**
+ * Tells if more data has been written to the ring than it's capacity
+ *
+ * \param[in] service pointer to a service
+ * \param[in] dir direction for the message
+ *
+ * \return true if data has been overflowed, otherwise false
+ */
+bool aoc_ring_did_overflow(aoc_service *service, aoc_direction dir);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/aoc_ipc_core_internal.h b/aoc_ipc_core_internal.h
index 2adac40..d2b329e 100644
--- a/aoc_ipc_core_internal.h
+++ b/aoc_ipc_core_internal.h
@@ -54,7 +54,7 @@ struct aoc_control_block {
 	u32 services;
 	u32 service_size;
 	u32 services_offset;
-} __attribute__((packed));
+} __attribute__((packed, aligned(4)));
 
 struct aoc_ipc_memory_region {
 	u32 offset;
@@ -62,14 +62,21 @@ struct aoc_ipc_memory_region {
 	u32 slots;
 	u32 tx;
 	u32 rx;
-} __attribute__((packed));
+} __attribute__((packed, aligned(4)));
+
+enum REGION_COMM {
+	REGION_COMM_TX = 0,
+	REGION_COMM_RX,
+
+	REGION_COMM_TOT = 2
+};
 
 struct aoc_ipc_service_header {
 	char name[AOC_SERVICE_NAME_LENGTH];
 	u32 flags;
 
 	struct aoc_ipc_memory_region regions[2];
-} __attribute__((packed));
+} __attribute__((packed, aligned(4)));
 
 struct aoc_ipc_message_header {
 	u16 length;
@@ -89,6 +96,9 @@ size_t aoc_ring_bytes_available_to_read(aoc_service *service,
 size_t aoc_ring_bytes_available_to_write(aoc_service *service,
 					 aoc_direction dir);
 
+bool aoc_ring_flush_read_data(aoc_service *service, aoc_direction dir, size_t bytes_to_leave);
+
+void *aoc_service_current_message_pointer(aoc_service *service, void *base, aoc_direction dir);
 void *aoc_service_current_read_pointer(struct aoc_ipc_service_header *service,
 				       void *base, aoc_direction dir);
 void *aoc_service_current_write_pointer(struct aoc_ipc_service_header *service,