Haiku Book: added Image for the Kernel Kit.
Made visible that kit in the index page. Change-Id: I1bceecc49205a2344bc5a6eff3296980162bf620 Reviewed-on: https://review.haiku-os.org/c/haiku/+/11015 Haiku-Format: Haiku-format Bot <[email protected]> Reviewed-by: Adrien Destugues <[email protected]> Tested-by: Commit checker robot <[email protected]>
This commit is contained in:
cafeina
committed by
Adrien Destugues
Adrien Destugues
parent
268e56a9c8
commit
8294280634
@@ -44,6 +44,12 @@
|
||||
- The \link layout_intro Layout API \endlink is a new addition
|
||||
to the Interface Kit in Haiku which provides resources to
|
||||
layout your application flexibly and easily.
|
||||
- The \ref kernel contains functions and definitions to work with the
|
||||
applications' running behaviors. This includes handling teams and
|
||||
their threads, loaded executable images and their symbols, or deal
|
||||
with big stretches of shared memory known as areas. In addition, it also
|
||||
provides utilities to perform scheduling and thread access protection
|
||||
through semaphores.
|
||||
- The \ref locale includes classes to localize your application to
|
||||
different languages, timezones, number formatting conventions and
|
||||
much more.
|
||||
|
||||
@@ -0,0 +1,469 @@
|
||||
/*
|
||||
* Copyright 2026 Haiku, Inc. All rights reserved.
|
||||
* Distributed under the terms of the MIT License.
|
||||
*
|
||||
* Authors:
|
||||
* cafeina
|
||||
*
|
||||
* Corresponds to:
|
||||
* headers/os/kernel/image.h
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\file image.h
|
||||
\ingroup kernel
|
||||
\brief Contains definitions and functions to deal with executable images
|
||||
and the symbols they contain.
|
||||
|
||||
It also contains the function clear_caches() to invalidate or flush
|
||||
sections in the CPU caches.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\typedef int32 image_id
|
||||
\brief Defines a type to identify images of binaries in memory.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\typedef enum {} image_type
|
||||
\brief Contains identifiers for the type of images.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var ::B_APP_IMAGE
|
||||
\brief The image is an application image.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var ::B_LIBRARY_IMAGE
|
||||
\brief The image is a library image.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var ::B_ADD_ON_IMAGE
|
||||
\brief The image is an add-on image.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var ::B_SYSTEM_IMAGE
|
||||
\brief The image is a system image.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\struct {} image_info
|
||||
\ingroup kernel
|
||||
\brief Contains information about a running image.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var image_id image_info::id
|
||||
\brief The image's identifier number.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var image_type image_info::type
|
||||
\brief The type of the image.
|
||||
|
||||
It is one of the following:
|
||||
- ::B_APP_IMAGE
|
||||
- ::B_LIBRARY_IMAGE
|
||||
- ::B_ADD_ON_IMAGE
|
||||
- ::B_SYSTEM_IMAGE
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var int32 image_info::sequence
|
||||
\brief A number that indicates the order in which the image was loaded
|
||||
respective to the other images in this team.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var int32 image_info::init_order
|
||||
\brief A number that indicates the order in which the image was initialized
|
||||
respective to the other images in this team.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\typedef void (*image_info::init_routine)()
|
||||
\brief A pointer to the function used to initialize the image.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\typedef void (*image_info::term_routine)()
|
||||
\brief A pointer to the function used to clean up the image before unloading.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var dev_t image_info::device
|
||||
\brief The identifier of the device where the image file is located.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var ino_t image_info::node
|
||||
\brief The file node identifier of the image file.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var char image_info::name[MAXPATHLEN]
|
||||
\brief The path of the file from where the image was created.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var void* image_info::text
|
||||
\brief The address of the image's .text section.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var void* image_info::data
|
||||
\brief The address of the image's .data section.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var int32 image_info::text_size
|
||||
\brief The size of the image's .text section.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var int32 image_info::data_size
|
||||
\brief The size of the image's .data section.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var int32 image_info::api_version
|
||||
\brief The Haiku application programming interface version used by the image.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\var int32 image_info::abi
|
||||
\brief The Haiku application binary interface used by the image.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\name Flags for cache management
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\def B_FLUSH_DCACHE
|
||||
\brief Flushes a segment in the processor data cache.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def B_FLUSH_ICACHE
|
||||
\brief Flushes a segment in the processor instruction cache.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def B_INVALIDATE_DCACHE
|
||||
\brief Invalidates a segment in the processor data cache.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def B_INVALIDATE_ICACHE
|
||||
\brief Invalidates a segment in the processor instruction cache.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Image's symbol types
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\def B_SYMBOL_TYPE_DATA
|
||||
\brief The symbol type .data for variables.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def B_SYMBOL_TYPE_TEXT
|
||||
\brief The symbol type .text for executable instructions.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def B_SYMBOL_TYPE_ANY
|
||||
\brief If the binary format distinguishes between .data and .text section
|
||||
symbols, use either type. Or else, the format does not distinguish
|
||||
between symbols of both sections.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\name Symbol's address definitions
|
||||
*/
|
||||
|
||||
//! @{
|
||||
|
||||
/*!
|
||||
\def B_APP_IMAGE_SYMBOL
|
||||
\brief Defines a value that can be used instead of a pointer to a symbol
|
||||
in the program image.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def B_CURRENT_IMAGE_SYMBOL
|
||||
\brief Defines a pointer to a symbol in the caller's image.
|
||||
|
||||
\since Haiku R1
|
||||
*/
|
||||
|
||||
//! @}
|
||||
|
||||
|
||||
/*!
|
||||
\fn thread_id load_image(int32 argc, const char** argv, const char** environ)
|
||||
\brief Loads an executable image with its own team and returns the identifier
|
||||
of the main thread of the spawned team.
|
||||
|
||||
\param[in] argc The number of arguments in \a argv.
|
||||
\param[in] argv The list of argument parameters to pass to the image.
|
||||
\param[in] environ The list of environment variables to pass.
|
||||
|
||||
\return A thread_id of the spawned team (a positive number) or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn image_id load_add_on(const char* path)
|
||||
\brief Loads an add-on image from a \a path into the caller address space.
|
||||
|
||||
\param[in] path The path of the add-on's image file.
|
||||
|
||||
\return An image_id of the add-on or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t unload_add_on(image_id image)
|
||||
\brief Unloads an add-on \a image and releases its resources.
|
||||
|
||||
\param[in] image The image_id identifier of the add-on to unload.
|
||||
|
||||
\return \c B_OK if successful or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t get_image_symbol(image_id image, const char* name,
|
||||
int32 symbolType, void** _symbolLocation)
|
||||
\brief Searches for the symbol with \a name and \a symbolType in an \a image
|
||||
and saves a pointer to its address into \a _symbolLocation.
|
||||
|
||||
\param[in] image The image_id identifier of the image containing the symbol.
|
||||
\param[in] name The symbol name.
|
||||
\param[in] symbolType The symbol type:
|
||||
- ::B_SYMBOL_TYPE_DATA
|
||||
- ::B_SYMBOL_TYPE_TEXT
|
||||
- ::B_SYMBOL_TYPE_ANY
|
||||
\param[out] _symbolLocation A pointer to a pointer where to return the
|
||||
symbol address.
|
||||
|
||||
\return \c B_OK if the symbol was found or an error code.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn status_t get_nth_image_symbol(image_id image, int32 n, char* nameBuffer,
|
||||
int32* _nameLength, int32* _symbolType, void** _symbolLocation)
|
||||
\brief Searches for the \c n-th symbol in an \a image and returns its
|
||||
name, type and address.
|
||||
|
||||
\param[in] image The image_id identifier of the image to read the symbols from.
|
||||
\param[in] n The index of the symbol among all the symbols in the image.
|
||||
\param[out] nameBuffer A pre-allocated string buffer where to write
|
||||
the symbol name.
|
||||
\param[in out] _nameLength As an input, specifies the length of the
|
||||
string buffer. If an image was found, this is then set to the actual
|
||||
length of the symbol name. This allows to call this function again
|
||||
with a larger nameBuffer if its length was smaller than the symbol name.
|
||||
\param[out] _symbolType A pre-allocated int32 variable where to write the
|
||||
symbol type. This will be one of these:
|
||||
- ::B_SYMBOL_TYPE_DATA
|
||||
- ::B_SYMBOL_TYPE_TEXT
|
||||
- ::B_SYMBOL_TYPE_ANY
|
||||
\param[out] _symbolLocation A pointer to a pointer where to write the address
|
||||
of the symbol.
|
||||
|
||||
\retval B_OK A symbol was found and the information was saved to the parameters.
|
||||
\retval B_BAD_IMAGE_ID \a image does not point to an existing image.
|
||||
\retval B_BAD_INDEX The image does not contain a symbol at the \a n-th position.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\fn void clear_caches(void* address, size_t length, uint32 flags)
|
||||
\brief Clears or invalidates the data or instruction caches of the processor
|
||||
at a certain \a address.
|
||||
|
||||
\param address The address where the section of the cache to flush or
|
||||
invalidate starts.
|
||||
\param[in] length The number of bytes of the section to flush or invalidate.
|
||||
\param[in] flags Configuration flags, that is of these:
|
||||
- ::B_FLUSH_DCACHE
|
||||
- ::B_FLUSH_ICACHE
|
||||
- ::B_INVALIDATE_DCACHE
|
||||
- ::B_INVALIDATE_ICACHE
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def get_image_info(image, info)
|
||||
\brief Retrieves information about a specific \a image into \a info.
|
||||
|
||||
\param[in] image An image_id containing the identifier for the target image
|
||||
to get the information from.
|
||||
\param[out] info A pointer to an image_info instance where to write the
|
||||
information.
|
||||
|
||||
\retval B_OK The \a image was found and the information was written into
|
||||
\a info.
|
||||
\retval B_BAD_VALUE The size of the object pointed by \a info is invalid.
|
||||
\retval B_ENTRY_NOT_FOUND The \a image was not found.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
\def get_next_image_info(team_id team, cookie, info)
|
||||
\brief Iterates through the list of images in a \a team to get an image_info
|
||||
with information of the queried image.
|
||||
|
||||
For example, the following snippet shows how to iterate through every image
|
||||
in a team:
|
||||
|
||||
\code{.cpp}
|
||||
team_id team = ...;
|
||||
int32 cookie = 0;
|
||||
image_info info = {};
|
||||
while(get_next_image_info(team, &cookie, &info) == B_OK) {
|
||||
printf("Image [%d]: identifier=%d\n", cookie, info.id);
|
||||
// do anything else...
|
||||
}
|
||||
\endcode
|
||||
|
||||
\param[in] team A team_id with the identifier of the team to analyze.
|
||||
\param[out] cookie A pointer to an int32 variable used to keep track of the
|
||||
current position in team's list of images. It must be initialized to
|
||||
\c 0 beforehand.
|
||||
\param[out] info A pointer to an image_info structure where to write the
|
||||
information about the currently iterated image.
|
||||
|
||||
\retval B_OK An image of \a team was found and the data about it was written
|
||||
into \a info.
|
||||
\retval B_BAD_VALUE The size of the object pointed by \a info is invalid.
|
||||
\retval B_BAD_TEAM_ID The \a team identifier is invalid, does not point to
|
||||
a running team.
|
||||
\retval B_ENTRY_NOT_FOUND There are no more images to visit from this \a team.
|
||||
|
||||
\since BeOS R3
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user