diff options
Diffstat (limited to 'cpukit/include')
225 files changed, 5599 insertions, 5024 deletions
diff --git a/cpukit/include/dev/can/can-msg.h b/cpukit/include/dev/can/can-msg.h deleted file mode 100644 index 9863e14d84..0000000000 --- a/cpukit/include/dev/can/can-msg.h +++ /dev/null @@ -1,105 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/** - * @file - * - * @ingroup CANBus - * - * @brief Controller Area Network (CAN) Bus Implementation - * - */ - -/* - * Copyright (C) 2022 Prashanth S <fishesprashanth@gmail.com> - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#ifndef _DEV_CAN_CAN_MSG_H -#define _DEV_CAN_CAN_MSG_H - -/** - * @defgroup Controller Area Network (CAN) Driver - * - * @ingroup RTEMSDeviceDrivers - * - * @brief Controller Area Network (CAN) bus and device driver support. - * - * @{ - */ - -/** - * @defgroup CANBus CAN Bus Driver - * - * @ingroup CAN - * - * @{ - */ - -/** - * @brief CAN message size - */ -#define CAN_MSG_MAX_SIZE (8u) - -/** - * @brief Number of CAN tx buffers - */ -#define CAN_TX_BUF_COUNT (10u) - -/** - * @brief Number of CAN rx buffers - */ -#define CAN_RX_BUF_COUNT (2u) - -#define CAN_MSGLEN(msg) (sizeof(struct can_msg) - (CAN_MSG_MAX_SIZE - msg->len)) - -/** - * @brief CAN message structure. - */ -struct can_msg { - /** - * @brief CAN message id. - */ - uint32_t id; - /** - * @brief CAN message timestamp. - */ - uint32_t timestamp; - /** - * @brief CAN message flags RTR | BRS | EXT. - */ - uint16_t flags; - /** - * @brief CAN message length. - */ - uint16_t len; - /** - * @brief CAN message. - */ - uint8_t data[CAN_MSG_MAX_SIZE]; -}; - -/** @} */ /* end of CAN message */ - -/** @} */ - -#endif /* _DEV_CAN_CAN_MSG_H */ diff --git a/cpukit/include/dev/can/can.h b/cpukit/include/dev/can/can.h deleted file mode 100644 index 9e55395039..0000000000 --- a/cpukit/include/dev/can/can.h +++ /dev/null @@ -1,284 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/** - * @file - * - * @ingroup CANBus - * - * @brief Controller Area Network (CAN) Bus Implementation - * - */ - -/* - * Copyright (C) 2022 Prashanth S (fishesprashanth@gmail.com) - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#ifndef _DEV_CAN_CAN_H -#define _DEV_CAN_CAN_H - -#include <rtems/imfs.h> -#include <rtems/thread.h> -#include <semaphore.h> - -#include <string.h> -#include <stdlib.h> -#include <stdio.h> - -#include <dev/can/can-msg.h> - -#define DEBUG(str, ...) \ - do { \ - printf("CAN: %s:%d ID: %08X ", __FILE__, __LINE__, rtems_task_self()); \ - printf(str, ##__VA_ARGS__); \ - } while (false); - -#define CAN_DEBUG(str, ...) DEBUG(str, ##__VA_ARGS__) -#define CAN_DEBUG_BUF(str, ...) CAN_DEBUG(str, ##__VA_ARGS__) -#define CAN_DEBUG_ISR(str, ...) CAN_DEBUG(str, ##__VA_ARGS__) -#define CAN_DEBUG_LOCK(str, ...) CAN_DEBUG(str, ##__VA_ARGS__) -#define CAN_DEBUG_RX(str, ...) CAN_DEBUG(str, ##__VA_ARGS__) -#define CAN_DEBUG_TX(str, ...) CAN_DEBUG(str, ##__VA_ARGS__) -#define CAN_DEBUG_REG(str, ...) //CAN_DEBUG(str, ##__VA_ARGS__) -#define CAN_ERR(str, ...) DEBUG(str, ##__VA_ARGS__) - -#define CAN_MSG_LEN(msg) ((char *)(&((struct can_msg *)msg)->data[(uint16_t)((struct can_msg *)msg)->len]) - (char *)(msg)) - -/* Maximum Bus Reg (255) */ -#define CAN_BUS_REG_MAX (255) - -/** - * @defgroup Controller Area Network (CAN) Driver - * - * @ingroup RTEMSDeviceDrivers - * - * @brief Controller Area Network (CAN) bus and device driver support. - * - * @{ - */ - -/** - * @defgroup CANBus CAN Bus Driver - * - * @ingroup CAN - * - * @{ - */ - -/** - * @brief CAN tx fifo data structure. - */ -struct ring_buf { - /** - * @brief Pointer to array of can_msg structure. - */ - struct can_msg *pbuf; - /** - * @brief Index of the next free buffer. - */ - uint32_t head; - /** - * @brief Index of the produced buffer. - */ - uint32_t tail; - /** - * @brief Number of empty buffers. - */ - uint32_t empty_count; -}; - -/** - * @brief CAN Controller device specific operations. - * These function pointers are initialized by the CAN device driver while - * registering (can_bus_register). - */ -typedef struct can_dev_ops { - /** - * @brief Transfers CAN messages to device fifo. - * - * @param[in] priv device control structure. - * @param[in] msg can_msg message structure. - * - * @retval 0 Successful operation. - * @retval >0 error number in case of an error. - */ - int32_t (*dev_tx)(void *priv, struct can_msg *msg); - /** - * @brief Check device is ready to transfer a CAN message - * - * @param[in] priv device control structure. - * - * @retval true device ready. - * @retval false device not ready. - */ - bool (*dev_tx_ready)(void *priv); - /** - * @brief Enable/Disable CAN interrupts. - * - * @param[in] priv device control structure. - * @param[in] flag true/false to Enable/Disable CAN interrupts. - * - */ - void (*dev_int)(void *priv, bool flag); - /** - * @brief CAN device specific I/O controls. - * - * @param[in] priv device control structure. - * @param[in] buffer This depends on the cmd. - * @param[in] cmd Device specific I/O commands. - * - * @retval 0 Depends on the cmd. - */ - int32_t (*dev_ioctl)(void *priv, void *buffer, size_t cmd); -} can_dev_ops; - -/** - * @name CAN bus control - * - * @{ - */ - -/** - * @brief Obtains the bus. - * - * This command has no argument. - */ -typedef struct can_bus { - /** - * @brief Device specific control. - */ - void *priv; - /** - * @brief Device controller index. - */ - uint8_t index; - /** - * @brief Device specific operations. - */ - struct can_dev_ops *can_dev_ops; - /** - * @brief tx fifo. - */ - struct ring_buf tx_fifo; - /** - * @brief Counting semaphore id (for fifo sync). - */ - rtems_id tx_fifo_sem_id; - - /* FIXME: Using only one CAN msg buffer, Should create a ring buffer */ - /** - * @brief rx fifo. - */ - struct can_msg can_rx_msg; - /** - * @brief Mutex to handle bus concurrency. - */ - rtems_mutex mutex; - /** - * @brief Destroys the bus. - * - * @param[in] bus control structure. - */ - void (*destroy)(struct can_bus *bus); -#ifdef CAN_DEBUG_LOCK - - /** - * @brief For debugging semaphore obtain/release. - */ - int sem_count; - -#endif /* CAN_DEBUG_LOCK */ - -} can_bus; - -/** @} */ - -/** - * @brief Register a CAN node with the CAN bus driver. - * - * @param[in] bus bus control structure. - * @param[in] bus_path path of device node. - * - * @retval >=0 rtems status. - */ -rtems_status_code can_bus_register(can_bus *bus, const char *bus_path); - -/** - * @brief Allocate and initilaize bus control structure. - * - * @param[in] size Size of the bus control structure. - * - * @retval NULL No memory available. - * @retval Address Pointer to the allocated bus control structure. - */ -can_bus *can_bus_alloc_and_init(size_t size); - -/** - * @brief initilaize bus control structure. - * - * @param[in] bus bus control structure. - * - * @retval 0 success. - * @retval >0 error number. - */ -int can_bus_init(can_bus *bus); - -/** - * @brief Initiates CAN message transfer. - * - * Should be called with CAN interrupt disabled. - * - * @param[in] bus Bus control structure. - * - * @retval 0 success. - * @retval >0 error number. - */ -int can_tx_done(struct can_bus *bus); - -/** - * @brief Sends the received CAN message to the application. - * - * Should be called by the device when CAN message should be sent to applicaiton. - * Should be called only with CAN interrupts disabled. - * - * @param[in] bus bus control structure. - * @param[in] msg can_msg structure. - * - * @retval 0 success. - * @retval >0 error number. - */ -int can_receive(struct can_bus *bus, struct can_msg *msg); - -/** - * @brief Prints the can_msg values pointed by msg. - * - * @param[in] msg can_msg structure. - * - */ -void can_print_msg(struct can_msg const *msg); - -/** @} */ /* end of CAN device driver */ - -/** @} */ - -#endif /* _DEV_CAN_CAN_H */ diff --git a/cpukit/include/dev/can/canqueueimpl.h b/cpukit/include/dev/can/canqueueimpl.h deleted file mode 100644 index ef0d56fe31..0000000000 --- a/cpukit/include/dev/can/canqueueimpl.h +++ /dev/null @@ -1,231 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/** - * @file - * - * @ingroup CANBus - * - * @brief Controller Area Network (CAN) Bus Implementation - * - */ - -/* - * Copyright (C) 2022 Prashanth S <fishesprashanth@gmail.com> - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#ifndef _DEV_CAN_CAN_QUEUE_H -#define _DEV_CAN_CAN_QUEUE_H - -#include <rtems/imfs.h> -#include <rtems/thread.h> - -#include <string.h> -#include <stdlib.h> -#include <stdio.h> - -#include <dev/can/can-msg.h> -#include <dev/can/can.h> - -/** - * @defgroup Controller Area Network (CAN) Driver - * - * @ingroup RTEMSDeviceDrivers - * - * @brief Controller Area Network (CAN) bus and device driver support. - * - * @{ - */ - -/** - * @defgroup CANBus CAN Bus Driver - * - * @ingroup CAN - * - * @{ - */ - -/** - * @brief Create CAN tx buffers. - * - * @param[in] bus Bus control structure. - * - * @retval 0 Successful operation. - * @retval >0 error number in case of an error. - */ -static rtems_status_code can_bus_create_tx_buffers(struct can_bus *bus); - -/** - * @brief Free CAN tx buffers. - * - * @param[in] bus Bus control structure. - * - */ -static void can_bus_free_tx_buffers(struct can_bus *bus); - -/** - * @brief Check for atleast one empty CAN tx buffer. - * - * @param[in] bus Bus control structure. - * - * @retval true If atleast one CAN buffer is empty. - * @retval false If no CAN buffer is empty. - */ -static bool can_bus_tx_buf_is_empty(struct can_bus *bus); - -/** - * @brief Get a produced tx buffer to transmit from the tx fifo. - * - * @param[in] bus Bus control structure. - * - * @retval can_msg Pointer to can_msg structure buffer. - * @retval NULL If no can_msg buffer. - */ -static struct can_msg *can_bus_tx_get_data_buf(struct can_bus *bus); - -/** - * @brief Get a empty tx buffer. - * - * @param[in] bus Bus control structure. - * - * @retval can_msg Pointer to can_msg structure buffer. - * @retval NULL If no empty can_msg buffer. - */ -static struct can_msg *can_bus_tx_get_empty_buf(struct can_bus *bus); - -/** - * @brief Creates tx buffers for the CAN bus driver. - * - * @param[in] bus Bus control structure. - * - * @retval rtems_status_code - */ -static rtems_status_code can_bus_create_tx_buffers(struct can_bus *bus) -{ - bus->tx_fifo.pbuf = (struct can_msg *)malloc(CAN_TX_BUF_COUNT * - sizeof(struct can_msg)); - if (bus->tx_fifo.pbuf == NULL) { - CAN_ERR("can_create_tx_buffers: malloc failed\n"); - return RTEMS_NO_MEMORY; - } - - bus->tx_fifo.empty_count = CAN_TX_BUF_COUNT; - - return RTEMS_SUCCESSFUL; -} - -/** - * @brief Free tx buffers for the CAN bus driver. - * - * @param[in] bus Bus control structure. - * - */ -static void can_bus_free_tx_buffers(struct can_bus *bus) -{ - free(bus->tx_fifo.pbuf); -} - -/** - * @brief Check if there is atleast one tx buffer in the CAN - * bus driver. - * - * @param[in] bus Bus control structure. - * - * @retval true - If there is at least one free tx buffer. - * false - If there is no free tx buffer. - */ -static bool can_bus_tx_buf_is_empty(struct can_bus *bus) -{ - if (bus->tx_fifo.empty_count == 0) { - return false; - } - - return true; -} - -/** - * @brief To get a can_msg tx buf which contains valid data to send in - * in the CAN bus. - * - * Note: freeing the returned data buf is done in the same function, - * So the returned buffer should be sent before releasing the - * lock acquired while calling this function. - * - * @param[in] bus Bus control structure. - * - * @retval *can_msg - If there is atleast one tx buffer to send in the CAN bus. - * NULL - If there is no valid tx buffer. - */ -static struct can_msg *can_bus_tx_get_data_buf(struct can_bus *bus) -{ - struct can_msg *msg = NULL; - - if (bus->tx_fifo.empty_count == CAN_TX_BUF_COUNT || - bus->tx_fifo.tail >= CAN_TX_BUF_COUNT) { - CAN_DEBUG_BUF("can_bus_tx_get_data_buf: All buffers are empty\n"); - return NULL; - } - - msg = &bus->tx_fifo.pbuf[bus->tx_fifo.tail]; - bus->tx_fifo.empty_count++; - bus->tx_fifo.tail = (bus->tx_fifo.tail + 1) % CAN_TX_BUF_COUNT; - - return msg; -} - -/** - * @brief To get a can_msg tx buf which is empty (contains no valid data). - * - * Note: marking the returned buf valid is done in the same function - * So a valid CAN message should be copied to the returned buffer before - * releasing the lock acquired while calling this function. - * - * @param[in] bus Bus control structure. - * - * @retval *can_msg - If there is atleast one empty tx buffer. - * NULL - If there is no empty tx buffer. - */ -static struct can_msg *can_bus_tx_get_empty_buf(struct can_bus *bus) -{ - struct can_msg *msg = NULL; - - /* Check whether there is a empty CAN msg buffer */ - if (can_bus_tx_buf_is_empty(bus) == false) { - CAN_DEBUG_BUF("can_bus_tx_get_empty_buf: No empty buffer\n"); - return NULL; - } - - bus->tx_fifo.empty_count--; - - /* tx_fifo.head always points to a empty buffer if there is atleast one */ - msg = &bus->tx_fifo.pbuf[bus->tx_fifo.head]; - bus->tx_fifo.head = (bus->tx_fifo.head + 1) % CAN_TX_BUF_COUNT; - - return msg; -} - -/** @} */ /* end of CAN device driver */ - -/** @} */ - -#endif /*_DEV_CAN_CAN_QUEUE_H */ diff --git a/cpukit/include/dev/flash/flashdev.h b/cpukit/include/dev/flash/flashdev.h new file mode 100644 index 0000000000..6759357206 --- /dev/null +++ b/cpukit/include/dev/flash/flashdev.h @@ -0,0 +1,468 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup Flash + * + * @brief Generic Flash API + */ + +/* + * Copyright (C) 2023 Aaron Nyholm + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef _DEV_FLASHDEV_H +#define _DEV_FLASHDEV_H + +#include <rtems/thread.h> +#include <sys/types.h> + +#ifdef __cplusplus +extern "C" { +#endif + + +typedef struct rtems_flashdev rtems_flashdev; + +/** + * @defgroup Generic Flash API + * + * @ingroup RTEMSDeviceDrivers + * + * @brief Generic Flash API to wrap specific device drivers. + * + * @{ + */ + +/* IOCTL Calls */ + +/** + * @brief Obtains the flash device. + * + * This command has no argument. + */ +#define RTEMS_FLASHDEV_IOCTL_OBTAIN 0 +/** + * @brief Releases the flash device. + * + * This command has no argument. + */ +#define RTEMS_FLASHDEV_IOCTL_RELEASE 1 +/** + * @brief Returns the JEDEC ID of the flash device. This IOCTL call + * is informational only. + * + * @param[out] jedec_id Pointer to uint32_t in which the JEDEC ID is + * returned in. + */ +#define RTEMS_FLASHDEV_IOCTL_JEDEC_ID 2 +/** + * @brief Erases flash device. + * + * @param[in] erase_args Pointer to rtems_flashdev_region struct + * containing offset and size of erase to be performed. + */ +#define RTEMS_FLASHDEV_IOCTL_ERASE 3 +/** + * @brief Set a region that limits read, write and erase calls to within it. + * Regions are file descriptor specific and limited to a single region per + * file descriptor and 32 regions total per flash device. Regions can be + * changed or updated by calling this IOCTL again. + * + * @param[in] region Pointer to rtems_flashdev_region struct containing + * base and length of defined region. + */ +#define RTEMS_FLASHDEV_IOCTL_REGION_SET 4 +/** + * @brief Removes the set region on the file descriptor. + * + * This command has no argument. + */ +#define RTEMS_FLASHDEV_IOCTL_REGION_UNSET 5 +/** + * @brief Returns the type of flash device (e.g. NOR or NAND). + * + * @param[out] flash_type Pointer to integer which is set to the flash + * type macro value. + */ +#define RTEMS_FLASHDEV_IOCTL_TYPE 6 + +/** + * @brief Get the size and address of flash page at given offset + * + * The offset ignores the region limiting. To find page of region + * limited offset add the base of the region to the desired offset. + * + * @param[in,out] rtems_flashdev_ioctl_page_info arg Pointer to struct + * with offset and space for return values. + */ +#define RTEMS_FLASHDEV_IOCTL_PAGEINFO_BY_OFFSET 7 + +/** + * @brief Get the size and address of nth flash page where n is index passed in. + * + * The index ignores the region limiting. + * + * @param[in,out] rtems_flashdev_ioctl_page_info arg Pointer to struct + * with index and space for return values. + */ +#define RTEMS_FLASHDEV_IOCTL_PAGEINFO_BY_INDEX 8 + +/** + * @brief Get the number of pages in flash device. + * + * @param[out] count Integer containing the number of pages. + */ +#define RTEMS_FLASHDEV_IOCTL_PAGE_COUNT 9 + +/** + * @brief Get the minimum write size supported by the driver. + * + * @param[out] count Integer containing the minimum write size. + */ +#define RTEMS_FLASHDEV_IOCTL_WRITE_BLOCK_SIZE 10 + +/** + * @brief The maximum number of region limited file descriptors + * allowed to be open at once. + */ +#define RTEMS_FLASHDEV_MAX_REGIONS 32 + +/** + * @brief Enum for flash type returned from IOCTL call. + */ +typedef enum rtems_flashdev_flash_type { + /** + * @brief The flash device is NOR flash. + **/ + RTEMS_FLASHDEV_NOR, + /** + * @brief The flash device is NAND flash. + */ + RTEMS_FLASHDEV_NAND +} rtems_flashdev_flash_type; + +/** + * @brief General definition for on flash device. + */ +typedef struct rtems_flashdev_region { + /** + * @brief Base of region. + */ + off_t offset; + /** + * @brief Length of region. + */ + size_t size; +} rtems_flashdev_region; + +/** + * @brief Struct holding region definitions + */ +typedef struct rtems_flashdev_region_table { + /** + * @brief The maximum regions that can be defined at once. + */ + int max_regions; + + /** + * @brief Pointer to array of rtems_flashdev_region of length + * max_regions + */ + rtems_flashdev_region* regions; + + /** + * @brief Array of uint32_t acting as bit allocator + * for regions array. + */ + uint32_t *bit_allocator; +} rtems_flashdev_region_table; + +/** + * @brief Page information returned from IOCTL calls. + */ +typedef struct rtems_flashdev_ioctl_page_info { + /** + * @brief Offset or index to find page at. + */ + off_t location; + + /** + * @brief Information returned about the page. Including the + * base offset and size of page. + */ + rtems_flashdev_region page_info; +} rtems_flashdev_ioctl_page_info; + +/** + * @brief Flash device. + */ +struct rtems_flashdev { + /** + * @brief Call to the device driver to read the flash device. + * + * @param[in] flash Pointer to flash device. + * @param[in] offset Address to read from. + * @param[in] count Number of bytes to read. + * @param[out] buffer Buffer for data to be read into. + * + * @retval 0 Successful operation. + * @retval 1 Failed operation. + */ + int ( *read )( + rtems_flashdev *flash, + uintptr_t offset, + size_t count, + void *buffer + ); + + /** + * @brief Call to the device driver to write to the flash device. + * + * @param[in] flash Pointer to flash device. + * @param[in] offset Address to write to. + * @param[in] count Number of bytes to read. + * @param[in] buffer Buffer for data to be written from. + * + * @retval 0 Successful operation. + * @retval 1 Failed operation. + */ + int ( *write )( + rtems_flashdev *flash, + uintptr_t offset, + size_t count, + const void *buffer + ); + + /** + * @brief Call to the device driver to erase the flash device. + * + * @param[in] flash Pointer to flash device. + * @param[in] offset Address to erase at. + * @param[in] count Number of bytes to erase. + * + * @retval 0 Successful operation. + * @retval 1 Failed operation. + */ + int ( *erase )( + rtems_flashdev *flash, + uintptr_t offset, + size_t count + ); + + /** + * @brief Call to the device driver to return the JEDEC ID. + * + * @param[in] flash The flash device. + * + * @retval JEDEC ID. + */ + uint32_t ( *jedec_id )( + rtems_flashdev *flash + ); + + /** + * @brief Call to the device driver to return the flash type. + * + * @param[in] flash The flash device. + * @param[out] type The type of flash device. + * + * @retval 0 Success + * @retbal Other Failure + */ + int ( *flash_type )( + rtems_flashdev *flash, + rtems_flashdev_flash_type *type + ); + + /** + * @brief Call to device driver to get size and offset of page at + * given offset. + * + * @param[in] flash The flash device + * @param[in] search_offset The offset of the page which info is to be + * returned. + * @param[out] page_offset The offset of the start of the page + * @param[out] page_size The size of the page + * + * @retval 0 Success. + * @retval non-zero Failed. + */ + int ( *page_info_by_offset )( + rtems_flashdev *flash, + off_t search_offset, + off_t *page_offset, + size_t *page_size + ); + + /** + * @brief Call to device driver to get size and offset of page at + * given index. + * + * @param[in] flash The flash device + * @param[in] search_index The index of the page which info is to be returned. + * @param[out] page_offset The offset of the start of the page + * @param[out] page_size The size of the page + * + * @retval 0 Success. + * @retval non-zero Failed. + */ + int ( *page_info_by_index )( + rtems_flashdev *flashdev, + off_t search_index, + off_t *page_offset, + size_t *page_size + ); + + /** + * @brief Call to device driver to return the number of pages on the flash + * device. + * + * @param[out] page_count The number of pages on the flash device. + * + * @retval 0 Success. + * @retval non-zero Failed. + */ + int ( *page_count )( + rtems_flashdev *flashdev, + int *page_count + ); + + /** + * @brief Call to device driver to return the minimum write size of the + * flash device. + * + * @param[out] write_block_size The minimum write size of the flash device. + * + * @retval 0 Success. + * @retval non-zero Failed. + */ + int ( *write_block_size )( + rtems_flashdev *flashdev, + size_t *write_block_size + ); + + /** + * @brief Destroys the flash device. + * + * @param[in] flash Pointer to flash device. + */ + void ( *destroy )( + rtems_flashdev *flashdev + ); + + /** + * @brief Pointer to device driver. + */ + void *driver; + + /** + * @brief Mutex to protect the flash device access. + */ + rtems_recursive_mutex mutex; + + /** + * @brief Region table defining size and memory for region allocations + */ + rtems_flashdev_region_table *region_table; +}; + +/** + * @brief Allocate and initialize the flash device. + * + * After a successful allocation and initialization of the flash device + * it must be destroyed via rtems_flashdev_destroy_and_free(). + * + * @param[in] size The number of bytes to allocate. + * + * @retval NULL Failed to set up flash device. + * @retval non-NULL The new flash device. + */ +rtems_flashdev *rtems_flashdev_alloc_and_init( + size_t size +); + +/** + * @brief Initialize the flash device. + * + * After a successful initialization of the flash device it must be + * destroyed via rtems_flashdev_destory(). + * + * After initialization and before registration read, write, erase, jedec_id + * and flash_type functions need to be set in the flashdev. + * + * @param[in] flash The flash device to initialize. + * + * @retval 1 Failed to set up flash device. + * @retval 0 Successful set up of flash device. + */ +int rtems_flashdev_init( + rtems_flashdev *flash +); + +/** + * @brief Register the flash device. + * + * This function always claims ownership of the flash device. + * + * After initialization and before registration read, write, erase, jedec_id + * and flash_type functions need to be set in the flashdev. + * + * @param[in] flash The flash device. + * @param[in] flash_path The path to the flash device file. + * + * @retval 0 Successful operation. + * @retval non-zero Failed operation. + */ +int rtems_flashdev_register( + rtems_flashdev *flash, + const char *flash_path +); + +/** + * @brief Destroys the flash device. + * + * @param[in] flash The flash device. + */ +void rtems_flashdev_destroy( + rtems_flashdev *flash +); + +/** + * @brief Destroys the flash device and frees its memory. + * + * @param[in] flash The flash device. + */ +void rtems_flashdev_destroy_and_free( + rtems_flashdev *flash +); + +#ifdef __cplusplus +} +#endif + +/** @} */ + +#endif /* _DEV_FLASHDEV_H */ diff --git a/cpukit/include/dev/i2c/eeprom.h b/cpukit/include/dev/i2c/eeprom.h index 9632eff32d..1179853a7e 100644 --- a/cpukit/include/dev/i2c/eeprom.h +++ b/cpukit/include/dev/i2c/eeprom.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/dev/i2c/gpio-nxp-pca9535.h b/cpukit/include/dev/i2c/gpio-nxp-pca9535.h index de01bcfbee..c8dec3ad85 100644 --- a/cpukit/include/dev/i2c/gpio-nxp-pca9535.h +++ b/cpukit/include/dev/i2c/gpio-nxp-pca9535.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/dev/i2c/i2c.h b/cpukit/include/dev/i2c/i2c.h index 7094911c9c..82cc11130c 100644 --- a/cpukit/include/dev/i2c/i2c.h +++ b/cpukit/include/dev/i2c/i2c.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2014, 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/dev/i2c/sensor-lm75a.h b/cpukit/include/dev/i2c/sensor-lm75a.h index ca9c9f3924..c963e71e65 100644 --- a/cpukit/include/dev/i2c/sensor-lm75a.h +++ b/cpukit/include/dev/i2c/sensor-lm75a.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2017 embedded brains GmbH. All rights reserved. + * Copyright (c) 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/dev/i2c/switch-nxp-pca9548a.h b/cpukit/include/dev/i2c/switch-nxp-pca9548a.h index d087704feb..4c70c0d9a6 100644 --- a/cpukit/include/dev/i2c/switch-nxp-pca9548a.h +++ b/cpukit/include/dev/i2c/switch-nxp-pca9548a.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/dev/serial/sc16is752.h b/cpukit/include/dev/serial/sc16is752.h index 78a9ef6278..27fdd2fe0b 100644 --- a/cpukit/include/dev/serial/sc16is752.h +++ b/cpukit/include/dev/serial/sc16is752.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: BSD-2-Clause */ /* - * Copyright (c) 2016 embedded brains GmbH. All rights reserved. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/dev/spi/spi.h b/cpukit/include/dev/spi/spi.h index 6d44db09d8..e08a4f697b 100644 --- a/cpukit/include/dev/spi/spi.h +++ b/cpukit/include/dev/spi/spi.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2016, 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2016, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/endian.h b/cpukit/include/endian.h index 84e9e74b75..76906e9ce0 100644 --- a/cpukit/include/endian.h +++ b/cpukit/include/endian.h @@ -7,7 +7,7 @@ */ /* - * Copyright (C) 2017 embedded brains Gmbh (http://www.embedded-brains.de) + * Copyright (C) 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/linux/i2c-dev.h b/cpukit/include/linux/i2c-dev.h index 64b52da22b..dec660f584 100644 --- a/cpukit/include/linux/i2c-dev.h +++ b/cpukit/include/linux/i2c-dev.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/linux/i2c.h b/cpukit/include/linux/i2c.h index b974f0c0db..ff51ab5cc9 100644 --- a/cpukit/include/linux/i2c.h +++ b/cpukit/include/linux/i2c.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/linux/rbtree.h b/cpukit/include/linux/rbtree.h index fc6caad582..2bd1e2bbf4 100644 --- a/cpukit/include/linux/rbtree.h +++ b/cpukit/include/linux/rbtree.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: BSD-2-Clause */ /* - * Copyright (c) 2015 embedded brains GmbH. All rights reserved. + * Copyright (c) 2015 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/linux/spi/spidev.h b/cpukit/include/linux/spi/spidev.h index 4f5e59edfc..c4f8957b94 100644 --- a/cpukit/include/linux/spi/spidev.h +++ b/cpukit/include/linux/spi/spidev.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2016 embedded brains GmbH. All rights reserved. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/machine/_kernel_cpuset.h b/cpukit/include/machine/_kernel_cpuset.h index 19c1a3e504..1164494b9e 100644 --- a/cpukit/include/machine/_kernel_cpuset.h +++ b/cpukit/include/machine/_kernel_cpuset.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides CPU set definitions for the kernel space * (_KERNEL is defined before including <sys/cpuset.h>). */ /* - * Copyright (C) 2016 embedded brains GmbH + * Copyright (C) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/machine/_kernel_in.h b/cpukit/include/machine/_kernel_in.h index b33283353a..1c7ad25565 100644 --- a/cpukit/include/machine/_kernel_in.h +++ b/cpukit/include/machine/_kernel_in.h @@ -35,13 +35,13 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides IPv4 definitions for the kernel space * (_KERNEL is defined before including <netinet/in.h>). */ -#if !defined(_NETINET_IN_H_) || !defined(_KERNEL) -#error "must be included via <netinet/in.h> in kernel space" -#endif +#if defined(_NETINET_IN_H_) && defined(_KERNEL) struct ifnet; struct mbuf; /* forward declarations for Standard C */ struct in_ifaddr; @@ -71,3 +71,7 @@ void in_ifdetach(struct ifnet *); #define satosin(sa) ((struct sockaddr_in *)(sa)) #define sintosa(sin) ((struct sockaddr *)(sin)) #define ifatoia(ifa) ((struct in_ifaddr *)(ifa)) + +#else /* !_NETINET_IN_H_ || !_KERNEL */ +#error "must be included via <netinet/in.h> in kernel space" +#endif /* _NETINET_IN_H_ && _KERNEL */ diff --git a/cpukit/include/machine/_kernel_in6.h b/cpukit/include/machine/_kernel_in6.h index 7ec695bd6d..e198e5d37a 100644 --- a/cpukit/include/machine/_kernel_in6.h +++ b/cpukit/include/machine/_kernel_in6.h @@ -34,13 +34,13 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides IPv6 definitions for the kernel space * (_KERNEL is defined before including <netinet6/in6.h>). */ -#if !defined(_NETINET6_IN6_H_) || !defined(_KERNEL) -#error "must be included via <netinet6/in6.h> in kernel space" -#endif +#if defined(_NETINET6_IN6_H_) && defined(_KERNEL) /* XXX nonstandard */ #define s6_addr8 __u6_addr.__u6_addr8 @@ -187,3 +187,7 @@ extern void addrsel_policy_init(void); #define satosin6(sa) ((struct sockaddr_in6 *)(sa)) #define sin6tosa(sin6) ((struct sockaddr *)(sin6)) #define ifatoia6(ifa) ((struct in6_ifaddr *)(ifa)) + +#else /* !_NETINET6_IN6_H_ || !_KERNEL */ +#error "must be included via <netinet6/in6.h> in kernel space" +#endif /* _NETINET6_IN6_H_ && _KERNEL */ diff --git a/cpukit/include/machine/_kernel_mman.h b/cpukit/include/machine/_kernel_mman.h index fa2677a122..325142f9f3 100644 --- a/cpukit/include/machine/_kernel_mman.h +++ b/cpukit/include/machine/_kernel_mman.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides memory map definitions for the kernel space * (_KERNEL is defined before including <sys/mman.h>). */ /* - * Copyright (C) 2016 embedded brains GmbH + * Copyright (C) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/machine/_kernel_param.h b/cpukit/include/machine/_kernel_param.h index 5b381ccca5..bda6008822 100644 --- a/cpukit/include/machine/_kernel_param.h +++ b/cpukit/include/machine/_kernel_param.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides parameter definitions for the kernel space * (_KERNEL is defined before including <sys/param.h>). */ /* - * Copyright (C) 2017 embedded brains GmbH + * Copyright (C) 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -37,9 +39,7 @@ #include <sys/time.h> #include <sys/priority.h> -#if !defined(_SYS_PARAM_H_) || !defined(_KERNEL) -#error "must be included via <sys/param.h> in kernel space" -#endif +#if defined(_SYS_PARAM_H_) && defined(_KERNEL) #ifndef FALSE #define FALSE 0 @@ -65,3 +65,7 @@ __END_DECLS #define ntohl(x) __ntohl(x) #define ntohs(x) __ntohs(x) #endif /* !_BYTEORDER_FUNC_DEFINED */ + +#else /* !_SYS_PARAM_H_ || !_KERNEL */ +#error "must be included via <sys/param.h> in kernel space" +#endif /* _SYS_PARAM_H_ && _KERNEL */ diff --git a/cpukit/include/machine/_kernel_time.h b/cpukit/include/machine/_kernel_time.h index cfd223f0b6..9279c1238a 100644 --- a/cpukit/include/machine/_kernel_time.h +++ b/cpukit/include/machine/_kernel_time.h @@ -1,7 +1,7 @@ /*- * SPDX-License-Identifier: BSD-3-Clause * - * Copyright (C) 2016 embedded brains GmbH + * Copyright (C) 2016 embedded brains GmbH & Co. KG * * Copyright (c) 1982, 1986, 1993 * The Regents of the University of California. All rights reserved. @@ -37,13 +37,13 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides time definitions for the kernel space * (_KERNEL is defined before including <sys/time.h>). */ -#if !defined(_SYS_TIME_H_) || !defined(_KERNEL) -#error "must be included via <sys/time.h> in kernel space" -#endif +#if defined(_SYS_TIME_H_) && defined(_KERNEL) #include <machine/_timecounter.h> @@ -216,3 +216,7 @@ int tvtohz(struct timeval *tv); #define TIMESEL(sbt, sbt2) \ (((sbt2) >= sbt_timethreshold) ? \ ((*(sbt) = getsbinuptime()), 1) : ((*(sbt) = sbinuptime()), 0)) + +#else /* !_SYS_TIME_H_ || !_KERNEL */ +#error "must be included via <sys/time.h> in kernel space" +#endif /* _SYS_TIME_H_ && _KERNEL */ diff --git a/cpukit/include/machine/_kernel_types.h b/cpukit/include/machine/_kernel_types.h index 98f0366b64..c65e51d8cf 100644 --- a/cpukit/include/machine/_kernel_types.h +++ b/cpukit/include/machine/_kernel_types.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides type definitions for the kernel space * (_KERNEL is defined before including <sys/types.h>). */ /* - * Copyright (C) 2016 embedded brains GmbH + * Copyright (C) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -32,9 +34,7 @@ * POSSIBILITY OF SUCH DAMAGE. */ -#if !defined(_SYS_TYPES_H) || !defined(_KERNEL) -#error "must be included via <sys/types.h> in kernel space" -#endif +#if defined(_SYS_TYPES_H) && defined(_KERNEL) #include <stdbool.h> @@ -42,3 +42,7 @@ typedef int boolean_t; typedef struct device *device_t; typedef char vm_memattr_t; typedef struct vm_page *vm_page_t; + +#else /* !_SYS_TYPES_H || !_KERNEL */ +#error "must be included via <sys/types.h> in kernel space" +#endif /* _SYS_TYPES_H && _KERNEL */ diff --git a/cpukit/include/machine/_kernel_uio.h b/cpukit/include/machine/_kernel_uio.h index 59929cb03c..8e368770f1 100644 --- a/cpukit/include/machine/_kernel_uio.h +++ b/cpukit/include/machine/_kernel_uio.h @@ -35,13 +35,13 @@ /** * @file * + * @ingroup RTEMSImplFreeBSDKernel + * * @brief This header file provides device driver I/O definitions for the * kernel space (_KERNEL is defined before including <sys/uio.h>). */ -#if !defined(_SYS_UIO_H_) || !defined(_KERNEL) -#error "must be included via <sys/uio.h> in kernel space" -#endif +#if defined(_SYS_UIO_H_) && defined(_KERNEL) struct uio { struct iovec *uio_iov; /* scatter/gather list */ @@ -88,3 +88,7 @@ int uiomove_fromphys(struct vm_page *ma[], vm_offset_t offset, int n, struct uio *uio); int uiomove_nofault(void *cp, int n, struct uio *uio); int uiomove_object(struct vm_object *obj, off_t obj_size, struct uio *uio); + +#else /* !_SYS_UIO_H_ || !_KERNEL */ +#error "must be included via <sys/uio.h> in kernel space" +#endif /* _SYS_UIO_H_ && _KERNEL */ diff --git a/cpukit/include/machine/_timecounter.h b/cpukit/include/machine/_timecounter.h index fc3d78c5ad..e20e051f84 100644 --- a/cpukit/include/machine/_timecounter.h +++ b/cpukit/include/machine/_timecounter.h @@ -3,12 +3,14 @@ /** * @file * + * @ingroup RTEMSScoreTimecounter + * * @brief This header file provides timecounter definitions for the kernel space * (_KERNEL is defined before including <sys/time.h>) and RTEMS. */ /* - * Copyright (C) 2016 embedded brains GmbH + * Copyright (C) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/pci/irq.h b/cpukit/include/pci/irq.h index 4069f1ffa8..8617dd1680 100644 --- a/cpukit/include/pci/irq.h +++ b/cpukit/include/pci/irq.h @@ -38,18 +38,9 @@ #ifndef __PCI_IRQ_H__ #define __PCI_IRQ_H__ -#include <rtems/irq-extension.h> +#include <rtems/rtems/intr.h> #include <rtems/score/basedefs.h> -/* - * FIXME: This should be available via the IRQ extensions API. - * - * https://devel.rtems.org/ticket/3269 - */ -void BSP_shared_interrupt_clear(int irq); -void BSP_shared_interrupt_unmask(int irq); -void BSP_shared_interrupt_mask(int irq); - /* PCI Handler (ISR) called when IRQ is generated by any of the PCI devices * connected to the same PCI IRQ Pin. This has been defined the same way as * rtems_interrupt_handler in order for BSPs to "direct-map" the register @@ -106,7 +97,7 @@ static inline int pci_interrupt_unregister(int irq, pci_isr isr, */ static inline void pci_interrupt_unmask(int irq) { - BSP_shared_interrupt_unmask(irq); + (void)rtems_interrupt_vector_enable((rtems_vector_number)irq); } /* Disable shared PCI IRQ handler. This function will mask the interrupt @@ -122,7 +113,7 @@ static inline void pci_interrupt_unmask(int irq) */ static inline void pci_interrupt_mask(int irq) { - BSP_shared_interrupt_mask(irq); + (void)rtems_interrupt_vector_disable((rtems_vector_number)irq); } /* Acknowledge the interrupt controller by writing to the interrupt controller. @@ -136,7 +127,7 @@ static inline void pci_interrupt_mask(int irq) */ static inline void pci_interrupt_clear(int irq) { - BSP_shared_interrupt_clear(irq); + (void)rtems_interrupt_clear((rtems_vector_number)irq); } #endif /* !__PCI_IRQ_H__ */ diff --git a/cpukit/include/rtems.h b/cpukit/include/rtems.h index 809b2b77f4..e5fb8a212e 100644 --- a/cpukit/include/rtems.h +++ b/cpukit/include/rtems.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/score/io.h b/cpukit/include/rtems/base64.h index 106418f185..58e48a8c33 100644 --- a/cpukit/include/rtems/score/io.h +++ b/cpukit/include/rtems/base64.h @@ -3,14 +3,14 @@ /** * @file * - * @ingroup RTEMSScoreIO + * @ingroup RTEMSImplBase64 * * @brief This header file provides the interfaces of the - * @ref RTEMSScoreIO. + * @ref RTEMSImplBase64. */ /* - * Copyright (c) 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2020, 2024 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -34,42 +34,35 @@ * POSSIBILITY OF SUCH DAMAGE. */ -#ifndef _RTEMS_SCORE_IO_H -#define _RTEMS_SCORE_IO_H +#ifndef _RTEMS_BASE64_H +#define _RTEMS_BASE64_H -#include <rtems/score/basedefs.h> - -#include <stdarg.h> +#include <rtems/dev/io.h> #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** - * @defgroup RTEMSScoreIO IO Handler + * @defgroup RTEMSImplBase64 Base64 Encoding and Decoding * - * @ingroup RTEMSScore + * @ingroup RTEMSImpl * - * @brief This group contains the IO Handler implementation. + * @brief This group contains support functions for base64 and base64url + * encoding and decoding. * * @{ */ -typedef void ( *IO_Put_char )( int c, void *arg ); - -int _IO_Printf( - IO_Put_char put_char, - void *arg, - char const *fmt, - ... -) RTEMS_PRINTFLIKE( 3, 4 ); +/** + * @brief Maps a 6-bit integer to the corresponding base64 encoding. + */ +extern const uint8_t _Base64_Encoding[ 64 ]; -int _IO_Vprintf( - IO_Put_char put_char, - void *arg, - char const *fmt, - va_list ap -); +/** + * @brief Maps a 6-bit integer to the corresponding base64url encoding. + */ +extern const uint8_t _Base64url_Encoding[ 64 ]; /** * @brief Outputs the source buffer in base64 encoding. @@ -93,7 +86,7 @@ int _IO_Vprintf( * * @return Returns the count of output characters. */ -int _IO_Base64( +int _Base64_Encode( IO_Put_char put_char, void *arg, const void *src, @@ -124,7 +117,7 @@ int _IO_Base64( * * @return Returns the count of output characters. */ -int _IO_Base64url( +int _Base64url_Encode( IO_Put_char put_char, void *arg, const void *src, @@ -134,17 +127,72 @@ int _IO_Base64url( ); /** - * @brief Issues a couple of no-operation instructions. + * @brief Represents the base64 and base64url decoder state. + */ +typedef enum { + BASE64_DECODE_STATE_0, + BASE64_DECODE_STATE_1, + BASE64_DECODE_STATE_2, + BASE64_DECODE_STATE_3 +} Base64_Decode_state; + +/** + * @brief Contains the base64 and base64url decoder control. + */ +typedef struct { + Base64_Decode_state state; + uint8_t *target; + const uint8_t *target_end; +} Base64_Decode_control; + +/** + * @brief Maps a 7-bit character to the associated 6-bit integer as defined by + * the base64 or base64url encoding or a special value. + */ +extern const uint8_t _Base64_Decoding[ 128 ]; + +/** + * @brief Initializes the base64 decoder. + * + * @param[out] self is the base64 decoder control to initialize. + * + * @param[out] target is the base address of the target area for decoding. + * + * @param target_size is the size in bytes of the target area for decoding. + */ +void _Base64_Decode_initialize( + Base64_Decode_control *self, + uint8_t *target, + size_t target_size +); + +/** + * @brief Represents the base64 and base64url decoder status. + */ +typedef enum { + BASE64_DECODE_SUCCESS, + BASE64_DECODE_OVERFLOW, + BASE64_DECODE_INVALID_INPUT +} Base64_Decode_status; + +/** + * @brief Decodes the character. + * + * The decoder accepts base64 and base64url encodings. White space is ignored. * - * This function may be used to burn a couple of processor cycles with minimum - * impact on the system bus. It may be used in busy wait loops. + * @param[in, out] self is the base64 decoder control. + * + * @param ch is the character to decode. */ -void _IO_Relax( void ); +Base64_Decode_status _Base64_Decode( + Base64_Decode_control *self, + char ch +); -/** @} */ +/** @} */ #ifdef __cplusplus } #endif /* __cplusplus */ -#endif /* _RTEMS_SCORE_IO_H */ +#endif /* _RTEMS_BASE64_H */ diff --git a/cpukit/include/rtems/bdbuf.h b/cpukit/include/rtems/bdbuf.h index 4d11a47619..2d6c022259 100644 --- a/cpukit/include/rtems/bdbuf.h +++ b/cpukit/include/rtems/bdbuf.h @@ -15,7 +15,7 @@ * issues. * Change to support demand driven variable buffer sizes. * - * Copyright (c) 2009-2012 embedded brains GmbH. + * Copyright (C) 2009, 2012 embedded brains GmbH & Co. KG */ #ifndef _RTEMS_BDBUF_H diff --git a/cpukit/include/rtems/bdpart.h b/cpukit/include/rtems/bdpart.h index adc3f7d5ed..872fe5ca9f 100644 --- a/cpukit/include/rtems/bdpart.h +++ b/cpukit/include/rtems/bdpart.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2009, 2012 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2009, 2012 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/bsd.h b/cpukit/include/rtems/bsd.h index fe54246212..00dd82e12e 100644 --- a/cpukit/include/rtems/bsd.h +++ b/cpukit/include/rtems/bsd.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2015 embedded brains GmbH. All rights reserved. + * Copyright (c) 2015 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/bspIo.h b/cpukit/include/rtems/bspIo.h index b8a48e8237..a03e08c6a9 100644 --- a/cpukit/include/rtems/bspIo.h +++ b/cpukit/include/rtems/bspIo.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 2015 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -78,7 +78,7 @@ extern "C" { * * The directives may be used to print debug and test information. The kernel * character input/output support should work even if no Console Driver is - * configured, see #CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER. The kernel + * configured, see @ref CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER. The kernel * character input and output device is provided by the BSP. Applications may * change the device. */ diff --git a/cpukit/include/rtems/chain.h b/cpukit/include/rtems/chain.h index 076056dd7a..4f9f9495d5 100644 --- a/cpukit/include/rtems/chain.h +++ b/cpukit/include/rtems/chain.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2010-2014 embedded brains GmbH. + * Copyright (C) 2010, 2014 embedded brains GmbH & Co. KG * * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). diff --git a/cpukit/include/rtems/confdefs.h b/cpukit/include/rtems/confdefs.h index 3927d26ec5..29f7a2e71f 100644 --- a/cpukit/include/rtems/confdefs.h +++ b/cpukit/include/rtems/confdefs.h @@ -15,7 +15,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2000 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/confdefs/bdbuf.h b/cpukit/include/rtems/confdefs/bdbuf.h index 79e991f6d9..1cffe3fef6 100644 --- a/cpukit/include/rtems/confdefs/bdbuf.h +++ b/cpukit/include/rtems/confdefs/bdbuf.h @@ -18,7 +18,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/bsp.h b/cpukit/include/rtems/confdefs/bsp.h index bc96713765..9e50b14f26 100644 --- a/cpukit/include/rtems/confdefs/bsp.h +++ b/cpukit/include/rtems/confdefs/bsp.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2013 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2013 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/clock.h b/cpukit/include/rtems/confdefs/clock.h index 4e86ec5d02..e57daa899b 100644 --- a/cpukit/include/rtems/confdefs/clock.h +++ b/cpukit/include/rtems/confdefs/clock.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -70,6 +70,11 @@ #warning "The clock ticks per second is not an integer" #endif +#if defined(CONFIGURE_TICKS_PER_TIMESLICE) \ + && CONFIGURE_TICKS_PER_TIMESLICE <= 0 + #error "CONFIGURE_TICKS_PER_TIMESLICE shall be greater than zero" +#endif + #if CONFIGURE_MICROSECONDS_PER_TICK <= 0 #error "CONFIGURE_MICROSECONDS_PER_TICK must be positive" #endif diff --git a/cpukit/include/rtems/confdefs/console.h b/cpukit/include/rtems/confdefs/console.h index f4ee59feea..9e12fa4c86 100644 --- a/cpukit/include/rtems/confdefs/console.h +++ b/cpukit/include/rtems/confdefs/console.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/extensions.h b/cpukit/include/rtems/confdefs/extensions.h index a369ef1f61..c3bceda773 100644 --- a/cpukit/include/rtems/confdefs/extensions.h +++ b/cpukit/include/rtems/confdefs/extensions.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/inittask.h b/cpukit/include/rtems/confdefs/inittask.h index 006cbb781f..0b17c08677 100644 --- a/cpukit/include/rtems/confdefs/inittask.h +++ b/cpukit/include/rtems/confdefs/inittask.h @@ -13,7 +13,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/initthread.h b/cpukit/include/rtems/confdefs/initthread.h index 2b3d957515..325795b754 100644 --- a/cpukit/include/rtems/confdefs/initthread.h +++ b/cpukit/include/rtems/confdefs/initthread.h @@ -13,7 +13,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/iodrivers.h b/cpukit/include/rtems/confdefs/iodrivers.h index 1f77948676..16d64fbb98 100644 --- a/cpukit/include/rtems/confdefs/iodrivers.h +++ b/cpukit/include/rtems/confdefs/iodrivers.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/libio.h b/cpukit/include/rtems/confdefs/libio.h index 1b84f8c20f..7cf9f46487 100644 --- a/cpukit/include/rtems/confdefs/libio.h +++ b/cpukit/include/rtems/confdefs/libio.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -145,6 +145,16 @@ #ifdef CONFIGURE_FILESYSTEM_JFFS2 #include <rtems/jffs2.h> + +#ifndef CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY + #define CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY \ + RTEMS_JFFS2_DELAYED_WRITE_TASK_PRIORITY_DEFAULT +#endif + +const rtems_jffs2_config jffs2_config = { + CONFIGURE_JFFS2_DELAYED_WRITE_TASK_PRIORITY, +}; + #endif #ifdef CONFIGURE_FILESYSTEM_NFS diff --git a/cpukit/include/rtems/confdefs/malloc.h b/cpukit/include/rtems/confdefs/malloc.h index a8dae6e739..a20c6a290e 100644 --- a/cpukit/include/rtems/confdefs/malloc.h +++ b/cpukit/include/rtems/confdefs/malloc.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/mpci.h b/cpukit/include/rtems/confdefs/mpci.h index 76bdf4af16..e079a59d70 100644 --- a/cpukit/include/rtems/confdefs/mpci.h +++ b/cpukit/include/rtems/confdefs/mpci.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/newlib.h b/cpukit/include/rtems/confdefs/newlib.h index fef71a8855..65393fe92d 100644 --- a/cpukit/include/rtems/confdefs/newlib.h +++ b/cpukit/include/rtems/confdefs/newlib.h @@ -13,7 +13,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/objectsclassic.h b/cpukit/include/rtems/confdefs/objectsclassic.h index ff6f79a30b..aec4cf388b 100644 --- a/cpukit/include/rtems/confdefs/objectsclassic.h +++ b/cpukit/include/rtems/confdefs/objectsclassic.h @@ -12,7 +12,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/objectsposix.h b/cpukit/include/rtems/confdefs/objectsposix.h index b4685c28f7..7dabb326f4 100644 --- a/cpukit/include/rtems/confdefs/objectsposix.h +++ b/cpukit/include/rtems/confdefs/objectsposix.h @@ -12,7 +12,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/obsolete.h b/cpukit/include/rtems/confdefs/obsolete.h index b8b041efb5..a2eedad794 100644 --- a/cpukit/include/rtems/confdefs/obsolete.h +++ b/cpukit/include/rtems/confdefs/obsolete.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2017, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2017, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/percpu.h b/cpukit/include/rtems/confdefs/percpu.h index a6b35e0eaf..8ea7dae250 100644 --- a/cpukit/include/rtems/confdefs/percpu.h +++ b/cpukit/include/rtems/confdefs/percpu.h @@ -18,7 +18,7 @@ */ /* - * Copyright (C) 2018, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2018, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/scheduler.h b/cpukit/include/rtems/confdefs/scheduler.h index 8ac943921f..fdad17a4e1 100644 --- a/cpukit/include/rtems/confdefs/scheduler.h +++ b/cpukit/include/rtems/confdefs/scheduler.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/threads.h b/cpukit/include/rtems/confdefs/threads.h index 5ccfffaf6e..2e83df73b0 100644 --- a/cpukit/include/rtems/confdefs/threads.h +++ b/cpukit/include/rtems/confdefs/threads.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/unlimited.h b/cpukit/include/rtems/confdefs/unlimited.h index 41e79af1ba..98475297ed 100644 --- a/cpukit/include/rtems/confdefs/unlimited.h +++ b/cpukit/include/rtems/confdefs/unlimited.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/wkspace.h b/cpukit/include/rtems/confdefs/wkspace.h index da766fd8af..65f66c5c48 100644 --- a/cpukit/include/rtems/confdefs/wkspace.h +++ b/cpukit/include/rtems/confdefs/wkspace.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/confdefs/wkspacesupport.h b/cpukit/include/rtems/confdefs/wkspacesupport.h index 4036a7ae7f..ada91d7e91 100644 --- a/cpukit/include/rtems/confdefs/wkspacesupport.h +++ b/cpukit/include/rtems/confdefs/wkspacesupport.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/config.h b/cpukit/include/rtems/config.h index 3d51fd6b5d..a19d809cf9 100644 --- a/cpukit/include/rtems/config.h +++ b/cpukit/include/rtems/config.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2021 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -152,8 +152,8 @@ extern "C" { * RTEMS Workspace for this application, otherwise false. * * @par Notes - * The setting is defined by the - * #CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE application configuration + * The setting is defined by the @ref + * CONFIGURE_TASK_STACK_ALLOCATOR_AVOIDS_WORK_SPACE application configuration * option. * * @par Constraints @@ -353,7 +353,7 @@ const char *rtems_get_version_string( void ); * during system initialization for this application, otherwise false. * * @par Notes - * The setting is defined by the #CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY + * The setting is defined by the @ref CONFIGURE_ZERO_WORKSPACE_AUTOMATICALLY * application configuration option. * * @par Constraints @@ -377,8 +377,8 @@ const char *rtems_get_version_string( void ); * @return Returns the IDLE task stack size in bytes of this application. * * @par Notes - * The IDLE task stack size is defined by the #CONFIGURE_IDLE_TASK_STACK_SIZE - * application configuration option. + * The IDLE task stack size is defined by the @ref + * CONFIGURE_IDLE_TASK_STACK_SIZE application configuration option. * * @par Constraints * @parblock @@ -401,8 +401,8 @@ const char *rtems_get_version_string( void ); * @return Returns the IDLE task body of this application. * * @par Notes - * The IDLE task body is defined by the #CONFIGURE_IDLE_TASK_BODY application - * configuration option. + * The IDLE task body is defined by the @ref CONFIGURE_IDLE_TASK_BODY + * application configuration option. * * @par Constraints * @parblock @@ -425,8 +425,8 @@ const char *rtems_get_version_string( void ); * @return Returns the interrupt stack size in bytes of this application. * * @par Notes - * The interrupt stack size is defined by the #CONFIGURE_INTERRUPT_STACK_SIZE - * application configuration option. + * The interrupt stack size is defined by the @ref + * CONFIGURE_INTERRUPT_STACK_SIZE application configuration option. * * @par Constraints * @parblock @@ -438,7 +438,7 @@ const char *rtems_get_version_string( void ); * @endparblock */ #define rtems_configuration_get_interrupt_stack_size() \ - ((size_t) _ISR_Stack_size) + ((size_t) _ISR_Stack_size_object) /* Generated from spec:/rtems/config/if/get-maximum-extensions */ @@ -452,7 +452,7 @@ const char *rtems_get_version_string( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_USER_EXTENSIONS + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_USER_EXTENSIONS * application configuration option. See also rtems_resource_is_unlimited() * and rtems_resource_maximum_per_allocation(). * @@ -482,7 +482,7 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * @parblock * The actual number of processors available to the application is returned by * rtems_scheduler_get_processor_maximum() which less than or equal to the - * configured maximum number of processors (#CONFIGURE_MAXIMUM_PROCESSORS). + * configured maximum number of processors (@ref CONFIGURE_MAXIMUM_PROCESSORS). * * In uniprocessor configurations, this macro is a compile time constant which * evaluates to one. @@ -512,8 +512,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * this application. * * @par Notes - * The number of microseconds per clock tick is defined by the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The number of microseconds per clock tick is defined by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * @par Constraints * @parblock @@ -539,8 +539,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * this application. * * @par Notes - * The number of milliseconds per clock tick is defined by the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The number of milliseconds per clock tick is defined by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * @par Constraints * @parblock @@ -566,8 +566,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * this application. * * @par Notes - * The number of nanoseconds per clock tick is defined by the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The number of nanoseconds per clock tick is defined by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * @par Constraints * @parblock @@ -593,8 +593,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * application. * * @par Notes - * The number of initial extensions is defined by the - * #CONFIGURE_INITIAL_EXTENSIONS application configuration option and related + * The number of initial extensions is defined by the @ref + * CONFIGURE_INITIAL_EXTENSIONS application configuration option and related * options. * * @par Constraints @@ -621,8 +621,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * stack of each IDLE task configured for this application. * * @par Notes - * The task stack allocator allocate hook for idle tasks is defined by the - * #CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE application configuration option. + * The task stack allocator allocate hook for idle tasks is defined by the @ref + * CONFIGURE_TASK_STACK_ALLOCATOR_FOR_IDLE application configuration option. * * @par Constraints * @parblock @@ -648,8 +648,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * application. * * @par Notes - * The task stack allocator allocate hook is defined by the - * #CONFIGURE_TASK_STACK_ALLOCATOR application configuration option. + * The task stack allocator allocate hook is defined by the @ref + * CONFIGURE_TASK_STACK_ALLOCATOR application configuration option. * * @par Constraints * @parblock @@ -674,8 +674,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * this application. * * @par Notes - * The task stack allocator initialization hook is defined by the - * #CONFIGURE_TASK_STACK_ALLOCATOR_INIT application configuration option. + * The task stack allocator initialization hook is defined by the @ref + * CONFIGURE_TASK_STACK_ALLOCATOR_INIT application configuration option. * * @par Constraints * @parblock @@ -701,8 +701,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * application. * * @par Notes - * The task stack allocator free hook is defined by the - * #CONFIGURE_TASK_STACK_DEALLOCATOR application configuration option. + * The task stack allocator free hook is defined by the @ref + * CONFIGURE_TASK_STACK_DEALLOCATOR application configuration option. * * @par Constraints * @parblock @@ -726,8 +726,8 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * application. * * @par Notes - * The clock ticks per timeslice is defined by the - * #CONFIGURE_TICKS_PER_TIMESLICE application configuration option. + * The clock ticks per timeslice is defined by the @ref + * CONFIGURE_TICKS_PER_TIMESLICE application configuration option. * * @par Constraints * @parblock @@ -753,7 +753,7 @@ uint32_t rtems_configuration_get_maximum_extensions( void ); * configured to be unified for this application, otherwise false. * * @par Notes - * The setting is defined by the #CONFIGURE_UNIFIED_WORK_AREAS application + * The setting is defined by the @ref CONFIGURE_UNIFIED_WORK_AREAS application * configuration option. * * @par Constraints diff --git a/cpukit/include/rtems/counter.h b/cpukit/include/rtems/counter.h index 61a0677bd3..9d8fa31719 100644 --- a/cpukit/include/rtems/counter.h +++ b/cpukit/include/rtems/counter.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2014, 2018 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/cpuuse.h b/cpukit/include/rtems/cpuuse.h index 45672d93de..f02f004073 100644 --- a/cpukit/include/rtems/cpuuse.h +++ b/cpukit/include/rtems/cpuuse.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/crc.h b/cpukit/include/rtems/crc.h new file mode 100644 index 0000000000..1158dbcd7b --- /dev/null +++ b/cpukit/include/rtems/crc.h @@ -0,0 +1,106 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup RTEMSImplCRC + * + * @brief This header file provides the interfaces of the + * @ref RTEMSImplCRC. + */ + +/* + * Copyright (C) 2024 embedded brains GmbH & Co. KG + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef _RTEMS_CRC_H +#define _RTEMS_CRC_H + +#include <stddef.h> +#include <stdint.h> + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @defgroup RTEMSImplCRC Cyclic Redundancy Check (CRC) Support + * + * @ingroup RTEMSImpl + * + * @brief This group contains functions to calculate + * Cyclic Redundancy Check (CRC) values. + * + * @{ + */ + + +/** + * @brief This constant represents the default CRC-24Q seed state. + */ +#define CRC24Q_SEED 0U + +/** + * @brief This constant provides a mask to get a valid CRC-24Q value from the + * integers returned by _CRC24Q_Update() and _CRC24Q_Sequence_update(). + */ +#define CRC24Q_MASK 0xffffffU + +/** + * @brief Updates the CRC-24Q state using a byte. + * + * @param crc is the input CRC-24Q state. + * + * @param byte is the byte updating the input CRC-24Q state. + * + * @return Returns the updated CRC-24Q state. Use the #CRC24Q_MASK to get a + * valid CRC-24Q value. + */ +uint32_t _CRC24Q_Update( uint32_t crc, uint8_t byte ); + +/** + * @brief Updates the CRC-24Q state using a sequence of bytes. + * + * @param crc is the input CRC-24Q state. + * + * @param bytes[in] is the sequence of bytes updating the input CRC-24Q state. + * + * @param size_in_bytes is the size in bytes of the byte sequence. + * + * @return Returns the updated CRC-24Q state. Use the #CRC24Q_MASK to get a + * valid CRC-24Q value. + */ +uint32_t _CRC24Q_Sequence_update( + uint32_t crc, + const void *bytes, + size_t size_in_bytes +); + +/** @} */ + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* _RTEMS_CRC_H */ diff --git a/cpukit/include/rtems/dev/io.h b/cpukit/include/rtems/dev/io.h new file mode 100644 index 0000000000..b8bcde7af4 --- /dev/null +++ b/cpukit/include/rtems/dev/io.h @@ -0,0 +1,123 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup RTEMSDeviceIO + * + * @brief This header file provides the interfaces of the + * @ref RTEMSDeviceIO. + */ + +/* + * Copyright (C) 2017, 2023 embedded brains GmbH & Co. KG + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef _RTEMS_DEV_IO_H +#define _RTEMS_DEV_IO_H + +#include <rtems/score/basedefs.h> + +#include <stdarg.h> + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @defgroup RTEMSDeviceIO Device I/O Support + * + * @ingroup RTEMSDeviceDrivers + * + * @brief This group contains the Device I/O Support API and implementation. + * + * @{ + */ + +/** + * @brief This type defines the put character handler. + * + * @param c is the character to put. + * + * @param arg is the user-provided argument. + */ +typedef void ( *IO_Put_char )( int c, void *arg ); + +/** + * @brief Prints characters using the put character handler according to the + * format string. + * + * @param put_char is the put character handler. + * + * @param arg is the user-provided argument for the put character handler. + * + * @param fmt is the printf()-style format string. + * + * @param ... is the list of parameters required by the format string. + * + * @return Returns the count of put characters. + */ +int _IO_Printf( + IO_Put_char put_char, + void *arg, + char const *fmt, + ... +) RTEMS_PRINTFLIKE( 3, 4 ); + +/** + * @brief Prints characters using the put character handler according to the + * format string. + * + * @param put_char is the put character handler. + * + * @param arg is the user-provided argument for the put character handler. + * + * @param fmt is the printf()-style format string. + * + * @param ap is the argument list required by the format string. + * + * @return Returns the count of put characters. + */ +int _IO_Vprintf( + IO_Put_char put_char, + void *arg, + char const *fmt, + va_list ap +); + +/** + * @brief Issues a couple of no-operation instructions. + * + * This function may be used to burn a couple of processor cycles with minimum + * impact on the system bus. It may be used in busy wait loops. + */ +void _IO_Relax( void ); + +/** @} */ + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* _RTEMS_DEV_IO_H */ diff --git a/cpukit/include/rtems/devzero.h b/cpukit/include/rtems/devzero.h index efe54966f8..734b02ef52 100644 --- a/cpukit/include/rtems/devzero.h +++ b/cpukit/include/rtems/devzero.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2011 embedded brains GmbH. All rights reserved. + * Copyright (c) 2011 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/dosfs.h b/cpukit/include/rtems/dosfs.h index 38fb9bd77b..1304347a44 100644 --- a/cpukit/include/rtems/dosfs.h +++ b/cpukit/include/rtems/dosfs.h @@ -13,7 +13,7 @@ * Author: Eugeny S. Mints <Eugeny.Mints@oktet.ru> * * Modifications to support UTF-8 in the file system are - * Copyright (c) 2013 embedded brains GmbH. + * Copyright (c) 2013 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/extension.h b/cpukit/include/rtems/extension.h index 0117a41b8a..31fb18de65 100644 --- a/cpukit/include/rtems/extension.h +++ b/cpukit/include/rtems/extension.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -140,7 +140,7 @@ rtems_status_code rtems_extension_delete( rtems_id id ); * may be in an undefined and corrupt state. * * It is recommended to register fatal extensions through initial extension - * sets, see #CONFIGURE_INITIAL_EXTENSIONS. + * sets, see @ref CONFIGURE_INITIAL_EXTENSIONS. * @endparblock */ typedef User_extensions_fatal_extension rtems_fatal_extension; @@ -230,7 +230,7 @@ rtems_status_code rtems_extension_ident( rtems_name name, rtems_id *id ); * @ingroup RTEMSAPIClassicUserExt * * @brief The extensions table contains a set of extensions which may be - * registered in the system through the #CONFIGURE_INITIAL_EXTENSIONS + * registered in the system through the @ref CONFIGURE_INITIAL_EXTENSIONS * application configuration option or the rtems_extension_create() * directive. */ @@ -271,8 +271,8 @@ typedef User_extensions_Table rtems_extensions_table; * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create an * extension set. The number of extension sets available to the application - * is configured through the #CONFIGURE_MAXIMUM_USER_EXTENSIONS application - * configuration option. + * is configured through the @ref CONFIGURE_MAXIMUM_USER_EXTENSIONS + * application configuration option. * * @par Notes * @parblock @@ -286,8 +286,8 @@ typedef User_extensions_Table rtems_extensions_table; * are invoked upon the next system event supporting an extension. * * An alternative to dynamically created extension sets are initial extensions, - * see #CONFIGURE_INITIAL_EXTENSIONS. Initial extensions are recommended for - * extension sets which provide a fatal error extension. + * see @ref CONFIGURE_INITIAL_EXTENSIONS. Initial extensions are recommended + * for extension sets which provide a fatal error extension. * * For control and maintenance of the extension set, RTEMS allocates a ESCB * from the local ESCB free pool and initializes it. @@ -306,8 +306,8 @@ typedef User_extensions_Table rtems_extensions_table; * cause the calling task to be preempted. * * * The number of extension sets available to the application is configured - * through the #CONFIGURE_MAXIMUM_USER_EXTENSIONS application configuration - * option. + * through the @ref CONFIGURE_MAXIMUM_USER_EXTENSIONS application + * configuration option. * @endparblock */ rtems_status_code rtems_extension_create( diff --git a/cpukit/include/rtems/fatal.h b/cpukit/include/rtems/fatal.h index 1cc59076fe..680fd4f934 100644 --- a/cpukit/include/rtems/fatal.h +++ b/cpukit/include/rtems/fatal.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/fs.h b/cpukit/include/rtems/fs.h index b52f675828..8b86536cc2 100644 --- a/cpukit/include/rtems/fs.h +++ b/cpukit/include/rtems/fs.h @@ -13,7 +13,7 @@ * On-Line Applications Research Corporation (OAR). * * Modifications to support reference counting in the file system are - * Copyright (c) 2012 embedded brains GmbH. + * Copyright (c) 2012 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/ftpfs.h b/cpukit/include/rtems/ftpfs.h index 6997563476..c21894a7fe 100644 --- a/cpukit/include/rtems/ftpfs.h +++ b/cpukit/include/rtems/ftpfs.h @@ -7,7 +7,7 @@ */ /* - * Copyright (c) 2009 embedded brains GmbH. All rights reserved. + * Copyright (c) 2009 embedded brains GmbH & Co. KG * * Copyright (c) 2002 IMD Ingenieurbuero fuer Microcomputertechnik * All rights reserved. diff --git a/cpukit/include/rtems/imfs.h b/cpukit/include/rtems/imfs.h index 7db9b4e462..405f489ab3 100644 --- a/cpukit/include/rtems/imfs.h +++ b/cpukit/include/rtems/imfs.h @@ -477,7 +477,7 @@ extern void IMFS_fsunmount( */ extern int rtems_tarfs_load( const char *mountpoint, - uint8_t *tar_image, + const void *tar_image, size_t tar_size ); diff --git a/cpukit/include/rtems/imfsimpl.h b/cpukit/include/rtems/imfsimpl.h index db1ae32af7..1275d831b3 100644 --- a/cpukit/include/rtems/imfsimpl.h +++ b/cpukit/include/rtems/imfsimpl.h @@ -8,7 +8,7 @@ */ /* - * Copyright (C) 2013, 2018 embedded brains GmbH + * Copyright (C) 2013, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/init.h b/cpukit/include/rtems/init.h index d386a0bcea..0ae483edf5 100644 --- a/cpukit/include/rtems/init.h +++ b/cpukit/include/rtems/init.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2015, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/io.h b/cpukit/include/rtems/io.h index 181da9fe4f..b6a25b5f2f 100644 --- a/cpukit/include/rtems/io.h +++ b/cpukit/include/rtems/io.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -98,7 +98,7 @@ typedef rtems_status_code rtems_device_driver; * * @par Notes * The major number of a device is determined by rtems_io_register_driver() and - * the application configuration (see #CONFIGURE_MAXIMUM_DRIVERS) . + * the application configuration (see @ref CONFIGURE_MAXIMUM_DRIVERS) . */ typedef uint32_t rtems_device_major_number; @@ -207,7 +207,7 @@ typedef struct { * @retval ::RTEMS_INVALID_ADDRESS The device driver address table was empty. * * @retval ::RTEMS_INVALID_NUMBER The device major number of the device was out - * of range, see #CONFIGURE_MAXIMUM_DRIVERS. + * of range, see @ref CONFIGURE_MAXIMUM_DRIVERS. * * @retval ::RTEMS_TOO_MANY The system was unable to obtain a device major * number. diff --git a/cpukit/include/rtems/irq-extension.h b/cpukit/include/rtems/irq-extension.h index 76b930dc69..c2576ec372 100644 --- a/cpukit/include/rtems/irq-extension.h +++ b/cpukit/include/rtems/irq-extension.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/jffs2.h b/cpukit/include/rtems/jffs2.h index 1cf9a01c6e..12f4f8e073 100644 --- a/cpukit/include/rtems/jffs2.h +++ b/cpukit/include/rtems/jffs2.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: BSD-2-Clause */ /* - * Copyright (c) 2013, 2016 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -230,6 +230,99 @@ typedef int (*rtems_jffs2_flash_erase)( ); /** + * @brief Flash bad block check operation. + * + * This operation checks whether a block is bad. + * + * @param[in, out] self The flash control. + * @param[in] offset The offset in bytes of the block to check. + * @param[out] The result of the bad block check. + * + * @retval 0 Successful operation. + * @retval -EIO An error occurred. Please note that the value is negative. + * @retval other All other values are reserved and must not be used. + */ +typedef int (*rtems_jffs2_flash_block_is_bad)( + rtems_jffs2_flash_control *self, + uint32_t offset, + bool *bad +); + +/** + * @brief Flash bad block mark operation. + * + * This operation marks a block bad. + * + * @param[in, out] self The flash control. + * @param[in] offset The offset in bytes of the block to mark bad. + * + * @retval 0 Successful operation. + * @retval -EIO An error occurred. Please note that the value is negative. + * @retval other All other values are reserved and must not be used. + */ +typedef int (*rtems_jffs2_flash_block_mark_bad)( + rtems_jffs2_flash_control *self, + uint32_t offset +); + +/** + * @brief Flash oob write. + * + * This operation writes the out-of-band/spare bytes for the block matching + * the given offset in bytes. + * + * @param[in, out] self The flash control. + * @param[in] offset The offset to erase from the flash begin in bytes. + * @param[in] pointer to the buffer which will be written to the oob/spare bytes. + * @param[in] length of the buffer which will be written to the oob/spare bytes. + * + * @retval 0 Successful operation. + * @retval -EIO An error occurred. Please note that the value is negative. + * @retval other All other values are reserved and must not be used. + */ +typedef int (*rtems_jffs2_flash_oob_write)( + rtems_jffs2_flash_control *self, + uint32_t offset, + uint8_t *oobbuf, + uint32_t obblen +); + +/** + * @brief Flash oob read. + * + * This operation reads the out-of-band/spare bytes for the block matching + * the given offset in bytes. + * + * @param[in, out] self The flash control. + * @param[in] offset The offset to erase from the flash begin in bytes. + * @param[out] pointer to the buffer which will have the oob/spare bytes data written to it. + * @param[in] length of the buffer which will hold the oob/spare bytes. + * + * @retval 0 Successful operation. + * @retval -EIO An error occurred. Please note that the value is negative. + * @retval other All other values are reserved and must not be used. + */ +typedef int (*rtems_jffs2_flash_oob_read)( + rtems_jffs2_flash_control *self, + uint32_t offset, + uint8_t *oobbuf, + uint32_t obblen +); + +/** + * @brief Flash get oob size. + * + * This operation gets the size of the out-of-band/spare bytes for each page. + * + * @param[in, out] self The flash control. + * + * @retval The size of the OOB/spare area available to each page + */ +typedef uint32_t (*rtems_jffs2_flash_get_oob_size)( + rtems_jffs2_flash_control *self +); + +/** * @brief Flash destroy operation. * * The flash destroy operation is called during unmount of the file system @@ -274,6 +367,14 @@ struct rtems_jffs2_flash_control { uint32_t flash_size; /** + * @brief The size in bytes of the minimum write size for the flash device. + * + * It must be an integral divisor into the block size. This is only applicable + * for NAND devices. + */ + uint32_t write_size; + + /** * @brief Read from flash operation. */ rtems_jffs2_flash_read read; @@ -289,6 +390,31 @@ struct rtems_jffs2_flash_control { rtems_jffs2_flash_erase erase; /** + * @brief Flash bad block check operation. + */ + rtems_jffs2_flash_block_is_bad block_is_bad; + + /** + * @brief Flash bad block mark operation. + */ + rtems_jffs2_flash_block_mark_bad block_mark_bad; + + /** + * @brief Flash oob bytes write operation. + */ + rtems_jffs2_flash_oob_write oob_write; + + /** + * @brief Flash oob bytes read operation. + */ + rtems_jffs2_flash_oob_read oob_read; + + /** + * @brief Flash get oob bytes per page operation. + */ + rtems_jffs2_flash_get_oob_size get_oob_size; + + /** * @brief Flash destroy operation. * * This operation is optional and the pointer may be @c NULL. @@ -608,6 +734,27 @@ typedef struct { */ #define RTEMS_JFFS2_FORCE_GARBAGE_COLLECTION _IO('F', 3) +/** + * Default delayed-write servicing task priority. + */ +#define RTEMS_JFFS2_DELAYED_WRITE_TASK_PRIORITY_DEFAULT 15 + +/** + * JFFS2 configuration definition. See confdefs.h for support on using this + * structure. + */ +typedef struct rtems_jffs2_config { + rtems_task_priority delayed_write_priority; /**< Priority of the delayed write + * task. */ +} rtems_jffs2_config; + +/** + * External reference to the configuration. + * + * The configuration is provided by the application. + */ +extern const rtems_jffs2_config jffs2_config; + /** @} */ #ifdef __cplusplus diff --git a/cpukit/include/rtems/libcsupport.h b/cpukit/include/rtems/libcsupport.h index 67a09dc2a2..9329b82674 100644 --- a/cpukit/include/rtems/libcsupport.h +++ b/cpukit/include/rtems/libcsupport.h @@ -2,9 +2,11 @@ /** * @file - * + * + * @ingroup libcsupport + * * @brief Standard C Library Support - * + * * This include file contains the information regarding the * RTEMS specific support for the standard C library. */ @@ -55,8 +57,8 @@ extern "C" { * * @brief RTEMS Specific Support for the Standard C Library * + * @{ */ -/**@{**/ extern void malloc_dump(void); diff --git a/cpukit/include/rtems/libio.h b/cpukit/include/rtems/libio.h index 041fc050ad..5424a2a03c 100644 --- a/cpukit/include/rtems/libio.h +++ b/cpukit/include/rtems/libio.h @@ -16,7 +16,7 @@ * COPYRIGHT (C) 1989, 2021 On-Line Applications Research Corporation (OAR). * * Modifications to support reference counting in the file system are - * Copyright (C) 2012 embedded brains GmbH. + * Copyright (C) 2012 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -56,6 +56,7 @@ #include <rtems/fs.h> #include <rtems/chain.h> #include <rtems/score/atomic.h> +#include <rtems/termiosdevice.h> #ifdef __cplusplus extern "C" { @@ -1360,7 +1361,7 @@ typedef struct { /** * @brief Parameter block for open/close. */ -typedef struct { +typedef struct rtems_libio_open_close_args { rtems_libio_t *iop; uint32_t flags; uint32_t mode; @@ -1902,7 +1903,7 @@ typedef struct rtems_termios_callbacks { int (*setAttributes)(int minor, const struct termios *t); int (*stopRemoteTx)(int minor); int (*startRemoteTx)(int minor); - int outputUsesInterrupts; + rtems_termios_device_mode outputUsesInterrupts; } rtems_termios_callbacks; static inline void rtems_termios_initialize( void ) diff --git a/cpukit/include/rtems/libio_.h b/cpukit/include/rtems/libio_.h index 8d4a2dc861..eb487934bc 100644 --- a/cpukit/include/rtems/libio_.h +++ b/cpukit/include/rtems/libio_.h @@ -12,7 +12,7 @@ * COPYRIGHT (C) 1989, 2021 On-Line Applications Research Corporation (OAR). * * Modifications to support reference counting in the file system are - * Copyright (c) 2012 embedded brains GmbH. + * Copyright (c) 2012 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/linkersets.h b/cpukit/include/rtems/linkersets.h index c4b3e2b7dc..a5d7b1b037 100644 --- a/cpukit/include/rtems/linkersets.h +++ b/cpukit/include/rtems/linkersets.h @@ -1,7 +1,15 @@ /* SPDX-License-Identifier: BSD-2-Clause */ +/** + * @file + * + * @ingroup RTEMSAPILinkerSets + * + * @brief This header file provides the linker sets API. + */ + /* - * Copyright (c) 2015, 2020 embedded brains GmbH. All rights reserved. + * Copyright (C) 2015, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -34,6 +42,36 @@ extern "C" { #endif /* __cplusplus */ +/** + * @ingroup RTEMSImpl + * + * @brief Obfuscates a pointer to prevent compiler optimizations. + * + * @param ptr is the pointer to obfuscate. + * + * @return Returns the unsigned integer representation of the obfuscated + * pointer. + */ +static inline uintptr_t _Linker_set_Obfuscate( const void *ptr ) +{ + uintptr_t addr; + + addr = (uintptr_t) ptr; + RTEMS_OBFUSCATE_VARIABLE( addr ); + + return addr; +} + +/** + * @defgroup RTEMSAPILinkerSets Linker Sets + * + * @ingroup RTEMSAPI + * + * @brief This group contains the linker sets API. + * + * @{ + */ + #define RTEMS_LINKER_SET_BEGIN( set ) \ _Linker_set_##set##_begin @@ -129,16 +167,6 @@ extern "C" { decl \ RTEMS_SECTION( ".rtemsrwset." #set ".content" ) -static inline uintptr_t _Linker_set_Obfuscate( const void *ptr ) -{ - uintptr_t addr; - - addr = (uintptr_t) ptr; - RTEMS_OBFUSCATE_VARIABLE( addr ); - - return addr; -} - #define RTEMS_LINKER_SET_SIZE( set ) \ ( _Linker_set_Obfuscate( RTEMS_LINKER_SET_END( set ) ) \ - _Linker_set_Obfuscate( RTEMS_LINKER_SET_BEGIN( set ) ) ) @@ -157,6 +185,8 @@ static inline uintptr_t _Linker_set_Obfuscate( const void *ptr ) ++item \ ) +/** @} */ + #ifdef __cplusplus } #endif /* __cplusplus */ diff --git a/cpukit/include/rtems/mallocinitmulti.h b/cpukit/include/rtems/mallocinitmulti.h index 45b52e7dc6..ba9cf6830c 100644 --- a/cpukit/include/rtems/mallocinitmulti.h +++ b/cpukit/include/rtems/mallocinitmulti.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2012, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2012, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/mallocinitone.h b/cpukit/include/rtems/mallocinitone.h index 1e28df137c..7ad13e3804 100644 --- a/cpukit/include/rtems/mallocinitone.h +++ b/cpukit/include/rtems/mallocinitone.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2012, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2012, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/media.h b/cpukit/include/rtems/media.h index 9a8cf2d4e2..ea9c667b93 100644 --- a/cpukit/include/rtems/media.h +++ b/cpukit/include/rtems/media.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2009, 2018 embedded brains GmbH. All rights reserved. + * Copyright (C) 2009, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/posix/barrierimpl.h b/cpukit/include/rtems/posix/barrierimpl.h index 44c1d4317c..3c75f9f50d 100644 --- a/cpukit/include/rtems/posix/barrierimpl.h +++ b/cpukit/include/rtems/posix/barrierimpl.h @@ -13,7 +13,7 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2017 embedded brains GmbH + * Copyright (c) 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/posix/key.h b/cpukit/include/rtems/posix/key.h index c3fa8ce51c..465986a91f 100644 --- a/cpukit/include/rtems/posix/key.h +++ b/cpukit/include/rtems/posix/key.h @@ -13,7 +13,7 @@ * Copyright (c) 2012 Zhongwei Yao. * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). - * Copyright (c) 2016 embedded brains GmbH. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/posix/keyimpl.h b/cpukit/include/rtems/posix/keyimpl.h index 5ff269d95c..2cc68eff3e 100644 --- a/cpukit/include/rtems/posix/keyimpl.h +++ b/cpukit/include/rtems/posix/keyimpl.h @@ -12,7 +12,7 @@ /* * COPYRIGHT (c) 1989-1999. * On-Line Applications Research Corporation (OAR). - * Copyright (c) 2016 embedded brains GmbH. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/posix/posixapi.h b/cpukit/include/rtems/posix/posixapi.h index 24c1dc51e0..5d78573ef7 100644 --- a/cpukit/include/rtems/posix/posixapi.h +++ b/cpukit/include/rtems/posix/posixapi.h @@ -3,10 +3,10 @@ /** * @file * - * @brief POSIX API Implementation + * @ingroup POSIXAPI * - * This include file defines the top level interface to the POSIX API - * implementation in RTEMS. + * @brief This header file provides interfaces used by the POSIX API + * implementation. */ /* diff --git a/cpukit/include/rtems/posix/spinlockimpl.h b/cpukit/include/rtems/posix/spinlockimpl.h index a5e5bb1850..10424f1961 100644 --- a/cpukit/include/rtems/posix/spinlockimpl.h +++ b/cpukit/include/rtems/posix/spinlockimpl.h @@ -2,18 +2,18 @@ /** * @file - * - * @brief Inlined Routines from the POSIX Spinlock Manager * - * This file contains the static inlin implementation of the inlined - * routines from the POSIX Spinlock Manager. + * @ingroup POSIXAPI + * + * @brief This header file provides interfaces used by the POSIX Spinlock + * implementation. */ /* * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2016 embedded brains GmbH + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/print.h b/cpukit/include/rtems/print.h index ee9fa366b7..1f870482d4 100644 --- a/cpukit/include/rtems/print.h +++ b/cpukit/include/rtems/print.h @@ -3,6 +3,8 @@ /** * @file * + * @ingroup RTEMSPrintSupport + * * @brief User print interface to the bspIO print plug in. * * This include file defines the user interface to kernel print methods. @@ -54,6 +56,8 @@ typedef struct rtems_printer rtems_printer; * * This module contains all methods and support related to providing the user * with an interface to the kernel level print support. + * + * @{ */ /** diff --git a/cpukit/include/rtems/printer.h b/cpukit/include/rtems/printer.h index 2c6e68060d..424d59563e 100644 --- a/cpukit/include/rtems/printer.h +++ b/cpukit/include/rtems/printer.h @@ -3,6 +3,8 @@ /** * @file * + * @ingroup RTEMSPrintSupport + * * @brief User print interface to the bspIO print plug in. * * This include file defines the user interface to kernel print methods. diff --git a/cpukit/include/rtems/profiling.h b/cpukit/include/rtems/profiling.h index 92cf123b40..95ec3323e1 100644 --- a/cpukit/include/rtems/profiling.h +++ b/cpukit/include/rtems/profiling.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/rbheap.h b/cpukit/include/rtems/rbheap.h index b1f7b562c8..8b190051a8 100644 --- a/cpukit/include/rtems/rbheap.h +++ b/cpukit/include/rtems/rbheap.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2012 embedded brains GmbH. All rights reserved. + * Copyright (c) 2012 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/record.h b/cpukit/include/rtems/record.h index 8a84c22bdc..cd52083e0c 100644 --- a/cpukit/include/rtems/record.h +++ b/cpukit/include/rtems/record.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: BSD-2-Clause */ /* - * Copyright (C) 2018, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2018, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/recordclient.h b/cpukit/include/rtems/recordclient.h index cb1e704f99..037c9d52f7 100644 --- a/cpukit/include/rtems/recordclient.h +++ b/cpukit/include/rtems/recordclient.h @@ -1,7 +1,7 @@ /* * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (C) 2018, 2019 embedded brains GmbH + * Copyright (C) 2018, 2019 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/recorddata.h b/cpukit/include/rtems/recorddata.h index 4fa16d6775..3ba67975c1 100644 --- a/cpukit/include/rtems/recorddata.h +++ b/cpukit/include/rtems/recorddata.h @@ -1,7 +1,7 @@ /* * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (C) 2018, 2019 embedded brains GmbH + * Copyright (C) 2018, 2019 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/recorddump.h b/cpukit/include/rtems/recorddump.h index 246482161c..c8d020b216 100644 --- a/cpukit/include/rtems/recorddump.h +++ b/cpukit/include/rtems/recorddump.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: BSD-2-Clause */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/recordserver.h b/cpukit/include/rtems/recordserver.h index 2c04ea65cb..eb6d98136a 100644 --- a/cpukit/include/rtems/recordserver.h +++ b/cpukit/include/rtems/recordserver.h @@ -1,7 +1,7 @@ /* * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (C) 2018, 2019 embedded brains GmbH + * Copyright (C) 2018, 2019 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/regulator.h b/cpukit/include/rtems/regulator.h new file mode 100644 index 0000000000..442040a180 --- /dev/null +++ b/cpukit/include/rtems/regulator.h @@ -0,0 +1,502 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup RegulatorAPI + * + * @brief This header file defines the Regulator API. + * + */ + +/* + * Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/** + * @defgroup RegulatorAPI Regulator API + * + * @brief Regulator APIs + * + * The Regulator provides a set of APIs to manage input sources which + * produces bursts of message traffic. + * + * The regulator is designed to sit logically between two entities -- a + * source and a destination, where it limits the traffic sent to the + * destination to prevent it from being flooded with messages from the + * source. This can be used to accommodate bursts of input from a source + * and meter it out to a destination. The maximum number of messages + * which can be buffered in the regulator is specified by the + * @a maximum_messages field in the @a rtems_regulator_attributes + * structure passed as an argument to @a rtems_regulator_create(). + * + * The regulator library accepts an input stream of messages from a + * source and delivers them to a destination. The regulator assumes that the + * input stream from the source contains sporadic bursts of data which can + * exceed the acceptable rate of the destination. By limiting the message rate, + * the regulator prevents an overflow of messages. + * + * The regulator can be configured for the input buffering required to manage + * the maximum burst and for the metering rate for the output. The output rate + * is in messages per second. If the sender produces data too fast, the + * regulator will buffer the configured number of messages. + * + * A configuration capability is provided to allow for adaptation to different + * message streams. The regulator can also support running multiple instances, + * which could be used on independent message streams. + * + * The regulator provides a simple interface to the application for avoiding + * bursts of input from a fast source overflowing a slower destination. + * + * It is assumed that the application has a design limit on the number of + * messages which may be buffered. All messages accepted by the regulator, + * assuming no overflow on input, will eventually be output by the Delivery + * thread. + * + * A regulator instance is used as follows from the producer/source side: + * + * @code + * while (1) + * use rtems_regulator_obtain_buffer to obtain a buffer + * input operation to fetch data into the buffer + * rtems_regulator_send(buffer, size of message) + * @endcode + * + * The delivery of message buffers to the Destination and subsequent + * release is performed in the context of the delivery thread by either + * the delivery function or delivery thread. Details are below. + * + * The sequence diagram below shows the interaction between a message Source, + * a Regulator instance, and RTEMS, given the usage described in the above + * paragraphs. + * + * \startuml "Regulator Application Input Source Usage" + * Source -> Regulator : rtems_regulator_obtain_buffer(regulator, buffer) + * Regulator -> RTEMS : rtems_partition_get_buffer(id, buffer) + * RTEMS --> Regulator : rtems_status_code + * Regulator --> Source : rtems_status_code + * Source -> Regulator : rtems_regulator_send(regulator, message, length) + * Regulator -> RTEMS : rtems_message_queue_send(id, message, size) + * RTEMS --> Regulator : rtems_status_code + * Regulator --> Source : rtems_status_code + * \enduml + * + * As illustrated in the sequence diagram, the Source usually corresponds + * to application software reading a system input. The Source obtains a + * buffer from the Regulator instance and fills it with incoming data. + * The application explicitly obtaining a buffer and filling it in allows + * for zero copy operations on the Source side. + * + * The Source then sends the buffer to the Regulator instance. The Regulator + * the sends the buffer via a message queue which to the Delivery thread. + * The Delivery thread executes periodically at a rate specified at + * Regulation creation. At each period, the Delivery thread attempts to + * receive up to a configured number of buffers and invoke the Delivery + * function to deliver them to the Destination. + * + * The Delivery function is provided by the application for this + * specific Regulator instance. Depending on the Destination, it may use + * a function which copies the buffer contents (e.g., write()) or which + * operates directly on the buffer contents (e.g. DMA from buffer). In + * the case of a Destination which copies the buffer contents, the buffer + * can be released via @a rtems_regulator_release_buffer() as soon as the + * function or copying completes. In the case where the delivery uses the + * buffer and returns, the call to @a rtems_regulator_release_buffer() + * will occur when the use of the buffer is complete (e.g. completion + * of DMA transfer). This explicit and deliberate exposure of buffering + * provides the application with the ability to avoid copying the contents. + * + * After the Source has sent the message to the Regulator instance, + * the Source is free to process another input and the Regulator + * instance will ensure that the buffer is delivered to the Delivery + * function and Destination. + * + * The Regulator implementation uses the RTEMS Classic API Partition Manager + * to manage the buffer pool and the RTEMS Classic API Message Queue + * Manager to send the buffer to the Delivery thread. + */ + +#ifndef REGULATOR_H +#define REGULATOR_H + +#include <stdlib.h> + +#include <rtems.h> + +/** + * @ingroup RegulatorAPI + * + * @brief Regulator Delivery Function Type + * + * The user provides a function which is invoked to deliver a message + * to the output. It is invoked by the Delivery thread created as part + * of @a rtems_regulator_create(). The priority and stack size of the + * Delivery thread are specified in the regulator attribute set. + * + * It takes three parameters: + * + * @param[in] context is an untyped pointer to a user context + * @param[in] message points to the message + * @param[in] length is the message size + * + * The following is an example deliverer function. It assumes that the + * application has defined the my_context_t structure and it has at least + * the socket field. The @a message passed in originated with an + * application source which obtained the @a message buffer using + * @a rtems_regulator_obtain_buffer(), filled it in with source data, + * and used @a rtems_regulator_send() to hand to the regulator instance + * for later delivery. + * + * @code + * bool my_deliverer( + * void *context, + * void *message, + * size_t length + * ) + * { + * my_context_t *my_context; + * + * my_context = (my_context_t *)context; + * + * write(my_context->socket, message, length); + * rtems_regulator_release_buffer(message); + * // return false to indicate we released the buffer + * return false; + * } + * @endcode + * + * The delivery function returns true to indicate that the delivery thread + * should release the buffer or false to indicate that it released the + * buffer. If the delivery function invokes a function like @a write() + * to deliver the message to the destination, then the buffer can be + * released immediately after the call. If the delivery function does + * something like setting up a DMA transfer of the buffer, it cannot be + * released until after the DMA is complete. + * + * The following sequence diagram shows the behavior of the Delivery thread + * body and its interaction with the user-supplied deliverer() function. + * + * \startuml "Regulator Delivery Thread Body" + * loop while (1) + * "Delivery Thread" -> RTEMS : rtems_rate_monotonic_period(id, delivery_thread_period) + * loop for 0 : maximum_to_dequeue_per_period + * "Delivery Thread" -> RTEMS : rtems_message_queue_receive(id, message, size, wait, 0) + * RTEMS --> "Delivery Thread" : rtems_status_code + * group if [rtems_status_code != RTEMS_SUCCESSFUL] + * RTEMS -> "Delivery Thread" : break + * end + * "Delivery Thread" -> Application : deliverer(context, buffer, length) + * "Delivery Thread" -> RTEMS : rtems_partition_return_buffer(id, buffer) + * RTEMS --> "Delivery Thread" : rtems_status_code + * end + * end + * \enduml + * + * In the above sequence diagram, the key points are: + * + * -# The Delivery Thread Body is periodically executed. + * -# During each period, up to the instance configuration parameter + * @a maximum_to_dequeue_per_period may be dequeued and + * passed the application's delivery function for processing. + * + * Note that the application explicitly obtains buffers from the + * regulator instance but that the release may be done by Delivery + * Thread, the Delivery function, or later when the buffer contents + * are transferred. + */ +typedef bool (*rtems_regulator_deliverer)( + void *context, + void *message, + size_t length +); + +/** + * @ingroup RegulatorAPI + * + * @brief Attributes for Regulator Instance + * + * An instance of this structure must be populated by the application + * before creating an instance of the regulator. These settings tailor + * the behavior of the regulator instance. + */ +typedef struct { + /** Application function to invoke to output a message to the destination*/ + rtems_regulator_deliverer deliverer; + + /** Context pointer to pass to deliver function */ + void *deliverer_context; + + /** Maximum size message to process */ + size_t maximum_message_size; + + /** Maximum number of messages to be able to buffer */ + size_t maximum_messages; + + /** Priority of Delivery thread */ + rtems_task_priority delivery_thread_priority; + + /** Stack size of Delivery thread */ + size_t delivery_thread_stack_size; + + /** Period (in ticks) of Delivery thread */ + rtems_interval delivery_thread_period; + + /** Maximum messages to dequeue per period */ + size_t maximum_to_dequeue_per_period; + +} rtems_regulator_attributes; + +/** + * @ingroup RegulatorAPI + * + * @brief Statistics for Regulator Instance + * + * An instance of this structure is provided to the directive + * @a rtems_regulator_get_statistics and is filled in by that service. + */ +typedef struct { + /** Number of successfully obtained buffers. */ + size_t obtained; + + /** Number of successfully released buffers. */ + size_t released; + + /** Number of successfully delivered buffers. */ + size_t delivered; + + /** Rate Monotonic Period statistics for Delivery Thread */ + rtems_rate_monotonic_period_statistics period_statistics; + +} rtems_regulator_statistics; + +/** + * @ingroup RegulatorAPI + * + * @brief Regulator Internal Structure + */ +struct _Regulator_Control; + +/** + * @ingroup RegulatorAPI + * + * @brief Regulator Instance + * + * This is used by the application as the handle to a Regulator instance. + */ +typedef struct _Regulator_Control *rtems_regulator_instance; + +/** + * @ingroup RegulatorAPI + * + * @brief Create a regulator + * + * This function creates an instance of a regulator. It uses the provided + * @a attributes to create the instance return in @a regulator. This instance + * will allocate the buffers associated with the regulator instance as well + * as the Delivery thread. + * + * The @a attributes structure defines the priority and stack size of + * the Delivery thread dedicated to this regulator instance. It also + * defines the period of the Delivery thread and the maximum number of + * messages that may be delivered per period via invocation of the + * delivery function. + * + * For each regulator instance, the following resources are allocated: + * + * - A memory area for the regulator control block using @a malloc(). + * - A RTEMS Classic API Message Queue is constructed with message + * buffer memory allocated using @a malloc(). Each message consists + * of a pointer and a length. + * - A RTEMS Classic API Partition. + * - A RTEMS Classic API Rate Monotonic Period. + * + * @param[in] attributes specify the regulator instance attributes + * @param[inout] regulator will point to the regulator instance + * + * @return an RTEMS status code indicating success or failure. + * + * @note This function allocates memory for the buffers holding messages, + * an Delivery thread and an RTEMS partition. When it executes, the + * Delivery thread will create an RTEMS rate monotonic period. + */ +rtems_status_code rtems_regulator_create( + rtems_regulator_attributes *attributes, + rtems_regulator_instance **regulator +); + +/** + * @ingroup RegulatorAPI + * + * @brief Delete a regulator + * + * This function is used to delete the specified @a regulator instance. + * + * It is the responsibility of the user to ensure that any resources + * such as sockets or open file descriptors used by the delivery + * function are also deleted. It is likely safer to delete those + * delivery resources after deleting the regulator instance rather than + * before. + * + * @param[in] regulator is the instance to delete + * @param[in] ticks is the maximum number of ticks to wait for + * the delivery thread to shutdown. + * + * @return an RTEMS status code indicating success or failure. + * + * @note This function deallocates the resources allocated during + * @a rtems_regulator_create(). + */ +rtems_status_code rtems_regulator_delete( + rtems_regulator_instance *regulator, + rtems_interval ticks +); + +/** + * @ingroup RegulatorAPI + * + * @brief Obtain Buffer from Regulator + * + * This function is used to obtain a buffer from the regulator's pool. The + * @a buffer returned is assumed to be filled in with contents and used + * in a subsequent call to @a rtems_regulator_send(). When the @a buffer is + * delivered, it is expected to be released. If the @a buffer is not + * successfully accepted by this function, then it should be returned + * using @a rtems_regulator_release_buffer() or used to send another message. + * + * The @a buffer is of the maximum_message_size specified in the attributes + * passed in to @a rtems_regulator_create(). + * + * @param[in] regulator is the regulator instance to operate upon + * @param[out] buffer will point to the allocated buffer + * + * @return an RTEMS status code indicating success or failure. + * + * @note This function does not perform dynamic allocation. It obtains a + * buffer from the pool allocated during @a rtems_regulator_create(). + * + * @note Any attempt to write outside the buffer area is undefined. + */ +rtems_status_code rtems_regulator_obtain_buffer( + rtems_regulator_instance *regulator, + void **buffer +); + +/** + * @ingroup RegulatorAPI + * + * @brief Release Previously Obtained Regulator Buffer + * + * This function is used to release a buffer to the regulator's pool. It is + * assumed that the @a buffer returned will not be used by the application + * anymore. The @a buffer must have previously been allocated by + * @a rtems_regulator_obtain_buffer() and NOT passed to + * @a rtems_regulator_send(). + * + * If a subsequent @a rtems_regulator_send() using this @a buffer is + * successful, the @a buffer will eventually be processed by the delivery + * thread and released. + * + * @param[in] regulator is the regulator instance to operate upon + * @param[out] buffer will point to the buffer to release + * + * @return an RTEMS status code indicating success or failure. + * + * @note This function does not perform dynamic deallocation. It releases a + * buffer to the pool allocated during @a rtems_regulator_create(). + */ +rtems_status_code rtems_regulator_release_buffer( + rtems_regulator_instance *regulator, + void *buffer +); + +/** + * @ingroup RegulatorAPI + * + * @brief Send to regulator instance + * + * This function is used by the producer to send a @a message to the + * @a regulator for later delivery by the Delivery thread. The message is + * contained in the memory pointed to by @a message and is @a length + * bytes in length. + * + * It is required that the @a message buffer was obtained via + * @a rtems_regulator_obtain_buffer(). + * + * It is assumed that the @a message buffer has been filled in with + * application content to deliver. + * + * If the @a rtems_regulator_send() is successful, the buffer is enqueued + * inside the regulator instance for subsequent delivery. After the + * @a message is delivered, it may be released by either delivery + * function or the application code depending on the implementation. + * + * The status @a RTEMS_TOO_MANY is returned if the regulator's + * internal queue is full. This indicates that the configured + * maximum number of messages was insufficient. It is the + * responsibility of the caller to decide whether to hold messages, + * drop them, or print a message that the maximum number of messages + * should be increased. + * + * If @a rtems_regulator_send() is unsuccessful, it is the application's + * responsibility to release the buffer. If it is successfully sent, + * then it becomes the responsibility of the delivery function to + * release it. + * + * @param[in] regulator is the regulator instance to operate upon + * @param[out] message points to the message to deliver + * @param[out] length is the size of the message in bytes + * + * @return an RTEMS status code indicating success or failure. + * + */ +rtems_status_code rtems_regulator_send( + rtems_regulator_instance *regulator, + void *message, + size_t length +); + +/** + * @ingroup RegulatorAPI + * + * @brief Obtain statistics for regulator instance + * + * This function is used by the application to obtain statistics + * information about the regulator instance. + * + * If the @a obtained and @a released fields in the returned + * @a statistics structure are equal, then there are no buffers + * outstanding from this regulator instance. + * + * @param[in] regulator is the regulator instance to operate upon + * @param[inout] statistics points to the statistics structure to fill in + * + * @return an RTEMS status code indicating success or failure. + * + */ +rtems_status_code rtems_regulator_get_statistics( + rtems_regulator_instance *regulator, + rtems_regulator_statistics *statistics +); + +#endif /* REGULATOR_H */ diff --git a/cpukit/include/rtems/regulatorimpl.h b/cpukit/include/rtems/regulatorimpl.h new file mode 100644 index 0000000000..a5652a764d --- /dev/null +++ b/cpukit/include/rtems/regulatorimpl.h @@ -0,0 +1,135 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup RegulatorInternalAPI + * + * @brief Regulator Library Implementation Support + */ + +/* + * Copyright (C) 2023 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +/** + * @defgroup RegulatorInternalAPI Regulator API Internals + * + * @brief Regulator Internal Information + * + * This concerns implementation information about the Regulator. + */ + +#ifndef RTEMS_REGULATORIMPL_H +#define RTEMS_REGULATORIMPL_H + +#include <stdatomic.h> + +#include <rtems/chain.h> + + +/** + * @ingroup RegulatorInternalAPI + * + * This constant is used to indicate the regulator instance is initialized. + */ +#define REGULATOR_INITIALIZED 0xDeadF00d + +/** + * @ingroup RegulatorInternalAPI + * + * @brief Regulator Message Instance Management Structure + */ +typedef struct { + /** This points to the message contents. */ + void *buffer; + /** This is the length of the message. */ + size_t length; +} _Regulator_Message_t; + +/** + * @ingroup RegulatorInternalAPI + * + * @brief Regulator Statistics Private Structure + * + * An instance of this structure is allocated per regulator instance. + */ +typedef struct { + /** Number of successfully obtained buffers. */ + atomic_size_t obtained; + + /** Number of successfully released buffers. */ + atomic_size_t released; + + /** Number of successfully delivered buffers. */ + atomic_size_t delivered; +} _Regulator_Statistics; + +/** + * @ingroup RegulatorInternalAPI + * + * @brief Regulator Instance Private Structure + * + * An instance of this structure is allocated per regulator instance. + */ +typedef struct { + /** Has magic value when instance is usable */ + uint32_t initialized; + + /** Attributes for this instance -- copied from user */ + rtems_regulator_attributes Attributes; + + /** Pointer to allocated message memory */ + void *message_memory; + + /** Pointer to allocated memory for RTEMS Message Queue for pending buffers*/ + void *message_queue_storage; + + /** RTEMS Message Queue of pending outgoing messages */ + rtems_id queue_id; + + /** RTEMS Partition for pool of unused messages */ + rtems_id messages_partition_id; + + /** RTEMS Task for performing output */ + rtems_id delivery_thread_id; + + /** Id of period used by output thread */ + rtems_id delivery_thread_period_id; + + /** Indicates Delivery thread is running */ + bool delivery_thread_is_running; + + /** Indicates Delivery thread has been requested to exit */ + bool delivery_thread_request_exit; + + /** Indicates Delivery thread has exited */ + bool delivery_thread_has_exited; + + /** Internal Statistics */ + _Regulator_Statistics Statistics; + +} _Regulator_Control; + +#endif /* RTEMS_REGULATORIMPL_H */ diff --git a/cpukit/include/rtems/rtems/asr.h b/cpukit/include/rtems/rtems/asr.h index 1b0af08a0e..1d3ba5fe4f 100644 --- a/cpukit/include/rtems/rtems/asr.h +++ b/cpukit/include/rtems/rtems/asr.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/attr.h b/cpukit/include/rtems/rtems/attr.h index 24b49247ee..708be99b2d 100644 --- a/cpukit/include/rtems/rtems/attr.h +++ b/cpukit/include/rtems/rtems/attr.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2020 embedded brains GmbH & Co. KG * Copyright (C) 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/barrier.h b/cpukit/include/rtems/rtems/barrier.h index 348610d886..029cffb406 100644 --- a/cpukit/include/rtems/rtems/barrier.h +++ b/cpukit/include/rtems/rtems/barrier.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -137,7 +137,7 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * barrier. The number of barriers available to the application is - * configured through the #CONFIGURE_MAXIMUM_BARRIERS application + * configured through the @ref CONFIGURE_MAXIMUM_BARRIERS application * configuration option. * * @par Notes @@ -157,7 +157,7 @@ extern "C" { * cause the calling task to be preempted. * * * The number of barriers available to the application is configured through - * the #CONFIGURE_MAXIMUM_BARRIERS application configuration option. + * the @ref CONFIGURE_MAXIMUM_BARRIERS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/cache.h b/cpukit/include/rtems/rtems/cache.h index e869769393..d59a3fddca 100644 --- a/cpukit/include/rtems/rtems/cache.h +++ b/cpukit/include/rtems/rtems/cache.h @@ -10,7 +10,7 @@ /* * Copyright (C) 2016 Pavel Pisa - * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG * Copyright (C) 2000, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -59,6 +59,7 @@ #include <stddef.h> #include <stdint.h> +#include <rtems/rtems/status.h> #ifdef __cplusplus extern "C" { @@ -89,6 +90,10 @@ extern "C" { * * @param size is the size in bytes of the cache coherent memory area to add. * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_UNSATISFIED The requested operation was not successful. + * * @par Constraints * @parblock * The following constraints apply to this directive: @@ -102,7 +107,7 @@ extern "C" { * cause the calling task to be preempted. * @endparblock */ -void rtems_cache_coherent_add_area( void *begin, uintptr_t size ); +rtems_status_code rtems_cache_coherent_add_area( void *begin, uintptr_t size ); /* Generated from spec:/rtems/cache/if/coherent-allocate */ diff --git a/cpukit/include/rtems/rtems/clock.h b/cpukit/include/rtems/rtems/clock.h index 2f541d46a2..5a8d0a44f9 100644 --- a/cpukit/include/rtems/rtems/clock.h +++ b/cpukit/include/rtems/rtems/clock.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -116,8 +116,8 @@ struct bintime; * before 2100-01-01:00:00.000000000Z. The latest valid time of day accepted * by the POSIX clock_settime() is 2400-01-01T00:00:00.999999999Z. * - * The specified time is based on the configured clock tick rate, see the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The specified time is based on the configured clock tick rate, see the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * Setting the time forward will fire all CLOCK_REALTIME timers which are * scheduled at a time point before or at the time set by the directive. This @@ -853,8 +853,8 @@ rtems_status_code rtems_clock_get_seconds_since_epoch( * application. * * @par Notes - * The number of clock ticks per second is defined indirectly by the - * #CONFIGURE_MICROSECONDS_PER_TICK configuration option. + * The number of clock ticks per second is defined indirectly by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK configuration option. * * @par Constraints * @parblock diff --git a/cpukit/include/rtems/rtems/config.h b/cpukit/include/rtems/rtems/config.h index 4a6e6c8e2e..d225902bf1 100644 --- a/cpukit/include/rtems/rtems/config.h +++ b/cpukit/include/rtems/rtems/config.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -80,7 +80,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Tasks * configured for this application. * - * See #CONFIGURE_MAXIMUM_TASKS. + * See @ref CONFIGURE_MAXIMUM_TASKS. */ uint32_t maximum_tasks; @@ -94,7 +94,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Timers * configured for this application. * - * See #CONFIGURE_MAXIMUM_TIMERS. + * See @ref CONFIGURE_MAXIMUM_TIMERS. */ uint32_t maximum_timers; @@ -102,7 +102,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Semaphores * configured for this application. * - * See #CONFIGURE_MAXIMUM_SEMAPHORES. + * See @ref CONFIGURE_MAXIMUM_SEMAPHORES. */ uint32_t maximum_semaphores; @@ -110,7 +110,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Message Queues * configured for this application. * - * See #CONFIGURE_MAXIMUM_MESSAGE_QUEUES. + * See @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES. */ uint32_t maximum_message_queues; @@ -118,7 +118,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Partitions * configured for this application. * - * See #CONFIGURE_MAXIMUM_PARTITIONS. + * See @ref CONFIGURE_MAXIMUM_PARTITIONS. */ uint32_t maximum_partitions; @@ -126,7 +126,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Regions * configured for this application. * - * See #CONFIGURE_MAXIMUM_REGIONS. + * See @ref CONFIGURE_MAXIMUM_REGIONS. */ uint32_t maximum_regions; @@ -134,7 +134,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Dual-Ported * Memories configured for this application. * - * See #CONFIGURE_MAXIMUM_PORTS. + * See @ref CONFIGURE_MAXIMUM_PORTS. */ uint32_t maximum_ports; @@ -142,7 +142,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Rate Monotonic * Periods configured for this application. * - * See #CONFIGURE_MAXIMUM_PERIODS. + * See @ref CONFIGURE_MAXIMUM_PERIODS. */ uint32_t maximum_periods; @@ -150,7 +150,7 @@ typedef struct { * @brief This member contains the maximum number of Classic API Barriers * configured for this application. * - * See #CONFIGURE_MAXIMUM_BARRIERS. + * See @ref CONFIGURE_MAXIMUM_BARRIERS. */ uint32_t maximum_barriers; @@ -158,7 +158,7 @@ typedef struct { * @brief This member contains the number of Classic API Initialization Tasks * configured for this application. * - * See #CONFIGURE_RTEMS_INIT_TASKS_TABLE. + * See @ref CONFIGURE_RTEMS_INIT_TASKS_TABLE. */ uint32_t number_of_initialization_tasks; @@ -166,7 +166,7 @@ typedef struct { * @brief This member contains the pointer to Classic API Initialization Tasks * Table of this application. * - * See #CONFIGURE_RTEMS_INIT_TASKS_TABLE. + * See @ref CONFIGURE_RTEMS_INIT_TASKS_TABLE. */ const rtems_initialization_tasks_table *User_initialization_tasks_table; } rtems_api_configuration_table; @@ -183,7 +183,7 @@ typedef struct { * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_BARRIERS + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_BARRIERS * application configuration option. See also rtems_resource_is_unlimited() * and rtems_resource_maximum_per_allocation(). * @@ -210,7 +210,7 @@ uint32_t rtems_configuration_get_maximum_barriers( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES * application configuration option. See also rtems_resource_is_unlimited() * and rtems_resource_maximum_per_allocation(). * @@ -237,7 +237,7 @@ uint32_t rtems_configuration_get_maximum_message_queues( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_PARTITIONS + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_PARTITIONS * application configuration option. See also rtems_resource_is_unlimited() * and rtems_resource_maximum_per_allocation(). * @@ -264,9 +264,9 @@ uint32_t rtems_configuration_get_maximum_partitions( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_PERIODS application - * configuration option. See also rtems_resource_is_unlimited() and - * rtems_resource_maximum_per_allocation(). + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_PERIODS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). * * @par Constraints * @parblock @@ -291,9 +291,9 @@ uint32_t rtems_configuration_get_maximum_periods( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_PORTS application - * configuration option. See also rtems_resource_is_unlimited() and - * rtems_resource_maximum_per_allocation(). + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_PORTS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). * * @par Constraints * @parblock @@ -318,9 +318,9 @@ uint32_t rtems_configuration_get_maximum_ports( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_REGIONS application - * configuration option. See also rtems_resource_is_unlimited() and - * rtems_resource_maximum_per_allocation(). + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_REGIONS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). * * @par Constraints * @parblock @@ -345,7 +345,7 @@ uint32_t rtems_configuration_get_maximum_regions( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_SEMAPHORES + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_SEMAPHORES * application configuration option. See also rtems_resource_is_unlimited() * and rtems_resource_maximum_per_allocation(). * @@ -372,9 +372,9 @@ uint32_t rtems_configuration_get_maximum_semaphores( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_TASKS application - * configuration option. See also rtems_resource_is_unlimited() and - * rtems_resource_maximum_per_allocation(). + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_TASKS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). * * @par Constraints * @parblock @@ -399,9 +399,9 @@ uint32_t rtems_configuration_get_maximum_tasks( void ); * configured for this application. * * @par Notes - * The resource number is defined by the #CONFIGURE_MAXIMUM_TIMERS application - * configuration option. See also rtems_resource_is_unlimited() and - * rtems_resource_maximum_per_allocation(). + * The resource number is defined by the @ref CONFIGURE_MAXIMUM_TIMERS + * application configuration option. See also rtems_resource_is_unlimited() + * and rtems_resource_maximum_per_allocation(). * * @par Constraints * @parblock diff --git a/cpukit/include/rtems/rtems/dpmem.h b/cpukit/include/rtems/rtems/dpmem.h index 855ea3ddc6..62e34053ea 100644 --- a/cpukit/include/rtems/rtems/dpmem.h +++ b/cpukit/include/rtems/rtems/dpmem.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -114,7 +114,7 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * port. The number of port available to the application is configured - * through the #CONFIGURE_MAXIMUM_PORTS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_PORTS application configuration option. * * @par Notes * @parblock @@ -138,7 +138,7 @@ extern "C" { * cause the calling task to be preempted. * * * The number of ports available to the application is configured through the - * #CONFIGURE_MAXIMUM_PORTS application configuration option. + * @ref CONFIGURE_MAXIMUM_PORTS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/event.h b/cpukit/include/rtems/rtems/event.h index 8d4424e628..81aa57585f 100644 --- a/cpukit/include/rtems/rtems/event.h +++ b/cpukit/include/rtems/rtems/event.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/intr.h b/cpukit/include/rtems/rtems/intr.h index 021b9e3e94..f682112bf5 100644 --- a/cpukit/include/rtems/rtems/intr.h +++ b/cpukit/include/rtems/rtems/intr.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2008, 2022 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2008, 2022 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -994,6 +994,13 @@ typedef void ( *rtems_interrupt_per_handler_routine )( * rtems_interrupt_entry_initialize(). It may be installed for an interrupt * vector with rtems_interrupt_entry_install() and removed from an interrupt * vector by rtems_interrupt_entry_remove(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock */ typedef struct rtems_interrupt_entry { /** @@ -2077,6 +2084,13 @@ rtems_status_code rtems_interrupt_handler_iterate( * view. Members shall not be accessed directly. The structure is initialized * by rtems_interrupt_server_create() and maintained by the interrupt server * support. + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock */ typedef struct rtems_interrupt_server_control { #if defined(RTEMS_SMP) @@ -2127,6 +2141,13 @@ typedef struct rtems_interrupt_server_control { * * @par Notes * See also rtems_interrupt_server_create(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock */ typedef struct { /** @@ -2715,6 +2736,13 @@ rtems_status_code rtems_interrupt_server_handler_iterate( * @par Notes * This structure shall be treated as an opaque data type from the API point of * view. Members shall not be accessed directly. + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock */ typedef struct rtems_interrupt_server_action { /** @@ -2747,6 +2775,13 @@ typedef struct rtems_interrupt_server_action { * rtems_interrupt_server_entry_destroy(). Interrupt server actions can be * prepended to the entry by rtems_interrupt_server_action_prepend(). The * entry is submitted to be serviced by rtems_interrupt_server_entry_submit(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock */ typedef struct { /** @@ -3041,6 +3076,13 @@ rtems_status_code rtems_interrupt_server_entry_move( * request can be set by rtems_interrupt_server_request_set_vector(). The * request is submitted to be serviced by * rtems_interrupt_server_request_submit(). + * + * @par Constraints + * @parblock + * The following constraints apply to this structure: + * + * * Members of the type shall not be accessed directly by the application. + * @endparblock */ typedef struct { /** diff --git a/cpukit/include/rtems/rtems/mainpage.h b/cpukit/include/rtems/rtems/mainpage.h deleted file mode 100644 index 313f4303c6..0000000000 --- a/cpukit/include/rtems/rtems/mainpage.h +++ /dev/null @@ -1,948 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/** - * @file - * - * This file exists to provide a top level description of RTEMS for Doxygen. - */ - -/* - * COPYRIGHT (c) 1989-2014. - * On-Line Applications Research Corporation (OAR). - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -/** - * @mainpage - * - * The RTEMS real-time operating systems is a layered system with each of the - * public APIs implemented in terms of a common foundation layer called the - * SuperCore. This is the Doxygen generated documentation for the RTEMS CPU - * Kit including the Classic API, POSIX API and SuperCore. - */ - -/** - * @page RTEMSPreface RTEMS History and Introduction - * - * In recent years, the cost required to develop a software product has - * increased significantly while the target hardware costs have decreased. Now - * a larger portion of money is expended in developing, using, and maintaining - * software. The trend in computing costs is the complete dominance of software - * over hardware costs. Because of this, it is necessary that formal - * disciplines be established to increase the probability that software is - * characterized by a high degree of correctness, maintainability, and - * portability. In addition, these disciplines must promote practices that aid - * in the consistent and orderly development of a software system within - * schedule and budgetary constraints. To be effective, these disciplines must - * adopt standards which channel individual software efforts toward a common - * goal. - * - * The push for standards in the software development field has been met with - * various degrees of success. The Microprocessor Operating Systems Interfaces - * (MOSI) effort has experienced only limited success. As popular as the UNIX - * operating system has grown, the attempt to develop a standard interface - * definition to allow portable application development has only recently begun - * to produce the results needed in this area. Unfortunately, very little - * effort has been expended to provide standards addressing the needs of the - * real-time community. Several organizations have addressed this need during - * recent years. - * - * The Real Time Executive Interface Definition (RTEID) was developed by - * Motorola with technical input from Software Components Group. RTEID was - * adopted by the VMEbus International Trade Association (VITA) as a baseline - * draft for their proposed standard multiprocessor, real-time executive - * interface, Open Real-Time Kernel Interface Definition (ORKID). These two - * groups are currently working together with the IEEE P1003.4 committee to - * insure that the functionality of their proposed standards is adopted as the - * real-time extensions to POSIX. - * - * This emerging standard defines an interface for the development of real-time - * software to ease the writing of real-time application programs that are - * directly portable across multiple real-time executive implementations. This - * interface includes both the source code interfaces and run-time behavior as - * seen by a real-time application. It does not include the details of how a - * kernel implements these functions. The standard's goal is to serve as a - * complete definition of external interfaces so that application code that - * conforms to these interfaces will execute properly in all real-time - * executive environments. With the use of a standards compliant executive, - * routines that acquire memory blocks, create and manage message queues, - * establish and use semaphores, and send and receive signals need not be - * redeveloped for a different real-time environment as long as the new - * environment is compliant with the standard. Software developers need only - * concentrate on the hardware dependencies of the real-time system. - * Furthermore, most hardware dependencies for real-time applications can be - * localized to the device drivers. - * - * A compliant executive provides simple and flexible real-time - * multiprocessing. It easily lends itself to both tightly-coupled and - * loosely-coupled configurations (depending on the system hardware - * configuration). Objects such as tasks, queues, events, signals, semaphores, - * and memory blocks can be designated as global objects and accessed by any - * task regardless of which processor the object and the accessing task reside. - * - * The acceptance of a standard for real-time executives will produce the same - * advantages enjoyed from the push for UNIX standardization by AT&T's System V - * Interface Definition and IEEE's POSIX efforts. A compliant multiprocessing - * executive will allow close coupling between UNIX systems and real-time - * executives to provide the many benefits of the UNIX development environment - * to be applied to real-time software development. Together they provide the - * necessary laboratory environment to implement real-time, distributed, - * embedded systems using a wide variety of computer architectures. - * - * A study was completed in 1988, within the Research, Development, and - * Engineering Center, U.S. Army Missile Command, which compared the various - * aspects of the Ada programming language as they related to the application - * of Ada code in distributed and/or multiple processing systems. Several - * critical conclusions were derived from the study. These conclusions have a - * major impact on the way the Army develops application software for embedded - * applications. These impacts apply to both in-house software development and - * contractor developed software. - * - * A conclusion of the analysis, which has been previously recognized by other - * agencies attempting to utilize Ada in a distributed or multiprocessing - * environment, is that the Ada programming language does not adequately - * support multiprocessing. Ada does provide a mechanism for multi-tasking, - * however, this capability exists only for a single processor system. The - * language also does not have inherent capabilities to access global named - * variables, flags or program code. These critical features are essential in - * order for data to be shared between processors. However, these drawbacks do - * have workarounds which are sometimes awkward and defeat the intent of - * software maintainability and portability goals. - * - * Another conclusion drawn from the analysis, was that the run time executives - * being delivered with the Ada compilers were too slow and inefficient to be - * used in modern missile systems. A run time executive is the core part of the - * run time system code, or operating system code, that controls task - * scheduling, input/output management and memory management. Traditionally, - * whenever efficient executive (also known as kernel) code was required by the - * application, the user developed in-house software. This software was usually - * written in assembly language for optimization. - * - * Because of this shortcoming in the Ada programming language, software - * developers in research and development and contractors for project managed - * systems, are mandated by technology to purchase and utilize off-the-shelf - * third party kernel code. The contractor, and eventually the Government, must - * pay a licensing fee for every copy of the kernel code used in an embedded - * system. - * - * The main drawback to this development environment is that the Government - * does not own, nor has the right to modify code contained within the kernel. - * V&V techniques in this situation are more difficult than if the complete - * source code were available. Responsibility for system failures due to faulty - * software is yet another area to be resolved under this environment. - * - * The Guidance and Control Directorate began a software development effort to - * address these problems. A project to develop an experimental run time kernel - * was begun that will eliminate the major drawbacks of the Ada programming - * language mentioned above. The Real Time Executive for Multiprocessor Systems - * (RTEMS) provides full capabilities for management of tasks, interrupts, - * time, and multiple processors in addition to those features typical of - * generic operating systems. The code is Government owned, so no licensing - * fees are necessary. RTEMS has been implemented in both the Ada and C - * programming languages. It has been ported to the following processor - * families: - * - * - Altera NIOS II - * - Analog Devices Blackfin - * - ARM - * - Freescale (formerly Motorola) MC68xxx - * - Freescale (formerly Motorola) MC683xx - * - Freescale (formerly Motorola) ColdFire - * - Intel i386 and above - * - Lattice Semiconductor LM32 - * - MIPS - * - PowerPC - * - Renesas (formerly Hitachi) SuperH - * - Renesas (formerly Hitachi) H8/300 - * - SPARC - * - Texas Instruments C3x/C4x - * - UNIX - * - * Support for other processor families, including RISC, CISC, and DSP, is - * planned. Since almost all of RTEMS is written in a high level language, - * ports to additional processor families require minimal effort. - * - * RTEMS multiprocessor support is capable of handling either homogeneous or - * heterogeneous systems. The kernel automatically compensates for - * architectural differences (byte swapping, etc.) between processors. This - * allows a much easier transition from one processor family to another without - * a major system redesign. - * - * Since the proposed standards are still in draft form, RTEMS cannot and does - * not claim compliance. However, the status of the standard is being carefully - * monitored to guarantee that RTEMS provides the functionality specified in - * the standard. Once approved, RTEMS will be made compliant. - */ - -/** - * @page RTEMSOverview RTEMS Overview - * - * @section RTEMSOverviewSecIntroduction Introduction - * - * RTEMS, Real-Time Executive for Multiprocessor Systems, is a real-time - * executive (kernel) which provides a high performance environment for - * embedded military applications including the following features: - * - * - multitasking capabilities - * - homogeneous and heterogeneous multiprocessor systems - * - event-driven, priority-based, preemptive scheduling - * - optional rate monotonic scheduling - * - intertask communication and synchronization - * - priority inheritance - * - responsive interrupt management - * - dynamic memory allocation - * - high level of user configurability - * - * This manual describes the usage of RTEMS for applications written in the C - * programming language. Those implementation details that are processor - * dependent are provided in the Applications Supplement documents. A - * supplement document which addresses specific architectural issues that - * affect RTEMS is provided for each processor type that is supported. - * - * @section RTEMSOverviewSecRealtimeApplicationSystems Real-time Application Systems - * - * Real-time application systems are a special class of computer applications. - * They have a complex set of characteristics that distinguish them from other - * software problems. Generally, they must adhere to more rigorous - * requirements. The correctness of the system depends not only on the results - * of computations, but also on the time at which the results are produced. The - * most important and complex characteristic of real-time application systems - * is that they must receive and respond to a set of external stimuli within - * rigid and critical time constraints referred to as deadlines. Systems can be - * buried by an avalanche of interdependent, asynchronous or cyclical event - * streams. - * - * Deadlines can be further characterized as either hard or soft based upon the - * value of the results when produced after the deadline has passed. A deadline - * is hard if the results have no value or if their use will result in a - * catastrophic event. In contrast, results which are produced after a soft - * deadline may have some value. - * - * Another distinguishing requirement of real-time application systems is the - * ability to coordinate or manage a large number of concurrent activities. - * Since software is a synchronous entity, this presents special problems. One - * instruction follows another in a repeating synchronous cycle. Even though - * mechanisms have been developed to allow for the processing of external - * asynchronous events, the software design efforts required to process and - * manage these events and tasks are growing more complicated. - * - * The design process is complicated further by spreading this activity over a - * set of processors instead of a single processor. The challenges associated - * with designing and building real-time application systems become very - * complex when multiple processors are involved. New requirements such as - * interprocessor communication channels and global resources that must be - * shared between competing processors are introduced. The ramifications of - * multiple processors complicate each and every characteristic of a real-time - * system. - * - * @section RTEMSOverviewSecRealtimeExecutive Real-time Executive - * - * Fortunately, real-time operating systems or real-time executives serve as a - * cornerstone on which to build the application system. A real-time - * multitasking executive allows an application to be cast into a set of - * logical, autonomous processes or tasks which become quite manageable. Each - * task is internally synchronous, but different tasks execute independently, - * resulting in an asynchronous processing stream. Tasks can be dynamically - * paused for many reasons resulting in a different task being allowed to - * execute for a period of time. The executive also provides an interface to - * other system components such as interrupt handlers and device drivers. - * System components may request the executive to allocate and coordinate - * resources, and to wait for and trigger synchronizing conditions. The - * executive system calls effectively extend the CPU instruction set to support - * efficient multitasking. By causing tasks to travel through well-defined - * state transitions, system calls permit an application to demand-switch - * between tasks in response to real-time events. - * - * By proper grouping of responses to stimuli into separate tasks, a system can - * now asynchronously switch between independent streams of execution, directly - * responding to external stimuli as they occur. This allows the system design - * to meet critical performance specifications which are typically measured by - * guaranteed response time and transaction throughput. The multiprocessor - * extensions of RTEMS provide the features necessary to manage the extra - * requirements introduced by a system distributed across several processors. - * It removes the physical barriers of processor boundaries from the world of - * the system designer, enabling more critical aspects of the system to receive - * the required attention. Such a system, based on an efficient real-time, - * multiprocessor executive, is a more realistic model of the outside world or - * environment for which it is designed. As a result, the system will always be - * more logical, efficient, and reliable. - * - * By using the directives provided by RTEMS, the real-time applications - * developer is freed from the problem of controlling and synchronizing - * multiple tasks and processors. In addition, one need not develop, test, - * debug, and document routines to manage memory, pass messages, or provide - * mutual exclusion. The developer is then able to concentrate solely on the - * application. By using standard software components, the time and cost - * required to develop sophisticated real-time applications is significantly - * reduced. - * - * @section RTEMSOverviewSecApplicationArchitecture RTEMS Application Architecture - * - * One important design goal of RTEMS was to provide a bridge between two - * critical layers of typical real-time systems. As shown in the following - * figure, RTEMS serves as a buffer between the project dependent application - * code and the target hardware. Most hardware dependencies for real-time - * applications can be localized to the low level device drivers. - * - * @todo Image RTEMS Application Architecture - * - * The RTEMS I/O interface manager provides an efficient tool for incorporating - * these hardware dependencies into the system while simultaneously providing a - * general mechanism to the application code that accesses them. A well - * designed real-time system can benefit from this architecture by building a - * rich library of standard application components which can be used repeatedly - * in other real-time projects. - * - * @section RTEMSOverviewSecInternalArchitecture RTEMS Internal Architecture - * - * RTEMS can be viewed as a set of layered components that work in harmony to - * provide a set of services to a real-time application system. The executive - * interface presented to the application is formed by grouping directives into - * logical sets called resource managers. Functions utilized by multiple - * managers such as scheduling, dispatching, and object management are provided - * in the executive core. The executive core depends on a small set of CPU - * dependent routines. Together these components provide a powerful run time - * environment that promotes the development of efficient real-time application - * systems. The following figure illustrates this organization: - * - * @todo Image RTEMS Architecture - * - * Subsequent chapters present a detailed description of the capabilities - * provided by each of the following RTEMS managers: - * - * - initialization - * - task - * - interrupt - * - clock - * - timer - * - semaphore - * - message - * - event - * - signal - * - partition - * - region - * - dual ported memory - * - I/O - * - fatal error - * - rate monotonic - * - user extensions - * - multiprocessing - * - * @section RTEMSOverviewSecUserCustomization User Customization and Extensibility - * - * As 32-bit microprocessors have decreased in cost, they have become - * increasingly common in a variety of embedded systems. A wide range of custom - * and general-purpose processor boards are based on various 32-bit - * processors. RTEMS was designed to make no assumptions concerning the - * characteristics of individual microprocessor families or of specific support - * hardware. In addition, RTEMS allows the system developer a high degree of - * freedom in customizing and extending its features. - * - * RTEMS assumes the existence of a supported microprocessor and sufficient - * memory for both RTEMS and the real-time application. Board dependent - * components such as clocks, interrupt controllers, or I/O devices can be - * easily integrated with RTEMS. The customization and extensibility features - * allow RTEMS to efficiently support as many environments as possible. - * - * @section RTEMSOverviewSecPortability Portability - * - * The issue of portability was the major factor in the creation of RTEMS. - * Since RTEMS is designed to isolate the hardware dependencies in the specific - * board support packages, the real-time application should be easily ported to - * any other processor. The use of RTEMS allows the development of real-time - * applications which can be completely independent of a particular - * microprocessor architecture. - * - * @section RTEMSOverviewSecMemoryRequirements Memory Requirements - * - * Since memory is a critical resource in many real-time embedded systems, - * RTEMS was specifically designed to automatically leave out all services that - * are not required from the run-time environment. Features such as networking, - * various filesystems, and many other features are completely optional. This - * allows the application designer the flexibility to tailor RTEMS to most - * efficiently meet system requirements while still satisfying even the most - * stringent memory constraints. As a result, the size of the RTEMS executive - * is application dependent. - * - * RTEMS requires RAM to manage each instance of an RTEMS object that is - * created. Thus the more RTEMS objects an application needs, the more memory - * that must be reserved. See Configuring a System Determining Memory - * Requirements for more details. - * - * @todo Link to Configuring a SystemDetermining Memory Requirements - * - * RTEMS utilizes memory for both code and data space. Although RTEMS' data - * space must be in RAM, its code space can be located in either ROM or RAM. - * - * @section RTEMSOverviewSecAudience Audience - * - * This manual was written for experienced real-time software developers. - * Although some background is provided, it is assumed that the reader is - * familiar with the concepts of task management as well as intertask - * communication and synchronization. Since directives, user related data - * structures, and examples are presented in C, a basic understanding of the C - * programming language is required to fully understand the material presented. - * However, because of the similarity of the Ada and C RTEMS implementations, - * users will find that the use and behavior of the two implementations is very - * similar. A working knowledge of the target processor is helpful in - * understanding some of RTEMS' features. A thorough understanding of the - * executive cannot be obtained without studying the entire manual because many - * of RTEMS' concepts and features are interrelated. Experienced RTEMS users - * will find that the manual organization facilitates its use as a reference - * document. - */ - -/** - * @addtogroup RTEMSAPIClassic - * - * The facilities provided by RTEMS are built upon a foundation of very - * powerful concepts. These concepts must be understood before the application - * developer can efficiently utilize RTEMS. The purpose of this chapter is to - * familiarize one with these concepts. - * - * @section ClassicRTEMSSecObjects Objects - * - * RTEMS provides directives which can be used to dynamically create, delete, - * and manipulate a set of predefined object types. These types include tasks, - * message queues, semaphores, memory regions, memory partitions, timers, - * ports, and rate monotonic periods. The object-oriented nature of RTEMS - * encourages the creation of modular applications built upon re-usable - * "building block" routines. - * - * All objects are created on the local node as required by the application and - * have an RTEMS assigned ID. All objects have a user-assigned name. Although a - * relationship exists between an object's name and its RTEMS assigned ID, the - * name and ID are not identical. Object names are completely arbitrary and - * selected by the user as a meaningful "tag" which may commonly reflect the - * object's use in the application. Conversely, object IDs are designed to - * facilitate efficient object manipulation by the executive. - * - * @subsection ClassicRTEMSSubSecObjectNames Object Names - * - * An object name is an unsigned 32-bit entity associated with the - * object by the user. The data type @ref rtems_name is used to store object names. - * - * Although not required by RTEMS, object names are often composed of four - * ASCII characters which help identify that object. For example, a task which - * causes a light to blink might be called "LITE". The rtems_build_name() - * routine is provided to build an object name from four ASCII characters. The - * following example illustrates this: - * - * @code - * rtems_name my_name = rtems_build_name('L', 'I', 'T', 'E'); - * @endcode - * - * However, it is not required that the application use ASCII characters to - * build object names. For example, if an application requires one-hundred - * tasks, it would be difficult to assign meaningful ASCII names to each task. - * A more convenient approach would be to name them the binary values one - * through one-hundred, respectively. - * - * RTEMS provides a helper routine, rtems_object_get_name(), which can be used to - * obtain the name of any RTEMS object using just its ID. This routine attempts - * to convert the name into a printable string. - * - * @subsection ClassicRTEMSSubSecObjectIdentifiers Object Identifiers - * - * An object ID is a unique unsigned integer value which uniquely identifies an - * object instance. Object IDs are passed as arguments to many directives in - * RTEMS and RTEMS translates the ID to an internal object pointer. The - * efficient manipulation of object IDs is critical to the performance of RTEMS - * services. Because of this, there are two object ID formats defined. Each - * target architecture specifies which format it will use. There is a 32-bit - * format which is used for most of the supported architectures and supports - * multiprocessor configurations. There is also a simpler 16-bit format which - * is appropriate for smaller target architectures and does not support - * multiprocessor configurations. - * - * @subsubsection ClassicRTEMSSubSec32BitObjectIdentifierFormat 32-Bit Object Identifier Format - * - * The 32-bit format for an object ID is composed of four parts: API, - * object class, node, and index. The data type @ref rtems_id is used to store - * object IDs. - * - * <table> - * <tr> - * <th>Bits</th> - * <td>31</td><td>30</td><td>29</td><td>28</td><td>27</td><td>26</td><td>25</td><td>24</td> - * <td>23</td><td>22</td><td>21</td><td>20</td><td>19</td><td>18</td><td>17</td><td>16</td> - * <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td> - * <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td> - * </tr> - * <tr> - * <th>Contents</th> - * <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Node</td><td colspan=16>Object Index</td> - * </tr> - * </table> - * - * The most significant five bits are the object class. The next three bits - * indicate the API to which the object class belongs. The next eight bits - * (16 .. 23) are the number of the node on which this object was created. The - * node number is always one (1) in a single processor system. The least - * significant 16-bits form an identifier within a particular object type. - * This identifier, called the object index, ranges in value from one to the - * maximum number of objects configured for this object type. - * - * @subsubsection ClassicRTEMSSubSec16BitObjectIdentifierFormat 16-Bit Object Identifier Format - * - * The 16-bit format for an object ID is composed of three parts: API, object - * class, and index. The data type @ref rtems_id is used to store object IDs. - * - * <table> - * <tr> - * <th>Bits</th> - * <td>15</td><td>14</td><td>13</td><td>12</td><td>11</td><td>10</td><td>09</td><td>08</td> - * <td>07</td><td>06</td><td>05</td><td>04</td><td>03</td><td>02</td><td>01</td><td>00</td> - * </tr> - * <tr> - * <th>Contents</th> - * <td colspan=5>Class</td><td colspan=3>API</td><td colspan=8>Object Index</td> - * </tr> - * </table> - * - * The 16-bit format is designed to be as similar as possible to the 32-bit - * format. The differences are limited to the elimination of the node field - * and reduction of the index field from 16-bits to 8-bits. Thus the 16-bit - * format only supports up to 255 object instances per API/Class combination - * and single processor systems. As this format is typically utilized by 16-bit - * processors with limited address space, this is more than enough object - * instances. - * - * @subsection ClassicRTEMSSubSecObjectIdentiferDescription Object Identifer Description - * - * The components of an object ID make it possible to quickly locate any object - * in even the most complicated multiprocessor system. Object ID's are - * associated with an object by RTEMS when the object is created and the - * corresponding ID is returned by the appropriate object create directive. The - * object ID is required as input to all directives involving objects, except - * those which create an object or obtain the ID of an object. - * - * The object identification directives can be used to dynamically obtain a - * particular object's ID given its name. This mapping is accomplished by - * searching the name table associated with this object type. If the name is - * non-unique, then the ID associated with the first occurrence of the name - * will be returned to the application. Since object IDs are returned when the - * object is created, the object identification directives are not necessary in - * a properly designed single processor application. - * - * In addition, services are provided to portably examine the subcomponents of - * an RTEMS ID. These services are described in detail later in this manual but - * are prototyped as follows: - * - * - rtems_object_id_get_api() - * - rtems_object_id_get_class() - * - rtems_object_id_get_node() - * - rtems_object_id_get_index() - * - * An object control block is a data structure defined by RTEMS which contains - * the information necessary to manage a particular object type. For efficiency - * reasons, the format of each object type's control block is different. - * However, many of the fields are similar in function. The number of each type - * of control block is application dependent and determined by the values - * specified in the user's Configuration Table. An object control block is - * allocated at object create time and freed when the object is deleted. With - * the exception of user extension routines, object control blocks are not - * directly manipulated by user applications. - * - * @section ClassicRTEMSSecComSync Communication and Synchronization - * - * In real-time multitasking applications, the ability for cooperating - * execution threads to communicate and synchronize with each other is - * imperative. A real-time executive should provide an application with the - * following capabilities - * - * - data transfer between cooperating tasks, - * - data transfer between tasks and ISRs, - * - synchronization of cooperating tasks, and - * - synchronization of tasks and ISRs. - * - * Most RTEMS managers can be used to provide some form of communication and/or - * synchronization. However, managers dedicated specifically to communication - * and synchronization provide well established mechanisms which directly map - * to the application's varying needs. This level of flexibility allows the - * application designer to match the features of a particular manager with the - * complexity of communication and synchronization required. The following - * managers were specifically designed for communication and synchronization: - * - * - @ref ClassicSem - * - @ref ClassicMessageQueue - * - @ref ClassicEvent - * - @ref ClassicSignal - * - * The semaphore manager supports mutual exclusion involving the - * synchronization of access to one or more shared user resources. Binary - * semaphores may utilize the optional priority inheritance algorithm to avoid - * the problem of priority inversion. The message manager supports both - * communication and synchronization, while the event manager primarily - * provides a high performance synchronization mechanism. The signal manager - * supports only asynchronous communication and is typically used for exception - * handling. - * - * @section ClassicRTEMSSecTime Time - * - * The development of responsive real-time applications requires an - * understanding of how RTEMS maintains and supports time-related operations. - * The basic unit of time in RTEMS is known as a tick. The frequency of clock - * ticks is completely application dependent and determines the granularity and - * accuracy of all interval and calendar time operations. - * - * By tracking time in units of ticks, RTEMS is capable of supporting interval - * timing functions such as task delays, timeouts, timeslicing, the delayed - * execution of timer service routines, and the rate monotonic scheduling of - * tasks. An interval is defined as a number of ticks relative to the current - * time. For example, when a task delays for an interval of ten ticks, it is - * implied that the task will not execute until ten clock ticks have occurred. - * All intervals are specified using data type @ref rtems_interval. - * - * A characteristic of interval timing is that the actual interval period may - * be a fraction of a tick less than the interval requested. This occurs - * because the time at which the delay timer is set up occurs at some time - * between two clock ticks. Therefore, the first countdown tick occurs in less - * than the complete time interval for a tick. This can be a problem if the - * clock granularity is large. - * - * The rate monotonic scheduling algorithm is a hard real-time scheduling - * methodology. This methodology provides rules which allows one to guarantee - * that a set of independent periodic tasks will always meet their deadlines -- - * even under transient overload conditions. The rate monotonic manager - * provides directives built upon the Clock Manager's interval timer support - * routines. - * - * Interval timing is not sufficient for the many applications which require - * that time be kept in wall time or true calendar form. Consequently, RTEMS - * maintains the current date and time. This allows selected time operations to - * be scheduled at an actual calendar date and time. For example, a task could - * request to delay until midnight on New Year's Eve before lowering the ball - * at Times Square. The data type @ref rtems_time_of_day is used to specify - * calendar time in RTEMS services. See Clock Manager Time and Date Data - * Structures. - * - * @todo Link to Clock Manager Time and Date Data Structures - * - * Obviously, the directives which use intervals or wall time cannot operate - * without some external mechanism which provides a periodic clock tick. This - * clock tick is typically provided by a real time clock or counter/timer - * device. - * - * @section ClassicRTEMSSecMemoryManagement Memory Management - * - * RTEMS memory management facilities can be grouped into two classes: dynamic - * memory allocation and address translation. Dynamic memory allocation is - * required by applications whose memory requirements vary through the - * application's course of execution. Address translation is needed by - * applications which share memory with another CPU or an intelligent - * Input/Output processor. The following RTEMS managers provide facilities to - * manage memory: - * - * - @ref ClassicRegion - * - @ref ClassicPart - * - @ref ClassicDPMEM - * - * RTEMS memory management features allow an application to create simple - * memory pools of fixed size buffers and/or more complex memory pools of - * variable size segments. The partition manager provides directives to manage - * and maintain pools of fixed size entities such as resource control blocks. - * Alternatively, the region manager provides a more general purpose memory - * allocation scheme that supports variable size blocks of memory which are - * dynamically obtained and freed by the application. The dual-ported memory - * manager provides executive support for address translation between internal - * and external dual-ported RAM address space. - */ - -/** - * @addtogroup RTEMSAPIClassicTasks - * - * @section ClassicTasksSecTaskDefinition Task Definition - * - * Many definitions of a task have been proposed in computer literature. - * Unfortunately, none of these definitions encompasses all facets of the - * concept in a manner which is operating system independent. Several of the - * more common definitions are provided to enable each user to select a - * definition which best matches their own experience and understanding of the - * task concept: - * - * - a "dispatchable" unit. - * - an entity to which the processor is allocated. - * - an atomic unit of a real-time, multiprocessor system. - * - single threads of execution which concurrently compete for resources. - * - a sequence of closely related computations which can execute concurrently - * with other computational sequences. - * - * From RTEMS' perspective, a task is the smallest thread of execution which - * can compete on its own for system resources. A task is manifested by the - * existence of a task control block (TCB). - * - * @section ClassicTasksSecTaskControlBlock Task Control Block - * - * The Task Control Block (TCB) is an RTEMS defined data structure which - * contains all the information that is pertinent to the execution of a task. - * During system initialization, RTEMS reserves a TCB for each task configured. - * A TCB is allocated upon creation of the task and is returned to the TCB free - * list upon deletion of the task. - * - * The TCB's elements are modified as a result of system calls made by the - * application in response to external and internal stimuli. TCBs are the only - * RTEMS internal data structure that can be accessed by an application via - * user extension routines. The TCB contains a task's name, ID, current - * priority, current and starting states, execution mode, TCB user extension - * pointer, scheduling control structures, as well as data required by a - * blocked task. - * - * A task's context is stored in the TCB when a task switch occurs. When the - * task regains control of the processor, its context is restored from the TCB. - * When a task is restarted, the initial state of the task is restored from the - * starting context area in the task's TCB. - * - * @section ClassicTasksSecTaskStates Task States - * - * A task may exist in one of the following five states: - * - * - executing - Currently scheduled to the CPU - * - ready - May be scheduled to the CPU - * - blocked - Unable to be scheduled to the CPU - * - dormant - Created task that is not started - * - non-existent - Uncreated or deleted task - * - * An active task may occupy the executing, ready, blocked or dormant state, - * otherwise the task is considered non-existent. One or more tasks may be - * active in the system simultaneously. Multiple tasks communicate, - * synchronize, and compete for system resources with each other via system - * calls. The multiple tasks appear to execute in parallel, but actually each - * is dispatched to the CPU for periods of time determined by the RTEMS - * scheduling algorithm. The scheduling of a task is based on its current state - * and priority. - * - * @section ClassicTasksSecTaskPriority Task Priority - * - * A task's priority determines its importance in relation to the other tasks - * executing on the same processor. RTEMS supports 255 levels of priority - * ranging from 1 to 255. The data type rtems_task_priority() is used to store - * task priorities. - * - * Tasks of numerically smaller priority values are more important tasks than - * tasks of numerically larger priority values. For example, a task at priority - * level 5 is of higher privilege than a task at priority level 10. There is no - * limit to the number of tasks assigned to the same priority. - * - * Each task has a priority associated with it at all times. The initial value - * of this priority is assigned at task creation time. The priority of a task - * may be changed at any subsequent time. - * - * Priorities are used by the scheduler to determine which ready task will be - * allowed to execute. In general, the higher the logical priority of a task, - * the more likely it is to receive processor execution time. - * - * @section ClassicTasksSecTaskMode Task Mode - * - * A task's execution mode is a combination of the following four components: - * - * - preemption - * - ASR processing - * - timeslicing - * - interrupt level - * - * It is used to modify RTEMS' scheduling process and to alter the execution - * environment of the task. The data type rtems_task_mode() is used to manage - * the task execution mode. - * - * The preemption component allows a task to determine when control of the - * processor is relinquished. If preemption is disabled (@c - * RTEMS_NO_PREEMPT), the task will retain control of the - * processor as long as it is in the executing state -- even if a higher - * priority task is made ready. If preemption is enabled (@c RTEMS_PREEMPT) - * and a higher priority task is made ready, then the processor will be - * taken away from the current task immediately and given to the higher - * priority task. - * - * The timeslicing component is used by the RTEMS scheduler to determine how - * the processor is allocated to tasks of equal priority. If timeslicing is - * enabled (@c RTEMS_TIMESLICE), then RTEMS will limit the amount of time the - * task can execute before the processor is allocated to another ready task of - * equal priority. The length of the timeslice is application dependent and - * specified in the Configuration Table. If timeslicing is disabled (@c - * RTEMS_NO_TIMESLICE), then the task will be allowed to - * execute until a task of higher priority is made ready. If @c - * RTEMS_NO_PREEMPT is selected, then the timeslicing component is ignored by - * the scheduler. - * - * The asynchronous signal processing component is used to determine when - * received signals are to be processed by the task. If signal processing is - * enabled (@c RTEMS_ASR), then signals sent to the task will be processed - * the next time the task executes. If signal processing is disabled (@c - * RTEMS_NO_ASR), then all signals received by the task will - * remain posted until signal processing is enabled. This component affects - * only tasks which have established a routine to process asynchronous signals. - * - * The interrupt level component is used to determine which interrupts will be - * enabled when the task is executing. @c RTEMS_INTERRUPT_LEVEL(n) specifies - * that the task will execute at interrupt level n. - * - * - @ref RTEMS_PREEMPT - enable preemption (default) - * - @ref RTEMS_NO_PREEMPT - disable preemption - * - @ref RTEMS_NO_TIMESLICE - disable timeslicing (default) - * - @ref RTEMS_TIMESLICE - enable timeslicing - * - @ref RTEMS_ASR - enable ASR processing (default) - * - @ref RTEMS_NO_ASR - disable ASR processing - * - @ref RTEMS_INTERRUPT_LEVEL(0) - enable all interrupts (default) - * - @ref RTEMS_INTERRUPT_LEVEL(n) - execute at interrupt level n - * - * The set of default modes may be selected by specifying the @ref - * RTEMS_DEFAULT_MODES constant. - * - * @section ClassicTasksSecAccessingTaskArguments Accessing Task Arguments - * - * All RTEMS tasks are invoked with a single argument which is specified when - * they are started or restarted. The argument is commonly used to communicate - * startup information to the task. The simplest manner in which to define a - * task which accesses it argument is: - * - * @code - * rtems_task user_task( - * rtems_task_argument argument - * ); - * @endcode - * - * Application tasks requiring more information may view this single argument - * as an index into an array of parameter blocks. - * - * @section ClassicTasksSecFloatingPointConsiderations Floating Point Considerations - * - * Creating a task with the @ref RTEMS_FLOATING_POINT attribute flag results in - * additional memory being allocated for the TCB to store the state of the - * numeric coprocessor during task switches. This additional memory is NOT - * allocated for @ref RTEMS_NO_FLOATING_POINT tasks. Saving and restoring the - * context of a @c RTEMS_FLOATING_POINT task takes longer than that of a @c - * RTEMS_NO_FLOATING_POINT task because of the relatively large amount of time - * required for the numeric coprocessor to save or restore its computational - * state. - * - * Since RTEMS was designed specifically for embedded military applications - * which are floating point intensive, the executive is optimized to avoid - * unnecessarily saving and restoring the state of the numeric coprocessor. The - * state of the numeric coprocessor is only saved when a @c - * RTEMS_FLOATING_POINT task is dispatched and that task was not the last task - * to utilize the coprocessor. In a system with only one @c - * RTEMS_FLOATING_POINT task, the state of the numeric coprocessor will never - * be saved or restored. - * - * Although the overhead imposed by @c RTEMS_FLOATING_POINT tasks is minimal, - * some applications may wish to completely avoid the overhead associated with - * @c RTEMS_FLOATING_POINT tasks and still utilize a numeric coprocessor. By - * preventing a task from being preempted while performing a sequence of - * floating point operations, a @c RTEMS_NO_FLOATING_POINT task can utilize - * the numeric coprocessor without incurring the overhead of a @c - * RTEMS_FLOATING_POINT context switch. This approach also avoids the - * allocation of a floating point context area. However, if this approach is - * taken by the application designer, NO tasks should be created as @c - * RTEMS_FLOATING_POINT tasks. Otherwise, the floating point context will not - * be correctly maintained because RTEMS assumes that the state of the numeric - * coprocessor will not be altered by @c RTEMS_NO_FLOATING_POINT tasks. - * - * If the supported processor type does not have hardware floating capabilities - * or a standard numeric coprocessor, RTEMS will not provide built-in support - * for hardware floating point on that processor. In this case, all tasks are - * considered @c RTEMS_NO_FLOATING_POINT whether created as @c - * RTEMS_FLOATING_POINT or @c RTEMS_NO_FLOATING_POINT tasks. A floating point - * emulation software library must be utilized for floating point operations. - * - * On some processors, it is possible to disable the floating point unit - * dynamically. If this capability is supported by the target processor, then - * RTEMS will utilize this capability to enable the floating point unit only - * for tasks which are created with the @c RTEMS_FLOATING_POINT attribute. - * The consequence of a @c RTEMS_NO_FLOATING_POINT task attempting to access - * the floating point unit is CPU dependent but will generally result in an - * exception condition. - * - * @section ClassicTasksSecPerTaskVariables Per Task Variables - * - * Per task variables are no longer available. In particular the - * rtems_task_variable_add(), rtems_task_variable_get() and - * rtems_task_variable_delete() functions are neither declared nor defined - * anymore. Use thread local storage or POSIX Keys instead. - * - * @section ClassicTasksSecBuildingTaskAttributeSet Building a Task Attribute Set - * - * In general, an attribute set is built by a bitwise OR of the desired - * components. The set of valid task attribute components is listed below: - * - * - @ref RTEMS_NO_FLOATING_POINT - does not use coprocessor (default) - * - @ref RTEMS_FLOATING_POINT - uses numeric coprocessor - * - @ref RTEMS_LOCAL - local task (default) - * - @ref RTEMS_GLOBAL - global task - * - * Attribute values are specifically designed to be mutually exclusive, - * therefore bitwise OR and addition operations are equivalent as long as each - * attribute appears exactly once in the component list. A component listed as - * a default is not required to appear in the component list, although it is a - * good programming practice to specify default components. If all defaults are - * desired, then @ref RTEMS_DEFAULT_ATTRIBUTES should be used. This example - * demonstrates the attribute_set parameter needed to create a local task which - * utilizes the numeric coprocessor. The attribute_set parameter could be @c - * RTEMS_FLOATING_POINT or @c RTEMS_LOCAL | @c RTEMS_FLOATING_POINT. The - * attribute_set parameter can be set to @c RTEMS_FLOATING_POINT because @c - * RTEMS_LOCAL is the default for all created tasks. If the task were global - * and used the numeric coprocessor, then the attribute_set parameter would be - * @c RTEMS_GLOBAL | @c RTEMS_FLOATING_POINT. - * - * @section ClassicTasksSecBuildingModeAndMask Building a Mode and Mask - * - * In general, a mode and its corresponding mask is built by a bitwise OR of - * the desired components. The set of valid mode constants and each mode's - * corresponding mask constant is listed below: - * - * <table> - * <tr><th>Mode Constant</th><th>Mask Constant</th><th>Description</th></tr> - * <tr><td>@ref RTEMS_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>enables preemption</td></tr> - * <tr><td>@ref RTEMS_NO_PREEMPT</td><td>@ref RTEMS_PREEMPT_MASK</td><td>disables preemption</td></tr> - * <tr><td>@ref RTEMS_NO_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>disables timeslicing</td></tr> - * <tr><td>@ref RTEMS_TIMESLICE</td><td>@ref RTEMS_TIMESLICE_MASK</td><td>enables timeslicing</td></tr> - * <tr><td>@ref RTEMS_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>enables ASR processing</td></tr> - * <tr><td>@ref RTEMS_NO_ASR</td><td>@ref RTEMS_ASR_MASK</td><td>disables ASR processing</td></tr> - * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(0)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>enables all interrupts</td></tr> - * <tr><td>@ref RTEMS_INTERRUPT_LEVEL(n)</td><td>@ref RTEMS_INTERRUPT_MASK</td><td>sets interrupts level n</td></tr> - * </table> - * - * Mode values are specifically designed to be mutually exclusive, therefore - * bitwise OR and addition operations are equivalent as long as each mode - * appears exactly once in the component list. A mode component listed as a - * default is not required to appear in the mode component list, although it is - * a good programming practice to specify default components. If all defaults - * are desired, the mode @ref RTEMS_DEFAULT_MODES and the mask @ref - * RTEMS_ALL_MODE_MASKS should be used. - * - * The following example demonstrates the mode and mask parameters used with - * the rtems_task_mode() directive to place a task at interrupt level 3 and - * make it non-preemptible. The mode should be set to @c - * RTEMS_INTERRUPT_LEVEL(3) | @c RTEMS_NO_PREEMPT to indicate the desired - * preemption mode and interrupt level, while the mask parameter should be set - * to @c RTEMS_INTERRUPT_MASK | @c RTEMS_PREEMPT_MASK to indicate that - * the calling task's interrupt level and preemption mode are being altered. - */ - - /** - * @defgroup LocalPackages Local Packages - * - * @ingroup RTEMSAPIClassic - * - * @brief Local packages. - */ diff --git a/cpukit/include/rtems/rtems/message.h b/cpukit/include/rtems/rtems/message.h index 4f2bb69500..0967430934 100644 --- a/cpukit/include/rtems/rtems/message.h +++ b/cpukit/include/rtems/rtems/message.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -212,14 +212,14 @@ typedef struct { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * message queue. The number of message queue available to the application - * is configured through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application - * configuration option. + * is configured through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES + * application configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global message queue. The * number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * * @retval ::RTEMS_INVALID_NUMBER The product of ``count`` and * ``max_message_size`` is greater than the maximum storage size. @@ -260,16 +260,16 @@ typedef struct { * message to remote nodes. This may preempt the calling task. * * * The number of message queues available to the application is configured - * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration - * option. + * through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES application + * configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_message_queue_create( @@ -288,7 +288,8 @@ rtems_status_code rtems_message_queue_create( * @brief Constructs a message queue from the specified the message queue * configuration. * - * @param config is the message queue configuration. + * @param config is the pointer to an rtems_message_queue_config object. It + * configures the message queue. * * @param[out] id is the pointer to an ::rtems_id object. When the directive * call is successful, the identifier of the constructed message queue will @@ -342,8 +343,8 @@ rtems_status_code rtems_message_queue_create( * runtime memory allocators. This can simplify the application architecture * as well as any analysis that may be required. * - * The value for #CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory for - * message queues constructed by rtems_message_queue_construct(). + * The value for @ref CONFIGURE_MESSAGE_BUFFER_MEMORY should not include memory + * for message queues constructed by rtems_message_queue_construct(). * @endparblock * * @par Constraints @@ -362,16 +363,16 @@ rtems_status_code rtems_message_queue_create( * message to remote nodes. This may preempt the calling task. * * * The number of message queues available to the application is configured - * through the #CONFIGURE_MAXIMUM_MESSAGE_QUEUES application configuration - * option. + * through the @ref CONFIGURE_MAXIMUM_MESSAGE_QUEUES application + * configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_message_queue_construct( diff --git a/cpukit/include/rtems/rtems/modes.h b/cpukit/include/rtems/rtems/modes.h index 038a84676d..f348941b24 100644 --- a/cpukit/include/rtems/rtems/modes.h +++ b/cpukit/include/rtems/rtems/modes.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/mp.h b/cpukit/include/rtems/rtems/mp.h index 614a65fe4c..5852f43381 100644 --- a/cpukit/include/rtems/rtems/mp.h +++ b/cpukit/include/rtems/rtems/mp.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/object.h b/cpukit/include/rtems/rtems/object.h index 02b8ef01e2..bda9a469ed 100644 --- a/cpukit/include/rtems/rtems/object.h +++ b/cpukit/include/rtems/rtems/object.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2009 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/objectimpl.h b/cpukit/include/rtems/rtems/objectimpl.h index fc93d1aa3b..b17a6ed4d6 100644 --- a/cpukit/include/rtems/rtems/objectimpl.h +++ b/cpukit/include/rtems/rtems/objectimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/rtems/options.h b/cpukit/include/rtems/rtems/options.h index 5328c383b5..44a8d6ccb8 100644 --- a/cpukit/include/rtems/rtems/options.h +++ b/cpukit/include/rtems/rtems/options.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/part.h b/cpukit/include/rtems/rtems/part.h index 10091b48f4..8c7b0b5ef3 100644 --- a/cpukit/include/rtems/rtems/part.h +++ b/cpukit/include/rtems/rtems/part.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -168,13 +168,13 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * partition. The number of partitions available to the application is - * configured through the #CONFIGURE_MAXIMUM_PARTITIONS application + * configured through the @ref CONFIGURE_MAXIMUM_PARTITIONS application * configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global semaphore. The number * of global objects available to the application is configured through the - * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @par Notes * @parblock @@ -220,7 +220,7 @@ extern "C" { * message to remote nodes. This may preempt the calling task. * * * The number of partitions available to the application is configured - * through the #CONFIGURE_MAXIMUM_PARTITIONS application configuration + * through the @ref CONFIGURE_MAXIMUM_PARTITIONS application configuration * option. * * * Where the object class corresponding to the directive is configured to use @@ -228,8 +228,8 @@ extern "C" { * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_partition_create( diff --git a/cpukit/include/rtems/rtems/partdata.h b/cpukit/include/rtems/rtems/partdata.h index 864c47294e..6df4af81c5 100644 --- a/cpukit/include/rtems/rtems/partdata.h +++ b/cpukit/include/rtems/rtems/partdata.h @@ -116,6 +116,8 @@ typedef struct { extern Objects_Information _Partition_Information; #if defined(RTEMS_MULTIPROCESSING) +struct _Thread_Control; + /** * @brief Sends the extract proxy request. * @@ -126,8 +128,8 @@ extern Objects_Information _Partition_Information; * @param id is the partition identifier. */ void _Partition_MP_Send_extract_proxy ( - Thread_Control *the_thread, - Objects_Id id + struct _Thread_Control *the_thread, + Objects_Id id ); #endif diff --git a/cpukit/include/rtems/rtems/ratemon.h b/cpukit/include/rtems/rtems/ratemon.h index 7c789a204b..4b9255e635 100644 --- a/cpukit/include/rtems/rtems/ratemon.h +++ b/cpukit/include/rtems/rtems/ratemon.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 2017 Kuan-Hsun Chen * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * @@ -245,7 +245,8 @@ struct rtems_printer; * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * period. The number of periods available to the application is configured - * through the #CONFIGURE_MAXIMUM_PERIODS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_PERIODS application configuration + * option. * * @par Notes * @parblock @@ -269,7 +270,7 @@ struct rtems_printer; * cause the calling task to be preempted. * * * The number of periods available to the application is configured through - * the #CONFIGURE_MAXIMUM_PERIODS application configuration option. + * the @ref CONFIGURE_MAXIMUM_PERIODS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/ratemonimpl.h b/cpukit/include/rtems/rtems/ratemonimpl.h index 3874fd4884..191e83f305 100644 --- a/cpukit/include/rtems/rtems/ratemonimpl.h +++ b/cpukit/include/rtems/rtems/ratemonimpl.h @@ -11,7 +11,7 @@ /* COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). - * Copyright (c) 2016 embedded brains GmbH. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * COPYRIGHT (c) 2016 Kuan-Hsun Chen. * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/region.h b/cpukit/include/rtems/rtems/region.h index 94a8d7008f..3d9c2bd8bc 100644 --- a/cpukit/include/rtems/rtems/region.h +++ b/cpukit/include/rtems/rtems/region.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -195,7 +195,8 @@ rtems_status_code rtems_region_get_segment_size( * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * region. The number of regions available to the application is configured - * through the #CONFIGURE_MAXIMUM_REGIONS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_REGIONS application configuration + * option. * * @retval ::RTEMS_INVALID_SIZE The ``page_size`` parameter was invalid. * @@ -219,7 +220,7 @@ rtems_status_code rtems_region_get_segment_size( * cause the calling task to be preempted. * * * The number of regions available to the application is configured through - * the #CONFIGURE_MAXIMUM_REGIONS application configuration option. + * the @ref CONFIGURE_MAXIMUM_REGIONS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/scheduler.h b/cpukit/include/rtems/rtems/scheduler.h index 8bd041558f..bec4932c6c 100644 --- a/cpukit/include/rtems/rtems/scheduler.h +++ b/cpukit/include/rtems/rtems/scheduler.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2013, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2013, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -383,8 +383,8 @@ uint32_t rtems_scheduler_get_processor( void ); * * Where the system was built with SMP support enabled, this directive returns * the minimum of the processors (physically or virtually) available at the - * target and the configured processor maximum (see - * #CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from + * target and the configured processor maximum (see @ref + * CONFIGURE_MAXIMUM_PROCESSORS). Not all processors in the range from * processor index zero to the last processor index (which is the processor * maximum minus one) may be configured to be used by a scheduler or may be * online (online processors have a scheduler assigned). diff --git a/cpukit/include/rtems/rtems/sem.h b/cpukit/include/rtems/rtems/sem.h index 31156b5e43..73e725f82d 100644 --- a/cpukit/include/rtems/rtems/sem.h +++ b/cpukit/include/rtems/rtems/sem.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -203,13 +203,13 @@ extern "C" { * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * semaphore. The number of semaphores available to the application is - * configured through the #CONFIGURE_MAXIMUM_SEMAPHORES application + * configured through the @ref CONFIGURE_MAXIMUM_SEMAPHORES application * configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global semaphore. The number * of global objects available to the application is configured through the - * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @retval ::RTEMS_INVALID_PRIORITY The ``priority_ceiling`` parameter was * invalid. @@ -243,7 +243,7 @@ extern "C" { * message to remote nodes. This may preempt the calling task. * * * The number of semaphores available to the application is configured - * through the #CONFIGURE_MAXIMUM_SEMAPHORES application configuration + * through the @ref CONFIGURE_MAXIMUM_SEMAPHORES application configuration * option. * * * Where the object class corresponding to the directive is configured to use @@ -251,8 +251,8 @@ extern "C" { * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_semaphore_create( diff --git a/cpukit/include/rtems/rtems/signal.h b/cpukit/include/rtems/rtems/signal.h index 9272f807bc..fb5254f5d9 100644 --- a/cpukit/include/rtems/rtems/signal.h +++ b/cpukit/include/rtems/rtems/signal.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/status.h b/cpukit/include/rtems/rtems/status.h index 29bcb27dc1..92a8b03c09 100644 --- a/cpukit/include/rtems/rtems/status.h +++ b/cpukit/include/rtems/rtems/status.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2014, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2014, 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/rtems/support.h b/cpukit/include/rtems/rtems/support.h index 356e29739b..bb2e6e3633 100644 --- a/cpukit/include/rtems/rtems/support.h +++ b/cpukit/include/rtems/rtems/support.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -115,8 +115,8 @@ static inline bool rtems_is_name_valid( rtems_name name ) * value. * * @par Notes - * The number of clock ticks per second is defined by the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The number of clock ticks per second is defined by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * @par Constraints * @parblock @@ -166,8 +166,8 @@ static inline bool rtems_is_name_valid( rtems_name name ) * @return Returns the number of clock ticks for the milliseconds value. * * @par Notes - * The number of clock ticks per second is defined by the - * #CONFIGURE_MICROSECONDS_PER_TICK application configuration option. + * The number of clock ticks per second is defined by the @ref + * CONFIGURE_MICROSECONDS_PER_TICK application configuration option. * * @par Constraints * @parblock diff --git a/cpukit/include/rtems/rtems/tasks.h b/cpukit/include/rtems/rtems/tasks.h index 6d643b7fbe..84dd646fe7 100644 --- a/cpukit/include/rtems/rtems/tasks.h +++ b/cpukit/include/rtems/rtems/tasks.h @@ -9,8 +9,8 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) - * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG + * Copyright (C) 1988, 2023 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -160,8 +160,8 @@ typedef struct { * alignment of an application executable. * * The application may configure the maximum thread-local storage size for all - * threads explicitly through the #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE - * configuration option. + * threads explicitly through the @ref + * CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE configuration option. */ size_t maximum_thread_local_storage_size; @@ -234,7 +234,7 @@ typedef void rtems_task; /** * @ingroup RTEMSAPIClassicTasks * - * @brief This type defines the entry point of an RTEMS task. + * @brief This type defines the task entry point of an RTEMS task. */ typedef rtems_task ( *rtems_task_entry )( rtems_task_argument ); @@ -325,8 +325,8 @@ rtems_task_priority _RTEMS_Maximum_priority( void ); * risk of blown stacks for most user applications. Using this constant when * specifying the task stack size, indicates that the stack size will be at * least RTEMS_MINIMUM_STACK_SIZE bytes in size. If the user configured - * minimum stack size (see #CONFIGURE_MINIMUM_TASK_STACK_SIZE) is larger than - * the recommended minimum, then it will be used. + * minimum stack size (see @ref CONFIGURE_MINIMUM_TASK_STACK_SIZE) is larger + * than the recommended minimum, then it will be used. */ #define RTEMS_MINIMUM_STACK_SIZE STACK_MINIMUM_SIZE @@ -454,8 +454,8 @@ typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); * The **stack size** of the task is specified in ``stack_size``. If the * requested stack size is less than the configured minimum stack size, then * RTEMS will use the configured minimum as the stack size for this task. The - * configured minimum stack size is defined by the - * #CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In + * configured minimum stack size is defined by the @ref + * CONFIGURE_MINIMUM_TASK_STACK_SIZE application configuration option. In * addition to being able to specify the task stack size as a integer, there * are two constants which may be specified: * @@ -583,12 +583,12 @@ typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * task. The number of tasks available to the application is configured - * through the #CONFIGURE_MAXIMUM_TASKS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * @retval ::RTEMS_TOO_MANY In multiprocessing configurations, there was no * inactive global object available to create a global task. The number of - * global objects available to the application is configured through the - * #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. + * global objects available to the application is configured through the @ref + * CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration option. * * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task * storage area. The task storage area contains the task stack, the @@ -615,7 +615,7 @@ typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); * The task stack size shall account for an target processor dependent * interrupt stack frame which may be placed on the stack of the interrupted * task while servicing an interrupt. The stack checker may be used to monitor - * the stack usage, see #CONFIGURE_STACK_CHECKER_ENABLED. + * the stack usage, see @ref CONFIGURE_STACK_CHECKER_ENABLED. * * For control and maintenance of the task, RTEMS allocates a TCB from the * local TCB free pool and initializes it. @@ -644,15 +644,15 @@ typedef bool( *rtems_task_visitor )( rtems_tcb *, void * ); * message to remote nodes. This may preempt the calling task. * * * The number of tasks available to the application is configured through the - * #CONFIGURE_MAXIMUM_TASKS application configuration option. + * @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_task_create( @@ -671,7 +671,8 @@ rtems_status_code rtems_task_create( * * @brief Constructs a task from the specified task configuration. * - * @param config is the task configuration. + * @param config is the pointer to an rtems_task_config object. It configures + * the task. * * @param[out] id is the pointer to an ::rtems_id object. When the directive * call is successful, the identifier of the constructed task will be stored @@ -690,12 +691,13 @@ rtems_status_code rtems_task_create( * @retval ::RTEMS_INVALID_SIZE The thread-local storage size is greater than * the maximum thread-local storage size specified in the task configuration. * The thread-local storage size is determined by the thread-local variables - * used by the application and #CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE. + * used by the application and @ref + * CONFIGURE_MAXIMUM_THREAD_LOCAL_STORAGE_SIZE. * * @retval ::RTEMS_INVALID_SIZE The task storage area was too small to provide - * a task stack of the configured minimum size, see - * #CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the - * task stack, the thread-local storage, and the floating-point context on + * a task stack of the configured minimum size, see @ref + * CONFIGURE_MINIMUM_TASK_STACK_SIZE. The task storage area contains the task + * stack, the thread-local storage, and the floating-point context on * architectures with a separate floating-point context. * * @retval ::RTEMS_TOO_MANY There was no inactive task object available to @@ -734,13 +736,13 @@ rtems_status_code rtems_task_create( * memory allocators. This can simplify the application architecture as well * as any analysis that may be required. * - * The stack space estimate done by <rtems/confdefs.h> assumes that all tasks - * are created by rtems_task_create(). The estimate can be adjusted to take - * user-provided task storage areas into account through the - * #CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application - * configuration option. + * The stack space estimate done by ``<rtems/confdefs.h>`` assumes that all + * tasks are created by rtems_task_create(). The estimate can be adjusted to + * take user-provided task storage areas into account through the @ref + * CONFIGURE_MINIMUM_TASKS_WITH_USER_PROVIDED_STORAGE application configuration + * option. * - * The #CONFIGURE_MAXIMUM_TASKS should include tasks constructed by + * The @ref CONFIGURE_MAXIMUM_TASKS should include tasks constructed by * rtems_task_construct(). * @endparblock * @@ -760,15 +762,15 @@ rtems_status_code rtems_task_create( * message to remote nodes. This may preempt the calling task. * * * The number of tasks available to the application is configured through the - * #CONFIGURE_MAXIMUM_TASKS application configuration option. + * @ref CONFIGURE_MAXIMUM_TASKS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS * Workspace. * * * The number of global objects available to the application is configured - * through the #CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application configuration - * option. + * through the @ref CONFIGURE_MP_MAXIMUM_GLOBAL_OBJECTS application + * configuration option. * @endparblock */ rtems_status_code rtems_task_construct( @@ -895,8 +897,8 @@ rtems_id rtems_task_self( void ); * * This directive readies the task, specified by ``id``, for execution based on * the priority and execution mode specified when the task was created. The - * entry point of the task is given in ``entry_point``. The task's entry point - * argument is contained in ``argument``. + * task entry point of the task is given in ``entry_point``. The task's entry + * point argument is contained in ``argument``. * * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * @@ -1542,15 +1544,16 @@ rtems_status_code rtems_task_mode( /** * @ingroup RTEMSAPIClassicTasks * - * @brief Wakes up after an interval in clock ticks or yields the processor. + * @brief Wakes up after a count of clock ticks have occurred or yields the + * processor. * - * @param ticks is the interval in clock ticks to delay the task or + * @param ticks is the count of clock ticks to delay the task or * #RTEMS_YIELD_PROCESSOR to yield the processor. * - * This directive blocks the calling task for the specified ``ticks`` of clock - * ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the - * requested interval has elapsed, the task is made ready. The clock tick - * directives automatically updates the delay period. The calling task may + * This directive blocks the calling task for the specified ``ticks`` count of + * clock ticks if the value is not equal to #RTEMS_YIELD_PROCESSOR. When the + * requested count of ticks have occurred, the task is made ready. The clock + * tick directives automatically update the delay period. The calling task may * give up the processor and remain in the ready state by specifying a value of * #RTEMS_YIELD_PROCESSOR in ``ticks``. * @@ -1559,7 +1562,11 @@ rtems_status_code rtems_task_mode( * @par Notes * Setting the system date and time with the rtems_clock_set() directive and * similar directives which set CLOCK_REALTIME have no effect on a - * rtems_task_wake_after() blocked task. + * rtems_task_wake_after() blocked task. The delay until first clock tick will + * never be a whole clock tick interval since this directive will never execute + * exactly on a clock tick. Applications requiring use of a clock + * (CLOCK_REALTIME or CLOCK_MONOTONIC) instead of clock ticks should make use + * of clock_nanosleep(). * * @par Constraints * @parblock diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h index 0f13c04bda..6af56c1576 100644 --- a/cpukit/include/rtems/rtems/timer.h +++ b/cpukit/include/rtems/rtems/timer.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -284,7 +284,8 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem * * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a * timer. The number of timers available to the application is configured - * through the #CONFIGURE_MAXIMUM_TIMERS application configuration option. + * through the @ref CONFIGURE_MAXIMUM_TIMERS application configuration + * option. * * @par Notes * @parblock @@ -308,7 +309,7 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtem * cause the calling task to be preempted. * * * The number of timers available to the application is configured through - * the #CONFIGURE_MAXIMUM_TIMERS application configuration option. + * the @ref CONFIGURE_MAXIMUM_TIMERS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS @@ -600,7 +601,7 @@ rtems_status_code rtems_timer_fire_when( * * The directive may be called from within task context. * * * The number of timers available to the application is configured through - * the #CONFIGURE_MAXIMUM_TIMERS application configuration option. + * the @ref CONFIGURE_MAXIMUM_TIMERS application configuration option. * * * Where the object class corresponding to the directive is configured to use * unlimited objects, the directive may allocate memory from the RTEMS diff --git a/cpukit/include/rtems/rtems/timerdata.h b/cpukit/include/rtems/rtems/timerdata.h index 83beea2c19..c66659fe4a 100644 --- a/cpukit/include/rtems/rtems/timerdata.h +++ b/cpukit/include/rtems/rtems/timerdata.h @@ -13,7 +13,7 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2009, 2016 embedded brains GmbH. + * Copyright (C) 2009, 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/rtems/timerimpl.h b/cpukit/include/rtems/rtems/timerimpl.h index 8bb95c3be1..5941616d61 100644 --- a/cpukit/include/rtems/rtems/timerimpl.h +++ b/cpukit/include/rtems/rtems/timerimpl.h @@ -13,7 +13,7 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2016 embedded brains GmbH. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/rtems/types.h b/cpukit/include/rtems/rtems/types.h index 1dd5f8da86..8f85def7c5 100644 --- a/cpukit/include/rtems/rtems/types.h +++ b/cpukit/include/rtems/rtems/types.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2009, 2021 embedded brains GmbH & Co. KG * Copyright (C) 1988, 2017 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without @@ -62,12 +62,12 @@ #include <sys/cpuset.h> #include <rtems/rtems/modes.h> #include <rtems/score/cpuopts.h> -#include <rtems/score/mppkt.h> #include <rtems/score/object.h> #include <rtems/score/watchdogticks.h> #if defined(RTEMS_MULTIPROCESSING) #include <rtems/score/mpci.h> + #include <rtems/score/mppkt.h> #endif #ifdef __cplusplus diff --git a/cpukit/include/rtems/rtl/rtl-allocator.h b/cpukit/include/rtems/rtl/rtl-allocator.h index 8ffaf58c3c..7d291c65f4 100644 --- a/cpukit/include/rtems/rtl/rtl-allocator.h +++ b/cpukit/include/rtems/rtl/rtl-allocator.h @@ -1,7 +1,7 @@ /* SPDX-License-Identifier: BSD-2-Clause */ /* - * COPYRIGHT (c) 2012, 2018 Chris Johns <chrisj@rtems.org> + * COPYRIGHT (c) 2012, 2018, 2023 Chris Johns <chrisj@rtems.org> * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -69,6 +69,7 @@ typedef enum rtems_rtl_alloc_tags rtems_rtl_alloc_tag; enum rtems_rtl_alloc_cmd { RTEMS_RTL_ALLOC_NEW, /**< Allocate new memory. */ RTEMS_RTL_ALLOC_DEL, /**< Delete allocated memory. */ + RTEMS_RTL_ALLOC_RESIZE, /**< Resize allocated memory. */ RTEMS_RTL_ALLOC_LOCK, /**< Lock the allocator. */ RTEMS_RTL_ALLOC_UNLOCK, /**< Unlock the allocator. */ RTEMS_RTL_ALLOC_WR_ENABLE, /**< Enable writes to the memory. */ @@ -143,6 +144,25 @@ void* rtems_rtl_alloc_new (rtems_rtl_alloc_tag tag, size_t size, bool zero); void rtems_rtl_alloc_del (rtems_rtl_alloc_tag tag, void* address); /** + * The Runtime Loader allocator resize resizes allocated memory. + * + * This call resizes a previously allocated block of memory. If the + * provided address cannot be resized it is deleted and a new block is + * allocated and the contents of the existing memory is copied. + * + * + * @param tag The type of allocation request. + * @param address The memory address to resize. A NULL is ignored. + * @param size The size of the allocation. + * @param zero If true the memory is cleared. + * @return void* The memory address or NULL is not memory available. + */ +void* rtems_rtl_alloc_resize (rtems_rtl_alloc_tag tag, + void* address, + size_t size, + bool zero); + +/** * The Runtime Loader allocator lock. An allocator that depends on a * separate allocation process, for example the heap, may need to be * locked during loading of an object file to make sure the locality @@ -267,6 +287,30 @@ bool rtems_rtl_alloc_module_new (void** text_base, size_t text_size, void** bss_base, size_t bss_size); /** + * Resize the allocated memory for a module given the new size of the text, + * const, data and bss sections. If any part of the allocation fails the + * allocated is deleted. + * + * @param text_base Pointer to the text base pointer. + * @param text_size The size of the read/exec section. + * @param const_base Pointer to the const base pointer. + * @param const_size The size of the read only section. + * @param eh_base Pointer to the eh base pointer. + * @param eh_size The size of the eh section. + * @param data_base Pointer to the data base pointer. + * @param data_size The size of the read/write secton. + * @param bss_base Pointer to the bss base pointer. + * @param bss_size The size of the read/write. + * @retval true The memory has been allocated. + * @retval false The allocation of memory has failed. + */ +bool rtems_rtl_alloc_module_resize (void** text_base, size_t text_size, + void** const_base, size_t const_size, + void** eh_base, size_t eh_size, + void** data_base, size_t data_size, + void** bss_base, size_t bss_size); + +/** * Free the memory allocated to a module. * * @param text_base Pointer to the text base pointer. diff --git a/cpukit/include/rtems/rtl/rtl-obj.h b/cpukit/include/rtems/rtl/rtl-obj.h index 6b47eb1205..3523958bfd 100644 --- a/cpukit/include/rtems/rtl/rtl-obj.h +++ b/cpukit/include/rtems/rtl/rtl-obj.h @@ -198,65 +198,66 @@ typedef bool (*rtems_rtl_obj_depends_iterator) (rtems_rtl_obj* obj, */ struct rtems_rtl_obj { - rtems_chain_node link; /**< The node's link in the chain. */ - uint32_t flags; /**< The status of the object file. */ - size_t users; /**< Users of this object file, number of loads. */ - size_t refs; /**< References to the object file. */ - int format; /**< The format of the object file. */ - const char* fname; /**< The file name for the object. */ - const char* oname; /**< The object file name. Can be - * relative. */ - const char* aname; /**< The archive name containing the - * object. NULL means the object is not - * in a lib */ - off_t ooffset; /**< The object offset in the archive. */ - size_t fsize; /**< Size of the object file. */ - rtems_chain_control sections; /**< The sections of interest in the object - * file. */ - rtems_chain_control dependents; /**< The dependent object files. */ - rtems_rtl_obj_sym* local_table; /**< Local symbol table. */ - size_t local_syms; /**< Local symbol count. */ - size_t local_size; /**< Local symbol memory usage. */ - rtems_rtl_obj_sym* global_table; /**< Global symbol table. */ - size_t global_syms; /**< Global symbol count. */ - size_t global_size; /**< Global symbol memory usage. */ - size_t unresolved; /**< The number of unresolved relocations. */ - void* text_base; /**< The base address of the text section - * in memory. */ - size_t text_size; /**< The size of the text section. */ - void* const_base; /**< The base address of the const section - * in memory. */ - size_t const_size; /**< The size of the const section. */ - void* eh_base; /**< The base address of the eh section in - * memory. */ - size_t eh_size; /**< The size of the eh section. */ - void* data_base; /**< The base address of the data section - * in memory. */ - size_t data_size; /**< The size of the data section. */ - void* bss_base; /**< The base address of the bss section in - * memory. */ - size_t bss_size; /**< The size of the bss section. */ - size_t exec_size; /**< The amount of executable memory - * allocated */ - void* entry; /**< The entry point of the module. */ - uint32_t checksum; /**< The checksum of the text sections. A - * zero means do not checksum. */ - uint32_t* sec_num; /**< The sec nums of each obj. */ - uint32_t obj_num; /**< The count of elf files in an rtl - * obj. */ - void* trampoline; /**< Trampoline memory. Used for fixups or - * veneers */ - size_t tramp_size; /**< Size of a tramopline slot. */ - size_t tramps_size; /**< Size of the trampoline memory. */ - void* tramp_brk; /**< Trampoline memory allocator. MD - * relocators can take memory from the - * break up to the size. */ - size_t tramp_relocs; /**< Number of slots reserved for - * relocs. The remainder are for - * unresolved symbols. */ - struct link_map* linkmap; /**< For GDB. */ - void* loader; /**< The file details specific to a - * loader. */ + rtems_chain_node link; /**< The node's link in the chain. */ + uint32_t flags; /**< The status of the object file. */ + size_t users; /**< Users of this object file, number of loads. */ + size_t refs; /**< References to the object file. */ + int format; /**< The format of the object file. */ + const char* fname; /**< The file name for the object. */ + const char* oname; /**< The object file name. Can be + * relative. */ + const char* aname; /**< The archive name containing the + * object. NULL means the object is not + * in a lib */ + off_t ooffset; /**< The object offset in the archive. */ + size_t fsize; /**< Size of the object file. */ + rtems_chain_control sections; /**< The sections of interest in the object + * file. */ + rtems_chain_control dependents; /**< The dependent object files. */ + rtems_rtl_obj_sym* local_table; /**< Local symbol table. */ + size_t local_syms; /**< Local symbol count. */ + size_t local_size; /**< Local symbol memory usage. */ + rtems_rtl_obj_sym* global_table; /**< Global symbol table. */ + size_t global_syms; /**< Global symbol count. */ + size_t global_size; /**< Global symbol memory usage. */ + size_t unresolved; /**< The number of unresolved relocations. */ + void* text_base; /**< The base address of the text section + * in memory. */ + size_t text_size; /**< The size of the text section. */ + void* const_base; /**< The base address of the const section + * in memory. */ + size_t const_size; /**< The size of the const section. */ + void* eh_base; /**< The base address of the eh section in + * memory. */ + size_t eh_size; /**< The size of the eh section. */ + void* data_base; /**< The base address of the data section + * in memory. */ + size_t data_size; /**< The size of the data section. */ + void* bss_base; /**< The base address of the bss section in + * memory. */ + size_t bss_size; /**< The size of the bss section. */ + size_t exec_size; /**< The amount of executable memory + * allocated */ + void* entry; /**< The entry point of the module. */ + uint32_t checksum; /**< The checksum of the text sections. A + * zero means do not checksum. */ + uint32_t* sec_num; /**< The sec nums of each obj. */ + uint32_t obj_num; /**< The count of elf files in an rtl + * obj. */ + void* tramp_base; /**< Trampoline memory. Used for fixups or + * veneers */ + size_t tramp_size; /**< Size of a trampoline memory. */ + size_t tramp_slots; /**< The number of tampoline slots. */ + size_t tramp_slot_size; /**< The number of tampoline slots. */ + void* tramp_brk; /**< Trampoline memory allocator. MD + * relocators can take memory from the + * break up to the size. */ + size_t tramp_relocs; /**< Number of slots reserved for + * relocs. The remainder are for + * unresolved symbols. */ + struct link_map* linkmap; /**< For GDB. */ + void* loader; /**< The file details specific to a + * loader. */ }; /** @@ -387,6 +388,17 @@ static inline bool rtems_rtl_obj_has_symbol (const rtems_rtl_obj* obj, } /** + * Does the object file have any trampolines? + * + * @param obj The object file's descriptor to check for available space. + * @retval bool Returns @true if the object file has trampolines + */ +static inline size_t rtems_rtl_obj_has_trampolines (const rtems_rtl_obj* obj) +{ + return obj->tramp_slot_size != 0 && obj->tramp_slots != 0; +} + +/** * Is there space in the trampoline memory for a trapoline. * * @param obj The object file's descriptor to check for available space. @@ -395,7 +407,7 @@ static inline bool rtems_rtl_obj_has_symbol (const rtems_rtl_obj* obj, */ static inline size_t rtems_rtl_obj_tramp_avail_space (const rtems_rtl_obj* obj) { - return (char*) obj->tramp_brk - (char*) obj->trampoline; + return (char*) obj->tramp_brk - (char*) obj->tramp_base; } /** @@ -408,8 +420,8 @@ static inline size_t rtems_rtl_obj_tramp_avail_space (const rtems_rtl_obj* obj) static inline bool rtems_rtl_obj_has_tramp_space (const rtems_rtl_obj* obj, const size_t size) { - return (obj->trampoline != NULL && - (rtems_rtl_obj_tramp_avail_space (obj) + size) <= obj->tramps_size); + return (obj->tramp_base != NULL && + (rtems_rtl_obj_tramp_avail_space (obj) + size) <= obj->tramp_size); } /** @@ -420,20 +432,19 @@ static inline bool rtems_rtl_obj_has_tramp_space (const rtems_rtl_obj* obj, */ static inline size_t rtems_rtl_obj_trampoline_slots (const rtems_rtl_obj* obj) { - return obj->trampoline == NULL || obj->tramp_size == 0 ? - 0 : obj->tramps_size / obj->tramp_size; + return obj->tramp_slots; } /** - * Number of trampolines. + * Number of trampoline slot available. * * @param obj The object file's descriptor. - * @retval size_t The number of trampolines. + * @retval size_t The number of trampoline slots available. */ static inline size_t rtems_rtl_obj_trampolines (const rtems_rtl_obj* obj) { - return obj->trampoline == NULL || obj->tramp_size == 0 ? - 0 : rtems_rtl_obj_tramp_avail_space (obj) / obj->tramp_size; + return obj->tramp_base == NULL || obj->tramp_slots == 0 ? + 0 : rtems_rtl_obj_tramp_avail_space (obj) / obj->tramp_slot_size; } /** @@ -572,22 +583,6 @@ rtems_rtl_obj_sect* rtems_rtl_obj_find_section_by_mask (const rtems_rtl_obj* obj uint32_t mask); /** - * Allocate a table for trampoline fixup calls. - * - * @param obj The object file's descriptor. - * @retval true The table was allocated. - * @retval false The alloction failed. - */ -bool rtems_rtl_obj_alloc_trampoline (rtems_rtl_obj* obj); - -/** - * Erase the object file descriptor's trampoline table.. - * - * @param obj The object file's descriptor. - */ -void rtems_rtl_obj_erase_trampoline (rtems_rtl_obj* obj); - -/** * Allocate a table for dependent objects. * * @param obj The object file's descriptor. @@ -750,6 +745,24 @@ size_t rtems_rtl_obj_bss_size (const rtems_rtl_obj* obj); uint32_t rtems_rtl_obj_bss_alignment (const rtems_rtl_obj* obj); /** + * The trampoline size. + * + * @param obj The object file's descriptor. + * @return size_t The size of the trampoline memory of the object file. + */ +size_t rtems_rtl_obj_tramp_size (const rtems_rtl_obj* obj); + +/** + * The trampolinme alignment for the architecture. + * + * This is implemented and set in the architecture backend. + * + * @param obj The object file's descriptor. + * @return uint32_t The alignment. Can be 0 or 1 for not aligned or the alignment. + */ +uint32_t rtems_rtl_obj_tramp_alignment (const rtems_rtl_obj* obj); + +/** * Relocate the object file. The object file's section are parsed for any * relocation type sections. * @@ -810,11 +823,19 @@ bool rtems_rtl_obj_load_symbols (rtems_rtl_obj* obj, * @retval true The object has been sucessfully loaded. * @retval false The load failed. The RTL error has been set. */ -bool -rtems_rtl_obj_alloc_sections (rtems_rtl_obj* obj, - int fd, - rtems_rtl_obj_sect_handler handler, - void* data); +bool rtems_rtl_obj_alloc_sections (rtems_rtl_obj* obj, + int fd, + rtems_rtl_obj_sect_handler handler, + void* data); + +/** + * Resize the sections. + * + * @param obj The object file's descriptor. + * @retval true The object has been sucessfully loaded. + * @retval false The load failed. The RTL error has been set. + */ +bool rtems_rtl_obj_resize_sections (rtems_rtl_obj* obj); /** * Load the sections that have been allocated memory in the target. The bss diff --git a/cpukit/include/rtems/rtl/rtl-sym.h b/cpukit/include/rtems/rtl/rtl-sym.h index 0d29a6ae40..3502b303b8 100644 --- a/cpukit/include/rtems/rtl/rtl-sym.h +++ b/cpukit/include/rtems/rtl/rtl-sym.h @@ -63,6 +63,22 @@ typedef struct rtems_rtl_symbols } rtems_rtl_symbols; /** + * A TLS variable offset call. There is one per base image TLS + * variable. + */ +typedef size_t (*rtems_rtl_tls_offset_func)(void); + +/** + * A TLS symbol offset entry. It is used with an exported symbol table + * to find a TSL table offset for a variable at runtime. + */ +typedef struct rtems_rtl_tls_offset +{ + size_t index; /** exported symbol table index */ + rtems_rtl_tls_offset_func offset; /** TLS offset function */ +} rtems_rtl_tls_offset; + +/** * Open a symbol table with the specified number of buckets. * * @param symbols The symbol table to open. @@ -101,10 +117,14 @@ void rtems_rtl_symbol_table_close (rtems_rtl_symbols* symbols); * @param obj The object table the symbols are for. * @param esyms The exported symbol table. * @param size The size of the table in bytes. + * @param tls_offsets The TLS offsets table. If NULL none provided. + * @param tls_size The number TLS offset entries in the table. */ -bool rtems_rtl_symbol_global_add (rtems_rtl_obj* obj, - const unsigned char* esyms, - unsigned int size); +bool rtems_rtl_symbol_global_add (rtems_rtl_obj* obj, + const unsigned char* esyms, + unsigned int size, + rtems_rtl_tls_offset* tls_offsets, + unsigned int tls_size); /** * Find a symbol given the symbol label in the global symbol table. diff --git a/cpukit/include/rtems/rtl/rtl.h b/cpukit/include/rtems/rtl/rtl.h index 0fd4e74cdf..bd3dce588a 100644 --- a/cpukit/include/rtems/rtl/rtl.h +++ b/cpukit/include/rtems/rtl/rtl.h @@ -393,9 +393,13 @@ bool rtems_rtl_path_prepend (const char* path); * * @param esyms The exported symbol table. * @param count The size of the exported symbol table. + * @param tls_offsets The TLS offsets table. If NULL none provided. + * @param tls_size The number TLS offset entries in the table. */ -void rtems_rtl_base_sym_global_add (const unsigned char* esyms, - unsigned int count); +void rtems_rtl_base_sym_global_add (const unsigned char* esyms, + unsigned int count, + rtems_rtl_tls_offset* tls_offsets, + unsigned int tls_size); /** * Return the object file descriptor for the base image. The object file diff --git a/cpukit/include/rtems/scheduler.h b/cpukit/include/rtems/scheduler.h index a8004cb5e4..cf0c562770 100644 --- a/cpukit/include/rtems/scheduler.h +++ b/cpukit/include/rtems/scheduler.h @@ -3,11 +3,14 @@ /** * @file * - * @brief Scheduler Configuration API + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief This header file contains interfaces to define a scheduler + * configuration for an application. */ /* - * Copyright (c) 2014, 2018 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -50,15 +53,61 @@ /* This object doesn't exist and indicates a configuration error */ extern const Scheduler_Control RTEMS_SCHEDULER_INVALID_INDEX; + /** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief This define indicates that default attributes shall be used for a + * processor to scheduler assignment. + * + * This define may be used as an attribute parameter value in the + * RTEMS_SCHEDULER_ASSIGN() macro. + */ #define RTEMS_SCHEDULER_ASSIGN_DEFAULT \ SCHEDULER_ASSIGN_DEFAULT + /** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief This define indicates that the processor is optionally assigned to + * the scheduler. + * + * If the processor is not present during system initialization, then the + * system initialization continues and the processor is marked as not online. + * + * This define may be used as an attribute parameter value in the + * RTEMS_SCHEDULER_ASSIGN() macro. + */ #define RTEMS_SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL \ SCHEDULER_ASSIGN_PROCESSOR_OPTIONAL + /** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief This define indicates that the processor to scheduler assignment is + * mandatory. + * + * If the processor is not present during system initialization, then the + * system terminates with the fatal source of ::RTEMS_FATAL_SOURCE_SMP and + * fatal code of ::SMP_FATAL_MANDATORY_PROCESSOR_NOT_PRESENT. + * + * This define may be used as an attribute parameter value in the + * RTEMS_SCHEDULER_ASSIGN() macro. + */ #define RTEMS_SCHEDULER_ASSIGN_PROCESSOR_MANDATORY \ SCHEDULER_ASSIGN_PROCESSOR_MANDATORY + /** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a processor to scheduler assignment. + * + * This macro may be used to define entries of the scheduler assignment + * table, see @ref CONFIGURE_SCHEDULER_ASSIGNMENTS. + * + * @param index is the scheduler index. + * + * @param attr is the attribute set of the assignment. + */ #define RTEMS_SCHEDULER_ASSIGN( index, attr ) \ { \ ( index ) < RTEMS_ARRAY_SIZE( _Scheduler_Table ) ? \ @@ -66,6 +115,16 @@ ( attr ) \ } + /** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines that no scheduler is assigned to the processor. + * + * This processor cannot be used by the application. + * + * This macro may be used to define entries of the scheduler assignment + * table, see @ref CONFIGURE_SCHEDULER_ASSIGNMENTS. + */ #define RTEMS_SCHEDULER_ASSIGN_NO_SCHEDULER { NULL, 0 } #endif @@ -77,23 +136,48 @@ * information. */ -#ifdef CONFIGURE_SCHEDULER_CBS - #include <rtems/score/schedulercbs.h> +/** + * @brief Defines a CBS Scheduler context name based on the instantiation + * name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_CBS_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( CBS_ ## name ) - #define SCHEDULER_CBS_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( CBS_ ## name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a CBS Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + */ +#define RTEMS_SCHEDULER_CBS( name ) \ + static Scheduler_EDF_Context SCHEDULER_CBS_CONTEXT_NAME( name ) - #define RTEMS_SCHEDULER_CBS( name ) \ - static Scheduler_EDF_Context SCHEDULER_CBS_CONTEXT_NAME( name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a CBS Scheduler entry for the scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_CBS( name, obj_name ) \ + { \ + &SCHEDULER_CBS_CONTEXT_NAME( name ).Base, \ + SCHEDULER_CBS_ENTRY_POINTS, \ + SCHEDULER_CBS_MAXIMUM_PRIORITY, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ + } - #define RTEMS_SCHEDULER_TABLE_CBS( name, obj_name ) \ - { \ - &SCHEDULER_CBS_CONTEXT_NAME( name ).Base, \ - SCHEDULER_CBS_ENTRY_POINTS, \ - SCHEDULER_CBS_MAXIMUM_PRIORITY, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ - } +#ifdef CONFIGURE_SCHEDULER_CBS + #include <rtems/score/schedulercbs.h> /* Provided for backward compatibility */ @@ -104,23 +188,48 @@ RTEMS_SCHEDULER_TABLE_CBS( name, obj_name ) #endif -#ifdef CONFIGURE_SCHEDULER_EDF - #include <rtems/score/scheduleredf.h> +/** + * @brief Defines an EDF Scheduler context name based on the instantiation + * name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_EDF_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( EDF_ ## name ) - #define SCHEDULER_EDF_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( EDF_ ## name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines an EDF Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + */ +#define RTEMS_SCHEDULER_EDF( name ) \ + static Scheduler_EDF_Context SCHEDULER_EDF_CONTEXT_NAME( name ) - #define RTEMS_SCHEDULER_EDF( name ) \ - static Scheduler_EDF_Context SCHEDULER_EDF_CONTEXT_NAME( name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines an EDF Scheduler entry for the scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_EDF( name, obj_name ) \ + { \ + &SCHEDULER_EDF_CONTEXT_NAME( name ).Base, \ + SCHEDULER_EDF_ENTRY_POINTS, \ + SCHEDULER_EDF_MAXIMUM_PRIORITY, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ + } - #define RTEMS_SCHEDULER_TABLE_EDF( name, obj_name ) \ - { \ - &SCHEDULER_EDF_CONTEXT_NAME( name ).Base, \ - SCHEDULER_EDF_ENTRY_POINTS, \ - SCHEDULER_EDF_MAXIMUM_PRIORITY, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ - } +#ifdef CONFIGURE_SCHEDULER_EDF + #include <rtems/score/scheduleredf.h> /* Provided for backward compatibility */ @@ -131,34 +240,59 @@ RTEMS_SCHEDULER_TABLE_EDF( name, obj_name ) #endif +/** + * @brief Defines an EDF SMP Scheduler context name based on the instantiation + * name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_EDF_SMP_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( EDF_SMP_ ## name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines an EDF SMP Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + */ +#define RTEMS_SCHEDULER_EDF_SMP( name ) \ + static struct { \ + Scheduler_EDF_SMP_Context Base; \ + Scheduler_EDF_SMP_Ready_queue Ready[ CONFIGURE_MAXIMUM_PROCESSORS + 1 ]; \ + } SCHEDULER_EDF_SMP_CONTEXT_NAME( name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines an EDF SMP Scheduler entry for the scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_EDF_SMP( name, obj_name ) \ + { \ + &SCHEDULER_EDF_SMP_CONTEXT_NAME( name ).Base.Base.Base, \ + SCHEDULER_EDF_SMP_ENTRY_POINTS, \ + SCHEDULER_EDF_MAXIMUM_PRIORITY, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ + } + #ifdef CONFIGURE_SCHEDULER_EDF_SMP #ifndef RTEMS_SMP #error "CONFIGURE_SCHEDULER_EDF_SMP cannot be used if RTEMS_SMP is disabled" #endif - #include <rtems/score/scheduleredfsmp.h> - #ifndef CONFIGURE_MAXIMUM_PROCESSORS - #error "CONFIGURE_MAXIMUM_PROCESSORS must be defined to configure the EDF SMP scheduler" + #error "CONFIGURE_MAXIMUM_PROCESSORS must be defined to configure the EDF SMP Scheduler" #endif - #define SCHEDULER_EDF_SMP_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( EDF_SMP_ ## name ) - - #define RTEMS_SCHEDULER_EDF_SMP( name ) \ - static struct { \ - Scheduler_EDF_SMP_Context Base; \ - Scheduler_EDF_SMP_Ready_queue Ready[ CONFIGURE_MAXIMUM_PROCESSORS + 1 ]; \ - } SCHEDULER_EDF_SMP_CONTEXT_NAME( name ) - - #define RTEMS_SCHEDULER_TABLE_EDF_SMP( name, obj_name ) \ - { \ - &SCHEDULER_EDF_SMP_CONTEXT_NAME( name ).Base.Base.Base, \ - SCHEDULER_EDF_SMP_ENTRY_POINTS, \ - SCHEDULER_EDF_MAXIMUM_PRIORITY, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ - } + #include <rtems/score/scheduleredfsmp.h> /* Provided for backward compatibility */ @@ -169,28 +303,56 @@ RTEMS_SCHEDULER_TABLE_EDF_SMP( name, obj_name ) #endif -#ifdef CONFIGURE_SCHEDULER_PRIORITY - #include <rtems/score/schedulerpriority.h> +/** + * @brief Defines a Deterministic Priority Scheduler context name based on the + * instantiation name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_PRIORITY_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( priority_ ## name ) - #define SCHEDULER_PRIORITY_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( priority_ ## name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Deterministic Priority Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + * + * @param prio_count is the count of supported priority levels. + */ +#define RTEMS_SCHEDULER_PRIORITY( name, prio_count ) \ + static struct { \ + Scheduler_priority_Context Base; \ + Chain_Control Ready[ ( prio_count ) ]; \ + } SCHEDULER_PRIORITY_CONTEXT_NAME( name ) - #define RTEMS_SCHEDULER_PRIORITY( name, prio_count ) \ - static struct { \ - Scheduler_priority_Context Base; \ - Chain_Control Ready[ ( prio_count ) ]; \ - } SCHEDULER_PRIORITY_CONTEXT_NAME( name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Deterministic Priority Scheduler entry for the scheduler + * table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_PRIORITY( name, obj_name ) \ + { \ + &SCHEDULER_PRIORITY_CONTEXT_NAME( name ).Base.Base, \ + SCHEDULER_PRIORITY_ENTRY_POINTS, \ + RTEMS_ARRAY_SIZE( \ + SCHEDULER_PRIORITY_CONTEXT_NAME( name ).Ready \ + ) - 1, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ + } - #define RTEMS_SCHEDULER_TABLE_PRIORITY( name, obj_name ) \ - { \ - &SCHEDULER_PRIORITY_CONTEXT_NAME( name ).Base.Base, \ - SCHEDULER_PRIORITY_ENTRY_POINTS, \ - RTEMS_ARRAY_SIZE( \ - SCHEDULER_PRIORITY_CONTEXT_NAME( name ).Ready \ - ) - 1, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ - } +#ifdef CONFIGURE_SCHEDULER_PRIORITY + #include <rtems/score/schedulerpriority.h> /* Provided for backward compatibility */ @@ -201,6 +363,55 @@ RTEMS_SCHEDULER_TABLE_PRIORITY( name, obj_name ) #endif +/** + * @brief Defines a Arbitrary Processor Affinity Priority SMP Scheduler context + * name based on the instantiation name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( priority_affinity_SMP_ ## name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Arbitrary Processor Affinity Priority SMP Scheduler + * instantiation. + * + * @param name is the scheduler instantiation name. + * + * @param prio_count is the count of supported priority levels. + */ +#define RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP( name, prio_count ) \ + static struct { \ + Scheduler_priority_SMP_Context Base; \ + Chain_Control Ready[ ( prio_count ) ]; \ + } SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Arbitrary Processor Affinity Priority SMP Scheduler entry + * for the scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP( name, obj_name ) \ + { \ + &SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ).Base.Base.Base, \ + SCHEDULER_PRIORITY_AFFINITY_SMP_ENTRY_POINTS, \ + RTEMS_ARRAY_SIZE( \ + SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ).Ready \ + ) - 1, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ + } + #ifdef CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP #ifndef RTEMS_SMP #error "CONFIGURE_SCHEDULER_PRIORITY_AFFINITY_SMP cannot be used if RTEMS_SMP is disabled" @@ -208,26 +419,6 @@ #include <rtems/score/schedulerpriorityaffinitysmp.h> - #define SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( priority_affinity_SMP_ ## name ) - - #define RTEMS_SCHEDULER_PRIORITY_AFFINITY_SMP( name, prio_count ) \ - static struct { \ - Scheduler_priority_SMP_Context Base; \ - Chain_Control Ready[ ( prio_count ) ]; \ - } SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ) - - #define RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP( name, obj_name ) \ - { \ - &SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ).Base.Base.Base, \ - SCHEDULER_PRIORITY_AFFINITY_SMP_ENTRY_POINTS, \ - RTEMS_ARRAY_SIZE( \ - SCHEDULER_PRIORITY_AFFINITY_SMP_CONTEXT_NAME( name ).Ready \ - ) - 1, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ - } - /* Provided for backward compatibility */ #define RTEMS_SCHEDULER_CONTEXT_PRIORITY_AFFINITY_SMP( name, prio_count ) \ @@ -237,6 +428,54 @@ RTEMS_SCHEDULER_TABLE_PRIORITY_AFFINITY_SMP( name, obj_name ) #endif +/** + * @brief Defines a Deterministic Priority SMP Scheduler context name based on + * the instantiation name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( priority_SMP_ ## name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Deterministic Priority SMP Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + * + * @param prio_count is the count of supported priority levels. + */ +#define RTEMS_SCHEDULER_PRIORITY_SMP( name, prio_count ) \ + static struct { \ + Scheduler_priority_SMP_Context Base; \ + Chain_Control Ready[ ( prio_count ) ]; \ + } SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Deterministic Priority SMP Scheduler entry for the + * scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( name, obj_name ) \ + { \ + &SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ).Base.Base.Base, \ + SCHEDULER_PRIORITY_SMP_ENTRY_POINTS, \ + RTEMS_ARRAY_SIZE( \ + SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ).Ready \ + ) - 1, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ + } + #ifdef CONFIGURE_SCHEDULER_PRIORITY_SMP #ifndef RTEMS_SMP #error "CONFIGURE_SCHEDULER_PRIORITY_SMP cannot be used if RTEMS_SMP is disabled" @@ -244,26 +483,6 @@ #include <rtems/score/schedulerprioritysmp.h> - #define SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( priority_SMP_ ## name ) - - #define RTEMS_SCHEDULER_PRIORITY_SMP( name, prio_count ) \ - static struct { \ - Scheduler_priority_SMP_Context Base; \ - Chain_Control Ready[ ( prio_count ) ]; \ - } SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ) - - #define RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( name, obj_name ) \ - { \ - &SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ).Base.Base.Base, \ - SCHEDULER_PRIORITY_SMP_ENTRY_POINTS, \ - RTEMS_ARRAY_SIZE( \ - SCHEDULER_PRIORITY_SMP_CONTEXT_NAME( name ).Ready \ - ) - 1, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ - } - /* Provided for backward compatibility */ #define RTEMS_SCHEDULER_CONTEXT_PRIORITY_SMP( name, prio_count ) \ @@ -273,34 +492,59 @@ RTEMS_SCHEDULER_TABLE_PRIORITY_SMP( name, obj_name ) #endif +/** + * @brief Defines a Strong APA Scheduler context name based on the + * instantiation name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_STRONG_APA_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( strong_APA_ ## name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Strong APA Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + */ +#define RTEMS_SCHEDULER_STRONG_APA( name, prio_count ) \ + static struct { \ + Scheduler_strong_APA_Context Base; \ + Scheduler_strong_APA_CPU CPU[ CONFIGURE_MAXIMUM_PROCESSORS ]; \ + } SCHEDULER_STRONG_APA_CONTEXT_NAME( name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Strong APA Scheduler entry for the scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_STRONG_APA( name, obj_name ) \ + { \ + &SCHEDULER_STRONG_APA_CONTEXT_NAME( name ).Base.Base.Base, \ + SCHEDULER_STRONG_APA_ENTRY_POINTS, \ + SCHEDULER_STRONG_APA_MAXIMUM_PRIORITY, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ + } + #ifdef CONFIGURE_SCHEDULER_STRONG_APA #ifndef RTEMS_SMP #error "CONFIGURE_SCHEDULER_STRONG_APA cannot be used if RTEMS_SMP is disabled" #endif - #include <rtems/score/schedulerstrongapa.h> - #ifndef CONFIGURE_MAXIMUM_PROCESSORS - #error "CONFIGURE_MAXIMUM_PROCESSORS must be defined to configure the Strong APA scheduler" + #error "CONFIGURE_MAXIMUM_PROCESSORS must be defined to configure the Strong APA Scheduler" #endif - #define SCHEDULER_STRONG_APA_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( strong_APA_ ## name ) - - #define RTEMS_SCHEDULER_STRONG_APA( name, prio_count ) \ - static struct { \ - Scheduler_strong_APA_Context Base; \ - Scheduler_strong_APA_CPU CPU[ CONFIGURE_MAXIMUM_PROCESSORS ]; \ - } SCHEDULER_STRONG_APA_CONTEXT_NAME( name ) - - #define RTEMS_SCHEDULER_TABLE_STRONG_APA( name, obj_name ) \ - { \ - &SCHEDULER_STRONG_APA_CONTEXT_NAME( name ).Base.Base.Base, \ - SCHEDULER_STRONG_APA_ENTRY_POINTS, \ - SCHEDULER_STRONG_APA_MAXIMUM_PRIORITY, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ - } + #include <rtems/score/schedulerstrongapa.h> /* Provided for backward compatibility */ @@ -311,24 +555,49 @@ RTEMS_SCHEDULER_TABLE_STRONG_APA( name, obj_name ) #endif -#ifdef CONFIGURE_SCHEDULER_SIMPLE - #include <rtems/score/schedulersimple.h> +/** + * @brief Defines a Simple Scheduler context name based on the instantiation + * name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_SIMPLE_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( simple_ ## name ) - #define SCHEDULER_SIMPLE_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( simple_ ## name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Simple Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + */ +#define RTEMS_SCHEDULER_SIMPLE( name ) \ + static Scheduler_simple_Context \ + SCHEDULER_SIMPLE_CONTEXT_NAME( name ) - #define RTEMS_SCHEDULER_SIMPLE( name ) \ - static Scheduler_simple_Context \ - SCHEDULER_SIMPLE_CONTEXT_NAME( name ) +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Simple Scheduler entry for the scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_SIMPLE( name, obj_name ) \ + { \ + &SCHEDULER_SIMPLE_CONTEXT_NAME( name ).Base, \ + SCHEDULER_SIMPLE_ENTRY_POINTS, \ + SCHEDULER_SIMPLE_MAXIMUM_PRIORITY, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ + } - #define RTEMS_SCHEDULER_TABLE_SIMPLE( name, obj_name ) \ - { \ - &SCHEDULER_SIMPLE_CONTEXT_NAME( name ).Base, \ - SCHEDULER_SIMPLE_ENTRY_POINTS, \ - SCHEDULER_SIMPLE_MAXIMUM_PRIORITY, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( true ) \ - } +#ifdef CONFIGURE_SCHEDULER_SIMPLE + #include <rtems/score/schedulersimple.h> /* Provided for backward compatibility */ @@ -339,6 +608,47 @@ RTEMS_SCHEDULER_TABLE_SIMPLE( name, obj_name ) #endif +/** + * @brief Defines a Simple SMP Scheduler context name based on the + * instantiation name. + * + * @param name is the scheduler instantiation name. + */ +#define SCHEDULER_SIMPLE_SMP_CONTEXT_NAME( name ) \ + SCHEDULER_CONTEXT_NAME( simple_SMP_ ## name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Simple SMP Scheduler instantiation. + * + * @param name is the scheduler instantiation name. + */ +#define RTEMS_SCHEDULER_SIMPLE_SMP( name ) \ + static Scheduler_simple_SMP_Context \ + SCHEDULER_SIMPLE_SMP_CONTEXT_NAME( name ) + +/** + * @ingroup RTEMSApplConfigGeneralSchedulerConfiguration + * + * @brief Defines a Simple SMP Scheduler entry for the scheduler table. + * + * Use this macro to define an entry for the + * @ref CONFIGURE_SCHEDULER_TABLE_ENTRIES application configuration option. + * + * @param name is the scheduler instantiation name. + * + * @param name is the scheduler object name. + */ +#define RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( name, obj_name ) \ + { \ + &SCHEDULER_SIMPLE_SMP_CONTEXT_NAME( name ).Base.Base, \ + SCHEDULER_SIMPLE_SMP_ENTRY_POINTS, \ + SCHEDULER_SIMPLE_SMP_MAXIMUM_PRIORITY, \ + ( obj_name ) \ + SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ + } + #ifdef CONFIGURE_SCHEDULER_SIMPLE_SMP #ifndef RTEMS_SMP #error "CONFIGURE_SCHEDULER_SIMPLE_SMP cannot be used if RTEMS_SMP is disabled" @@ -346,22 +656,6 @@ #include <rtems/score/schedulersimplesmp.h> - #define SCHEDULER_SIMPLE_SMP_CONTEXT_NAME( name ) \ - SCHEDULER_CONTEXT_NAME( simple_SMP_ ## name ) - - #define RTEMS_SCHEDULER_SIMPLE_SMP( name ) \ - static Scheduler_simple_SMP_Context \ - SCHEDULER_SIMPLE_SMP_CONTEXT_NAME( name ) - - #define RTEMS_SCHEDULER_TABLE_SIMPLE_SMP( name, obj_name ) \ - { \ - &SCHEDULER_SIMPLE_SMP_CONTEXT_NAME( name ).Base.Base, \ - SCHEDULER_SIMPLE_SMP_ENTRY_POINTS, \ - SCHEDULER_SIMPLE_SMP_MAXIMUM_PRIORITY, \ - ( obj_name ) \ - SCHEDULER_CONTROL_IS_NON_PREEMPT_MODE_SUPPORTED( false ) \ - } - /* Provided for backward compatibility */ #define RTEMS_SCHEDULER_CONTEXT_SIMPLE_SMP( name ) \ diff --git a/cpukit/include/rtems/score/assert.h b/cpukit/include/rtems/score/assert.h index 9eeccacf76..ad92a585fd 100644 --- a/cpukit/include/rtems/score/assert.h +++ b/cpukit/include/rtems/score/assert.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2013-2014 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -71,22 +71,7 @@ extern "C" { * @note This is based on the code in newlib's assert.h. */ #ifndef __RTEMS_ASSERT_FUNCTION - /* Use g++'s demangled names in C++. */ - #if defined __cplusplus && defined __GNUC__ - #define __RTEMS_ASSERT_FUNCTION __PRETTY_FUNCTION__ - - /* C99 requires the use of __func__. */ - #elif __STDC_VERSION__ >= 199901L - #define __RTEMS_ASSERT_FUNCTION __func__ - - /* Older versions of gcc don't have __func__ but can use __FUNCTION__. */ - #elif __GNUC__ >= 2 - #define __RTEMS_ASSERT_FUNCTION __FUNCTION__ - - /* failed to detect __func__ support. */ - #else - #define __RTEMS_ASSERT_FUNCTION ((char *) 0) - #endif + #define __RTEMS_ASSERT_FUNCTION RTEMS_FUNCTION_NAME #endif /* !__RTEMS_ASSERT_FUNCTION */ #if !defined( RTEMS_SCHEDSIM ) diff --git a/cpukit/include/rtems/score/atomic.h b/cpukit/include/rtems/score/atomic.h index 161b0ec03e..9ef1779e60 100644 --- a/cpukit/include/rtems/score/atomic.h +++ b/cpukit/include/rtems/score/atomic.h @@ -10,6 +10,7 @@ */ /* + * Copyright (C) 2015 embedded brains GmbH & Co. KG * COPYRIGHT (c) 2012-2013 Deng Hengyi. * * Redistribution and use in source and binary forms, with or without @@ -37,7 +38,7 @@ #ifndef _RTEMS_SCORE_ATOMIC_H #define _RTEMS_SCORE_ATOMIC_H -#include <rtems/score/cpuatomic.h> +#include <rtems/score/basedefs.h> /** * @defgroup RTEMSScoreAtomic Atomic Operations @@ -54,122 +55,935 @@ * @{ */ -typedef CPU_atomic_Uint Atomic_Uint; +#ifdef RTEMS_SMP + #if defined(__cplusplus) \ + && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)) + /* + * The GCC 4.9 ships its own <stdatomic.h> which is not C++ compatible. The + * suggested solution was to include <atomic> in case C++ is used. This works + * at least with GCC 4.9. See also: + * + * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=60932 + * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=60940 + */ + #include <atomic> + #define _RTEMS_SCORE_ATOMIC_USE_ATOMIC + #else + #include <stdatomic.h> + #define _RTEMS_SCORE_ATOMIC_USE_STDATOMIC + #endif +#else + #include <rtems/score/isrlevel.h> +#endif -typedef CPU_atomic_Ulong Atomic_Ulong; +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) -typedef CPU_atomic_Uintptr Atomic_Uintptr; +typedef std::atomic_uint Atomic_Uint; -typedef CPU_atomic_Flag Atomic_Flag; +typedef std::atomic_ulong Atomic_Ulong; -typedef CPU_atomic_Order Atomic_Order; +typedef std::atomic_uintptr_t Atomic_Uintptr; -#define ATOMIC_ORDER_RELAXED CPU_ATOMIC_ORDER_RELAXED +typedef std::atomic_flag Atomic_Flag; -#define ATOMIC_ORDER_ACQUIRE CPU_ATOMIC_ORDER_ACQUIRE +typedef std::memory_order Atomic_Order; -#define ATOMIC_ORDER_RELEASE CPU_ATOMIC_ORDER_RELEASE +#define ATOMIC_ORDER_RELAXED std::memory_order_relaxed -#define ATOMIC_ORDER_ACQ_REL CPU_ATOMIC_ORDER_ACQ_REL +#define ATOMIC_ORDER_ACQUIRE std::memory_order_acquire -#define ATOMIC_ORDER_SEQ_CST CPU_ATOMIC_ORDER_SEQ_CST +#define ATOMIC_ORDER_RELEASE std::memory_order_release -#define ATOMIC_INITIALIZER_UINT( value ) CPU_ATOMIC_INITIALIZER_UINT( value ) +#define ATOMIC_ORDER_ACQ_REL std::memory_order_acq_rel -#define ATOMIC_INITIALIZER_ULONG( value ) CPU_ATOMIC_INITIALIZER_ULONG( value ) +#define ATOMIC_ORDER_SEQ_CST std::memory_order_seq_cst -#define ATOMIC_INITIALIZER_UINTPTR( value ) CPU_ATOMIC_INITIALIZER_UINTPTR( value ) +#define ATOMIC_INITIALIZER_UINT( value ) ATOMIC_VAR_INIT( value ) -#define ATOMIC_INITIALIZER_FLAG CPU_ATOMIC_INITIALIZER_FLAG +#define ATOMIC_INITIALIZER_ULONG( value ) ATOMIC_VAR_INIT( value ) -#define _Atomic_Fence( order ) _CPU_atomic_Fence( order ) +#define ATOMIC_INITIALIZER_UINTPTR( value ) ATOMIC_VAR_INIT( value ) -#define _Atomic_Init_uint( obj, desired ) \ - _CPU_atomic_Init_uint( obj, desired ) +#define ATOMIC_INITIALIZER_FLAG ATOMIC_FLAG_INIT -#define _Atomic_Init_ulong( obj, desired ) \ - _CPU_atomic_Init_ulong( obj, desired ) +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) -#define _Atomic_Init_uintptr( obj, desired ) \ - _CPU_atomic_Init_uintptr( obj, desired ) +typedef atomic_uint Atomic_Uint; -#define _Atomic_Load_uint( obj, order ) \ - _CPU_atomic_Load_uint( obj, order ) +typedef atomic_ulong Atomic_Ulong; -#define _Atomic_Load_ulong( obj, order ) \ - _CPU_atomic_Load_ulong( obj, order ) +typedef atomic_uintptr_t Atomic_Uintptr; -#define _Atomic_Load_uintptr( obj, order ) \ - _CPU_atomic_Load_uintptr( obj, order ) +typedef atomic_flag Atomic_Flag; -#define _Atomic_Store_uint( obj, desr, order ) \ - _CPU_atomic_Store_uint( obj, desr, order ) +typedef memory_order Atomic_Order; -#define _Atomic_Store_ulong( obj, desr, order ) \ - _CPU_atomic_Store_ulong( obj, desr, order ) +#define ATOMIC_ORDER_RELAXED memory_order_relaxed -#define _Atomic_Store_uintptr( obj, desr, order ) \ - _CPU_atomic_Store_uintptr( obj, desr, order ) +#define ATOMIC_ORDER_ACQUIRE memory_order_acquire -#define _Atomic_Fetch_add_uint( obj, arg, order ) \ - _CPU_atomic_Fetch_add_uint( obj, arg, order ) +#define ATOMIC_ORDER_RELEASE memory_order_release -#define _Atomic_Fetch_add_ulong( obj, arg, order ) \ - _CPU_atomic_Fetch_add_ulong( obj, arg, order ) +#define ATOMIC_ORDER_ACQ_REL memory_order_acq_rel -#define _Atomic_Fetch_add_uintptr( obj, arg, order ) \ - _CPU_atomic_Fetch_add_uintptr( obj, arg, order ) +#define ATOMIC_ORDER_SEQ_CST memory_order_seq_cst -#define _Atomic_Fetch_sub_uint( obj, arg, order ) \ - _CPU_atomic_Fetch_sub_uint( obj, arg, order ) +#define ATOMIC_INITIALIZER_UINT( value ) ATOMIC_VAR_INIT( value ) -#define _Atomic_Fetch_sub_ulong( obj, arg, order ) \ - _CPU_atomic_Fetch_sub_ulong( obj, arg, order ) +#define ATOMIC_INITIALIZER_ULONG( value ) ATOMIC_VAR_INIT( value ) -#define _Atomic_Fetch_sub_uintptr( obj, arg, order ) \ - _CPU_atomic_Fetch_sub_uintptr( obj, arg, order ) +#define ATOMIC_INITIALIZER_UINTPTR( value ) ATOMIC_VAR_INIT( value ) -#define _Atomic_Fetch_or_uint( obj, arg, order ) \ - _CPU_atomic_Fetch_or_uint( obj, arg, order ) +#define ATOMIC_INITIALIZER_FLAG ATOMIC_FLAG_INIT -#define _Atomic_Fetch_or_ulong( obj, arg, order ) \ - _CPU_atomic_Fetch_or_ulong( obj, arg, order ) +#else -#define _Atomic_Fetch_or_uintptr( obj, arg, order ) \ - _CPU_atomic_Fetch_or_uintptr( obj, arg, order ) +typedef unsigned int Atomic_Uint; -#define _Atomic_Fetch_and_uint( obj, arg, order ) \ - _CPU_atomic_Fetch_and_uint( obj, arg, order ) +typedef unsigned long Atomic_Ulong; -#define _Atomic_Fetch_and_ulong( obj, arg, order ) \ - _CPU_atomic_Fetch_and_ulong( obj, arg, order ) +typedef uintptr_t Atomic_Uintptr; -#define _Atomic_Fetch_and_uintptr( obj, arg, order ) \ - _CPU_atomic_Fetch_and_uintptr( obj, arg, order ) +typedef bool Atomic_Flag; -#define _Atomic_Exchange_uint( obj, desr, order ) \ - _CPU_atomic_Exchange_uint( obj, desr, order ) +typedef int Atomic_Order; -#define _Atomic_Exchange_ulong( obj, desr, order ) \ - _CPU_atomic_Exchange_ulong( obj, desr, order ) +#define ATOMIC_ORDER_RELAXED 0 -#define _Atomic_Exchange_uintptr( obj, desr, order ) \ - _CPU_atomic_Exchange_uintptr( obj, desr, order ) +#define ATOMIC_ORDER_ACQUIRE 2 -#define _Atomic_Compare_exchange_uint( obj, expected, desired, succ, fail ) \ - _CPU_atomic_Compare_exchange_uint( obj, expected, desired, succ, fail ) +#define ATOMIC_ORDER_RELEASE 3 -#define _Atomic_Compare_exchange_ulong( obj, expected, desired, succ, fail ) \ - _CPU_atomic_Compare_exchange_ulong( obj, expected, desired, succ, fail ) +#define ATOMIC_ORDER_ACQ_REL 4 -#define _Atomic_Compare_exchange_uintptr( obj, expected, desired, succ, fail ) \ - _CPU_atomic_Compare_exchange_uintptr( obj, expected, desired, succ, fail ) +#define ATOMIC_ORDER_SEQ_CST 5 -#define _Atomic_Flag_clear( obj, order ) \ - _CPU_atomic_Flag_clear( obj, order ) +#define ATOMIC_INITIALIZER_UINT( value ) ( value ) -#define _Atomic_Flag_test_and_set( obj, order ) \ - _CPU_atomic_Flag_test_and_set( obj, order ) +#define ATOMIC_INITIALIZER_ULONG( value ) ( value ) + +#define ATOMIC_INITIALIZER_UINTPTR( value ) ( value ) + +#define ATOMIC_INITIALIZER_FLAG false + +#endif + +/** + * @brief Sets up a cpu fence. + * + * @param[out] order The order for the fence. + */ +static inline void _Atomic_Fence( Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + std::atomic_thread_fence( order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_thread_fence( order ); +#else + (void) order; + RTEMS_COMPILER_MEMORY_BARRIER(); +#endif +} + +/** + * @brief Initializes Uint. + * + * @param[out] obj The CPU atomic Uint to initialize. + * @param desired The desired value for @a obj. + */ +static inline void _Atomic_Init_uint( Atomic_Uint *obj, unsigned int desired ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + obj->store( desired ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_init( obj, desired ); +#else + *obj = desired; +#endif +} + +/** + * @brief Initializes Ulong. + * + * @param[out] obj The CPU atomic Ulong to initialize. + * @param desired The desired value for @a obj. + */ +static inline void _Atomic_Init_ulong( Atomic_Ulong *obj, unsigned long desired ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + obj->store( desired ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_init( obj, desired ); +#else + *obj = desired; +#endif +} + +/** + * @brief Initializes Uintptr. + * + * @param[out] obj The CPU atomic Uintptr to initialize. + * @param desired The desired value for @a obj. + */ +static inline void _Atomic_Init_uintptr( Atomic_Uintptr *obj, uintptr_t desired ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + obj->store( desired ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_init( obj, desired ); +#else + *obj = desired; +#endif +} + +/** + * @brief Loads value of Uint considering the order. + * + * @param obj The CPU atomic Uint to get the value from. + * @param order The atomic order for getting the value. + * + * @return The value of @a obj considering the @a order. + */ +static inline unsigned int _Atomic_Load_uint( const Atomic_Uint *obj, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->load( order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_load_explicit( obj, order ); +#else + unsigned int val; + + (void) order; + val = *obj; + RTEMS_COMPILER_MEMORY_BARRIER(); + + return val; +#endif +} + +/** + * @brief Loads value of Ulong considering the order. + * + * @param obj The CPU atomic Ulong to get the value from. + * @param order The atomic order for getting the value. + * + * @return The value of @a obj considering the @a order. + */ +static inline unsigned long _Atomic_Load_ulong( const Atomic_Ulong *obj, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->load( order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_load_explicit( obj, order ); +#else + unsigned long val; + + (void) order; + val = *obj; + RTEMS_COMPILER_MEMORY_BARRIER(); + + return val; +#endif +} + +/** + * @brief Loads value of Uintptr considering the order. + * + * @param obj The CPU atomic Uintptr to get the value from. + * @param order The atomic order for getting the value. + * + * @return The value of @a obj considering the @a order. + */ +static inline uintptr_t _Atomic_Load_uintptr( const Atomic_Uintptr *obj, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->load( order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_load_explicit( obj, order ); +#else + uintptr_t val; + + (void) order; + val = *obj; + RTEMS_COMPILER_MEMORY_BARRIER(); + + return val; +#endif +} + +/** + * @brief Stores a value to Uint considering the order. + * + * @param[out] obj The CPU atomic Uint to store a value in. + * @param desired The desired value for @a obj. + * @param order The atomic order for storing the value. + */ +static inline void _Atomic_Store_uint( Atomic_Uint *obj, unsigned int desired, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + obj->store( desired, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_store_explicit( obj, desired, order ); +#else + (void) order; + RTEMS_COMPILER_MEMORY_BARRIER(); + *obj = desired; +#endif +} + +/** + * @brief Stores a value to Ulong considering the order. + * + * @param[out] obj The CPU atomic Ulong to store a value in. + * @param desired The desired value for @a obj. + * @param order The atomic order for storing the value. + */ +static inline void _Atomic_Store_ulong( Atomic_Ulong *obj, unsigned long desired, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + obj->store( desired, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_store_explicit( obj, desired, order ); +#else + (void) order; + RTEMS_COMPILER_MEMORY_BARRIER(); + *obj = desired; +#endif +} + +/** + * @brief Stores a value to Uintptr considering the order. + * + * @param[out] obj The CPU atomic Uintptr to store a value in. + * @param desired The desired value for @a obj. + * @param order The atomic order for storing the value. + */ +static inline void _Atomic_Store_uintptr( Atomic_Uintptr *obj, uintptr_t desired, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + obj->store( desired, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_store_explicit( obj, desired, order ); +#else + (void) order; + RTEMS_COMPILER_MEMORY_BARRIER(); + *obj = desired; +#endif +} + +/** + * @brief Fetches current value of Uint and adds a value to the stored value. + * + * @param[in, out] obj The CPU atomic Uint to get the value from and add @a arg to. + * @param arg The value to add to @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the addition of @a arg. + */ +static inline unsigned int _Atomic_Fetch_add_uint( Atomic_Uint *obj, unsigned int arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_add( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_add_explicit( obj, arg, order ); +#else + unsigned int val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val + arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Ulong and adds a value to the stored value. + * + * @param[in, out] obj The CPU atomic Ulong to get the value from and add @a arg to. + * @param arg The value to add to @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the addition of @a arg. + */ +static inline unsigned long _Atomic_Fetch_add_ulong( Atomic_Ulong *obj, unsigned long arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_add( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_add_explicit( obj, arg, order ); +#else + unsigned long val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val + arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uintptr and adds a value to the stored value. + * + * @param[in, out] obj The CPU atomic Uintptr to get the value from and add @a arg to. + * @param arg The value to add to @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the addition of @a arg. + */ +static inline uintptr_t _Atomic_Fetch_add_uintptr( Atomic_Uintptr *obj, uintptr_t arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_add( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_add_explicit( obj, arg, order ); +#else + uintptr_t val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val + arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uint and subtracts a value from the stored value. + * + * @param[in, out] obj The CPU atomic Uint to get the value from and subtract @a arg from. + * @param arg The value to subtract from @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the subtraction of @a arg. + */ +static inline unsigned int _Atomic_Fetch_sub_uint( Atomic_Uint *obj, unsigned int arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_sub( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_sub_explicit( obj, arg, order ); +#else + unsigned int val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val - arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Ulong and subtracts a value from the stored value. + * + * @param[in, out] obj The CPU atomic Ulong to get the value from and subtract @a arg from. + * @param arg The value to subtract from @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the subtraction of @a arg. + */ +static inline unsigned long _Atomic_Fetch_sub_ulong( Atomic_Ulong *obj, unsigned long arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_sub( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_sub_explicit( obj, arg, order ); +#else + unsigned long val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val - arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uintptr and subtracts a value from the stored value. + * + * @param[in, out] obj The CPU atomic Uintptr to get the value from and subtract @a arg from. + * @param arg The value to subtract from @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the subtraction of @a arg. + */ +static inline uintptr_t _Atomic_Fetch_sub_uintptr( Atomic_Uintptr *obj, uintptr_t arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_sub( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_sub_explicit( obj, arg, order ); +#else + uintptr_t val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val - arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uint and ORs a value with the stored value. + * + * @param[in, out] obj The CPU atomic Uint to get the value from and OR @a arg to. + * @param arg The value to OR with @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the OR operation with @a arg. + */ +static inline unsigned int _Atomic_Fetch_or_uint( Atomic_Uint *obj, unsigned int arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_or( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_or_explicit( obj, arg, order ); +#else + unsigned int val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val | arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Ulong and ORs a value with the stored value. + * + * @param[in, out] obj The CPU atomic Ulong to get the value from and OR @a arg to. + * @param arg The value to OR with @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the OR operation with @a arg. + */ +static inline unsigned long _Atomic_Fetch_or_ulong( Atomic_Ulong *obj, unsigned long arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_or( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_or_explicit( obj, arg, order ); +#else + unsigned long val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val | arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uintptr and ORs a value with the stored value. + * + * @param[in, out] obj The CPU atomic Uintptr to get the value from and OR @a arg to. + * @param arg The value to OR with @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the OR operation with @a arg. + */ +static inline uintptr_t _Atomic_Fetch_or_uintptr( Atomic_Uintptr *obj, uintptr_t arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_or( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_or_explicit( obj, arg, order ); +#else + uintptr_t val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val | arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uint and ANDs a value with the stored value. + * + * @param[in, out] obj The CPU atomic Uint to get the value from and AND @a arg to. + * @param arg The value to AND with @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the AND operation with @a arg. + */ +static inline unsigned int _Atomic_Fetch_and_uint( Atomic_Uint *obj, unsigned int arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_and( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_and_explicit( obj, arg, order ); +#else + unsigned int val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val & arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Ulong and ANDs a value with the stored value. + * + * @param[in, out] obj The CPU atomic Ulong to get the value from and AND @a arg to. + * @param arg The value to AND with @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the AND operation with @a arg. + */ +static inline unsigned long _Atomic_Fetch_and_ulong( Atomic_Ulong *obj, unsigned long arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_and( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_and_explicit( obj, arg, order ); +#else + unsigned long val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val & arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uintptr and ANDs a value with the stored value. + * + * @param[in, out] obj The CPU atomic Uintptr to get the value from and AND @a arg to. + * @param arg The value to AND with @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the AND operation with @a arg. + */ +static inline uintptr_t _Atomic_Fetch_and_uintptr( Atomic_Uintptr *obj, uintptr_t arg, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->fetch_and( arg, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_fetch_and_explicit( obj, arg, order ); +#else + uintptr_t val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = val & arg; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uint and sets its value. + * + * @param[in, out] obj The CPU atomic Uint to get the value from and set the value to @a desired. + * @param arg The value to set for @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the exchange with @a desired. + */ +static inline unsigned int _Atomic_Exchange_uint( Atomic_Uint *obj, unsigned int desired, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->exchange( desired, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_exchange_explicit( obj, desired, order ); +#else + unsigned int val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = desired; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Ulong and sets its value. + * + * @param[in, out] obj The CPU atomic Ulong to get the value from and set the value to @a desired. + * @param arg The value to set for @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the exchange with @a desired. + */ +static inline unsigned long _Atomic_Exchange_ulong( Atomic_Ulong *obj, unsigned long desired, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->exchange( desired, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_exchange_explicit( obj, desired, order ); +#else + unsigned long val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = desired; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Fetches current value of Uintptr and sets its value. + * + * @param[in, out] obj The CPU atomic Uintptr to get the value from and set the value to @a desired. + * @param arg The value to set for @a obj. + * @param order The atomic order for the operation. + * + * @return The value of @a obj prior to the exchange with @a desired. + */ +static inline uintptr_t _Atomic_Exchange_uintptr( Atomic_Uintptr *obj, uintptr_t desired, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->exchange( desired, order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_exchange_explicit( obj, desired, order ); +#else + uintptr_t val; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + val = *obj; + *obj = desired; + _ISR_Local_enable( level ); + + return val; +#endif +} + +/** + * @brief Checks if value of Uint is as expected. + * + * This method checks if the value of @a obj is equal to the value of @a expected. If + * this is the case, the value of @a obj is changed to @a desired. Otherwise, the value + * of @a obj is changed to @a expected. + * + * @param[in, out] obj The CPU atomic Uint to operate upon. + * @param[in, out] expected The expected value of @a obj. If @a obj has a different + * value, @a expected is changed to the actual value of @a obj. + * @param desired The new value of @a obj if the old value of @a obj was as expected. + * @param succ The order if it is successful. + * @param fail The order if it fails. + * + * @retval true The old value of @a obj was as expected. + * @retval false The old value of @a obj was not as expected. + */ +static inline bool _Atomic_Compare_exchange_uint( Atomic_Uint *obj, unsigned int *expected, unsigned int desired, Atomic_Order succ, Atomic_Order fail ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->compare_exchange_strong( *expected, desired, succ, fail ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_compare_exchange_strong_explicit( obj, expected, desired, succ, fail ); +#else + bool success; + ISR_Level level; + unsigned int actual; + + (void) succ; + (void) fail; + _ISR_Local_disable( level ); + actual = *obj; + success = ( actual == *expected ); + if ( success ) { + *obj = desired; + } else { + *expected = actual; + } + _ISR_Local_enable( level ); + + return success; +#endif +} + +/** + * @brief Checks if value of Ulong is as expected. + * + * This method checks if the value of @a obj is equal to the value of @a expected. If + * this is the case, the value of @a obj is changed to @a desired. Otherwise, the value + * of @a obj is changed to @a expected. + * + * @param[in, out] obj The CPU atomic Ulong to operate upon. + * @param[in, out] expected The expected value of @a obj. If @a obj has a different + * value, @a expected is changed to the actual value of @a obj. + * @param desired The new value of @a obj if the old value of @a obj was as expected. + * @param succ The order if it is successful. + * @param fail The order if it fails. + * + * @retval true The old value of @a obj was as expected. + * @retval false The old value of @a obj was not as expected. + */ +static inline bool _Atomic_Compare_exchange_ulong( Atomic_Ulong *obj, unsigned long *expected, unsigned long desired, Atomic_Order succ, Atomic_Order fail ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->compare_exchange_strong( *expected, desired, succ, fail ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_compare_exchange_strong_explicit( obj, expected, desired, succ, fail ); +#else + bool success; + ISR_Level level; + unsigned long actual; + + (void) succ; + (void) fail; + _ISR_Local_disable( level ); + actual = *obj; + success = ( actual == *expected ); + if ( success ) { + *obj = desired; + } else { + *expected = actual; + } + _ISR_Local_enable( level ); + + return success; +#endif +} + +/** + * @brief Checks if value of Uintptr is as expected. + * + * This method checks if the value of @a obj is equal to the value of @a expected. If + * this is the case, the value of @a obj is changed to @a desired. Otherwise, the value + * of @a obj is changed to @a expected. + * + * @param[in, out] obj The CPU atomic Uintptr to operate upon. + * @param[in, out] expected The expected value of @a obj. If @a obj has a different + * value, @a expected is changed to the actual value of @a obj. + * @param desired The new value of @a obj if the old value of @a obj was as expected. + * @param succ The order if it is successful. + * @param fail The order if it fails. + * + * @retval true The old value of @a obj was as expected. + * @retval false The old value of @a obj was not as expected. + */ +static inline bool _Atomic_Compare_exchange_uintptr( Atomic_Uintptr *obj, uintptr_t *expected, uintptr_t desired, Atomic_Order succ, Atomic_Order fail ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->compare_exchange_strong( *expected, desired, succ, fail ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_compare_exchange_strong_explicit( obj, expected, desired, succ, fail ); +#else + bool success; + ISR_Level level; + uintptr_t actual; + + (void) succ; + (void) fail; + _ISR_Local_disable( level ); + actual = *obj; + success = ( actual == *expected ); + if ( success ) { + *obj = desired; + } else { + *expected = actual; + } + _ISR_Local_enable( level ); + + return success; +#endif +} + +/** + * @brief Clears the atomic flag. + * + * @param[out] obj The atomic flag to be cleared. + * @param order The atomic order for the operation. + */ +static inline void _Atomic_Flag_clear( Atomic_Flag *obj, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + obj->clear( order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + atomic_flag_clear_explicit( obj, order ); +#else + (void) order; + *obj = false; +#endif +} + +/** + * @brief Returns current flag state and sets it. + * + * @param[in, out] obj The atomic flag to be set. + * @param order The atomic order for the operation. + * + * @retval true @a obj was set prior to this operation. + * @retval false @a obj was not set prior to this operation. + */ +static inline bool _Atomic_Flag_test_and_set( Atomic_Flag *obj, Atomic_Order order ) +{ +#if defined(_RTEMS_SCORE_ATOMIC_USE_ATOMIC) + return obj->test_and_set( order ); +#elif defined(_RTEMS_SCORE_ATOMIC_USE_STDATOMIC) + return atomic_flag_test_and_set_explicit( obj, order ); +#else + bool flag; + ISR_Level level; + + (void) order; + _ISR_Local_disable( level ); + flag = *obj; + *obj = true; + _ISR_Local_enable( level ); + + return flag; +#endif +} /** @} */ diff --git a/cpukit/include/rtems/score/basedefs.h b/cpukit/include/rtems/score/basedefs.h index c182ea02ec..010728d795 100644 --- a/cpukit/include/rtems/score/basedefs.h +++ b/cpukit/include/rtems/score/basedefs.h @@ -10,9 +10,9 @@ */ /* - * Copyright (C) 2014 Paval Pisa + * Copyright (C) 2014 Pavel Pisa * Copyright (C) 2011, 2013 On-Line Applications Research Corporation (OAR) - * Copyright (C) 2009, 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2009, 2023 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -75,9 +75,8 @@ extern "C" { /** * @defgroup RTEMSAPI API * - * @brief API - * - * This group contains the RTEMS Application Programming Interface (API). + * @brief This group contains the RTEMS Application Programming Interface + * (API). */ /* Generated from spec:/rtems/basedefs/if/group */ @@ -169,9 +168,9 @@ extern "C" { * * @return Returns the alignment requirement of the type. */ -#if __cplusplus >= 201103L +#if defined( __cplusplus ) && __cplusplus >= 201103L #define RTEMS_ALIGNOF( _type_name ) alignof( _type_name ) -#elif __STDC_VERSION__ >= 201112L +#elif defined( __STDC_VERSION__ ) && __STDC_VERSION__ >= 201112L #define RTEMS_ALIGNOF( _type_name ) _Alignof( _type_name ) #else #define RTEMS_ALIGNOF( _type_name ) sizeof( _type_name ) @@ -355,6 +354,47 @@ extern "C" { */ #define RTEMS_EXPAND( _token ) _token +/* Generated from spec:/rtems/basedefs/if/function-name */ + +/** + * @ingroup RTEMSAPIBaseDefs + * + * @brief Expands to the name of the function containing the use of this + * define. + */ +#if defined(__cplusplus) && defined(__GNUC__) + #define RTEMS_FUNCTION_NAME __PRETTY_FUNCTION__ +#else + #define RTEMS_FUNCTION_NAME __func__ +#endif + +/* Generated from spec:/rtems/basedefs/if/no-return */ + +/** + * @ingroup RTEMSAPIBaseDefs + * + * @brief Tells the compiler in a function declaration that this function does + * not return. + */ +#if defined( __cplusplus ) && __cplusplus >= 201103L + #define RTEMS_NO_RETURN [[noreturn]] +#elif defined( __STDC_VERSION__ ) && __STDC_VERSION__ >= 201112L + #define RTEMS_NO_RETURN _Noreturn +#elif defined(__GNUC__) + #define RTEMS_NO_RETURN __attribute__(( __noreturn__ )) +#else + #define RTEMS_NO_RETURN +#endif + +/* Generated from spec:/rtems/basedefs/if/compiler-no-return-attribute */ + +/** + * @ingroup RTEMSAPIBaseDefs + * + * @brief Provided for backward compatibility. + */ +#define RTEMS_COMPILER_NO_RETURN_ATTRIBUTE RTEMS_NO_RETURN + /* Generated from spec:/rtems/basedefs/if/section */ /** @@ -392,7 +432,7 @@ extern "C" { * * @brief Gets the pointer reference type. * - * @param _level is the pointer indirection level expressed in *. + * @param _level is the pointer indirection level expressed in ``*``. * * @param _target is the reference target type. * @@ -425,17 +465,25 @@ extern "C" { */ #define RTEMS_XCONCAT( _x, _y ) RTEMS_CONCAT( _x, _y ) -/* Generated from spec:/score/basedefs/if/assert-unreachable */ +#if !defined(ASM) && defined(RTEMS_DEBUG) + /* Generated from spec:/score/basedefs/if/debug-unreachable */ -/** - * @ingroup RTEMSScore - * - * @brief Asserts that this program point is unreachable. - */ -#if defined(RTEMS_DEBUG) - #define _Assert_Unreachable() _Assert( 0 ) -#else - #define _Assert_Unreachable() do { } while ( 0 ) + /** + * @ingroup RTEMSScore + * + * @brief Terminates the program with a failed assertion. + * + * @param file is the file name. + * + * @param line is the line of the file. + * + * @param func is the function name. + */ + RTEMS_NO_RETURN void _Debug_Unreachable( + const char *file, + int line, + const char *func + ); #endif #if !defined(ASM) @@ -463,7 +511,7 @@ extern "C" { * @brief Performs a type cast which removes qualifiers without warnings to the * type for the variable. * - * @param _ptr_level is the pointer indirection level expressed in *. + * @param _ptr_level is the pointer indirection level expressed in ``*``. * * @param _type is the target type of the cast. * @@ -614,33 +662,6 @@ extern "C" { #define RTEMS_NO_INLINE #endif -/* Generated from spec:/rtems/basedefs/if/no-return */ - -/** - * @ingroup RTEMSAPIBaseDefs - * - * @brief Tells the compiler in a function declaration that this function does - * not return. - */ -#if __cplusplus >= 201103L - #define RTEMS_NO_RETURN [[noreturn]] -#elif __STDC_VERSION__ >= 201112L - #define RTEMS_NO_RETURN _Noreturn -#elif defined(__GNUC__) - #define RTEMS_NO_RETURN __attribute__(( __noreturn__ )) -#else - #define RTEMS_NO_RETURN -#endif - -/* Generated from spec:/rtems/basedefs/if/compiler-no-return-attribute */ - -/** - * @ingroup RTEMSAPIBaseDefs - * - * @brief Provided for backward compatibility. - */ -#define RTEMS_COMPILER_NO_RETURN_ATTRIBUTE RTEMS_NO_RETURN - /* Generated from spec:/rtems/basedefs/if/noinit */ /** @@ -812,9 +833,9 @@ extern "C" { * * @param _msg is the error message in case the static assertion fails. */ -#if __cplusplus >= 201103L +#if defined( __cplusplus ) && __cplusplus >= 201103L #define RTEMS_STATIC_ASSERT( _cond, _msg ) static_assert( _cond, # _msg ) -#elif __STDC_VERSION__ >= 201112L +#elif defined( __STDC_VERSION__ ) && __STDC_VERSION__ >= 201112L #define RTEMS_STATIC_ASSERT( _cond, _msg ) _Static_assert( _cond, # _msg ) #else #define RTEMS_STATIC_ASSERT( _cond, _msg ) \ @@ -858,14 +879,13 @@ extern "C" { * * @brief Tells the compiler that this program point is unreachable. */ -#if defined(__GNUC__) +#if defined(RTEMS_DEBUG) #define RTEMS_UNREACHABLE() \ - do { \ - __builtin_unreachable(); \ - _Assert_Unreachable(); \ - } while ( 0 ) + _Debug_Unreachable( __FILE__, __LINE__, RTEMS_FUNCTION_NAME ) +#elif defined(__GNUC__) + #define RTEMS_UNREACHABLE() __builtin_unreachable() #else - #define RTEMS_UNREACHABLE() _Assert_Unreachable() + #define RTEMS_UNREACHABLE() do { } while ( 0 ) #endif /* Generated from spec:/rtems/basedefs/if/unused */ @@ -979,11 +999,12 @@ extern "C" { * * @param _value is the value of the symbol. On the value a macro expansion is * performed and afterwards it is stringified. It shall expand to an integer - * expression understood by the assembler. + * expression understood by the assembler. The value shall be representable + * in the code model of the target architecture. * * This macro shall be placed at file scope. */ -#if defined(__USER_LABEL_PREFIX__) +#if defined(__GNUC__) #define RTEMS_DEFINE_GLOBAL_SYMBOL( _name, _value ) \ __asm__( \ "\t.globl " RTEMS_XSTRING( RTEMS_SYMBOL_NAME( _name ) ) \ diff --git a/cpukit/include/rtems/score/chain.h b/cpukit/include/rtems/score/chain.h index 95f2d2b2ef..0b1ede75cf 100644 --- a/cpukit/include/rtems/score/chain.h +++ b/cpukit/include/rtems/score/chain.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2010 embedded brains GmbH. + * Copyright (c) 2010 embedded brains GmbH & Co. KG * * COPYRIGHT (c) 1989-2006. * On-Line Applications Research Corporation (OAR). diff --git a/cpukit/include/rtems/score/chainimpl.h b/cpukit/include/rtems/score/chainimpl.h index 1f0d29cc6d..a2ea5e2645 100644 --- a/cpukit/include/rtems/score/chainimpl.h +++ b/cpukit/include/rtems/score/chainimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2010 embedded brains GmbH. + * Copyright (c) 2010 embedded brains GmbH & Co. KG * * COPYRIGHT (c) 1989-2014. * On-Line Applications Research Corporation (OAR). diff --git a/cpukit/include/rtems/score/copyrt.h b/cpukit/include/rtems/score/copyrt.h index 17067a26cf..21c4bec635 100644 --- a/cpukit/include/rtems/score/copyrt.h +++ b/cpukit/include/rtems/score/copyrt.h @@ -3,7 +3,7 @@ /** * @file * - * @ingroup RTEMSSuperCoreCopyright + * @ingroup RTEMSScoreCopyright * * @brief This header file provides the interfaces of the * @ref RTEMSScoreCopyright. diff --git a/cpukit/include/rtems/score/coremsgbuffer.h b/cpukit/include/rtems/score/coremsgbuffer.h index 330a480423..cceb80bdf5 100644 --- a/cpukit/include/rtems/score/coremsgbuffer.h +++ b/cpukit/include/rtems/score/coremsgbuffer.h @@ -11,7 +11,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2009 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/score/cpustdatomic.h b/cpukit/include/rtems/score/cpustdatomic.h deleted file mode 100644 index 899f52cd83..0000000000 --- a/cpukit/include/rtems/score/cpustdatomic.h +++ /dev/null @@ -1,984 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/** - * @file - * - * @brief This header file provides the interfaces of the - * @ref RTEMSScoreAtomicCPU. - */ - -/* - * COPYRIGHT (c) 2013 Deng Hengyi. - * Copyright (c) 2015 embedded brains GmbH. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#ifndef _RTEMS_SCORE_CPUSTDATOMIC_H -#define _RTEMS_SCORE_CPUSTDATOMIC_H - -#include <rtems/score/basedefs.h> - -/** - * @defgroup RTEMSScoreAtomicCPU C11/C++11 Atomic Operations - * - * @ingroup RTEMSScoreAtomic - * - * @brief This group contains the atomic operations implementation using - * functions provided by the C11/C++11. - * - * @{ - */ - -#ifdef RTEMS_SMP - #if defined(__cplusplus) \ - && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ >= 9)) - /* - * The GCC 4.9 ships its own <stdatomic.h> which is not C++ compatible. The - * suggested solution was to include <atomic> in case C++ is used. This works - * at least with GCC 4.9. See also: - * - * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=60932 - * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=60940 - */ - #include <atomic> - #define _RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC - #else - #include <stdatomic.h> - #define _RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC - #endif -#else - #include <rtems/score/isrlevel.h> -#endif - -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - -typedef std::atomic_uint CPU_atomic_Uint; - -typedef std::atomic_ulong CPU_atomic_Ulong; - -typedef std::atomic_uintptr_t CPU_atomic_Uintptr; - -typedef std::atomic_flag CPU_atomic_Flag; - -typedef std::memory_order CPU_atomic_Order; - -#define CPU_ATOMIC_ORDER_RELAXED std::memory_order_relaxed - -#define CPU_ATOMIC_ORDER_ACQUIRE std::memory_order_acquire - -#define CPU_ATOMIC_ORDER_RELEASE std::memory_order_release - -#define CPU_ATOMIC_ORDER_ACQ_REL std::memory_order_acq_rel - -#define CPU_ATOMIC_ORDER_SEQ_CST std::memory_order_seq_cst - -#define CPU_ATOMIC_INITIALIZER_UINT( value ) ATOMIC_VAR_INIT( value ) - -#define CPU_ATOMIC_INITIALIZER_ULONG( value ) ATOMIC_VAR_INIT( value ) - -#define CPU_ATOMIC_INITIALIZER_UINTPTR( value ) ATOMIC_VAR_INIT( value ) - -#define CPU_ATOMIC_INITIALIZER_FLAG ATOMIC_FLAG_INIT - -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - -typedef atomic_uint CPU_atomic_Uint; - -typedef atomic_ulong CPU_atomic_Ulong; - -typedef atomic_uintptr_t CPU_atomic_Uintptr; - -typedef atomic_flag CPU_atomic_Flag; - -typedef memory_order CPU_atomic_Order; - -#define CPU_ATOMIC_ORDER_RELAXED memory_order_relaxed - -#define CPU_ATOMIC_ORDER_ACQUIRE memory_order_acquire - -#define CPU_ATOMIC_ORDER_RELEASE memory_order_release - -#define CPU_ATOMIC_ORDER_ACQ_REL memory_order_acq_rel - -#define CPU_ATOMIC_ORDER_SEQ_CST memory_order_seq_cst - -#define CPU_ATOMIC_INITIALIZER_UINT( value ) ATOMIC_VAR_INIT( value ) - -#define CPU_ATOMIC_INITIALIZER_ULONG( value ) ATOMIC_VAR_INIT( value ) - -#define CPU_ATOMIC_INITIALIZER_UINTPTR( value ) ATOMIC_VAR_INIT( value ) - -#define CPU_ATOMIC_INITIALIZER_FLAG ATOMIC_FLAG_INIT - -#else - -typedef unsigned int CPU_atomic_Uint; - -typedef unsigned long CPU_atomic_Ulong; - -typedef uintptr_t CPU_atomic_Uintptr; - -typedef bool CPU_atomic_Flag; - -typedef int CPU_atomic_Order; - -#define CPU_ATOMIC_ORDER_RELAXED 0 - -#define CPU_ATOMIC_ORDER_ACQUIRE 2 - -#define CPU_ATOMIC_ORDER_RELEASE 3 - -#define CPU_ATOMIC_ORDER_ACQ_REL 4 - -#define CPU_ATOMIC_ORDER_SEQ_CST 5 - -#define CPU_ATOMIC_INITIALIZER_UINT( value ) ( value ) - -#define CPU_ATOMIC_INITIALIZER_ULONG( value ) ( value ) - -#define CPU_ATOMIC_INITIALIZER_UINTPTR( value ) ( value ) - -#define CPU_ATOMIC_INITIALIZER_FLAG false - -#endif - -/** - * @brief Sets up a cpu fence. - * - * @param[out] order The order for the fence. - */ -static inline void _CPU_atomic_Fence( CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - std::atomic_thread_fence( order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_thread_fence( order ); -#else - (void) order; - RTEMS_COMPILER_MEMORY_BARRIER(); -#endif -} - -/** - * @brief Initializes Uint. - * - * @param[out] obj The CPU atomic Uint to initialize. - * @param desired The desired value for @a obj. - */ -static inline void _CPU_atomic_Init_uint( CPU_atomic_Uint *obj, unsigned int desired ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - obj->store( desired ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_init( obj, desired ); -#else - *obj = desired; -#endif -} - -/** - * @brief Initializes Ulong. - * - * @param[out] obj The CPU atomic Ulong to initialize. - * @param desired The desired value for @a obj. - */ -static inline void _CPU_atomic_Init_ulong( CPU_atomic_Ulong *obj, unsigned long desired ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - obj->store( desired ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_init( obj, desired ); -#else - *obj = desired; -#endif -} - -/** - * @brief Initializes Uintptr. - * - * @param[out] obj The CPU atomic Uintptr to initialize. - * @param desired The desired value for @a obj. - */ -static inline void _CPU_atomic_Init_uintptr( CPU_atomic_Uintptr *obj, uintptr_t desired ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - obj->store( desired ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_init( obj, desired ); -#else - *obj = desired; -#endif -} - -/** - * @brief Loads value of Uint considering the order. - * - * @param obj The CPU atomic Uint to get the value from. - * @param order The atomic order for getting the value. - * - * @return The value of @a obj considering the @a order. - */ -static inline unsigned int _CPU_atomic_Load_uint( const CPU_atomic_Uint *obj, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->load( order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_load_explicit( obj, order ); -#else - unsigned int val; - - (void) order; - val = *obj; - RTEMS_COMPILER_MEMORY_BARRIER(); - - return val; -#endif -} - -/** - * @brief Loads value of Ulong considering the order. - * - * @param obj The CPU atomic Ulong to get the value from. - * @param order The atomic order for getting the value. - * - * @return The value of @a obj considering the @a order. - */ -static inline unsigned long _CPU_atomic_Load_ulong( const CPU_atomic_Ulong *obj, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->load( order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_load_explicit( obj, order ); -#else - unsigned long val; - - (void) order; - val = *obj; - RTEMS_COMPILER_MEMORY_BARRIER(); - - return val; -#endif -} - -/** - * @brief Loads value of Uintptr considering the order. - * - * @param obj The CPU atomic Uintptr to get the value from. - * @param order The atomic order for getting the value. - * - * @return The value of @a obj considering the @a order. - */ -static inline uintptr_t _CPU_atomic_Load_uintptr( const CPU_atomic_Uintptr *obj, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->load( order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_load_explicit( obj, order ); -#else - uintptr_t val; - - (void) order; - val = *obj; - RTEMS_COMPILER_MEMORY_BARRIER(); - - return val; -#endif -} - -/** - * @brief Stores a value to Uint considering the order. - * - * @param[out] obj The CPU atomic Uint to store a value in. - * @param desired The desired value for @a obj. - * @param order The atomic order for storing the value. - */ -static inline void _CPU_atomic_Store_uint( CPU_atomic_Uint *obj, unsigned int desired, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - obj->store( desired, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_store_explicit( obj, desired, order ); -#else - (void) order; - RTEMS_COMPILER_MEMORY_BARRIER(); - *obj = desired; -#endif -} - -/** - * @brief Stores a value to Ulong considering the order. - * - * @param[out] obj The CPU atomic Ulong to store a value in. - * @param desired The desired value for @a obj. - * @param order The atomic order for storing the value. - */ -static inline void _CPU_atomic_Store_ulong( CPU_atomic_Ulong *obj, unsigned long desired, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - obj->store( desired, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_store_explicit( obj, desired, order ); -#else - (void) order; - RTEMS_COMPILER_MEMORY_BARRIER(); - *obj = desired; -#endif -} - -/** - * @brief Stores a value to Uintptr considering the order. - * - * @param[out] obj The CPU atomic Uintptr to store a value in. - * @param desired The desired value for @a obj. - * @param order The atomic order for storing the value. - */ -static inline void _CPU_atomic_Store_uintptr( CPU_atomic_Uintptr *obj, uintptr_t desired, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - obj->store( desired, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_store_explicit( obj, desired, order ); -#else - (void) order; - RTEMS_COMPILER_MEMORY_BARRIER(); - *obj = desired; -#endif -} - -/** - * @brief Fetches current value of Uint and adds a value to the stored value. - * - * @param[in, out] obj The CPU atomic Uint to get the value from and add @a arg to. - * @param arg The value to add to @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the addition of @a arg. - */ -static inline unsigned int _CPU_atomic_Fetch_add_uint( CPU_atomic_Uint *obj, unsigned int arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_add( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_add_explicit( obj, arg, order ); -#else - unsigned int val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val + arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Ulong and adds a value to the stored value. - * - * @param[in, out] obj The CPU atomic Ulong to get the value from and add @a arg to. - * @param arg The value to add to @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the addition of @a arg. - */ -static inline unsigned long _CPU_atomic_Fetch_add_ulong( CPU_atomic_Ulong *obj, unsigned long arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_add( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_add_explicit( obj, arg, order ); -#else - unsigned long val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val + arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uintptr and adds a value to the stored value. - * - * @param[in, out] obj The CPU atomic Uintptr to get the value from and add @a arg to. - * @param arg The value to add to @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the addition of @a arg. - */ -static inline uintptr_t _CPU_atomic_Fetch_add_uintptr( CPU_atomic_Uintptr *obj, uintptr_t arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_add( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_add_explicit( obj, arg, order ); -#else - uintptr_t val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val + arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uint and subtracts a value from the stored value. - * - * @param[in, out] obj The CPU atomic Uint to get the value from and subtract @a arg from. - * @param arg The value to subtract from @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the subtraction of @a arg. - */ -static inline unsigned int _CPU_atomic_Fetch_sub_uint( CPU_atomic_Uint *obj, unsigned int arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_sub( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_sub_explicit( obj, arg, order ); -#else - unsigned int val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val - arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Ulong and subtracts a value from the stored value. - * - * @param[in, out] obj The CPU atomic Ulong to get the value from and subtract @a arg from. - * @param arg The value to subtract from @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the subtraction of @a arg. - */ -static inline unsigned long _CPU_atomic_Fetch_sub_ulong( CPU_atomic_Ulong *obj, unsigned long arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_sub( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_sub_explicit( obj, arg, order ); -#else - unsigned long val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val - arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uintptr and subtracts a value from the stored value. - * - * @param[in, out] obj The CPU atomic Uintptr to get the value from and subtract @a arg from. - * @param arg The value to subtract from @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the subtraction of @a arg. - */ -static inline uintptr_t _CPU_atomic_Fetch_sub_uintptr( CPU_atomic_Uintptr *obj, uintptr_t arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_sub( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_sub_explicit( obj, arg, order ); -#else - uintptr_t val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val - arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uint and ORs a value with the stored value. - * - * @param[in, out] obj The CPU atomic Uint to get the value from and OR @a arg to. - * @param arg The value to OR with @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the OR operation with @a arg. - */ -static inline unsigned int _CPU_atomic_Fetch_or_uint( CPU_atomic_Uint *obj, unsigned int arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_or( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_or_explicit( obj, arg, order ); -#else - unsigned int val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val | arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Ulong and ORs a value with the stored value. - * - * @param[in, out] obj The CPU atomic Ulong to get the value from and OR @a arg to. - * @param arg The value to OR with @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the OR operation with @a arg. - */ -static inline unsigned long _CPU_atomic_Fetch_or_ulong( CPU_atomic_Ulong *obj, unsigned long arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_or( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_or_explicit( obj, arg, order ); -#else - unsigned long val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val | arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uintptr and ORs a value with the stored value. - * - * @param[in, out] obj The CPU atomic Uintptr to get the value from and OR @a arg to. - * @param arg The value to OR with @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the OR operation with @a arg. - */ -static inline uintptr_t _CPU_atomic_Fetch_or_uintptr( CPU_atomic_Uintptr *obj, uintptr_t arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_or( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_or_explicit( obj, arg, order ); -#else - uintptr_t val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val | arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uint and ANDs a value with the stored value. - * - * @param[in, out] obj The CPU atomic Uint to get the value from and AND @a arg to. - * @param arg The value to AND with @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the AND operation with @a arg. - */ -static inline unsigned int _CPU_atomic_Fetch_and_uint( CPU_atomic_Uint *obj, unsigned int arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_and( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_and_explicit( obj, arg, order ); -#else - unsigned int val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val & arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Ulong and ANDs a value with the stored value. - * - * @param[in, out] obj The CPU atomic Ulong to get the value from and AND @a arg to. - * @param arg The value to AND with @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the AND operation with @a arg. - */ -static inline unsigned long _CPU_atomic_Fetch_and_ulong( CPU_atomic_Ulong *obj, unsigned long arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_and( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_and_explicit( obj, arg, order ); -#else - unsigned long val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val & arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uintptr and ANDs a value with the stored value. - * - * @param[in, out] obj The CPU atomic Uintptr to get the value from and AND @a arg to. - * @param arg The value to AND with @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the AND operation with @a arg. - */ -static inline uintptr_t _CPU_atomic_Fetch_and_uintptr( CPU_atomic_Uintptr *obj, uintptr_t arg, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->fetch_and( arg, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_fetch_and_explicit( obj, arg, order ); -#else - uintptr_t val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = val & arg; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uint and sets its value. - * - * @param[in, out] obj The CPU atomic Uint to get the value from and set the value to @a desired. - * @param arg The value to set for @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the exchange with @a desired. - */ -static inline unsigned int _CPU_atomic_Exchange_uint( CPU_atomic_Uint *obj, unsigned int desired, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->exchange( desired, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_exchange_explicit( obj, desired, order ); -#else - unsigned int val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = desired; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Ulong and sets its value. - * - * @param[in, out] obj The CPU atomic Ulong to get the value from and set the value to @a desired. - * @param arg The value to set for @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the exchange with @a desired. - */ -static inline unsigned long _CPU_atomic_Exchange_ulong( CPU_atomic_Ulong *obj, unsigned long desired, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->exchange( desired, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_exchange_explicit( obj, desired, order ); -#else - unsigned long val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = desired; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Fetches current value of Uintptr and sets its value. - * - * @param[in, out] obj The CPU atomic Uintptr to get the value from and set the value to @a desired. - * @param arg The value to set for @a obj. - * @param order The atomic order for the operation. - * - * @return The value of @a obj prior to the exchange with @a desired. - */ -static inline uintptr_t _CPU_atomic_Exchange_uintptr( CPU_atomic_Uintptr *obj, uintptr_t desired, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->exchange( desired, order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_exchange_explicit( obj, desired, order ); -#else - uintptr_t val; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - val = *obj; - *obj = desired; - _ISR_Local_enable( level ); - - return val; -#endif -} - -/** - * @brief Checks if value of Uint is as expected. - * - * This method checks if the value of @a obj is equal to the value of @a expected. If - * this is the case, the value of @a obj is changed to @a desired. Otherwise, the value - * of @a obj is changed to @a expected. - * - * @param[in, out] obj The CPU atomic Uint to operate upon. - * @param[in, out] expected The expected value of @a obj. If @a obj has a different - * value, @a expected is changed to the actual value of @a obj. - * @param desired The new value of @a obj if the old value of @a obj was as expected. - * @param succ The order if it is successful. - * @param fail The order if it fails. - * - * @retval true The old value of @a obj was as expected. - * @retval false The old value of @a obj was not as expected. - */ -static inline bool _CPU_atomic_Compare_exchange_uint( CPU_atomic_Uint *obj, unsigned int *expected, unsigned int desired, CPU_atomic_Order succ, CPU_atomic_Order fail ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->compare_exchange_strong( *expected, desired, succ, fail ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_compare_exchange_strong_explicit( obj, expected, desired, succ, fail ); -#else - bool success; - ISR_Level level; - unsigned int actual; - - (void) succ; - (void) fail; - _ISR_Local_disable( level ); - actual = *obj; - success = ( actual == *expected ); - if ( success ) { - *obj = desired; - } else { - *expected = actual; - } - _ISR_Local_enable( level ); - - return success; -#endif -} - -/** - * @brief Checks if value of Ulong is as expected. - * - * This method checks if the value of @a obj is equal to the value of @a expected. If - * this is the case, the value of @a obj is changed to @a desired. Otherwise, the value - * of @a obj is changed to @a expected. - * - * @param[in, out] obj The CPU atomic Ulong to operate upon. - * @param[in, out] expected The expected value of @a obj. If @a obj has a different - * value, @a expected is changed to the actual value of @a obj. - * @param desired The new value of @a obj if the old value of @a obj was as expected. - * @param succ The order if it is successful. - * @param fail The order if it fails. - * - * @retval true The old value of @a obj was as expected. - * @retval false The old value of @a obj was not as expected. - */ -static inline bool _CPU_atomic_Compare_exchange_ulong( CPU_atomic_Ulong *obj, unsigned long *expected, unsigned long desired, CPU_atomic_Order succ, CPU_atomic_Order fail ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->compare_exchange_strong( *expected, desired, succ, fail ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_compare_exchange_strong_explicit( obj, expected, desired, succ, fail ); -#else - bool success; - ISR_Level level; - unsigned long actual; - - (void) succ; - (void) fail; - _ISR_Local_disable( level ); - actual = *obj; - success = ( actual == *expected ); - if ( success ) { - *obj = desired; - } else { - *expected = actual; - } - _ISR_Local_enable( level ); - - return success; -#endif -} - -/** - * @brief Checks if value of Uintptr is as expected. - * - * This method checks if the value of @a obj is equal to the value of @a expected. If - * this is the case, the value of @a obj is changed to @a desired. Otherwise, the value - * of @a obj is changed to @a expected. - * - * @param[in, out] obj The CPU atomic Uintptr to operate upon. - * @param[in, out] expected The expected value of @a obj. If @a obj has a different - * value, @a expected is changed to the actual value of @a obj. - * @param desired The new value of @a obj if the old value of @a obj was as expected. - * @param succ The order if it is successful. - * @param fail The order if it fails. - * - * @retval true The old value of @a obj was as expected. - * @retval false The old value of @a obj was not as expected. - */ -static inline bool _CPU_atomic_Compare_exchange_uintptr( CPU_atomic_Uintptr *obj, uintptr_t *expected, uintptr_t desired, CPU_atomic_Order succ, CPU_atomic_Order fail ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->compare_exchange_strong( *expected, desired, succ, fail ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_compare_exchange_strong_explicit( obj, expected, desired, succ, fail ); -#else - bool success; - ISR_Level level; - uintptr_t actual; - - (void) succ; - (void) fail; - _ISR_Local_disable( level ); - actual = *obj; - success = ( actual == *expected ); - if ( success ) { - *obj = desired; - } else { - *expected = actual; - } - _ISR_Local_enable( level ); - - return success; -#endif -} - -/** - * @brief Clears the atomic flag. - * - * @param[out] obj The atomic flag to be cleared. - * @param order The atomic order for the operation. - */ -static inline void _CPU_atomic_Flag_clear( CPU_atomic_Flag *obj, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - obj->clear( order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - atomic_flag_clear_explicit( obj, order ); -#else - (void) order; - *obj = false; -#endif -} - -/** - * @brief Returns current flag state and sets it. - * - * @param[in, out] obj The atomic flag to be set. - * @param order The atomic order for the operation. - * - * @retval true @a obj was set prior to this operation. - * @retval false @a obj was not set prior to this operation. - */ -static inline bool _CPU_atomic_Flag_test_and_set( CPU_atomic_Flag *obj, CPU_atomic_Order order ) -{ -#if defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_ATOMIC) - return obj->test_and_set( order ); -#elif defined(_RTEMS_SCORE_CPUSTDATOMIC_USE_STDATOMIC) - return atomic_flag_test_and_set_explicit( obj, order ); -#else - bool flag; - ISR_Level level; - - (void) order; - _ISR_Local_disable( level ); - flag = *obj; - *obj = true; - _ISR_Local_enable( level ); - - return flag; -#endif -} - -/** @} */ - -#endif /* _RTEMS_SCORE_CPUSTDATOMIC_H */ diff --git a/cpukit/include/rtems/score/hash.h b/cpukit/include/rtems/score/hash.h index 06c88c6948..666407a791 100644 --- a/cpukit/include/rtems/score/hash.h +++ b/cpukit/include/rtems/score/hash.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/isr.h b/cpukit/include/rtems/score/isr.h index bb1f3cee50..96ad816245 100644 --- a/cpukit/include/rtems/score/isr.h +++ b/cpukit/include/rtems/score/isr.h @@ -98,7 +98,11 @@ extern ISR_Handler_entry _ISR_Vector_table[ CPU_INTERRUPT_NUMBER_OF_VECTORS ]; #endif /** - * @brief Global symbol with a value equal to the configure interrupt stack size. + * @brief Provides the configured interrupt stack size through an address. + * + * The address of this global symbol is equal to the configured interrupt stack + * size. The address of this symbol has an arbitrary value an may not be + * representable in the code model used by the compiler. * * This global symbol is defined by the application configuration option * CONFIGURE_INIT_TASK_STACK_SIZE via <rtems/confdefs.h>. @@ -106,6 +110,14 @@ extern ISR_Handler_entry _ISR_Vector_table[ CPU_INTERRUPT_NUMBER_OF_VECTORS ]; RTEMS_DECLARE_GLOBAL_SYMBOL( _ISR_Stack_size ); /** + * @brief Provides the configured interrupt stack size through an object. + * + * This object is provided to avoid issues with the _ISR_Stack_size symbol + * address and the code model used by the compiler. + */ +extern const char * const volatile _ISR_Stack_size_object; + +/** * @brief The interrupt stack area begin. * * The interrupt stack area is defined by the application configuration via diff --git a/cpukit/include/rtems/score/isrlock.h b/cpukit/include/rtems/score/isrlock.h index 72ac760196..7586624f9d 100644 --- a/cpukit/include/rtems/score/isrlock.h +++ b/cpukit/include/rtems/score/isrlock.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2013, 2019 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2019 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/memory.h b/cpukit/include/rtems/score/memory.h index 7eceef360b..a593d98d76 100644 --- a/cpukit/include/rtems/score/memory.h +++ b/cpukit/include/rtems/score/memory.h @@ -10,7 +10,7 @@ /* * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (C) 2019, 2022 embedded brains GmbH + * Copyright (C) 2019, 2022 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/mpci.h b/cpukit/include/rtems/score/mpci.h index 874c195e95..796c881929 100644 --- a/cpukit/include/rtems/score/mpci.h +++ b/cpukit/include/rtems/score/mpci.h @@ -40,9 +40,6 @@ #define _RTEMS_SCORE_MPCI_H #include <rtems/score/mppkt.h> -#include <rtems/score/thread.h> -#include <rtems/score/threadq.h> -#include <rtems/score/watchdog.h> #ifdef __cplusplus extern "C" { diff --git a/cpukit/include/rtems/score/mpciimpl.h b/cpukit/include/rtems/score/mpciimpl.h index b646d4be4d..d0c2d0558a 100644 --- a/cpukit/include/rtems/score/mpciimpl.h +++ b/cpukit/include/rtems/score/mpciimpl.h @@ -39,6 +39,9 @@ #define _RTEMS_SCORE_MPCIIMPL_H #include <rtems/score/mpci.h> +#include <rtems/score/thread.h> +#include <rtems/score/threadq.h> +#include <rtems/score/watchdog.h> #include <rtems/score/status.h> #ifdef __cplusplus diff --git a/cpukit/include/rtems/score/mrsp.h b/cpukit/include/rtems/score/mrsp.h index 266e52fc60..cd9b0a046d 100644 --- a/cpukit/include/rtems/score/mrsp.h +++ b/cpukit/include/rtems/score/mrsp.h @@ -11,7 +11,7 @@ */ /* - * Copyright (c) 2014, 2016 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/mrspimpl.h b/cpukit/include/rtems/score/mrspimpl.h index 4a5e68fa41..fd783bf2a0 100644 --- a/cpukit/include/rtems/score/mrspimpl.h +++ b/cpukit/include/rtems/score/mrspimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2014, 2019 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2019 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -130,6 +130,7 @@ static inline Priority_Control _MRSP_Get_priority( uint32_t scheduler_index; scheduler_index = _Scheduler_Get_index( scheduler ); + _Assert( scheduler_index < _Scheduler_Count ); return mrsp->ceiling_priorities[ scheduler_index ]; } @@ -149,6 +150,7 @@ static inline void _MRSP_Set_priority( uint32_t scheduler_index; scheduler_index = _Scheduler_Get_index( scheduler ); + _Assert( scheduler_index < _Scheduler_Count ); mrsp->ceiling_priorities[ scheduler_index ] = new_priority; } diff --git a/cpukit/include/rtems/score/muteximpl.h b/cpukit/include/rtems/score/muteximpl.h index c024a00060..aa76b7e7b8 100644 --- a/cpukit/include/rtems/score/muteximpl.h +++ b/cpukit/include/rtems/score/muteximpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2015, 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2015, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/objectimpl.h b/cpukit/include/rtems/score/objectimpl.h index c58957ccb5..a1a87b5ccb 100644 --- a/cpukit/include/rtems/score/objectimpl.h +++ b/cpukit/include/rtems/score/objectimpl.h @@ -542,9 +542,7 @@ static inline bool _Objects_Is_api_valid( uint32_t the_api ) { - if ( !the_api || the_api > OBJECTS_APIS_LAST ) - return false; - return true; + return ( 1 <= the_api && the_api <= OBJECTS_APIS_LAST ); } /** diff --git a/cpukit/include/rtems/score/onceimpl.h b/cpukit/include/rtems/score/onceimpl.h index 2060a376a2..9552cc0a67 100644 --- a/cpukit/include/rtems/score/onceimpl.h +++ b/cpukit/include/rtems/score/onceimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2014, 2019 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2019 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/percpu.h b/cpukit/include/rtems/score/percpu.h index f740ed2a00..288445bc6f 100644 --- a/cpukit/include/rtems/score/percpu.h +++ b/cpukit/include/rtems/score/percpu.h @@ -13,7 +13,7 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2012, 2018 embedded brains GmbH + * Copyright (C) 2012, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/percpudata.h b/cpukit/include/rtems/score/percpudata.h index 07045525bc..817adde232 100644 --- a/cpukit/include/rtems/score/percpudata.h +++ b/cpukit/include/rtems/score/percpudata.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2018 embedded brains GmbH. All rights reserved. + * Copyright (c) 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/priority.h b/cpukit/include/rtems/score/priority.h index aa29fef8c0..bbb8fd03f2 100644 --- a/cpukit/include/rtems/score/priority.h +++ b/cpukit/include/rtems/score/priority.h @@ -14,7 +14,7 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2016, 2017 embedded brains GmbH. + * Copyright (C) 2016, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/priorityimpl.h b/cpukit/include/rtems/score/priorityimpl.h index ccd4cd7c64..2a95ea605c 100644 --- a/cpukit/include/rtems/score/priorityimpl.h +++ b/cpukit/include/rtems/score/priorityimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2016 embedded brains GmbH. All rights reserved. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/processormask.h b/cpukit/include/rtems/score/processormask.h index 7ad6ea6edb..71ed37cd0e 100644 --- a/cpukit/include/rtems/score/processormask.h +++ b/cpukit/include/rtems/score/processormask.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2016, 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2016, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -39,9 +39,7 @@ #include <rtems/score/cpu.h> -#include <sys/cpuset.h> - -#include <strings.h> +#include <sys/_bitset.h> #ifdef __cplusplus extern "C" { @@ -123,381 +121,6 @@ extern "C" { */ typedef __BITSET_DEFINE( Processor_mask, CPU_MAXIMUM_PROCESSORS ) Processor_mask; -/** - * @brief Sets the bits of the mask to zero, also considers CPU_MAXIMUM_PROCESSORS. - * - * @param[out] mask The mask to set to zero. - */ -static inline void _Processor_mask_Zero( Processor_mask *mask ) -{ - __BIT_ZERO( CPU_MAXIMUM_PROCESSORS, mask ); -} - -/** - * @brief Checks if the mask is zero, also considers CPU_MAXIMUM_PROCESSORS. - * - * @param mask The mask to check whether is is zero - * - * @retval true The mask is zero. - * @retval false The mask is not zero. - */ -static inline bool _Processor_mask_Is_zero( const Processor_mask *mask ) -{ - return __BIT_EMPTY( CPU_MAXIMUM_PROCESSORS, mask ); -} - -/** - * @brief Fills the mask, also considers CPU_MAXIMUM_PROCESSORS. - * - * @param[out] mask The mask to fill - */ -static inline void _Processor_mask_Fill( Processor_mask *mask ) -{ - __BIT_FILL( CPU_MAXIMUM_PROCESSORS, mask ); -} - -/** - * @brief Copies the mask to another mask, also considers CPU_MAXIMUM_PROCESSORS. - * - * @param[out] dst The mask to copy @a src to. - * @param src The mask to copy to @a dst. - */ -static inline void _Processor_mask_Assign( - Processor_mask *dst, const Processor_mask *src -) -{ - __BIT_COPY( CPU_MAXIMUM_PROCESSORS, src, dst ); -} - -/** - * @brief Sets the specified index bit of the mask. - * - * @param[out] mask The mask to set the bit of. - * @param index The index of the bit that shall be set. - */ -static inline void _Processor_mask_Set( - Processor_mask *mask, - uint32_t index -) -{ - __BIT_SET( CPU_MAXIMUM_PROCESSORS, index, mask ); -} - -/** - * @brief Clears the specified index bit of the mask. - * - * @param[out] mask The mask to clear the bit of. - * @param index The index of the bit that shall be cleared. - */ -static inline void _Processor_mask_Clear( - Processor_mask *mask, - uint32_t index -) -{ - __BIT_CLR( CPU_MAXIMUM_PROCESSORS, index, mask ); -} - -/** - * @brief Checks if the specified index bit of the mask is set. - * - * @param mask The mask to check if the specified bit is set. - * @param index The index of the bit that is checked. - * - * @retval true The specified index bit is set. - * @retval false The specified index bit is not set. - */ -static inline bool _Processor_mask_Is_set( - const Processor_mask *mask, - uint32_t index -) -{ - return __BIT_ISSET( CPU_MAXIMUM_PROCESSORS, index, mask ); -} - -/** - * @brief Checks if the processor sets a and b are equal. - * - * @param a The first processor set. - * @param b The seconde processor set. - * - * @retval true The processor sets a and b are equal. - * @retval false The processor sets a and b are not equal. - */ -static inline bool _Processor_mask_Is_equal( - const Processor_mask *a, - const Processor_mask *b -) -{ - return !__BIT_CMP( CPU_MAXIMUM_PROCESSORS, a, b ); -} - -/** - * @brief Checks if the intersection of the processor sets a and b is - * non-empty. - * - * @param a The first processor set. - * @param b The second processor set. - * - * @retval true The intersection of the processor sets a and b is non-empty. - * @retval false The intersection of the processor sets a and b is empty. - */ -static inline bool _Processor_mask_Has_overlap( - const Processor_mask *a, - const Processor_mask *b -) -{ - return __BIT_OVERLAP( CPU_MAXIMUM_PROCESSORS, a, b ); -} - -/** - * @brief Checks if the processor set small is a subset of processor set - * big. - * - * @param big The bigger processor set. - * @param small The smaller processor set. - * - * @retval true @a small is a subset of @a big. - * @retval false @a small is not a subset of @a big. - */ -static inline bool _Processor_mask_Is_subset( - const Processor_mask *big, - const Processor_mask *small -) -{ - return __BIT_SUBSET( CPU_MAXIMUM_PROCESSORS, big, small ); -} - -/** - * @brief Performs a bitwise a = b & c. - * - * @param[out] a The processor mask that is set by this operation. - * @param b The first parameter of the AND-operation. - * @param c The second parameter of the AND-operation. - */ -static inline void _Processor_mask_And( - Processor_mask *a, - const Processor_mask *b, - const Processor_mask *c -) -{ - __BIT_AND2( CPU_MAXIMUM_PROCESSORS, a, b, c ); -} - -/** - * @brief Performs a bitwise a = b | c. - * - * @param[out] a The processor mask that is set by this operation. - * @param b The first parameter of the OR-operation. - * @param c The second parameter of the OR-operation. - */ -static inline void _Processor_mask_Or( - Processor_mask *a, - const Processor_mask *b, - const Processor_mask *c -) -{ - __BIT_OR2( CPU_MAXIMUM_PROCESSORS, a, b, c ); -} - -/** - * @brief Performs a bitwise a = b ^ c. - * - * @param[out] a The processor mask that is set by this operation. - * @param b The first parameter of the XOR-operation. - * @param c The second parameter of the XOR-operation. - */ -static inline void _Processor_mask_Xor( - Processor_mask *a, - const Processor_mask *b, - const Processor_mask *c -) -{ - __BIT_XOR2( CPU_MAXIMUM_PROCESSORS, a, b, c ); -} - -/** - * @brief Gets the number of set bits in the processor mask. - * - * @param a The processor mask of which the set bits are counted. - * - * @return The number of set bits in @a a. - */ -static inline uint32_t _Processor_mask_Count( const Processor_mask *a ) -{ - return (uint32_t) __BIT_COUNT( CPU_MAXIMUM_PROCESSORS, a ); -} - -/** - * @brief Finds the last set of the processor mask. - * - * @param a The processor mask wo find the last set of. - * - * @return The last set of @a a. - */ -static inline uint32_t _Processor_mask_Find_last_set( const Processor_mask *a ) -{ - return (uint32_t) __BIT_FLS( CPU_MAXIMUM_PROCESSORS, a ); -} - -/** - * @brief Returns the subset of 32 processors containing the specified index as - * an unsigned 32-bit integer. - * - * @param mask The processor mask. - * @param index The specified index. - * - * @return The subset containing the specified index as an unsigned 32-bit integer. - */ -static inline uint32_t _Processor_mask_To_uint32_t( - const Processor_mask *mask, - uint32_t index -) -{ - long bits = mask->__bits[ index / _BITSET_BITS ]; - - return (uint32_t) ( bits >> ( 32 * ( ( index % _BITSET_BITS ) / 32 ) ) ); -} - -/** - * @brief Creates a processor set from an unsigned 32-bit integer relative to - * the specified index. - * - * @param[out] mask The mask that is created. - * @param bits The bits for creating the mask. - * @param index The index to which the mask is relative. - */ -static inline void _Processor_mask_From_uint32_t( - Processor_mask *mask, - uint32_t bits, - uint32_t index -) -{ - _Processor_mask_Zero( mask ); - mask->__bits[ __bitset_words( index ) ] = ((long) bits) << (32 * (index % _BITSET_BITS) / 32); -} - -/** - * @brief Creates a processor set from the specified index. - * - * @param[out] The mask that is created. - * @param index The specified index. - */ -static inline void _Processor_mask_From_index( - Processor_mask *mask, - uint32_t index -) -{ - __BIT_SETOF( CPU_MAXIMUM_PROCESSORS, (int) index, mask ); -} - -typedef enum { - PROCESSOR_MASK_COPY_LOSSLESS, - PROCESSOR_MASK_COPY_PARTIAL_LOSS, - PROCESSOR_MASK_COPY_COMPLETE_LOSS, - PROCESSOR_MASK_COPY_INVALID_SIZE -} Processor_mask_Copy_status; - -/** - * @brief Checks if the copy status guarantees at most partial loss. - * - * @param status The copy status to check. - * - * @retval true At most partial loss can be guaranteed. - * @retval false The status indicates more than partial loss. - */ -static inline bool _Processor_mask_Is_at_most_partial_loss( - Processor_mask_Copy_status status -) -{ - return (unsigned int) status <= PROCESSOR_MASK_COPY_PARTIAL_LOSS; -} - -/** - * @brief Copies one mask to another. - * - * @param[out] dst The destination of the copy operation. - * @param dst_size The size of @a dst. - * @param src The source of the copy operation. - * @param src_size The size of @a src. - * - * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy - * operation is lossless. - * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due - * to the sizes of @a src and @a dst. - * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due - * to the sizes of @a src and @a dst. - * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes - * is invalid (bigger than the size of a long). - */ -Processor_mask_Copy_status _Processor_mask_Copy( - long *dst, - size_t dst_size, - const long *src, - size_t src_size -); - -/** - * @brief Copies one mask to another. - * - * @param src The source for the copy operation. - * @param dst_size The size of @a dst. - * @param[out] dst The destination for the copy operation. - * - * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy - * operation is lossless. - * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due - * to the sizes of @a src and @a dst. - * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due - * to the sizes of @a src and @a dst. - * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes - * is invalid (bigger than the size of a long). - */ -static inline Processor_mask_Copy_status _Processor_mask_To_cpu_set_t( - const Processor_mask *src, - size_t dst_size, - cpu_set_t *dst -) -{ - return _Processor_mask_Copy( - &dst->__bits[ 0 ], - dst_size, - &src->__bits[ 0 ], - sizeof( *src ) - ); -} - -/** - * @brief Copies one mask to another. - * - * @param src The source for the copy operation. - * @param src_size The size of @a src. - * @param[out] dst The destination for the copy operation. - * - * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy - * operation is lossless. - * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due - * to the sizes of @a src and @a dst. - * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due - * to the sizes of @a src and @a dst. - * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes - * is invalid (bigger than the size of a long). - */ -static inline Processor_mask_Copy_status _Processor_mask_From_cpu_set_t( - Processor_mask *dst, - size_t src_size, - const cpu_set_t *src -) -{ - return _Processor_mask_Copy( - &dst->__bits[ 0 ], - sizeof( *dst ), - &src->__bits[ 0 ], - src_size - ); -} - -extern const Processor_mask _Processor_mask_The_one_and_only; - /** @} */ #ifdef __cplusplus diff --git a/cpukit/include/rtems/score/processormaskimpl.h b/cpukit/include/rtems/score/processormaskimpl.h new file mode 100644 index 0000000000..bc997edfd4 --- /dev/null +++ b/cpukit/include/rtems/score/processormaskimpl.h @@ -0,0 +1,437 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup RTEMSScoreProcessorMask + * + * @brief This header file provides the interfaces of the + * @ref RTEMSScoreProcessorMask. + */ + +/* + * Copyright (C) 2016, 2017 embedded brains GmbH & Co. KG + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef _RTEMS_SCORE_PROCESSORMASKIMPL_H +#define _RTEMS_SCORE_PROCESSORMASKIMPL_H + +#include <rtems/score/processormask.h> + +#include <sys/cpuset.h> + +#include <strings.h> + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/** + * @addtogroup RTEMSScoreProcessorMask + * + * @{ + */ + +/** + * @brief Sets the bits of the mask to zero, also considers CPU_MAXIMUM_PROCESSORS. + * + * @param[out] mask The mask to set to zero. + */ +static inline void _Processor_mask_Zero( Processor_mask *mask ) +{ + __BIT_ZERO( CPU_MAXIMUM_PROCESSORS, mask ); +} + +/** + * @brief Checks if the mask is zero, also considers CPU_MAXIMUM_PROCESSORS. + * + * @param mask The mask to check whether is is zero + * + * @retval true The mask is zero. + * @retval false The mask is not zero. + */ +static inline bool _Processor_mask_Is_zero( const Processor_mask *mask ) +{ + return __BIT_EMPTY( CPU_MAXIMUM_PROCESSORS, mask ); +} + +/** + * @brief Fills the mask, also considers CPU_MAXIMUM_PROCESSORS. + * + * @param[out] mask The mask to fill + */ +static inline void _Processor_mask_Fill( Processor_mask *mask ) +{ + __BIT_FILL( CPU_MAXIMUM_PROCESSORS, mask ); +} + +/** + * @brief Copies the mask to another mask, also considers CPU_MAXIMUM_PROCESSORS. + * + * @param[out] dst The mask to copy @a src to. + * @param src The mask to copy to @a dst. + */ +static inline void _Processor_mask_Assign( + Processor_mask *dst, const Processor_mask *src +) +{ + __BIT_COPY( CPU_MAXIMUM_PROCESSORS, src, dst ); +} + +/** + * @brief Sets the specified index bit of the mask. + * + * @param[out] mask The mask to set the bit of. + * @param index The index of the bit that shall be set. + */ +static inline void _Processor_mask_Set( + Processor_mask *mask, + uint32_t index +) +{ + __BIT_SET( CPU_MAXIMUM_PROCESSORS, index, mask ); +} + +/** + * @brief Clears the specified index bit of the mask. + * + * @param[out] mask The mask to clear the bit of. + * @param index The index of the bit that shall be cleared. + */ +static inline void _Processor_mask_Clear( + Processor_mask *mask, + uint32_t index +) +{ + __BIT_CLR( CPU_MAXIMUM_PROCESSORS, index, mask ); +} + +/** + * @brief Checks if the specified index bit of the mask is set. + * + * @param mask The mask to check if the specified bit is set. + * @param index The index of the bit that is checked. + * + * @retval true The specified index bit is set. + * @retval false The specified index bit is not set. + */ +static inline bool _Processor_mask_Is_set( + const Processor_mask *mask, + uint32_t index +) +{ + return __BIT_ISSET( CPU_MAXIMUM_PROCESSORS, index, mask ); +} + +/** + * @brief Checks if the processor sets a and b are equal. + * + * @param a The first processor set. + * @param b The seconde processor set. + * + * @retval true The processor sets a and b are equal. + * @retval false The processor sets a and b are not equal. + */ +static inline bool _Processor_mask_Is_equal( + const Processor_mask *a, + const Processor_mask *b +) +{ + return !__BIT_CMP( CPU_MAXIMUM_PROCESSORS, a, b ); +} + +/** + * @brief Checks if the intersection of the processor sets a and b is + * non-empty. + * + * @param a The first processor set. + * @param b The second processor set. + * + * @retval true The intersection of the processor sets a and b is non-empty. + * @retval false The intersection of the processor sets a and b is empty. + */ +static inline bool _Processor_mask_Has_overlap( + const Processor_mask *a, + const Processor_mask *b +) +{ + return __BIT_OVERLAP( CPU_MAXIMUM_PROCESSORS, a, b ); +} + +/** + * @brief Checks if the processor set small is a subset of processor set + * big. + * + * @param big The bigger processor set. + * @param small The smaller processor set. + * + * @retval true @a small is a subset of @a big. + * @retval false @a small is not a subset of @a big. + */ +static inline bool _Processor_mask_Is_subset( + const Processor_mask *big, + const Processor_mask *small +) +{ + return __BIT_SUBSET( CPU_MAXIMUM_PROCESSORS, big, small ); +} + +/** + * @brief Performs a bitwise a = b & c. + * + * @param[out] a The processor mask that is set by this operation. + * @param b The first parameter of the AND-operation. + * @param c The second parameter of the AND-operation. + */ +static inline void _Processor_mask_And( + Processor_mask *a, + const Processor_mask *b, + const Processor_mask *c +) +{ + __BIT_AND2( CPU_MAXIMUM_PROCESSORS, a, b, c ); +} + +/** + * @brief Performs a bitwise a = b | c. + * + * @param[out] a The processor mask that is set by this operation. + * @param b The first parameter of the OR-operation. + * @param c The second parameter of the OR-operation. + */ +static inline void _Processor_mask_Or( + Processor_mask *a, + const Processor_mask *b, + const Processor_mask *c +) +{ + __BIT_OR2( CPU_MAXIMUM_PROCESSORS, a, b, c ); +} + +/** + * @brief Performs a bitwise a = b ^ c. + * + * @param[out] a The processor mask that is set by this operation. + * @param b The first parameter of the XOR-operation. + * @param c The second parameter of the XOR-operation. + */ +static inline void _Processor_mask_Xor( + Processor_mask *a, + const Processor_mask *b, + const Processor_mask *c +) +{ + __BIT_XOR2( CPU_MAXIMUM_PROCESSORS, a, b, c ); +} + +/** + * @brief Gets the number of set bits in the processor mask. + * + * @param a The processor mask of which the set bits are counted. + * + * @return The number of set bits in @a a. + */ +static inline uint32_t _Processor_mask_Count( const Processor_mask *a ) +{ + return (uint32_t) __BIT_COUNT( CPU_MAXIMUM_PROCESSORS, a ); +} + +/** + * @brief Finds the last set of the processor mask. + * + * @param a The processor mask wo find the last set of. + * + * @return The last set of @a a. + */ +static inline uint32_t _Processor_mask_Find_last_set( const Processor_mask *a ) +{ + return (uint32_t) __BIT_FLS( CPU_MAXIMUM_PROCESSORS, a ); +} + +/** + * @brief Returns the subset of 32 processors containing the specified index as + * an unsigned 32-bit integer. + * + * @param mask The processor mask. + * @param index The specified index. + * + * @return The subset containing the specified index as an unsigned 32-bit integer. + */ +static inline uint32_t _Processor_mask_To_uint32_t( + const Processor_mask *mask, + uint32_t index +) +{ + long bits = mask->__bits[ index / _BITSET_BITS ]; + + return (uint32_t) ( bits >> ( 32 * ( ( index % _BITSET_BITS ) / 32 ) ) ); +} + +/** + * @brief Creates a processor set from an unsigned 32-bit integer relative to + * the specified index. + * + * @param[out] mask The mask that is created. + * @param bits The bits for creating the mask. + * @param index The index to which the mask is relative. + */ +static inline void _Processor_mask_From_uint32_t( + Processor_mask *mask, + uint32_t bits, + uint32_t index +) +{ + _Processor_mask_Zero( mask ); + mask->__bits[ __bitset_words( index ) ] = ((long) bits) << (32 * (index % _BITSET_BITS) / 32); +} + +/** + * @brief Creates a processor set from the specified index. + * + * @param[out] The mask that is created. + * @param index The specified index. + */ +static inline void _Processor_mask_From_index( + Processor_mask *mask, + uint32_t index +) +{ + __BIT_SETOF( CPU_MAXIMUM_PROCESSORS, (int) index, mask ); +} + +typedef enum { + PROCESSOR_MASK_COPY_LOSSLESS, + PROCESSOR_MASK_COPY_PARTIAL_LOSS, + PROCESSOR_MASK_COPY_COMPLETE_LOSS, + PROCESSOR_MASK_COPY_INVALID_SIZE +} Processor_mask_Copy_status; + +/** + * @brief Checks if the copy status guarantees at most partial loss. + * + * @param status The copy status to check. + * + * @retval true At most partial loss can be guaranteed. + * @retval false The status indicates more than partial loss. + */ +static inline bool _Processor_mask_Is_at_most_partial_loss( + Processor_mask_Copy_status status +) +{ + return (unsigned int) status <= PROCESSOR_MASK_COPY_PARTIAL_LOSS; +} + +/** + * @brief Copies one mask to another. + * + * @param[out] dst The destination of the copy operation. + * @param dst_size The size of @a dst. + * @param src The source of the copy operation. + * @param src_size The size of @a src. + * + * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy + * operation is lossless. + * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due + * to the sizes of @a src and @a dst. + * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due + * to the sizes of @a src and @a dst. + * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes + * is invalid (bigger than the size of a long). + */ +Processor_mask_Copy_status _Processor_mask_Copy( + long *dst, + size_t dst_size, + const long *src, + size_t src_size +); + +/** + * @brief Copies one mask to another. + * + * @param src The source for the copy operation. + * @param dst_size The size of @a dst. + * @param[out] dst The destination for the copy operation. + * + * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy + * operation is lossless. + * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due + * to the sizes of @a src and @a dst. + * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due + * to the sizes of @a src and @a dst. + * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes + * is invalid (bigger than the size of a long). + */ +static inline Processor_mask_Copy_status _Processor_mask_To_cpu_set_t( + const Processor_mask *src, + size_t dst_size, + cpu_set_t *dst +) +{ + return _Processor_mask_Copy( + &dst->__bits[ 0 ], + dst_size, + &src->__bits[ 0 ], + sizeof( *src ) + ); +} + +/** + * @brief Copies one mask to another. + * + * @param src The source for the copy operation. + * @param src_size The size of @a src. + * @param[out] dst The destination for the copy operation. + * + * @retval PROCESSOR_MASK_COPY_LOSSLESS It is guaranteed that the copy + * operation is lossless. + * @retval PROCESSOR_MASK_COPY_PARTIAL_LOSS Partial loss happened due + * to the sizes of @a src and @a dst. + * @retval PROCESSOR_MASK_COPY_COMPLETE_LOSS Complete loss happened due + * to the sizes of @a src and @a dst. + * @retval PROCESSOR_MASK_COPY_INVALID_SIZE One of the arguments sizes + * is invalid (bigger than the size of a long). + */ +static inline Processor_mask_Copy_status _Processor_mask_From_cpu_set_t( + Processor_mask *dst, + size_t src_size, + const cpu_set_t *src +) +{ + return _Processor_mask_Copy( + &dst->__bits[ 0 ], + sizeof( *dst ), + &src->__bits[ 0 ], + src_size + ); +} + +extern const Processor_mask _Processor_mask_The_one_and_only; + +/** @} */ + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* _RTEMS_SCORE_PROCESSORMASKIMPL_H */ diff --git a/cpukit/include/rtems/score/profiling.h b/cpukit/include/rtems/score/profiling.h index 90d441b0d0..af26970dcd 100644 --- a/cpukit/include/rtems/score/profiling.h +++ b/cpukit/include/rtems/score/profiling.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/protectedheap.h b/cpukit/include/rtems/score/protectedheap.h index 884d7e1c47..287108568a 100644 --- a/cpukit/include/rtems/score/protectedheap.h +++ b/cpukit/include/rtems/score/protectedheap.h @@ -163,59 +163,6 @@ static inline void *_Protected_heap_Allocate( } /** - * @brief Returns the size of the allocatable memory area. - * - * The size value may be greater than the initially requested size in - * _Heap_Allocate_aligned_with_boundary(). - * - * Inappropriate values for @a addr will not corrupt the heap, but may yield - * invalid size values. - * - * This method first locks the allocator and after the operation, unlocks it again. - * - * @param heap The heap to operate upon. - * @param addr The starting address of the allocatable memory area. - * @param[out] size Stores the size of the allocatable memory area after the method call. - * - * @retval true The operation was successful. - * @retval false The operation was not successful. - */ -bool _Protected_heap_Get_block_size( - Heap_Control *heap, - void *addr, - uintptr_t *size -); - -/** - * @brief Resizes the block of the allocated memory area. - * - * Inappropriate values for @a addr may corrupt the heap. - * - * This method first locks the allocator and after the resize, unlocks it again. - * - * @param[in, out] heap The heap to operate upon. - * @param addr The starting address of the allocated memory area to be resized. - * @param size The least possible size for the new memory area. Resize may be - * impossible and depends on the current heap usage. - * @param[out] old_size Stores the size available for allocation in the current - * block before the resize after the method call. - * @param[out] new_size Stores the size available for allocation in the resized - * block after the method call. In the case of an unsuccessful resize, - * zero is returned in this parameter - * - * @retval HEAP_RESIZE_SUCCESSFUL The resize was successful. - * @retval HEAP_RESIZE_UNSATISFIED The least possible size @a size was too big. - * Resize not possible. - * @retval HEAP_RESIZE_FATAL_ERROR The block starting at @a addr is not part of - * the heap. - */ -bool _Protected_heap_Resize_block( - Heap_Control *heap, - void *addr, - uintptr_t size -); - -/** * @brief Frees the allocated memory area. * * Inappropriate values for @a addr may corrupt the heap. This method first locks @@ -245,22 +192,6 @@ bool _Protected_heap_Free( Heap_Control *heap, void *addr ); bool _Protected_heap_Walk( Heap_Control *heap, int source, bool dump ); /** - * @brief Iterates over all blocks of the heap. - * - * This method first locks the allocator and after the operation, unlocks it again. - * - * @param[in, out] heap The heap to iterate over. - * @param visitor This will be called for each heap block with - * the argument @a visitor_arg. - * @param[in, out] visitor_arg The argument for all calls of @a visitor. - */ -void _Protected_heap_Iterate( - Heap_Control *heap, - Heap_Block_visitor visitor, - void *visitor_arg -); - -/** * @brief Returns information about used and free blocks for the heap. * * This method first locks the allocator and after the operation, unlocks it again. diff --git a/cpukit/include/rtems/score/schedulercbsimpl.h b/cpukit/include/rtems/score/schedulercbsimpl.h index 83d4eac9d8..95e19f149d 100644 --- a/cpukit/include/rtems/score/schedulercbsimpl.h +++ b/cpukit/include/rtems/score/schedulercbsimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2014 embedded brains GmbH. All rights reserved. + * Copyright (c) 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/scheduleredfsmp.h b/cpukit/include/rtems/score/scheduleredfsmp.h index ef1a116eb1..f915154241 100644 --- a/cpukit/include/rtems/score/scheduleredfsmp.h +++ b/cpukit/include/rtems/score/scheduleredfsmp.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2017, 2018 embedded brains GmbH. + * Copyright (C) 2017, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulerimpl.h b/cpukit/include/rtems/score/schedulerimpl.h index 2056408e6a..2ca3e6e8b7 100644 --- a/cpukit/include/rtems/score/schedulerimpl.h +++ b/cpukit/include/rtems/score/schedulerimpl.h @@ -12,7 +12,7 @@ /* * Copyright (C) 2010 Gedare Bloom. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). - * Copyright (c) 2014, 2017 embedded brains GmbH + * Copyright (C) 2014, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulernode.h b/cpukit/include/rtems/score/schedulernode.h index 0a2de3b6e3..65a33a1485 100644 --- a/cpukit/include/rtems/score/schedulernode.h +++ b/cpukit/include/rtems/score/schedulernode.h @@ -11,7 +11,7 @@ */ /* - * Copyright (c) 2014, 2016 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulernodeimpl.h b/cpukit/include/rtems/score/schedulernodeimpl.h index ef1813d39c..db14184723 100644 --- a/cpukit/include/rtems/score/schedulernodeimpl.h +++ b/cpukit/include/rtems/score/schedulernodeimpl.h @@ -11,7 +11,7 @@ */ /* - * Copyright (c) 2014, 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulerpriority.h b/cpukit/include/rtems/score/schedulerpriority.h index 1325224fa9..86681cd201 100644 --- a/cpukit/include/rtems/score/schedulerpriority.h +++ b/cpukit/include/rtems/score/schedulerpriority.h @@ -3,10 +3,10 @@ /** * @file * - * @ingroup RTEMSScoreSchedulerDPS + * @ingroup RTEMSScoreSchedulerPriority * * @brief This header file provides interfaces of the - * @ref RTEMSScoreSchedulerDPS which are used by the implementation and the + * @ref RTEMSScoreSchedulerPriority which are used by the implementation and the * @ref RTEMSImplApplConfig. */ @@ -48,7 +48,7 @@ extern "C" { #endif /** - * @defgroup RTEMSScoreSchedulerDPS Deterministic Priority Scheduler + * @defgroup RTEMSScoreSchedulerPriority Deterministic Priority Scheduler * * @ingroup RTEMSScoreScheduler * diff --git a/cpukit/include/rtems/score/schedulerpriorityimpl.h b/cpukit/include/rtems/score/schedulerpriorityimpl.h index eef0de59b1..5e80918b20 100644 --- a/cpukit/include/rtems/score/schedulerpriorityimpl.h +++ b/cpukit/include/rtems/score/schedulerpriorityimpl.h @@ -3,10 +3,10 @@ /** * @file * - * @ingroup RTEMSScoreSchedulerDPS + * @ingroup RTEMSScoreSchedulerPriority * * @brief This header file provides interfaces of the - * @ref RTEMSScoreSchedulerDPS which are only used by the implementation. + * @ref RTEMSScoreSchedulerPriority which are only used by the implementation. */ /* @@ -49,7 +49,7 @@ extern "C" { #endif /** - * @addtogroup RTEMSScoreSchedulerDPS + * @addtogroup RTEMSScoreSchedulerPriority * * @{ */ diff --git a/cpukit/include/rtems/score/schedulerprioritysmp.h b/cpukit/include/rtems/score/schedulerprioritysmp.h index af4ad2aaf3..476036b3bd 100644 --- a/cpukit/include/rtems/score/schedulerprioritysmp.h +++ b/cpukit/include/rtems/score/schedulerprioritysmp.h @@ -11,7 +11,7 @@ */ /* - * Copyright (c) 2013, 2018 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulerprioritysmpimpl.h b/cpukit/include/rtems/score/schedulerprioritysmpimpl.h index c6e2dbb285..12fe6b1004 100644 --- a/cpukit/include/rtems/score/schedulerprioritysmpimpl.h +++ b/cpukit/include/rtems/score/schedulerprioritysmpimpl.h @@ -11,7 +11,7 @@ */ /* - * Copyright (c) 2013, 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulersimplesmp.h b/cpukit/include/rtems/score/schedulersimplesmp.h index 5781a11b2b..4ef34847b8 100644 --- a/cpukit/include/rtems/score/schedulersimplesmp.h +++ b/cpukit/include/rtems/score/schedulersimplesmp.h @@ -12,7 +12,7 @@ /* * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2013, 2018 embedded brains GmbH. + * Copyright (C) 2013, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulersmp.h b/cpukit/include/rtems/score/schedulersmp.h index f6421504c9..3d1fe86582 100644 --- a/cpukit/include/rtems/score/schedulersmp.h +++ b/cpukit/include/rtems/score/schedulersmp.h @@ -11,7 +11,7 @@ */ /* - * Copyright (c) 2013-2014 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulersmpimpl.h b/cpukit/include/rtems/score/schedulersmpimpl.h index 93716be256..c1839c4517 100644 --- a/cpukit/include/rtems/score/schedulersmpimpl.h +++ b/cpukit/include/rtems/score/schedulersmpimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2013, 2021 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/schedulerstrongapa.h b/cpukit/include/rtems/score/schedulerstrongapa.h index 8db3ae8634..9bf0e615b6 100644 --- a/cpukit/include/rtems/score/schedulerstrongapa.h +++ b/cpukit/include/rtems/score/schedulerstrongapa.h @@ -11,7 +11,7 @@ /* * Copyright (C) 2020 Richi Dubey - * Copyright (C) 2013, 2018 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2013, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/scheduleruniimpl.h b/cpukit/include/rtems/score/scheduleruniimpl.h index 5cc4942fcc..9fe9ec394c 100644 --- a/cpukit/include/rtems/score/scheduleruniimpl.h +++ b/cpukit/include/rtems/score/scheduleruniimpl.h @@ -12,7 +12,7 @@ /* * Copyright (C) 2010 Gedare Bloom. * Copyright (C) 2011 On-Line Applications Research Corporation (OAR). - * Copyright (C) 2014, 2022 embedded brains GmbH + * Copyright (C) 2014, 2022 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/semaphoreimpl.h b/cpukit/include/rtems/score/semaphoreimpl.h index e28375521c..6c0b62adcd 100644 --- a/cpukit/include/rtems/score/semaphoreimpl.h +++ b/cpukit/include/rtems/score/semaphoreimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2015, 2017 embedded brains GmbH. All rights reserved. + * Copyright (C) 2015, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/smpbarrier.h b/cpukit/include/rtems/score/smpbarrier.h index 51dfddae56..fc14859c41 100644 --- a/cpukit/include/rtems/score/smpbarrier.h +++ b/cpukit/include/rtems/score/smpbarrier.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2013-2014 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/smpimpl.h b/cpukit/include/rtems/score/smpimpl.h index 2ffc047070..a8e3a3be15 100644 --- a/cpukit/include/rtems/score/smpimpl.h +++ b/cpukit/include/rtems/score/smpimpl.h @@ -40,7 +40,7 @@ #include <rtems/score/smp.h> #include <rtems/score/percpu.h> -#include <rtems/score/processormask.h> +#include <rtems/score/processormaskimpl.h> #include <rtems/fatal.h> #ifdef __cplusplus diff --git a/cpukit/include/rtems/score/smplock.h b/cpukit/include/rtems/score/smplock.h index ca874fef08..52324fc76c 100644 --- a/cpukit/include/rtems/score/smplock.h +++ b/cpukit/include/rtems/score/smplock.h @@ -13,7 +13,7 @@ * COPYRIGHT (c) 1989-2011. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2013, 2016 embedded brains GmbH + * Copyright (C) 2013, 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/smplockmcs.h b/cpukit/include/rtems/score/smplockmcs.h index deb6ddeb3e..89c66e9ebf 100644 --- a/cpukit/include/rtems/score/smplockmcs.h +++ b/cpukit/include/rtems/score/smplockmcs.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2016 embedded brains GmbH + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/smplockseq.h b/cpukit/include/rtems/score/smplockseq.h index d96cc6acaf..be0225b4dc 100644 --- a/cpukit/include/rtems/score/smplockseq.h +++ b/cpukit/include/rtems/score/smplockseq.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2016 embedded brains GmbH + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/smplockstats.h b/cpukit/include/rtems/score/smplockstats.h index cebfb80bd6..913d551418 100644 --- a/cpukit/include/rtems/score/smplockstats.h +++ b/cpukit/include/rtems/score/smplockstats.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2013, 2018 embedded brains GmbH + * Copyright (C) 2013, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/smplockticket.h b/cpukit/include/rtems/score/smplockticket.h index 1f6172baa8..d317ea5dd2 100644 --- a/cpukit/include/rtems/score/smplockticket.h +++ b/cpukit/include/rtems/score/smplockticket.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2013, 2016 embedded brains GmbH + * Copyright (C) 2013, 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/stack.h b/cpukit/include/rtems/score/stack.h index 9326480373..6746d6991b 100644 --- a/cpukit/include/rtems/score/stack.h +++ b/cpukit/include/rtems/score/stack.h @@ -11,7 +11,7 @@ */ /* - * Copyright (C) 2022 embedded brains GmbH + * Copyright (C) 2022 embedded brains GmbH & Co. KG * Copyright (C) 1989, 2021 On-Line Applications Research Corporation (OAR) * * Redistribution and use in source and binary forms, with or without diff --git a/cpukit/include/rtems/score/status.h b/cpukit/include/rtems/score/status.h index ac2da9b7d7..7fdf6a9017 100644 --- a/cpukit/include/rtems/score/status.h +++ b/cpukit/include/rtems/score/status.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2016 embedded brains GmbH. All rights reserved. + * Copyright (c) 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/thread.h b/cpukit/include/rtems/score/thread.h index 2b4d6823f0..8ca7d85205 100644 --- a/cpukit/include/rtems/score/thread.h +++ b/cpukit/include/rtems/score/thread.h @@ -14,7 +14,7 @@ * COPYRIGHT (c) 1989-2014. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2014, 2016 embedded brains GmbH. + * Copyright (C) 2014, 2016 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -719,50 +719,50 @@ typedef struct { * The individual state flags must be a power of two to allow use of bit * operations to manipulate and evaluate the thread life state. */ -typedef enum { - /** - * @brief Indicates that the thread life is protected. - * - * If this flag is set, then the thread restart or delete requests are deferred - * until the protection and deferred change flags are cleared. It is used by - * _Thread_Set_life_protection(). - */ - THREAD_LIFE_PROTECTED = 0x1, +typedef unsigned int Thread_Life_state; - /** - * @brief Indicates that thread is restarting. - * - * If this flag is set, then a thread restart request is in pending. See - * _Thread_Restart_self() and _Thread_Restart_other(). - */ - THREAD_LIFE_RESTARTING = 0x2, +/** + * @brief Indicates that the thread life is protected. + * + * If this flag is set, then the thread restart or delete requests are deferred + * until the protection and deferred change flags are cleared. It is used by + * _Thread_Set_life_protection(). + */ +#define THREAD_LIFE_PROTECTED 0x1U - /** - * @brief Indicates that thread is terminating. - * - * If this flag is set, then a thread termination request is in pending. See - * _Thread_Exit() and _Thread_Cancel(). - */ - THREAD_LIFE_TERMINATING = 0x4, +/** + * @brief Indicates that thread is restarting. + * + * If this flag is set, then a thread restart request is in pending. See + * _Thread_Restart_self() and _Thread_Restart_other(). + */ +#define THREAD_LIFE_RESTARTING 0x2U - /** - * @brief Indicates that thread life changes are deferred. - * - * If this flag is set, then the thread restart or delete requests are deferred - * until the protection and deferred change flags are cleared. It is used by - * pthread_setcanceltype(). - */ - THREAD_LIFE_CHANGE_DEFERRED = 0x8, +/** + * @brief Indicates that thread is terminating. + * + * If this flag is set, then a thread termination request is in pending. See + * _Thread_Exit() and _Thread_Cancel(). + */ +#define THREAD_LIFE_TERMINATING 0x4U - /** - * @brief Indicates that thread is detached. - * - * If this flag is set, then the thread is detached. Detached threads do not - * wait during termination for other threads to join. See rtems_task_delete(), - * rtems_task_exit(), and pthread_detach(). - */ - THREAD_LIFE_DETACHED = 0x10 -} Thread_Life_state; +/** + * @brief Indicates that thread life changes are deferred. + * + * If this flag is set, then the thread restart or delete requests are deferred + * until the protection and deferred change flags are cleared. It is used by + * pthread_setcanceltype(). + */ +#define THREAD_LIFE_CHANGE_DEFERRED 0x8U + +/** + * @brief Indicates that thread is detached. + * + * If this flag is set, then the thread is detached. Detached threads do not + * wait during termination for other threads to join. See rtems_task_delete(), + * rtems_task_exit(), and pthread_detach(). + */ +#define THREAD_LIFE_DETACHED 0x10U /** * @brief Thread life control. diff --git a/cpukit/include/rtems/score/threadcpubudget.h b/cpukit/include/rtems/score/threadcpubudget.h index bcbaa11bdb..e1d18ef6ed 100644 --- a/cpukit/include/rtems/score/threadcpubudget.h +++ b/cpukit/include/rtems/score/threadcpubudget.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/threaddispatch.h b/cpukit/include/rtems/score/threaddispatch.h index 589935823f..b06ebe8fec 100644 --- a/cpukit/include/rtems/score/threaddispatch.h +++ b/cpukit/include/rtems/score/threaddispatch.h @@ -222,16 +222,17 @@ static inline Per_CPU_Control *_Thread_Dispatch_disable_critical( static inline Per_CPU_Control *_Thread_Dispatch_disable( void ) { Per_CPU_Control *cpu_self; - ISR_lock_Context lock_context; #if defined( RTEMS_SMP ) || defined( RTEMS_PROFILING ) + ISR_lock_Context lock_context; + _ISR_lock_ISR_disable( &lock_context ); -#endif cpu_self = _Thread_Dispatch_disable_critical( &lock_context ); -#if defined( RTEMS_SMP ) || defined( RTEMS_PROFILING ) _ISR_lock_ISR_enable( &lock_context ); +#else + cpu_self = _Thread_Dispatch_disable_critical( NULL ); #endif return cpu_self; diff --git a/cpukit/include/rtems/score/threadidledata.h b/cpukit/include/rtems/score/threadidledata.h index 4f2a785ccd..8e458de345 100644 --- a/cpukit/include/rtems/score/threadidledata.h +++ b/cpukit/include/rtems/score/threadidledata.h @@ -11,7 +11,7 @@ /* * SPDX-License-Identifier: BSD-2-Clause * - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/threadimpl.h b/cpukit/include/rtems/score/threadimpl.h index 01c3860db8..36ddb785e9 100644 --- a/cpukit/include/rtems/score/threadimpl.h +++ b/cpukit/include/rtems/score/threadimpl.h @@ -13,7 +13,7 @@ * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * - * Copyright (c) 2014, 2017 embedded brains GmbH. + * Copyright (C) 2014, 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -1598,12 +1598,12 @@ static inline Scheduler_Node *_Thread_Scheduler_get_node_by_index( size_t scheduler_index ) { + _Assert( scheduler_index < _Scheduler_Count ); #if defined(RTEMS_SMP) return (Scheduler_Node *) ( (uintptr_t) the_thread->Scheduler.nodes + scheduler_index * _Scheduler_Node_size ); #else - _Assert( scheduler_index == 0 ); (void) scheduler_index; return the_thread->Scheduler.nodes; #endif diff --git a/cpukit/include/rtems/score/threadqops.h b/cpukit/include/rtems/score/threadqops.h index 504383e98d..d05823eefb 100644 --- a/cpukit/include/rtems/score/threadqops.h +++ b/cpukit/include/rtems/score/threadqops.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/timecounter.h b/cpukit/include/rtems/score/timecounter.h index 6559801559..ced3d7c60c 100644 --- a/cpukit/include/rtems/score/timecounter.h +++ b/cpukit/include/rtems/score/timecounter.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2015, 2021 embedded brains GmbH. All rights reserved. + * Copyright (C) 2015, 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/timecounterimpl.h b/cpukit/include/rtems/score/timecounterimpl.h index a1f79f2ee2..ee8f795bba 100644 --- a/cpukit/include/rtems/score/timecounterimpl.h +++ b/cpukit/include/rtems/score/timecounterimpl.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2015 embedded brains GmbH. All rights reserved. + * Copyright (c) 2015 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/timespec.h b/cpukit/include/rtems/score/timespec.h index 2090f19b32..2e419d69de 100644 --- a/cpukit/include/rtems/score/timespec.h +++ b/cpukit/include/rtems/score/timespec.h @@ -3,7 +3,7 @@ /** * @file * - * @ingroup Timespec + * @ingroup RTEMSScoreTimespec * * @brief This header file provides the interfaces of the * @ref RTEMSScoreTimespec. diff --git a/cpukit/include/rtems/score/tls.h b/cpukit/include/rtems/score/tls.h index abb0a748ad..8716c5230c 100644 --- a/cpukit/include/rtems/score/tls.h +++ b/cpukit/include/rtems/score/tls.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2014, 2022 embedded brains GmbH + * Copyright (C) 2014, 2023 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -59,31 +59,51 @@ extern "C" { * @{ */ -extern char _TLS_Data_begin[]; - -extern char _TLS_Data_end[]; +/** + * @brief Represents the TLS configuration. + */ +typedef struct { + /** + * @brief This member is initialized to _TLS_Data_begin. + */ + const char *data_begin; -extern char _TLS_Data_size[]; + /** + * @brief This member is initialized to _TLS_Data_size. + */ + const char *data_size; -extern char _TLS_BSS_begin[]; + /** + * @brief This member is initialized to _TLS_BSS_begin. + */ + const char *bss_begin; -extern char _TLS_BSS_end[]; + /** + * @brief This member is initialized to _TLS_BSS_size. + */ + const char *bss_size; -extern char _TLS_BSS_size[]; + /** + * @brief This member is initialized to _TLS_Size. + */ + const char *size; -extern char _TLS_Size[]; + /** + * @brief This member is initialized to _TLS_Alignment. + */ + const char *alignment; +} TLS_Configuration; /** - * @brief The TLS section alignment. + * @brief Provides the TLS configuration. * - * This symbol is provided by the linker command file as the maximum alignment - * of the .tdata and .tbss sections. The linker ensures that the first TLS - * output section is aligned to the maximum alignment of all TLS output - * sections, see function _bfd_elf_tls_setup() in bfd/elflink.c of the GNU - * Binutils sources. The linker command file must take into account the case - * that the .tdata section is empty and the .tbss section is non-empty. + * Directly using symbols with an arbitrary absolute address such as + * _TLS_Alignment may not work with all code models (for example the AArch64 + * tiny and small code models). Store the addresses in a read-only object. + * Using the volatile qualifier ensures that the compiler actually loads the + * address from the object. */ -extern char _TLS_Alignment[]; +extern const volatile TLS_Configuration _TLS_Configuration; typedef struct { /* @@ -116,38 +136,24 @@ typedef struct { } TLS_Index; /** - * @brief Gets the size of the thread-local storage data in bytes. - * - * @return Returns the size of the thread-local storage data in bytes. - */ -static inline uintptr_t _TLS_Get_size( void ) -{ - uintptr_t size; - - /* - * We must be careful with using _TLS_Size here since this could lead GCC to - * assume that this symbol is not 0 and the tests for 0 will be optimized - * away. - */ - size = (uintptr_t) _TLS_Size; - RTEMS_OBFUSCATE_VARIABLE( size ); - return size; -} - -/** * @brief Gets the size of the thread control block area in bytes. * + * @param config is the TLS configuration. + * * @return Returns the size of the thread control block area in bytes. */ -static inline uintptr_t _TLS_Get_thread_control_block_area_size( void ) +static inline uintptr_t _TLS_Get_thread_control_block_area_size( + const volatile TLS_Configuration *config +) { #if CPU_THREAD_LOCAL_STORAGE_VARIANT == 11 uintptr_t alignment; - alignment = (uintptr_t) _TLS_Alignment; + alignment = (uintptr_t) config->alignment; return RTEMS_ALIGN_UP( sizeof( TLS_Thread_control_block ), alignment ); #else + (void) config; return sizeof( TLS_Thread_control_block ); #endif } @@ -163,17 +169,23 @@ uintptr_t _TLS_Get_allocation_size( void ); /** * @brief Initializes the thread-local storage data. * + * @param config is the TLS configuration. + * * @param[out] tls_data is the thread-local storage data to initialize. */ -static inline void _TLS_Copy_and_clear( void *tls_data ) +static inline void _TLS_Copy_and_clear( + const volatile TLS_Configuration *config, + void *tls_data +) { - tls_data = memcpy( tls_data, _TLS_Data_begin, (uintptr_t) _TLS_Data_size ); + tls_data = + memcpy( tls_data, config->data_begin, (uintptr_t) config->data_size ); memset( (char *) tls_data + - (uintptr_t) _TLS_BSS_begin - (uintptr_t) _TLS_Data_begin, + (uintptr_t) config->bss_begin - (uintptr_t) config->data_begin, 0, - (uintptr_t) _TLS_BSS_size + (uintptr_t) config->bss_size ); } @@ -213,20 +225,22 @@ static inline void _TLS_Initialize_TCB_and_DTV( */ static inline void *_TLS_Initialize_area( void *tls_area ) { - uintptr_t alignment; - void *tls_data; - TLS_Thread_control_block *tcb; - TLS_Dynamic_thread_vector *dtv; - void *return_value; + const volatile TLS_Configuration *config; + uintptr_t alignment; + void *tls_data; + TLS_Thread_control_block *tcb; + TLS_Dynamic_thread_vector *dtv; + void *return_value; #if CPU_THREAD_LOCAL_STORAGE_VARIANT == 11 - uintptr_t tcb_size; + uintptr_t tcb_size; #endif #if CPU_THREAD_LOCAL_STORAGE_VARIANT == 20 - uintptr_t size; - uintptr_t alignment_2; + uintptr_t size; + uintptr_t alignment_2; #endif - alignment = (uintptr_t) _TLS_Alignment; + config = &_TLS_Configuration; + alignment = (uintptr_t) config->alignment; #ifdef __i386__ dtv = NULL; @@ -249,7 +263,7 @@ static inline void *_TLS_Initialize_area( void *tls_area ) #elif CPU_THREAD_LOCAL_STORAGE_VARIANT == 20 alignment_2 = RTEMS_ALIGN_UP( alignment, CPU_SIZEOF_POINTER ); tls_area = (void *) RTEMS_ALIGN_UP( (uintptr_t) tls_area, alignment_2 ); - size = _TLS_Get_size(); + size = (uintptr_t) config->size; tcb = (TLS_Thread_control_block *) ((char *) tls_area + RTEMS_ALIGN_UP( size, alignment_2 )); tls_data = (char *) tcb - RTEMS_ALIGN_UP( size, alignment ); @@ -259,7 +273,7 @@ static inline void *_TLS_Initialize_area( void *tls_area ) #endif _TLS_Initialize_TCB_and_DTV( tls_data, tcb, dtv ); - _TLS_Copy_and_clear( tls_data ); + _TLS_Copy_and_clear( config, tls_data ); return return_value; } diff --git a/cpukit/include/rtems/score/todimpl.h b/cpukit/include/rtems/score/todimpl.h index ce75ff681f..565e047c7f 100644 --- a/cpukit/include/rtems/score/todimpl.h +++ b/cpukit/include/rtems/score/todimpl.h @@ -382,21 +382,6 @@ static inline void _TOD_Get_timeval( } /** - * @brief Adjusts the Time of Time. - * - * This method is used to adjust the current time of day by the - * specified amount. - * - * @param delta is the amount to adjust. - * - * @retval STATUS_SUCCESSFUL Successful operation. - * @retval other Some error occurred. - */ -Status_Control _TOD_Adjust( - const struct timespec *delta -); - -/** * @brief Check if the TOD is Set * * @retval true The time is set. diff --git a/cpukit/include/rtems/score/wkspacedata.h b/cpukit/include/rtems/score/wkspacedata.h index f1ca524fa0..6d809ca788 100644 --- a/cpukit/include/rtems/score/wkspacedata.h +++ b/cpukit/include/rtems/score/wkspacedata.h @@ -11,7 +11,7 @@ */ /* - * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/wkspaceinitmulti.h b/cpukit/include/rtems/score/wkspaceinitmulti.h index 44a6b08445..dfb2b3cbde 100644 --- a/cpukit/include/rtems/score/wkspaceinitmulti.h +++ b/cpukit/include/rtems/score/wkspaceinitmulti.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2012, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2012, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/score/wkspaceinitone.h b/cpukit/include/rtems/score/wkspaceinitone.h index 47ea4efb5e..0dc252ad43 100644 --- a/cpukit/include/rtems/score/wkspaceinitone.h +++ b/cpukit/include/rtems/score/wkspaceinitone.h @@ -10,7 +10,7 @@ */ /* - * Copyright (C) 2012, 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2012, 2020 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/serdbg.h b/cpukit/include/rtems/serdbg.h deleted file mode 100644 index eef2a0182a..0000000000 --- a/cpukit/include/rtems/serdbg.h +++ /dev/null @@ -1,168 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/* - * RTEMS remote gdb over serial line - * - * This file declares intialization functions to add - * a gdb remote debug stub to an RTEMS system. - */ - -/* - * Copyright (c) 2002 IMD Ingenieurbuero fuer Microcomputertechnik - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#ifndef _SERDBG_H -#define _SERDBG_H - -#include <rtems.h> -#include <termios.h> - -#ifdef __cplusplus -extern "C" { -#endif - -typedef struct { - uint32_t baudrate; /* debug baud rate, e.g. 57600 */ - void (*callout)(void); /* callout pointer during polling */ - int (*open_io)(const char *dev_name, uint32_t baudrate); /* I/O open fnc */ - const char *devname; /* debug device, e.g. "/dev/tty01" */ - bool skip_init_bkpt; /* if TRUE, do not stop when initializing */ -} serdbg_conf_t; - -/* - * must be defined in init module... - */ -extern serdbg_conf_t serdbg_conf; - - -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -void putDebugChar -( -/*-------------------------------------------------------------------------*\ -| Purpose: | -| send character to remote debugger | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ - char c /* char to send */ - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| <none> | -\*=========================================================================*/ - -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -int getDebugChar -( -/*-------------------------------------------------------------------------*\ -| Purpose: | -| get character from remote debugger | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ - void /* <none> */ - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| <none> | -\*=========================================================================*/ - -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -void serdbg_exceptionHandler -( -/*-------------------------------------------------------------------------*\ -| Purpose: | -| hook directly to an exception vector | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ - int vecnum, /* vector index to hook at */ - void *vector /* address of handler function */ - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| <none> | -\*=========================================================================*/ - -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -int serdbg_init -( -/*-------------------------------------------------------------------------*\ -| Purpose: | -| initialize remote gdb session over serial line | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ - void - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| rtems_status_code | -\*=========================================================================*/ - -/* - * stuff from serdbgio.c - */ -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -int serdbg_open - -/*-------------------------------------------------------------------------*\ -| Purpose: | -| try to open given serial debug port | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ -( - const char *dev_name, /* name of device to open */ - uint32_t baudrate /* baud rate to use */ - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| 0 on success, -1 and errno otherwise | -\*=========================================================================*/ - - -extern int serdbg_init_dbg(void); - -/* - * Assumed to be provided by the BSP - */ -extern void set_debug_traps(void); -extern void breakpoint(void); -#ifdef __cplusplus -} -#endif - -#endif /* _SERDBG_H */ diff --git a/cpukit/include/rtems/shellconfig.h b/cpukit/include/rtems/shellconfig.h index a013840ee7..489f281400 100644 --- a/cpukit/include/rtems/shellconfig.h +++ b/cpukit/include/rtems/shellconfig.h @@ -98,6 +98,7 @@ extern rtems_shell_cmd_t rtems_shell_MD5_Command; extern rtems_shell_cmd_t rtems_shell_RTC_Command; extern rtems_shell_cmd_t rtems_shell_SPI_Command; +extern rtems_shell_cmd_t rtems_shell_FLASHDEV_Command; extern rtems_shell_cmd_t rtems_shell_I2CDETECT_Command; extern rtems_shell_cmd_t rtems_shell_I2CGET_Command; extern rtems_shell_cmd_t rtems_shell_I2CSET_Command; @@ -557,6 +558,12 @@ extern rtems_shell_alias_t * const rtems_shell_Initial_aliases[]; #endif #if (defined(CONFIGURE_SHELL_COMMANDS_ALL) \ + && !defined(CONFIGURE_SHELL_NO_COMMAND_FLASHDEV)) \ + || defined(CONFIGURE_SHELL_COMMAND_FLASHDEV) + &rtems_shell_FLASHDEV_Command, + #endif + + #if (defined(CONFIGURE_SHELL_COMMANDS_ALL) \ && !defined(CONFIGURE_SHELL_NO_COMMAND_I2CDETECT)) \ || defined(CONFIGURE_SHELL_COMMAND_I2CDETECT) &rtems_shell_I2CDETECT_Command, diff --git a/cpukit/include/rtems/sparse-disk.h b/cpukit/include/rtems/sparse-disk.h index 5b280be0a7..7bf448afbd 100644 --- a/cpukit/include/rtems/sparse-disk.h +++ b/cpukit/include/rtems/sparse-disk.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2012 embedded brains GmbH. All rights reserved. + * Copyright (c) 2012 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/status-checks.h b/cpukit/include/rtems/status-checks.h index e669bd6318..762899e845 100644 --- a/cpukit/include/rtems/status-checks.h +++ b/cpukit/include/rtems/status-checks.h @@ -10,7 +10,7 @@ */ /* - * Copyright (c) 2008 embedded brains GmbH. All rights reserved. + * Copyright (c) 2008 embedded brains GmbH & Co. KG * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: diff --git a/cpukit/include/rtems/sysinit.h b/cpukit/include/rtems/sysinit.h index ad483684e7..3e6f4d9933 100644 --- a/cpukit/include/rtems/sysinit.h +++ b/cpukit/include/rtems/sysinit.h @@ -1,7 +1,15 @@ /* SPDX-License-Identifier: BSD-2-Clause */ +/** + * @file + * + * @ingroup RTEMSAPISystemInit + * + * @brief This header file provides the API of the @ref RTEMSAPISystemInit. + */ + /* - * Copyright (c) 2015, 2020 embedded brains GmbH. All rights reserved. + * Copyright (C) 2015, 2023 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -34,6 +42,54 @@ extern "C" { #endif /* __cplusplus */ +/** + * @ingroup RTEMSImpl + * + * @brief Enables a verbose system initialization. + */ +void _Sysinit_Verbose( void ); + +/** + * @ingroup RTEMSImpl + * + * @brief Creates the system initialization item associated with the handler + * and index. + * + * The enum helps to detect typos in the module and order parameters of + * RTEMS_SYSINIT_ITEM(). + */ +#define _RTEMS_SYSINIT_INDEX_ITEM( handler, index ) \ + enum { _Sysinit_##handler = index }; \ + RTEMS_LINKER_ROSET_ITEM_ORDERED( \ + _Sysinit, \ + rtems_sysinit_item, \ + handler, \ + index \ + ) = { handler } + +/** + * @ingroup RTEMSImpl + * + * @brief Creates the system initialization item associated with the handler, + * module, and order. + * + * This helper macro is used to perform parameter expansion in + * RTEMS_SYSINIT_ITEM(). + */ +#define _RTEMS_SYSINIT_ITEM( handler, module, order ) \ + _RTEMS_SYSINIT_INDEX_ITEM( handler, 0x##module##order ) + +/** + * @defgroup RTEMSAPISystemInit System Initialization Support + * + * @ingroup RTEMSAPI + * + * @brief The system initialization support provides an ordered invocation of + * system initialization handlers registered in a linker set. + * + * @{ + */ + /* * The value of each module define must consist of exactly six hexadecimal * digits without a 0x-prefix. A 0x-prefix is concatenated with the module and @@ -133,29 +189,22 @@ typedef struct { rtems_sysinit_handler handler; } rtems_sysinit_item; -/* The enum helps to detect typos in the module and order parameters */ -#define _RTEMS_SYSINIT_INDEX_ITEM( handler, index ) \ - enum { _Sysinit_##handler = index }; \ - RTEMS_LINKER_ROSET_ITEM_ORDERED( \ - _Sysinit, \ - rtems_sysinit_item, \ - handler, \ - index \ - ) = { handler } - -/* Create index from module and order */ -#define _RTEMS_SYSINIT_ITEM( handler, module, order ) \ - _RTEMS_SYSINIT_INDEX_ITEM( handler, 0x##module##order ) - -/* Perform parameter expansion */ +/** + * @brief Creates the system initialization item associated with the handler, + * module, and order. + * + * @param handler is the system initialization handler. + * + * @param module is the system initialization module. It shall be a 6-digit + * hex number without a 0x-prefix. + * + * @param order is the system initialization order with respect to the module. + * It shall be a 2-digit hex number without a 0x-prefix. + */ #define RTEMS_SYSINIT_ITEM( handler, module, order ) \ _RTEMS_SYSINIT_ITEM( handler, module, order ) -/** - * @brief System initialization handler to enable a verbose system - * initialization. - */ -void _Sysinit_Verbose( void ); +/** @} */ #ifdef __cplusplus } diff --git a/cpukit/include/rtems/telnetd.h b/cpukit/include/rtems/telnetd.h index 86ec1f0eb5..3f20207e0c 100644 --- a/cpukit/include/rtems/telnetd.h +++ b/cpukit/include/rtems/telnetd.h @@ -7,7 +7,7 @@ /* * Copyright (c) 2001 Fernando Ruiz Casas <fruizcasas@gmail.com> * Reworked by Till Straumann and .h overhauled by Joel Sherrill. - * Copyright (c) 2009 embedded brains GmbH and others. + * Copyright (c) 2009 embedded brains GmbH & Co. KG * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at diff --git a/cpukit/include/rtems/termios_printk.h b/cpukit/include/rtems/termios_printk.h deleted file mode 100644 index 6273f1bb9d..0000000000 --- a/cpukit/include/rtems/termios_printk.h +++ /dev/null @@ -1,116 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/* - * This file declares intialization functions to add - * printk polled output via termios polled drivers. - */ - -/* - * Copyright (c) 2002 IMD Ingenieurbuero fuer Microcomputertechnik - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#ifndef _TERMIOS_PRINTK_H -#define _TERMIOS_PRINTK_H - -#include <rtems.h> -#include <termios.h> - -#ifdef __cplusplus -extern "C" { -#endif - -typedef struct { - uint32_t baudrate; /* debug baud rate, e.g. 57600 */ - void (*callout)(void); /* callout pointer during polling */ - const char *devname; /* debug device, e.g. "/dev/tty01" */ -} termios_printk_conf_t; - -/* - * must be defined in init module... - */ -extern termios_printk_conf_t termios_printk_conf; - -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -void termios_printk_outputchar -/*-------------------------------------------------------------------------*\ -| Purpose: | -| send one character to serial port | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ -( - char c /* character to print */ - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| <none> | -\*=========================================================================*/ - -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -int termios_printk_inputchar -/*-------------------------------------------------------------------------*\ -| Purpose: | -| wait for one character from serial port | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ -( - void /* none */ - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| received character | -\*=========================================================================*/ - - -/*=========================================================================*\ -| Function: | -\*-------------------------------------------------------------------------*/ -int termios_printk_open - -/*-------------------------------------------------------------------------*\ -| Purpose: | -| try to open given serial debug port | -+---------------------------------------------------------------------------+ -| Input Parameters: | -\*-------------------------------------------------------------------------*/ -( - const char *dev_name, /* name of device to open */ - uint32_t baudrate /* baud rate to use */ - ); -/*-------------------------------------------------------------------------*\ -| Return Value: | -| 0 on success, -1 and errno otherwise | -\*=========================================================================*/ - -#ifdef __cplusplus -} -#endif - -#endif /* _TERMIOS_PRINTK_H */ diff --git a/cpukit/include/rtems/termios_printk_cnf.h b/cpukit/include/rtems/termios_printk_cnf.h deleted file mode 100644 index 7a5f6cc8a5..0000000000 --- a/cpukit/include/rtems/termios_printk_cnf.h +++ /dev/null @@ -1,91 +0,0 @@ -/* SPDX-License-Identifier: BSD-2-Clause */ - -/** - * @file - * - * @brief Adds printk Support via Polled termios - */ - -/* - * Copyright (c) 2002 IMD Ingenieurbuero fuer Microcomputertechnik - * All rights reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * - * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" - * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE - * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF - * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS - * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) - * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE - * POSSIBILITY OF SUCH DAMAGE. - */ - -#ifndef _TERMIOS_PRINTK_CNF_H -#define _TERMIOS_PRINTK_CNF_H - -#include <rtems/termios_printk.h> - -#ifdef __cplusplus -extern "C" { -#endif - -#ifdef CONFIGURE_INIT - -/* - * fallback for baud rate to use - */ -#ifndef CONFIGURE_TERMIOS_PRINTK_BAUDRATE -#define CONFIGURE_TERMIOS_PRINTK_BAUDRATE 9600 -#endif - -/* - * fallback for device name to use - */ -#ifndef CONFIGURE_TERMIOS_PRINTK_DEVNAME -#define CONFIGURE_TERMIOS_PRINTK_DEVNAME "/dev/console" -#endif - -#ifdef CONFIGURE_USE_TERMIOS_PRINTK -/* - * fill in termios_printk_conf structure - */ -termios_printk_conf_t termios_printk_conf = { - CONFIGURE_TERMIOS_PRINTK_BAUDRATE, - -#ifdef CONFIGURE_TERMIOS_PRINTK_CALLOUT - CONFIGURE_TERMIOS_PRINTK_CALLOUT, -#else - NULL, -#endif - CONFIGURE_TERMIOS_PRINTK_DEVNAME, -}; -#endif - -int termios_printk_init(void) { -#ifdef CONFIGURE_USE_TERMIOS_PRINTK - return termios_printk_open(termios_printk_conf.devname, - termios_printk_conf.baudrate); -#else - return 0; -#endif -} - -#endif /* CONFIGURE_INIT */ - -#ifdef __cplusplus -} -#endif - -#endif /* _TERMIOS_PRINTK_CNF_H */ diff --git a/cpukit/include/rtems/termiosdevice.h b/cpukit/include/rtems/termiosdevice.h new file mode 100644 index 0000000000..17d05e61f6 --- /dev/null +++ b/cpukit/include/rtems/termiosdevice.h @@ -0,0 +1,300 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file + * + * @ingroup TermiostypesSupport + * + * @brief This header file provides the interfaces of the + * @ref TermiostypesSupport. + */ + +/* + * Copyright (C) 2014, 2017 embedded brains GmbH & Co. KG + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. + */ + +#ifndef _RTEMS_TERMIOSDEVICE_H +#define _RTEMS_TERMIOSDEVICE_H + +#include <rtems/thread.h> +#include <rtems/rtems/intr.h> + +#include <sys/ioccom.h> + +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +struct rtems_libio_open_close_args; +struct rtems_termios_tty; +struct termios; + +/** + * @defgroup TermiostypesSupport RTEMS Termios Device Support + * + * @ingroup libcsupport + * + * @brief This group contains the Termios Device Support provided by RTEMS. + */ + +/** + * @brief Termios device context. + * + * @see RTEMS_TERMIOS_DEVICE_CONTEXT_INITIALIZER(), + * rtems_termios_device_context_initialize() and + * rtems_termios_device_install(). + */ +typedef struct rtems_termios_device_context { + union { + /* Used for TERMIOS_POLLED and TERMIOS_IRQ_DRIVEN */ + rtems_interrupt_lock interrupt; + + /* Used for TERMIOS_IRQ_SERVER_DRIVEN and TERMIOS_TASK_DRIVEN */ + rtems_mutex mutex; + } lock; + + void ( *lock_acquire )( + struct rtems_termios_device_context *, + rtems_interrupt_lock_context * + ); + + void ( *lock_release )( + struct rtems_termios_device_context *, + rtems_interrupt_lock_context * + ); +} rtems_termios_device_context; + +typedef enum { + TERMIOS_POLLED, + TERMIOS_IRQ_DRIVEN, + TERMIOS_TASK_DRIVEN, + TERMIOS_IRQ_SERVER_DRIVEN +} rtems_termios_device_mode; + +/** + * @brief Termios device handler. + * + * @see rtems_termios_device_install(). + */ +typedef struct { + /** + * @brief First open of this device. + * + * @param[in] tty The Termios control. This parameter may be passed to + * interrupt service routines since it must be provided for the + * rtems_termios_enqueue_raw_characters() and + * rtems_termios_dequeue_characters() functions. + * @param[in] context The Termios device context. + * @param[in] term The current Termios attributes. + * @param[in] args The open/close arguments. This is parameter provided to + * support legacy drivers. It must not be used by new drivers. + * + * @retval true Successful operation. + * @retval false Cannot open device. + * + * @see rtems_termios_get_device_context() and rtems_termios_set_best_baud(). + */ + bool (*first_open)( + struct rtems_termios_tty *tty, + rtems_termios_device_context *context, + struct termios *term, + struct rtems_libio_open_close_args *args + ); + + /** + * @brief Last close of this device. + * + * @param[in] tty The Termios control. + * @param[in] context The Termios device context. + * @param[in] args The open/close arguments. This is parameter provided to + * support legacy drivers. It must not be used by new drivers. + */ + void (*last_close)( + struct rtems_termios_tty *tty, + rtems_termios_device_context *context, + struct rtems_libio_open_close_args *args + ); + + /** + * @brief Polled read. + * + * In case mode is TERMIOS_IRQ_DRIVEN, TERMIOS_IRQ_SERVER_DRIVEN or + * TERMIOS_TASK_DRIVEN, then data is received via + * rtems_termios_enqueue_raw_characters(). + * + * @param[in] context The Termios device context. + * + * @retval char The received data encoded as unsigned char. + * @retval -1 No data currently available. + */ + int (*poll_read)(rtems_termios_device_context *context); + + /** + * @brief Polled write in case mode is TERMIOS_POLLED or write support + * otherwise. + * + * @param[in] context The Termios device context. + * @param[in] buf The output buffer. + * @param[in] len The output buffer length in characters. + */ + void (*write)( + rtems_termios_device_context *context, + const char *buf, + size_t len + ); + + /** + * @brief Set attributes after a Termios settings change. + * + * @param[in] context The Termios device context. + * @param[in] term The new Termios attributes. + * + * @retval true Successful operation. + * @retval false Invalid attributes. + */ + bool (*set_attributes)( + rtems_termios_device_context *context, + const struct termios *term + ); + + /** + * @brief IO control handler. + * + * Invoked in case the Termios layer cannot deal with the IO request. + * + * @param[in] context The Termios device context. + * @param[in] request The IO control request. + * @param[in] buffer The IO control buffer. + */ + int (*ioctl)( + rtems_termios_device_context *context, + ioctl_command_t request, + void *buffer + ); + + /** + * @brief Termios device mode. + */ + rtems_termios_device_mode mode; +} rtems_termios_device_handler; + +/** + * @brief Termios device flow control handler. + * + * @see rtems_termios_device_install(). + */ +typedef struct { + /** + * @brief Indicate to stop remote transmitter. + * + * @param[in] context The Termios device context. + */ + void (*stop_remote_tx)(rtems_termios_device_context *context); + + /** + * @brief Indicate to start remote transmitter. + * + * @param[in] context The Termios device context. + */ + void (*start_remote_tx)(rtems_termios_device_context *context); +} rtems_termios_device_flow; + +void rtems_termios_device_lock_acquire_default( + rtems_termios_device_context *ctx, + rtems_interrupt_lock_context *lock_context +); + +void rtems_termios_device_lock_release_default( + rtems_termios_device_context *ctx, + rtems_interrupt_lock_context *lock_context +); + +/** + * @brief Initializes a device context. + * + * @param[in] context The Termios device context. + * @param[in] name The name for the interrupt lock. This name must be a + * string persistent throughout the life time of this lock. The name is only + * used if profiling is enabled. + */ +static inline void rtems_termios_device_context_initialize( + rtems_termios_device_context *context, + const char *name +) +{ + rtems_interrupt_lock_initialize( &context->lock.interrupt, name ); + context->lock_acquire = rtems_termios_device_lock_acquire_default; + context->lock_release = rtems_termios_device_lock_release_default; +} + +/** + * @brief Initializer for static initialization of Termios device contexts. + * + * @param name The name for the interrupt lock. It must be a string. The name + * is only used if profiling is enabled. + */ +#define RTEMS_TERMIOS_DEVICE_CONTEXT_INITIALIZER( name ) \ + { \ + { RTEMS_INTERRUPT_LOCK_INITIALIZER( name ) }, \ + rtems_termios_device_lock_acquire_default, \ + rtems_termios_device_lock_release_default \ + } + +/** + * @brief Acquires the device lock. + * + * @param[in] context The device context. + * @param[in] lock_context The local interrupt lock context for an acquire and + * release pair. + */ +static inline void rtems_termios_device_lock_acquire( + rtems_termios_device_context *context, + rtems_interrupt_lock_context *lock_context +) +{ + ( *context->lock_acquire )( context, lock_context ); +} + +/** + * @brief Releases the device lock. + * + * @param[in] context The device context. + * @param[in] lock_context The local interrupt lock context for an acquire and + * release pair. + */ +static inline void rtems_termios_device_lock_release( + rtems_termios_device_context *context, + rtems_interrupt_lock_context *lock_context +) +{ + ( *context->lock_release )( context, lock_context ); +} + +/** @} */ + +#ifdef __cplusplus +} +#endif /* __cplusplus */ + +#endif /* _RTEMS_TERMIOSDEVICE_H */ diff --git a/cpukit/include/rtems/termiostypes.h b/cpukit/include/rtems/termiostypes.h index 67f3461b1f..5cf418a5eb 100644 --- a/cpukit/include/rtems/termiostypes.h +++ b/cpukit/include/rtems/termiostypes.h @@ -39,8 +39,7 @@ #include <rtems/libio.h> #include <rtems/assoc.h> #include <rtems/chain.h> -#include <rtems/thread.h> -#include <sys/ioccom.h> +#include <rtems/termiosdevice.h> #include <stdint.h> #include <termios.h> @@ -49,11 +48,9 @@ extern "C" { #endif /** - * @defgroup TermiostypesSupport RTEMS Termios Device Support + * @addtogroup TermiostypesSupport * - * @ingroup libcsupport - * - * @brief RTEMS Termios Device Support Internal Data Structures + * @{ */ /* @@ -75,211 +72,6 @@ struct rtems_termios_rawbuf { rtems_binary_semaphore Semaphore; }; -typedef enum { - TERMIOS_POLLED, - TERMIOS_IRQ_DRIVEN, - TERMIOS_TASK_DRIVEN, - TERMIOS_IRQ_SERVER_DRIVEN -} rtems_termios_device_mode; - -struct rtems_termios_tty; - -/** - * @brief Termios device context. - * - * @see RTEMS_TERMIOS_DEVICE_CONTEXT_INITIALIZER(), - * rtems_termios_device_context_initialize() and - * rtems_termios_device_install(). - */ -typedef struct rtems_termios_device_context { - union { - /* Used for TERMIOS_POLLED and TERMIOS_IRQ_DRIVEN */ - rtems_interrupt_lock interrupt; - - /* Used for TERMIOS_IRQ_SERVER_DRIVEN or TERMIOS_TASK_DRIVEN */ - rtems_mutex mutex; - } lock; - - void ( *lock_acquire )( - struct rtems_termios_device_context *, - rtems_interrupt_lock_context * - ); - - void ( *lock_release )( - struct rtems_termios_device_context *, - rtems_interrupt_lock_context * - ); -} rtems_termios_device_context; - -void rtems_termios_device_lock_acquire_default( - rtems_termios_device_context *ctx, - rtems_interrupt_lock_context *lock_context -); - -void rtems_termios_device_lock_release_default( - rtems_termios_device_context *ctx, - rtems_interrupt_lock_context *lock_context -); - -/** - * @brief Initializes a device context. - * - * @param[in] context The Termios device context. - * @param[in] name The name for the interrupt lock. This name must be a - * string persistent throughout the life time of this lock. The name is only - * used if profiling is enabled. - */ -static inline void rtems_termios_device_context_initialize( - rtems_termios_device_context *context, - const char *name -) -{ - rtems_interrupt_lock_initialize( &context->lock.interrupt, name ); - context->lock_acquire = rtems_termios_device_lock_acquire_default; - context->lock_release = rtems_termios_device_lock_release_default; -} - -/** - * @brief Initializer for static initialization of Termios device contexts. - * - * @param name The name for the interrupt lock. It must be a string. The name - * is only used if profiling is enabled. - */ -#define RTEMS_TERMIOS_DEVICE_CONTEXT_INITIALIZER( name ) \ - { \ - { RTEMS_INTERRUPT_LOCK_INITIALIZER( name ) }, \ - rtems_termios_device_lock_acquire_default, \ - rtems_termios_device_lock_release_default \ - } - -/** - * @brief Termios device handler. - * - * @see rtems_termios_device_install(). - */ -typedef struct { - /** - * @brief First open of this device. - * - * @param[in] tty The Termios control. This parameter may be passed to - * interrupt service routines since it must be provided for the - * rtems_termios_enqueue_raw_characters() and - * rtems_termios_dequeue_characters() functions. - * @param[in] context The Termios device context. - * @param[in] term The current Termios attributes. - * @param[in] args The open/close arguments. This is parameter provided to - * support legacy drivers. It must not be used by new drivers. - * - * @retval true Successful operation. - * @retval false Cannot open device. - * - * @see rtems_termios_get_device_context() and rtems_termios_set_best_baud(). - */ - bool (*first_open)( - struct rtems_termios_tty *tty, - rtems_termios_device_context *context, - struct termios *term, - rtems_libio_open_close_args_t *args - ); - - /** - * @brief Last close of this device. - * - * @param[in] tty The Termios control. - * @param[in] context The Termios device context. - * @param[in] args The open/close arguments. This is parameter provided to - * support legacy drivers. It must not be used by new drivers. - */ - void (*last_close)( - struct rtems_termios_tty *tty, - rtems_termios_device_context *context, - rtems_libio_open_close_args_t *args - ); - - /** - * @brief Polled read. - * - * In case mode is TERMIOS_IRQ_DRIVEN, TERMIOS_IRQ_SERVER_DRIVEN or - * TERMIOS_TASK_DRIVEN, then data is received via - * rtems_termios_enqueue_raw_characters(). - * - * @param[in] context The Termios device context. - * - * @retval char The received data encoded as unsigned char. - * @retval -1 No data currently available. - */ - int (*poll_read)(rtems_termios_device_context *context); - - /** - * @brief Polled write in case mode is TERMIOS_POLLED or write support - * otherwise. - * - * @param[in] context The Termios device context. - * @param[in] buf The output buffer. - * @param[in] len The output buffer length in characters. - */ - void (*write)( - rtems_termios_device_context *context, - const char *buf, - size_t len - ); - - /** - * @brief Set attributes after a Termios settings change. - * - * @param[in] context The Termios device context. - * @param[in] term The new Termios attributes. - * - * @retval true Successful operation. - * @retval false Invalid attributes. - */ - bool (*set_attributes)( - rtems_termios_device_context *context, - const struct termios *term - ); - - /** - * @brief IO control handler. - * - * Invoked in case the Termios layer cannot deal with the IO request. - * - * @param[in] context The Termios device context. - * @param[in] request The IO control request. - * @param[in] buffer The IO control buffer. - */ - int (*ioctl)( - rtems_termios_device_context *context, - ioctl_command_t request, - void *buffer - ); - - /** - * @brief Termios device mode. - */ - rtems_termios_device_mode mode; -} rtems_termios_device_handler; - -/** - * @brief Termios device flow control handler. - * - * @see rtems_termios_device_install(). - */ -typedef struct { - /** - * @brief Indicate to stop remote transmitter. - * - * @param[in] context The Termios device context. - */ - void (*stop_remote_tx)(rtems_termios_device_context *context); - - /** - * @brief Indicate to start remote transmitter. - * - * @param[in] context The Termios device context. - */ - void (*start_remote_tx)(rtems_termios_device_context *context); -} rtems_termios_device_flow; - /** * @brief Termios device node for installed devices. * @@ -456,36 +248,6 @@ static inline void *rtems_termios_get_device_context( } /** - * @brief Acquires the device lock. - * - * @param[in] context The device context. - * @param[in] lock_context The local interrupt lock context for an acquire and - * release pair. - */ -static inline void rtems_termios_device_lock_acquire( - rtems_termios_device_context *context, - rtems_interrupt_lock_context *lock_context -) -{ - ( *context->lock_acquire )( context, lock_context ); -} - -/** - * @brief Releases the device lock. - * - * @param[in] context The device context. - * @param[in] lock_context The local interrupt lock context for an acquire and - * release pair. - */ -static inline void rtems_termios_device_lock_release( - rtems_termios_device_context *context, - rtems_interrupt_lock_context *lock_context -) -{ - ( *context->lock_release )( context, lock_context ); -} - -/** * @brief Sets the best baud value in the Termios control. * * The valid Termios baud values are between 0 and 460800. The Termios baud diff --git a/cpukit/include/rtems/score/gcov.h b/cpukit/include/rtems/test-gcov.h index b150c9f763..3664e91c64 100644 --- a/cpukit/include/rtems/score/gcov.h +++ b/cpukit/include/rtems/test-gcov.h @@ -3,14 +3,13 @@ /** * @file * - * @ingroup RTEMSScoreGcov + * @ingroup RTEMSImplGcov * - * @brief This header file provides the interfaces of the - * @ref RTEMSScoreGcov. + * @brief This header file provides the interfaces of the @ref RTEMSImplGcov. */ /* - * Copyright (c) 2013-2014 embedded brains GmbH. All rights reserved. + * Copyright (C) 2013, 2014 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -34,22 +33,22 @@ * POSSIBILITY OF SUCH DAMAGE. */ -#ifndef _RTEMS_SCORE_GCOV_H -#define _RTEMS_SCORE_GCOV_H +#ifndef _RTEMS_TEST_GCOV_H +#define _RTEMS_TEST_GCOV_H #include <gcov.h> #include <rtems/linkersets.h> -#include <rtems/score/io.h> +#include <rtems/dev/io.h> #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** - * @defgroup RTEMSScoreGcov Gcov Support + * @defgroup RTEMSImplGcov Gcov Support * - * @ingroup RTEMSScore + * @ingroup RTEMSTestFrameworkImpl * * @brief This group contains the gocv support. * @@ -84,4 +83,4 @@ void _Gcov_Dump_info_base64( IO_Put_char put_char, void *arg ); } #endif /* __cplusplus */ -#endif /* _RTEMS_SCORE_GCOV_H */ +#endif /* _RTEMS_TEST_GCOV_H */ diff --git a/cpukit/include/rtems/test-info.h b/cpukit/include/rtems/test-info.h index 3b839533c2..a5c00c423a 100644 --- a/cpukit/include/rtems/test-info.h +++ b/cpukit/include/rtems/test-info.h @@ -1,7 +1,15 @@ /* SPDX-License-Identifier: BSD-2-Clause */ +/** + * @file + * + * @ingroup RTEMSTest + * + * @brief This header file provides interfaces of the RTEMS Test Support. + */ + /* - * Copyright (c) 2014, 2018 embedded brains GmbH. All rights reserved. + * Copyright (C) 2014, 2018 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -29,7 +37,6 @@ #define _RTEMS_TEST_H #include <rtems.h> -#include <rtems/printer.h> #include <rtems/score/atomic.h> #include <rtems/score/smpbarrier.h> @@ -53,11 +60,6 @@ extern "C" { extern const char rtems_test_name[]; /** - * @brief Each test must define a printer. - */ -extern rtems_printer rtems_test_printer; - -/** * @brief Fatal extension for tests. */ void rtems_test_fatal_extension( @@ -125,13 +127,6 @@ int rtems_test_end(const char* name); */ RTEMS_NO_RETURN void rtems_test_exit(int status); -/** - * @brief Prints via the RTEMS printer. - * - * @return As specified by printf(). - */ -int rtems_test_printf(const char* format, ...) RTEMS_PRINTFLIKE(1, 2); - #define RTEMS_TEST_PARALLEL_PROCESSOR_MAX 32 typedef struct rtems_test_parallel_job rtems_test_parallel_job; diff --git a/cpukit/include/rtems/serdbgcnf.h b/cpukit/include/rtems/test-printer.h index 59d254c4bc..6625aa5a29 100644 --- a/cpukit/include/rtems/serdbgcnf.h +++ b/cpukit/include/rtems/test-printer.h @@ -3,12 +3,13 @@ /** * @file * - * @brief Adds a GDB remote Debug Stub to an RTEMS System + * @ingroup RTEMSTest + * + * @brief This header file provides interfaces of the RTEMS Test Support. */ /* - * Copyright (c) 2002 IMD Ingenieurbuero fuer Microcomputertechnik - * All rights reserved. + * Copyright (C) 2014, 2023 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -32,70 +33,37 @@ * POSSIBILITY OF SUCH DAMAGE. */ -#ifndef _SERDBGCNF_H -#define _SERDBGCNF_H +#ifndef _RTEMS_TEST_PRINTER_H +#define _RTEMS_TEST_PRINTER_H -#include <rtems/serdbg.h> +#include <rtems/printer.h> #ifdef __cplusplus extern "C" { -#endif - -#ifdef CONFIGURE_INIT +#endif /* __cplusplus */ -/* - * fallback for baud rate to use +/** + * @addtogroup RTEMSTest + * + * @{ */ -#ifndef CONFIGURE_SERDBG_BAUDRATE -#define CONFIGURE_SERDBG_BAUDRATE 9600 -#endif -/* - * fallback for device name to use +/** + * @brief Provides an RTEMS printer for tests. */ -#ifndef CONFIGURE_SERDBG_DEVNAME -#define CONFIGURE_SERDBG_DEVNAME "/dev/tty01" -#endif +extern rtems_printer rtems_test_printer; -/* - * fill in serdbg_conf structure +/** + * @brief Prints via the RTEMS test printer. + * + * @return Returns the count of output characters as specified by printf(). */ -serdbg_conf_t serdbg_conf = { - CONFIGURE_SERDBG_BAUDRATE, - -#ifdef CONFIGURE_SERDBG_CALLOUT - CONFIGURE_SERDBG_CALLOUT, -#else - NULL, -#endif - -#ifdef CONFIGURE_SERDBG_USE_POLLED_TERMIOS - serdbg_open, -#else - NULL, -#endif - - CONFIGURE_SERDBG_DEVNAME, - -#ifdef CONFIGURE_SERDBG_SKIP_INIT_BKPT - true, -#else - false, -#endif -}; - -int serdbg_init(void) { -#ifdef CONFIGURE_USE_SERDBG - return serdbg_init_dbg(); -#else - return 0; -#endif -} +int rtems_test_printf( const char *format, ... ) RTEMS_PRINTFLIKE( 1, 2 ); -#endif /* CONFIGURE_INIT */ +/** @} */ #ifdef __cplusplus } -#endif +#endif /* __cplusplus */ -#endif /* _SERDBGCNF_H */ +#endif /* _RTEMS_TEST_PRINTER_H */ diff --git a/cpukit/include/rtems/test-scheduler.h b/cpukit/include/rtems/test-scheduler.h index b9e8bf2993..39474cf250 100644 --- a/cpukit/include/rtems/test-scheduler.h +++ b/cpukit/include/rtems/test-scheduler.h @@ -9,7 +9,7 @@ */ /* - * Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/test.h b/cpukit/include/rtems/test.h index aa6b4f88b2..b8e7934883 100644 --- a/cpukit/include/rtems/test.h +++ b/cpukit/include/rtems/test.h @@ -1,7 +1,16 @@ -/* - * SPDX-License-Identifier: BSD-2-Clause +/* SPDX-License-Identifier: BSD-2-Clause */ + +/** + * @file * - * Copyright (C) 2017, 2021 embedded brains GmbH + * @ingroup RTEMSTestFramework + * + * @brief This header file provides interfaces of the + * RTEMS Test Framework. + */ + +/* + * Copyright (C) 2017, 2021 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -77,6 +86,11 @@ typedef struct T_fixture_node { unsigned int failures; } T_fixture_node; +typedef struct T_remark { + struct T_remark *next; + const char *remark; +} T_remark; + #define T_ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0])) /* @@ -98,7 +112,7 @@ typedef struct T_fixture_node { /** * @defgroup RTEMSTestFrameworkImpl RTEMS Test Framework Implementation * - * @ingroup RTEMSTestFramework + * @ingroup RTEMSImpl * * @brief Implementation details. * @@ -1322,7 +1336,7 @@ T_verbosity T_set_verbosity(T_verbosity); /** @} */ /** - * @defgroup RTEMSTestFrameworkChecksLong Signed Long Long Integer Checks + * @defgroup RTEMSTestFrameworkChecksLongLong Signed Long Long Integer Checks * * @ingroup RTEMSTestFramework * @@ -2318,6 +2332,8 @@ void *T_fixture_context(void); void T_set_fixture_context(void *); +void T_add_remark(T_remark *); + void *T_push_fixture(T_fixture_node *, const T_fixture *); void T_pop_fixture(void); @@ -2365,8 +2381,8 @@ T_case_context T_case_instance_##name = { \ NULL \ }; \ static T_case_context * const T_case_item_##name \ -__attribute((__section__(".rtemsroset._T.content.0." #name))) \ -__attribute((__used__)) = &T_case_instance_##name; \ +__attribute__((__section__(".rtemsroset._T.content.0." #name))) \ +__attribute__((__used__)) = &T_case_instance_##name; \ void T_case_body_##name(void) #else /* __rtems__ */ #define T_TEST_CASE_FIXTURE(name, fixture) \ @@ -2377,7 +2393,7 @@ T_case_context T_case_instance_##name = { \ fixture, \ NULL \ }; \ -__attribute((__constructor__)) static void \ +__attribute__((__constructor__)) static void \ T_case_register_##name(void) \ { \ T_case_register(&T_case_instance_##name); \ diff --git a/cpukit/include/rtems/tftp.h b/cpukit/include/rtems/tftp.h index d2328e3cdc..6df3866711 100644 --- a/cpukit/include/rtems/tftp.h +++ b/cpukit/include/rtems/tftp.h @@ -14,7 +14,7 @@ /* * Copyright (C) 1998 W. Eric Norum <eric@norum.ca> - * Copyright (C) 2022 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 2022 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/thread.h b/cpukit/include/rtems/thread.h index f77b572e34..c3d7de67f4 100644 --- a/cpukit/include/rtems/thread.h +++ b/cpukit/include/rtems/thread.h @@ -1,7 +1,16 @@ /* SPDX-License-Identifier: BSD-2-Clause */ +/** + * @file + * + * @ingroup RTEMSAPISelfContainedObjects + * + * @brief This header file provides the API of + * @ref RTEMSAPISelfContainedObjects. + */ + /* - * Copyright (c) 2017 embedded brains GmbH. All rights reserved. + * Copyright (c) 2017 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions @@ -45,6 +54,16 @@ void _Semaphore_Post_binary(struct _Semaphore_Control *); typedef struct _Mutex_Control rtems_mutex; +/** + * @defgroup RTEMSAPISelfContainedObjects Self-Contained Objects + * + * @ingroup RTEMSAPI + * + * @brief This group contains the self-contained objects API. + * + * @{ + */ + #define RTEMS_MUTEX_INITIALIZER( name ) _MUTEX_NAMED_INITIALIZER( name ) static __inline void rtems_mutex_init( rtems_mutex *mutex, const char *name ) @@ -309,6 +328,8 @@ static __inline void rtems_binary_semaphore_destroy( _Semaphore_Destroy( &binary_semaphore->Semaphore ); } +/** @} */ + __END_DECLS #endif /* _RTEMS_THREAD_H */ diff --git a/cpukit/include/rtems/timecounter.h b/cpukit/include/rtems/timecounter.h index 4ca17a6708..891f8d6afd 100644 --- a/cpukit/include/rtems/timecounter.h +++ b/cpukit/include/rtems/timecounter.h @@ -9,7 +9,7 @@ */ /* - * Copyright (c) 2015 embedded brains GmbH. All rights reserved. + * Copyright (c) 2015 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/rtems/userenv.h b/cpukit/include/rtems/userenv.h index 0161d6a554..cd9524110d 100644 --- a/cpukit/include/rtems/userenv.h +++ b/cpukit/include/rtems/userenv.h @@ -12,7 +12,7 @@ * On-Line Applications Research Corporation (OAR). * * Modifications to support reference counting in the file system are - * Copyright (c) 2012 embedded brains GmbH. + * Copyright (c) 2012 embedded brains GmbH & Co. KG * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions diff --git a/cpukit/include/sys/_ffcounter.h b/cpukit/include/sys/_ffcounter.h index d83c48cd44..802c7d3224 100644 --- a/cpukit/include/sys/_ffcounter.h +++ b/cpukit/include/sys/_ffcounter.h @@ -1,3 +1,12 @@ +/** + * @file + * + * @ingroup RTEMSScoreTimecounter + * + * @brief This header file provides interfaces of the feed-forward clock + * counter. + */ + /*- * Copyright (c) 2011 The University of Melbourne * All rights reserved. diff --git a/cpukit/include/sys/endian.h b/cpukit/include/sys/endian.h index 0849a6a90b..cdd6201736 100644 --- a/cpukit/include/sys/endian.h +++ b/cpukit/include/sys/endian.h @@ -1,3 +1,12 @@ +/** + * @file + * + * @ingroup RTEMSAPISystemLibrary + * + * @brief This header file provides interfaces of the system endianness + * support. + */ + /*- * Copyright (c) 2002 Thomas Moestl <tmm@FreeBSD.org> * All rights reserved. diff --git a/cpukit/include/sys/priority.h b/cpukit/include/sys/priority.h index 855edb63c2..37d0d938dc 100644 --- a/cpukit/include/sys/priority.h +++ b/cpukit/include/sys/priority.h @@ -1,3 +1,11 @@ +/** + * @file + * + * @ingroup RTEMSAPISystemLibrary + * + * @brief This header file provides interfaces of the process priority support. + */ + /*- * SPDX-License-Identifier: BSD-4-Clause * diff --git a/cpukit/include/sys/statvfs.h b/cpukit/include/sys/statvfs.h index 52d8e9d3fa..655f9a596c 100644 --- a/cpukit/include/sys/statvfs.h +++ b/cpukit/include/sys/statvfs.h @@ -3,10 +3,11 @@ /** * @file * - * @brief Interface to the statvfs() Set of API Methods + * @ingroup RTEMSAPISystemLibrary * - * This include file defines the interface to the statvfs() set of - * API methods. The statvfs as defined by the SUS: + * @brief This header file provides the statvfs() and fstatvfs() interfaces. + * + * The statvfs() is defined by the SUS: * * - http://www.opengroup.org/onlinepubs/009695399/basedefs/sys/statvfs.h.html */ diff --git a/cpukit/include/sys/timeffc.h b/cpukit/include/sys/timeffc.h index c04de97f1d..13abd37a2b 100644 --- a/cpukit/include/sys/timeffc.h +++ b/cpukit/include/sys/timeffc.h @@ -1,3 +1,12 @@ +/** + * @file + * + * @ingroup RTEMSScoreTimecounter + * + * @brief This header file provides interfaces of the feed-back and + * feed-forward clock implementations. + */ + /*- * Copyright (c) 2011 The University of Melbourne * All rights reserved. diff --git a/cpukit/include/sys/timepps.h b/cpukit/include/sys/timepps.h index 030c734477..502d93833e 100644 --- a/cpukit/include/sys/timepps.h +++ b/cpukit/include/sys/timepps.h @@ -1,3 +1,12 @@ +/** + * @file + * + * @ingroup RTEMSScoreTimecounter + * + * @brief This header file provides interfaces of the Pulse Per Second (PPS) + * support. + */ + /*- * ---------------------------------------------------------------------------- * "THE BEER-WARE LICENSE" (Revision 42): diff --git a/cpukit/include/sys/timetc.h b/cpukit/include/sys/timetc.h index 1ef58b378d..8f2537692c 100644 --- a/cpukit/include/sys/timetc.h +++ b/cpukit/include/sys/timetc.h @@ -1,3 +1,12 @@ +/** + * @file + * + * @ingroup RTEMSScoreTimecounter + * + * @brief This header file provides interfaces of the timecounter + * implementation. + */ + /*- * ---------------------------------------------------------------------------- * "THE BEER-WARE LICENSE" (Revision 42): diff --git a/cpukit/include/sys/timex.h b/cpukit/include/sys/timex.h index 8e763bb30f..36b1fcdb5a 100644 --- a/cpukit/include/sys/timex.h +++ b/cpukit/include/sys/timex.h @@ -1,3 +1,12 @@ +/** + * @file + * + * @ingroup RTEMSScoreTimecounter + * + * @brief This header file provides interfaces of the Network Time Protocol + * (NTP) support. + */ + /*- *********************************************************************** * * diff --git a/cpukit/include/zconf.h b/cpukit/include/zconf.h index a1d94ea8ee..bd10ba8e34 100644 --- a/cpukit/include/zconf.h +++ b/cpukit/include/zconf.h @@ -1,10 +1,16 @@ /* zconf.h -- configuration of the zlib compression library - * Copyright (C) 1995-2010 Jean-loup Gailly. + * Copyright (C) 1995-2016 Jean-loup Gailly, Mark Adler * For conditions of distribution and use, see copyright notice in zlib.h */ +/* @(#) $Id$ */ + #ifndef ZCONF_H #define ZCONF_H +#ifdef __rtems__ +#define ZLIB_CONST 1 +#define Z_PREFIX 1 +#endif /* __rtems__ */ /* * If you *really* need a unique prefix for all types and library functions, @@ -12,12 +18,14 @@ * Even better than compiling with -DZ_PREFIX would be to use configure to set * this permanently in zconf.h using "./configure --zprefix". */ -#if 1 /* is set to #if 1 for RTEMS */ +#ifdef Z_PREFIX /* may be set to #if 1 by ./configure */ +# define Z_PREFIX_SET -/* all linked symbols */ +/* all linked symbols and init macros */ # define _dist_code z__dist_code # define _length_code z__length_code # define _tr_align z__tr_align +# define _tr_flush_bits z__tr_flush_bits # define _tr_flush_block z__tr_flush_block # define _tr_init z__tr_init # define _tr_stored_block z__tr_stored_block @@ -25,81 +33,114 @@ # define adler32 z_adler32 # define adler32_combine z_adler32_combine # define adler32_combine64 z_adler32_combine64 -# define compress z_compress -# define compress2 z_compress2 -# define compressBound z_compressBound +# define adler32_z z_adler32_z +# ifndef Z_SOLO +# define compress z_compress +# define compress2 z_compress2 +# define compressBound z_compressBound +# endif # define crc32 z_crc32 # define crc32_combine z_crc32_combine # define crc32_combine64 z_crc32_combine64 +# define crc32_combine_gen z_crc32_combine_gen +# define crc32_combine_gen64 z_crc32_combine_gen64 +# define crc32_combine_op z_crc32_combine_op +# define crc32_z z_crc32_z # define deflate z_deflate # define deflateBound z_deflateBound # define deflateCopy z_deflateCopy # define deflateEnd z_deflateEnd +# define deflateGetDictionary z_deflateGetDictionary +# define deflateInit z_deflateInit +# define deflateInit2 z_deflateInit2 # define deflateInit2_ z_deflateInit2_ # define deflateInit_ z_deflateInit_ # define deflateParams z_deflateParams +# define deflatePending z_deflatePending # define deflatePrime z_deflatePrime # define deflateReset z_deflateReset +# define deflateResetKeep z_deflateResetKeep # define deflateSetDictionary z_deflateSetDictionary # define deflateSetHeader z_deflateSetHeader # define deflateTune z_deflateTune # define deflate_copyright z_deflate_copyright # define get_crc_table z_get_crc_table -# define gz_error z_gz_error -# define gz_intmax z_gz_intmax -# define gz_strwinerror z_gz_strwinerror -# define gzbuffer z_gzbuffer -# define gzclearerr z_gzclearerr -# define gzclose z_gzclose -# define gzclose_r z_gzclose_r -# define gzclose_w z_gzclose_w -# define gzdirect z_gzdirect -# define gzdopen z_gzdopen -# define gzeof z_gzeof -# define gzerror z_gzerror -# define gzflush z_gzflush -# define gzgetc z_gzgetc -# define gzgets z_gzgets -# define gzoffset z_gzoffset -# define gzoffset64 z_gzoffset64 -# define gzopen z_gzopen -# define gzopen64 z_gzopen64 -# define gzprintf z_gzprintf -# define gzputc z_gzputc -# define gzputs z_gzputs -# define gzread z_gzread -# define gzrewind z_gzrewind -# define gzseek z_gzseek -# define gzseek64 z_gzseek64 -# define gzsetparams z_gzsetparams -# define gztell z_gztell -# define gztell64 z_gztell64 -# define gzungetc z_gzungetc -# define gzwrite z_gzwrite +# ifndef Z_SOLO +# define gz_error z_gz_error +# define gz_intmax z_gz_intmax +# define gz_strwinerror z_gz_strwinerror +# define gzbuffer z_gzbuffer +# define gzclearerr z_gzclearerr +# define gzclose z_gzclose +# define gzclose_r z_gzclose_r +# define gzclose_w z_gzclose_w +# define gzdirect z_gzdirect +# define gzdopen z_gzdopen +# define gzeof z_gzeof +# define gzerror z_gzerror +# define gzflush z_gzflush +# define gzfread z_gzfread +# define gzfwrite z_gzfwrite +# define gzgetc z_gzgetc +# define gzgetc_ z_gzgetc_ +# define gzgets z_gzgets +# define gzoffset z_gzoffset +# define gzoffset64 z_gzoffset64 +# define gzopen z_gzopen +# define gzopen64 z_gzopen64 +# ifdef _WIN32 +# define gzopen_w z_gzopen_w +# endif +# define gzprintf z_gzprintf +# define gzputc z_gzputc +# define gzputs z_gzputs +# define gzread z_gzread +# define gzrewind z_gzrewind +# define gzseek z_gzseek +# define gzseek64 z_gzseek64 +# define gzsetparams z_gzsetparams +# define gztell z_gztell +# define gztell64 z_gztell64 +# define gzungetc z_gzungetc +# define gzvprintf z_gzvprintf +# define gzwrite z_gzwrite +# endif # define inflate z_inflate # define inflateBack z_inflateBack # define inflateBackEnd z_inflateBackEnd +# define inflateBackInit z_inflateBackInit # define inflateBackInit_ z_inflateBackInit_ +# define inflateCodesUsed z_inflateCodesUsed # define inflateCopy z_inflateCopy # define inflateEnd z_inflateEnd +# define inflateGetDictionary z_inflateGetDictionary # define inflateGetHeader z_inflateGetHeader +# define inflateInit z_inflateInit +# define inflateInit2 z_inflateInit2 # define inflateInit2_ z_inflateInit2_ # define inflateInit_ z_inflateInit_ # define inflateMark z_inflateMark # define inflatePrime z_inflatePrime # define inflateReset z_inflateReset # define inflateReset2 z_inflateReset2 +# define inflateResetKeep z_inflateResetKeep # define inflateSetDictionary z_inflateSetDictionary # define inflateSync z_inflateSync # define inflateSyncPoint z_inflateSyncPoint # define inflateUndermine z_inflateUndermine +# define inflateValidate z_inflateValidate # define inflate_copyright z_inflate_copyright # define inflate_fast z_inflate_fast # define inflate_table z_inflate_table -# define uncompress z_uncompress +# ifndef Z_SOLO +# define uncompress z_uncompress +# define uncompress2 z_uncompress2 +# endif # define zError z_zError -# define zcalloc z_zcalloc -# define zcfree z_zcfree +# ifndef Z_SOLO +# define zcalloc z_zcalloc +# define zcfree z_zcfree +# endif # define zlibCompileFlags z_zlibCompileFlags # define zlibVersion z_zlibVersion @@ -109,7 +150,9 @@ # define alloc_func z_alloc_func # define charf z_charf # define free_func z_free_func -# define gzFile z_gzFile +# ifndef Z_SOLO +# define gzFile z_gzFile +# endif # define gz_header z_gz_header # define gz_headerp z_gz_headerp # define in_func z_in_func @@ -195,9 +238,25 @@ # endif #endif -/* Some Mac compilers merge all .h files incorrectly: */ -#if defined(__MWERKS__)||defined(applec)||defined(THINK_C)||defined(__SC__) -# define NO_DUMMY_DECL +#if defined(ZLIB_CONST) && !defined(z_const) +# define z_const const +#else +# define z_const +#endif + +#ifdef Z_SOLO + typedef unsigned long z_size_t; +#else +# define z_longlong long long +# if defined(NO_SIZE_T) + typedef unsigned NO_SIZE_T z_size_t; +# elif defined(STDC) +# include <stddef.h> + typedef size_t z_size_t; +# else + typedef unsigned long z_size_t; +# endif +# undef z_longlong #endif /* Maximum value for memLevel in deflateInit2 */ @@ -227,7 +286,7 @@ Of course this will generally degrade compression (there's no free lunch). The memory requirements for inflate are (in bytes) 1 << windowBits - that is, 32K for windowBits=15 (default value) plus a few kilobytes + that is, 32K for windowBits=15 (default value) plus about 7 kilobytes for small objects. */ @@ -241,6 +300,14 @@ # endif #endif +#ifndef Z_ARG /* function prototypes for stdarg */ +# if defined(STDC) || defined(Z_HAVE_STDARG_H) +# define Z_ARG(args) args +# else +# define Z_ARG(args) () +# endif +#endif + /* The following definitions for FAR are needed only for MSDOS mixed * model programming (small or medium model with some far allocations). * This was tested only with MSC; for other MSDOS compilers you may have @@ -289,6 +356,9 @@ # ifdef FAR # undef FAR # endif +# ifndef WIN32_LEAN_AND_MEAN +# define WIN32_LEAN_AND_MEAN +# endif # include <windows.h> /* No need for _export, use ZLIB.DEF instead. */ /* For complete Windows compatibility, use WINAPI, not __stdcall. */ @@ -354,12 +424,52 @@ typedef uLong FAR uLongf; typedef Byte *voidp; #endif -#if 1 /* is set to #if 1 for RTEMS */ +#ifndef __rtems__ +#if !defined(Z_U4) && !defined(Z_SOLO) && defined(STDC) +# include <limits.h> +# if (UINT_MAX == 0xffffffffUL) +# define Z_U4 unsigned +# elif (ULONG_MAX == 0xffffffffUL) +# define Z_U4 unsigned long +# elif (USHRT_MAX == 0xffffffffUL) +# define Z_U4 unsigned short +# endif +#endif +#else /* __rtems__ */ +#include <stdint.h> +#define Z_U4 uint32_t +#endif /* __rtems__ */ + +#ifdef Z_U4 + typedef Z_U4 z_crc_t; +#else + typedef unsigned long z_crc_t; +#endif + +#ifdef __rtems__ # define Z_HAVE_UNISTD_H #endif +#ifdef __rtems__ +# define Z_HAVE_STDARG_H +#endif + #ifdef STDC -# include <sys/types.h> /* for off_t */ +# ifndef Z_SOLO +# include <sys/types.h> /* for off_t */ +# endif +#endif + +#if defined(STDC) || defined(Z_HAVE_STDARG_H) +# ifndef Z_SOLO +# include <stdarg.h> /* for va_list */ +# endif +#endif + +#ifdef _WIN32 +# ifndef Z_SOLO +# include <stddef.h> /* for wchar_t */ +# endif #endif /* a little trick to accommodate both "#define _LARGEFILE64_SOURCE" and @@ -368,21 +478,45 @@ typedef uLong FAR uLongf; * both "#undef _LARGEFILE64_SOURCE" and "#define _LARGEFILE64_SOURCE 0" as * equivalently requesting no 64-bit operations */ -#if -_LARGEFILE64_SOURCE - -1 == 1 +#if defined(_LARGEFILE64_SOURCE) && -_LARGEFILE64_SOURCE - -1 == 1 # undef _LARGEFILE64_SOURCE #endif -#if defined(Z_HAVE_UNISTD_H) || defined(_LARGEFILE64_SOURCE) -# include <unistd.h> /* for SEEK_* and off_t */ -# ifdef VMS -# include <unixio.h> /* for off_t */ +#ifndef Z_HAVE_UNISTD_H +# ifdef __WATCOMC__ +# define Z_HAVE_UNISTD_H # endif -# ifndef z_off_t -# define z_off_t off_t +#endif +#ifndef Z_HAVE_UNISTD_H +# if defined(_LARGEFILE64_SOURCE) && !defined(_WIN32) +# define Z_HAVE_UNISTD_H +# endif +#endif +#ifndef Z_SOLO +# if defined(Z_HAVE_UNISTD_H) +# include <unistd.h> /* for SEEK_*, off_t, and _LFS64_LARGEFILE */ +# ifdef VMS +# include <unixio.h> /* for off_t */ +# endif +# ifndef z_off_t +# define z_off_t off_t +# endif # endif #endif -#ifndef SEEK_SET +#if defined(_LFS64_LARGEFILE) && _LFS64_LARGEFILE-0 +# define Z_LFS64 +#endif + +#if defined(_LARGEFILE64_SOURCE) && defined(Z_LFS64) +# define Z_LARGE64 +#endif + +#if defined(_FILE_OFFSET_BITS) && _FILE_OFFSET_BITS-0 == 64 && defined(Z_LFS64) +# define Z_WANT64 +#endif + +#if !defined(SEEK_SET) && !defined(Z_SOLO) # define SEEK_SET 0 /* Seek from beginning of file. */ # define SEEK_CUR 1 /* Seek from current position. */ # define SEEK_END 2 /* Set file pointer to EOF plus "offset" */ @@ -392,18 +526,14 @@ typedef uLong FAR uLongf; # define z_off_t long #endif -#if defined(_LARGEFILE64_SOURCE) && _LFS64_LARGEFILE-0 +#if !defined(_WIN32) && defined(Z_LARGE64) # define z_off64_t off64_t #else -# define z_off64_t z_off_t -#endif - -#if defined(__OS400__) -# define NO_vsnprintf -#endif - -#if defined(__MVS__) -# define NO_vsnprintf +# if defined(_WIN32) && !defined(__GNUC__) && !defined(Z_SOLO) +# define z_off64_t __int64 +# else +# define z_off64_t z_off_t +# endif #endif /* MVS linker does not support external names larger than 8 bytes */ diff --git a/cpukit/include/zlib.h b/cpukit/include/zlib.h index bfbba83e8e..953cb5012d 100644 --- a/cpukit/include/zlib.h +++ b/cpukit/include/zlib.h @@ -1,7 +1,7 @@ /* zlib.h -- interface of the 'zlib' general purpose compression library - version 1.2.5, April 19th, 2010 + version 1.2.13, October 13th, 2022 - Copyright (C) 1995-2010 Jean-loup Gailly and Mark Adler + Copyright (C) 1995-2022 Jean-loup Gailly and Mark Adler This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages @@ -24,8 +24,8 @@ The data format used by the zlib library is described by RFCs (Request for - Comments) 1950 to 1952 in the files http://www.ietf.org/rfc/rfc1950.txt - (zlib format), rfc1951.txt (deflate format) and rfc1952.txt (gzip format). + Comments) 1950 to 1952 in the files http://tools.ietf.org/html/rfc1950 + (zlib format), rfc1951 (deflate format) and rfc1952 (gzip format). */ #ifndef ZLIB_H @@ -37,11 +37,11 @@ extern "C" { #endif -#define ZLIB_VERSION "1.2.5" -#define ZLIB_VERNUM 0x1250 +#define ZLIB_VERSION "1.2.13" +#define ZLIB_VERNUM 0x12d0 #define ZLIB_VER_MAJOR 1 #define ZLIB_VER_MINOR 2 -#define ZLIB_VER_REVISION 5 +#define ZLIB_VER_REVISION 13 #define ZLIB_VER_SUBREVISION 0 /* @@ -65,7 +65,8 @@ extern "C" { with "gz". The gzip format is different from the zlib format. gzip is a gzip wrapper, documented in RFC 1952, wrapped around a deflate stream. - This library can optionally read and write gzip streams in memory as well. + This library can optionally read and write gzip and raw deflate streams in + memory as well. The zlib format was designed to be compact and fast for use in memory and on communications channels. The gzip format was designed for single- @@ -74,7 +75,7 @@ extern "C" { The library does not install any signal handler. The decoder checks the consistency of the compressed data, so the library should never crash - even in case of corrupted input. + even in the case of corrupted input. */ typedef voidpf (*alloc_func) OF((voidpf opaque, uInt items, uInt size)); @@ -83,23 +84,24 @@ typedef void (*free_func) OF((voidpf opaque, voidpf address)); struct internal_state; typedef struct z_stream_s { - Bytef *next_in; /* next input byte */ + z_const Bytef *next_in; /* next input byte */ uInt avail_in; /* number of bytes available at next_in */ - uLong total_in; /* total nb of input bytes read so far */ + uLong total_in; /* total number of input bytes read so far */ - Bytef *next_out; /* next output byte should be put there */ + Bytef *next_out; /* next output byte will go here */ uInt avail_out; /* remaining free space at next_out */ - uLong total_out; /* total nb of bytes output so far */ + uLong total_out; /* total number of bytes output so far */ - char *msg; /* last error message, NULL if no error */ + z_const char *msg; /* last error message, NULL if no error */ struct internal_state FAR *state; /* not visible by applications */ alloc_func zalloc; /* used to allocate the internal state */ free_func zfree; /* used to free the internal state */ voidpf opaque; /* private data object passed to zalloc and zfree */ - int data_type; /* best guess about the data type: binary or text */ - uLong adler; /* adler32 value of the uncompressed data */ + int data_type; /* best guess about the data type: binary or text + for deflate, or the decoding state for inflate */ + uLong adler; /* Adler-32 or CRC-32 value of the uncompressed data */ uLong reserved; /* reserved for future use */ } z_stream; @@ -142,7 +144,9 @@ typedef gz_header FAR *gz_headerp; zalloc must return Z_NULL if there is not enough memory for the object. If zlib is used in a multi-threaded application, zalloc and zfree must be - thread safe. + thread safe. In that case, zlib is thread-safe. When zalloc and zfree are + Z_NULL on entry to the initialization function, they are set to internal + routines that use the standard library functions malloc() and free(). On 16-bit systems, the functions zalloc and zfree must be able to allocate exactly 65536 bytes, but will not be required to allocate more than this if @@ -155,7 +159,7 @@ typedef gz_header FAR *gz_headerp; The fields total_in and total_out can be used for statistics or progress reports. After compression, total_in holds the total size of the - uncompressed data and may be saved for use in the decompressor (particularly + uncompressed data and may be saved for use by the decompressor (particularly if the decompressor wants to decompress everything in a single step). */ @@ -200,7 +204,7 @@ typedef gz_header FAR *gz_headerp; #define Z_TEXT 1 #define Z_ASCII Z_TEXT /* for compatibility with 1.2.2 and earlier */ #define Z_UNKNOWN 2 -/* Possible values of the data_type field (though see inflate()) */ +/* Possible values of the data_type field for deflate() */ #define Z_DEFLATED 8 /* The deflate compression method (the only one supported in this version) */ @@ -258,11 +262,11 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); enough room in the output buffer), next_in and avail_in are updated and processing will resume at this point for the next call of deflate(). - - Provide more output starting at next_out and update next_out and avail_out + - Generate more output starting at next_out and update next_out and avail_out accordingly. This action is forced if the parameter flush is non zero. Forcing flush frequently degrades the compression ratio, so this parameter - should be set only when necessary (in interactive applications). Some - output may be provided even if flush is not set. + should be set only when necessary. Some output may be provided even if + flush is zero. Before the call of deflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more @@ -271,7 +275,9 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); output when it wants, for example when the output buffer is full (avail_out == 0), or after each call of deflate(). If deflate returns Z_OK and with zero avail_out, it must be called again after making room in the output - buffer because there might be more output pending. + buffer because there might be more output pending. See deflatePending(), + which can be used if desired to determine whether or not there is more output + in that case. Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to decide how much data to accumulate before producing output, in order to @@ -292,8 +298,8 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); input data so far will be available to the decompressor, as for Z_SYNC_FLUSH. This completes the current deflate block and follows it with an empty fixed codes block that is 10 bits long. This assures that enough bytes are output - in order for the decompressor to finish the block before the empty fixed code - block. + in order for the decompressor to finish the block before the empty fixed + codes block. If flush is set to Z_BLOCK, a deflate block is completed and emitted, as for Z_SYNC_FLUSH, but the output is not aligned on a byte boundary, and up to @@ -319,33 +325,38 @@ ZEXTERN int ZEXPORT deflate OF((z_streamp strm, int flush)); If the parameter flush is set to Z_FINISH, pending input is processed, pending output is flushed and deflate returns with Z_STREAM_END if there was - enough output space; if deflate returns with Z_OK, this function must be - called again with Z_FINISH and more output space (updated avail_out) but no - more input data, until it returns with Z_STREAM_END or an error. After - deflate has returned Z_STREAM_END, the only possible operations on the stream - are deflateReset or deflateEnd. - - Z_FINISH can be used immediately after deflateInit if all the compression - is to be done in a single step. In this case, avail_out must be at least the - value returned by deflateBound (see below). If deflate does not return - Z_STREAM_END, then it must be called again as described above. - - deflate() sets strm->adler to the adler32 checksum of all input read - so far (that is, total_in bytes). + enough output space. If deflate returns with Z_OK or Z_BUF_ERROR, this + function must be called again with Z_FINISH and more output space (updated + avail_out) but no more input data, until it returns with Z_STREAM_END or an + error. After deflate has returned Z_STREAM_END, the only possible operations + on the stream are deflateReset or deflateEnd. + + Z_FINISH can be used in the first deflate call after deflateInit if all the + compression is to be done in a single step. In order to complete in one + call, avail_out must be at least the value returned by deflateBound (see + below). Then deflate is guaranteed to return Z_STREAM_END. If not enough + output space is provided, deflate will not return Z_STREAM_END, and it must + be called again as described above. + + deflate() sets strm->adler to the Adler-32 checksum of all input read + so far (that is, total_in bytes). If a gzip stream is being generated, then + strm->adler will be the CRC-32 checksum of the input read so far. (See + deflateInit2 below.) deflate() may update strm->data_type if it can make a good guess about - the input data type (Z_BINARY or Z_TEXT). In doubt, the data is considered - binary. This field is only for information purposes and does not affect the - compression algorithm in any manner. + the input data type (Z_BINARY or Z_TEXT). If in doubt, the data is + considered binary. This field is only for information purposes and does not + affect the compression algorithm in any manner. deflate() returns Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if all input has been consumed and all output has been produced (only when flush is set to Z_FINISH), Z_STREAM_ERROR if the stream state was inconsistent (for example - if next_in or next_out was Z_NULL), Z_BUF_ERROR if no progress is possible - (for example avail_in or avail_out was zero). Note that Z_BUF_ERROR is not - fatal, and deflate() can be called again with more input and more output - space to continue compressing. + if next_in or next_out was Z_NULL or the state was inadvertently written over + by the application), or Z_BUF_ERROR if no progress is possible (for example + avail_in or avail_out was zero). Note that Z_BUF_ERROR is not fatal, and + deflate() can be called again with more input and more output space to + continue compressing. */ @@ -368,23 +379,21 @@ ZEXTERN int ZEXPORT inflateInit OF((z_streamp strm)); Initializes the internal stream state for decompression. The fields next_in, avail_in, zalloc, zfree and opaque must be initialized before by - the caller. If next_in is not Z_NULL and avail_in is large enough (the - exact value depends on the compression method), inflateInit determines the - compression method from the zlib header and allocates all data structures - accordingly; otherwise the allocation will be deferred to the first call of - inflate. If zalloc and zfree are set to Z_NULL, inflateInit updates them to - use default allocation functions. + the caller. In the current version of inflate, the provided input is not + read or consumed. The allocation of a sliding window will be deferred to + the first call of inflate (if the decompression does not complete on the + first call). If zalloc and zfree are set to Z_NULL, inflateInit updates + them to use default allocation functions. inflateInit returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_VERSION_ERROR if the zlib library version is incompatible with the version assumed by the caller, or Z_STREAM_ERROR if the parameters are invalid, such as a null pointer to the structure. msg is set to null if - there is no error message. inflateInit does not perform any decompression - apart from possibly reading the zlib header if present: actual decompression - will be done by inflate(). (So next_in and avail_in may be modified, but - next_out and avail_out are unused and unchanged.) The current implementation - of inflateInit() does not process any header information -- that is deferred - until inflate() is called. + there is no error message. inflateInit does not perform any decompression. + Actual decompression will be done by inflate(). So next_in, and avail_in, + next_out, and avail_out are unused and unchanged. The current + implementation of inflateInit() does not process any header information -- + that is deferred until inflate() is called. */ @@ -400,17 +409,20 @@ ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); - Decompress more input starting at next_in and update next_in and avail_in accordingly. If not all input can be processed (because there is not - enough room in the output buffer), next_in is updated and processing will - resume at this point for the next call of inflate(). + enough room in the output buffer), then next_in and avail_in are updated + accordingly, and processing will resume at this point for the next call of + inflate(). - - Provide more output starting at next_out and update next_out and avail_out + - Generate more output starting at next_out and update next_out and avail_out accordingly. inflate() provides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter). Before the call of inflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more - output, and updating the next_* and avail_* values accordingly. The + output, and updating the next_* and avail_* values accordingly. If the + caller of inflate() does not provide both available input and available + output space, it is possible that there will be no progress made. The application can consume the uncompressed output when it wants, for example when the output buffer is full (avail_out == 0), or after each call of inflate(). If inflate returns Z_OK and with zero avail_out, it must be @@ -427,7 +439,7 @@ ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); gets to the end of that block, or when it runs out of data. The Z_BLOCK option assists in appending to or combining deflate streams. - Also to assist in this, on return inflate() will set strm->data_type to the + To assist in this, on return inflate() always sets strm->data_type to the number of unused bits in the last byte taken from strm->next_in, plus 64 if inflate() is currently decoding the last block in the deflate stream, plus 128 if inflate() returned immediately after decoding an end-of-block code or @@ -451,48 +463,57 @@ ZEXTERN int ZEXPORT inflate OF((z_streamp strm, int flush)); error. However if all decompression is to be performed in a single step (a single call of inflate), the parameter flush should be set to Z_FINISH. In this case all pending input is processed and all pending output is flushed; - avail_out must be large enough to hold all the uncompressed data. (The size - of the uncompressed data may have been saved by the compressor for this - purpose.) The next operation on this stream must be inflateEnd to deallocate - the decompression state. The use of Z_FINISH is never required, but can be - used to inform inflate that a faster approach may be used for the single - inflate() call. + avail_out must be large enough to hold all of the uncompressed data for the + operation to complete. (The size of the uncompressed data may have been + saved by the compressor for this purpose.) The use of Z_FINISH is not + required to perform an inflation in one step. However it may be used to + inform inflate that a faster approach can be used for the single inflate() + call. Z_FINISH also informs inflate to not maintain a sliding window if the + stream completes, which reduces inflate's memory footprint. If the stream + does not complete, either because not all of the stream is provided or not + enough output space is provided, then a sliding window will be allocated and + inflate() can be called again to continue the operation as if Z_NO_FLUSH had + been used. In this implementation, inflate() always flushes as much output as possible to the output buffer, and always uses the faster approach on the - first call. So the only effect of the flush parameter in this implementation - is on the return value of inflate(), as noted below, or when it returns early - because Z_BLOCK or Z_TREES is used. + first call. So the effects of the flush parameter in this implementation are + on the return value of inflate() as noted below, when inflate() returns early + when Z_BLOCK or Z_TREES is used, and when inflate() avoids the allocation of + memory for a sliding window when Z_FINISH is used. If a preset dictionary is needed after this call (see inflateSetDictionary - below), inflate sets strm->adler to the adler32 checksum of the dictionary + below), inflate sets strm->adler to the Adler-32 checksum of the dictionary chosen by the compressor and returns Z_NEED_DICT; otherwise it sets - strm->adler to the adler32 checksum of all output produced so far (that is, + strm->adler to the Adler-32 checksum of all output produced so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described - below. At the end of the stream, inflate() checks that its computed adler32 + below. At the end of the stream, inflate() checks that its computed Adler-32 checksum is equal to that saved by the compressor and returns Z_STREAM_END only if the checksum is correct. inflate() can decompress and check either zlib-wrapped or gzip-wrapped deflate data. The header type is detected automatically, if requested when initializing with inflateInit2(). Any information contained in the gzip - header is not retained, so applications that need that information should - instead use raw inflate, see inflateInit2() below, or inflateBack() and - perform their own processing of the gzip header and trailer. + header is not retained unless inflateGetHeader() is used. When processing + gzip-wrapped deflate data, strm->adler32 is set to the CRC-32 of the output + produced so far. The CRC-32 is checked against the gzip trailer, as is the + uncompressed length, modulo 2^32. inflate() returns Z_OK if some progress has been made (more input processed or more output produced), Z_STREAM_END if the end of the compressed data has been reached and all uncompressed output has been produced, Z_NEED_DICT if a preset dictionary is needed at this point, Z_DATA_ERROR if the input data was corrupted (input stream not conforming to the zlib format or incorrect check - value), Z_STREAM_ERROR if the stream structure was inconsistent (for example - next_in or next_out was Z_NULL), Z_MEM_ERROR if there was not enough memory, - Z_BUF_ERROR if no progress is possible or if there was not enough room in the - output buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and + value, in which case strm->msg points to a string with a more specific + error), Z_STREAM_ERROR if the stream structure was inconsistent (for example + next_in or next_out was Z_NULL, or the state was inadvertently written over + by the application), Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR + if no progress was possible or if there was not enough room in the output + buffer when Z_FINISH is used. Note that Z_BUF_ERROR is not fatal, and inflate() can be called again with more input and more output space to continue decompressing. If Z_DATA_ERROR is returned, the application may then call inflateSync() to look for a good compression block if a partial - recovery of the data is desired. + recovery of the data is to be attempted. */ @@ -502,9 +523,8 @@ ZEXTERN int ZEXPORT inflateEnd OF((z_streamp strm)); This function discards any unprocessed input and does not flush any pending output. - inflateEnd returns Z_OK if success, Z_STREAM_ERROR if the stream state - was inconsistent. In the error case, msg may be set but then points to a - static string (which must not be deallocated). + inflateEnd returns Z_OK if success, or Z_STREAM_ERROR if the stream state + was inconsistent. */ @@ -523,8 +543,7 @@ ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm, int strategy)); This is another version of deflateInit with more compression options. The - fields next_in, zalloc, zfree and opaque must be initialized before by the - caller. + fields zalloc, zfree and opaque must be initialized before by the caller. The method parameter is the compression method. It must be Z_DEFLATED in this version of the library. @@ -535,16 +554,29 @@ ZEXTERN int ZEXPORT deflateInit2 OF((z_streamp strm, compression at the expense of memory usage. The default value is 15 if deflateInit is used instead. + For the current implementation of deflate(), a windowBits value of 8 (a + window size of 256 bytes) is not supported. As a result, a request for 8 + will result in 9 (a 512-byte window). In that case, providing 8 to + inflateInit2() will result in an error when the zlib header with 9 is + checked against the initialization of inflate(). The remedy is to not use 8 + with deflateInit2() with this initialization, or at least in that case use 9 + with inflateInit2(). + windowBits can also be -8..-15 for raw deflate. In this case, -windowBits determines the window size. deflate() will then generate raw deflate data - with no zlib header or trailer, and will not compute an adler32 check value. + with no zlib header or trailer, and will not compute a check value. windowBits can also be greater than 15 for optional gzip encoding. Add 16 to windowBits to write a simple gzip header and trailer around the compressed data instead of a zlib wrapper. The gzip header will have no file name, no extra data, no comment, no modification time (set to zero), no - header crc, and the operating system will be set to 255 (unknown). If a - gzip stream is being written, strm->adler is a crc32 instead of an adler32. + header crc, and the operating system will be set to the appropriate value, + if the operating system was determined at compile time. If a gzip stream is + being written, strm->adler is a CRC-32 instead of an Adler-32. + + For raw deflate or gzip encoding, a request for a 256-byte window is + rejected as invalid, since only the zlib header provides a means of + transmitting the window size to the decompressor. The memLevel parameter specifies how much memory should be allocated for the internal compression state. memLevel=1 uses minimum memory but is @@ -580,10 +612,15 @@ ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, uInt dictLength)); /* Initializes the compression dictionary from the given byte sequence - without producing any compressed output. This function must be called - immediately after deflateInit, deflateInit2 or deflateReset, before any call - of deflate. The compressor and decompressor must use exactly the same - dictionary (see inflateSetDictionary). + without producing any compressed output. When using the zlib format, this + function must be called immediately after deflateInit, deflateInit2 or + deflateReset, and before any call of deflate. When doing raw deflate, this + function must be called either before any call of deflate, or immediately + after the completion of a deflate block, i.e. after all input has been + consumed and all output has been delivered when using any of the flush + options Z_BLOCK, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH, or Z_FULL_FLUSH. The + compressor and decompressor must use exactly the same dictionary (see + inflateSetDictionary). The dictionary should consist of strings (byte sequences) that are likely to be encountered later in the data to be compressed, with the most commonly @@ -600,18 +637,40 @@ ZEXTERN int ZEXPORT deflateSetDictionary OF((z_streamp strm, addition, the current implementation of deflate will use at most the window size minus 262 bytes of the provided dictionary. - Upon return of this function, strm->adler is set to the adler32 value + Upon return of this function, strm->adler is set to the Adler-32 value of the dictionary; the decompressor may later use this value to determine - which dictionary has been used by the compressor. (The adler32 value + which dictionary has been used by the compressor. (The Adler-32 value applies to the whole dictionary even if only a subset of the dictionary is actually used by the compressor.) If a raw deflate was requested, then the - adler32 value is not computed and strm->adler is not set. + Adler-32 value is not computed and strm->adler is not set. deflateSetDictionary returns Z_OK if success, or Z_STREAM_ERROR if a parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is inconsistent (for example if deflate has already been called for this stream - or if the compression method is bsort). deflateSetDictionary does not - perform any compression: this will be done by deflate(). + or if not at a block boundary for raw deflate). deflateSetDictionary does + not perform any compression: this will be done by deflate(). +*/ + +ZEXTERN int ZEXPORT deflateGetDictionary OF((z_streamp strm, + Bytef *dictionary, + uInt *dictLength)); +/* + Returns the sliding dictionary being maintained by deflate. dictLength is + set to the number of bytes in the dictionary, and that many bytes are copied + to dictionary. dictionary must have enough space, where 32768 bytes is + always enough. If deflateGetDictionary() is called with dictionary equal to + Z_NULL, then only the dictionary length is returned, and nothing is copied. + Similarly, if dictLength is Z_NULL, then it is not set. + + deflateGetDictionary() may return a length less than the window size, even + when more than the window size in input has been provided. It may return up + to 258 bytes less in that case, due to how zlib's implementation of deflate + manages the sliding window and lookahead for matches, where matches can be + up to 258 bytes long. If the application needs the last window-size bytes of + input, then that would need to be saved by the application outside of zlib. + + deflateGetDictionary returns Z_OK on success, or Z_STREAM_ERROR if the + stream state is inconsistent. */ ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, @@ -634,10 +693,10 @@ ZEXTERN int ZEXPORT deflateCopy OF((z_streamp dest, ZEXTERN int ZEXPORT deflateReset OF((z_streamp strm)); /* - This function is equivalent to deflateEnd followed by deflateInit, - but does not free and reallocate all the internal compression state. The - stream will keep the same compression level and any other attributes that - may have been set by deflateInit2. + This function is equivalent to deflateEnd followed by deflateInit, but + does not free and reallocate the internal compression state. The stream + will leave the compression level and any other attributes that may have been + set unchanged. deflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL). @@ -648,20 +707,37 @@ ZEXTERN int ZEXPORT deflateParams OF((z_streamp strm, int strategy)); /* Dynamically update the compression level and compression strategy. The - interpretation of level and strategy is as in deflateInit2. This can be + interpretation of level and strategy is as in deflateInit2(). This can be used to switch between compression and straight copy of the input data, or to switch to a different kind of input data requiring a different strategy. - If the compression level is changed, the input available so far is - compressed with the old level (and may be flushed); the new level will take - effect only at the next call of deflate(). - - Before the call of deflateParams, the stream state must be set as for - a call of deflate(), since the currently available input may have to be - compressed and flushed. In particular, strm->avail_out must be non-zero. - - deflateParams returns Z_OK if success, Z_STREAM_ERROR if the source - stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR if - strm->avail_out was zero. + If the compression approach (which is a function of the level) or the + strategy is changed, and if there have been any deflate() calls since the + state was initialized or reset, then the input available so far is + compressed with the old level and strategy using deflate(strm, Z_BLOCK). + There are three approaches for the compression levels 0, 1..3, and 4..9 + respectively. The new level and strategy will take effect at the next call + of deflate(). + + If a deflate(strm, Z_BLOCK) is performed by deflateParams(), and it does + not have enough output space to complete, then the parameter change will not + take effect. In this case, deflateParams() can be called again with the + same parameters and more output space to try again. + + In order to assure a change in the parameters on the first try, the + deflate stream should be flushed using deflate() with Z_BLOCK or other flush + request until strm.avail_out is not zero, before calling deflateParams(). + Then no more input data should be provided before the deflateParams() call. + If this is done, the old level and strategy will be applied to the data + compressed before deflateParams(), and the new level and strategy will be + applied to the the data compressed after deflateParams(). + + deflateParams returns Z_OK on success, Z_STREAM_ERROR if the source stream + state was inconsistent or if a parameter was invalid, or Z_BUF_ERROR if + there was not enough output space to complete the compression of the + available input data before a change in the strategy or approach. Note that + in the case of a Z_BUF_ERROR, the parameters are not changed. A return + value of Z_BUF_ERROR is not fatal, in which case deflateParams() can be + retried with more output space. */ ZEXTERN int ZEXPORT deflateTune OF((z_streamp strm, @@ -688,8 +764,28 @@ ZEXTERN uLong ZEXPORT deflateBound OF((z_streamp strm, deflation of sourceLen bytes. It must be called after deflateInit() or deflateInit2(), and after deflateSetHeader(), if used. This would be used to allocate an output buffer for deflation in a single pass, and so would be - called before deflate(). -*/ + called before deflate(). If that first deflate() call is provided the + sourceLen input bytes, an output buffer allocated to the size returned by + deflateBound(), and the flush value Z_FINISH, then deflate() is guaranteed + to return Z_STREAM_END. Note that it is possible for the compressed size to + be larger than the value returned by deflateBound() if flush options other + than Z_FINISH or Z_NO_FLUSH are used. +*/ + +ZEXTERN int ZEXPORT deflatePending OF((z_streamp strm, + unsigned *pending, + int *bits)); +/* + deflatePending() returns the number of bytes and bits of output that have + been generated, but not yet provided in the available output. The bytes not + provided would be due to the available output space having being consumed. + The number of bits of output not provided are between 0 and 7, where they + await more bits to join them in order to fill out a full byte. If pending + or bits are Z_NULL, then those values are not set. + + deflatePending returns Z_OK if success, or Z_STREAM_ERROR if the source + stream state was inconsistent. + */ ZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm, int bits, @@ -703,8 +799,9 @@ ZEXTERN int ZEXPORT deflatePrime OF((z_streamp strm, than or equal to 16, and that many of the least significant bits of value will be inserted in the output. - deflatePrime returns Z_OK if success, or Z_STREAM_ERROR if the source - stream state was inconsistent. + deflatePrime returns Z_OK if success, Z_BUF_ERROR if there was not enough + room in the internal buffer to insert the bits, or Z_STREAM_ERROR if the + source stream state was inconsistent. */ ZEXTERN int ZEXPORT deflateSetHeader OF((z_streamp strm, @@ -758,7 +855,7 @@ ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, is for use with other formats that use the deflate compressed data format such as zip. Those formats provide their own check values. If a custom format is developed using the raw deflate format for compressed data, it is - recommended that a check value such as an adler32 or a crc32 be applied to + recommended that a check value such as an Adler-32 or a CRC-32 be applied to the uncompressed data as is done in the zlib, gzip, and zip formats. For most applications, the zlib format should be used as is. Note that comments above on the use in deflateInit2() applies to the magnitude of windowBits. @@ -767,7 +864,12 @@ ZEXTERN int ZEXPORT inflateInit2 OF((z_streamp strm, 32 to windowBits to enable zlib and gzip decoding with automatic header detection, or add 16 to decode only the gzip format (the zlib format will return a Z_DATA_ERROR). If a gzip stream is being decoded, strm->adler is a - crc32 instead of an adler32. + CRC-32 instead of an Adler-32. Unlike the gunzip utility and gzread() (see + below), inflate() will *not* automatically decode concatenated gzip members. + inflate() will return Z_STREAM_END at the end of the gzip member. The state + would need to be reset to continue decoding a subsequent gzip member. This + *must* be done if there is more data after a gzip member, in order for the + decompression to be compliant with the gzip standard (RFC 1952). inflateInit2 returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_VERSION_ERROR if the zlib library version is incompatible with the @@ -788,34 +890,54 @@ ZEXTERN int ZEXPORT inflateSetDictionary OF((z_streamp strm, Initializes the decompression dictionary from the given uncompressed byte sequence. This function must be called immediately after a call of inflate, if that call returned Z_NEED_DICT. The dictionary chosen by the compressor - can be determined from the adler32 value returned by that call of inflate. + can be determined from the Adler-32 value returned by that call of inflate. The compressor and decompressor must use exactly the same dictionary (see - deflateSetDictionary). For raw inflate, this function can be called - immediately after inflateInit2() or inflateReset() and before any call of - inflate() to set the dictionary. The application must insure that the - dictionary that was used for compression is provided. + deflateSetDictionary). For raw inflate, this function can be called at any + time to set the dictionary. If the provided dictionary is smaller than the + window and there is already data in the window, then the provided dictionary + will amend what's there. The application must insure that the dictionary + that was used for compression is provided. inflateSetDictionary returns Z_OK if success, Z_STREAM_ERROR if a parameter is invalid (e.g. dictionary being Z_NULL) or the stream state is inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the - expected one (incorrect adler32 value). inflateSetDictionary does not + expected one (incorrect Adler-32 value). inflateSetDictionary does not perform any decompression: this will be done by subsequent calls of inflate(). */ +ZEXTERN int ZEXPORT inflateGetDictionary OF((z_streamp strm, + Bytef *dictionary, + uInt *dictLength)); +/* + Returns the sliding dictionary being maintained by inflate. dictLength is + set to the number of bytes in the dictionary, and that many bytes are copied + to dictionary. dictionary must have enough space, where 32768 bytes is + always enough. If inflateGetDictionary() is called with dictionary equal to + Z_NULL, then only the dictionary length is returned, and nothing is copied. + Similarly, if dictLength is Z_NULL, then it is not set. + + inflateGetDictionary returns Z_OK on success, or Z_STREAM_ERROR if the + stream state is inconsistent. +*/ + ZEXTERN int ZEXPORT inflateSync OF((z_streamp strm)); /* - Skips invalid compressed data until a full flush point (see above the - description of deflate with Z_FULL_FLUSH) can be found, or until all + Skips invalid compressed data until a possible full flush point (see above + for the description of deflate with Z_FULL_FLUSH) can be found, or until all available input is skipped. No output is provided. - inflateSync returns Z_OK if a full flush point has been found, Z_BUF_ERROR - if no more input was provided, Z_DATA_ERROR if no flush point has been - found, or Z_STREAM_ERROR if the stream structure was inconsistent. In the - success case, the application may save the current current value of total_in - which indicates where valid compressed data was found. In the error case, - the application may repeatedly call inflateSync, providing more input each - time, until success or end of the input data. + inflateSync searches for a 00 00 FF FF pattern in the compressed data. + All full flush points have this pattern, but not all occurrences of this + pattern are full flush points. + + inflateSync returns Z_OK if a possible full flush point has been found, + Z_BUF_ERROR if no more input was provided, Z_DATA_ERROR if no flush point + has been found, or Z_STREAM_ERROR if the stream structure was inconsistent. + In the success case, the application may save the current current value of + total_in which indicates where valid compressed data was found. In the + error case, the application may repeatedly call inflateSync, providing more + input each time, until success or end of the input data. */ ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest, @@ -837,7 +959,7 @@ ZEXTERN int ZEXPORT inflateCopy OF((z_streamp dest, ZEXTERN int ZEXPORT inflateReset OF((z_streamp strm)); /* This function is equivalent to inflateEnd followed by inflateInit, - but does not free and reallocate all the internal decompression state. The + but does not free and reallocate the internal decompression state. The stream will keep attributes that may have been set by inflateInit2. inflateReset returns Z_OK if success, or Z_STREAM_ERROR if the source @@ -849,7 +971,9 @@ ZEXTERN int ZEXPORT inflateReset2 OF((z_streamp strm, /* This function is the same as inflateReset, but it also permits changing the wrap and window size requests. The windowBits parameter is interpreted - the same as it is for inflateInit2. + the same as it is for inflateInit2. If the window size is changed, then the + memory allocated for the window is freed, and the window will be reallocated + by inflate() if needed. inflateReset2 returns Z_OK if success, or Z_STREAM_ERROR if the source stream state was inconsistent (such as zalloc or state being Z_NULL), or if @@ -901,7 +1025,7 @@ ZEXTERN long ZEXPORT inflateMark OF((z_streamp strm)); location in the input stream can be determined from avail_in and data_type as noted in the description for the Z_BLOCK flush parameter for inflate. - inflateMark returns the value noted above or -1 << 16 if the provided + inflateMark returns the value noted above, or -65536 if the provided source stream state was inconsistent. */ @@ -962,12 +1086,13 @@ ZEXTERN int ZEXPORT inflateBackInit OF((z_streamp strm, int windowBits, See inflateBack() for the usage of these routines. inflateBackInit will return Z_OK on success, Z_STREAM_ERROR if any of - the paramaters are invalid, Z_MEM_ERROR if the internal state could not be + the parameters are invalid, Z_MEM_ERROR if the internal state could not be allocated, or Z_VERSION_ERROR if the version of the library does not match the version of the header file. */ -typedef unsigned (*in_func) OF((void FAR *, unsigned char FAR * FAR *)); +typedef unsigned (*in_func) OF((void FAR *, + z_const unsigned char FAR * FAR *)); typedef int (*out_func) OF((void FAR *, unsigned char FAR *, unsigned)); ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, @@ -975,11 +1100,12 @@ ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, out_func out, void FAR *out_desc)); /* inflateBack() does a raw inflate with a single call using a call-back - interface for input and output. This is more efficient than inflate() for - file i/o applications in that it avoids copying between the output and the - sliding window by simply making the window itself the output buffer. This - function trusts the application to not change the output buffer passed by - the output function, at least until inflateBack() returns. + interface for input and output. This is potentially more efficient than + inflate() for file i/o applications, in that it avoids copying between the + output and the sliding window by simply making the window itself the output + buffer. inflate() can be faster on modern CPUs when used with large + buffers. inflateBack() trusts the application to not change the output + buffer passed by the output function, at least until inflateBack() returns. inflateBackInit() must be called first to allocate the internal state and to initialize the state with the user-provided window buffer. @@ -991,9 +1117,9 @@ ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, This routine would normally be used in a utility that reads zip or gzip files and writes out uncompressed files. The utility would decode the header and process the trailer on its own, hence this routine expects only - the raw deflate stream to decompress. This is different from the normal - behavior of inflate(), which expects either a zlib or gzip header and - trailer around the deflate stream. + the raw deflate stream to decompress. This is different from the default + behavior of inflate(), which expects a zlib header and trailer around the + deflate stream. inflateBack() uses two subroutines supplied by the caller that are then called by inflateBack() for input and output. inflateBack() calls those @@ -1002,12 +1128,12 @@ ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, parameters and return types are defined above in the in_func and out_func typedefs. inflateBack() will call in(in_desc, &buf) which should return the number of bytes of provided input, and a pointer to that input in buf. If - there is no input available, in() must return zero--buf is ignored in that - case--and inflateBack() will return a buffer error. inflateBack() will call - out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. out() - should return zero on success, or non-zero on failure. If out() returns - non-zero, inflateBack() will return with an error. Neither in() nor out() - are permitted to change the contents of the window provided to + there is no input available, in() must return zero -- buf is ignored in that + case -- and inflateBack() will return a buffer error. inflateBack() will + call out(out_desc, buf, len) to write the uncompressed data buf[0..len-1]. + out() should return zero on success, or non-zero on failure. If out() + returns non-zero, inflateBack() will return with an error. Neither in() nor + out() are permitted to change the contents of the window provided to inflateBackInit(), which is also the buffer that out() uses to write from. The length written by out() will be at most the window size. Any non-zero amount of input may be provided by in(). @@ -1035,7 +1161,7 @@ ZEXTERN int ZEXPORT inflateBack OF((z_streamp strm, using strm->next_in which will be Z_NULL only if in() returned an error. If strm->next_in is not Z_NULL, then the Z_BUF_ERROR was due to out() returning non-zero. (in() will always be called before out(), so strm->next_in is - assured to be defined if out() returns non-zero.) Note that inflateBack() + assured to be defined if out() returns non-zero.) Note that inflateBack() cannot return Z_OK. */ @@ -1057,7 +1183,7 @@ ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void)); 7.6: size of z_off_t Compiler, assembler, and debug options: - 8: DEBUG + 8: ZLIB_DEBUG 9: ASMV or ASMINF -- use ASM code 10: ZLIB_WINAPI -- exported functions use the WINAPI calling convention 11: 0 (reserved) @@ -1088,6 +1214,7 @@ ZEXTERN uLong ZEXPORT zlibCompileFlags OF((void)); 27-31: 0 (reserved) */ +#ifndef Z_SOLO /* utility functions */ @@ -1106,7 +1233,8 @@ ZEXTERN int ZEXPORT compress OF((Bytef *dest, uLongf *destLen, the byte length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least the value returned by compressBound(sourceLen). Upon exit, destLen is the actual size of the - compressed buffer. + compressed data. compress() is equivalent to compress2() with a level + parameter of Z_DEFAULT_COMPRESSION. compress returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output @@ -1122,7 +1250,7 @@ ZEXTERN int ZEXPORT compress2 OF((Bytef *dest, uLongf *destLen, length of the source buffer. Upon entry, destLen is the total size of the destination buffer, which must be at least the value returned by compressBound(sourceLen). Upon exit, destLen is the actual size of the - compressed buffer. + compressed data. compress2 returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output buffer, @@ -1145,13 +1273,22 @@ ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, uncompressed data. (The size of the uncompressed data must have been saved previously by the compressor and transmitted to the decompressor by some mechanism outside the scope of this compression library.) Upon exit, destLen - is the actual size of the uncompressed buffer. + is the actual size of the uncompressed data. uncompress returns Z_OK if success, Z_MEM_ERROR if there was not enough memory, Z_BUF_ERROR if there was not enough room in the output - buffer, or Z_DATA_ERROR if the input data was corrupted or incomplete. + buffer, or Z_DATA_ERROR if the input data was corrupted or incomplete. In + the case where there is not enough room, uncompress() will fill the output + buffer with the uncompressed data up to that point. */ +ZEXTERN int ZEXPORT uncompress2 OF((Bytef *dest, uLongf *destLen, + const Bytef *source, uLong *sourceLen)); +/* + Same as uncompress, except that sourceLen is a pointer, where the + length of the source is *sourceLen. On return, *sourceLen is the number of + source bytes consumed. +*/ /* gzip file access functions */ @@ -1162,23 +1299,38 @@ ZEXTERN int ZEXPORT uncompress OF((Bytef *dest, uLongf *destLen, wrapper, documented in RFC 1952, wrapped around a deflate stream. */ -typedef voidp gzFile; /* opaque gzip file descriptor */ +typedef struct gzFile_s *gzFile; /* semi-opaque gzip file descriptor */ /* ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode)); - Opens a gzip (.gz) file for reading or writing. The mode parameter is as - in fopen ("rb" or "wb") but can also include a compression level ("wb9") or - a strategy: 'f' for filtered data as in "wb6f", 'h' for Huffman-only - compression as in "wb1h", 'R' for run-length encoding as in "wb1R", or 'F' - for fixed code compression as in "wb9F". (See the description of - deflateInit2 for more information about the strategy parameter.) Also "a" - can be used instead of "w" to request that the gzip stream that will be - written be appended to the file. "+" will result in an error, since reading - and writing to the same gzip file is not supported. + Open the gzip (.gz) file at path for reading and decompressing, or + compressing and writing. The mode parameter is as in fopen ("rb" or "wb") + but can also include a compression level ("wb9") or a strategy: 'f' for + filtered data as in "wb6f", 'h' for Huffman-only compression as in "wb1h", + 'R' for run-length encoding as in "wb1R", or 'F' for fixed code compression + as in "wb9F". (See the description of deflateInit2 for more information + about the strategy parameter.) 'T' will request transparent writing or + appending with no compression and not using the gzip format. + + "a" can be used instead of "w" to request that the gzip stream that will + be written be appended to the file. "+" will result in an error, since + reading and writing to the same gzip file is not supported. The addition of + "x" when writing will create the file exclusively, which fails if the file + already exists. On systems that support it, the addition of "e" when + reading or writing will set the flag to close the file on an execve() call. + + These functions, as well as gzip, will read and decode a sequence of gzip + streams in a file. The append function of gzopen() can be used to create + such a file. (Also see gzflush() for another way to do this.) When + appending, gzopen does not test whether the file begins with a gzip stream, + nor does it look for the end of the gzip streams to begin appending. gzopen + will simply append a gzip stream to the existing file. gzopen can be used to read a file which is not in gzip format; in this - case gzread will directly read from the file without decompression. + case gzread will directly read from the file without decompression. When + reading, this will be detected automatically by looking for the magic two- + byte gzip header. gzopen returns NULL if the file could not be opened, if there was insufficient memory to allocate the gzFile state, or if an invalid mode was @@ -1189,15 +1341,19 @@ ZEXTERN gzFile ZEXPORT gzopen OF((const char *path, const char *mode)); ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode)); /* - gzdopen associates a gzFile with the file descriptor fd. File descriptors - are obtained from calls like open, dup, creat, pipe or fileno (if the file - has been previously opened with fopen). The mode parameter is as in gzopen. + Associate a gzFile with the file descriptor fd. File descriptors are + obtained from calls like open, dup, creat, pipe or fileno (if the file has + been previously opened with fopen). The mode parameter is as in gzopen. The next call of gzclose on the returned gzFile will also close the file descriptor fd, just like fclose(fdopen(fd, mode)) closes the file descriptor fd. If you want to keep fd open, use fd = dup(fd_keep); gz = gzdopen(fd, mode);. The duplicated descriptor should be saved to avoid a leak, since - gzdopen does not close fd if it fails. + gzdopen does not close fd if it fails. If you are using fileno() to get the + file descriptor from a FILE *, then you will have to use dup() to avoid + double-close()ing the file descriptor. Both gzclose() and fclose() will + close the associated file descriptor, so they need to have different file + descriptors. gzdopen returns NULL if there was insufficient memory to allocate the gzFile state, if an invalid mode was specified (an 'r', 'w', or 'a' was not @@ -1208,14 +1364,13 @@ ZEXTERN gzFile ZEXPORT gzdopen OF((int fd, const char *mode)); ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size)); /* - Set the internal buffer size used by this library's functions. The - default buffer size is 8192 bytes. This function must be called after - gzopen() or gzdopen(), and before any other calls that read or write the - file. The buffer memory allocation is always deferred to the first read or - write. Two buffers are allocated, either both of the specified size when - writing, or one of the specified size and the other twice that size when - reading. A larger buffer size of, for example, 64K or 128K bytes will - noticeably increase the speed of decompression (reading). + Set the internal buffer size used by this library's functions for file to + size. The default buffer size is 8192 bytes. This function must be called + after gzopen() or gzdopen(), and before any other calls that read or write + the file. The buffer memory allocation is always deferred to the first read + or write. Three times that size in buffer space is allocated. A larger + buffer size of, for example, 64K or 128K bytes will noticeably increase the + speed of decompression (reading). The new buffer size also affects the maximum length for gzprintf(). @@ -1225,55 +1380,109 @@ ZEXTERN int ZEXPORT gzbuffer OF((gzFile file, unsigned size)); ZEXTERN int ZEXPORT gzsetparams OF((gzFile file, int level, int strategy)); /* - Dynamically update the compression level or strategy. See the description - of deflateInit2 for the meaning of these parameters. + Dynamically update the compression level and strategy for file. See the + description of deflateInit2 for the meaning of these parameters. Previously + provided data is flushed before applying the parameter changes. - gzsetparams returns Z_OK if success, or Z_STREAM_ERROR if the file was not - opened for writing. + gzsetparams returns Z_OK if success, Z_STREAM_ERROR if the file was not + opened for writing, Z_ERRNO if there is an error writing the flushed data, + or Z_MEM_ERROR if there is a memory allocation error. */ ZEXTERN int ZEXPORT gzread OF((gzFile file, voidp buf, unsigned len)); /* - Reads the given number of uncompressed bytes from the compressed file. If - the input file was not in gzip format, gzread copies the given number of - bytes into the buffer. + Read and decompress up to len uncompressed bytes from file into buf. If + the input file is not in gzip format, gzread copies the given number of + bytes into the buffer directly from the file. After reaching the end of a gzip stream in the input, gzread will continue - to read, looking for another gzip stream, or failing that, reading the rest - of the input file directly without decompression. The entire input file - will be read if gzread is called until it returns less than the requested - len. + to read, looking for another gzip stream. Any number of gzip streams may be + concatenated in the input file, and will all be decompressed by gzread(). + If something other than a gzip stream is encountered after a gzip stream, + that remaining trailing garbage is ignored (and no error is returned). + + gzread can be used to read a gzip file that is being concurrently written. + Upon reaching the end of the input, gzread will return with the available + data. If the error code returned by gzerror is Z_OK or Z_BUF_ERROR, then + gzclearerr can be used to clear the end of file indicator in order to permit + gzread to be tried again. Z_OK indicates that a gzip stream was completed + on the last gzread. Z_BUF_ERROR indicates that the input file ended in the + middle of a gzip stream. Note that gzread does not return -1 in the event + of an incomplete gzip stream. This error is deferred until gzclose(), which + will return Z_BUF_ERROR if the last gzread ended in the middle of a gzip + stream. Alternatively, gzerror can be used before gzclose to detect this + case. gzread returns the number of uncompressed bytes actually read, less than - len for end of file, or -1 for error. + len for end of file, or -1 for error. If len is too large to fit in an int, + then nothing is read, -1 is returned, and the error state is set to + Z_STREAM_ERROR. +*/ + +ZEXTERN z_size_t ZEXPORT gzfread OF((voidp buf, z_size_t size, z_size_t nitems, + gzFile file)); +/* + Read and decompress up to nitems items of size size from file into buf, + otherwise operating as gzread() does. This duplicates the interface of + stdio's fread(), with size_t request and return types. If the library + defines size_t, then z_size_t is identical to size_t. If not, then z_size_t + is an unsigned integer type that can contain a pointer. + + gzfread() returns the number of full items read of size size, or zero if + the end of the file was reached and a full item could not be read, or if + there was an error. gzerror() must be consulted if zero is returned in + order to determine if there was an error. If the multiplication of size and + nitems overflows, i.e. the product does not fit in a z_size_t, then nothing + is read, zero is returned, and the error state is set to Z_STREAM_ERROR. + + In the event that the end of file is reached and only a partial item is + available at the end, i.e. the remaining uncompressed data length is not a + multiple of size, then the final partial item is nevertheless read into buf + and the end-of-file flag is set. The length of the partial item read is not + provided, but could be inferred from the result of gztell(). This behavior + is the same as the behavior of fread() implementations in common libraries, + but it prevents the direct use of gzfread() to read a concurrently written + file, resetting and retrying on end-of-file, when size is not 1. */ -ZEXTERN int ZEXPORT gzwrite OF((gzFile file, - voidpc buf, unsigned len)); +ZEXTERN int ZEXPORT gzwrite OF((gzFile file, voidpc buf, unsigned len)); /* - Writes the given number of uncompressed bytes into the compressed file. - gzwrite returns the number of uncompressed bytes written or 0 in case of - error. + Compress and write the len uncompressed bytes at buf to file. gzwrite + returns the number of uncompressed bytes written or 0 in case of error. */ -ZEXTERN int ZEXPORTVA gzprintf OF((gzFile file, const char *format, ...)); +ZEXTERN z_size_t ZEXPORT gzfwrite OF((voidpc buf, z_size_t size, + z_size_t nitems, gzFile file)); /* - Converts, formats, and writes the arguments to the compressed file under - control of the format string, as in fprintf. gzprintf returns the number of - uncompressed bytes actually written, or 0 in case of error. The number of - uncompressed bytes written is limited to 8191, or one less than the buffer - size given to gzbuffer(). The caller should assure that this limit is not - exceeded. If it is exceeded, then gzprintf() will return an error (0) with - nothing written. In this case, there may also be a buffer overflow with - unpredictable consequences, which is possible only if zlib was compiled with - the insecure functions sprintf() or vsprintf() because the secure snprintf() - or vsnprintf() functions were not available. This can be determined using - zlibCompileFlags(). + Compress and write nitems items of size size from buf to file, duplicating + the interface of stdio's fwrite(), with size_t request and return types. If + the library defines size_t, then z_size_t is identical to size_t. If not, + then z_size_t is an unsigned integer type that can contain a pointer. + + gzfwrite() returns the number of full items written of size size, or zero + if there was an error. If the multiplication of size and nitems overflows, + i.e. the product does not fit in a z_size_t, then nothing is written, zero + is returned, and the error state is set to Z_STREAM_ERROR. +*/ + +ZEXTERN int ZEXPORTVA gzprintf Z_ARG((gzFile file, const char *format, ...)); +/* + Convert, format, compress, and write the arguments (...) to file under + control of the string format, as in fprintf. gzprintf returns the number of + uncompressed bytes actually written, or a negative zlib error code in case + of error. The number of uncompressed bytes written is limited to 8191, or + one less than the buffer size given to gzbuffer(). The caller should assure + that this limit is not exceeded. If it is exceeded, then gzprintf() will + return an error (0) with nothing written. In this case, there may also be a + buffer overflow with unpredictable consequences, which is possible only if + zlib was compiled with the insecure functions sprintf() or vsprintf(), + because the secure snprintf() or vsnprintf() functions were not available. + This can be determined using zlibCompileFlags(). */ ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); /* - Writes the given null-terminated string to the compressed file, excluding + Compress and write the given null-terminated string s to file, excluding the terminating null character. gzputs returns the number of characters written, or -1 in case of error. @@ -1281,11 +1490,12 @@ ZEXTERN int ZEXPORT gzputs OF((gzFile file, const char *s)); ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len)); /* - Reads bytes from the compressed file until len-1 characters are read, or a - newline character is read and transferred to buf, or an end-of-file - condition is encountered. If any characters are read or if len == 1, the - string is terminated with a null character. If no characters are read due - to an end-of-file or len < 1, then the buffer is left untouched. + Read and decompress bytes from file into buf, until len-1 characters are + read, or until a newline character is read and transferred to buf, or an + end-of-file condition is encountered. If any characters are read or if len + is one, the string is terminated with a null character. If no characters + are read due to an end-of-file or len is less than one, then the buffer is + left untouched. gzgets returns buf which is a null-terminated string, or it returns NULL for end-of-file or in case of error. If there was an error, the contents at @@ -1294,20 +1504,23 @@ ZEXTERN char * ZEXPORT gzgets OF((gzFile file, char *buf, int len)); ZEXTERN int ZEXPORT gzputc OF((gzFile file, int c)); /* - Writes c, converted to an unsigned char, into the compressed file. gzputc + Compress and write c, converted to an unsigned char, into file. gzputc returns the value that was written, or -1 in case of error. */ ZEXTERN int ZEXPORT gzgetc OF((gzFile file)); /* - Reads one byte from the compressed file. gzgetc returns this byte or -1 - in case of end of file or error. + Read and decompress one byte from file. gzgetc returns this byte or -1 + in case of end of file or error. This is implemented as a macro for speed. + As such, it does not do all of the checking the other functions do. I.e. + it does not check to see if file is NULL, nor whether the structure file + points to has been clobbered or not. */ ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file)); /* - Push one character back onto the stream to be read as the first character - on the next read. At least one character of push-back is allowed. + Push c back onto the stream for file to be read as the first character on + the next read. At least one character of push-back is always allowed. gzungetc() returns the character pushed, or -1 on failure. gzungetc() will fail if c is -1, and may fail if a character has been pushed but not read yet. If gzungetc is used immediately after gzopen or gzdopen, at least the @@ -1318,14 +1531,14 @@ ZEXTERN int ZEXPORT gzungetc OF((int c, gzFile file)); ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); /* - Flushes all pending output into the compressed file. The parameter flush - is as in the deflate() function. The return value is the zlib error number - (see function gzerror below). gzflush is only permitted when writing. + Flush all pending output to file. The parameter flush is as in the + deflate() function. The return value is the zlib error number (see function + gzerror below). gzflush is only permitted when writing. If the flush parameter is Z_FINISH, the remaining data is written and the gzip stream is completed in the output. If gzwrite() is called again, a new gzip stream will be started in the output. gzread() is able to read such - concatented gzip streams. + concatenated gzip streams. gzflush should be called only when strictly necessary because it will degrade compression if called too often. @@ -1335,8 +1548,8 @@ ZEXTERN int ZEXPORT gzflush OF((gzFile file, int flush)); ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file, z_off_t offset, int whence)); - Sets the starting position for the next gzread or gzwrite on the given - compressed file. The offset represents a number of bytes in the + Set the starting position to offset relative to whence for the next gzread + or gzwrite on file. The offset represents a number of bytes in the uncompressed data stream. The whence parameter is defined as in lseek(2); the value SEEK_END is not supported. @@ -1353,18 +1566,18 @@ ZEXTERN z_off_t ZEXPORT gzseek OF((gzFile file, ZEXTERN int ZEXPORT gzrewind OF((gzFile file)); /* - Rewinds the given file. This function is supported only for reading. + Rewind file. This function is supported only for reading. - gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET) + gzrewind(file) is equivalent to (int)gzseek(file, 0L, SEEK_SET). */ /* ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file)); - Returns the starting position for the next gzread or gzwrite on the given - compressed file. This position represents a number of bytes in the - uncompressed data stream, and is zero when starting, even if appending or - reading a gzip stream from the middle of a file using gzdopen(). + Return the starting position for the next gzread or gzwrite on file. + This position represents a number of bytes in the uncompressed data stream, + and is zero when starting, even if appending or reading a gzip stream from + the middle of a file using gzdopen(). gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) */ @@ -1372,22 +1585,22 @@ ZEXTERN z_off_t ZEXPORT gztell OF((gzFile file)); /* ZEXTERN z_off_t ZEXPORT gzoffset OF((gzFile file)); - Returns the current offset in the file being read or written. This offset - includes the count of bytes that precede the gzip stream, for example when - appending or when using gzdopen() for reading. When reading, the offset - does not include as yet unused buffered input. This information can be used - for a progress indicator. On error, gzoffset() returns -1. + Return the current compressed (actual) read or write offset of file. This + offset includes the count of bytes that precede the gzip stream, for example + when appending or when using gzdopen() for reading. When reading, the + offset does not include as yet unused buffered input. This information can + be used for a progress indicator. On error, gzoffset() returns -1. */ ZEXTERN int ZEXPORT gzeof OF((gzFile file)); /* - Returns true (1) if the end-of-file indicator has been set while reading, - false (0) otherwise. Note that the end-of-file indicator is set only if the - read tried to go past the end of the input, but came up short. Therefore, - just like feof(), gzeof() may return false even if there is no more data to - read, in the event that the last read request was for the exact number of - bytes remaining in the input file. This will happen if the input file size - is an exact multiple of the buffer size. + Return true (1) if the end-of-file indicator for file has been set while + reading, false (0) otherwise. Note that the end-of-file indicator is set + only if the read tried to go past the end of the input, but came up short. + Therefore, just like feof(), gzeof() may return false even if there is no + more data to read, in the event that the last read request was for the exact + number of bytes remaining in the input file. This will happen if the input + file size is an exact multiple of the buffer size. If gzeof() returns true, then the read functions will return no more data, unless the end-of-file indicator is reset by gzclearerr() and the input file @@ -1396,10 +1609,8 @@ ZEXTERN int ZEXPORT gzeof OF((gzFile file)); ZEXTERN int ZEXPORT gzdirect OF((gzFile file)); /* - Returns true (1) if file is being copied directly while reading, or false - (0) if file is a gzip stream being decompressed. This state can change from - false to true while reading the input file if the end of a gzip stream is - reached, but is followed by data that is not another gzip stream. + Return true (1) if file is being copied directly while reading, or false + (0) if file is a gzip stream being decompressed. If the input file is empty, gzdirect() will return true, since the input does not contain a gzip stream. @@ -1408,18 +1619,26 @@ ZEXTERN int ZEXPORT gzdirect OF((gzFile file)); cause buffers to be allocated to allow reading the file to determine if it is a gzip file. Therefore if gzbuffer() is used, it should be called before gzdirect(). + + When writing, gzdirect() returns true (1) if transparent writing was + requested ("wT" for the gzopen() mode), or false (0) otherwise. (Note: + gzdirect() is not needed when writing. Transparent writing must be + explicitly requested, so the application already knows the answer. When + linking statically, using gzdirect() will include all of the zlib code for + gzip file reading and decompression, which may not be desired.) */ ZEXTERN int ZEXPORT gzclose OF((gzFile file)); /* - Flushes all pending output if necessary, closes the compressed file and - deallocates the (de)compression state. Note that once file is closed, you + Flush all pending output for file, if necessary, close file and + deallocate the (de)compression state. Note that once file is closed, you cannot call gzerror with file, since its structures have been deallocated. gzclose must not be called more than once on the same file, just as free must not be called more than once on the same allocation. gzclose will return Z_STREAM_ERROR if file is not valid, Z_ERRNO on a - file operation error, or Z_OK on success. + file operation error, Z_MEM_ERROR if out of memory, Z_BUF_ERROR if the + last read ended in the middle of a gzip stream, or Z_OK on success. */ ZEXTERN int ZEXPORT gzclose_r OF((gzFile file)); @@ -1436,10 +1655,10 @@ ZEXTERN int ZEXPORT gzclose_w OF((gzFile file)); ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum)); /* - Returns the error message for the last error which occurred on the given - compressed file. errnum is set to zlib error number. If an error occurred - in the file system and not in the compression library, errnum is set to - Z_ERRNO and the application may consult errno to get the exact error code. + Return the error message for the last error which occurred on file. + errnum is set to zlib error number. If an error occurred in the file system + and not in the compression library, errnum is set to Z_ERRNO and the + application may consult errno to get the exact error code. The application must not modify the returned string. Future calls to this function may invalidate the previously returned string. If file is @@ -1452,11 +1671,12 @@ ZEXTERN const char * ZEXPORT gzerror OF((gzFile file, int *errnum)); ZEXTERN void ZEXPORT gzclearerr OF((gzFile file)); /* - Clears the error and end-of-file flags for file. This is analogous to the + Clear the error and end-of-file flags for file. This is analogous to the clearerr() function in stdio. This is useful for continuing to read a gzip file that is being written concurrently. */ +#endif /* !Z_SOLO */ /* checksum functions */ @@ -1469,10 +1689,11 @@ ZEXTERN void ZEXPORT gzclearerr OF((gzFile file)); ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); /* Update a running Adler-32 checksum with the bytes buf[0..len-1] and - return the updated checksum. If buf is Z_NULL, this function returns the - required initial value for the checksum. + return the updated checksum. An Adler-32 value is in the range of a 32-bit + unsigned integer. If buf is Z_NULL, this function returns the required + initial value for the checksum. - An Adler-32 checksum is almost as reliable as a CRC32 but can be computed + An Adler-32 checksum is almost as reliable as a CRC-32 but can be computed much faster. Usage example: @@ -1485,6 +1706,12 @@ ZEXTERN uLong ZEXPORT adler32 OF((uLong adler, const Bytef *buf, uInt len)); if (adler != original_adler) error(); */ +ZEXTERN uLong ZEXPORT adler32_z OF((uLong adler, const Bytef *buf, + z_size_t len)); +/* + Same as adler32(), but with a size_t length. +*/ + /* ZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2, z_off_t len2)); @@ -1492,16 +1719,18 @@ ZEXTERN uLong ZEXPORT adler32_combine OF((uLong adler1, uLong adler2, Combine two Adler-32 checksums into one. For two sequences of bytes, seq1 and seq2 with lengths len1 and len2, Adler-32 checksums were calculated for each, adler1 and adler2. adler32_combine() returns the Adler-32 checksum of - seq1 and seq2 concatenated, requiring only adler1, adler2, and len2. + seq1 and seq2 concatenated, requiring only adler1, adler2, and len2. Note + that the z_off_t type (like off_t) is a signed integer. If len2 is + negative, the result has no meaning or utility. */ -ZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len)); +ZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len)); /* Update a running CRC-32 with the bytes buf[0..len-1] and return the - updated CRC-32. If buf is Z_NULL, this function returns the required - initial value for the for the crc. Pre- and post-conditioning (one's - complement) is performed within this function so it shouldn't be done by the - application. + updated CRC-32. A CRC-32 value is in the range of a 32-bit unsigned integer. + If buf is Z_NULL, this function returns the required initial value for the + crc. Pre- and post-conditioning (one's complement) is performed within this + function so it shouldn't be done by the application. Usage example: @@ -1513,6 +1742,12 @@ ZEXTERN uLong ZEXPORT crc32 OF((uLong crc, const Bytef *buf, uInt len)); if (crc != original_crc) error(); */ +ZEXTERN uLong ZEXPORT crc32_z OF((uLong crc, const Bytef *buf, + z_size_t len)); +/* + Same as crc32(), but with a size_t length. +*/ + /* ZEXTERN uLong ZEXPORT crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2)); @@ -1523,6 +1758,20 @@ ZEXTERN uLong ZEXPORT crc32_combine OF((uLong crc1, uLong crc2, z_off_t len2)); len2. */ +/* +ZEXTERN uLong ZEXPORT crc32_combine_gen OF((z_off_t len2)); + + Return the operator corresponding to length len2, to be used with + crc32_combine_op(). +*/ + +ZEXTERN uLong ZEXPORT crc32_combine_op OF((uLong crc1, uLong crc2, uLong op)); +/* + Give the same result as crc32_combine(), using op in place of len2. op is + is generated from len2 by crc32_combine_gen(). This will be faster than + crc32_combine() if the generated op is used more than once. +*/ + /* various hacks, don't look :) */ @@ -1543,18 +1792,59 @@ ZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, unsigned char FAR *window, const char *version, int stream_size)); -#define deflateInit(strm, level) \ - deflateInit_((strm), (level), ZLIB_VERSION, sizeof(z_stream)) -#define inflateInit(strm) \ - inflateInit_((strm), ZLIB_VERSION, sizeof(z_stream)) -#define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ - deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ - (strategy), ZLIB_VERSION, sizeof(z_stream)) -#define inflateInit2(strm, windowBits) \ - inflateInit2_((strm), (windowBits), ZLIB_VERSION, sizeof(z_stream)) -#define inflateBackInit(strm, windowBits, window) \ - inflateBackInit_((strm), (windowBits), (window), \ - ZLIB_VERSION, sizeof(z_stream)) +#ifdef Z_PREFIX_SET +# define z_deflateInit(strm, level) \ + deflateInit_((strm), (level), ZLIB_VERSION, (int)sizeof(z_stream)) +# define z_inflateInit(strm) \ + inflateInit_((strm), ZLIB_VERSION, (int)sizeof(z_stream)) +# define z_deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ + deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ + (strategy), ZLIB_VERSION, (int)sizeof(z_stream)) +# define z_inflateInit2(strm, windowBits) \ + inflateInit2_((strm), (windowBits), ZLIB_VERSION, \ + (int)sizeof(z_stream)) +# define z_inflateBackInit(strm, windowBits, window) \ + inflateBackInit_((strm), (windowBits), (window), \ + ZLIB_VERSION, (int)sizeof(z_stream)) +#else +# define deflateInit(strm, level) \ + deflateInit_((strm), (level), ZLIB_VERSION, (int)sizeof(z_stream)) +# define inflateInit(strm) \ + inflateInit_((strm), ZLIB_VERSION, (int)sizeof(z_stream)) +# define deflateInit2(strm, level, method, windowBits, memLevel, strategy) \ + deflateInit2_((strm),(level),(method),(windowBits),(memLevel),\ + (strategy), ZLIB_VERSION, (int)sizeof(z_stream)) +# define inflateInit2(strm, windowBits) \ + inflateInit2_((strm), (windowBits), ZLIB_VERSION, \ + (int)sizeof(z_stream)) +# define inflateBackInit(strm, windowBits, window) \ + inflateBackInit_((strm), (windowBits), (window), \ + ZLIB_VERSION, (int)sizeof(z_stream)) +#endif + +#ifndef Z_SOLO + +/* gzgetc() macro and its supporting function and exposed data structure. Note + * that the real internal state is much larger than the exposed structure. + * This abbreviated structure exposes just enough for the gzgetc() macro. The + * user should not mess with these exposed elements, since their names or + * behavior could change in the future, perhaps even capriciously. They can + * only be used by the gzgetc() macro. You have been warned. + */ +struct gzFile_s { + unsigned have; + unsigned char *next; + z_off64_t pos; +}; +ZEXTERN int ZEXPORT gzgetc_ OF((gzFile file)); /* backward compatibility */ +#ifdef Z_PREFIX_SET +# undef z_gzgetc +# define z_gzgetc(g) \ + ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : (gzgetc)(g)) +#else +# define gzgetc(g) \ + ((g)->have ? ((g)->have--, (g)->pos++, *((g)->next)++) : (gzgetc)(g)) +#endif /* provide 64-bit offset functions if _LARGEFILE64_SOURCE defined, and/or * change the regular functions to 64 bits if _FILE_OFFSET_BITS is 64 (if @@ -1562,29 +1852,42 @@ ZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, * functions are changed to 64 bits) -- in case these are set on systems * without large file support, _LFS64_LARGEFILE must also be true */ -#if defined(_LARGEFILE64_SOURCE) && _LFS64_LARGEFILE-0 +#ifdef Z_LARGE64 ZEXTERN gzFile ZEXPORT gzopen64 OF((const char *, const char *)); ZEXTERN z_off64_t ZEXPORT gzseek64 OF((gzFile, z_off64_t, int)); ZEXTERN z_off64_t ZEXPORT gztell64 OF((gzFile)); ZEXTERN z_off64_t ZEXPORT gzoffset64 OF((gzFile)); ZEXTERN uLong ZEXPORT adler32_combine64 OF((uLong, uLong, z_off64_t)); ZEXTERN uLong ZEXPORT crc32_combine64 OF((uLong, uLong, z_off64_t)); + ZEXTERN uLong ZEXPORT crc32_combine_gen64 OF((z_off64_t)); #endif -#if !defined(ZLIB_INTERNAL) && _FILE_OFFSET_BITS-0 == 64 && _LFS64_LARGEFILE-0 -# define gzopen gzopen64 -# define gzseek gzseek64 -# define gztell gztell64 -# define gzoffset gzoffset64 -# define adler32_combine adler32_combine64 -# define crc32_combine crc32_combine64 -# ifdef _LARGEFILE64_SOURCE +#if !defined(ZLIB_INTERNAL) && defined(Z_WANT64) +# ifdef Z_PREFIX_SET +# define z_gzopen z_gzopen64 +# define z_gzseek z_gzseek64 +# define z_gztell z_gztell64 +# define z_gzoffset z_gzoffset64 +# define z_adler32_combine z_adler32_combine64 +# define z_crc32_combine z_crc32_combine64 +# define z_crc32_combine_gen z_crc32_combine_gen64 +# else +# define gzopen gzopen64 +# define gzseek gzseek64 +# define gztell gztell64 +# define gzoffset gzoffset64 +# define adler32_combine adler32_combine64 +# define crc32_combine crc32_combine64 +# define crc32_combine_gen crc32_combine_gen64 +# endif +# ifndef Z_LARGE64 ZEXTERN gzFile ZEXPORT gzopen64 OF((const char *, const char *)); ZEXTERN z_off_t ZEXPORT gzseek64 OF((gzFile, z_off_t, int)); ZEXTERN z_off_t ZEXPORT gztell64 OF((gzFile)); ZEXTERN z_off_t ZEXPORT gzoffset64 OF((gzFile)); ZEXTERN uLong ZEXPORT adler32_combine64 OF((uLong, uLong, z_off_t)); ZEXTERN uLong ZEXPORT crc32_combine64 OF((uLong, uLong, z_off_t)); + ZEXTERN uLong ZEXPORT crc32_combine_gen64 OF((z_off_t)); # endif #else ZEXTERN gzFile ZEXPORT gzopen OF((const char *, const char *)); @@ -1593,18 +1896,37 @@ ZEXTERN int ZEXPORT inflateBackInit_ OF((z_streamp strm, int windowBits, ZEXTERN z_off_t ZEXPORT gzoffset OF((gzFile)); ZEXTERN uLong ZEXPORT adler32_combine OF((uLong, uLong, z_off_t)); ZEXTERN uLong ZEXPORT crc32_combine OF((uLong, uLong, z_off_t)); + ZEXTERN uLong ZEXPORT crc32_combine_gen OF((z_off_t)); #endif -/* hack for buggy compilers */ -#if !defined(ZUTIL_H) && !defined(NO_DUMMY_DECL) - struct internal_state {int dummy;}; -#endif +#else /* Z_SOLO */ + + ZEXTERN uLong ZEXPORT adler32_combine OF((uLong, uLong, z_off_t)); + ZEXTERN uLong ZEXPORT crc32_combine OF((uLong, uLong, z_off_t)); + ZEXTERN uLong ZEXPORT crc32_combine_gen OF((z_off_t)); + +#endif /* !Z_SOLO */ /* undocumented functions */ ZEXTERN const char * ZEXPORT zError OF((int)); ZEXTERN int ZEXPORT inflateSyncPoint OF((z_streamp)); -ZEXTERN const uLongf * ZEXPORT get_crc_table OF((void)); +ZEXTERN const z_crc_t FAR * ZEXPORT get_crc_table OF((void)); ZEXTERN int ZEXPORT inflateUndermine OF((z_streamp, int)); +ZEXTERN int ZEXPORT inflateValidate OF((z_streamp, int)); +ZEXTERN unsigned long ZEXPORT inflateCodesUsed OF((z_streamp)); +ZEXTERN int ZEXPORT inflateResetKeep OF((z_streamp)); +ZEXTERN int ZEXPORT deflateResetKeep OF((z_streamp)); +#if defined(_WIN32) && !defined(Z_SOLO) +ZEXTERN gzFile ZEXPORT gzopen_w OF((const wchar_t *path, + const char *mode)); +#endif +#if defined(STDC) || defined(Z_HAVE_STDARG_H) +# ifndef Z_SOLO +ZEXTERN int ZEXPORTVA gzvprintf Z_ARG((gzFile file, + const char *format, + va_list va)); +# endif +#endif #ifdef __cplusplus } |