1/** @file
2  Provides copy memory, fill memory, zero memory, and GUID functions.
3
4  The Base Memory Library provides optimized implementations for common memory-based operations.
5  These functions should be used in place of coding your own loops to do equivalent common functions.
6  This allows optimized library implementations to help increase performance.
7
8Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
9This program and the accompanying materials are licensed and made available under
10the terms and conditions of the BSD License that accompanies this distribution.
11The full text of the license may be found at
12http://opensource.org/licenses/bsd-license.php.
13
14THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
15WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16
17**/
18
19#ifndef __BASE_MEMORY_LIB__
20#define __BASE_MEMORY_LIB__
21
22/**
23  Copies a source buffer to a destination buffer, and returns the destination buffer.
24
25  This function copies Length bytes from SourceBuffer to DestinationBuffer, and returns
26  DestinationBuffer.  The implementation must be reentrant, and it must handle the case
27  where SourceBuffer overlaps DestinationBuffer.
28
29  If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
30  If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
31
32  @param  DestinationBuffer   The pointer to the destination buffer of the memory copy.
33  @param  SourceBuffer        The pointer to the source buffer of the memory copy.
34  @param  Length              The number of bytes to copy from SourceBuffer to DestinationBuffer.
35
36  @return DestinationBuffer.
37
38**/
39VOID *
40EFIAPI
41CopyMem (
42  OUT VOID       *DestinationBuffer,
43  IN CONST VOID  *SourceBuffer,
44  IN UINTN       Length
45  );
46
47/**
48  Fills a target buffer with a byte value, and returns the target buffer.
49
50  This function fills Length bytes of Buffer with Value, and returns Buffer.
51
52  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
53
54  @param  Buffer    The memory to set.
55  @param  Length    The number of bytes to set.
56  @param  Value     The value with which to fill Length bytes of Buffer.
57
58  @return Buffer.
59
60**/
61VOID *
62EFIAPI
63SetMem (
64  OUT VOID  *Buffer,
65  IN UINTN  Length,
66  IN UINT8  Value
67  );
68
69/**
70  Fills a target buffer with a 16-bit value, and returns the target buffer.
71
72  This function fills Length bytes of Buffer with the 16-bit value specified by
73  Value, and returns Buffer. Value is repeated every 16-bits in for Length
74  bytes of Buffer.
75
76  If Length > 0 and Buffer is NULL, then ASSERT().
77  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
78  If Buffer is not aligned on a 16-bit boundary, then ASSERT().
79  If Length is not aligned on a 16-bit boundary, then ASSERT().
80
81  @param  Buffer  The pointer to the target buffer to fill.
82  @param  Length  The number of bytes in Buffer to fill.
83  @param  Value   The value with which to fill Length bytes of Buffer.
84
85  @return Buffer.
86
87**/
88VOID *
89EFIAPI
90SetMem16 (
91  OUT VOID   *Buffer,
92  IN UINTN   Length,
93  IN UINT16  Value
94  );
95
96/**
97  Fills a target buffer with a 32-bit value, and returns the target buffer.
98
99  This function fills Length bytes of Buffer with the 32-bit value specified by
100  Value, and returns Buffer. Value is repeated every 32-bits in for Length
101  bytes of Buffer.
102
103  If Length > 0 and Buffer is NULL, then ASSERT().
104  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
105  If Buffer is not aligned on a 32-bit boundary, then ASSERT().
106  If Length is not aligned on a 32-bit boundary, then ASSERT().
107
108  @param  Buffer  The pointer to the target buffer to fill.
109  @param  Length  The number of bytes in Buffer to fill.
110  @param  Value   The value with which to fill Length bytes of Buffer.
111
112  @return Buffer.
113
114**/
115VOID *
116EFIAPI
117SetMem32 (
118  OUT VOID   *Buffer,
119  IN UINTN   Length,
120  IN UINT32  Value
121  );
122
123/**
124  Fills a target buffer with a 64-bit value, and returns the target buffer.
125
126  This function fills Length bytes of Buffer with the 64-bit value specified by
127  Value, and returns Buffer. Value is repeated every 64-bits in for Length
128  bytes of Buffer.
129
130  If Length > 0 and Buffer is NULL, then ASSERT().
131  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
132  If Buffer is not aligned on a 64-bit boundary, then ASSERT().
133  If Length is not aligned on a 64-bit boundary, then ASSERT().
134
135  @param  Buffer  The pointer to the target buffer to fill.
136  @param  Length  The number of bytes in Buffer to fill.
137  @param  Value   The value with which to fill Length bytes of Buffer.
138
139  @return Buffer.
140
141**/
142VOID *
143EFIAPI
144SetMem64 (
145  OUT VOID   *Buffer,
146  IN UINTN   Length,
147  IN UINT64  Value
148  );
149
150/**
151  Fills a target buffer with a value that is size UINTN, and returns the target buffer.
152
153  This function fills Length bytes of Buffer with the UINTN sized value specified by
154  Value, and returns Buffer. Value is repeated every sizeof(UINTN) bytes for Length
155  bytes of Buffer.
156
157  If Length > 0 and Buffer is NULL, then ASSERT().
158  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
159  If Buffer is not aligned on a UINTN boundary, then ASSERT().
160  If Length is not aligned on a UINTN boundary, then ASSERT().
161
162  @param  Buffer  The pointer to the target buffer to fill.
163  @param  Length  The number of bytes in Buffer to fill.
164  @param  Value   The value with which to fill Length bytes of Buffer.
165
166  @return Buffer.
167
168**/
169VOID *
170EFIAPI
171SetMemN (
172  OUT VOID  *Buffer,
173  IN UINTN  Length,
174  IN UINTN  Value
175  );
176
177/**
178  Fills a target buffer with zeros, and returns the target buffer.
179
180  This function fills Length bytes of Buffer with zeros, and returns Buffer.
181
182  If Length > 0 and Buffer is NULL, then ASSERT().
183  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
184
185  @param  Buffer      The pointer to the target buffer to fill with zeros.
186  @param  Length      The number of bytes in Buffer to fill with zeros.
187
188  @return Buffer.
189
190**/
191VOID *
192EFIAPI
193ZeroMem (
194  OUT VOID  *Buffer,
195  IN UINTN  Length
196  );
197
198/**
199  Compares the contents of two buffers.
200
201  This function compares Length bytes of SourceBuffer to Length bytes of DestinationBuffer.
202  If all Length bytes of the two buffers are identical, then 0 is returned.  Otherwise, the
203  value returned is the first mismatched byte in SourceBuffer subtracted from the first
204  mismatched byte in DestinationBuffer.
205
206  If Length > 0 and DestinationBuffer is NULL, then ASSERT().
207  If Length > 0 and SourceBuffer is NULL, then ASSERT().
208  If Length is greater than (MAX_ADDRESS - DestinationBuffer + 1), then ASSERT().
209  If Length is greater than (MAX_ADDRESS - SourceBuffer + 1), then ASSERT().
210
211  @param  DestinationBuffer The pointer to the destination buffer to compare.
212  @param  SourceBuffer      The pointer to the source buffer to compare.
213  @param  Length            The number of bytes to compare.
214
215  @return 0                 All Length bytes of the two buffers are identical.
216  @retval Non-zero          The first mismatched byte in SourceBuffer subtracted from the first
217                            mismatched byte in DestinationBuffer.
218
219**/
220INTN
221EFIAPI
222CompareMem (
223  IN CONST VOID  *DestinationBuffer,
224  IN CONST VOID  *SourceBuffer,
225  IN UINTN       Length
226  );
227
228/**
229  Scans a target buffer for an 8-bit value, and returns a pointer to the matching 8-bit value
230  in the target buffer.
231
232  This function searches target the buffer specified by Buffer and Length from the lowest
233  address to the highest address for an 8-bit value that matches Value.  If a match is found,
234  then a pointer to the matching byte in the target buffer is returned.  If no match is found,
235  then NULL is returned.  If Length is 0, then NULL is returned.
236
237  If Length > 0 and Buffer is NULL, then ASSERT().
238  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
239
240  @param  Buffer      The pointer to the target buffer to scan.
241  @param  Length      The number of bytes in Buffer to scan.
242  @param  Value       The value to search for in the target buffer.
243
244  @return A pointer to the matching byte in the target buffer, otherwise NULL.
245
246**/
247VOID *
248EFIAPI
249ScanMem8 (
250  IN CONST VOID  *Buffer,
251  IN UINTN       Length,
252  IN UINT8       Value
253  );
254
255/**
256  Scans a target buffer for a 16-bit value, and returns a pointer to the matching 16-bit value
257  in the target buffer.
258
259  This function searches target the buffer specified by Buffer and Length from the lowest
260  address to the highest address for a 16-bit value that matches Value.  If a match is found,
261  then a pointer to the matching byte in the target buffer is returned.  If no match is found,
262  then NULL is returned.  If Length is 0, then NULL is returned.
263
264  If Length > 0 and Buffer is NULL, then ASSERT().
265  If Buffer is not aligned on a 16-bit boundary, then ASSERT().
266  If Length is not aligned on a 16-bit boundary, then ASSERT().
267  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
268
269  @param  Buffer      The pointer to the target buffer to scan.
270  @param  Length      The number of bytes in Buffer to scan.
271  @param  Value       The value to search for in the target buffer.
272
273  @return A pointer to the matching byte in the target buffer, otherwise NULL.
274
275**/
276VOID *
277EFIAPI
278ScanMem16 (
279  IN CONST VOID  *Buffer,
280  IN UINTN       Length,
281  IN UINT16      Value
282  );
283
284/**
285  Scans a target buffer for a 32-bit value, and returns a pointer to the matching 32-bit value
286  in the target buffer.
287
288  This function searches target the buffer specified by Buffer and Length from the lowest
289  address to the highest address for a 32-bit value that matches Value.  If a match is found,
290  then a pointer to the matching byte in the target buffer is returned.  If no match is found,
291  then NULL is returned.  If Length is 0, then NULL is returned.
292
293  If Length > 0 and Buffer is NULL, then ASSERT().
294  If Buffer is not aligned on a 32-bit boundary, then ASSERT().
295  If Length is not aligned on a 32-bit boundary, then ASSERT().
296  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
297
298  @param  Buffer      The pointer to the target buffer to scan.
299  @param  Length      The number of bytes in Buffer to scan.
300  @param  Value       The value to search for in the target buffer.
301
302  @return A pointer to the matching byte in the target buffer, otherwise NULL.
303
304**/
305VOID *
306EFIAPI
307ScanMem32 (
308  IN CONST VOID  *Buffer,
309  IN UINTN       Length,
310  IN UINT32      Value
311  );
312
313/**
314  Scans a target buffer for a 64-bit value, and returns a pointer to the matching 64-bit value
315  in the target buffer.
316
317  This function searches target the buffer specified by Buffer and Length from the lowest
318  address to the highest address for a 64-bit value that matches Value.  If a match is found,
319  then a pointer to the matching byte in the target buffer is returned.  If no match is found,
320  then NULL is returned.  If Length is 0, then NULL is returned.
321
322  If Length > 0 and Buffer is NULL, then ASSERT().
323  If Buffer is not aligned on a 64-bit boundary, then ASSERT().
324  If Length is not aligned on a 64-bit boundary, then ASSERT().
325  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
326
327  @param  Buffer      The pointer to the target buffer to scan.
328  @param  Length      The number of bytes in Buffer to scan.
329  @param  Value       The value to search for in the target buffer.
330
331  @return A pointer to the matching byte in the target buffer, otherwise NULL.
332
333**/
334VOID *
335EFIAPI
336ScanMem64 (
337  IN CONST VOID  *Buffer,
338  IN UINTN       Length,
339  IN UINT64      Value
340  );
341
342/**
343  Scans a target buffer for a UINTN sized value, and returns a pointer to the matching
344  UINTN sized value in the target buffer.
345
346  This function searches target the buffer specified by Buffer and Length from the lowest
347  address to the highest address for a UINTN sized value that matches Value.  If a match is found,
348  then a pointer to the matching byte in the target buffer is returned.  If no match is found,
349  then NULL is returned.  If Length is 0, then NULL is returned.
350
351  If Length > 0 and Buffer is NULL, then ASSERT().
352  If Buffer is not aligned on a UINTN boundary, then ASSERT().
353  If Length is not aligned on a UINTN boundary, then ASSERT().
354  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
355
356  @param  Buffer      The pointer to the target buffer to scan.
357  @param  Length      The number of bytes in Buffer to scan.
358  @param  Value       The value to search for in the target buffer.
359
360  @return A pointer to the matching byte in the target buffer, otherwise NULL.
361
362**/
363VOID *
364EFIAPI
365ScanMemN (
366  IN CONST VOID  *Buffer,
367  IN UINTN       Length,
368  IN UINTN       Value
369  );
370
371/**
372  Copies a source GUID to a destination GUID.
373
374  This function copies the contents of the 128-bit GUID specified by SourceGuid to
375  DestinationGuid, and returns DestinationGuid.
376
377  If DestinationGuid is NULL, then ASSERT().
378  If SourceGuid is NULL, then ASSERT().
379
380  @param  DestinationGuid   The pointer to the destination GUID.
381  @param  SourceGuid        The pointer to the source GUID.
382
383  @return DestinationGuid.
384
385**/
386GUID *
387EFIAPI
388CopyGuid (
389  OUT GUID       *DestinationGuid,
390  IN CONST GUID  *SourceGuid
391  );
392
393/**
394  Compares two GUIDs.
395
396  This function compares Guid1 to Guid2.  If the GUIDs are identical then TRUE is returned.
397  If there are any bit differences in the two GUIDs, then FALSE is returned.
398
399  If Guid1 is NULL, then ASSERT().
400  If Guid2 is NULL, then ASSERT().
401
402  @param  Guid1       A pointer to a 128 bit GUID.
403  @param  Guid2       A pointer to a 128 bit GUID.
404
405  @retval TRUE        Guid1 and Guid2 are identical.
406  @retval FALSE       Guid1 and Guid2 are not identical.
407
408**/
409BOOLEAN
410EFIAPI
411CompareGuid (
412  IN CONST GUID  *Guid1,
413  IN CONST GUID  *Guid2
414  );
415
416/**
417  Scans a target buffer for a GUID, and returns a pointer to the matching GUID
418  in the target buffer.
419
420  This function searches target the buffer specified by Buffer and Length from
421  the lowest address to the highest address at 128-bit increments for the 128-bit
422  GUID value that matches Guid.  If a match is found, then a pointer to the matching
423  GUID in the target buffer is returned.  If no match is found, then NULL is returned.
424  If Length is 0, then NULL is returned.
425
426  If Length > 0 and Buffer is NULL, then ASSERT().
427  If Buffer is not aligned on a 32-bit boundary, then ASSERT().
428  If Length is not aligned on a 128-bit boundary, then ASSERT().
429  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
430
431  @param  Buffer  The pointer to the target buffer to scan.
432  @param  Length  The number of bytes in Buffer to scan.
433  @param  Guid    The value to search for in the target buffer.
434
435  @return A pointer to the matching Guid in the target buffer, otherwise NULL.
436
437**/
438VOID *
439EFIAPI
440ScanGuid (
441  IN CONST VOID  *Buffer,
442  IN UINTN       Length,
443  IN CONST GUID  *Guid
444  );
445
446/**
447  Checks if the given GUID is a zero GUID.
448
449  This function checks whether the given GUID is a zero GUID. If the GUID is
450  identical to a zero GUID then TRUE is returned. Otherwise, FALSE is returned.
451
452  If Guid is NULL, then ASSERT().
453
454  @param  Guid        The pointer to a 128 bit GUID.
455
456  @retval TRUE        Guid is a zero GUID.
457  @retval FALSE       Guid is not a zero GUID.
458
459**/
460BOOLEAN
461EFIAPI
462IsZeroGuid (
463  IN CONST GUID  *Guid
464  );
465
466/**
467  Checks if the contents of a buffer are all zeros.
468
469  This function checks whether the contents of a buffer are all zeros. If the
470  contents are all zeros, return TRUE. Otherwise, return FALSE.
471
472  If Length > 0 and Buffer is NULL, then ASSERT().
473  If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
474
475  @param  Buffer      The pointer to the buffer to be checked.
476  @param  Length      The size of the buffer (in bytes) to be checked.
477
478  @retval TRUE        Contents of the buffer are all zeros.
479  @retval FALSE       Contents of the buffer are not all zeros.
480
481**/
482BOOLEAN
483EFIAPI
484IsZeroBuffer (
485  IN CONST VOID  *Buffer,
486  IN UINTN       Length
487  );
488
489#endif
490