abuf.h 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159
  1. /* SPDX-License-Identifier: GPL-2.0+ */
  2. /*
  3. * Handles a buffer that can be allocated and freed
  4. *
  5. * Copyright 2021 Google LLC
  6. * Written by Simon Glass <sjg@chromium.org>
  7. */
  8. #ifndef __ABUF_H
  9. #define __ABUF_H
  10. #include <linux/types.h>
  11. /**
  12. * struct abuf - buffer that can be allocated and freed
  13. *
  14. * This is useful for a block of data which may be allocated with malloc(), or
  15. * not, so that it needs to be freed correctly when finished with.
  16. *
  17. * For now it has a very simple purpose.
  18. *
  19. * Using memset() to zero all fields is guaranteed to be equivalent to
  20. * abuf_init().
  21. *
  22. * @data: Pointer to data
  23. * @size: Size of data in bytes
  24. * @alloced: true if allocated with malloc(), so must be freed after use
  25. */
  26. struct abuf {
  27. void *data;
  28. size_t size;
  29. bool alloced;
  30. };
  31. static inline void *abuf_data(const struct abuf *abuf)
  32. {
  33. return abuf->data;
  34. }
  35. static inline size_t abuf_size(const struct abuf *abuf)
  36. {
  37. return abuf->size;
  38. }
  39. /**
  40. * abuf_set() - set the (unallocated) data in a buffer
  41. *
  42. * This simply makes the abuf point to the supplied data, which must be live
  43. * for the lifetime of the abuf. It is not alloced.
  44. *
  45. * Any existing data in the abuf is freed and the alloced member is set to
  46. * false.
  47. *
  48. * @abuf: abuf to adjust
  49. * @data: New contents of abuf
  50. * @size: New size of abuf
  51. */
  52. void abuf_set(struct abuf *abuf, void *data, size_t size);
  53. /**
  54. * abuf_map_sysmem() - calls map_sysmem() to set up an abuf
  55. *
  56. * This is equivalent to abuf_set(abuf, map_sysmem(addr, size), size)
  57. *
  58. * Any existing data in the abuf is freed and the alloced member is set to
  59. * false.
  60. *
  61. * @abuf: abuf to adjust
  62. * @addr: Address to set the abuf to
  63. * @size: New size of abuf
  64. */
  65. void abuf_map_sysmem(struct abuf *abuf, ulong addr, size_t size);
  66. /**
  67. * abuf_realloc() - Change the size of a buffer
  68. *
  69. * This uses realloc() to change the size of the buffer, with the same semantics
  70. * as that function. If the abuf is not currently alloced, then it will alloc
  71. * it if the size needs to increase (i.e. set the alloced member to true)
  72. *
  73. * @abuf: abuf to adjust
  74. * @new_size: new size in bytes.
  75. * if 0, the abuf is freed
  76. * if greater than the current size, the abuf is extended and the new
  77. * space is not inited. The alloced member is set to true
  78. * if less than the current size, the abuf is contracted and the data at
  79. * the end is lost. If @new_size is 0, this sets the alloced member to
  80. * false
  81. * Return: true if OK, false if out of memory
  82. */
  83. bool abuf_realloc(struct abuf *abuf, size_t new_size);
  84. /**
  85. * abuf_uninit_move() - Return the allocated contents and uninit the abuf
  86. *
  87. * This returns the abuf data to the caller, allocating it if necessary, so that
  88. * the caller receives data that it can be sure will hang around. The caller is
  89. * responsible for freeing the data.
  90. *
  91. * If the abuf has allocated data, it is returned. If the abuf has data but it
  92. * is not allocated, then it is first allocated, then returned.
  93. *
  94. * If the abuf size is 0, this returns NULL
  95. *
  96. * The abuf is uninited as part of this, except if the allocation fails, in
  97. * which NULL is returned and the abuf remains untouched.
  98. *
  99. * The abuf must be inited before this can be called.
  100. *
  101. * @abuf: abuf to uninit
  102. * @sizep: if non-NULL, returns the size of the returned data
  103. * Return: data contents, allocated with malloc(), or NULL if the data could not
  104. * be allocated, or the data size is 0
  105. */
  106. void *abuf_uninit_move(struct abuf *abuf, size_t *sizep);
  107. /**
  108. * abuf_init_move() - Make abuf take over the management of an allocated region
  109. *
  110. * After this, @data must not be used. All access must be via the abuf.
  111. *
  112. * @abuf: abuf to init
  113. * @data: Existing allocated buffer to place in the abuf
  114. * @size: Size of allocated buffer
  115. */
  116. void abuf_init_move(struct abuf *abuf, void *data, size_t size);
  117. /**
  118. * abuf_init_set() - Set up a new abuf
  119. *
  120. * Inits a new abuf and sets up its (unallocated) data
  121. *
  122. * @abuf: abuf to set up
  123. * @data: New contents of abuf
  124. * @size: New size of abuf
  125. */
  126. void abuf_init_set(struct abuf *abuf, void *data, size_t size);
  127. /**
  128. * abuf_uninit() - Free any memory used by an abuf
  129. *
  130. * The buffer must be inited before this can be called.
  131. *
  132. * @abuf: abuf to uninit
  133. */
  134. void abuf_uninit(struct abuf *abuf);
  135. /**
  136. * abuf_init() - Set up a new abuf
  137. *
  138. * This initially has no data and alloced is set to false. This is equivalent to
  139. * setting all fields to 0, e.g. with memset(), so callers can do that instead
  140. * if desired.
  141. *
  142. * @abuf: abuf to set up
  143. */
  144. void abuf_init(struct abuf *abuf);
  145. #endif