From 2a1755db022eab9f1cf43b7a3b3ce1b610121589 Mon Sep 17 00:00:00 2001 From: Dustin Brown Date: Fri, 22 Mar 2019 13:39:13 -0700 Subject: [PATCH] qcacld-3.0: Add osif_sync high level documentation While the concepts of osif_sync started out as a simple set of APIs, it ultimately evolved into its own full-fledge code module. While the per-function documenation is present, high-level documentation for the osif_sync code module as a whole was over looked. Add a high-level description of the purpose of osif_sync in osif_sync.h Change-Id: I42cd28673b500c85ecf95de4b507b677804892ba CRs-Fixed: 2421801 --- os_if/sync/inc/osif_sync.h | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/os_if/sync/inc/osif_sync.h b/os_if/sync/inc/osif_sync.h index 779543f21c66..02fc97c93c38 100644 --- a/os_if/sync/inc/osif_sync.h +++ b/os_if/sync/inc/osif_sync.h @@ -16,6 +16,30 @@ * PERFORMANCE OF THIS SOFTWARE. */ +/** + * DOC: Operating System Interface, Synchronization (osif_sync) + * + * osif_sync is a collection of APIs for synchronizing and safely interacting + * with external processes/threads via various operating system interfaces. It + * relies heavily on the Driver Synchronization Core, which defines the + * synchronization primitives and behavior. + * + * While DSC is great at doing the required synchronization, it (by design) does + * not address the gap between receiving a callback and involing the appropriate + * DSC protections. For example, given an input net_device pointer from the + * kernel, how does one safely aquire the appropriate DSC context? osif_sync + * implements this logic via wrapping DSC APIs with a registration mechanism. + * + * For example, after the creation of a new dsc_vdev context, osif_sync allows + * it to be registered with a specific net_device pointer as a key. Future + * operations against this net_device can use this pointer to atomically lookup + * the DSC context, and start either a DSC transition or DSC operation. If this + * is successful, the operation continues and is guaranteed protected from major + * state changes. Otherwise, the operation attempt is rejected. + * + * See also: wlan_dsc.h + */ + #ifndef __OSIF_SYNC_H #define __OSIF_SYNC_H