VirtualBox

source: vbox/trunk/include/iprt/krnlmod.h@ 103224

Last change on this file since 103224 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.9 KB
Line 
1/** @file
2 * IPRT - Kernel module.
3 */
4
5/*
6 * Copyright (C) 2017-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_krnlmod_h
37#define IPRT_INCLUDED_krnlmod_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44
45
46RT_C_DECLS_BEGIN
47
48/** @defgroup grp_rt_kmod RTKrnlMod - Kernel module/driver userspace side API.
49 * @ingroup grp_rt
50 * @{
51 */
52
53/**
54 * Checks whether the given kernel module was loaded.
55 *
56 * @returns IPRT status code.
57 * @param pszName The driver name to check.
58 * @param pfLoaded Where to store the flag whether the module is loaded on success.
59 */
60RTDECL(int) RTKrnlModQueryLoaded(const char *pszName, bool *pfLoaded);
61
62/**
63 * Returns the kernel module information handle for the given loaded kernel module.
64 *
65 * @returns IPRT status code.
66 * @retval VERR_NOT_FOUND if the kernel driver is not loaded.
67 * @param pszName The driver name.
68 * @param phKrnlModInfo Where to store the handle to the kernel module information record.
69 */
70RTDECL(int) RTKrnlModLoadedQueryInfo(const char *pszName, PRTKRNLMODINFO phKrnlModInfo);
71
72/**
73 * Returns the number of kernel modules loaded on the host system.
74 *
75 * @returns Number of kernel modules loaded.
76 */
77RTDECL(uint32_t) RTKrnlModLoadedGetCount(void);
78
79/**
80 * Returns all loaded kernel modules on the host.
81 *
82 * @returns IPRT status code.
83 * @retval VERR_BUFFER_OVERFLOW if there are not enough entries in the passed handle array.
84 * The required number of entries will be returned in pcEntries.
85 * @param pahKrnlModInfo Where to store the handles to the kernel module information records
86 * on success.
87 * @param cEntriesMax Maximum number of entries fitting in the given array.
88 * @param pcEntries Where to store the number of entries used/required.
89 */
90RTDECL(int) RTKrnlModLoadedQueryInfoAll(PRTKRNLMODINFO pahKrnlModInfo, uint32_t cEntriesMax,
91 uint32_t *pcEntries);
92
93/**
94 * Retains the given kernel module information record handle.
95 *
96 * @returns New reference count.
97 * @param hKrnlModInfo The kernel module information record handle.
98 */
99RTDECL(uint32_t) RTKrnlModInfoRetain(RTKRNLMODINFO hKrnlModInfo);
100
101/**
102 * Releases the given kernel module information record handle.
103 *
104 * @returns New reference count, on 0 the handle is destroyed.
105 * @param hKrnlModInfo The kernel module information record handle.
106 */
107RTDECL(uint32_t) RTKrnlModInfoRelease(RTKRNLMODINFO hKrnlModInfo);
108
109/**
110 * Returns the number of references held onto the kernel module by other
111 * drivers or userspace clients.
112 *
113 * @returns Number of references held on the kernel module.
114 * @param hKrnlModInfo The kernel module information record handle.
115 */
116RTDECL(uint32_t) RTKrnlModInfoGetRefCnt(RTKRNLMODINFO hKrnlModInfo);
117
118/**
119 * Returns the name of the kernel module.
120 *
121 * @returns Pointer to the kernel module name.
122 * @param hKrnlModInfo The kernel module information record handle.
123 */
124RTDECL(const char *) RTKrnlModInfoGetName(RTKRNLMODINFO hKrnlModInfo);
125
126/**
127 * Returns the filepath of the kernel module.
128 *
129 * @returns Pointer to the kernel module path.
130 * @param hKrnlModInfo The kernel module information record handle.
131 */
132RTDECL(const char *) RTKrnlModInfoGetFilePath(RTKRNLMODINFO hKrnlModInfo);
133
134/**
135 * Returns the size of the kernel module.
136 *
137 * @returns Size of the kernel module in bytes.
138 * @param hKrnlModInfo The kernel module information record handle.
139 */
140RTDECL(size_t) RTKrnlModInfoGetSize(RTKRNLMODINFO hKrnlModInfo);
141
142/**
143 * Returns the load address of the kernel module.
144 *
145 * @returns Load address of the kernel module.
146 * @param hKrnlModInfo The kernel module information record handle.
147 */
148RTDECL(RTR0UINTPTR) RTKrnlModInfoGetLoadAddr(RTKRNLMODINFO hKrnlModInfo);
149
150/**
151 * Query the kernel information record for a referencing kernel module of the
152 * given record.
153 *
154 * @returns IPRT status code.
155 * @param hKrnlModInfo The kernel module information record handle.
156 * @param idx Referencing kernel module index (< reference count
157 * as retrieved by RTKrnlModInfoGetRefCnt() ).
158 * @param phKrnlModInfoRef Where to store the handle to the referencing kernel module
159 * information record.
160 */
161RTDECL(int) RTKrnlModInfoQueryRefModInfo(RTKRNLMODINFO hKrnlModInfo, uint32_t idx,
162 PRTKRNLMODINFO phKrnlModInfoRef);
163
164/**
165 * Tries to load a kernel module by the given name.
166 *
167 * @returns IPRT status code.
168 * @retval VERR_NOT_SUPPORTED if not supported by or implemented for the platform.
169 * @param pszName The name of the kernel module. This is highly platform
170 * dependent.
171 *
172 * @note On macOS for example the name is the bundle ID.
173 */
174RTDECL(int) RTKrnlModLoadByName(const char *pszName);
175
176/**
177 * Tries to load a kernel module by the given file path.
178 *
179 * @returns IPRT status code.
180 * @retval VERR_NOT_SUPPORTED if not supported by or implemented for the platform.
181 * @param pszPath The path of the kernel module.
182 */
183RTDECL(int) RTKrnlModLoadByPath(const char *pszPath);
184
185/**
186 * Tries to unload a kernel module by the given name.
187 *
188 * @returns IPRT status code.
189 * @param pszName The name of the kernel module. This is highly platform
190 * dependent and should be queried with RTKrnlModInfoGetName()
191 * when checking whether the module was actually loaded.
192 *
193 * @note On macOS for example the name is the bundle ID.
194 */
195RTDECL(int) RTKrnlModUnloadByName(const char *pszName);
196
197/** @} */
198
199RT_C_DECLS_END
200
201#endif /* !IPRT_INCLUDED_krnlmod_h */
202
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