/* begincopyright
  Copyright (c) 1988 Xerox Corporation. All rights reserved.
  Use and copying of this software and preparation of derivative works based
  upon this software are permitted. Any distribution of this software or
  derivative works must comply with all applicable United States export
  control laws. This software is made available AS IS, and Xerox Corporation
  makes no warranty about the software, its performance or its conformity to
  any specification. Any person obtaining a copy of this software is requested
  to send their name and post office or electronic mail address to:
    PCR Coordinator
    Xerox PARC
    3333 Coyote Hill Rd.
    Palo Alto, CA 94304
  endcopyright */

/*
 * ThreadsSchedCtl.h
 *
 * Demers, February 6, 1990 7:41:00 pm PST
 *
 * Scheduling control
 */

#ifndef XR_BASIC_TYPES_
#   include "BasicTypes.h"
#endif

#ifndef _XR_THREADS_
#   include "Threads.h"
#endif


/*
 * Global sched control lock
 */


extern int /* 0 or -errno */
XR_SchedCtlLock(/* bool wait */);
/*
    Acquire lock for global SchedCtl operations.
    The wait is abortable.
*/

extern int /* 0 or -errno */
XR_SchedCtlUnlock();


/*
 * Scheduler control operations ...
 *
 * Should be called only from a thread.
 * For some operations, caller must hold schedCtl lock.
 */


/* thread groups */

typedef unsigned long XR_SchedCtlWhich;

#define XR_SchedCtlWhichSelf() \
	((XR_SchedCtlWhich)(-1))
#define XR_SchedCtlWhichIsSelf(w) \
	((w) == XR_SchedCtlWhichSelf())

#define XR_SchedCtlWhichFromPri(pri) \
	((XR_SchedCtlWhich)(pri))
#define XR_SchedCtlWhichToPri(w) \
	((XR_Pri)(w))
#define XR_SchedCtlWhichIsPri(w) \
	( (((XR_Pri)(w)) > XR_PRI_IDLE) && (((XR_Pri)(w)) <= XR_PRI_LAST) )

#define XR_SchedCtlWhichFromThread(t) \
	((XR_SchedCtlWhich)(t))
#define XR_SchedCtlWhichToThread(w) \
	((XR_Thread)(w))
#define XR_SchedCtlWhichIsThread(w) \
	( (((XR_Pri)(w)) > XR_PRI_LAST)) && (!XR_SchedCtlWhichIsSelf(w)) )


/* schedCtl ops */

typedef enum {
    scop_nop = 0,
    scop_getProcessor = 1,
    scop_setProcessor = 2,
    scop_getPriority = 3,
    scop_setPriority = 4,
    scop_disable = 5,
    scop_enable = 6,
    scop_lastInvalid = 0x7fffffff
} XR_SchedCtlOp;



extern int /* result >= 0 or -errno */
XR_SchedCtl(/*
    XR_SchedCtlWhich which,
    XR_SchedCtlOp op,
    unsigned long *argp
*/);
/*
    Execute the specified opcode, changing scheduling parameters
      for threads identified by which.
    If which is not SELF, the caller must hold the schedCtl lock.
    Don't wait for the command to take effect on all processors
      (see XR_SchedCtlWait below).
    Return an op-specific nonnegative value on success,
      or (-XR_GetErrno()) on failure.


    Op == scop_nop
    
      Do nothing

    Op == scop_setProcessor
    Op == scop_getProcessor

      Set/get processor on which specified threads may be scheduled.
      Arg values:
*/

#       define scop_ProcessorRestrictedBit(i) \
		(01 << (i))
#       define scop_IsRestricted(processorArg,bit) \
		( ((processorArg) & (bit)) != 0 )

#       define scop_processorArgAny \
		((unsigned long)(0))
#       define scop_processorArgNone \
		((unsigned long)(-1))
#       define scop_processorArgVP(i) \
		( (unsigned long) (~scop_ProcessorRestrictedBit(i)) )
#       define scop_processorArgNotVP(i) \
		( (unsigned long) scop_ProcessorRestrictedBit(i) )

/*
      Success result is 0.


    Op == scop_setPriority
    Op == scop_getPriority

      Set/get scheduling priority.  Legal only if which is Self.
      Arg is an XR_PRI value > XR_PRI_IDLE



    Op == scop_disable
    Op == scop_enable

      Disable or enable scheduling of specified thread.
      The caller itself cannot be included among the specified threads.
      Multiple disable/enable calls are accumulated.
*/


extern int /* 0 or -errno */
XR_SchedCtlAll(/*
    XR_SchedCtlOp othersOp,
    unsigned long *othersArgp,
    XR_SchedCtlOp myOp,
    unsigned long *myArgp
*/);
/*
    Issue a SchedCtl to every group, treating the group
      of the current thread specially.
    Don't wait for the op to take effect on all processors,
      (see XR_SchedCtlWait below).
    Return 0 on success, (-XR_GetErrno()) on failure.
*/


int /* 0 or -errno */
XR_SchedCtlWait();
/*
    Wait for all previous schedCtl operations issued by this thread
      to take effect.
    Return 0 on success, (-XR_GetErrno()) on failure.
*/


/*
 * Creature Comforts ...
 */

int /* result or -errno */
XR_SchedCtlRunAtomically(/*
    int (*proc)(XR_Pointer data),
    XR_Pointer data
*/);
/*
    Stop all other priorities.
    Call (*proc)(data) on processor 0.
    Restart all priorities.
    Result is the value returned by proc (which is assumed to
      be nonnegative) or (-XR_GetErrno()).
*/