SPINLOCK

The Spinlock driver provides API to program the Spinlock module to synchronize processes running on multiple processors in the device.

Features Supported

  • 256 spinlocks

  • Lock and unlock API

SysConfig Features

It is strongly recommend to use SysConfig where it is available instead of using direct SW API calls. This will help simplify the SW application and also catch common mistakes early in the development cycle.

  • Not applicable/supported

Features NOT Supported

NA

Important Usage Guidelines

  • The Spinlock driver doesn’t enforce below limitation as defined in device manual. It is the responsibility of the application to take care of below recommendations

  • Spinlock is appropriate for mutual exclusion for access to a shared data structure. It should be used only when:

    • The time to hold the lock is predictable and small (for example, a maximum hold time of less than 200 CPU cycles may be acceptable).

    • The locking task cannot be preempted, suspended, or interrupted while holding the lock (this would make the hold time large and unpredictable).

    • The lock is lightly contended, that is the chance of any other process (or processor) trying to acquire the lock while it is held is small.

Example Usage

Include the below file to access the APIs

#include <drivers/spinlock.h>

Lock API

    int32_t  status;

    /* Spin till lock is acquired */
    while(1U)
    {
        status = Spinlock_lock(spinlockBaseAddr, lockNum);
        if(status == SPINLOCK_LOCK_STATUS_FREE)
        {
            break;  /* Free and taken */
        }
    }

    /*
     * enter critical section
     */

Unlock API

    Spinlock_unlock(spinlockBaseAddr, lockNum);

API

group APIs for SPINLOCK

This module contains APIs to program and use the SPINLOCK module.

Defines

SPINLOCK_LOCK_STATUS_FREE

Flag to indicate spinlock is free.

SPINLOCK_LOCK_STATUS_INUSE

Flag to indicate spinlock is in use.

Functions

uint32_t Spinlock_getNumLocks(uint32_t baseAddr)

This API provides returns the number of locks supported.

Parameters:

baseAddr – Memory address of SPINLOCK module

Returns:

Number of locks in an instance

int32_t Spinlock_lock(uint32_t baseAddr, uint32_t lockNumber)

This API performs the Read operation for Lock status of the SPINLOCK_LOCK_REG, in order to acquire a Spinlock.

Parameters:

  • baseAddr – Memory address of SPINLOCK module

  • lockNumber – Lock number in Spinlock module that should be acquired

Returns:

Status of the Lock Register Lock state : SPINLOCK_LOCK_STATUS_FREE: Lock was previously NOT Taken (Free). The requester is granted the lock SPINLOCK_LOCK_STATUS_INUSE: Lock was previously Taken (Not Free). The requester is not granted the lock and must retry SystemP_FAILURE: lockNumber is invalid (out of range)

void Spinlock_unlock(uint32_t baseAddr, uint32_t lockNumber)

This API performs the write operation for Lock status of the SPINLOCK_LOCK_REG, in order to Free the lock If lockNumber is invalid (out of range), no operation is performed Lock state : Write 0x0: Set the lock to Not Taken(Free) Write 0x1: No update to the lock value.

Parameters:

  • baseAddr – Memory address of SPINLOCK module

  • lockNumber – Lock number in Spinlock module that should be released

void Spinlock_moduleReset(uint32_t baseAddr)

This API performs the module reset of the Spinlock module. It also waits until the reset process is complete.

.

Parameters:

baseAddr – Memory address of SPINLOCK module.