Hardware spinlock framework

서로 다른 processor와 OS 사이의 hardware lock

Hardware spinlock module은 heterogeneous processor 사이, 특히 하나의 공유 operating system 아래에서 실행되지 않는 processor 사이에서 synchronization과 mutual exclusion을 hardware로 지원한다.

예를 들어 OMAP4에는 Cortex-A9 두 개, Cortex-M3 두 개, C64x+ DSP가 함께 들어 있다. Master인 A9에서는 보통 Linux가 실행되고 slave processor인 M3와 DSP에서는 각각 RTOS 계열 operating system이 실행된다. 서로 다른 OS scheduler와 software lock domain을 사용하므로 Linux의 일반 spinlock만으로는 모든 core를 직렬화할 수 없다.

Generic hwspinlock framework를 사용하면 platform-independent driver가 hwspinlock device를 통해 remote processor와 공유하는 data structure에 접근할 수 있다. 별도의 synchronization 수단이 없는 processor들 사이에서도 이 framework가 mutual exclusion을 제공하므로 driver를 특정 SoC 구현에 묶지 않을 수 있다.

대표적인 사용처는 inter-processor communication이다. OMAP4에서는 host가 CPU 사용량이 많은 multimedia task를 Syslink라는 IPC subsystem을 통해 remote M3 또는 C64x+ slave processor로 넘긴다. 빠른 message 기반 통신을 위해서는 remote processor에서 도착한 message를 적절한 user process로 전달하는 최소한의 kernel 지원이 필요하다.

이 통신은 remote processor가 새 message를 직접 기록하는 단순한 shared data structure를 기반으로 한다. 여러 processor의 동시 접근은 hwspinlock module로 조정한다. 공통 hwspinlock interface가 있기 때문에 이 IPC driver를 generic하고 platform-independent하게 작성할 수 있다.

Lock 식별자 조회, 할당, 해제와 강제 회수

struct hwspinlock *hwspin_lock_request_specific(unsigned int id);

지정한 hwspinlock id를 caller에게 할당하고 그 object 주소를 반환한다. 해당 lock이 이미 사용 중이면 NULL을 반환한다. Board code가 미리 정해진 용도로 특정 lock id를 예약할 때 주로 호출한다. 내부에서 sleep할 수 있으므로 process context에서 호출해야 한다.

int of_hwspin_lock_get_id(struct device_node *np, int index);

OF phandle로 지정된 lock의 global lock id를 얻는다. Device Tree에서 hwspinlock module을 참조하는 사용자가 특정 hwspinlock의 global id를 구한 다음 일반 hwspin_lock_request_specific() API로 요청할 수 있게 한다. 성공하면 lock id를, hwspinlock device가 아직 core에 등록되지 않았으면 -EPROBE_DEFER를, 그 밖의 실패에는 해당 error 값을 반환한다. 이 함수도 sleep할 수 있으므로 process context에서 호출해야 한다.

int hwspin_lock_free(struct hwspinlock *hwlock);

앞서 할당한 hwspinlock을 반납한다. 성공하면 0을 반환하고, 이미 free 상태인 lock을 넘긴 경우의 -EINVAL처럼 실패 원인에 맞는 error code를 반환한다. Sleep할 수 있으므로 process context에서 호출한다.

int hwspin_lock_bust(struct hwspinlock *hwlock, unsigned int id);

Hardware lock의 owner를 확인한 뒤 이미 획득된 hwspinlock을 강제로 release한다. 성공하면 0을 반환하며, 해당 hwspinlock 구현에 bust operation이 없으면 -EOPNOTSUPP 같은 error code를 반환한다. 이 함수 역시 sleep할 수 있으므로 process context 전용이다.

Timeout을 사용하는 blocking-free 획득 API

hwspin_lock_timeout*() family는 이미 할당된 hardware lock을 millisecond 단위 timeout 안에서 획득하려고 한다. 다른 processor가 lock을 잡고 있으면 sleep하지 않고 busy loop로 release를 기다리며, 제한 시간이 지나면 포기한다. 성공 시 0, 실패 시 적절한 error code를 반환하며 대표적인 timeout 결과는 -ETIMEDOUT이다.

int hwspin_lock_timeout(struct hwspinlock *hwlock,
                        unsigned int timeout);

int hwspin_lock_timeout_irq(struct hwspinlock *hwlock,
                            unsigned int timeout);

