Interrupt Manager

Any real-time executive must provide a mechanism for quick response to externally generated interrupts to satisfy the critical time constraints of the application. The Interrupt Manager provides this mechanism for RTEMS. This manager permits quick interrupt response times by providing the critical ability to alter task execution which allows a task to be preempted upon exit from an ISR. More...

Files
file	irq-extension.h
	This header file is provided for backward compatiblility.

Data Structures
struct	rtems_interrupt_entry
	This structure represents an interrupt entry. More...
struct	rtems_interrupt_attributes
	This structure provides the attributes of an interrupt vector. More...
struct	rtems_interrupt_server_control
	This structure represents an interrupt server. More...
struct	rtems_interrupt_server_config
	This structure defines an interrupt server configuration. More...
struct	rtems_interrupt_server_action
	This structure represents an interrupt server action. More...
struct	rtems_interrupt_server_entry
	This structure represents an interrupt server entry. More...
struct	rtems_interrupt_server_request
	This structure represents an interrupt server request. More...

Macros
#define	rtems_interrupt_disable(_isr_cookie)   _ISR_Local_disable( _isr_cookie )
	Disables the maskable interrupts on the current processor.
#define	rtems_interrupt_enable(_isr_cookie)   _ISR_Local_enable( _isr_cookie )
	Restores the previous interrupt level on the current processor.
#define	rtems_interrupt_flash(_isr_cookie)   _ISR_Local_flash( _isr_cookie )
	Flashes interrupts on the current processor.
#define	rtems_interrupt_local_disable(_isr_cookie)    _ISR_Local_disable( _isr_cookie )
	Disables the maskable interrupts on the current processor.
#define	rtems_interrupt_local_enable(_isr_cookie)    _ISR_Local_enable( _isr_cookie )
	Restores the previous interrupt level on the current processor.
#define	rtems_interrupt_is_in_progress()   _ISR_Is_in_progress()
	Checks if an ISR is in progress on the current processor.
#define	RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT   ISR_LOCK_NEEDS_OBJECT
	If this define has a non-zero value, then the interrupt lock operations require an object of type rtems_interrupt_lock, otherwise no lock object is required.
#define	rtems_interrupt_lock_initialize(_lock, _name)    _ISR_lock_Initialize( _lock, _name )
	Initializes the ISR lock.
#define	rtems_interrupt_lock_destroy(_lock)   _ISR_lock_Destroy( _lock )
	Destroys the ISR lock.
#define	rtems_interrupt_lock_acquire(_lock, _lock_context)    _ISR_lock_ISR_disable_and_acquire( _lock, _lock_context )
	Acquires the ISR lock.
#define	rtems_interrupt_lock_release(_lock, _lock_context)    _ISR_lock_Release_and_ISR_enable( _lock, _lock_context )
	Releases the ISR lock.
#define	rtems_interrupt_lock_acquire_isr(_lock, _lock_context)    do { (void) _lock_context; } while ( 0 )
	Acquires the ISR lock from within an ISR.
#define	rtems_interrupt_lock_release_isr(_lock, _lock_context)    do { (void) _lock_context; } while ( 0 )
	Releases the ISR lock from within an ISR.
#define	rtems_interrupt_lock_interrupt_disable(_lock_context)    _ISR_lock_ISR_disable( _lock_context )
	Disables maskable interrupts on the current processor.
#define	RTEMS_INTERRUPT_LOCK_DECLARE(_specifier, _designator)
	Declares an ISR lock object.
#define	RTEMS_INTERRUPT_LOCK_DEFINE(_specifier, _designator, _name)
	Defines an ISR lock object.
#define	RTEMS_INTERRUPT_LOCK_INITIALIZER(_name)   0
	Statically initializes an ISR lock object.
#define	RTEMS_INTERRUPT_LOCK_MEMBER(_designator)
	Defines an ISR lock member.
#define	RTEMS_INTERRUPT_LOCK_REFERENCE(_designator, _target)
	Defines an ISR lock object reference.
#define	RTEMS_INTERRUPT_SHARED   ( (rtems_option) 0x00000000 )
	This interrupt handler install option allows that the interrupt handler may share the interrupt vector with other handler.
#define	RTEMS_INTERRUPT_UNIQUE   ( (rtems_option) 0x00000001 )
	This interrupt handler install option ensures that the interrupt handler is unique.
#define	RTEMS_INTERRUPT_REPLACE   ( (rtems_option) 0x00000002 )
	This interrupt handler install option requests that the interrupt handler replaces the first handler with the same argument.
#define	RTEMS_INTERRUPT_ENTRY_INITIALIZER(_routine, _arg, _info)    { _routine, _arg, NULL, _info }
	Statically initializes an interrupt entry object.
#define	RTEMS_INTERRUPT_SERVER_DEFAULT   0
	The constant represents the index of the default interrupt server.

Typedefs
typedef ISR_Vector_number	rtems_vector_number
	This integer type represents interrupt vector numbers.
typedef ISR_Level	rtems_interrupt_level
	This integer type represents interrupt levels.
typedef ISR_Handler	rtems_isr
	This type defines the return type of interrupt service routines.
typedef ISR_Handler_entry	rtems_isr_entry
	Interrupt service routines installed by rtems_interrupt_catch() shall have this type.
typedef char	rtems_interrupt_lock
	This structure represents an ISR lock.
typedef ISR_lock_Context	rtems_interrupt_lock_context
	This structure provides an ISR lock context for acquire and release pairs.
typedef void(*	rtems_interrupt_handler) (void *)
	Interrupt handler routines shall have this type.
typedef void(*	rtems_interrupt_per_handler_routine) (void *, const char *, rtems_option, rtems_interrupt_handler, void *)
	Visitor routines invoked by rtems_interrupt_handler_iterate() shall have this type.
typedef struct rtems_interrupt_entry	rtems_interrupt_entry
	This structure represents an interrupt entry.
typedef struct rtems_interrupt_server_control	rtems_interrupt_server_control
	This structure represents an interrupt server.
typedef struct rtems_interrupt_server_action	rtems_interrupt_server_action
	This structure represents an interrupt server action.

Enumerations
enum	rtems_interrupt_signal_variant {   RTEMS_INTERRUPT_UNSPECIFIED_SIGNAL , RTEMS_INTERRUPT_NO_SIGNAL , RTEMS_INTERRUPT_SIGNAL_LEVEL_LOW , RTEMS_INTERRUPT_SIGNAL_LEVEL_HIGH ,   RTEMS_INTERRUPT_SIGNAL_EDGE_FALLING , RTEMS_INTERRUPT_SIGNAL_EDGE_RAISING }
	This enumeration provides interrupt trigger signal variants. More...

Functions
rtems_status_code	rtems_interrupt_catch (rtems_isr_entry new_isr_handler, rtems_vector_number vector, rtems_isr_entry *old_isr_handler)
	Establishes an interrupt service routine.
rtems_status_code	rtems_interrupt_entry_install (rtems_vector_number vector, rtems_option options, rtems_interrupt_entry *entry)
	Installs the interrupt entry at the interrupt vector.
