sync.h

一个AVR单片机的操作系统

/**
 * Copyright (c) 2006-2008 iWESUN (ShenZhen) Inf.
 * All rights reserved. 
 * 
 * Redistribution and use in source and binary forms, with or without modification, 
 * are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission. 
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 
 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
 * OF SUCH DAMAGE.
 *
 * This file is part of the AvrcX MTOS
 * 
 * Author: Winter Hu  <[e-mail]>
 * Create: Nov 25, 2006
 */

#ifndef __SYNC_H__
#define __SYNC_H__

#include "common.h"
#include "lnklist.h"

#define TYPE_SEMAPHORE 1
#define TYPE_MUTEX     2
#define TYPE_EVENT     4

#ifndef __ASSEMBLER__
/* These only work in C program */

/**
 * Define synchronized monitor 
 * type = 1, Semaphore
 * type = 2, Mutex
 * type = 4, Event
 */
typedef struct Monitor {
  unsigned char type;
  __volatile__ signed char sema; // It MUST be signed 
  LinkedList BlockedQueue; // Blocked PID in this queue
} Monitor, Semaphore, Mutex, Event;

/**
 * A macro to ease the declaration of Semaphore
 * USAGE: SEMAPHORE(mySema, 10);
 *
 * @param name, The name of the Semaphore
 * @param sema, The initilize semaphore value
 */
#define SEMAPHORE(name, sema) \
  Semaphore name = {TYPE_SEMAPHORE, sema, {NULL}}

/**
 * A macro to ease the declaration of Mutex
 * USAGE: MUTEX(myMutex);
 *
 * @param name, The name of the Semaphore
 */
#define MUTEX(name) \
  Mutex name = {TYPE_MUTEX, 1, {NULL}}

/**
 * A macro to ease the declaration of Event
 * USAGE: EVENT(myEvent);
 *
 * @param name, The name of the Semaphore
 */
#define EVENT(name) \
  Event name = {TYPE_EVENT, 0, {NULL}};

/**
 * Set value of Semaphore
 *
 * @param Semaphore*, The pointer to the Semaphore monitor
 * @param signed char, The value of semaphore
 */
INTERFACE void set_semaphore(Semaphore*, signed char);

/**
 * Reset Event to un-trigger status
 * User MUST invoke this method to reset Event monitor after wakeup
 *
 * @param Event*, The pointer to the Event monitor
 * @see void triggerEvent(Event*)
 */
INTERFACE void reset_event(Event*);

/**
 * P primitive of the Semaphore
 * If --sema < 0, the caller will be swaped to BlockedQueue
 * 
 * @param Semaphore*, The pointer to the Semaphore
 */
INTERFACE void P(Semaphore*);

/**
 * V primitive of the Semaphore
 * If ++sema <= 0, the FIRST process in BlockedQueue will be wakeup.
 *
 * @param Semaphore*, The pointer to the Semaphore monitor
 */
INTERFACE void V(Semaphore*);

/**
 * Release Mutex monitor, the FIRST process in BlockedQueue will be wakeup.
 *
 * @param Mutex*, The pointer to the Mutex monitor
 * @see void waitObject(Monitor*)
 */
INTERFACE void release_mutex(Mutex*);

/**
 * Trigger Event monitor, ALL processes in BlockedQueue could be wakeup,
 * User MUST reset Event monitor obviously.
 *
 * @param Event*, The pointer to the Event monitor
 * @see void waitObject(Monitor*)
 * @see void resetEvent(Event*)
 */
INTERFACE void trigger_event(Event*);

/**
 * The caller maybe blocked in the BlockedQueue until the monitor object is
 * obtainable.
 *
 * @param Monitor*, The pointer to the Semaphore, Mutex or Event 
 * @see void V(Semaphore*)
 * @see void releaseMutex(Mutex*)
 * @see void triggerEvent(Event*)
 */
INTERFACE void wait_object(Monitor*);

/**
 * The caller blocked in the BlockedQueue until the monitor object is 
 * obtainable or the specified wating time is timeout.
 *
 * @param Monitor*, The pointer to the Semaphore, Mutex, or Event 
 * @param unsinged int, The timeout in ticks
 * @return unsigned char, 0, the monitor is obtainable. 1, timeout
 */
INTERFACE unsigned char wait_object_with_timeout(Monitor*, unsigned int);

#endif /* !__ASSEMBLER__ */



#endif /* __LNKLIST_H__ */