int hwspin_lock_timeout_irqsave(struct hwspinlock *hwlock,
                                unsigned int to,
                                unsigned long *flags);

int hwspin_lock_timeout_raw(struct hwspinlock *hwlock,
                            unsigned int timeout);

int hwspin_lock_timeout_in_atomic(struct hwspinlock *hwlock,
                                  unsigned int to);

기본 hwspin_lock_timeout()이 성공하면 preemption이 disabled 상태가 된다. Caller는 sleep할 수 없으며 remote core가 hardware interconnect를 계속 polling하는 시간을 줄이기 위해 critical section을 짧게 끝내고 가능한 빨리 hwspinlock을 release해야 한다.

_irq variant가 성공하면 preemption과 local interrupt가 모두 disabled 상태다. _irqsave variant는 여기에 더해 lock 진입 전 local interrupt 상태를 flags가 가리키는 저장 위치에 기록한다. 따라서 release할 때 같은 flags를 hwspin_unlock_irqrestore()에 전달해야 원래 IRQ 상태를 복원할 수 있다.

_raw variant를 사용할 때는 hardware lock을 얻는 전체 절차를 사용자 쪽 mutex 또는 spinlock으로 보호하여 deadlock을 피해야 한다. 이렇게 별도 local serialization을 책임지는 대신 hardware lock 아래에서 시간이 오래 걸리거나 sleep 가능한 operation을 수행할 수 있다. 단, 이 함수 자체는 sleep하지 않는다.

_in_atomic variant는 atomic context에서만 호출해야 하며 timeout 값을 수 millisecond보다 크게 두어서는 안 된다. 모든 timeout variant는 lock을 기다리는 동안 busy loop하며 함수 자체가 sleep하는 일은 없다.

즉시 성공하거나 -EBUSY로 끝나는 trylock API

hwspin_trylock*() family는 이미 할당된 hwspinlock을 한 번 획득해 본다. Hardware lock이 이미 사용 중이면 기다리지 않고 즉시 실패한다. 성공 시 0을 반환하며, 이미 점유된 경우의 대표적인 error code는 -EBUSY다. 모든 variant는 sleep하지 않는다.

int hwspin_trylock(struct hwspinlock *hwlock);
int hwspin_trylock_irq(struct hwspinlock *hwlock);
int hwspin_trylock_irqsave(struct hwspinlock *hwlock,
                           unsigned long *flags);
int hwspin_trylock_raw(struct hwspinlock *hwlock);
int hwspin_trylock_in_atomic(struct hwspinlock *hwlock);

기본 variant가 성공하면 preemption이 disabled되므로 caller는 sleep할 수 없다. Remote core가 hardware interconnect를 polling하는 시간을 최소화하려면 hardware lock 보유 시간을 짧게 해야 한다. _irq와 _irqsave는 timeout family와 같은 방식으로 local interrupt 상태까지 관리한다.

_raw variant 사용자는 hardware lock 획득 routine 자체를 mutex 또는 spinlock으로 보호해 deadlock을 피해야 한다. 이 방식을 통해 hardware lock 아래에서 시간이 오래 걸리거나 sleep 가능한 operation을 수행할 수 있다. _in_atomic variant는 atomic context에서만 호출한다.

획득 방식과 짝을 이루는 unlock API

hwspin_unlock*() family는 획득한 hardware lock을 release한다. 이미 unlocked 상태인 lock을 다시 unlock해서는 절대 안 된다. Framework에는 이를 막는 보호 장치가 없으며 그런 호출은 bug로 간주된다. 모든 unlock variant는 sleep하지 않는다.

void hwspin_unlock(struct hwspinlock *hwlock);
void hwspin_unlock_irq(struct hwspinlock *hwlock);
void hwspin_unlock_irqrestore(struct hwspinlock *hwlock,
                              unsigned long *flags);
void hwspin_unlock_raw(struct hwspinlock *hwlock);
void hwspin_unlock_in_atomic(struct hwspinlock *hwlock);

원문의 일반 사용 예제

#include <linux/hwspinlock.h>
#include <linux/err.h>

int hwspinlock_example(void)
{
	struct hwspinlock *hwlock;
	int ret;

	/*
	* assign a specific hwspinlock id - this should be called early
	* by board init code.
	*/
	hwlock = hwspin_lock_request_specific(PREDEFINED_LOCK_ID);
	if (!hwlock)
		...

	/* try to take it, but don't spin on it */
	ret = hwspin_trylock(hwlock);
	if (!ret) {
		pr_info("lock is already taken\n");
		return -EBUSY;
	}

	/*
	* we took the lock, do our thing now, but do NOT sleep
	*/

	/* release the lock */
	hwspin_unlock(hwlock);

	/* free the lock */
	ret = hwspin_lock_free(hwlock);
	if (ret)
		...

	return ret;
}

