[v2,1/6] staging/android: remove doc from sw_sync

Commit Message

Gustavo Padovan Aug. 8, 2016, 9:24 p.m. UTC

From: Gustavo Padovan <[e-mail]>

SW_SYNC should never be used by other pieces of the kernel apart from
sync_debug as it is only a Sync File Validation Framework, so hide any
info to avoid confuse this with a standard kernel internal API.

Signed-off-by: Gustavo Padovan <[e-mail]>
---
 drivers/staging/android/sw_sync.c    | 26 --------------------------
 drivers/staging/android/sync_debug.h | 15 ---------------
 2 files changed, 41 deletions(-)

Comments

Pavel Machek Aug. 8, 2016, 11:41 p.m. UTC | #1

On Mon 2016-08-08 18:24:17, Gustavo Padovan wrote:
> From: Gustavo Padovan <[e-mail]>
> 
> SW_SYNC should never be used by other pieces of the kernel apart from
> sync_debug as it is only a Sync File Validation Framework, so hide any
> info to avoid confuse this with a standard kernel internal API.

> Signed-off-by: Gustavo Padovan <[e-mail]>

NAK.

It is unclear for what the code does, removing the docs is not going to help.

If it should not be used, document that it should not be used.. but not remove
the docs.

> -/**
> - * sync_timeline_signal() - signal a status change on a sync_timeline
> - * @obj:	sync_timeline to signal
> - * @inc:	num to increment on timeline->value
> - *
> - * A sync implementation should call this any time one of it's fences
> - * has signaled or has an error condition.
> - */
>  static void sync_timeline_signal(struct sync_timeline *obj, unsigned int inc)
>  {

And as the functions are static... there's little danger that someone will misuse them.

										Pavel

Gustavo Padovan Aug. 11, 2016, 3:06 p.m. UTC | #2

Hi Pavel,

2016-08-09 Pavel Machek <[e-mail]>:

> On Mon 2016-08-08 18:24:17, Gustavo Padovan wrote:
> > From: Gustavo Padovan <[e-mail]>
> > 
> > SW_SYNC should never be used by other pieces of the kernel apart from
> > sync_debug as it is only a Sync File Validation Framework, so hide any
> > info to avoid confuse this with a standard kernel internal API.
> 
> > Signed-off-by: Gustavo Padovan <[e-mail]>
> 
> NAK.
> 
> It is unclear for what the code does, removing the docs is not going to help.
> 
> If it should not be used, document that it should not be used.. but not remove
> the docs.

Okay, I'll skip this patch.

Patch

diff --git a/drivers/staging/android/sw_sync.c b/drivers/staging/android/sw_sync.c
index 115c917..b4ae092 100644
--- a/drivers/staging/android/sw_sync.c
+++ b/drivers/staging/android/sw_sync.c
@@ -46,13 +46,6 @@  static inline struct sync_pt *fence_to_sync_pt(struct fence *fence)
 	return container_of(fence, struct sync_pt, base);
 }
 
-/**
- * sync_timeline_create() - creates a sync object
- * @name:	sync_timeline name
- *
- * Creates a new sync_timeline. Returns the sync_timeline object or NULL in
- * case of error.
- */
 struct sync_timeline *sync_timeline_create(const char *name)
 {
 	struct sync_timeline *obj;
@@ -94,14 +87,6 @@  static void sync_timeline_put(struct sync_timeline *obj)
 	kref_put(&obj->kref, sync_timeline_free);
 }
 
-/**
- * sync_timeline_signal() - signal a status change on a sync_timeline
- * @obj:	sync_timeline to signal
- * @inc:	num to increment on timeline->value
- *
- * A sync implementation should call this any time one of it's fences
- * has signaled or has an error condition.
- */
 static void sync_timeline_signal(struct sync_timeline *obj, unsigned int inc)
 {
 	unsigned long flags;
@@ -122,17 +107,6 @@  static void sync_timeline_signal(struct sync_timeline *obj, unsigned int inc)
 	spin_unlock_irqrestore(&obj->child_list_lock, flags);
 }
 
-/**
- * sync_pt_create() - creates a sync pt
- * @parent:	fence's parent sync_timeline
- * @size:	size to allocate for this pt
- * @inc:	value of the fence
- *
- * Creates a new sync_pt as a child of @parent.  @size bytes will be
- * allocated allowing for implementation specific data to be kept after
- * the generic sync_timeline struct. Returns the sync_pt object or
- * NULL in case of error.
- */
 static struct sync_pt *sync_pt_create(struct sync_timeline *obj, int size,
 			     unsigned int value)
 {
diff --git a/drivers/staging/android/sync_debug.h b/drivers/staging/android/sync_debug.h
index fab6639..5b82cf8 100644
--- a/drivers/staging/android/sync_debug.h
+++ b/drivers/staging/android/sync_debug.h
@@ -20,15 +20,6 @@ 
 #include <linux/sync_file.h>
 #include <uapi/linux/sync_file.h>
 
-/**
- * struct sync_timeline - sync object
- * @kref:		reference count on fence.
- * @name:		name of the sync_timeline. Useful for debugging
- * @child_list_head:	list of children sync_pts for this sync_timeline
- * @child_list_lock:	lock protecting @child_list_head and fence.status
- * @active_list_head:	list of active (unsignaled/errored) sync_pts
- * @sync_timeline_list:	membership in global sync_timeline_list
- */
 struct sync_timeline {
 	struct kref		kref;
 	char			name[32];
@@ -51,12 +42,6 @@  static inline struct sync_timeline *fence_parent(struct fence *fence)
 			    child_list_lock);
 }
 
-/**
- * struct sync_pt - sync_pt object
- * @base: base fence object
- * @child_list: sync timeline child's list
- * @active_list: sync timeline active child's list
- */
 struct sync_pt {
 	struct fence base;
 	struct list_head child_list;