VirtualBox

Changeset 15399 in vbox for trunk/include/iprt


Ignore:
Timestamp:
Dec 12, 2008 10:02:14 PM (16 years ago)
Author:
vboxsync
Message:

iprt: new Linux sysfs APIs

Location:
trunk/include/iprt/linux
Files:
1 added
1 copied

Legend:

Unmodified
Added
Removed

  • trunk/include/iprt/linux/sysfs.h

    r14990 r15399  
     1/* $Id$ */
    12/** @file
    2  * IPRT - Multiprocessor.
     3 * IPRT - Linux sysfs access.
    34 */
    45
    … …  
    2829 */
    2930
    30 #ifndef ___iprt_mp_h
    31 #define ___iprt_mp_h
     31#ifndef ___iprt_linux_sysfs_h
     32#define ___iprt_linux_sysfs_h
    3233
    3334#include <iprt/cdefs.h>
    3435#include <iprt/types.h>
    3536
     37#include <stdarg.h>
    3638
    3739__BEGIN_DECLS
    3840
    39 /** @defgroup grp_rt_mp RTMp - Multiprocessor
     41/** @defgroup grp_rt_mp RTLinuxSysfs - Linux sysfs
    4042 * @ingroup grp_rt
    4143 * @{
    … …  
    4345
    4446/**
    45  * Gets the identifier of the CPU executing the call.
     47 * Checks if a sysfs file (or directory, device, symlink, whatever) exists.
    4648 *
    47  * When called from a system mode where scheduling is active, like ring-3 or
    48  * kernel mode with interrupts enabled on some systems, no assumptions should
    49  * be made about the current CPU when the call returns.
    50  *
    51  * @returns CPU Id.
     49 * @returns true / false, errno is preserved.
     50 * @param   pszFormat   The name format, either absolute or relative to "/sys/".
     51 * @param   va          The format args.
    5252 */
    53 RTDECL(RTCPUID) RTMpCpuId(void);
     53RTDECL(bool) RTLinuxSysFsExistsV(const char *pszFormat, va_list va);
    5454
    5555/**
    56  * Converts a CPU identifier to a CPU set index.
     56 * Checks if a sysfs file (or directory, device, symlink, whatever) exists.
    5757 *
    58  * This may or may not validate the presence of the CPU.
    59  *
    60  * @returns The CPU set index on success, -1 on failure.
    61  * @param   idCpu       The identifier of the CPU.
     58 * @returns true / false, errno is preserved.
     59 * @param   pszFormat   The name format, either absolute or relative to "/sys/".
     60 * @param   ...         The format args.
    6261 */
    63 RTDECL(int) RTMpCpuIdToSetIndex(RTCPUID idCpu);
     62RTDECL(bool) RTLinuxSysFsExists(const char *pszFormat, ...);
    6463
    6564/**
    66  * Converts a CPU set index to a a CPU identifier.
     65 * Opens a sysfs file.
    6766 *
    68  * This may or may not validate the presence of the CPU, so, use
    69  * RTMpIsCpuPossible for that.
    70  *
    71  * @returns The corresponding CPU identifier, NIL_RTCPUID on failure.
    72  * @param   iCpu    The CPU set index.
     67 * @returns The file descriptor. -1 and errno on failure.
     68 * @param   pszFormat   The name format, either absolute or relative to "/sys/".
     69 * @param   va          The format args.
    7370 */
    74 RTDECL(RTCPUID) RTMpCpuIdFromSetIndex(int iCpu);
     71RTDECL(int) RTLinuxSysFsOpenV(const char *pszFormat, va_list va);
    7572
    7673/**
    77  * Gets the max CPU identifier (inclusive).
     74 * Opens a sysfs file.
    7875 *
    79  * Inteded for brute force enumerations, but use with
    80  * care as it may be expensive.
    81  *
    82  * @returns The current higest CPU identifier value.
     76 * @returns The file descriptor. -1 and errno on failure.
     77 * @param   pszFormat   The name format, either absolute or relative to "/sys/".
     78 * @param   ...         The format args.
    8379 */
    84 RTDECL(RTCPUID) RTMpGetMaxCpuId(void);
    85 
     80RTDECL(int) RTLinuxSysFsOpen(const char *pszFormat, ...);
    8681
    8782/**
    88  * Checks if a CPU exists in the system or may possibly be hotplugged later.
     83 * Closes a file opened with RTLinuxSysFsOpen or RTLinuxSysFsOpenV.
    8984 *
    90  * @returns true/false accordingly.
    91  * @param   idCpu       The identifier of the CPU.
     85 * @param   fd
    9286 */
    93 RTDECL(bool) RTMpIsCpuPossible(RTCPUID idCpu);
     87RTDECL(void) RTLinuxSysFsClose(int fd);
    9488
    9589/**
    96  * Gets set of the CPUs present in the system pluss any that may
    97  * possibly be hotplugged later.
     90 * Reads a string from a file opened with RTLinuxSysFsOpen or RTLinuxSysFsOpenV.
    9891 *
    99  * @returns pSet.
    100  * @param   pSet    Where to put the set.
     92 * @returns The number of bytes read. -1 and errno on failure.
     93 * @param   fd          The file descriptor returned by RTLinuxSysFsOpen or RTLinuxSysFsOpenV.
     94 * @param   pszBuf      Where to store the string.
     95 * @param   cchBuf      The size of the buffer. Must be at least 2 bytes.
    10196 */
    102 RTDECL(PRTCPUSET) RTMpGetSet(PRTCPUSET pSet);
     97RTDECL(ssize_t) RTLinuxSysFsReadStr(int fd, char *pszBuf, size_t cchBuf);
    10398
    10499/**
    105  * Get the count of CPUs present in the system plus any that may
    106  * possibly be hotplugged later.
     100 * Reads a number from a sysfs file.
    107101 *
    108  * @return The count.
     102 * @returns 64-bit signed value on success, -1 and errno on failure.
     103 * @param   uBase       The number base, 0 for autodetect.
     104 * @param   pszFormat   The filename format, either absolute or relative to "/sys/".
     105 * @param   va          Format args.
    109106 */
    110 RTDECL(RTCPUID) RTMpGetCount(void);
    111 
     107RTDECL(int64_t) RTLinuxSysFsReadIntFileV(unsigned uBase, const char *pszFormat, va_list va);
    112108
    113109/**
    114  * Gets set of the CPUs present that are currently online.
     110 * Reads a number from a sysfs file.
    115111 *
    116  * @returns pSet.
    117  * @param   pSet    Where to put the set.
     112 * @returns 64-bit signed value on success, -1 and errno on failure.
     113 * @param   uBase       The number base, 0 for autodetect.
     114 * @param   pszFormat   The filename format, either absolute or relative to "/sys/".
     115 * @param   ...         Format args.
    118116 */
    119 RTDECL(PRTCPUSET) RTMpGetOnlineSet(PRTCPUSET pSet);
     117RTDECL(int64_t) RTLinuxSysFsReadIntFile(unsigned uBase, const char *pszFormat, ...);
    120118
    121119/**
    122  * Get the count of CPUs that are currently online.
     120 * Reads a string from a sysfs file.  If the file contains a newline, we only
     121 * return the text up until there.
    123122 *
    124  * @return The count.
     123 * @returns number of characters read on success, -1 and errno on failure.
     124 * @param   pszBuf      Where to store the path element.  Must be at least two
     125 *                      characters, but a longer buffer would be advisable.
     126 * @param   cchBuf      The size of the buffer pointed to by @a pszBuf.
     127 * @param   pszFormat   The filename format, either absolute or relative to "/sys/".
     128 * @param   va          Format args.
    125129 */
    126 RTDECL(RTCPUID) RTMpGetOnlineCount(void);
     130RTDECL(ssize_t) RTLinuxSysFsReadStrFileV(char *pszBuf, size_t cchBuf, const char *pszFormat, va_list va);
    127131
    128132/**
    129  * Checks if a CPU is online or not.
     133 * Reads a string from a sysfs file.  If the file contains a newline, we only
     134 * return the text up until there.
    130135 *
    131  * @returns true/false accordingly.
    132  * @param   idCpu       The identifier of the CPU.
     136 * @returns number of characters read on success, -1 and errno on failure.
     137 * @param   pszBuf      Where to store the path element.  Must be at least two
     138 *                      characters, but a longer buffer would be advisable.
     139 * @param   cchBuf      The size of the buffer pointed to by @a pszBuf.
     140 * @param   pszFormat   The filename format, either absolute or relative to "/sys/".
     141 * @param   ...         Format args.
    133142 */
    134 RTDECL(bool) RTMpIsCpuOnline(RTCPUID idCpu);
    135 
     143RTDECL(ssize_t) RTLinuxSysFsReadStrFile(char *pszBuf, size_t cchBuf, const char *pszFormat, ...);
    136144
    137145/**
    138  * Gets set of the CPUs present in the system.
     146 * Reads the last element of the path of the file pointed to by the symbolic
     147 * link specified.  This is needed at least to get the name of the driver
     148 * associated with a device, where pszFormat should be the "driver" link in the
     149 * devices sysfs directory.
    139150 *
    140  * @returns pSet.
    141  * @param   pSet    Where to put the set.
     151 * @returns The number of characters written on success, -1 and errno on failure.
     152 * @param   pszBuf      Where to store the path element.  Must be at least two
     153 *                      characters, but a longer buffer would be advisable.
     154 * @param   cchBuf      The size of the buffer pointed to by @a pszBuf.
     155 * @param   pszFormat   The filename format, either absolute or relative to "/sys/".
     156 * @param   ...         Format args.
    142157 */
    143 RTDECL(PRTCPUSET) RTMpGetPresentSet(PRTCPUSET pSet);
    144 
    145 /**
    146  * Get the count of CPUs that are present in the system.
    147  *
    148  * @return The count.
    149  */
    150 RTDECL(RTCPUID) RTMpGetPresentCount(void);
    151 
    152 /**
    153  * Checks if a CPU is present in the system.
    154  *
    155  * @returns true/false accordingly.
    156  * @param   idCpu       The identifier of the CPU.
    157  */
    158 RTDECL(bool) RTMpIsCpuPresent(RTCPUID idCpu);
    159 
    160 
    161 /**
    162  * Get the current frequency of a CPU.
    163  *
    164  * The CPU must be online.
    165  *
    166  * @returns The frequency as MHz. 0 if the CPU is offline
    167  *          or the information is not available.
    168  * @param   idCpu       The identifier of the CPU.
    169  */
    170 RTDECL(uint32_t) RTMpGetCurFrequency(RTCPUID idCpu);
    171 
    172 
    173 /**
    174  * Get the maximum frequency of a CPU.
    175  *
    176  * The CPU must be online.
    177  *
    178  * @returns The frequency as MHz. 0 if the CPU is offline
    179  *          or the information is not available.
    180  * @param   idCpu       The identifier of the CPU.
    181  */
    182 RTDECL(uint32_t) RTMpGetMaxFrequency(RTCPUID idCpu);
    183 
    184 
    185 #ifdef IN_RING0
    186 
    187 /**
    188  * Worker function passed to RTMpOnAll, RTMpOnOthers and RTMpOnSpecific that
    189  * is to be called on the target cpus.
    190  *
    191  * @param   idCpu       The identifier for the CPU the function is called on.
    192  * @param   pvUser1     The 1st user argument.
    193  * @param   pvUser2     The 2nd user argument.
    194  */
    195 typedef DECLCALLBACK(void) FNRTMPWORKER(RTCPUID idCpu, void *pvUser1, void *pvUser2);
    196 /** Pointer to a FNRTMPWORKER. */
    197 typedef FNRTMPWORKER *PFNRTMPWORKER;
    198 
    199 /**
    200  * Executes a function on each (online) CPU in the system.
    201  *
    202  * @returns IPRT status code.
    203  * @retval  VINF_SUCCESS on success.
    204  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
    205  *
    206  * @param   pfnWorker       The worker function.
    207  * @param   pvUser1         The first user argument for the worker.
    208  * @param   pvUser2         The second user argument for the worker.
    209  *
    210  * @remarks The execution isn't in any way guaranteed to be simultaneous,
    211  *          it might even be serial (cpu by cpu).
    212  */
    213 RTDECL(int) RTMpOnAll(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
    214 
    215 /**
    216  * Executes a function on a all other (online) CPUs in the system.
    217  *
    218  * @returns IPRT status code.
    219  * @retval  VINF_SUCCESS on success.
    220  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
    221  *
    222  * @param   pfnWorker       The worker function.
    223  * @param   pvUser1         The first user argument for the worker.
    224  * @param   pvUser2         The second user argument for the worker.
    225  *
    226  * @remarks The execution isn't in any way guaranteed to be simultaneous,
    227  *          it might even be serial (cpu by cpu).
    228  */
    229 RTDECL(int) RTMpOnOthers(PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
    230 
    231 /**
    232  * Executes a function on a specific CPU in the system.
    233  *
    234  * @returns IPRT status code.
    235  * @retval  VINF_SUCCESS on success.
    236  * @retval  VERR_NOT_SUPPORTED if this kind of operation isn't supported by the system.
    237  * @retval  VERR_CPU_OFFLINE if the CPU is offline.
    238  * @retval  VERR_CPU_NOT_FOUND if the CPU wasn't found.
    239  *
    240  * @param   idCpu           The id of the CPU.
    241  * @param   pfnWorker       The worker function.
    242  * @param   pvUser1         The first user argument for the worker.
    243  * @param   pvUser2         The second user argument for the worker.
    244  */
    245 RTDECL(int) RTMpOnSpecific(RTCPUID idCpu, PFNRTMPWORKER pfnWorker, void *pvUser1, void *pvUser2);
    246 
    247 
    248 /**
    249  * MP event, see FNRTMPNOTIFICATION.
    250  */
    251 typedef enum RTMPEVENT
    252 {
    253     /** The CPU goes online. */
    254     RTMPEVENT_ONLINE = 1,
    255     /** The CPU goes offline. */
    256     RTMPEVENT_OFFLINE
    257 } RTMPEVENT;
    258 
    259 /**
    260  * Notification callback.
    261  *
    262  * The context this is called in differs a bit from platform to
    263  * platform, so be careful while in here.
    264  *
    265  * @param   idCpu       The CPU this applies to.
    266  * @param   enmEvent    The event.
    267  * @param   pvUser      The user argument.
    268  */
    269 typedef DECLCALLBACK(void) FNRTMPNOTIFICATION(RTMPEVENT enmEvent, RTCPUID idCpu, void *pvUser);
    270 /** Pointer to a FNRTMPNOTIFICATION(). */
    271 typedef FNRTMPNOTIFICATION *PFNRTMPNOTIFICATION;
    272 
    273 /**
    274  * Registers a notification callback for cpu events.
    275  *
    276  * On platforms which doesn't do cpu offline/online events this API
    277  * will just be a no-op that pretends to work.
    278  *
    279  * @todo We'll be adding a flag to this soon to indicate whether the callback should be called on all
    280  *       CPUs that are currently online while it's being registered. This is to help avoid some race
    281  *       conditions (we'll hopefully be able to implement this on linux, solaris/win is no issue).
    282  *
    283  * @returns IPRT status code.
    284  * @retval  VINF_SUCCESS on success.
    285  * @retval  VERR_NO_MEMORY if a registration record cannot be allocated.
    286  * @retval  VERR_ALREADY_EXISTS if the pfnCallback and pvUser already exist
    287  *          in the callback list.
    288  *
    289  * @param   pfnCallback     The callback.
    290  * @param   pvUser          The user argument to the callback function.
    291  */
    292 RTDECL(int) RTMpNotificationRegister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
    293 
    294 /**
    295  * This deregisters a notification callback registered via RTMpNotificationRegister().
    296  *
    297  * The pfnCallback and pvUser arguments must be identical to the registration call
    298  * of we won't find the right entry.
    299  *
    300  * @returns IPRT status code.
    301  * @retval  VINF_SUCCESS on success.
    302  * @retval  VERR_NOT_FOUND if no matching entry was found.
    303  *
    304  * @param   pfnCallback     The callback.
    305  * @param   pvUser          The user argument to the callback function.
    306  */
    307 RTDECL(int) RTMpNotificationDeregister(PFNRTMPNOTIFICATION pfnCallback, void *pvUser);
    308 
    309 #endif /* IN_RING0 */
     158RTDECL(int) RTLinuxSysFsGetLinkDest(char *pszBuf, size_t cchBuf, const char *pszFormat, ...);
    310159
    311160/** @} */
Note: See TracChangeset for help on using the changeset viewer.

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