Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ./../../../../../../usr/include/sys/kom.h
Real path: /usr/include/sys/kom.h
Zurück

/* * Copyright (c) 2014, 2021, Oracle and/or its affiliates. */ #ifndef _SYS_KOM_H #define _SYS_KOM_H #include <sys/types.h> #include <sys/systm.h> #ifdef __cplusplus extern "C" { #endif /* * Kernel Object Manager subsystem. * * *** Interface Stability and Scope: Unstable / Consolidation Private *** * * Kernel objects are opaque ranges of kernel memory, which may represent. * resources, linear-addressed spaces, memory spans, or abstract data types. * Each kernel object is a member of a class, has a blob of kernel physcial * memory behind it, and some class-dependent kernel state associated with it * (the payload). * * There is a common set of methods which can be used to manipulate objects of * any class. A class may use the system default methods, which treat the * object as a buffer in the kernel's virtual address space which is not * necessarily physically contiguous. Alternatively, the class may define its * own methods. Regardless of class type, objects appear to be opaque binary * blobs supporting a common set of object-oriented semantics. * * The set of methods supported is: * * Create - creates an object, and allocates its in-memory kernel state, * returning a handle. The object is returned with an exclusive hold on it. It * is the responsibility of the caller to release or downgrade the excl hold * associated with the handle. * * Destroy - destroys an object, and frees its in-memory kernel state. The * caller must have an exclusive hold on the object. The passed handle is * invalid after this call completes. If the object was allocated from a * KOM cache the object is returned to the cache, otherwise it is freed * to the system. * * Cache Create - creates a kmem cache which will hold objects of the same * size and create flags. * * Cache Destroy - destroys a kmem cache of objects. The cache must be empty. * * Cache Alloc - logically equivalent to calling kom_create() with the create * flags matching those the KOM cache was created with, but much more * scaleable for objects which are frequently created or destroyed. * * There is no Cache Free - Destroy or Release will just do the right thing. * * Hold - acquire a new shared reference to an object, and return the new * handle. The handle passed in remains valid. The caller must not have an * exclusive hold on the object. Can fail even if we did not ask to block * in some cases, such as out of available resources. * * Query - various routines query object attributes given a handle. * * Upgrade - upgrade a previously acquired shared hold to an exclusive hold. * The handle remains valid after a call to this method. It is invalid to * call this funciton on an exclusively held handle. The flags indicate * whether the caller should wait or fail, and if the call would not block, * whether we should panic instead of returning failure. * * Downgrade - downgrade a previously acquired exclusive hold to a shared * hold. The handle remains valid after a call to this method. * * Release - release a handle and the hold associated with it. The handle is * invalid after a call to this method. * * Freeze - make the object's in-memory state immutable. After this method * returns, the in-memory state is guaranteed not to change until the object * is thawed, or destroyed. * * Thaw - make the object's in-memory state mutable. * * Copyfrombuf - serialize an object's in-memory state to a supplied buffer. * The size of the supplied buffer is assumed to be at least as large as the * size returned by the getsize method. The object must not be frozen. * * Copytobuf - sync an object's in-memory state with a supplied buffer. The * size of the supplied buffer is assumed to be at least as large as the size * returned by the getsize method. * * Activate - acquire a linear, virtually-addressed mapping to the object's * in-memory state at the given logical <offset, len> tuple within the object * space. Each handle may be activated at most once, and the handle may not * be destroyed while activated. If passed, the given revocation function * will be called to revoke the activation, should the system need to move * the object in memory. The LONGTERM flag should be passed if the activation * is likely to persist for more than several seconds (e.g. if it's part of * the I/O path). If the object's activation is only used for reading data * READ_ONLY should be asserted. If the entire contents of the object will be * overwritten, OVERWRITE should be asserted to eliminate some unnecessary * data copies. * * Deactivate - release a virtually-addressed mapping to the object's * in-memory state which was established by a call to Activate. * * Getsize - return the current size of the object's in-memory state. * * Getpayload - returns a void * pointer to the "payload" metadata for the * object. Each object has a payload buffer which is sized based on the * object class definition. The payload area is opaque to the framework. * * Getowner / Setowner - sets or returns a void * pointer in the object * _handle_ itself. The owner value is opaque to the framework and is * typically used to provide a back pointer to the data structure which "owns" * the handle. * * * Advantages / when to use * ------------------------ * * One advantage of using an object vs kmem_alloc(), or kmem_cache_alloc() with * virtual addresses, is that many common operations such as locking, reference * counting, and debug tracing are automated by the kernel object manager * framework. Another advantage is that the system has direct control over, * plus visibility of, memory usage by class. In the near future, the system * will request to reclaim not recently or frequently used objects from the * owning subsystem when it needs more memory. In addition, the system will * relocate objects as required in order to defragment heap memory. This * defragmentation is transparent to the interface consumers. * * Another consideration vs traditional heap-based ADTs, is that the KOM * framework provides plenty of debugging and consistency checks, better * guarding against common errors such as buffer overruns and use-after-free * problems; these types of problems can be considerably more difficult to * debug when the symptom of a bug is random kernel heap corruption. File * systems (in particular) should find it very convenient and natural to use * kernel objects to represent and cache on-disk metadata within the kernel. * * Finally, when KOM objects are relinquished, their virtual address demapping * may be batched and async (as required), versus kmem_alloc(), which requires * immediate demapping before the virtual address can be returned to the heap * arena. This saves many expensive cross calls and can greatly improve * scalability of large systems when kernel memory is heavily used. * * KOM objects do have considerable overhead, sizeof (kom_object_t) + * sizeof (kom_handle_t) per object, so it doesn't make sense to use objects * for really small datatypes. * * * Events * ------ * * Many of the object methods, when invoked, generate associated events. The * available events are defined in the kom_event_t enum below. An interested * subsystem may register a callback to be notified of events it is interested * about on a given object. The event callback should not make any assumptions * about the state of the object, since the object is not held or otherwise * locked across the callback invocation. * * One thing to note is that once an object payload is constructed by the * consumer, the consumer can register a destroy callback on the object -- this * callback can serve as the destructor for the object payload to free any * resources which are held by the payload. */ struct kom_handle; struct kom_object; struct kom_class; struct kom_cache; typedef struct kom_handle kom_handle_t; typedef struct kom_object kom_object_t; typedef struct kom_class kom_class_t; typedef struct kom_cache kom_cache_t; typedef enum { KO_HOLD_SHARED = 0x001, /* obtain shared handle */ KO_HOLD_EXCL = 0x080, /* obtain the one true handle */ #define KO_HOLD_SE 0x081 KO_HOLD_NOWAIT = 0x100, /* don't sleep if busy */ KO_HOLD_DEBUG = 0x200 /* enable handle debugging */ } kom_hold_t; typedef enum { KO_UPGRADE_NOWAIT = 0x01, /* no block or wait for mem */ KO_UPGRADE_PANIC = 0x02 /* panic if >1 shared ref */ } kom_upgrade_t; typedef enum { KO_SUCCESS, /* operation succeeded */ KO_BUSY, /* object is temporarily busy, retry later */ KO_REJECT, /* object is indefinitely busy, do not retry */ KO_NOTCONTIG, /* object is not in one contiguous memory chunk */ KO_NOMEM, /* system is out of available memory for objects */ KO_FAULT, /* memory access generated a trap (possibly ECC) */ KO_CHECKSUM /* current checksum does not match stored checksum */ } kom_result_t; /* These values are used in kom_flags_t in kom_impl.h */ typedef enum { KO_CREATE_NOWAIT = 0x01, /* creating thread cannot block */ KO_CREATE_NUMA = 0x02, /* affinity to the creating thread */ KO_CREATE_ZERO = 0x04, /* object is immmutable zero buffer */ KO_CREATE_DEBUG = 0x08, /* enable debug tracing / validation */ KO_CREATE_FIREWALL = 0x10, /* enable firewalled activations */ #define KO_CREATE_FLAGS 0x1f } kom_crflags_t; typedef enum { KO_EVENT_DESTROY = 0x01, /* fires on kom_destroy() */ KO_EVENT_FREEZE = 0x02, /* fires on kom_freeze() */ KO_EVENT_THAW = 0x04, /* fires on kom_thaw() */ KO_EVENT_HOLD = 0x08, /* fires on kom_hold() */ KO_EVENT_RELE = 0x10, /* fires on kom_rele() */ KO_EVENT_ACTIVATE = 0x20, /* fires on kom_*activate() */ KO_EVENT_DEACTIVATE = 0x40 /* fires on kom_*deactivate() */ } kom_event_t; typedef enum { KO_ACTIVATE_NOWAIT = 0x1, /* don't sleep */ KO_ACTIVATE_LONGTERM = 0x2, /* long term activation */ KO_ACTIVATE_FIREWALL = 0x4, /* use firewalled VA */ KO_ACTIVATE_READ_ONLY = 0x8, /* read-only activation */ KO_ACTIVATE_PFN = 0x10, /* return PFN rather than VA */ KO_ACTIVATE_OVERWRITE = 0x20, /* content will be overritten */ #define KO_ACTIVATE_FLAGS 0x3f KO_ACTIVATE_NOTRACK = 0x40000, /* internal: framework mapped */ KO_ACTIVATE_KPM = 0x80000, /* internal: using KPM VA */ KO_ACTIVATE_LOCKED = 0x100000 /* internal: obj lock held */ } kom_acttype_t; struct _kthread; #define KO_LOG_STACKDEPTH 29 typedef struct { hrtime_t kod_hrtime; hrtime_t kod_stopped_interval; struct _kthread *kod_thread; pc_t kod_callstack[KO_LOG_STACKDEPTH]; int kod_depth; } kom_debug_t; typedef void (*kom_event_cb_t)(kom_object_t *, kom_event_t, void *arg); typedef kom_result_t (*kom_revoke_cb_t)(kom_handle_t *, void *arg, void *ptr); /* * Class API */ typedef struct { void (*kcm_hold)(kom_handle_t *h, kom_hold_t hflags); void (*kcm_rele)(kom_handle_t *h); void (*kcm_freeze)(kom_handle_t *h); void (*kcm_thaw)(kom_handle_t *h); kom_result_t (*kcm_cksum_set)(kom_handle_t *h); kom_result_t (*kcm_cksum_check)(kom_handle_t *h); kom_result_t (*kcm_copytobuf)(kom_handle_t *h, char *buf, size_t); kom_result_t (*kcm_copyfrombuf)(kom_handle_t *h, char *buf, size_t); } kom_class_method_t; /* * These correspond to supported memory_usage_type_ts */ typedef enum { KOM_MEMUSAGE_KERNEL = 0, KOM_MEMUSAGE_ZFS, KOM_MEMUSAGE_EXECUTABLE, KOM_MEMUSAGE_NTYPES /* must be last */ } kom_memusagetype_t; /* * These correspond with the dump_dataphase_t dump types. */ typedef enum { KOM_DUMP_MAIN = 0, KOM_DUMP_OTHER, KOM_DUMP_ZFS, KOM_DUMP_NONE /* must be last */ } kom_dumptype_t; /* * Slab properties which are required for the class. */ typedef enum { KO_SLABPROP_LONGTERM = 0x01, KO_SLABPROP_PSTATIC = 0x02, KO_SLABPROP_CONTIG = 0x04 } kom_slabprop_t; typedef struct kom_classusage { uint64_t kcu_memsize; /* total memory used */ uint64_t kcu_rss; /* total memory currently in-use */ uint64_t kcu_kmbacked; /* total memory backed by kmem */ } kom_classusage_t; typedef enum { KOM_STATE_GROW, KOM_STATE_STEADY, KOM_STATE_PAUSE, KOM_STATE_SHRINK } kom_throttle_state_t; /* * The freelist index function is expected to take a size between * [c_minsize, c_maxsize] and return an index between [0, c_num_freelists). * This allows the consumer of the interface to decide which sizes are most * frequently used and allow for the least waste of space, rather than the * framework having to guess and get it wrong. */ typedef uint_t (*kom_flidx_fn_t)(size_t); typedef size_t (*kom_flsize_fn_t)(uint_t); /* * The alloc/free functions take a size between [c_minsize, c_maxsize] and * do a KM_SLEEP allocation. The memory returned is not guaranteed contiguous. */ typedef void * (*kom_alloc_fn_t)(size_t); typedef void (*kom_free_fn_t)(void *, size_t); typedef struct { /* Object method implementation */ kom_class_method_t *c_obj_methods; /* Memory attributes required for this class */ kom_slabprop_t c_slabprops; /* Size of payload buffer to be returned by kom_getpayload() */ size_t c_obj_payload_size; /* Memory usage type. Default == KERNEL */ kom_memusagetype_t c_memusagetype; /* Dump type. Default == MAIN */ kom_dumptype_t c_dumptype; /* Smallest supported object size */ size_t c_minsize; /* Largest supported object size */ size_t c_maxsize; /* Number of possible freelist index values from minsize to maxsize */ uint_t c_num_freelists; /* Function which returns freelist idx from 0 to c_num_freelists */ kom_flidx_fn_t c_size2idx; /* Function which returns object size for a given freelist idx */ kom_flsize_fn_t c_idx2size; /* vmem arena to use for any kmem caches (or NULL) */ struct vmem *c_arena; /* name to use in ::memstat and other descriptive displays */ const char *c_descriptive_name; /* kmem reap group for caches that KOM uses to manage this class */ kmem_reapset_t c_kmem_reap_set; /* function to allocate memory if the backend allocation fails */ kom_alloc_fn_t c_virtmem_alloc; /* function to free memory allocated by preceeding function */ kom_free_fn_t c_virtmem_free; } kom_classdef_t; extern kom_class_t *kom_class_create(char *, kom_classdef_t *); extern void kom_class_destroy(kom_class_t *); extern void kom_class_usage(kom_class_t *, kom_classusage_t *); extern void kom_usage_bymemusagetype(kom_classusage_t *, size_t); /* * Capture interface */ #ifdef _KERNEL extern kom_result_t kom_capture_init(paddr_t); extern kom_result_t kom_capture_start(paddr_t, boolean_t); extern kom_result_t kom_capture_alloc(paddr_t, boolean_t); extern kom_result_t kom_capture_drain(paddr_t); extern void kom_capture_fini(paddr_t); extern void kom_capture_handoff_callback(paddr_t); #endif /* * Default method implementation */ extern void kom_default_hold(kom_handle_t *, kom_hold_t); extern void kom_default_release(kom_handle_t *); extern void kom_default_freeze(kom_handle_t *); extern void kom_default_thaw(kom_handle_t *); extern kom_result_t kom_default_checksum_set(kom_handle_t *); extern kom_result_t kom_default_checksum_check(kom_handle_t *); extern kom_result_t kom_default_copytobuf(kom_handle_t *, char *, size_t); extern kom_result_t kom_default_copyfrombuf(kom_handle_t *, char *, size_t); /* * Object API */ extern kom_handle_t *kom_create(kom_class_t *, size_t, kom_crflags_t, void *); extern void kom_destroy(kom_handle_t *); extern kom_cache_t *kom_cache_create(kom_class_t *, size_t, kom_crflags_t); extern void kom_cache_destroy(kom_cache_t *); extern kom_handle_t *kom_cache_alloc(kom_cache_t *, void *, boolean_t); extern kom_handle_t *kom_hold(kom_handle_t *, kom_hold_t, void *); extern kom_handle_t *kom_hold_bypayload(void *, void *); extern kom_result_t kom_upgrade(kom_handle_t *, kom_upgrade_t); extern void kom_downgrade(kom_handle_t *); extern void kom_release(kom_handle_t *); extern void kom_freeze(kom_handle_t *); extern void kom_thaw(kom_handle_t *); extern boolean_t kom_equiv(kom_handle_t *, kom_handle_t *); extern kom_result_t kom_copytobuf(kom_handle_t *__src, char *__dest, size_t __len); extern kom_result_t kom_copyfrombuf(kom_handle_t *__dest, char *__src, size_t __len); extern void *kom_activate(kom_handle_t *, kom_acttype_t); extern void *kom_reactivate(kom_handle_t *, kom_acttype_t, void *); extern void *kom_xactivate(kom_handle_t *, kom_acttype_t, kom_revoke_cb_t, void *); extern void kom_deactivate(kom_handle_t *, void *); extern void kom_xdeactivate(kom_handle_t *, kom_acttype_t, void *); extern size_t kom_getsize(kom_handle_t *); extern void kom_event_register(kom_handle_t *, uint_t, kom_event_cb_t, void *); extern void kom_event_unregister(kom_handle_t *, kom_event_cb_t, void *); /* * Various query routines */ extern kom_class_t *kom_getclass(kom_handle_t *); extern const char *kom_getclassname(kom_handle_t *); extern kom_hold_t kom_getholdtype(kom_handle_t *); extern void *kom_getpayload(kom_handle_t *); extern void *kom_getowner(kom_handle_t *); extern void kom_setowner(kom_handle_t *, void *); extern boolean_t kom_mutable(kom_handle_t *); extern boolean_t kom_immutable(kom_handle_t *); extern boolean_t kom_activated(kom_handle_t *); extern void kom_arc_delay(uint64_t); extern void kom_arc_register_cv(kcondvar_t *); extern kom_throttle_state_t kom_throttle(int64_t *, uint_t); extern kom_throttle_state_t kom_throttle_state(void); #ifdef __cplusplus } #endif #endif /* _SYS_KOM_H */