rtems_status_code	rtems_interrupt_entry_remove (rtems_vector_number vector, rtems_interrupt_entry *entry)
	Removes the interrupt entry from the interrupt vector.
rtems_status_code	rtems_interrupt_handler_install (rtems_vector_number vector, const char *info, rtems_option options, rtems_interrupt_handler routine, void *arg)
	Installs the interrupt handler routine and argument at the interrupt vector.
rtems_status_code	rtems_interrupt_handler_remove (rtems_vector_number vector, rtems_interrupt_handler routine, void *arg)
	Removes the interrupt handler routine and argument from the interrupt vector.
rtems_status_code	rtems_interrupt_vector_is_enabled (rtems_vector_number vector, bool *enabled)
	Checks if the interrupt vector is enabled.
rtems_status_code	rtems_interrupt_vector_enable (rtems_vector_number vector)
	Enables the interrupt vector.
rtems_status_code	rtems_interrupt_vector_disable (rtems_vector_number vector)
	Disables the interrupt vector.
rtems_status_code	rtems_interrupt_is_pending (rtems_vector_number vector, bool *pending)
	Checks if the interrupt is pending.
rtems_status_code	rtems_interrupt_raise (rtems_vector_number vector)
	Raises the interrupt vector.
rtems_status_code	rtems_interrupt_raise_on (rtems_vector_number vector, uint32_t cpu_index)
	Raises the interrupt vector on the processor.
rtems_status_code	rtems_interrupt_clear (rtems_vector_number vector)
	Clears the interrupt vector.
rtems_status_code	rtems_interrupt_get_priority (rtems_vector_number vector, uint32_t *priority)
	Gets the priority of the interrupt vector.
rtems_status_code	rtems_interrupt_set_priority (rtems_vector_number vector, uint32_t priority)
	Sets the priority of the interrupt vector.
rtems_status_code	rtems_interrupt_get_affinity (rtems_vector_number vector, size_t affinity_size, cpu_set_t *affinity)
	Gets the processor affinity set of the interrupt vector.
rtems_status_code	rtems_interrupt_set_affinity (rtems_vector_number vector, size_t affinity_size, const cpu_set_t *affinity)
	Sets the processor affinity set of the interrupt vector.
rtems_status_code	rtems_interrupt_get_attributes (rtems_vector_number vector, rtems_interrupt_attributes *attributes)
	Gets the attributes of the interrupt vector.
rtems_status_code	rtems_interrupt_handler_iterate (rtems_vector_number vector, rtems_interrupt_per_handler_routine routine, void *arg)
	Iterates over all interrupt handler installed at the interrupt vector.
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)
	Initializes the interrupt server tasks.
rtems_status_code	rtems_interrupt_server_create (rtems_interrupt_server_control *control, const rtems_interrupt_server_config *config, uint32_t *server_index)
	Creates an interrupt server.
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 routine, void *arg)
	Installs the interrupt handler routine and argument at the interrupt vector on the interrupt server.
rtems_status_code	rtems_interrupt_server_handler_remove (uint32_t server_index, rtems_vector_number vector, rtems_interrupt_handler routine, void *arg)
	Removes the interrupt handler routine and argument from the interrupt vector and the interrupt server.
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)
	Sets the processor affinity of the interrupt server.
rtems_status_code	rtems_interrupt_server_delete (uint32_t server_index)
	Deletes the interrupt server.
rtems_status_code	rtems_interrupt_server_suspend (uint32_t server_index)
	Suspends the interrupt server.
rtems_status_code	rtems_interrupt_server_resume (uint32_t server_index)
	Resumes the interrupt server.
rtems_status_code	rtems_interrupt_server_move (uint32_t source_server_index, rtems_vector_number vector, uint32_t destination_server_index)
	Moves the interrupt handlers installed at the interrupt vector and the source interrupt server to the destination interrupt server.
rtems_status_code	rtems_interrupt_server_handler_iterate (uint32_t server_index, rtems_vector_number vector, rtems_interrupt_per_handler_routine routine, void *arg)
	Iterates over all interrupt handler installed at the interrupt vector and interrupt server.
rtems_status_code	rtems_interrupt_server_entry_initialize (uint32_t server_index, rtems_interrupt_server_entry *entry)
	Initializes the interrupt server entry.
void	rtems_interrupt_server_action_prepend (rtems_interrupt_server_entry *entry, rtems_interrupt_server_action *action, rtems_interrupt_handler routine, void *arg)
	Prepends the interrupt server action to the list of actions of the interrupt server entry.
void	rtems_interrupt_server_entry_destroy (rtems_interrupt_server_entry *entry)
	Destroys the interrupt server entry.
void	rtems_interrupt_server_entry_submit (rtems_interrupt_server_entry *entry)
	Submits the interrupt server entry to be serviced by the interrupt server.
rtems_status_code	rtems_interrupt_server_entry_move (rtems_interrupt_server_entry *entry, uint32_t server_index)
	Moves the interrupt server entry to the interrupt server.
rtems_status_code	rtems_interrupt_server_request_initialize (uint32_t server_index, rtems_interrupt_server_request *request, rtems_interrupt_handler routine, void *arg)
	Initializes the interrupt server request.

Detailed Description

Any real-time executive must provide a mechanism for quick response to externally generated interrupts to satisfy the critical time constraints of the application. The Interrupt Manager provides this mechanism for RTEMS. This manager permits quick interrupt response times by providing the critical ability to alter task execution which allows a task to be preempted upon exit from an ISR.

Macro Definition Documentation

rtems_interrupt_disable

#define rtems_interrupt_disable

(

_isr_cookie

)

_ISR_Local_disable( _isr_cookie )

Disables the maskable interrupts on the current processor.

Parameters

[out]

_isr_cookie

is a variable of type rtems_interrupt_level which will be used to save the previous interrupt level.

This directive disables all maskable interrupts on the current processor and returns the previous interrupt level in _isr_cookie.

Notes

A later invocation of the rtems_interrupt_enable() directive should be used to restore the previous interrupt level.

This directive is implemented as a macro which sets the _isr_cookie parameter.

#include <rtems.h>
 
void local_critical_section( void )
{
  rtems_interrupt_level level;
 
  // Please note that the rtems_interrupt_disable() is a macro.  The
  // previous interrupt level (before the maskable interrupts are
  // disabled) is returned here in the level macro parameter.  This
  // would be wrong:
  //
  // rtems_interrupt_disable( &level );
  rtems_interrupt_disable( level );
 
  // Here is the critical section: maskable interrupts are disabled
 
  {
    rtems_interrupt_level nested_level;
 
    rtems_interrupt_disable( nested_level );
 
    // Here is a nested critical section
 
    rtems_interrupt_enable( nested_level );
  }
 
  // Maskable interrupts are still disabled
 
  rtems_interrupt_enable( level );
}

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• Where the system was built with SMP support enabled, the directive is not available. Its use will result in compiler warnings and linker errors. The rtems_interrupt_local_disable() and rtems_interrupt_local_enable() directives are available in all build configurations.

