rtems/rtl/rap.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /*
0004  *  COPYRIGHT (c) 2013, 2018 Chris Johns <chrisj@rtems.org>
0005  *
0006  * Redistribution and use in source and binary forms, with or without
0007  * modification, are permitted provided that the following conditions
0008  * are met:
0009  * 1. Redistributions of source code must retain the above copyright
0010  *    notice, this list of conditions and the following disclaimer.
0011  * 2. Redistributions in binary form must reproduce the above copyright
0012  *    notice, this list of conditions and the following disclaimer in the
0013  *    documentation and/or other materials provided with the distribution.
0014  *
0015  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0016  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0017  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0018  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0019  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0020  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0021  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0022  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0023  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0024  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0025  * POSSIBILITY OF SUCH DAMAGE.
0026  */
0027 /**
0028  * @file
0029  *
0030  * @ingroup rtems_rap
0031  *
0032  * @brief RTEMS Application Loader
0033  *
0034  * This is the RTEMS Application loader for files in the RAP format.
0035  */
0036
0037 #if !defined (_RAP_H_)
0038 #define _RAP_H_
0039
0040 #include <rtems.h>
0041 #include <rtems/chain.h>
0042
0043 #ifdef __cplusplus
0044 extern "C" {
0045 #endif /* __cplusplus */
0046
0047 /**
0048  * @defgroup rtems_rap RTEMS Application Loader
0049  *
0050  * @ingroup RTEMSAPI
0051  *
0052  * The module implements an application loader for files in the RAP format. The
0053  * RAP format is:
0054  *
0055  *   <header>
0056  *   <compressed container>
0057  *
0058  * The compressed container is a stream of ELF relocatable object files.
0059  *
0060  *  TBD.
0061  */
0062
0063 /**
0064  * The module iterator handle.
0065  */
0066 typedef bool (*rtems_rap_iterator) (void* handle);
0067
0068 /**
0069  * Load an application.
0070  *
0071  * @param name The name of the application file.
0072  * @return bool True if the module loads else an error.
0073  */
0074 bool rtems_rap_load (const char* name, int mode, int argc, const char* argv[]);
0075
0076 /**
0077  * Unload an application.
0078  *
0079  * @param obj The application descriptor.
0080  * @retval true The application file has been unloaded.
0081  * @retval false The application could not be unloaded.
0082  */
0083 bool rtems_rap_unload (const char* name);
0084
0085 /**
0086  * Find the application handle given a file name.
0087  *
0088  * @param name The name of the application file. It can be absolute or
0089  *             relative. Relative names can the basename with an extension.
0090  * @retval NULL No application file with that name found.
0091  * @return void* The application descriptor.
0092  */
0093 void* rtems_rap_find (const char* name);
0094
0095 /**
0096  * Run an iterator over the modules calling the iterator function.
0097  *
0098  * @param iterator The iterator function.
0099  * @retval true The iterator function returned did not return false.
0100  * @retval false The iterator function returned false..
0101  */
0102 bool rtems_rap_iterate (rtems_rap_iterator iterator);
0103
0104 /**
0105  * Return the name of the module given a handle.
0106  *
0107  * @param handle The module handle.
0108  * @return const char* The name of the module if the handle is valid else it
0109  *                     is NULL.
0110  */
0111 const char* rtems_rap_name (void* handle);
0112
0113 /**
0114  * Return the DL handle used to load the module given the RAP handle.
0115  *
0116  * @param handle The module handle.
0117  * @return void* The DL handle returned by the dlopen call.
0118  */
0119 void* rtems_rap_dl_handle (void* handle);
0120
0121 /**
0122  * Get the last error message clearing it. This call is not thread safe is
0123  * multiple threads are loading object files at the same time. This call
0124  * follows the model provided by the dlopen family of calls.
0125  *
0126  * @param message Pointer to a buffer to copy the message into.
0127  * @param max_message The maximum message that can be copied.
0128  * @return int The last error number.
0129  */
0130 int rtems_rap_get_error (char* message, size_t max_message);
0131
0132 #ifdef __cplusplus
0133 }
0134 #endif /* __cplusplus */
0135
0136 #endif