From 4d2c9d5ddc3a38abb12253b4fd6ac05bfc3b4462 Mon Sep 17 00:00:00 2001 From: Cruz Julian Bishop Date: Tue, 3 Sep 2013 22:05:07 +1000 Subject: staging/android: Initial partial kernel-doc for ashmem.c I am beginning to understand the core concepts at play here. I am nowhere near finished with this class - However, it is better if I commit what I have documented so far tonight - That way, if I mess up tomorrow morning, I can just roll back to here. Sorry if this clutters things up. In the end, once *everything* is documented, it will make understanding the Android staging driver easier to understand as a programmer - Hopefully for both new developers and current ones. Signed-off-by: Cruz Julian Bishop Signed-off-by: Greg Kroah-Hartman diff --git a/drivers/staging/android/ashmem.c b/drivers/staging/android/ashmem.c index 8e76ddc..acfaeae 100644 --- a/drivers/staging/android/ashmem.c +++ b/drivers/staging/android/ashmem.c @@ -37,41 +37,59 @@ #define ASHMEM_NAME_PREFIX_LEN (sizeof(ASHMEM_NAME_PREFIX) - 1) #define ASHMEM_FULL_NAME_LEN (ASHMEM_NAME_LEN + ASHMEM_NAME_PREFIX_LEN) -/* - * ashmem_area - anonymous shared memory area - * Lifecycle: From our parent file's open() until its release() - * Locking: Protected by `ashmem_mutex' - * Big Note: Mappings do NOT pin this structure; it dies on close() +/** + * struct ashmem_area - The anonymous shared memory area + * @name: The optional name in /proc/pid/maps + * @unpinned_list: The list of all ashmem areas + * @file: The shmem-based backing file + * @size: The size of the mapping, in bytes + * @prot_masks: The allowed protection bits, as vm_flags + * + * The lifecycle of this structure is from our parent file's open() until + * its release(). It is also protected by 'ashmem_mutex' + * + * Warning: Mappings do NOT pin this structure; It dies on close() */ struct ashmem_area { - char name[ASHMEM_FULL_NAME_LEN]; /* optional name in /proc/pid/maps */ - struct list_head unpinned_list; /* list of all ashmem areas */ - struct file *file; /* the shmem-based backing file */ - size_t size; /* size of the mapping, in bytes */ - unsigned long prot_mask; /* allowed prot bits, as vm_flags */ + char name[ASHMEM_FULL_NAME_LEN]; + struct list_head unpinned_list; + struct file *file; + size_t size; + unsigned long prot_mask; }; -/* - * ashmem_range - represents an interval of unpinned (evictable) pages - * Lifecycle: From unpin to pin - * Locking: Protected by `ashmem_mutex' +/** + * struct ashmem_range - A range of unpinned/evictable pages + * @lru: The entry in the LRU list + * @unpinned: The entry in its area's unpinned list + * @asma: The associated anonymous shared memory area. + * @pgstart: The starting page (inclusive) + * @pgend: The ending page (inclusive) + * @purged: The purge status (ASHMEM_NOT or ASHMEM_WAS_PURGED) + * + * The lifecycle of this structure is from unpin to pin. + * It is protected by 'ashmem_mutex' */ struct ashmem_range { - struct list_head lru; /* entry in LRU list */ - struct list_head unpinned; /* entry in its area's unpinned list */ - struct ashmem_area *asma; /* associated area */ - size_t pgstart; /* starting page, inclusive */ - size_t pgend; /* ending page, inclusive */ - unsigned int purged; /* ASHMEM_NOT or ASHMEM_WAS_PURGED */ + struct list_head lru; + struct list_head unpinned; + struct ashmem_area *asma; + size_t pgstart; + size_t pgend; + unsigned int purged; }; /* LRU list of unpinned pages, protected by ashmem_mutex */ static LIST_HEAD(ashmem_lru_list); -/* Count of pages on our LRU list, protected by ashmem_mutex */ +/** + * long lru_count - The count of pages on our LRU list. + * + * This is protected by ashmem_mutex. + */ static unsigned long lru_count; -/* +/** * ashmem_mutex - protects the list of and each individual ashmem_area * * Lock Ordering: ashmex_mutex -> i_mutex -> i_alloc_sem @@ -105,28 +123,43 @@ static struct kmem_cache *ashmem_range_cachep __read_mostly; #define PROT_MASK (PROT_EXEC | PROT_READ | PROT_WRITE) +/** + * lru_add() - Adds a range of memory to the LRU list + * @range: The memory range being added. + * + * The range is first added to the end (tail) of the LRU list. + * After this, the size of the range is added to @lru_count + */ static inline void lru_add(struct ashmem_range *range) { list_add_tail(&range->lru, &ashmem_lru_list); lru_count += range_size(range); } +/** + * lru_del() - Removes a range of memory from the LRU list + * @range: The memory range being removed + * + * The range is first deleted from the LRU list. + * After this, the size of the range is removed from @lru_count + */ static inline void lru_del(struct ashmem_range *range) { list_del(&range->lru); lru_count -= range_size(range); } -/* - * range_alloc - allocate and initialize a new ashmem_range structure +/** + * range_alloc() - Allocates and initializes a new ashmem_range structure + * @asma: The associated ashmem_area + * @prev_range: The previous ashmem_range in the sorted asma->unpinned list + * @purged: Initial purge status (ASMEM_NOT_PURGED or ASHMEM_WAS_PURGED) + * @start: The starting page (inclusive) + * @end: The ending page (inclusive) * - * 'asma' - associated ashmem_area - * 'prev_range' - the previous ashmem_range in the sorted asma->unpinned list - * 'purged' - initial purge value (ASMEM_NOT_PURGED or ASHMEM_WAS_PURGED) - * 'start' - starting page, inclusive - * 'end' - ending page, inclusive + * This function is protected by ashmem_mutex. * - * Caller must hold ashmem_mutex. + * Return: 0 if successful, or -ENOMEM if there is an error */ static int range_alloc(struct ashmem_area *asma, struct ashmem_range *prev_range, unsigned int purged, @@ -151,6 +184,10 @@ static int range_alloc(struct ashmem_area *asma, return 0; } +/** + * range_del() - Deletes and dealloctes an ashmem_range structure + * @range: The associated ashmem_range that has previously been allocated + */ static void range_del(struct ashmem_range *range) { list_del(&range->unpinned); -- cgit v0.10.2