rtems_interrupt_enable

#define rtems_interrupt_enable

(

_isr_cookie

)

_ISR_Local_enable( _isr_cookie )

Restores the previous interrupt level on the current processor.

Parameters

[in]

_isr_cookie

is the previous interrupt level to restore. The value must be obtained by a previous call to rtems_interrupt_disable() or rtems_interrupt_flash().

This directive restores the interrupt level specified by _isr_cookie on the current processor.

Notes

The _isr_cookie parameter value must be obtained by a previous call to rtems_interrupt_disable() or rtems_interrupt_flash(). Using an otherwise obtained value is undefined behaviour.

This directive is unsuitable to enable particular interrupt sources, for example in an interrupt controller.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• While at least one maskable interrupt is pending, when the directive enables maskable interrupts, the pending interrupts are immediately serviced. The interrupt service routines may unblock higher priority tasks which may preempt the calling task.
• Where the system was built with SMP support enabled, the directive is not available. Its use will result in compiler warnings and linker errors. The rtems_interrupt_local_disable() and rtems_interrupt_local_enable() directives are available in all build configurations.

RTEMS_INTERRUPT_ENTRY_INITIALIZER

#define RTEMS_INTERRUPT_ENTRY_INITIALIZER	(		_routine,
			_arg,
			_info
	)		{ _routine, _arg, NULL, _info }

Statically initializes an interrupt entry object.

Parameters

_routine	is the interrupt handler routine for the entry.
_arg	is the interrupt handler argument for the entry.
_info	is the descriptive information for the entry.

Notes

Alternatively, rtems_interrupt_entry_initialize() may be used to dynamically initialize an interrupt entry.

rtems_interrupt_flash

#define rtems_interrupt_flash

(

_isr_cookie

)

_ISR_Local_flash( _isr_cookie )

Flashes interrupts on the current processor.

Parameters

[in,out]

_isr_cookie

is the previous interrupt level.

This directive is functionally equivalent to a calling rtems_interrupt_enable() immediately followed by a rtems_interrupt_disable(). On some architectures it is possible to provide an optimized implementation for this sequence.

Notes

The _isr_cookie parameter value must be obtained by a previous call to rtems_interrupt_disable() or rtems_interrupt_flash(). Using an otherwise obtained value is undefined behaviour.

Historically, the interrupt flash directive was heavily used in the operating system implementation. However, this is no longer the case. The interrupt flash directive is provided for backward compatibility reasons.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• Where the system was built with SMP support enabled, the directive is not available. Its use will result in compiler warnings and linker errors. The rtems_interrupt_local_disable() and rtems_interrupt_local_enable() directives are available in all build configurations.

rtems_interrupt_is_in_progress

bool rtems_interrupt_is_in_progress

(

void

)

_ISR_Is_in_progress()

Checks if an ISR is in progress on the current processor.

This directive returns true, if the current processor is currently servicing an interrupt, and false otherwise. A return value of true indicates that the caller is an interrupt service routine, not a task. The directives available to an interrupt service routine are restricted.

Returns

Returns true, if the current processor is currently servicing an interrupt, otherwise false.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

rtems_interrupt_local_disable

#define rtems_interrupt_local_disable

(

_isr_cookie

)

_ISR_Local_disable( _isr_cookie )

Disables the maskable interrupts on the current processor.

Parameters

[out]

_isr_cookie

is a variable of type rtems_interrupt_level which will be used to save the previous interrupt level.

This directive disables all maskable interrupts on the current processor and returns the previous interrupt level in _isr_cookie.

Notes

A later invocation of the rtems_interrupt_local_enable() directive should be used to restore the previous interrupt level.

This directive is implemented as a macro which sets the _isr_cookie parameter.

Where the system was built with SMP support enabled, this will not ensure system wide mutual exclusion. Use interrupt locks instead, see rtems_interrupt_lock_acquire(). Interrupt disabled critical sections may be used to access processor-specific data structures or disable thread dispatching.

#include <rtems.h>
 
void local_critical_section( void )
{
  rtems_interrupt_level level;
 
  // Please note that the rtems_interrupt_local_disable() is a macro.
  // The previous interrupt level (before the maskable interrupts are
  // disabled) is returned here in the level macro parameter.  This would
  // be wrong:
  //
  // rtems_interrupt_local_disable( &level );
  rtems_interrupt_local_disable( level );
 
  // Here is the critical section: maskable interrupts are disabled
 
  {
    rtems_interrupt_level nested_level;
 
    rtems_interrupt_local_disable( nested_level );
 
    // Here is a nested critical section
 
    rtems_interrupt_local_enable( nested_level );
  }
 
  // Maskable interrupts are still disabled
 
  rtems_interrupt_local_enable( level );
}

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

rtems_interrupt_local_enable

#define rtems_interrupt_local_enable

(

_isr_cookie

)

_ISR_Local_enable( _isr_cookie )

Restores the previous interrupt level on the current processor.

Parameters

[in]

_isr_cookie

is the previous interrupt level to restore. The value must be obtained by a previous call to rtems_interrupt_local_disable().

This directive restores the interrupt level specified by _isr_cookie on the current processor.

Notes

The _isr_cookie parameter value must be obtained by a previous call to rtems_interrupt_local_disable(). Using an otherwise obtained value is undefined behaviour.

This directive is unsuitable to enable particular interrupt sources, for example in an interrupt controller.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• While at least one maskable interrupt is pending, when the directive enables maskable interrupts, the pending interrupts are immediately serviced. The interrupt service routines may unblock higher priority tasks which may preempt the calling task.

rtems_interrupt_lock_acquire

#define rtems_interrupt_lock_acquire	(		_lock,
			_lock_context
	)		_ISR_lock_ISR_disable_and_acquire( _lock, _lock_context )

Acquires the ISR lock.

Parameters

[in,out]	_lock	is the ISR lock to acquire.
[out]	_lock_context	is the ISR lock context. This lock context shall be used to release the lock by calling rtems_interrupt_lock_release().

This directive acquires the ISR lock specified by _lock using the lock context provided by _lock_context. Maskable interrupts will be disabled on the current processor.

Notes

A caller-specific lock context shall be provided for each acquire/release pair, for example an automatic variable.

Where the system was built with SMP support enabled, this directive acquires an SMP lock. An attempt to recursively acquire the lock may result in an infinite loop with maskable interrupts disabled.

This directive establishes a non-preemptive critical section with system wide mutual exclusion on the local node in all RTEMS build configurations.

#include <rtems.h>
 
void critical_section( rtems_interrupt_lock *lock )
{
  rtems_interrupt_lock_context lock_context;
 
  rtems_interrupt_lock_acquire( lock, &lock_context );
 
  // Here is the critical section.  Maskable interrupts are disabled.
  // Where the system was built with SMP support enabled, this section
  // is protected by an SMP lock.
 
  rtems_interrupt_lock_release( lock, &lock_context );
}

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

