VirtualBox

source: vbox/trunk/src/VBox/Runtime/r0drv/memobj-r0drv.cpp@ 92246

Last change on this file since 92246 was 92246, checked in by vboxsync, 3 years ago

IPRT/RTR0MemObj: Added RTR0MemObjWasZeroInitialized and a couple of flags with which the backend can feed it the necessary info. It would be good to try avoid zeroing memory twice when we can. bugref:10093

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Rev Revision
File size: 33.8 KB
Line 
1/* $Id: memobj-r0drv.cpp 92246 2021-11-06 03:10:49Z vboxsync $ */
2/** @file
3 * IPRT - Ring-0 Memory Objects, Common Code.
4 */
5
6/*
7 * Copyright (C) 2006-2020 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27
28/*********************************************************************************************************************************
29* Header Files *
30*********************************************************************************************************************************/
31#define LOG_GROUP RTLOGGROUP_DEFAULT /// @todo RTLOGGROUP_MEM
32#define RTMEM_NO_WRAP_TO_EF_APIS /* circular dependency otherwise. */
33#include <iprt/memobj.h>
34#include "internal/iprt.h"
35
36#include <iprt/alloc.h>
37#include <iprt/asm.h>
38#include <iprt/assert.h>
39#include <iprt/err.h>
40#include <iprt/log.h>
41#include <iprt/mp.h>
42#include <iprt/param.h>
43#include <iprt/process.h>
44#include <iprt/thread.h>
45
46#include "internal/memobj.h"
47
48
49/**
50 * Internal function for allocating a new memory object.
51 *
52 * @returns The allocated and initialized handle.
53 * @param cbSelf The size of the memory object handle. 0 mean default size.
54 * @param enmType The memory object type.
55 * @param pv The memory object mapping.
56 * @param cb The size of the memory object.
57 * @param pszTag The tag string.
58 */
59DECLHIDDEN(PRTR0MEMOBJINTERNAL) rtR0MemObjNew(size_t cbSelf, RTR0MEMOBJTYPE enmType, void *pv, size_t cb, const char *pszTag)
60{
61 PRTR0MEMOBJINTERNAL pNew;
62
63 /* validate the size */
64 if (!cbSelf)
65 cbSelf = sizeof(*pNew);
66 Assert(cbSelf >= sizeof(*pNew));
67 Assert(cbSelf == (uint32_t)cbSelf);
68 AssertMsg(RT_ALIGN_Z(cb, PAGE_SIZE) == cb, ("%#zx\n", cb));
69
70 /*
71 * Allocate and initialize the object.
72 */
73 pNew = (PRTR0MEMOBJINTERNAL)RTMemAllocZ(cbSelf);
74 if (pNew)
75 {
76 pNew->u32Magic = RTR0MEMOBJ_MAGIC;
77 pNew->cbSelf = (uint32_t)cbSelf;
78 pNew->enmType = enmType;
79 pNew->fFlags = 0;
80 pNew->cb = cb;
81 pNew->pv = pv;
82#ifdef DEBUG
83 pNew->pszTag = pszTag;
84#else
85 RT_NOREF_PV(pszTag);
86#endif
87 }
88 return pNew;
89}
90
91
92/**
93 * Deletes an incomplete memory object.
94 *
95 * This is for cleaning up after failures during object creation.
96 *
97 * @param pMem The incomplete memory object to delete.
98 */
99DECLHIDDEN(void) rtR0MemObjDelete(PRTR0MEMOBJINTERNAL pMem)
100{
101 if (pMem)
102 {
103 ASMAtomicUoWriteU32(&pMem->u32Magic, ~RTR0MEMOBJ_MAGIC);
104 pMem->enmType = RTR0MEMOBJTYPE_END;
105 RTMemFree(pMem);
106 }
107}
108
109
110/**
111 * Links a mapping object to a primary object.
112 *
113 * @returns IPRT status code.
114 * @retval VINF_SUCCESS on success.
115 * @retval VINF_NO_MEMORY if we couldn't expand the mapping array of the parent.
116 * @param pParent The parent (primary) memory object.
117 * @param pChild The child (mapping) memory object.
118 */
119static int rtR0MemObjLink(PRTR0MEMOBJINTERNAL pParent, PRTR0MEMOBJINTERNAL pChild)
120{
121 uint32_t i;
122
123 /* sanity */
124 Assert(rtR0MemObjIsMapping(pChild));
125 Assert(!rtR0MemObjIsMapping(pParent));
126
127 /* expand the array? */
128 i = pParent->uRel.Parent.cMappings;
129 if (i >= pParent->uRel.Parent.cMappingsAllocated)
130 {
131 void *pv = RTMemRealloc(pParent->uRel.Parent.papMappings,
132 (i + 32) * sizeof(pParent->uRel.Parent.papMappings[0]));
133 if (!pv)
134 return VERR_NO_MEMORY;
135 pParent->uRel.Parent.papMappings = (PPRTR0MEMOBJINTERNAL)pv;
136 pParent->uRel.Parent.cMappingsAllocated = i + 32;
137 Assert(i == pParent->uRel.Parent.cMappings);
138 }
139
140 /* do the linking. */
141 pParent->uRel.Parent.papMappings[i] = pChild;
142 pParent->uRel.Parent.cMappings++;
143 pChild->uRel.Child.pParent = pParent;
144
145 return VINF_SUCCESS;
146}
147
148
149/**
150 * Checks if this is mapping or not.
151 *
152 * @returns true if it's a mapping, otherwise false.
153 * @param MemObj The ring-0 memory object handle.
154 */
155RTR0DECL(bool) RTR0MemObjIsMapping(RTR0MEMOBJ MemObj)
156{
157 /* Validate the object handle. */
158 PRTR0MEMOBJINTERNAL pMem;
159 AssertPtrReturn(MemObj, false);
160 pMem = (PRTR0MEMOBJINTERNAL)MemObj;
161 AssertMsgReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, ("%p: %#x\n", pMem, pMem->u32Magic), false);
162 AssertMsgReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, ("%p: %d\n", pMem, pMem->enmType), false);
163
164 /* hand it on to the inlined worker. */
165 return rtR0MemObjIsMapping(pMem);
166}
167RT_EXPORT_SYMBOL(RTR0MemObjIsMapping);
168
169
170/**
171 * Gets the address of a ring-0 memory object.
172 *
173 * @returns The address of the memory object.
174 * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
175 * @param MemObj The ring-0 memory object handle.
176 */
177RTR0DECL(void *) RTR0MemObjAddress(RTR0MEMOBJ MemObj)
178{
179 /* Validate the object handle. */
180 PRTR0MEMOBJINTERNAL pMem;
181 if (RT_UNLIKELY(MemObj == NIL_RTR0MEMOBJ))
182 return NULL;
183 AssertPtrReturn(MemObj, NULL);
184 pMem = (PRTR0MEMOBJINTERNAL)MemObj;
185 AssertMsgReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, ("%p: %#x\n", pMem, pMem->u32Magic), NULL);
186 AssertMsgReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, ("%p: %d\n", pMem, pMem->enmType), NULL);
187
188 /* return the mapping address. */
189 return pMem->pv;
190}
191RT_EXPORT_SYMBOL(RTR0MemObjAddress);
192
193
194/**
195 * Gets the ring-3 address of a ring-0 memory object.
196 *
197 * This only applies to ring-0 memory object with ring-3 mappings of some kind, i.e.
198 * locked user memory, reserved user address space and user mappings. This API should
199 * not be used on any other objects.
200 *
201 * @returns The address of the memory object.
202 * @returns NIL_RTR3PTR if the handle is invalid or if it's not an object with a ring-3 mapping.
203 * Strict builds will assert in both cases.
204 * @param MemObj The ring-0 memory object handle.
205 */
206RTR0DECL(RTR3PTR) RTR0MemObjAddressR3(RTR0MEMOBJ MemObj)
207{
208 PRTR0MEMOBJINTERNAL pMem;
209
210 /* Validate the object handle. */
211 if (RT_UNLIKELY(MemObj == NIL_RTR0MEMOBJ))
212 return NIL_RTR3PTR;
213 AssertPtrReturn(MemObj, NIL_RTR3PTR);
214 pMem = (PRTR0MEMOBJINTERNAL)MemObj;
215 AssertMsgReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, ("%p: %#x\n", pMem, pMem->u32Magic), NIL_RTR3PTR);
216 AssertMsgReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, ("%p: %d\n", pMem, pMem->enmType), NIL_RTR3PTR);
217 if (RT_UNLIKELY( ( pMem->enmType != RTR0MEMOBJTYPE_MAPPING
218 || pMem->u.Mapping.R0Process == NIL_RTR0PROCESS)
219 && ( pMem->enmType != RTR0MEMOBJTYPE_LOCK
220 || pMem->u.Lock.R0Process == NIL_RTR0PROCESS)
221 && ( pMem->enmType != RTR0MEMOBJTYPE_PHYS_NC
222 || pMem->u.Lock.R0Process == NIL_RTR0PROCESS)
223 && ( pMem->enmType != RTR0MEMOBJTYPE_RES_VIRT
224 || pMem->u.ResVirt.R0Process == NIL_RTR0PROCESS)))
225 return NIL_RTR3PTR;
226
227 /* return the mapping address. */
228 return (RTR3PTR)pMem->pv;
229}
230RT_EXPORT_SYMBOL(RTR0MemObjAddressR3);
231
232
233/**
234 * Gets the size of a ring-0 memory object.
235 *
236 * The returned value may differ from the one specified to the API creating the
237 * object because of alignment adjustments. The minimal alignment currently
238 * employed by any API is PAGE_SIZE, so the result can safely be shifted by
239 * PAGE_SHIFT to calculate a page count.
240 *
241 * @returns The object size.
242 * @returns 0 if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
243 * @param MemObj The ring-0 memory object handle.
244 */
245RTR0DECL(size_t) RTR0MemObjSize(RTR0MEMOBJ MemObj)
246{
247 PRTR0MEMOBJINTERNAL pMem;
248
249 /* Validate the object handle. */
250 if (RT_UNLIKELY(MemObj == NIL_RTR0MEMOBJ))
251 return 0;
252 AssertPtrReturn(MemObj, 0);
253 pMem = (PRTR0MEMOBJINTERNAL)MemObj;
254 AssertMsgReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, ("%p: %#x\n", pMem, pMem->u32Magic), 0);
255 AssertMsgReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, ("%p: %d\n", pMem, pMem->enmType), 0);
256 AssertMsg(RT_ALIGN_Z(pMem->cb, PAGE_SIZE) == pMem->cb, ("%#zx\n", pMem->cb));
257
258 /* return the size. */
259 return pMem->cb;
260}
261RT_EXPORT_SYMBOL(RTR0MemObjSize);
262
263
264/**
265 * Get the physical address of an page in the memory object.
266 *
267 * @returns The physical address.
268 * @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
269 * @returns NIL_RTHCPHYS if the iPage is out of range.
270 * @returns NIL_RTHCPHYS if the object handle isn't valid.
271 * @param MemObj The ring-0 memory object handle.
272 * @param iPage The page number within the object.
273 */
274/* Work around gcc bug 55940 */
275#if defined(__GNUC__) && defined(RT_ARCH_X86) && (__GNUC__ * 100 + __GNUC_MINOR__) == 407
276 __attribute__((__optimize__ ("no-shrink-wrap")))
277#endif
278RTR0DECL(RTHCPHYS) RTR0MemObjGetPagePhysAddr(RTR0MEMOBJ MemObj, size_t iPage)
279{
280 /* Validate the object handle. */
281 PRTR0MEMOBJINTERNAL pMem;
282 size_t cPages;
283 AssertPtrReturn(MemObj, NIL_RTHCPHYS);
284 pMem = (PRTR0MEMOBJINTERNAL)MemObj;
285 AssertReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, NIL_RTHCPHYS);
286 AssertReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, NIL_RTHCPHYS);
287 AssertMsgReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, ("%p: %#x\n", pMem, pMem->u32Magic), NIL_RTHCPHYS);
288 AssertMsgReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, ("%p: %d\n", pMem, pMem->enmType), NIL_RTHCPHYS);
289 cPages = (pMem->cb >> PAGE_SHIFT);
290 if (iPage >= cPages)
291 {
292 /* permit: while (RTR0MemObjGetPagePhysAddr(pMem, iPage++) != NIL_RTHCPHYS) {} */
293 if (iPage == cPages)
294 return NIL_RTHCPHYS;
295 AssertReturn(iPage < (pMem->cb >> PAGE_SHIFT), NIL_RTHCPHYS);
296 }
297
298 /*
299 * We know the address of physically contiguous allocations and mappings.
300 */
301 if (pMem->enmType == RTR0MEMOBJTYPE_CONT)
302 return pMem->u.Cont.Phys + iPage * PAGE_SIZE;
303 if (pMem->enmType == RTR0MEMOBJTYPE_PHYS)
304 return pMem->u.Phys.PhysBase + iPage * PAGE_SIZE;
305
306 /*
307 * Do the job.
308 */
309 return rtR0MemObjNativeGetPagePhysAddr(pMem, iPage);
310}
311RT_EXPORT_SYMBOL(RTR0MemObjGetPagePhysAddr);
312
313
314/**
315 * Checks whether the allocation was zero initialized or not.
316 *
317 * This only works on allocations. It is not meaningful for mappings, reserved
318 * memory and entered physical address, and will return false for these.
319 *
320 * @returns true if the allocation was initialized to zero at allocation time,
321 * false if not or query not meaningful to the object type.
322 * @param hMemObj The ring-0 memory object to be freed.
323 *
324 * @remarks It can be expected that memory allocated in the same fashion will
325 * have the same initialization state. So, if this returns true for
326 * one allocation it will return true for all other similarly made
327 * allocations.
328 */
329RTR0DECL(bool) RTR0MemObjWasZeroInitialized(PRTR0MEMOBJ hMemObj)
330{
331 PRTR0MEMOBJINTERNAL pMem;
332
333 /* Validate the object handle. */
334 if (RT_UNLIKELY(hMemObj == NIL_RTR0MEMOBJ))
335 return false;
336 AssertPtrReturn(hMemObj, false);
337 pMem = (PRTR0MEMOBJINTERNAL)hMemObj;
338 AssertMsgReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, ("%p: %#x\n", pMem, pMem->u32Magic), false);
339 AssertMsgReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, ("%p: %d\n", pMem, pMem->enmType), false);
340 Assert( (pMem->fFlags & (RTR0MEMOBJ_FLAGS_ZERO_AT_ALLOC | RTR0MEMOBJ_FLAGS_UNINITIALIZED_AT_ALLOC))
341 != (RTR0MEMOBJ_FLAGS_ZERO_AT_ALLOC | RTR0MEMOBJ_FLAGS_UNINITIALIZED_AT_ALLOC));
342
343 /* return the alloc init state. */
344 return (pMem->fFlags & (RTR0MEMOBJ_FLAGS_ZERO_AT_ALLOC | RTR0MEMOBJ_FLAGS_UNINITIALIZED_AT_ALLOC))
345 == RTR0MEMOBJ_FLAGS_ZERO_AT_ALLOC;
346
347}
348RT_EXPORT_SYMBOL(RTR0MemObjWasZeroInitialized);
349
350
351/**
352 * Frees a ring-0 memory object.
353 *
354 * @returns IPRT status code.
355 * @retval VERR_INVALID_HANDLE if
356 * @param MemObj The ring-0 memory object to be freed. NIL is
357 * accepted.
358 * @param fFreeMappings Whether or not to free mappings of the object.
359 */
360RTR0DECL(int) RTR0MemObjFree(RTR0MEMOBJ MemObj, bool fFreeMappings)
361{
362 /*
363 * Validate the object handle.
364 */
365 PRTR0MEMOBJINTERNAL pMem;
366 int rc;
367
368 if (MemObj == NIL_RTR0MEMOBJ)
369 return VINF_SUCCESS;
370 AssertPtrReturn(MemObj, VERR_INVALID_HANDLE);
371 pMem = (PRTR0MEMOBJINTERNAL)MemObj;
372 AssertReturn(pMem->u32Magic == RTR0MEMOBJ_MAGIC, VERR_INVALID_HANDLE);
373 AssertReturn(pMem->enmType > RTR0MEMOBJTYPE_INVALID && pMem->enmType < RTR0MEMOBJTYPE_END, VERR_INVALID_HANDLE);
374 RT_ASSERT_PREEMPTIBLE();
375
376 /*
377 * Deal with mappings according to fFreeMappings.
378 */
379 if ( !rtR0MemObjIsMapping(pMem)
380 && pMem->uRel.Parent.cMappings > 0)
381 {
382 /* fail if not requested to free mappings. */
383 if (!fFreeMappings)
384 return VERR_MEMORY_BUSY;
385
386 while (pMem->uRel.Parent.cMappings > 0)
387 {
388 PRTR0MEMOBJINTERNAL pChild = pMem->uRel.Parent.papMappings[--pMem->uRel.Parent.cMappings];
389 pMem->uRel.Parent.papMappings[pMem->uRel.Parent.cMappings] = NULL;
390
391 /* sanity checks. */
392 AssertPtr(pChild);
393 AssertFatal(pChild->u32Magic == RTR0MEMOBJ_MAGIC);
394 AssertFatal(pChild->enmType > RTR0MEMOBJTYPE_INVALID && pChild->enmType < RTR0MEMOBJTYPE_END);
395 AssertFatal(rtR0MemObjIsMapping(pChild));
396
397 /* free the mapping. */
398 rc = rtR0MemObjNativeFree(pChild);
399 if (RT_FAILURE(rc))
400 {
401 Log(("RTR0MemObjFree: failed to free mapping %p: %p %#zx; rc=%Rrc\n", pChild, pChild->pv, pChild->cb, rc));
402 pMem->uRel.Parent.papMappings[pMem->uRel.Parent.cMappings++] = pChild;
403 return rc;
404 }
405
406 pChild->u32Magic++;
407 pChild->enmType = RTR0MEMOBJTYPE_END;
408 RTMemFree(pChild);
409 }
410 }
411
412 /*
413 * Free this object.
414 */
415 rc = rtR0MemObjNativeFree(pMem);
416 if (RT_SUCCESS(rc))
417 {
418 /*
419 * Ok, it was freed just fine. Now, if it's a mapping we'll have to remove it from the parent.
420 */
421 if (rtR0MemObjIsMapping(pMem))
422 {
423 PRTR0MEMOBJINTERNAL pParent = pMem->uRel.Child.pParent;
424 uint32_t i;
425
426 /* sanity checks */
427 AssertPtr(pParent);
428 AssertFatal(pParent->u32Magic == RTR0MEMOBJ_MAGIC);
429 AssertFatal(pParent->enmType > RTR0MEMOBJTYPE_INVALID && pParent->enmType < RTR0MEMOBJTYPE_END);
430 AssertFatal(!rtR0MemObjIsMapping(pParent));
431 AssertFatal(pParent->uRel.Parent.cMappings > 0);
432 AssertPtr(pParent->uRel.Parent.papMappings);
433
434 /* locate and remove from the array of mappings. */
435 i = pParent->uRel.Parent.cMappings;
436 while (i-- > 0)
437 {
438 if (pParent->uRel.Parent.papMappings[i] == pMem)
439 {
440 pParent->uRel.Parent.papMappings[i] = pParent->uRel.Parent.papMappings[--pParent->uRel.Parent.cMappings];
441 break;
442 }
443 }
444 Assert(i != UINT32_MAX);
445 }
446 else
447 Assert(pMem->uRel.Parent.cMappings == 0);
448
449 /*
450 * Finally, destroy the handle.
451 */
452 pMem->u32Magic++;
453 pMem->enmType = RTR0MEMOBJTYPE_END;
454 if (!rtR0MemObjIsMapping(pMem))
455 RTMemFree(pMem->uRel.Parent.papMappings);
456 RTMemFree(pMem);
457 }
458 else
459 Log(("RTR0MemObjFree: failed to free %p: %d %p %#zx; rc=%Rrc\n",
460 pMem, pMem->enmType, pMem->pv, pMem->cb, rc));
461 return rc;
462}
463RT_EXPORT_SYMBOL(RTR0MemObjFree);
464
465
466
467RTR0DECL(int) RTR0MemObjAllocPageTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag)
468{
469 /* sanity checks. */
470 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
471 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
472 *pMemObj = NIL_RTR0MEMOBJ;
473 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
474 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
475 RT_ASSERT_PREEMPTIBLE();
476
477 /* do the allocation. */
478 return rtR0MemObjNativeAllocPage(pMemObj, cbAligned, fExecutable, pszTag);
479}
480RT_EXPORT_SYMBOL(RTR0MemObjAllocPageTag);
481
482
483RTR0DECL(int) RTR0MemObjAllocLargeTag(PRTR0MEMOBJ pMemObj, size_t cb, size_t cbLargePage, uint32_t fFlags, const char *pszTag)
484{
485 /* sanity checks. */
486 const size_t cbAligned = RT_ALIGN_Z(cb, cbLargePage);
487 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
488 *pMemObj = NIL_RTR0MEMOBJ;
489#ifdef RT_ARCH_AMD64
490 AssertReturn(cbLargePage == _2M || cbLargePage == _1G, VERR_OUT_OF_RANGE);
491#elif defined(RT_ARCH_X86)
492 AssertReturn(cbLargePage == _2M || cbLargePage == _4M, VERR_OUT_OF_RANGE);
493#else
494 AssertReturn(RT_IS_POWER_OF_TWO(cbLargePage), VERR_NOT_POWER_OF_TWO);
495 AssertReturn(cbLargePage > PAGE_SIZE, VERR_OUT_OF_RANGE);
496#endif
497 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
498 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
499 AssertReturn(!(fFlags & ~RTMEMOBJ_ALLOC_LARGE_F_VALID_MASK), VERR_INVALID_PARAMETER);
500 RT_ASSERT_PREEMPTIBLE();
501
502 /* do the allocation. */
503 return rtR0MemObjNativeAllocLarge(pMemObj, cbAligned, cbLargePage, fFlags, pszTag);
504}
505RT_EXPORT_SYMBOL(RTR0MemObjAllocLargeTag);
506
507
508/**
509 * Fallback implementation of rtR0MemObjNativeAllocLarge and implements single
510 * page allocation using rtR0MemObjNativeAllocPhys.
511 */
512DECLHIDDEN(int) rtR0MemObjFallbackAllocLarge(PPRTR0MEMOBJINTERNAL ppMem, size_t cb, size_t cbLargePage, uint32_t fFlags,
513 const char *pszTag)
514{
515 RT_NOREF(pszTag, fFlags);
516 if (cb == cbLargePage)
517 return rtR0MemObjNativeAllocPhys(ppMem, cb, NIL_RTHCPHYS, cbLargePage, pszTag);
518 return VERR_NOT_SUPPORTED;
519}
520
521
522RTR0DECL(int) RTR0MemObjAllocLowTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag)
523{
524 /* sanity checks. */
525 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
526 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
527 *pMemObj = NIL_RTR0MEMOBJ;
528 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
529 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
530 RT_ASSERT_PREEMPTIBLE();
531
532 /* do the allocation. */
533 return rtR0MemObjNativeAllocLow(pMemObj, cbAligned, fExecutable, pszTag);
534}
535RT_EXPORT_SYMBOL(RTR0MemObjAllocLowTag);
536
537
538RTR0DECL(int) RTR0MemObjAllocContTag(PRTR0MEMOBJ pMemObj, size_t cb, bool fExecutable, const char *pszTag)
539{
540 /* sanity checks. */
541 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
542 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
543 *pMemObj = NIL_RTR0MEMOBJ;
544 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
545 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
546 RT_ASSERT_PREEMPTIBLE();
547
548 /* do the allocation. */
549 return rtR0MemObjNativeAllocCont(pMemObj, cbAligned, fExecutable, pszTag);
550}
551RT_EXPORT_SYMBOL(RTR0MemObjAllocContTag);
552
553
554RTR0DECL(int) RTR0MemObjLockUserTag(PRTR0MEMOBJ pMemObj, RTR3PTR R3Ptr, size_t cb,
555 uint32_t fAccess, RTR0PROCESS R0Process, const char *pszTag)
556{
557 /* sanity checks. */
558 const size_t cbAligned = RT_ALIGN_Z(cb + (R3Ptr & PAGE_OFFSET_MASK), PAGE_SIZE);
559 RTR3PTR const R3PtrAligned = (R3Ptr & ~(RTR3PTR)PAGE_OFFSET_MASK);
560 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
561 *pMemObj = NIL_RTR0MEMOBJ;
562 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
563 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
564 if (R0Process == NIL_RTR0PROCESS)
565 R0Process = RTR0ProcHandleSelf();
566 AssertReturn(!(fAccess & ~(RTMEM_PROT_READ | RTMEM_PROT_WRITE)), VERR_INVALID_PARAMETER);
567 AssertReturn(fAccess, VERR_INVALID_PARAMETER);
568 RT_ASSERT_PREEMPTIBLE();
569
570 /* do the locking. */
571 return rtR0MemObjNativeLockUser(pMemObj, R3PtrAligned, cbAligned, fAccess, R0Process, pszTag);
572}
573RT_EXPORT_SYMBOL(RTR0MemObjLockUserTag);
574
575
576RTR0DECL(int) RTR0MemObjLockKernelTag(PRTR0MEMOBJ pMemObj, void *pv, size_t cb, uint32_t fAccess, const char *pszTag)
577{
578 /* sanity checks. */
579 const size_t cbAligned = RT_ALIGN_Z(cb + ((uintptr_t)pv & PAGE_OFFSET_MASK), PAGE_SIZE);
580 void * const pvAligned = (void *)((uintptr_t)pv & ~(uintptr_t)PAGE_OFFSET_MASK);
581 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
582 *pMemObj = NIL_RTR0MEMOBJ;
583 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
584 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
585 AssertPtrReturn(pvAligned, VERR_INVALID_POINTER);
586 AssertReturn(!(fAccess & ~(RTMEM_PROT_READ | RTMEM_PROT_WRITE)), VERR_INVALID_PARAMETER);
587 AssertReturn(fAccess, VERR_INVALID_PARAMETER);
588 RT_ASSERT_PREEMPTIBLE();
589
590 /* do the allocation. */
591 return rtR0MemObjNativeLockKernel(pMemObj, pvAligned, cbAligned, fAccess, pszTag);
592}
593RT_EXPORT_SYMBOL(RTR0MemObjLockKernelTag);
594
595
596RTR0DECL(int) RTR0MemObjAllocPhysTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, const char *pszTag)
597{
598 /* sanity checks. */
599 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
600 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
601 *pMemObj = NIL_RTR0MEMOBJ;
602 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
603 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
604 AssertReturn(PhysHighest >= cb, VERR_INVALID_PARAMETER);
605 RT_ASSERT_PREEMPTIBLE();
606
607 /* do the allocation. */
608 return rtR0MemObjNativeAllocPhys(pMemObj, cbAligned, PhysHighest, PAGE_SIZE /* page aligned */, pszTag);
609}
610RT_EXPORT_SYMBOL(RTR0MemObjAllocPhysTag);
611
612
613RTR0DECL(int) RTR0MemObjAllocPhysExTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, size_t uAlignment, const char *pszTag)
614{
615 /* sanity checks. */
616 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
617 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
618 *pMemObj = NIL_RTR0MEMOBJ;
619 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
620 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
621 AssertReturn(PhysHighest >= cb, VERR_INVALID_PARAMETER);
622 if (uAlignment == 0)
623 uAlignment = PAGE_SIZE;
624 AssertReturn( uAlignment == PAGE_SIZE
625 || uAlignment == _2M
626 || uAlignment == _4M
627 || uAlignment == _1G,
628 VERR_INVALID_PARAMETER);
629#if HC_ARCH_BITS == 32
630 /* Memory allocated in this way is typically mapped into kernel space as well; simply
631 don't allow this on 32 bits hosts as the kernel space is too crowded already. */
632 if (uAlignment != PAGE_SIZE)
633 return VERR_NOT_SUPPORTED;
634#endif
635 RT_ASSERT_PREEMPTIBLE();
636
637 /* do the allocation. */
638 return rtR0MemObjNativeAllocPhys(pMemObj, cbAligned, PhysHighest, uAlignment, pszTag);
639}
640RT_EXPORT_SYMBOL(RTR0MemObjAllocPhysExTag);
641
642
643RTR0DECL(int) RTR0MemObjAllocPhysNCTag(PRTR0MEMOBJ pMemObj, size_t cb, RTHCPHYS PhysHighest, const char *pszTag)
644{
645 /* sanity checks. */
646 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
647 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
648 *pMemObj = NIL_RTR0MEMOBJ;
649 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
650 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
651 AssertReturn(PhysHighest >= cb, VERR_INVALID_PARAMETER);
652 RT_ASSERT_PREEMPTIBLE();
653
654 /* do the allocation. */
655 return rtR0MemObjNativeAllocPhysNC(pMemObj, cbAligned, PhysHighest, pszTag);
656}
657RT_EXPORT_SYMBOL(RTR0MemObjAllocPhysNCTag);
658
659
660RTR0DECL(int) RTR0MemObjEnterPhysTag(PRTR0MEMOBJ pMemObj, RTHCPHYS Phys, size_t cb, uint32_t uCachePolicy, const char *pszTag)
661{
662 /* sanity checks. */
663 const size_t cbAligned = RT_ALIGN_Z(cb + (Phys & PAGE_OFFSET_MASK), PAGE_SIZE);
664 const RTHCPHYS PhysAligned = Phys & ~(RTHCPHYS)PAGE_OFFSET_MASK;
665 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
666 *pMemObj = NIL_RTR0MEMOBJ;
667 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
668 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
669 AssertReturn(Phys != NIL_RTHCPHYS, VERR_INVALID_PARAMETER);
670 AssertReturn( uCachePolicy == RTMEM_CACHE_POLICY_DONT_CARE
671 || uCachePolicy == RTMEM_CACHE_POLICY_MMIO,
672 VERR_INVALID_PARAMETER);
673 RT_ASSERT_PREEMPTIBLE();
674
675 /* do the allocation. */
676 return rtR0MemObjNativeEnterPhys(pMemObj, PhysAligned, cbAligned, uCachePolicy, pszTag);
677}
678RT_EXPORT_SYMBOL(RTR0MemObjEnterPhysTag);
679
680
681RTR0DECL(int) RTR0MemObjReserveKernelTag(PRTR0MEMOBJ pMemObj, void *pvFixed, size_t cb, size_t uAlignment, const char *pszTag)
682{
683 /* sanity checks. */
684 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
685 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
686 *pMemObj = NIL_RTR0MEMOBJ;
687 if (uAlignment == 0)
688 uAlignment = PAGE_SIZE;
689 AssertReturn(uAlignment == PAGE_SIZE || uAlignment == _2M || uAlignment == _4M, VERR_INVALID_PARAMETER);
690 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
691 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
692 if (pvFixed != (void *)-1)
693 AssertReturn(!((uintptr_t)pvFixed & (uAlignment - 1)), VERR_INVALID_PARAMETER);
694 RT_ASSERT_PREEMPTIBLE();
695
696 /* do the reservation. */
697 return rtR0MemObjNativeReserveKernel(pMemObj, pvFixed, cbAligned, uAlignment, pszTag);
698}
699RT_EXPORT_SYMBOL(RTR0MemObjReserveKernelTag);
700
701
702RTR0DECL(int) RTR0MemObjReserveUserTag(PRTR0MEMOBJ pMemObj, RTR3PTR R3PtrFixed, size_t cb,
703 size_t uAlignment, RTR0PROCESS R0Process, const char *pszTag)
704{
705 /* sanity checks. */
706 const size_t cbAligned = RT_ALIGN_Z(cb, PAGE_SIZE);
707 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
708 *pMemObj = NIL_RTR0MEMOBJ;
709 if (uAlignment == 0)
710 uAlignment = PAGE_SIZE;
711 AssertReturn(uAlignment == PAGE_SIZE || uAlignment == _2M || uAlignment == _4M, VERR_INVALID_PARAMETER);
712 AssertReturn(cb > 0, VERR_INVALID_PARAMETER);
713 AssertReturn(cb <= cbAligned, VERR_INVALID_PARAMETER);
714 if (R3PtrFixed != (RTR3PTR)-1)
715 AssertReturn(!(R3PtrFixed & (uAlignment - 1)), VERR_INVALID_PARAMETER);
716 if (R0Process == NIL_RTR0PROCESS)
717 R0Process = RTR0ProcHandleSelf();
718 RT_ASSERT_PREEMPTIBLE();
719
720 /* do the reservation. */
721 return rtR0MemObjNativeReserveUser(pMemObj, R3PtrFixed, cbAligned, uAlignment, R0Process, pszTag);
722}
723RT_EXPORT_SYMBOL(RTR0MemObjReserveUserTag);
724
725
726RTR0DECL(int) RTR0MemObjMapKernelTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed,
727 size_t uAlignment, unsigned fProt, const char *pszTag)
728{
729 return RTR0MemObjMapKernelExTag(pMemObj, MemObjToMap, pvFixed, uAlignment, fProt, 0, 0, pszTag);
730}
731RT_EXPORT_SYMBOL(RTR0MemObjMapKernelTag);
732
733
734RTR0DECL(int) RTR0MemObjMapKernelExTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, void *pvFixed, size_t uAlignment,
735 unsigned fProt, size_t offSub, size_t cbSub, const char *pszTag)
736{
737 PRTR0MEMOBJINTERNAL pMemToMap;
738 PRTR0MEMOBJINTERNAL pNew;
739 int rc;
740
741 /* sanity checks. */
742 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
743 *pMemObj = NIL_RTR0MEMOBJ;
744 AssertPtrReturn(MemObjToMap, VERR_INVALID_HANDLE);
745 pMemToMap = (PRTR0MEMOBJINTERNAL)MemObjToMap;
746 AssertReturn(pMemToMap->u32Magic == RTR0MEMOBJ_MAGIC, VERR_INVALID_HANDLE);
747 AssertReturn(pMemToMap->enmType > RTR0MEMOBJTYPE_INVALID && pMemToMap->enmType < RTR0MEMOBJTYPE_END, VERR_INVALID_HANDLE);
748 AssertReturn(!rtR0MemObjIsMapping(pMemToMap), VERR_INVALID_PARAMETER);
749 AssertReturn(pMemToMap->enmType != RTR0MEMOBJTYPE_RES_VIRT, VERR_INVALID_PARAMETER);
750 if (uAlignment == 0)
751 uAlignment = PAGE_SIZE;
752 AssertReturn(uAlignment == PAGE_SIZE || uAlignment == _2M || uAlignment == _4M, VERR_INVALID_PARAMETER);
753 if (pvFixed != (void *)-1)
754 AssertReturn(!((uintptr_t)pvFixed & (uAlignment - 1)), VERR_INVALID_PARAMETER);
755 AssertReturn(fProt != RTMEM_PROT_NONE, VERR_INVALID_PARAMETER);
756 AssertReturn(!(fProt & ~(RTMEM_PROT_READ | RTMEM_PROT_WRITE | RTMEM_PROT_EXEC)), VERR_INVALID_PARAMETER);
757 AssertReturn(!(offSub & PAGE_OFFSET_MASK), VERR_INVALID_PARAMETER);
758 AssertReturn(offSub < pMemToMap->cb, VERR_INVALID_PARAMETER);
759 AssertReturn(!(cbSub & PAGE_OFFSET_MASK), VERR_INVALID_PARAMETER);
760 AssertReturn(cbSub <= pMemToMap->cb, VERR_INVALID_PARAMETER);
761 AssertReturn((!offSub && !cbSub) || (offSub + cbSub) <= pMemToMap->cb, VERR_INVALID_PARAMETER);
762 RT_ASSERT_PREEMPTIBLE();
763
764 /* adjust the request to simplify the native code. */
765 if (offSub == 0 && cbSub == pMemToMap->cb)
766 cbSub = 0;
767
768 /* do the mapping. */
769 rc = rtR0MemObjNativeMapKernel(&pNew, pMemToMap, pvFixed, uAlignment, fProt, offSub, cbSub, pszTag);
770 if (RT_SUCCESS(rc))
771 {
772 /* link it. */
773 rc = rtR0MemObjLink(pMemToMap, pNew);
774 if (RT_SUCCESS(rc))
775 *pMemObj = pNew;
776 else
777 {
778 /* damn, out of memory. bail out. */
779 int rc2 = rtR0MemObjNativeFree(pNew);
780 AssertRC(rc2);
781 pNew->u32Magic++;
782 pNew->enmType = RTR0MEMOBJTYPE_END;
783 RTMemFree(pNew);
784 }
785 }
786
787 return rc;
788}
789RT_EXPORT_SYMBOL(RTR0MemObjMapKernelExTag);
790
791
792RTR0DECL(int) RTR0MemObjMapUserTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, RTR3PTR R3PtrFixed,
793 size_t uAlignment, unsigned fProt, RTR0PROCESS R0Process, const char *pszTag)
794{
795 return RTR0MemObjMapUserExTag(pMemObj, MemObjToMap, R3PtrFixed, uAlignment, fProt, R0Process, 0, 0, pszTag);
796}
797RT_EXPORT_SYMBOL(RTR0MemObjMapUserTag);
798
799
800RTR0DECL(int) RTR0MemObjMapUserExTag(PRTR0MEMOBJ pMemObj, RTR0MEMOBJ MemObjToMap, RTR3PTR R3PtrFixed, size_t uAlignment,
801 unsigned fProt, RTR0PROCESS R0Process, size_t offSub, size_t cbSub, const char *pszTag)
802{
803 /* sanity checks. */
804 PRTR0MEMOBJINTERNAL pMemToMap;
805 PRTR0MEMOBJINTERNAL pNew;
806 int rc;
807 AssertPtrReturn(pMemObj, VERR_INVALID_POINTER);
808 pMemToMap = (PRTR0MEMOBJINTERNAL)MemObjToMap;
809 *pMemObj = NIL_RTR0MEMOBJ;
810 AssertPtrReturn(MemObjToMap, VERR_INVALID_HANDLE);
811 AssertReturn(pMemToMap->u32Magic == RTR0MEMOBJ_MAGIC, VERR_INVALID_HANDLE);
812 AssertReturn(pMemToMap->enmType > RTR0MEMOBJTYPE_INVALID && pMemToMap->enmType < RTR0MEMOBJTYPE_END, VERR_INVALID_HANDLE);
813 AssertReturn(!rtR0MemObjIsMapping(pMemToMap), VERR_INVALID_PARAMETER);
814 AssertReturn(pMemToMap->enmType != RTR0MEMOBJTYPE_RES_VIRT, VERR_INVALID_PARAMETER);
815 if (uAlignment == 0)
816 uAlignment = PAGE_SIZE;
817 AssertReturn(uAlignment == PAGE_SIZE || uAlignment == _2M || uAlignment == _4M, VERR_INVALID_PARAMETER);
818 if (R3PtrFixed != (RTR3PTR)-1)
819 AssertReturn(!(R3PtrFixed & (uAlignment - 1)), VERR_INVALID_PARAMETER);
820 AssertReturn(fProt != RTMEM_PROT_NONE, VERR_INVALID_PARAMETER);
821 AssertReturn(!(fProt & ~(RTMEM_PROT_READ | RTMEM_PROT_WRITE | RTMEM_PROT_EXEC)), VERR_INVALID_PARAMETER);
822 AssertReturn(!(offSub & PAGE_OFFSET_MASK), VERR_INVALID_PARAMETER);
823 AssertReturn(offSub < pMemToMap->cb, VERR_INVALID_PARAMETER);
824 AssertReturn(!(cbSub & PAGE_OFFSET_MASK), VERR_INVALID_PARAMETER);
825 AssertReturn(cbSub <= pMemToMap->cb, VERR_INVALID_PARAMETER);
826 AssertReturn((!offSub && !cbSub) || (offSub + cbSub) <= pMemToMap->cb, VERR_INVALID_PARAMETER);
827 if (R0Process == NIL_RTR0PROCESS)
828 R0Process = RTR0ProcHandleSelf();
829 RT_ASSERT_PREEMPTIBLE();
830
831 /* adjust the request to simplify the native code. */
832 if (offSub == 0 && cbSub == pMemToMap->cb)
833 cbSub = 0;
834
835 /* do the mapping. */
836 rc = rtR0MemObjNativeMapUser(&pNew, pMemToMap, R3PtrFixed, uAlignment, fProt, R0Process, offSub, cbSub, pszTag);
837 if (RT_SUCCESS(rc))
838 {
839 /* link it. */
840 rc = rtR0MemObjLink(pMemToMap, pNew);
841 if (RT_SUCCESS(rc))
842 *pMemObj = pNew;
843 else
844 {
845 /* damn, out of memory. bail out. */
846 int rc2 = rtR0MemObjNativeFree(pNew);
847 AssertRC(rc2);
848 pNew->u32Magic++;
849 pNew->enmType = RTR0MEMOBJTYPE_END;
850 RTMemFree(pNew);
851 }
852 }
853
854 return rc;
855}
856RT_EXPORT_SYMBOL(RTR0MemObjMapUserExTag);
857
858
859RTR0DECL(int) RTR0MemObjProtect(RTR0MEMOBJ hMemObj, size_t offSub, size_t cbSub, uint32_t fProt)
860{
861 PRTR0MEMOBJINTERNAL pMemObj;
862 int rc;
863
864 /* sanity checks. */
865 pMemObj = (PRTR0MEMOBJINTERNAL)hMemObj;
866 AssertPtrReturn(pMemObj, VERR_INVALID_HANDLE);
867 AssertReturn(pMemObj->u32Magic == RTR0MEMOBJ_MAGIC, VERR_INVALID_HANDLE);
868 AssertReturn(pMemObj->enmType > RTR0MEMOBJTYPE_INVALID && pMemObj->enmType < RTR0MEMOBJTYPE_END, VERR_INVALID_HANDLE);
869 AssertReturn(rtR0MemObjIsProtectable(pMemObj), VERR_INVALID_PARAMETER);
870 AssertReturn(!(offSub & PAGE_OFFSET_MASK), VERR_INVALID_PARAMETER);
871 AssertReturn(offSub < pMemObj->cb, VERR_INVALID_PARAMETER);
872 AssertReturn(!(cbSub & PAGE_OFFSET_MASK), VERR_INVALID_PARAMETER);
873 AssertReturn(cbSub <= pMemObj->cb, VERR_INVALID_PARAMETER);
874 AssertReturn(offSub + cbSub <= pMemObj->cb, VERR_INVALID_PARAMETER);
875 AssertReturn(!(fProt & ~(RTMEM_PROT_NONE | RTMEM_PROT_READ | RTMEM_PROT_WRITE | RTMEM_PROT_EXEC)), VERR_INVALID_PARAMETER);
876 RT_ASSERT_PREEMPTIBLE();
877
878 /* do the job */
879 rc = rtR0MemObjNativeProtect(pMemObj, offSub, cbSub, fProt);
880 if (RT_SUCCESS(rc))
881 pMemObj->fFlags |= RTR0MEMOBJ_FLAGS_PROT_CHANGED; /* record it */
882
883 return rc;
884}
885RT_EXPORT_SYMBOL(RTR0MemObjProtect);
886
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette