[PATCH 05/41] rtems: Generate <rtems/irq-extension.h>
Gedare Bloom
gedare at rtems.org
Wed Jul 21 17:50:07 UTC 2021
On Mon, Jul 12, 2021 at 6:50 AM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> Use <rtems/score/chain.h> which just provides the data types and avoid a
> dependency on <rtems/chain.h> which contains the full chain
> implementation.
>
> Change license to BSD-2-Clause according to file histories and
> documentation re-licensing agreement.
>
> Update #3269.
> Update #3899.
> Update #3993.
> ---
> cpukit/include/rtems/irq-extension.h | 1830 +++++++++++++++++++-------
> 1 file changed, 1354 insertions(+), 476 deletions(-)
>
> diff --git a/cpukit/include/rtems/irq-extension.h b/cpukit/include/rtems/irq-extension.h
> index 915be09e2b..5f24fb502e 100644
> --- a/cpukit/include/rtems/irq-extension.h
> +++ b/cpukit/include/rtems/irq-extension.h
> @@ -1,294 +1,566 @@
> +/* SPDX-License-Identifier: BSD-2-Clause */
> +
> /**
> * @file
> *
> - * @ingroup rtems_interrupt_extension
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * @brief Header file for the Interrupt Manager Extension.
> + * @brief This header file defines the Interrupt Manager Extension API.
> + */
> +
> +/*
> + * Copyright (C) 2008, 2021 embedded brains GmbH (http://www.embedded-brains.de)
> + *
> + * 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.
> */
>
> /*
> - * Based on concepts of Pavel Pisa, Till Straumann and Eric Valette.
We lose some kind of historical record / attribution here. I wonder
if, based on the other discussion about sponsor attribution, there
should be something in the generated header for any non-copyright
attribution (e.g., if someone wants their authorship reflected)?
I don't think it matters so much. Those three guys have their
contributions well-reflected in other parts of RTEMS.
> + * This file is part of the RTEMS quality process and was automatically
> + * generated. If you find something that needs to be fixed or
> + * worded better please post a report or patch to an RTEMS mailing list
> + * or raise a bug report:
> + *
> + * https://www.rtems.org/bugs.html
> *
> - * Copyright (C) 2008, 2020 embedded brains GmbH (http://www.embedded-brains.de)
> + * For information on updating and regenerating please refer to the How-To
> + * section in the Software Requirements Engineering chapter of the
> + * RTEMS Software Engineering manual. The manual is provided as a part of
> + * a release. For development sources please refer to the online
> + * documentation at:
> *
> - * The license and distribution terms for this file may be
> - * found in the file LICENSE in this distribution or at
> - * http://www.rtems.org/license/LICENSE.
> + * https://docs.rtems.org
> */
>
> -#ifndef RTEMS_IRQ_EXTENSION_H
> -#define RTEMS_IRQ_EXTENSION_H
> +/* Generated from spec:/rtems/intr/if/header-2 */
>
> -#include <rtems.h>
> -#include <rtems/chain.h>
> +#ifndef _RTEMS_IRQ_EXTENSION_H
> +#define _RTEMS_IRQ_EXTENSION_H
> +
> +#include <stddef.h>
> +#include <stdint.h>
> +#include <sys/cpuset.h>
> +#include <rtems/rtems/attr.h>
> +#include <rtems/rtems/intr.h>
> +#include <rtems/rtems/modes.h>
> +#include <rtems/rtems/options.h>
> +#include <rtems/rtems/status.h>
> +#include <rtems/rtems/types.h>
> +#include <rtems/score/chain.h>
>
> #ifdef __cplusplus
> extern "C" {
> -#endif /* __cplusplus */
> +#endif
> +
> +/* Generated from spec:/rtems/intr/if/handler */
>
> /**
> - * @defgroup rtems_interrupt_extension Interrupt Manager Extension
> - *
> * @ingroup RTEMSAPIClassicIntr
> *
> - * In addition to the Classic API interrupt handler with a handle are
> - * supported. You can also install multiple shared handler for one interrupt
> - * vector.
> + * @brief Interrupt handler routines shall have this type.
> */
> -/**@{**/
> +typedef void ( *rtems_interrupt_handler )( void * );
> +
> +/* Generated from spec:/rtems/intr/if/per-handler-routine */
>
> /**
> - * @brief Makes the interrupt handler unique. Prevents other handler from
> - * using the same interrupt vector.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Visitor routines invoked by rtems_interrupt_handler_iterate() shall
> + * have this type.
> */
> -#define RTEMS_INTERRUPT_UNIQUE ((rtems_option) 0x00000001)
> +typedef void ( *rtems_interrupt_per_handler_routine )(
> + void *,
> + const char *,
> + rtems_option,
> + rtems_interrupt_handler,
> + void *
> +);
> +
> +/* Generated from spec:/rtems/intr/if/shared */
>
> /**
> - * @brief Allows that this interrupt handler may share a common interrupt
> - * vector with other handler.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief This interrupt handler install option allows that the interrupt
> + * handler may share the interrupt vector with other handler.
> */
> -#define RTEMS_INTERRUPT_SHARED ((rtems_option) 0x00000000)
> +#define RTEMS_INTERRUPT_SHARED ( (rtems_option) 0x00000000 )
> +
> +/* Generated from spec:/rtems/intr/if/unique */
>
> /**
> - * @brief Forces that this interrupt handler replaces the first handler with
> - * the same argument.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief This interrupt handler install option ensures that the interrupt
> + * handler is unique.
> + *
> + * This option prevents other handler from using the same interrupt vector.
> */
> -#define RTEMS_INTERRUPT_REPLACE ((rtems_option) 0x00000002)
> +#define RTEMS_INTERRUPT_UNIQUE ( (rtems_option) 0x00000001 )
> +
> +/* Generated from spec:/rtems/intr/if/replace */
>
> /**
> - * @brief Returns true if the interrupt handler unique option is set.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief This interrupt handler install option requests that the interrupt
> + * handler replaces the first handler with the same argument.
> */
> -#define RTEMS_INTERRUPT_IS_UNIQUE( options) \
> - ((options) & RTEMS_INTERRUPT_UNIQUE)
> +#define RTEMS_INTERRUPT_REPLACE ( (rtems_option) 0x00000002 )
> +
> +/* Generated from spec:/rtems/intr/if/is-shared */
>
> /**
> - * @brief Returns true if the interrupt handler shared option is set.
> + * @brief Checks if the interrupt handler shared option is set.
> + *
> + * @param _options is the interrupt handler option set to check.
> + *
> + * @return Returns true, if the interrupt handler shared option
> + * #RTEMS_INTERRUPT_SHARED is set, otherwise false.
> */
> -#define RTEMS_INTERRUPT_IS_SHARED( options) \
> - (!RTEMS_INTERRUPT_IS_UNIQUE( options))
> +#define RTEMS_INTERRUPT_IS_SHARED( _options ) \
> + ( ( _options ) & RTEMS_INTERRUPT_SHARED )
> +
> +/* Generated from spec:/rtems/intr/if/is-unique */
>
> /**
> - * @brief Returns true if the interrupt handler replace option is set.
> + * @brief Checks if the interrupt handler unique option is set.
> + *
> + * @param _options is the interrupt handler option set to check.
> + *
> + * @return Returns true, if the interrupt handler unique option
> + * #RTEMS_INTERRUPT_UNIQUE is set, otherwise false.
> */
> -#define RTEMS_INTERRUPT_IS_REPLACE( options) \
> - ((options) & RTEMS_INTERRUPT_REPLACE)
> +#define RTEMS_INTERRUPT_IS_UNIQUE( _options ) \
> + ( ( _options ) & RTEMS_INTERRUPT_UNIQUE )
> +
> +/* Generated from spec:/rtems/intr/if/is-replace */
>
> /**
> - * @brief Interrupt handler routine type.
> + * @brief Checks if the interrupt handler replace option is set.
> + *
> + * @param _options is the interrupt handler option set to check.
> + *
> + * @return Returns true, if the interrupt handler replace option
> + * #RTEMS_INTERRUPT_REPLACE is set, otherwise false.
> */
> -typedef void (*rtems_interrupt_handler)(void *);
> +#define RTEMS_INTERRUPT_IS_REPLACE( _options ) \
> + ( ( _options ) & RTEMS_INTERRUPT_REPLACE )
> +
> +/* Generated from spec:/rtems/intr/if/handler-install */
>
> /**
> - * @brief Installs the interrupt handler routine @a handler for the interrupt
> - * vector with number @a vector.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Installs the interrupt handler routine and argument at the interrupt
> + * vector.
> + *
> + * @param vector is the interrupt vector number.
> + *
> + * @param info is the descriptive information of the interrupt handler to
> + * install.
> + *
> + * @param options is the interrupt handler install option set.
> + *
> + * @param routine is the interrupt handler routine to install.
> *
> - * You can set one of the mutually exclusive options
> + * @param arg is the interrupt handler argument to install.
> *
> - * - @ref RTEMS_INTERRUPT_UNIQUE
> - * - @ref RTEMS_INTERRUPT_SHARED
> - * - @ref RTEMS_INTERRUPT_REPLACE
> + * One of the following mutually exclusive options
> *
> - * with the @a options parameter for the interrupt handler.
> + * * #RTEMS_INTERRUPT_UNIQUE,
> *
> - * The handler routine shall be called with argument @a arg when dispatched.
> - * The order in which the shared interrupt handlers are dispatched for one
> - * vector is BSP dependent.
> + * * #RTEMS_INTERRUPT_SHARED, and
> *
> - * If the option @ref RTEMS_INTERRUPT_UNIQUE is set then it shall be ensured
> - * that this handler will be the only one for this vector.
> + * * #RTEMS_INTERRUPT_REPLACE
> *
> - * If the option @ref RTEMS_INTERRUPT_REPLACE is set then it shall be ensured
> - * that this handler will replace the first handler with the same argument for
> - * this vector if it exists, otherwise an error status shall be returned. A
> - * second handler with the same argument for this vector shall remain
> - * unchanged. The new handler will inherit the unique or shared option from
> + * shall be set in the ``options`` parameter.
> + *
> + * The handler routine will be called with the argument specified by ``arg``
> + * when dispatched. The order in which shared interrupt handlers are
> + * dispatched for one vector is defined by the installation order. The first
> + * installed handler is dispatched first.
> + *
> + * If the option #RTEMS_INTERRUPT_UNIQUE is set, then it will be ensured that
> + * the handler will be the only one for the interrupt vector.
> + *
> + * If the option #RTEMS_INTERRUPT_SHARED is set, then multiple handler may be
> + * installed for the interrupt vector.
> + *
> + * If the option #RTEMS_INTERRUPT_REPLACE is set, then the handler specified by
> + * ``routine`` will replace the first handler with the same argument for the
> + * interrupt vector if it exists, otherwise an error status will be returned.
> + * A second handler with the same argument for the interrupt vector will remain
> + * unchanged. The new handler will inherit the unique or shared options from
> * the replaced handler.
> *
> - * You can provide an informative description @a info. This may be used for
> - * system debugging and status tools. The string has to be persistent during
> - * the handler life time.
> - *
> - * This function may block.
> - *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_CALLED_FROM_ISR If this function is called from interrupt
> - * context this shall be returned.
> - * @retval RTEMS_INVALID_ADDRESS If the handler address is NULL this shall be
> - * returned.
> - * @retval RTEMS_INVALID_ID If the vector number is out of range this shall be
> - * returned.
> - * @retval RTEMS_INVALID_NUMBER If an option is not applicable this shall be
> - * returned.
> - * @retval RTEMS_RESOURCE_IN_USE If the vector is already occupied with a
> - * unique handler this shall be returned. If a unique handler should be
> - * installed and there is already a handler installed this shall be returned.
> - * @retval RTEMS_TOO_MANY If a handler with this argument is already installed
> - * for the vector this shall be returned.
> - * @retval RTEMS_UNSATISFIED If no handler exists to replace with the specified
> - * argument and vector this shall be returned.
> - * @retval RTEMS_IO_ERROR Reserved for board support package specific error
> - * conditions.
> + * An informative description may be provided in ``info``. It may be used for
> + * system debugging and diagnostic tools. The referenced string has to be
> + * persistent as long as the handler is installed.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
> + *
> + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
> + * interrupt context.
> + *
> + * @retval ::RTEMS_NO_MEMORY There was not enough memory available to allocate
> + * data structures to install the handler.
> + *
> + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set
> + * in ``options`` and the interrupt vector was already occupied by a handler.
> + *
> + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set
> + * in ``options`` and the interrupt vector was already occupied by a unique
> + * handler.
> + *
> + * @retval ::RTEMS_TOO_MANY The handler specified by ``routine`` was already
> + * installed for the interrupt vector specified by ``vector`` with an
> + * argument equal to the argument specified by ``arg``.
> + *
> + * @retval ::RTEMS_UNSATISFIED The #RTEMS_INTERRUPT_REPLACE option was set in
> + * ``options`` and no handler to replace was installed.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_handler_install(
> - rtems_vector_number vector,
> - const char *info,
> - rtems_option options,
> - rtems_interrupt_handler handler,
> - void *arg
> + rtems_vector_number vector,
> + const char *info,
> + rtems_option options,
> + rtems_interrupt_handler routine,
> + void *arg
> );
>
> +/* Generated from spec:/rtems/intr/if/handler-remove */
> +
> /**
> - * @brief Removes the interrupt handler routine @a handler with argument @a arg
> - * for the interrupt vector with number @a vector.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Removes the interrupt handler routine and argument from the interrupt
> + * vector.
> + *
> + * @param vector is the interrupt vector number.
> *
> - * This function may block.
> + * @param routine is the interrupt handler routine to remove.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_CALLED_FROM_ISR If this function is called from interrupt
> - * context this shall be returned.
> - * @retval RTEMS_INVALID_ADDRESS If the handler address is NULL this shall be
> - * returned.
> - * @retval RTEMS_INVALID_ID If the vector number is out of range this shall be
> - * returned.
> - * @retval RTEMS_UNSATISFIED If the handler with its argument is not installed
> - * for the vector this shall be returned.
> - * @retval RTEMS_IO_ERROR Reserved for board support package specific error
> - * conditions.
> + * @param arg is the interrupt handler argument to remove.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
> + *
> + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
> + * interrupt context.
> + *
> + * @retval ::RTEMS_UNSATISFIED There was no handler routine and argument pair
> + * installed specified by ``routine`` and ``arg``.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_handler_remove(
> - rtems_vector_number vector,
> - rtems_interrupt_handler handler,
> - void *arg
> + rtems_vector_number vector,
> + rtems_interrupt_handler routine,
> + void *arg
> );
>
> -/**
> - * @brief Interrupt handler iteration routine type.
> - *
> - * @see rtems_interrupt_handler_iterate()
> - */
> -typedef void (*rtems_interrupt_per_handler_routine)(
> - void *, const char *, rtems_option, rtems_interrupt_handler, void *
> -);
> +/* Generated from spec:/rtems/intr/if/get-affinity */
>
> /**
> - * @brief Iterates over all installed interrupt handler of the interrupt vector
> - * with number @a vector.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * For each installed handler of the vector the function @a routine will be
> - * called with the supplied argument @a arg and the handler information,
> - * options, routine and argument.
> + * @brief Gets the processor affinity set of the interrupt vector.
> *
> - * This function is intended for system information and diagnostics.
> + * @param vector is the interrupt vector number.
> *
> - * This function may block. Never install or remove an interrupt handler
> - * within the iteration routine. This may result in a deadlock.
> + * @param affinity_size is the size of the processor set referenced by
> + * ``affinity`` in bytes.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_CALLED_FROM_ISR If this function is called from interrupt
> - * context this shall be returned.
> - * @retval RTEMS_INVALID_ID If the vector number is out of range this shall be
> - * returned.
> - * @retval RTEMS_IO_ERROR Reserved for board support package specific error
> - * conditions.
> + * @param[out] affinity is the pointer to a cpu_set_t object. When the
> + * directive call is successful, the processor affinity set of the interrupt
> + * vector will be stored in this object. A set bit in the processor set
> + * means that the corresponding processor is in the processor affinity set of
> + * the interrupt vector, otherwise the bit is cleared.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ADDRESS The ``affinity`` parameter was NULL.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @retval ::RTEMS_INVALID_SIZE The size specified by ``affinity_size`` of the
> + * processor set was too small for the processor affinity set of the
> + * interrupt vector.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within interrupt context.
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive will not cause the calling task to be preempted.
> + * @endparblock
> */
> -rtems_status_code rtems_interrupt_handler_iterate(
> +rtems_status_code rtems_interrupt_get_affinity(
> rtems_vector_number vector,
> - rtems_interrupt_per_handler_routine routine,
> - void *arg
> + size_t affinity_size,
> + cpu_set_t *affinity
> );
>
> +/* Generated from spec:/rtems/intr/if/set-affinity */
> +
> /**
> - * @brief Sets the processor affinity set of an interrupt vector.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * @param[in] vector The interrupt vector number.
> - * @param[in] affinity_size The storage size of the affinity set.
> - * @param[in] affinity_set The new processor affinity set for the interrupt
> - * vector. This pointer must not be @c NULL.
> + * @brief Sets the processor affinity set of the interrupt vector.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_INVALID_ID The vector number is invalid.
> - * @retval RTEMS_INVALID_SIZE Invalid affinity set size.
> - * @retval RTEMS_INVALID_NUMBER Invalid processor affinity set.
> + * @param vector is the interrupt vector number.
> + *
> + * @param affinity_size is the size of the processor set referenced by
> + * ``affinity`` in bytes.
> + *
> + * @param affinity is the pointer to a cpu_set_t object. The processor set
> + * defines the new processor affinity set of the interrupt vector. A set bit
> + * in the processor set means that the corresponding processor shall be in
> + * the processor affinity set of the interrupt vector, otherwise the bit
> + * shall be cleared.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ADDRESS The ``affinity`` parameter was NULL.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @retval ::RTEMS_INVALID_NUMBER The referenced processor set was not a valid
> + * new processor affinity set for the interrupt vector.
> + *
> + * @retval ::RTEMS_UNSATISFIED The request to set the processor affinity of the
> + * interrupt vector has not been satisfied.
> + *
> + * @par Notes
> + * The rtems_interrupt_get_attributes() directive may be used to check if the
> + * processor affinity of an interrupt vector can be set.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within interrupt context.
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive will not cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_set_affinity(
> - rtems_vector_number vector,
> - size_t affinity_size,
> - const cpu_set_t *affinity
> + rtems_vector_number vector,
> + size_t affinity_size,
> + const cpu_set_t *affinity
> );
>
> +/* Generated from spec:/rtems/intr/if/handler-iterate */
> +
> /**
> - * @brief Gets the processor affinity set of an interrupt vector.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * @param[in] vector The interrupt vector number.
> - * @param[in] affinity_size The storage size of the affinity set.
> - * @param[out] affinity_set The current processor affinity set for the
> - * interrupt vector. This pointer must not be @c NULL.
> + * @brief Iterates over all interrupt handler installed at the interrupt
> + * vector.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_INVALID_ID The vector number is invalid.
> - * @retval RTEMS_INVALID_SIZE Invalid affinity set size.
> - */
> -rtems_status_code rtems_interrupt_get_affinity(
> - rtems_vector_number vector,
> - size_t affinity_size,
> - cpu_set_t *affinity
> -);
> -
> -/**
> - * @brief An interrupt server action.
> + * @param vector is the interrupt vector number.
> + *
> + * @param routine is the visitor routine.
> + *
> + * @param arg is the visitor argument.
> + *
> + * For each installed handler at the interrupt vector the visitor function
> + * specified by ``routine`` will be called with the argument specified by
> + * ``arg`` and the handler information, options, routine and argument.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INCORRECT_STATE The service was not initialized.
> + *
> + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
> + * interrupt context.
> + *
> + * @par Notes
> + * @parblock
> + * The directive is intended for system information and diagnostics.
> *
> - * This structure must be treated as an opaque data type. Members must not be
> - * accessed directly.
> + * Never install or remove an interrupt handler within the visitor function.
> + * This may result in a deadlock.
> + * @endparblock
> *
> - * @see rtems_interrupt_server_action_prepend().
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> -typedef struct rtems_interrupt_server_action {
> - struct rtems_interrupt_server_action *next;
> - rtems_interrupt_handler handler;
> - void *arg;
> -} rtems_interrupt_server_action;
> +rtems_status_code rtems_interrupt_handler_iterate(
> + rtems_vector_number vector,
> + rtems_interrupt_per_handler_routine routine,
> + void *arg
> +);
> +
> +/* Generated from spec:/rtems/intr/if/server-default */
>
> /**
> - * @brief The interrupt server index of the default interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief The constant represents the index of the default interrupt server.
> */
> #define RTEMS_INTERRUPT_SERVER_DEFAULT 0
>
> +/* Generated from spec:/rtems/intr/if/server-control */
> +
> /**
> - * @brief An interrupt server control.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * This structure must be treated as an opaque data type. Members must not be
> - * accessed directly.
> + * @brief This structure represents an interrupt server.
> *
> - * @see rtems_interrupt_server_create()
> + * @par Notes
> + * This structure shall be treated as an opaque data type from the API point of
> + * view. Members shall not be accessed directly. The structure is initialized
> + * by rtems_interrupt_server_create() and maintained by the interrupt server
> + * support.
> */
> typedef struct rtems_interrupt_server_control {
> - RTEMS_INTERRUPT_LOCK_MEMBER( lock )
> - rtems_chain_control entries;
> - rtems_id server;
> - unsigned long errors;
> - uint32_t index;
> - rtems_chain_node node;
> + #if defined(RTEMS_SMP)
> + /**
> + * @brief This member is the ISR lock protecting the server control state.
> + */
> + rtems_interrupt_lock lock;
> + #endif
> +
> + /**
> + * @brief This member is the chain of pending interrupt entries.
> + */
> + Chain_Control entries;
> +
> + /**
> + * @brief This member is the identifier of the server task.
> + */
> + rtems_id server;
> +
> + /**
> + * @brief This member is the error count.
> + */
> + unsigned long errors;
> +
> + /**
> + * @brief This member is the server index.
> + */
> + uint32_t index;
> +
> + /**
> + * @brief This member is the node for the interrupt server registry.
> + */
> + Chain_Node node;
> +
> + /**
> + * @brief This member is the optional handler to destroy the interrupt server
> + * control.
> + */
> void ( *destroy )( struct rtems_interrupt_server_control * );
> } rtems_interrupt_server_control;
>
> +/* Generated from spec:/rtems/intr/if/server-config */
> +
> /**
> - * @brief An interrupt server configuration.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief This structure defines an interrupt server configuration.
> *
> - * @see rtems_interrupt_server_create()
> + * @par Notes
> + * See also rtems_interrupt_server_create().
> */
> typedef struct {
> /**
> - * @brief The task name of the interrupt server.
> + * @brief This member is the task name of the interrupt server.
> */
> rtems_name name;
>
> /**
> - * @brief The initial task priority of the interrupt server.
> + * @brief This member is the initial task priority of the interrupt server.
> */
> rtems_task_priority priority;
>
> /**
> - * @brief The task storage area of the interrupt server.
> + * @brief This member is the task storage area of the interrupt server.
> *
> * It shall be NULL for interrupt servers created by
> * rtems_interrupt_server_create().
> @@ -296,127 +568,142 @@ typedef struct {
> void *storage_area;
>
> /**
> - * @brief The task storage size of the interrupt server.
> + * @brief This member is the task storage size of the interrupt server.
> *
> - * For interrupt servers created by rtems_interrupt_server_create() this is
> - * the task stack size.
> + * For interrupt servers created by rtems_interrupt_server_create() this is the
> + * task stack size.
> */
> size_t storage_size;
>
> /**
> - * @brief The initial task modes of the interrupt server.
> + * @brief This member is the initial mode set of the interrupt server.
> */
> rtems_mode modes;
>
> /**
> - * @brief The task attributes of the interrupt server.
> + * @brief This member is the attribute set of the interrupt server.
> */
> rtems_attribute attributes;
>
> /**
> - * @brief An optional handler to destroy the interrupt server control handed
> - * over to rtems_interrupt_server_create().
> + * @brief This member is an optional handler to destroy the interrupt server
> + * control handed over to rtems_interrupt_server_create().
> *
> - * This handler is called in the context of the interrupt server to be
> + * The destroy handler is optional and may be NULL. If the destroy handler is
> + * present, it is called from within the context of the interrupt server to be
> * deleted, see also rtems_interrupt_server_delete().
> */
> void ( *destroy )( rtems_interrupt_server_control * );
> } rtems_interrupt_server_config;
>
> +/* Generated from spec:/rtems/intr/if/server-initialize */
> +
> /**
> - * @brief An interrupt server entry.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * This structure must be treated as an opaque data type. Members must not be
> - * accessed directly.
> + * @brief Initializes the interrupt server tasks.
> *
> - * @see rtems_interrupt_server_entry_initialize(),
> - * rtems_interrupt_server_action_prepend(),
> - * rtems_interrupt_server_entry_submit(), and
> - * rtems_interrupt_server_entry_destroy().
> - */
> -typedef struct {
> - rtems_chain_node node;
> - void *server;
> - rtems_vector_number vector;
> - rtems_interrupt_server_action *actions;
> -} rtems_interrupt_server_entry;
> -
> -/**
> - * @brief An interrupt server request.
> + * @param priority is the initial task priority of the created interrupt
> + * servers.
> *
> - * This structure must be treated as an opaque data type. Members must not be
> - * accessed directly.
> + * @param stack_size is the task stack size of the created interrupt servers.
> *
> - * @see rtems_interrupt_server_request_initialize(),
> - * rtems_interrupt_server_request_set_vector(),
> - * rtems_interrupt_server_request_submit(), and
> - * rtems_interrupt_server_request_destroy().
> - */
> -typedef struct {
> - rtems_interrupt_server_entry entry;
> - rtems_interrupt_server_action action;
> -} rtems_interrupt_server_request;
> -
> -/**
> - * @brief Initializes the interrupt server tasks.
> + * @param modes is the initial mode set of the created interrupt servers.
> + *
> + * @param attributes is the attribute set of the created interrupt servers.
> + *
> + * @param[out] server_count is the pointer to an uint32_t object or NULL. When
> + * the pointer is not equal to NULL, the count of successfully created
> + * interrupt servers is stored in this object regardless of the return
> + * status.
> + *
> + * The directive tries to create an interrupt server task for each online
> + * processor in the system. The tasks will have the initial priority specified
> + * by ``priority``, the stack size specified by ``stack_size``, the initial
> + * mode set specified by ``modes``, and the attribute set specified by
> + * ``attributes``. The count of successfully created server tasks will be
> + * returned in ``server_count`` if the pointer is not equal to NULL.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> *
> - * This function tries to create an interrupt server task for each processor in
> - * the system. The tasks will have the priority @a priority, the stack size @a
> - * stack_size, the modes @a modes and the attributes @a attributes. The count
> - * of server tasks will be returned in @a server_count. Interrupt handlers can
> - * be installed on an interrupt server with
> + * @retval ::RTEMS_INCORRECT_STATE The interrupt servers were already
> + * initialized.
> + *
> + * @return The directive uses rtems_task_create(). If this directive fails,
> + * then its error status will be returned.
> + *
> + * @par Notes
> + * @parblock
> + * Interrupt handlers may be installed on an interrupt server with
> * rtems_interrupt_server_handler_install() and removed with
> * rtems_interrupt_server_handler_remove() using a server index. In case of an
> * interrupt, the request will be forwarded to the interrupt server. The
> * handlers are executed within the interrupt server context. If one handler
> * blocks on something this may delay the processing of other handlers.
> *
> - * The server count pointer @a server_count may be @a NULL.
> - *
> - * The task name of interrupt servers created by this function is
> - * rtems_build_name( 'I', 'R', 'Q', 'S' ).
> - *
> - * This function may block.
> + * Interrupt servers may be deleted by rtems_interrupt_server_delete().
> + * @endparblock
> *
> - * @retval RTEMS_SUCCESSFUL The operation was successful.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers were already initialized.
> + * * The directive may be called from within device driver initialization
> + * context.
> *
> - * @return The function uses rtems_task_create(). If this operation is not
> - * successful, then its status code is returned.
> + * * The directive may be called from within task context.
> *
> - * @see rtems_interrupt_server_create() and rtems_interrupt_server_delete().
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_initialize(
> rtems_task_priority priority,
> - size_t stack_size,
> - rtems_mode modes,
> - rtems_attribute attributes,
> - uint32_t *server_count
> + size_t stack_size,
> + rtems_mode modes,
> + rtems_attribute attributes,
> + uint32_t *server_count
> );
>
> +/* Generated from spec:/rtems/intr/if/server-create */
> +
> /**
> - * @brief Creates an interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * This function may block.
> + * @brief Creates an interrupt server.
> *
> - * @param[out] control is the interrupt server control. The ownership of this
> - * structure is transferred from the caller of this function to the interrupt
> + * @param[out] control is the pointer to an rtems_interrupt_server_control
> + * object. When the directive call was successful, the ownership of the
> + * object was transferred from the caller of the directive to the interrupt
> * server management.
> *
> * @param config is the interrupt server configuration.
> *
> - * @param[out] server_index is the pointer to a server index variable. The
> - * index of the built interrupt server will be stored in the referenced
> - * variable if the operation was successful.
> + * @param[out] server_index is the pointer to an uint32_t object. When the
> + * directive call was successful, the index of the created interrupt server
> + * will be stored in this object.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @return The directive uses rtems_task_create(). If this directive fails,
> + * then its error status will be returned.
> + *
> + * @par Notes
> + * See also rtems_interrupt_server_initialize() and
> + * rtems_interrupt_server_delete().
> *
> - * @retval RTEMS_SUCCESSFUL The operation was successful.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @return The function uses rtems_task_create(). If this operation is not
> - * successful, then its status code is returned.
> + * * The directive may be called from within device driver initialization
> + * context.
> *
> - * @see rtems_interrupt_server_initialize() and
> - * rtems_interrupt_server_delete().
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_create(
> rtems_interrupt_server_control *control,
> @@ -424,318 +711,832 @@ rtems_status_code rtems_interrupt_server_create(
> uint32_t *server_index
> );
>
> +/* Generated from spec:/rtems/intr/if/server-handler-install */
> +
> /**
> - * @brief Destroys the interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Installs the interrupt handler routine and argument at the interrupt
> + * vector on the interrupt server.
> *
> - * This function may block.
> + * @param server_index is the interrupt server index. The constant
> + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
> + * interrupt server.
> *
> - * The interrupt server deletes itself, so after the return of the function the
> - * interrupt server may be still in the termination process depending on the
> - * task priorities of the system.
> + * @param vector is the interrupt vector number.
> *
> - * @param server_index is the index of the interrupt server to destroy. Use
> - * ::RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> + * @param info is the descriptive information of the interrupt handler to
> + * install.
> *
> - * @retval RTEMS_SUCCESSFUL The operation was successful.
> - * @retval RTEMS_INVALID_ID The interrupt server index was invalid.
> + * @param options is the interrupt handler install option set.
> *
> - * @see rtems_interrupt_server_create()
> - */
> -rtems_status_code rtems_interrupt_server_delete( uint32_t server_index );
> -
> -/**
> - * @brief Installs the interrupt handler routine @a handler for the interrupt
> - * vector with number @a vector on the server @a server.
> + * @param routine is the interrupt handler routine to install.
> + *
> + * @param arg is the interrupt handler argument to install.
> + *
> + * The handler routine specified by ``routine`` will be executed within the
> + * context of the interrupt server task specified by ``server_index``.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> *
> - * The handler routine will be executed on the corresponding interrupt server
> - * task. A server index @a server_index of @c RTEMS_INTERRUPT_SERVER_DEFAULT
> - * may be used to install the handler on the default server.
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> *
> - * This function may block.
> + * @retval ::RTEMS_CALLED_FROM_ISR The directive was called from within
> + * interrupt context.
> *
> - * @see rtems_interrupt_handler_install().
> + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> - * @retval * For other errors see rtems_interrupt_handler_install().
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @retval ::RTEMS_INVALID_NUMBER An option specified by ``info`` was not
> + * applicable.
> + *
> + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_UNIQUE option was set
> + * in ``info`` and the interrupt vector was already occupied by a handler.
> + *
> + * @retval ::RTEMS_RESOURCE_IN_USE The #RTEMS_INTERRUPT_SHARED option was set
> + * in ``info`` and the interrupt vector was already occupied by a unique
> + * handler.
> + *
> + * @retval ::RTEMS_TOO_MANY The handler specified by ``routine`` was already
> + * installed for the interrupt vector specified by ``vector`` with an
> + * argument equal to the argument specified by ``arg``.
> + *
> + * @retval ::RTEMS_UNSATISFIED The #RTEMS_INTERRUPT_REPLACE option was set in
> + * ``info`` and no handler to replace was installed.
> + *
> + * @par Notes
> + * See also rtems_interrupt_handler_install().
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_handler_install(
> - uint32_t server_index,
> - rtems_vector_number vector,
> - const char *info,
> - rtems_option options,
> - rtems_interrupt_handler handler,
> - void *arg
> + uint32_t server_index,
> + rtems_vector_number vector,
> + const char *info,
> + rtems_option options,
> + rtems_interrupt_handler routine,
> + void *arg
> );
>
> +/* Generated from spec:/rtems/intr/if/server-handler-remove */
> +
> /**
> - * @brief Removes the interrupt handler routine @a handler with argument @a arg
> - * for the interrupt vector with number @a vector from the server @a server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Removes the interrupt handler routine and argument from the interrupt
> + * vector and the interrupt server.
> *
> - * A server index @a server_index of @c RTEMS_INTERRUPT_SERVER_DEFAULT may be
> - * used to remove the handler from the default server.
> + * @param server_index is the interrupt server index. The constant
> + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
> + * interrupt server.
> *
> - * This function may block.
> + * @param vector is the interrupt vector number.
> *
> - * @see rtems_interrupt_handler_remove().
> + * @param routine is the interrupt handler routine to remove.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> - * @retval * For other errors see rtems_interrupt_handler_remove().
> + * @param arg is the interrupt handler argument to remove.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @retval ::RTEMS_UNSATISFIED There was no handler routine and argument pair
> + * installed specified by ``routine`` and ``arg``.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + *
> + * * The directive sends a request to another task and waits for a response.
> + * This may cause the calling task to be blocked and unblocked.
> + *
> + * * The directive shall not be called from within the context of an interrupt
> + * server. Calling the directive from within the context of an interrupt
> + * server is undefined behaviour.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_handler_remove(
> - uint32_t server_index,
> - rtems_vector_number vector,
> - rtems_interrupt_handler handler,
> - void *arg
> + uint32_t server_index,
> + rtems_vector_number vector,
> + rtems_interrupt_handler routine,
> + void *arg
> );
>
> +/* Generated from spec:/rtems/intr/if/server-set-affinity */
> +
> /**
> - * @brief Iterates over all interrupt handler of the interrupt vector with
> - * number @a vector which are installed on the interrupt server specified by
> - * @a server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Sets the processor affinity of the interrupt server.
> + *
> + * @param server_index is the interrupt server index. The constant
> + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
> + * interrupt server.
> *
> - * A server index @a server_index of @c RTEMS_INTERRUPT_SERVER_DEFAULT may be
> - * used to specify the default server.
> + * @param affinity_size is the size of the processor set referenced by
> + * ``affinity`` in bytes.
> *
> - * @see rtems_interrupt_handler_iterate()
> + * @param affinity is the pointer to a cpu_set_t object. The processor set
> + * defines the new processor affinity set of the interrupt server. A set bit
> + * in the processor set means that the corresponding processor shall be in
> + * the processor affinity set of the task, otherwise the bit shall be
> + * cleared.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> - * @retval * For other errors see rtems_interrupt_handler_iterate().
> + * @param priority is the new real priority for the interrupt server.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> + *
> + * @return The directive uses rtems_scheduler_ident_by_processor_set(),
> + * rtems_task_set_scheduler(), and rtems_task_set_affinity(). If one of
> + * these directive fails, then its error status will be returned.
> + *
> + * @par Notes
> + * @parblock
> + * The scheduler is set determined by the highest numbered processor in the
> + * affinity set specified by ``affinity``.
> + *
> + * This operation is only reliable in case the interrupt server was suspended
> + * via rtems_interrupt_server_suspend().
> + * @endparblock
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within interrupt context.
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may change the processor affinity of a task. This may cause
> + * the calling task to be preempted.
> + *
> + * * The directive may change the priority of a task. This may cause the
> + * calling task to be preempted.
> + * @endparblock
> */
> -rtems_status_code rtems_interrupt_server_handler_iterate(
> - uint32_t server_index,
> - rtems_vector_number vector,
> - rtems_interrupt_per_handler_routine routine,
> - void *arg
> +rtems_status_code rtems_interrupt_server_set_affinity(
> + uint32_t server_index,
> + size_t affinity_size,
> + const cpu_set_t *affinity,
> + rtems_task_priority priority
> );
>
> +/* Generated from spec:/rtems/intr/if/server-delete */
> +
> /**
> - * @brief Moves the interrupt handlers installed on the specified source
> - * interrupt server to the destination interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Deletes the interrupt server.
> *
> - * This function must be called from thread context. It may block. Calling
> - * this function within the context of an interrupt server is undefined
> - * behaviour.
> + * @param server_index is the index of the interrupt server to delete.
> *
> - * @param[in] source_server_index The source interrupt server index. Use
> - * @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> - * @param[in] vector The interrupt vector number.
> - * @param[in] destination_server_index The destination interrupt server index.
> - * Use @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID The destination interrupt server index is invalid.
> - * @retval RTEMS_INVALID_ID The vector number is invalid.
> - * @retval RTEMS_INVALID_ID The destination interrupt server index is invalid.
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * server index specified by ``server_index``.
> + *
> + * @par Notes
> + * @parblock
> + * The interrupt server deletes itself, so after the return of the directive
> + * the interrupt server may be still in the termination process depending on
> + * the task priorities of the system.
> + *
> + * See also rtems_interrupt_server_create().
> + * @endparblock
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive shall not be called from within the context of an interrupt
> + * server. Calling the directive from within the context of an interrupt
> + * server is undefined behaviour.
> + *
> + * * The directive sends a request to another task and waits for a response.
> + * This may cause the calling task to be blocked and unblocked.
> + * @endparblock
> */
> -rtems_status_code rtems_interrupt_server_move(
> - uint32_t source_server_index,
> - rtems_vector_number vector,
> - uint32_t destination_server_index
> -);
> +rtems_status_code rtems_interrupt_server_delete( uint32_t server_index );
> +
> +/* Generated from spec:/rtems/intr/if/server-suspend */
>
> /**
> - * @brief Suspends the specified interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Suspends the interrupt server.
> + *
> + * @param server_index is the index of the interrupt server to suspend. The
> + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
> + * default interrupt server.
> *
> - * A suspend request is sent to the specified interrupt server. This function
> - * waits for an acknowledgment from the specified interrupt server.
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> *
> - * This function must be called from thread context. It may block. Calling
> - * this function within the context of an interrupt server is undefined
> - * behaviour.
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> *
> - * @param[in] server_index The interrupt server index. Use
> - * @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> + * @par Notes
> + * Interrupt server may be resumed by rtems_interrupt_server_resume().
> *
> - * @see rtems_interrupt_server_resume().
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> + * * The directive may be called from within task context.
> + *
> + * * The directive shall not be called from within the context of an interrupt
> + * server. Calling the directive from within the context of an interrupt
> + * server is undefined behaviour.
> + *
> + * * The directive sends a request to another task and waits for a response.
> + * This may cause the calling task to be blocked and unblocked.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_suspend( uint32_t server_index );
>
> +/* Generated from spec:/rtems/intr/if/server-resume */
> +
> /**
> - * @brief Resumes the specified interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Resumes the interrupt server.
> + *
> + * @param server_index is the index of the interrupt server to resume. The
> + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
> + * default interrupt server.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> *
> - * This function must be called from thread context. It may block. Calling
> - * this function within the context of an interrupt server is undefined
> - * behaviour.
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> *
> - * @param[in] server_index The interrupt server index. Use
> - * @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> + * @par Notes
> + * Interrupt server may be suspended by rtems_interrupt_server_suspend().
> *
> - * @see rtems_interrupt_server_suspend().
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> + * * The directive may be called from within task context.
> + *
> + * * The directive shall not be called from within the context of an interrupt
> + * server. Calling the directive from within the context of an interrupt
> + * server is undefined behaviour.
> + *
> + * * The directive sends a request to another task and waits for a response.
> + * This may cause the calling task to be blocked and unblocked.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_resume( uint32_t server_index );
>
> +/* Generated from spec:/rtems/intr/if/server-move */
> +
> /**
> - * @brief Sets the processor affinity of the specified interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * The scheduler is set determined by the highest numbered processor in the
> - * specified affinity set.
> + * @brief Moves the interrupt handlers installed at the interrupt vector and
> + * the source interrupt server to the destination interrupt server.
> *
> - * This operation is only reliable in case the specified interrupt was
> - * suspended via rtems_interrupt_server_suspend().
> + * @param source_server_index is the index of the source interrupt server. The
> + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
> + * default interrupt server.
> *
> - * @param[in] server_index The interrupt server index. Use
> - * @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> - * @param[in] affinity_size The storage size of the affinity set.
> - * @param[in] affinity The desired processor affinity set for the specified
> - * interrupt server.
> - * @param[in] priority The task priority with respect to the corresponding
> - * scheduler instance.
> - *
> - * @retval RTEMS_SUCCESSFUL Successful operation
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> - * @retval RTEMS_INVALID_SIZE Invalid affinity set size.
> - * @retval RTEMS_INVALID_NAME The affinity set contains no online processor.
> - * @retval RTEMS_INCORRECT_STATE The highest numbered online processor in the
> - * specified affinity set is not owned by a scheduler.
> - * @retval RTEMS_INVALID_PRIORITY Invalid priority.
> - * @retval RTEMS_RESOURCE_IN_USE The interrupt server owns resources which deny
> - * a scheduler change.
> - * @retval RTEMS_INVALID_NUMBER Invalid processor affinity set.
> + * @param vector is the interrupt vector number.
> + *
> + * @param destination_server_index is the index of the destination interrupt
> + * server. The constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to
> + * specify the default interrupt server.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``source_server_index``.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``destination_server_index``.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive shall not be called from within the context of an interrupt
> + * server. Calling the directive from within the context of an interrupt
> + * server is undefined behaviour.
> + *
> + * * The directive sends a request to another task and waits for a response.
> + * This may cause the calling task to be blocked and unblocked.
> + * @endparblock
> */
> -rtems_status_code rtems_interrupt_server_set_affinity(
> - uint32_t server_index,
> - size_t affinity_size,
> - const cpu_set_t *affinity,
> - rtems_task_priority priority
> +rtems_status_code rtems_interrupt_server_move(
> + uint32_t source_server_index,
> + rtems_vector_number vector,
> + uint32_t destination_server_index
> +);
> +
> +/* Generated from spec:/rtems/intr/if/server-handler-iterate */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Iterates over all interrupt handler installed at the interrupt vector
> + * and interrupt server.
> + *
> + * @param server_index is the index of the interrupt server.
> + *
> + * @param vector is the interrupt vector number.
> + *
> + * @param routine is the visitor routine.
> + *
> + * @param arg is the visitor argument.
> + *
> + * For each installed handler at the interrupt vector and interrupt server the
> + * visitor function specified by ``vector`` will be called with the argument
> + * specified by ``routine`` and the handler information, options, routine and
> + * argument.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt vector associated with the
> + * number specified by ``vector``.
> + *
> + * @par Notes
> + * @parblock
> + * The directive is intended for system information and diagnostics.
> + *
> + * Never install or remove an interrupt handler within the visitor function.
> + * This may result in a deadlock.
> + * @endparblock
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> + */
> +rtems_status_code rtems_interrupt_server_handler_iterate(
> + uint32_t server_index,
> + rtems_vector_number vector,
> + rtems_interrupt_per_handler_routine routine,
> + void *arg
> );
>
> +/* Generated from spec:/rtems/intr/if/server-action */
> +
> /**
> - * @brief Initializes the specified interrupt server entry.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * @param[in] server_index The interrupt server index. Use
> - * @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> - * @param[in] entry The interrupt server entry to initialize.
> + * @brief This structure represents an interrupt server action.
> + *
> + * @par Notes
> + * This structure shall be treated as an opaque data type from the API point of
> + * view. Members shall not be accessed directly.
> + */
> +typedef struct rtems_interrupt_server_action {
> + /**
> + * @brief This member is the reference to the next action or NULL.
> + */
> + struct rtems_interrupt_server_action *next;
> +
> + /**
> + * @brief This member is the interrupt handler.
> + */
> + rtems_interrupt_handler handler;
> +
> + /**
> + * @brief This member is the interrupt handler argument.
> + */
> + void *arg;
> +} rtems_interrupt_server_action;
> +
> +/* Generated from spec:/rtems/intr/if/server-entry */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * @see rtems_interrupt_server_action_prepend().
> + * @brief This structure represents an interrupt server entry.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> + * @par Notes
> + * This structure shall be treated as an opaque data type from the API point of
> + * view. Members shall not be accessed directly. An entry is initialized by
> + * rtems_interrupt_server_entry_initialize() and destroyed by
> + * 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().
> + */
> +typedef struct {
> + /**
> + * @brief This member is the node for the interrupt entry processing.
> + */
> + Chain_Node node;
> +
> + /**
> + * @brief This member references the interrupt server used to process the
> + * entry.
> + */
> + rtems_interrupt_server_control *server;
> +
> + /**
> + * @brief This member is the interrupt vector number.
> + */
> + rtems_vector_number vector;
> +
> + /**
> + * @brief This member is the interrupt server actions list head.
> + */
> + rtems_interrupt_server_action *actions;
> +} rtems_interrupt_server_entry;
> +
> +/* Generated from spec:/rtems/intr/if/server-entry-initialize */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Initializes the interrupt server entry.
> + *
> + * @param server_index is the interrupt server index. The constant
> + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
> + * interrupt server.
> + *
> + * @param entry is the interrupt server entry to initialize.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> + *
> + * @par Notes
> + * After initialization, the list of actions of the interrupt server entry is
> + * empty. Actions may be prepended by rtems_interrupt_server_action_prepend().
> + * Interrupt server entries may be moved to another interrupt vector with
> + * rtems_interrupt_server_entry_move(). Server entries may be submitted to get
> + * serviced by the interrupt server with rtems_interrupt_server_entry_submit().
> + * Server entries may be destroyed by rtems_interrupt_server_entry_destroy().
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_entry_initialize(
> uint32_t server_index,
> rtems_interrupt_server_entry *entry
> );
>
> +/* Generated from spec:/rtems/intr/if/server-action-prepend */
> +
> /**
> - * @brief Prepends the specified interrupt server action to the list of actions
> - * of the specified interrupt server entry.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * No error checking is performed.
> + * @brief Prepends the interrupt server action to the list of actions of the
> + * interrupt server entry.
> *
> - * @param[in] entry The interrupt server entry to prepend the interrupt server
> - * action. It must have been initialized via
> + * @param[in,out] entry is the interrupt server entry to prepend the interrupt
> + * server action. It shall have been initialized via
> * rtems_interrupt_server_entry_initialize().
> - * @param[in] action The interrupt server action to prepend the list of actions
> - * of the entry.
> - * @param[in] handler The interrupt handler for the action.
> - * @param[in] arg The interrupt handler argument for the action.
> + *
> + * @param[out] action is the interrupt server action to initialize and prepend
> + * to the list of actions of the entry.
> + *
> + * @param routine is the interrupt handler routine to set in the action.
> + *
> + * @param arg is the interrupt handler argument to set in the action.
> + *
> + * @par Notes
> + * No error checking is performed by the directive.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within interrupt context.
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive will not cause the calling task to be preempted.
> + *
> + * * The interrupt server entry shall have been initialized by
> + * rtems_interrupt_server_entry_initialize() and further optional calls to
> + * rtems_interrupt_server_action_prepend().
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_action_prepend() with the same interrupt server
> + * entry. Calling the directive under this condition is undefined behaviour.
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_entry_move() with the same interrupt server entry.
> + * Calling the directive under this condition is undefined behaviour.
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_entry_submit() with the same interrupt server
> + * entry. Calling the directive under this condition is undefined behaviour.
> + *
> + * * The directive shall not be called while the interrupt server entry is
> + * pending on or serviced by its current interrupt server. Calling the
> + * directive under these conditions is undefined behaviour.
> + * @endparblock
> */
> void rtems_interrupt_server_action_prepend(
> rtems_interrupt_server_entry *entry,
> rtems_interrupt_server_action *action,
> - rtems_interrupt_handler handler,
> + rtems_interrupt_handler routine,
> void *arg
> );
>
> +/* Generated from spec:/rtems/intr/if/server-entry-destroy */
> +
> +/**
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Destroys the interrupt server entry.
> + *
> + * @param[in,out] entry is the interrupt server entry to destroy.
> + *
> + * @par Notes
> + * No error checking is performed by the directive.
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive shall not be called from within the context of an interrupt
> + * server. Calling the directive from within the context of an interrupt
> + * server is undefined behaviour.
> + *
> + * * The directive sends a request to another task and waits for a response.
> + * This may cause the calling task to be blocked and unblocked.
> + *
> + * * The interrupt server entry shall have been initialized by
> + * rtems_interrupt_server_entry_initialize() and further optional calls to
> + * rtems_interrupt_server_action_prepend().
> + * @endparblock
> + */
> +void rtems_interrupt_server_entry_destroy(
> + rtems_interrupt_server_entry *entry
> +);
> +
> +/* Generated from spec:/rtems/intr/if/server-entry-submit */
> +
> /**
> - * @brief Submits the specified interrupt server entry so that its interrupt
> - * server actions can be invoked by the specified interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Submits the interrupt server entry to be serviced by the interrupt
> + * server.
> + *
> + * @param entry is the interrupt server entry to submit.
> + *
> + * The directive appends the entry to the pending entries of the interrupt
> + * server. The interrupt server is notified that a new entry is pending. Once
> + * the interrupt server is scheduled it services the actions of all pending
> + * entries.
> + *
> + * @par Notes
> + * @parblock
> + * This directive may be used to do a two-step interrupt processing. The first
> + * step is done from within interrupt context by a call to this directive. The
> + * second step is then done from within the context of the interrupt server.
> + *
> + * No error checking is performed by the directive.
> + *
> + * A submitted entry may be destroyed by
> + * rtems_interrupt_server_entry_destroy().
> + * @endparblock
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within interrupt context.
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> *
> - * This function may be used to do a two-step interrupt processing. The first
> - * step is done in interrupt context which calls this function. The second
> - * step is then done in the context of the interrupt server.
> + * * The directive may unblock a task. This may cause the calling task to be
> + * preempted.
> *
> - * This function may be called from thread or interrupt context. It does not
> - * block. No error checking is performed.
> + * * The interrupt server entry shall have been initialized by
> + * rtems_interrupt_server_entry_initialize() and further optional calls to
> + * rtems_interrupt_server_action_prepend().
> *
> - * @param[in] entry The interrupt server entry must be initialized before the
> - * first call to this function via rtems_interrupt_server_entry_initialize()
> - * and rtems_interrupt_server_action_prepend(). The entry and its actions
> - * must not be modified between calls to this function. Use
> - * rtems_interrupt_server_entry_destroy() to destroy an entry in use.
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_action_prepend() with the same interrupt server
> + * entry. Calling the directive under this condition is undefined behaviour.
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_entry_move() with the same interrupt server entry.
> + * Calling the directive under this condition is undefined behaviour.
> + * @endparblock
> */
> void rtems_interrupt_server_entry_submit(
> rtems_interrupt_server_entry *entry
> );
>
> +/* Generated from spec:/rtems/intr/if/server-entry-move */
> +
> /**
> - * @brief Moves the interrupt server entry to the specified destination
> - * interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Moves the interrupt server entry to the interrupt server.
> + *
> + * @param entry is the interrupt server entry to move.
> + *
> + * @param server_index is the index of the destination interrupt server. The
> + * constant #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the
> + * default interrupt server.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> *
> - * Calling this function concurrently with rtems_interrupt_server_entry_submit()
> - * with the same entry or while the entry is enqueued on the previous interrupt
> - * server is undefined behaviour.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * @param[in,out] entry The interrupt server entry. It must have be initialized
> - * before the call to this function.
> - * @param destination_server_index The destination interrupt server index.
> - * Use @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> + * * The directive may be called from within device driver initialization
> + * context.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID The destination interrupt server index is invalid.
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + *
> + * * The interrupt server entry shall have been initialized by
> + * rtems_interrupt_server_entry_initialize() and further optional calls to
> + * rtems_interrupt_server_action_prepend().
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_action_prepend() with the same interrupt server
> + * entry. Calling the directive under this condition is undefined behaviour.
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_entry_move() with the same interrupt server entry.
> + * Calling the directive under this condition is undefined behaviour.
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_entry_submit() with the same interrupt server
> + * entry. Calling the directive under this condition is undefined behaviour.
> + *
> + * * The directive shall not be called while the interrupt server entry is
> + * pending on or serviced by its current interrupt server. Calling the
> + * directive under these conditions is undefined behaviour.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_entry_move(
> rtems_interrupt_server_entry *entry,
> - uint32_t destination_server_index
> + uint32_t server_index
> );
>
> +/* Generated from spec:/rtems/intr/if/server-request */
> +
> /**
> - * @brief Destroys the specified interrupt server entry.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * This function must be called from thread context. It may block. Calling
> - * this function within the context of an interrupt server is undefined
> - * behaviour. No error checking is performed.
> + * @brief This structure represents an interrupt server request.
> *
> - * @param[in] entry The interrupt server entry to destroy. It must have been
> - * initialized via rtems_interrupt_server_entry_initialize().
> + * @par Notes
> + * This structure shall be treated as an opaque data type from the API point of
> + * view. Members shall not be accessed directly. A request is initialized by
> + * rtems_interrupt_server_request_initialize() and destroyed by
> + * rtems_interrupt_server_request_destroy(). The interrupt vector of the
> + * request can be set by rtems_interrupt_server_request_set_vector(). The
> + * request is submitted to be serviced by
> + * rtems_interrupt_server_request_submit().
> */
> -void rtems_interrupt_server_entry_destroy(
> - rtems_interrupt_server_entry *entry
> -);
> +typedef struct {
> + /**
> + * @brief This member is the interrupt server entry.
> + */
> + rtems_interrupt_server_entry entry;
> +
> + /**
> + * @brief This member is the interrupt server action.
> + */
> + rtems_interrupt_server_action action;
> +} rtems_interrupt_server_request;
> +
> +/* Generated from spec:/rtems/intr/if/server-request-initialize */
>
> /**
> - * @brief Initializes the specified interrupt server request.
> + * @ingroup RTEMSAPIClassicIntr
> *
> - * @param[in] server_index The interrupt server index. Use
> - * @c RTEMS_INTERRUPT_SERVER_DEFAULT to specify the default server.
> - * @param[in] request The interrupt server request to initialize.
> - * @param[in] handler The interrupt handler for the request action.
> - * @param[in] arg The interrupt handler argument for the request action.
> + * @brief Initializes the interrupt server request.
> + *
> + * @param server_index is the interrupt server index. The constant
> + * #RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default
> + * interrupt server.
> *
> - * @retval RTEMS_SUCCESSFUL Successful operation.
> - * @retval RTEMS_INCORRECT_STATE The interrupt servers are not initialized.
> - * @retval RTEMS_INVALID_ID If the interrupt server index is invalid.
> + * @param[out] request is the interrupt server request to initialize.
> *
> - * @see rtems_interrupt_server_request_set_vector().
> + * @param routine is the interrupt handler routine for the request action.
> + *
> + * @param arg is the interrupt handler argument for the request action.
> + *
> + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
> + *
> + * @retval ::RTEMS_INVALID_ID There was no interrupt server associated with the
> + * index specified by ``server_index``.
> + *
> + * @par Notes
> + * An interrupt server requests consists of an interrupt server entry and
> + * exactly one interrupt server action. The interrupt vector of the request
> + * may be changed with rtems_interrupt_server_request_set_vector(). Interrupt
> + * server requests may be submitted to get serviced by the interrupt server
> + * with rtems_interrupt_server_request_submit(). Requests may be destroyed by
> + * rtems_interrupt_server_request_destroy().
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may obtain and release the object allocator mutex. This may
> + * cause the calling task to be preempted.
> + * @endparblock
> */
> rtems_status_code rtems_interrupt_server_request_initialize(
> uint32_t server_index,
> rtems_interrupt_server_request *request,
> - rtems_interrupt_handler handler,
> + rtems_interrupt_handler routine,
> void *arg
> );
>
> +/* Generated from spec:/rtems/intr/if/server-request-set-vector */
> +
> /**
> - * @brief Sets the interrupt vector in the specified interrupt server request.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Sets the interrupt vector in the interrupt server request.
> + *
> + * @param[in,out] request is the interrupt server request to change.
> *
> + * @param vector is the interrupt vector number to be used by the request.
> + *
> + * @par Notes
> + * @parblock
> * By default, the interrupt vector of an interrupt server request is set to a
> * special value which is outside the range of vectors supported by the
> * interrupt controller hardware.
> @@ -743,13 +1544,40 @@ rtems_status_code rtems_interrupt_server_request_initialize(
> * Calls to rtems_interrupt_server_request_submit() will disable the interrupt
> * vector of the request. After processing of the request by the interrupt
> * server the interrupt vector will be enabled again.
> + * @endparblock
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within interrupt context.
> *
> - * @param[in] request The initialized interrupt server request.
> - * @param[in] vector The interrupt vector number.
> + * * The directive may be called from within device driver initialization
> + * context.
> *
> - * @see rtems_interrupt_server_request_initialize().
> + * * The directive may be called from within task context.
> + *
> + * * The directive will not cause the calling task to be preempted.
> + *
> + * * The interrupt server request shall have been initialized by
> + * rtems_interrupt_server_request_initialize().
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_request_set_vector() with the same interrupt server
> + * request. Calling the directive under this condition is undefined
> + * behaviour.
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_request_submit() with the same interrupt server
> + * request. Calling the directive under this condition is undefined
> + * behaviour.
> + *
> + * * The directive shall not be called while the interrupt server entry is
> + * pending on or serviced by its current interrupt server. Calling the
> + * directive under these conditions is undefined behaviour.
> + * @endparblock
> */
> -RTEMS_INLINE_ROUTINE void rtems_interrupt_server_request_set_vector(
> +static inline void rtems_interrupt_server_request_set_vector(
> rtems_interrupt_server_request *request,
> rtems_vector_number vector
> )
> @@ -757,51 +1585,101 @@ RTEMS_INLINE_ROUTINE void rtems_interrupt_server_request_set_vector(
> request->entry.vector = vector;
> }
>
> +/* Generated from spec:/rtems/intr/if/server-request-destroy */
> +
> /**
> - * @brief Submits the specified interrupt server request so that its interrupt
> - * server action can be invoked by the specified interrupt server.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Destroys the interrupt server request.
> *
> - * This function may be used to do a two-step interrupt processing. The first
> - * step is done in interrupt context which calls this function. The second
> - * step is then done in the context of the interrupt server.
> + * @param[in,out] request is the interrupt server request to destroy.
> *
> - * This function may be called from thread or interrupt context. It does not
> - * block. No error checking is performed.
> + * @par Notes
> + * No error checking is performed by the directive.
> *
> - * @param[in] request The interrupt server request must be initialized before the
> - * first call to this function via
> - * rtems_interrupt_server_request_initialize(). The request must not be
> - * modified between calls to this function. Use
> - * rtems_interrupt_server_request_destroy() to destroy a request in use.
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive shall not be called from within the context of an interrupt
> + * server. Calling the directive from within the context of an interrupt
> + * server is undefined behaviour.
> + *
> + * * The directive sends a request to another task and waits for a response.
> + * This may cause the calling task to be blocked and unblocked.
> + *
> + * * The interrupt server request shall have been initialized by
> + * rtems_interrupt_server_request_initialize().
> + * @endparblock
> */
> -RTEMS_INLINE_ROUTINE void rtems_interrupt_server_request_submit(
> +static inline void rtems_interrupt_server_request_destroy(
> rtems_interrupt_server_request *request
> )
> {
> - rtems_interrupt_server_entry_submit( &request->entry );
> + rtems_interrupt_server_entry_destroy( &request->entry );
> }
>
> +/* Generated from spec:/rtems/intr/if/server-request-submit */
> +
> /**
> - * @brief Destroys the specified interrupt server request.
> + * @ingroup RTEMSAPIClassicIntr
> + *
> + * @brief Submits the interrupt server request to be serviced by the interrupt
> + * server.
> + *
> + * @param[in,out] request is the interrupt server request to submit.
> + *
> + * The directive appends the interrupt server entry of the request to the
> + * pending entries of the interrupt server. The interrupt server is notified
> + * that a new entry is pending. Once the interrupt server is scheduled it
> + * services the actions of all pending entries.
> + *
> + * @par Notes
> + * @parblock
> + * This directive may be used to do a two-step interrupt processing. The first
> + * step is done from within interrupt context by a call to this directive. The
> + * second step is then done from within the context of the interrupt server.
> + *
> + * No error checking is performed by the directive.
> + *
> + * A submitted request may be destroyed by
> + * rtems_interrupt_server_request_destroy().
> + * @endparblock
> + *
> + * @par Constraints
> + * @parblock
> + * The following constraints apply to this directive:
> *
> - * This function must be called from thread context. It may block. Calling
> - * this function within the context of an interrupt server is undefined
> - * behaviour. No error checking is performed.
> + * * The directive may be called from within interrupt context.
> *
> - * @param[in] request The interrupt server request to destroy. It must have
> - * been initialized via rtems_interrupt_server_request_initialize().
> + * * The directive may be called from within device driver initialization
> + * context.
> + *
> + * * The directive may be called from within task context.
> + *
> + * * The directive may unblock a task. This may cause the calling task to be
> + * preempted.
> + *
> + * * The interrupt server request shall have been initialized by
> + * rtems_interrupt_server_request_initialize().
> + *
> + * * The directive shall not be called concurrently with
> + * rtems_interrupt_server_request_set_vector() with the same interrupt server
> + * request. Calling the directive under this condition is undefined
> + * behaviour.
> + * @endparblock
> */
> -RTEMS_INLINE_ROUTINE void rtems_interrupt_server_request_destroy(
> +static inline void rtems_interrupt_server_request_submit(
> rtems_interrupt_server_request *request
> )
> {
> - rtems_interrupt_server_entry_destroy( &request->entry );
> + rtems_interrupt_server_entry_submit( &request->entry );
> }
>
> -/** @} */
> -
> #ifdef __cplusplus
> }
> -#endif /* __cplusplus */
> +#endif
>
> -#endif /* RTEMS_IRQ_EXTENSION_H */
> +#endif /* _RTEMS_IRQ_EXTENSION_H */
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list