rtems_interrupt_lock_acquire_isr

#define rtems_interrupt_lock_acquire_isr	(		_lock,
			_lock_context
	)		do { (void) _lock_context; } while ( 0 )

Acquires the ISR lock from within an ISR.

Parameters

[in,out]	_lock	is the ISR lock to acquire within an ISR.
[out]	_lock_context	is the ISR lock context. This lock context shall be used to release the lock by calling rtems_interrupt_lock_release_isr().

This directive acquires the ISR lock specified by _lock using the lock context provided by _lock_context. The interrupt level will remain unchanged.

Notes

A caller-specific lock context shall be provided for each acquire/release pair, for example an automatic variable.

Where the system was built with SMP support enabled, this directive acquires an SMP lock. An attempt to recursively acquire the lock may result in an infinite loop.

This directive is intended for device drivers and should be called from the corresponding interrupt service routine.

In case the corresponding interrupt service routine can be interrupted by higher priority interrupts and these interrupts enter the critical section protected by this lock, then the result is unpredictable. This directive may be used under specific circumstances as an optimization. In doubt, use rtems_interrupt_lock_acquire() and rtems_interrupt_lock_release().

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

RTEMS_INTERRUPT_LOCK_DECLARE

#define RTEMS_INTERRUPT_LOCK_DECLARE	(		_specifier,
			_designator
	)

Declares an ISR lock object.

Parameters

_specifier	is the storage-class specifier for the ISR lock to declare, for example extern or static.
_designator	is the ISR lock object designator.

Notes

Do not add a ";" after this macro.

RTEMS_INTERRUPT_LOCK_DEFINE

#define RTEMS_INTERRUPT_LOCK_DEFINE	(		_specifier,
			_designator,
			_name
	)

Defines an ISR lock object.

Parameters

_specifier	is the storage-class specifier for the ISR lock to declare, for example extern or static.
_designator	is the ISR lock object designator.
_name	is the ISR lock name. It shall be a string. The name is only used where the system was built with profiling support enabled.

Notes

Do not add a ";" after this macro.

ISR locks may also be dynamically initialized by rtems_interrupt_lock_initialize() or statically by RTEMS_INTERRUPT_LOCK_INITIALIZER().

rtems_interrupt_lock_destroy

#define rtems_interrupt_lock_destroy

(

_lock

)

_ISR_lock_Destroy( _lock )

Destroys the ISR lock.

Parameters

[in,out]

_lock

is the ISR lock to destroy.

Notes

The lock must have been dynamically initialized by rtems_interrupt_lock_initialize(), statically defined by RTEMS_INTERRUPT_LOCK_DEFINE(), or statically initialized by RTEMS_INTERRUPT_LOCK_INITIALIZER().

Concurrent lock use during the destruction or concurrent destruction leads to unpredictable results.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

rtems_interrupt_lock_initialize

#define rtems_interrupt_lock_initialize	(		_lock,
			_name
	)		_ISR_lock_Initialize( _lock, _name )

Initializes the ISR lock.

Parameters

[out]	_lock	is the ISR lock to initialize.
	_name	is the ISR lock name. It shall be a string. The name is only used where the system was built with profiling support enabled.

Notes

ISR locks may also be statically defined by RTEMS_INTERRUPT_LOCK_DEFINE() or statically initialized by RTEMS_INTERRUPT_LOCK_INITIALIZER().

RTEMS_INTERRUPT_LOCK_INITIALIZER

#define RTEMS_INTERRUPT_LOCK_INITIALIZER

(

_name

)

0

Statically initializes an ISR lock object.

Parameters

_name

is the ISR lock name. It shall be a string. The name is only used where the system was built with profiling support enabled.

Notes

ISR locks may also be dynamically initialized by rtems_interrupt_lock_initialize() or statically defined by RTEMS_INTERRUPT_LOCK_DEFINE().

rtems_interrupt_lock_interrupt_disable

#define rtems_interrupt_lock_interrupt_disable

(

_lock_context

)

_ISR_lock_ISR_disable( _lock_context )

Disables maskable interrupts on the current processor.

Parameters

[out]

_lock_context

is the ISR lock context for an acquire and release pair.

This directive disables maskable interrupts on the current processor and stores the previous interrupt level in _lock_context.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

RTEMS_INTERRUPT_LOCK_MEMBER

#define RTEMS_INTERRUPT_LOCK_MEMBER

(

_designator

)

Defines an ISR lock member.

Parameters

_designator

is the ISR lock member designator.

Notes

Do not add a ";" after this macro.

RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT

#define RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT   ISR_LOCK_NEEDS_OBJECT

If this define has a non-zero value, then the interrupt lock operations require an object of type rtems_interrupt_lock, otherwise no lock object is required.

Notes

This indication can be used to avoid the space overhead for lock objects when they are not needed. In this case, the lock operations will not use a lock objects parameter.

RTEMS_INTERRUPT_LOCK_REFERENCE

#define RTEMS_INTERRUPT_LOCK_REFERENCE	(		_designator,
			_target
	)

Defines an ISR lock object reference.

Parameters

_designator	is the ISR lock reference designator.
_target	is the target object to reference.

Notes

Do not add a ";" after this macro.

rtems_interrupt_lock_release

#define rtems_interrupt_lock_release	(		_lock,
			_lock_context
	)		_ISR_lock_Release_and_ISR_enable( _lock, _lock_context )

Releases the ISR lock.

Parameters

[in,out]	_lock	is the ISR lock to release.
[in,out]	_lock_context	is the ISR lock context. This lock context shall have been used to acquire the lock by calling rtems_interrupt_lock_acquire().

This directive releases the ISR lock specified by _lock using the lock context provided by _lock_context. The previous interrupt level will be restored on the current processor.

Notes

The lock context shall be the one used to acquire the lock, otherwise the result is unpredictable.

Where the system was built with SMP support enabled, this directive releases an SMP lock.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• While at least one maskable interrupt is pending, when the directive enables maskable interrupts, the pending interrupts are immediately serviced. The interrupt service routines may unblock higher priority tasks which may preempt the calling task.

rtems_interrupt_lock_release_isr

#define rtems_interrupt_lock_release_isr	(		_lock,
			_lock_context
	)		do { (void) _lock_context; } while ( 0 )

Releases the ISR lock from within an ISR.

Parameters

[in,out]	_lock	is the ISR lock to release within an ISR.
[in,out]	_lock_context	is the ISR lock context. This lock context shall have been used to acquire the lock by calling rtems_interrupt_lock_acquire_isr().

This directive releases the ISR lock specified by _lock using the lock context provided by _lock_context. The interrupt level will remain unchanged.

Notes

The lock context shall be the one used to acquire the lock, otherwise the result is unpredictable.

Where the system was built with SMP support enabled, this directive releases an SMP lock.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

RTEMS_INTERRUPT_UNIQUE

#define RTEMS_INTERRUPT_UNIQUE   ( (rtems_option) 0x00000001 )

This interrupt handler install option ensures that the interrupt handler is unique.

