SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Acquires the ISR lock from within an ISR.
copyrights:
- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
  default: do { (void) ${.:/params[1]/name}; } while ( 0 )
  variants:
  - definition: |
      ${/score/smp/if/lock-acquire:/name}(
        &( ${.:/params[0]/name} )->Lock,
        &( ${.:/params[1]/name} )->Lock_context
      )
    enabled-by: defined(${/build-options/if/smp:/name})
description: |
  This directive acquires the ISR lock specified by ${.:/params[0]/name} using
  the lock context provided by ${.:/params[1]/name}.  The interrupt level will
  remain unchanged.
enabled-by: true
index-entries: []
interface-type: macro
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
- role: constraint
  uid: /constraint/directive-ctx-any
- role: constraint
  uid: /constraint/directive-no-preempt
name: rtems_interrupt_lock_acquire_isr
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
  ${lock-acquire:/name} and ${lock-release:/name}.
params:
- description: |
    is the ISR lock to acquire within an ISR.
  dir: inout
  name: _lock
- description: |
    is the ISR lock context.  This lock context shall be used to release the
    lock by calling ${lock-release-isr:/name}.
  dir: out
  name: _lock_context
return: null
type: interface