예제는 board 초기화 단계에서 PREDEFINED_LOCK_ID를 예약하고, hwspin_trylock()으로 기다리지 않는 획득을 시도한 뒤, lock을 잡은 동안 sleep하지 않고 작업을 수행하고, hwspin_unlock()과 hwspin_lock_free() 순서로 release와 object 반납을 수행하는 구조를 보여 준다.

Hwspinlock provider 등록과 해제

int hwspin_lock_register(struct hwspinlock_device *bank,
                         struct device *dev,
                         const struct hwspinlock_ops *ops,
                         int base_id, int num_locks);

Platform-specific 구현이 새 hwspinlock device를 core에 등록할 때 호출한다. 하나의 device는 보통 다수의 hardware lock을 포함하는 bank다. 함수가 sleep할 수 있으므로 process context에서 호출해야 하며 성공하면 0, 실패하면 적절한 error code를 반환한다.

int hwspin_lock_unregister(struct hwspinlock_device *bank);

Vendor-specific 구현이 등록된 hwspinlock device bank를 core에서 제거할 때 호출한다. 이 함수도 sleep할 수 있으므로 process context에서 호출해야 한다.

핵심 data structure와 ownership

struct hwspinlock_device는 보통 hardware lock bank 하나를 나타낸다. 하위 hwspinlock provider가 hwspin_lock_register()를 호출하여 core에 등록한다.

/**
* struct hwspinlock_device - a device which usually spans numerous hwspinlocks
* @dev: underlying device, will be used to invoke runtime PM api
* @ops: platform-specific hwspinlock handlers
* @base_id: id index of the first lock in this device
* @num_locks: number of locks in this device
* @lock: dynamically allocated array of 'struct hwspinlock'
*/
struct hwspinlock_device {
	struct device *dev;
	const struct hwspinlock_ops *ops;
	int base_id;
	int num_locks;
	struct hwspinlock lock[0];
};

• dev는 underlying device이며 runtime PM API 호출에 사용된다.
• ops는 platform-specific hardware operation callback 집합이다.
• base_id는 이 bank에 속한 첫 번째 lock의 global id index다.
• num_locks는 bank가 제공하는 lock 수다.
• lock은 struct hwspinlock의 동적 array다.

hwspinlock_device 안의 각 struct hwspinlock은 hardware lock instance 하나를 나타낸다.

/**
* struct hwspinlock - this struct represents a single hwspinlock instance
* @bank: the hwspinlock_device structure which owns this lock
* @lock: initialized and used by hwspinlock core
* @priv: private data, owned by the underlying platform-specific hwspinlock drv
*/
struct hwspinlock {
	struct hwspinlock_device *bank;
	spinlock_t lock;
	void *priv;
};

bank는 이 lock을 소유한 hwspinlock_device를 가리킨다. 내부 spinlock_t lock은 hwspinlock core가 초기화하고 사용한다. priv는 platform-specific provider driver가 소유하는 private data다. Lock bank를 등록할 때 provider driver가 직접 설정해야 하는 것은 각 lock의 priv member뿐이며, 나머지는 hwspinlock core가 설정하고 초기화한다.

Provider callback 구현 규칙

struct hwspinlock_ops {
	int (*trylock)(struct hwspinlock *lock);
	void (*unlock)(struct hwspinlock *lock);
	void (*relax)(struct hwspinlock *lock);
};

struct hwspinlock_ops에는 trylock, unlock, relax 세 callback이 있다. 앞의 두 callback은 필수이고 relax는 선택 사항이다.

• ->trylock(): hardware lock 획득을 정확히 한 번 시도한다. 실패하면 0, 성공하면 1을 반환하며 절대로 sleep해서는 안 된다.
• ->unlock(): hardware lock을 release한다. 항상 성공해야 하며 이 callback도 sleep할 수 없다.
• ->relax(): hwspinlock core가 lock을 얻기 위해 spin하는 동안 호출할 수 있는 선택 callback이다. 연속된 ->trylock() 호출 사이에 platform-specific delay를 넣는 데 사용할 수 있고, sleep해서는 안 된다.