This option prevents other handler from using the same interrupt vector.

Typedef Documentation

rtems_interrupt_entry

typedef struct rtems_interrupt_entry rtems_interrupt_entry

This structure represents an interrupt entry.

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 may be initialized by RTEMS_INTERRUPT_ENTRY_INITIALIZER() or 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().

Constraints

The following constraints apply to this structure:

• Members of the type shall not be accessed directly by the application.

rtems_interrupt_lock

typedef char rtems_interrupt_lock

This structure represents an ISR lock.

Notes

Lock objects are only needed in some RTEMS build configurations, for example where the SMP support is enabled. The RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT constant can be used to determine whether a lock object is needed or not. This may help to reduce the memory demands of an application. All lock operations do not use the lock object parameter if lock objects are not needed.

#include <rtems.h>
 
#if RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT
rtems_interrupt_lock lock = RTEMS_INTERRUPT_LOCK_INITIALIZER( "name" );
#endif
 
struct s {
#if RTEMS_INTERRUPT_LOCK_NEEDS_OBJECT
  rtems_interrupt_lock lock;
#endif
  int foobar;
};

rtems_interrupt_server_action

typedef struct rtems_interrupt_server_action rtems_interrupt_server_action

This structure represents an interrupt server action.

Notes

This structure shall be treated as an opaque data type from the API point of view. Members shall not be accessed directly.

Constraints

The following constraints apply to this structure:

• Members of the type shall not be accessed directly by the application.

rtems_interrupt_server_control

typedef struct rtems_interrupt_server_control rtems_interrupt_server_control

This structure represents an interrupt server.

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.

Constraints

The following constraints apply to this structure:

• Members of the type shall not be accessed directly by the application.

rtems_isr

typedef ISR_Handler rtems_isr

This type defines the return type of interrupt service routines.

This type can be used to document interrupt service routines in the source code.

Enumeration Type Documentation

rtems_interrupt_signal_variant

enum rtems_interrupt_signal_variant

This enumeration provides interrupt trigger signal variants.

Enumerator
RTEMS_INTERRUPT_UNSPECIFIED_SIGNAL	This interrupt signal variant indicates that the interrupt trigger signal is unspecified.
RTEMS_INTERRUPT_NO_SIGNAL	This interrupt signal variant indicates that the interrupt cannot be triggered by a signal.
RTEMS_INTERRUPT_SIGNAL_LEVEL_LOW	This interrupt signal variant indicates that the interrupt is triggered by a low level signal.
RTEMS_INTERRUPT_SIGNAL_LEVEL_HIGH	This interrupt signal variant indicates that the interrupt is triggered by a high level signal.
RTEMS_INTERRUPT_SIGNAL_EDGE_FALLING	This interrupt signal variant indicates that the interrupt is triggered by a falling edge signal.
RTEMS_INTERRUPT_SIGNAL_EDGE_RAISING	This interrupt signal variant indicates that the interrupt is triggered by a raising edge signal.

Function Documentation

rtems_interrupt_catch()

rtems_status_code rtems_interrupt_catch	(	rtems_isr_entry	new_isr_handler,
		rtems_vector_number	vector,
		rtems_isr_entry *	old_isr_handler
	)

Establishes an interrupt service routine.

Parameters

	new_isr_handler	is the new interrupt service routine.
	vector	is the interrupt vector number.
[out]	old_isr_handler	is the pointer to an rtems_isr_entry object. When the directive call is successful, the previous interrupt service routine established for this interrupt vector will be stored in this object.

This directive establishes an interrupt service routine (ISR) for the interrupt specified by the vector number. The new_isr_handler parameter specifies the entry point of the ISR. The entry point of the previous ISR for the specified vector is returned in old_isr_handler.

To release an interrupt vector, pass the old handler's address obtained when the vector was first capture.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_NUMBER	The interrupt vector number was illegal.
RTEMS_INVALID_ADDRESS	The new_isr_handler parameter was NULL.
RTEMS_INVALID_ADDRESS	The old_isr_handler parameter was NULL.

Constraints

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 directive is only available where the target architecture support enabled simple vectored interrupts.

rtems_interrupt_clear()

rtems_status_code rtems_interrupt_clear

(

rtems_vector_number

vector

)

Clears the interrupt vector.

Parameters

vector

is the number of the interrupt vector to clear.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_UNSATISFIED	The request to raise the interrupt vector has not been satisfied.

Notes

The rtems_interrupt_get_attributes() directive may be used to check if an interrupt vector can be cleared.

Constraints

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.

rtems_interrupt_entry_install()

rtems_status_code rtems_interrupt_entry_install	(	rtems_vector_number	vector,
		rtems_option	options,
		rtems_interrupt_entry *	entry
	)

Installs the interrupt entry at the interrupt vector.

Parameters

vector	is the interrupt vector number.
options	is the interrupt entry install option set.
entry	is the interrupt entry to install.

One of the following mutually exclusive options

• RTEMS_INTERRUPT_UNIQUE, and
• RTEMS_INTERRUPT_SHARED

shall be set in the options parameter.

The handler routine of the entry specified by entry will be called with the handler argument of the entry 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 handlers may be installed for the interrupt vector.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The entry parameter was NULL.
RTEMS_INCORRECT_STATE	The service was not initialized.
RTEMS_INVALID_ADDRESS	The handler routine of the entry was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_CALLED_FROM_ISR	The directive was called from within interrupt context.
RTEMS_INVALID_NUMBER	An option specified by options was not applicable.
RTEMS_RESOURCE_IN_USE	The RTEMS_INTERRUPT_UNIQUE option was set in entry and the interrupt vector was already occupied by a handler.
RTEMS_RESOURCE_IN_USE	The RTEMS_INTERRUPT_SHARED option was set in entry and the interrupt vector was already occupied by a unique handler.
RTEMS_TOO_MANY	The handler routine of the entry specified by entry was already installed for the interrupt vector specified by vector with an argument equal to the handler argument of the entry.

Notes

When the directive call was successful, the ownership of the interrupt entry has been transferred from the caller to the interrupt service. An installed interrupt entry may be removed from the interrupt service by calling rtems_interrupt_entry_remove().

Constraints

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.
• The interrupt entry shall have been initialized by rtems_interrupt_entry_initialize() or RTEMS_INTERRUPT_ENTRY_INITIALIZER().

rtems_interrupt_entry_remove()

rtems_status_code rtems_interrupt_entry_remove	(	rtems_vector_number	vector,
		rtems_interrupt_entry *	entry
	)

Removes the interrupt entry from the interrupt vector.

Parameters

vector	is the interrupt vector number.
entry	is the interrupt entry to remove.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INCORRECT_STATE	The service was not initialized.
RTEMS_INVALID_ADDRESS	The entry parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_CALLED_FROM_ISR	The directive was called from within interrupt context.
RTEMS_UNSATISFIED	The entry specified by entry was not installed at the interrupt vector specified by vector.

Notes

When the directive call was successful, the ownership of the interrupt entry has been transferred from the interrupt service to the caller.

