Eric Lee / linux-smarc-t335x-v3.2

Download as
Browse Code ยป

Commit 1243ba98e3abecd12e9e90dd390801b95ef070f2

Authored by Jonathan Corbet
1 parent 161291396e

Update flex_arrays.txt 

The 2.6.32 merge window brought a number of changes to the flexible array
API; this patch updates the documentation to match the new state of
affairs.

Acked-by: David Rientjes <rientjes@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Showing 1 changed file with 32 additions and 11 deletions Side-by-side Diff

Documentation/flexible-arrays.txt
Diff comments   View file @ 1243ba9
1 1 Using flexible arrays in the kernel
2   -Last updated for 2.6.31
  2 +Last updated for 2.6.32
3 3 Jonathan Corbet <corbet@lwn.net>
4 4  
5 5 Large contiguous memory allocations can be unreliable in the Linux kernel.
... ... @@ -40,6 +40,13 @@
40 40 the current code, using flags to ask for high memory is likely to lead to
41 41 notably unpleasant side effects.
42 42  
  43 +It is also possible to define flexible arrays at compile time with:
  44 +
  45 + DEFINE_FLEX_ARRAY(name, element_size, total);
  46 +
  47 +This macro will result in a definition of an array with the given name; the
  48 +element size and total will be checked for validity at compile time.
  49 +
43 50 Storing data into a flexible array is accomplished with a call to:
44 51  
45 52 int flex_array_put(struct flex_array *array, unsigned int element_nr,
46 53  
... ... @@ -76,16 +83,30 @@
76 83 Note that it is possible to get back a valid pointer for an element which
77 84 has never been stored in the array. Memory for array elements is allocated
78 85 one page at a time; a single allocation could provide memory for several
79   -adjacent elements. The flexible array code does not know if a specific
80   -element has been written; it only knows if the associated memory is
81   -present. So a flex_array_get() call on an element which was never stored
82   -in the array has the potential to return a pointer to random data. If the
83   -caller does not have a separate way to know which elements were actually
84   -stored, it might be wise, at least, to add GFP_ZERO to the flags argument
85   -to ensure that all elements are zeroed.
  86 +adjacent elements. Flexible array elements are normally initialized to the
  87 +value FLEX_ARRAY_FREE (defined as 0x6c in <linux/poison.h>), so errors
  88 +involving that number probably result from use of unstored array entries.
  89 +Note that, if array elements are allocated with __GFP_ZERO, they will be
  90 +initialized to zero and this poisoning will not happen.
86 91  
87   -There is no way to remove a single element from the array. It is possible,
88   -though, to remove all elements with a call to:
  92 +Individual elements in the array can be cleared with:
  93 +
  94 + int flex_array_clear(struct flex_array *array, unsigned int element_nr);
  95 +
  96 +This function will set the given element to FLEX_ARRAY_FREE and return
  97 +zero. If storage for the indicated element is not allocated for the array,
  98 +flex_array_clear() will return -EINVAL instead. Note that clearing an
  99 +element does not release the storage associated with it; to reduce the
  100 +allocated size of an array, call:
  101 +
  102 + int flex_array_shrink(struct flex_array *array);
  103 +
  104 +The return value will be the number of pages of memory actually freed.
  105 +This function works by scanning the array for pages containing nothing but
  106 +FLEX_ARRAY_FREE bytes, so (1) it can be expensive, and (2) it will not work
  107 +if the array's pages are allocated with __GFP_ZERO.
  108 +
  109 +It is possible to remove all elements of an array with a call to:
89 110  
90 111 void flex_array_free_parts(struct flex_array *array);
91 112