Constraints

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.
• The interrupt entry shall have been installed by rtems_interrupt_entry_install().

rtems_interrupt_get_affinity()

rtems_status_code rtems_interrupt_get_affinity	(	rtems_vector_number	vector,
		size_t	affinity_size,
		cpu_set_t *	affinity
	)

Gets the processor affinity set of the interrupt vector.

Parameters

	vector	is the interrupt vector number.
	affinity_size	is the size of the processor set referenced by affinity in bytes.
[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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The affinity parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
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.

Constraints

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.

rtems_interrupt_get_attributes()

rtems_status_code rtems_interrupt_get_attributes	(	rtems_vector_number	vector,
		rtems_interrupt_attributes *	attributes
	)

Gets the attributes of the interrupt vector.

Parameters

	vector	is the interrupt vector number.
[out]	attributes	is the pointer to an rtems_interrupt_attributes object. When the directive call is successful, the attributes of the interrupt vector will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The attributes parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.

Constraints

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.

rtems_interrupt_get_priority()

rtems_status_code rtems_interrupt_get_priority	(	rtems_vector_number	vector,
		uint32_t *	priority
	)

Gets the priority of the interrupt vector.

Parameters

	vector	is the interrupt vector number.
[out]	priority	is the pointer to an uint32_t object. When the directive call is successful, the priority of the interrupt vector will be stored in this object.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The priority parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_UNSATISFIED	There is no priority associated with the interrupt vector.

Notes

The rtems_interrupt_set_priority() directive may be used to set the priority associated with an interrupt vector.

Constraints

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.

rtems_interrupt_handler_install()

rtems_status_code rtems_interrupt_handler_install	(	rtems_vector_number	vector,
		const char *	info,
		rtems_option	options,
		rtems_interrupt_handler	routine,
		void *	arg
	)

Installs the interrupt handler routine and argument at the interrupt vector.

Parameters

vector	is the interrupt vector number.
info	is the descriptive information of the interrupt handler to install.
options	is the interrupt handler install option set.
routine	is the interrupt handler routine to install.
arg	is the interrupt handler argument to install.

One of the following mutually exclusive options

• RTEMS_INTERRUPT_UNIQUE,
• RTEMS_INTERRUPT_SHARED, and
• RTEMS_INTERRUPT_REPLACE

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.

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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INCORRECT_STATE	The service was not initialized.
RTEMS_INVALID_ADDRESS	The routine parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_CALLED_FROM_ISR	The directive was called from within interrupt context.
RTEMS_NO_MEMORY	There was not enough memory available to allocate data structures to install the handler.
RTEMS_RESOURCE_IN_USE	The RTEMS_INTERRUPT_UNIQUE option was set in options and the interrupt vector was already occupied by a handler.
RTEMS_RESOURCE_IN_USE	The RTEMS_INTERRUPT_SHARED option was set in options and the interrupt vector was already occupied by a unique handler.
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.
RTEMS_UNSATISFIED	The RTEMS_INTERRUPT_REPLACE option was set in options and no handler to replace was installed.

Constraints

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.

rtems_interrupt_handler_iterate()

rtems_status_code rtems_interrupt_handler_iterate	(	rtems_vector_number	vector,
		rtems_interrupt_per_handler_routine	routine,
		void *	arg
	)

Iterates over all interrupt handler installed at the interrupt vector.

Parameters

vector	is the interrupt vector number.
routine	is the visitor routine.
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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INCORRECT_STATE	The service was not initialized.
RTEMS_INVALID_ADDRESS	The routine parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_CALLED_FROM_ISR	The directive was called from within interrupt context.

Notes

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.

Constraints

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.

rtems_interrupt_handler_remove()

rtems_status_code rtems_interrupt_handler_remove	(	rtems_vector_number	vector,
		rtems_interrupt_handler	routine,
		void *	arg
	)

Removes the interrupt handler routine and argument from the interrupt vector.

Parameters

vector	is the interrupt vector number.
routine	is the interrupt handler routine to remove.
arg	is the interrupt handler argument to remove.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INCORRECT_STATE	The service was not initialized.
RTEMS_INVALID_ADDRESS	The routine parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_CALLED_FROM_ISR	The directive was called from within interrupt context.
RTEMS_UNSATISFIED	There was no handler routine and argument pair installed specified by routine and arg.

Constraints

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.

rtems_interrupt_is_pending()

rtems_status_code rtems_interrupt_is_pending	(	rtems_vector_number	vector,
		bool *	pending
	)

Checks if the interrupt is pending.

Parameters

	vector	is the interrupt vector number.
[out]	pending	is the pointer to a bool object. When the directive call is successful, the pending status of the interrupt associated with the interrupt vector specified by vector will be stored in this object. When the interrupt was pending for the processor executing the directive call at some time point during the call, the object value will be set to true, otherwise to false.

The directive checks if the interrupt associated with the interrupt vector specified by vector was pending for the processor executing the directive call at some time point during the call.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The pending parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_UNSATISFIED	The request to get the pending status has not been satisfied.

Notes

Interrupts may be made pending by calling the rtems_interrupt_raise() or rtems_interrupt_raise_on() directives or due to external signals or messages. The pending state may be cleared by rtems_interrupt_clear().

Constraints

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.

rtems_interrupt_raise()

rtems_status_code rtems_interrupt_raise

(

rtems_vector_number

vector

)

Raises the interrupt vector.

Parameters

vector

is the number of the interrupt vector to raise.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_UNSATISFIED	The request to raise the interrupt vector has not been satisfied.

Notes

The rtems_interrupt_get_attributes() directive may be used to check if an interrupt vector can be raised.

Constraints

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.

rtems_interrupt_raise_on()

rtems_status_code rtems_interrupt_raise_on	(	rtems_vector_number	vector,
		uint32_t	cpu_index
	)

Raises the interrupt vector on the processor.

Parameters

vector	is the number of the interrupt vector to raise.
cpu_index	is the index of the target processor of the interrupt vector to raise.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_NOT_CONFIGURED	The processor specified by cpu_index was not configured to be used by the application.
RTEMS_INCORRECT_STATE	The processor specified by cpu_index was configured to be used by the application, however, it was not online.
RTEMS_UNSATISFIED	The request to raise the interrupt vector has not been satisfied.

Notes

The rtems_interrupt_get_attributes() directive may be used to check if an interrupt vector can be raised on a processor.

Constraints

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.

rtems_interrupt_server_action_prepend()

void rtems_interrupt_server_action_prepend	(	rtems_interrupt_server_entry *	entry,
		rtems_interrupt_server_action *	action,
		rtems_interrupt_handler	routine,
		void *	arg
	)

Prepends the interrupt server action to the list of actions of the interrupt server entry.

Parameters

[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().
[out]	action	is the interrupt server action to initialize and prepend to the list of actions of the entry.
	routine	is the interrupt handler routine to set in the action.
	arg	is the interrupt handler argument to set in the action.

Notes

No error checking is performed by the directive.

Constraints

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.

rtems_interrupt_server_create()

rtems_status_code rtems_interrupt_server_create	(	rtems_interrupt_server_control *	control,
		const rtems_interrupt_server_config *	config,
		uint32_t *	server_index
	)

Creates an interrupt server.

Parameters

[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.
	config	is the interrupt server configuration.
[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.

Return values

RTEMS_SUCCESSFUL

The requested operation was successful.

Returns

The directive uses rtems_task_create(). If this directive fails, then its error status will be returned.

Notes

See also rtems_interrupt_server_initialize() and rtems_interrupt_server_delete().

Constraints

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.

rtems_interrupt_server_delete()

rtems_status_code rtems_interrupt_server_delete

(

uint32_t

server_index

)

Deletes the interrupt server.

Parameters

server_index

is the index of the interrupt server to delete.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the server index specified by server_index.

Notes

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().

Constraints

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.

rtems_interrupt_server_entry_destroy()

void rtems_interrupt_server_entry_destroy

(

rtems_interrupt_server_entry *

entry

)

Destroys the interrupt server entry.

Parameters

[in,out]

entry

is the interrupt server entry to destroy.

Notes

No error checking is performed by the directive.

Constraints

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().

rtems_interrupt_server_entry_initialize()

rtems_status_code rtems_interrupt_server_entry_initialize	(	uint32_t	server_index,
		rtems_interrupt_server_entry *	entry
	)

Initializes the interrupt server entry.

Parameters

server_index	is the interrupt server index. The constant RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default interrupt server.
entry	is the interrupt server entry to initialize.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.

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().

Constraints

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.

rtems_interrupt_server_entry_move()

rtems_status_code rtems_interrupt_server_entry_move	(	rtems_interrupt_server_entry *	entry,
		uint32_t	server_index
	)

Moves the interrupt server entry to the interrupt server.

Parameters

entry	is the interrupt server entry to move.
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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.

Constraints

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.
• 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.

rtems_interrupt_server_entry_submit()

void rtems_interrupt_server_entry_submit

(

rtems_interrupt_server_entry *

entry

)

Submits the interrupt server entry to be serviced by the interrupt server.

Parameters

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.

Notes

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().

Constraints

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 unblock a task. 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.

rtems_interrupt_server_handler_install()

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	routine,
		void *	arg
	)

Installs the interrupt handler routine and argument at the interrupt vector on the interrupt server.

Parameters

server_index	is the interrupt server index. The constant RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default interrupt server.
vector	is the interrupt vector number.
info	is the descriptive information of the interrupt handler to install.
options	is the interrupt handler install option set.
routine	is the interrupt handler routine to install.
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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.
RTEMS_CALLED_FROM_ISR	The directive was called from within interrupt context.
RTEMS_INVALID_ADDRESS	The routine parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_INVALID_NUMBER	An option specified by info was not applicable.
RTEMS_RESOURCE_IN_USE	The RTEMS_INTERRUPT_UNIQUE option was set in info and the interrupt vector was already occupied by a handler.
RTEMS_RESOURCE_IN_USE	The RTEMS_INTERRUPT_SHARED option was set in info and the interrupt vector was already occupied by a unique handler.
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.
RTEMS_UNSATISFIED	The RTEMS_INTERRUPT_REPLACE option was set in info and no handler to replace was installed.

Notes

See also rtems_interrupt_handler_install().

Constraints

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.

rtems_interrupt_server_handler_iterate()

rtems_status_code rtems_interrupt_server_handler_iterate	(	uint32_t	server_index,
		rtems_vector_number	vector,
		rtems_interrupt_per_handler_routine	routine,
		void *	arg
	)

Iterates over all interrupt handler installed at the interrupt vector and interrupt server.

Parameters

server_index	is the index of the interrupt server.
vector	is the interrupt vector number.
routine	is the visitor routine.
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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.

Notes

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.

Constraints

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.

rtems_interrupt_server_handler_remove()

rtems_status_code rtems_interrupt_server_handler_remove	(	uint32_t	server_index,
		rtems_vector_number	vector,
		rtems_interrupt_handler	routine,
		void *	arg
	)

Removes the interrupt handler routine and argument from the interrupt vector and the interrupt server.

Parameters

server_index	is the interrupt server index. The constant RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default interrupt server.
vector	is the interrupt vector number.
routine	is the interrupt handler routine to remove.
arg	is the interrupt handler argument to remove.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_UNSATISFIED	There was no handler routine and argument pair installed specified by routine and arg.

Constraints

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.

rtems_interrupt_server_initialize()

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
	)

Initializes the interrupt server tasks.

Parameters

	priority	is the initial task priority of the created interrupt servers.
	stack_size	is the task stack size of the created interrupt servers.
	modes	is the initial mode set of the created interrupt servers.
	attributes	is the attribute set of the created interrupt servers.
[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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INCORRECT_STATE	The interrupt servers were already initialized.

Returns

The directive uses rtems_task_create(). If this directive fails, then its error status will be returned.

Notes

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.

Interrupt servers may be deleted by rtems_interrupt_server_delete().

Constraints

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.

rtems_interrupt_server_move()

rtems_status_code rtems_interrupt_server_move	(	uint32_t	source_server_index,
		rtems_vector_number	vector,
		uint32_t	destination_server_index
	)

Moves the interrupt handlers installed at the interrupt vector and the source interrupt server to the destination interrupt server.

Parameters

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.
vector	is the interrupt vector number.
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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by source_server_index.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by destination_server_index.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.

Constraints

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.

rtems_interrupt_server_request_initialize()

rtems_status_code rtems_interrupt_server_request_initialize	(	uint32_t	server_index,
		rtems_interrupt_server_request *	request,
		rtems_interrupt_handler	routine,
		void *	arg
	)

Initializes the interrupt server request.

Parameters

	server_index	is the interrupt server index. The constant RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default interrupt server.
[out]	request	is the interrupt server request to initialize.
	routine	is the interrupt handler routine for the request action.
	arg	is the interrupt handler argument for the request action.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.

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().

Constraints

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.

rtems_interrupt_server_resume()

rtems_status_code rtems_interrupt_server_resume

(

uint32_t

server_index

)

Resumes the interrupt server.

Parameters

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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.

Notes

Interrupt server may be suspended by rtems_interrupt_server_suspend().

Constraints

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.

rtems_interrupt_server_set_affinity()

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
	)

Sets the processor affinity of the interrupt server.

Parameters

server_index	is the interrupt server index. The constant RTEMS_INTERRUPT_SERVER_DEFAULT may be used to specify the default interrupt server.
affinity_size	is the size of the processor set referenced by affinity in bytes.
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.
priority	is the new real priority for the interrupt server.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.

Returns

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.

Notes

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().

Constraints

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.

rtems_interrupt_server_suspend()

rtems_status_code rtems_interrupt_server_suspend

(

uint32_t

server_index

)

Suspends the interrupt server.

Parameters

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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt server associated with the index specified by server_index.

Notes

Interrupt server may be resumed by rtems_interrupt_server_resume().

Constraints

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.

rtems_interrupt_set_affinity()

rtems_status_code rtems_interrupt_set_affinity	(	rtems_vector_number	vector,
		size_t	affinity_size,
		const cpu_set_t *	affinity
	)

Sets the processor affinity set of the interrupt vector.

Parameters

vector	is the interrupt vector number.
affinity_size	is the size of the processor set referenced by affinity in bytes.
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.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The affinity parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_INVALID_NUMBER	The referenced processor set was not a valid new processor affinity set for the interrupt vector.
RTEMS_UNSATISFIED	The request to set the processor affinity of the interrupt vector has not been satisfied.

Notes

The rtems_interrupt_get_attributes() directive may be used to check if the processor affinity of an interrupt vector can be set.

Only online processors of the affinity set specified by affinity_size and affinity are considered by the directive. Other processors of the set are ignored. If the set contains no online processor, then the set is invalid and an error status is returned.

Constraints

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.

rtems_interrupt_set_priority()

rtems_status_code rtems_interrupt_set_priority	(	rtems_vector_number	vector,
		uint32_t	priority
	)

Sets the priority of the interrupt vector.

Parameters

vector	is the interrupt vector number.
priority	is the new priority for the interrupt vector.

This directive sets the priority of the interrupt specified by vector to the priority specified by priority.

For processor-specific interrupts, the priority of the interrupt specific to a processor executing the directive call will be set.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_INVALID_PRIORITY	The priority specified by priority was not a valid new priority for the interrupt vector.
RTEMS_UNSATISFIED	The request to set the priority of the interrupt vector has not been satisfied.

Notes

The rtems_interrupt_get_priority() directive may be used to get the priority associated with an interrupt vector.

The interrupt prioritization support depends on the interrupt controller of the target. It is strongly recommended to read the relevant hardware documentation. What happens when the priority of a pending or active interrupt is changed, depends on the interrupt controller. In general, you should set the interrupt priority of an interrupt vector before a handler is installed. On some interrupt controllers, setting the priority to the maximum value (lowest importance) effectively disables the interrupt.

On some architectures, a range of interrupt priority values may be not disabled by the interrupt disable directives such as rtems_interrupt_disable() and rtems_interrupt_local_disable(). These interrupts are called non-maskable interrupts. Handlers of non-maskable interrupts shall not use operating system services. In addition, non-maskable interrupts may be not installable through rtems_interrupt_entry_install() or rtems_interrupt_handler_install(), and may require architecture-specific prologue and epilogue code.

The interrupt priority settings affect the maximum nesting depth while servicing interrupts. The interrupt stack size calculation needs to take this into account, see also CONFIGURE_INTERRUPT_STACK_SIZE.

For the ARM Generic Interrupt Controller (GIC), an 8-bit priority value is supported. The granularity of the priority levels depends on the interrupt controller configuration. Some low-order bits of a priority value may be read-as-zero (RAZ) and writes are ignored (WI). Where group 0 (FIQ) and group 1 (IRQ) interrupts are used, it is recommended to use the lower half of the supported priority value range for the group 0 interrupts and the upper half for group 1 interrupts. This ensures that group 1 interrupts cannot preempt group 0 interrupts.

For the Armv7-M Nested Vector Interrupt Controller (NVIC), an 8-bit priority value is supported. The granularity of the priority levels depends on the interrupt controller configuration. Some lower bits of a priority value may be read-as-zero (RAZ) and writes are ignored (WI). Interrupts with a priority value less than 128 are not disabled by the RTEMS interrupt disable directives. Handlers of such interrupts shall not use operating system services.

For the RISC-V Platform-Level Interrupt Controller (PLIC), all priority values from 0 up to and including the 0xffffffff are supported since the priority for the PLIC is defined by a write-any-read-legal (WARL) register. Please note that for this directive in contrast to the PLIC, a higher priority value is associated with a lower importance. The maximum priority value (mapped to the value 0 for the PLIC) is reserved to mean "never interrupt" and effectively disables the interrupt.

For the QorIQ Multicore Programmable Interrupt Controller (MPIC), a 4-bit priority value is supported. Please note that for this directive in contrast to the MPIC, a higher priority value is associated with a lower importance. The maximum priority value of 15 (mapped to the value 0 for the MPIC) inhibits signalling of this interrupt.

Consult the RTEMS CPU Architecture Supplement and the BSP documentation in the RTEMS User Manual for further information.

Constraints

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.

rtems_interrupt_vector_disable()

rtems_status_code rtems_interrupt_vector_disable

(

rtems_vector_number

vector

)

Disables the interrupt vector.

Parameters

vector

is the number of the interrupt vector to disable.

The directive disables the interrupt vector specified by vector. This prevents that an interrupt service request is issued to the target processors of the interrupt vector.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_UNSATISFIED	The request to disable the interrupt vector has not been satisfied.

Notes

The rtems_interrupt_get_attributes() directive may be used to check if an interrupt vector can be disabled. Interrupt vectors may be enabled by rtems_interrupt_vector_enable(). There may be targets on which some interrupt vectors cannot be disabled, for example a hardware watchdog interrupt or software generated interrupts.

Constraints

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.

rtems_interrupt_vector_enable()

rtems_status_code rtems_interrupt_vector_enable

(

rtems_vector_number

vector

)

Enables the interrupt vector.

Parameters

vector

is the number of the interrupt vector to enable.

The directive enables the interrupt vector specified by vector. This allows that interrupt service requests are issued to the target processors of the interrupt vector. Interrupt service requests for an interrupt vector may be raised by rtems_interrupt_raise(), rtems_interrupt_raise_on(), external signals, or messages.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.
RTEMS_UNSATISFIED	The request to enable the interrupt vector has not been satisfied.

Notes

The rtems_interrupt_get_attributes() directive may be used to check if an interrupt vector can be enabled. Interrupt vectors may be disabled by rtems_interrupt_vector_disable().

Constraints

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.

rtems_interrupt_vector_is_enabled()

rtems_status_code rtems_interrupt_vector_is_enabled	(	rtems_vector_number	vector,
		bool *	enabled
	)

Checks if the interrupt vector is enabled.

Parameters

	vector	is the interrupt vector number.
[out]	enabled	is the pointer to a bool object. When the directive call is successful, the enabled status of the interrupt associated with the interrupt vector specified by vector will be stored in this object. When the interrupt was enabled for the processor executing the directive call at some time point during the call, the object value will be set to true, otherwise to false.

The directive checks if the interrupt associated with the interrupt vector specified by vector was enabled for the processor executing the directive call at some time point during the call.

Return values

RTEMS_SUCCESSFUL	The requested operation was successful.
RTEMS_INVALID_ADDRESS	The enabled parameter was NULL.
RTEMS_INVALID_ID	There was no interrupt vector associated with the number specified by vector.

Notes

Interrupt vectors may be enabled by rtems_interrupt_vector_enable() and disabled by rtems_interrupt_vector_disable().

Constraints

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.