/*
** @file	procs.c
**
** @author	CSCI-452 class of 20245
**
** @brief	Process-related implementations
*/

#define	KERNEL_SRC

#include <common.h>

#include <procs.h>
#include <user.h>

/*
** PRIVATE DEFINITIONS
*/

// determine if a queue is empty; assumes 'q' is a valid pointer
#define	PCB_QUEUE_EMPTY(q)	((q)->head == NULL)

/*
** PRIVATE DATA TYPES
*/

/*
** PCB Queue structure
**
** Opaque to the rest of the kernel
**
** Typedef'd in the header: typedef struct pcb_queue_s *pcb_queue_t;
*/
struct pcb_queue_s {
	pcb_t *head;
	pcb_t *tail;
	enum pcb_queue_order_e order;
};

/*
** PRIVATE GLOBAL VARIABLES
*/

// collection of queues
static struct pcb_queue_s pcb_freelist_queue;
static struct pcb_queue_s ready_queue;
static struct pcb_queue_s waiting_queue;
static struct pcb_queue_s sleeping_queue;
static struct pcb_queue_s zombie_queue;
static struct pcb_queue_s sioread_queue;

/*
** PUBLIC GLOBAL VARIABLES
*/

// public-facing queue handles
pcb_queue_t pcb_freelist;
pcb_queue_t ready;
pcb_queue_t waiting;
pcb_queue_t sleeping;
pcb_queue_t zombie;
pcb_queue_t sioread;

// pointer to the currently-running process
pcb_t *current;

// the process table
pcb_t ptable[N_PROCS];

// next available PID
uint_t next_pid;

// pointer to the PCB for the 'init' process
pcb_t *init_pcb;

// table of state name strings
const char *state_str[N_STATES] = {
	[ STATE_UNUSED   ] = "Unu",       // "Unused"
	[ STATE_NEW      ] = "New",
	[ STATE_READY    ] = "Rdy",       // "Ready"
	[ STATE_RUNNING  ] = "Run",       // "Running"
	[ STATE_SLEEPING ] = "Slp",       // "Sleeping"
	[ STATE_BLOCKED  ] = "Blk",       // "Blocked"
	[ STATE_WAITING  ] = "Wat",       // "Waiting"
	[ STATE_KILLED   ] = "Kil",       // "Killed"
	[ STATE_ZOMBIE   ] = "Zom"        // "Zombie"
};

// table of priority name strings
const char *prio_str[N_PRIOS] = {
	[ PRIO_HIGH     ] = "High",
	[ PRIO_STD      ] = "User",
	[ PRIO_LOW      ] = "Low ",
	[ PRIO_DEFERRED ] = "Def "
};

// table of queue ordering name strings
const char *ord_str[N_PRIOS] = {
	[ O_FIFO   ] = "FIFO",
	[ O_PRIO   ] = "PRIO",
	[ O_PID    ] = "PID ",
	[ O_WAKEUP ] = "WAKE"
};

/*
** PRIVATE FUNCTIONS
*/

/**
** Priority search functions. These are used to traverse a supplied
** queue looking for the queue entry that would precede the supplied
** PCB when that PCB is inserted into the queue.
**
** Variations:
**     find_prev_wakeup()     compares wakeup times
**     find_prev_priority()   compares process priorities
**     find_prev_pid()        compares PIDs
**
** Each assumes the queue should be in ascending order by the specified
** comparison value.
**
** @param[in] queue  The queue to search
** @param[in] pcb    The PCB to look for
**
** @return a pointer to the predecessor in the queue, or NULL if
** this PCB would be at the beginning of the queue.
*/
static pcb_t *find_prev_wakeup( pcb_queue_t queue, pcb_t *pcb ) {

	// sanity checks!
	assert1( queue != NULL );
	assert1( pcb != NULL );

	pcb_t *prev = NULL;
	pcb_t *curr = queue->head;

	while( curr != NULL && curr->wakeup <= pcb->wakeup ) {
		prev = curr;
		curr = curr->next;
	}

	return prev;
}

static pcb_t *find_prev_priority( pcb_queue_t queue, pcb_t *pcb ) {

	// sanity checks!
	assert1( queue != NULL );
	assert1( pcb != NULL );

	pcb_t *prev = NULL;
	pcb_t *curr = queue->head;

	while( curr != NULL && curr->priority <= pcb->priority ) {
		prev = curr;
		curr = curr->next;
	}

	return prev;
}

static pcb_t *find_prev_pid( pcb_queue_t queue, pcb_t *pcb ) {

	// sanity checks!
	assert1( queue != NULL );
	assert1( pcb != NULL );

	pcb_t *prev = NULL;
	pcb_t *curr = queue->head;

	while( curr != NULL && curr->pid <= pcb->pid ) {
		prev = curr;
		curr = curr->next;
	}

	return prev;
}

/*
** PUBLIC FUNCTIONS
*/

// a macro to simplify queue setup
#define	QINIT(q,s) \
	q = &q##_queue; \
	if( pcb_queue_reset(q,s) != SUCCESS ) { \
		PANIC( 0, "pcb_init can't reset " # q ); \
	}

/**
** Name:	pcb_init
**
** Initialization for the Process module.
*/
void pcb_init( void ) {

#if TRACING_INIT
	cio_puts( " Procs" );
#endif

	// there is no current process
	current = NULL;

	// set up the external links to the queues
	QINIT( pcb_freelist, O_FIFO );
	QINIT( ready, O_PRIO );
	QINIT( waiting, O_PID );
	QINIT( sleeping, O_WAKEUP );
	QINIT( zombie, O_PID );
	QINIT( sioread, O_FIFO );

	/*
	** We statically allocate our PCBs, so we need to add them
	** to the freelist before we can use them. If this changes
	** so that we dynamicallyl allocate PCBs, this step either
	** won't be required, or could be used to pre-allocate some
	** number of PCB structures for future use.
	*/

	pcb_t *ptr = ptable;
	for( int i = 0; i < N_PROCS; ++i ) {
		pcb_free( ptr );
		++ptr;
	}
}

/**
** Name:	pcb_alloc
**
** Allocate a PCB from the list of free PCBs.
**
** @param pcb   Pointer to a pcb_t * where the PCB pointer will be returned.
**
** @return status of the allocation attempt
*/
int pcb_alloc( pcb_t **pcb ) {

	// sanity check!
	assert1( pcb != NULL );

	// remove the first PCB from the free list
	pcb_t *tmp;
	if( pcb_queue_remove(pcb_freelist,&tmp) != SUCCESS ) {
		return E_NO_PCBS;
	}

	*pcb = tmp;
	return SUCCESS;
}

/**
** Name:	pcb_free
**
** Return a PCB to the list of free PCBs.
**
** @param pcb   Pointer to the PCB to be deallocated.
*/
void pcb_free( pcb_t *pcb ) {

	if( pcb != NULL ) {
		// mark the PCB as available
		pcb->state = STATE_UNUSED;

		// add it to the free list
		int status = pcb_queue_insert( pcb_freelist, pcb );

		// if that failed, we're in trouble
		if( status != SUCCESS ) {
			sprint( b256, "pcb_free(0x%08x) status %d", (uint32_t) pcb,
					status );
			PANIC( 0, b256 );
		}
	}
}

/**
** Name:	pcb_zombify
**
** Turn the indicated process into a Zombie. This function
** does most of the real work for exit() and kill() calls.
** Is also called from the scheduler and dispatcher.
**
** @param pcb   Pointer to the newly-undead PCB
*/
void pcb_zombify( register pcb_t *victim ) {

	// should this be an error?
	if( victim == NULL ) {
		return;
	}

	// every process must have a parent, even if it's 'init'
	assert( victim->parent != NULL );

	/*
	** We need to locate the parent of this process.  We also need
	** to reparent any children of this process.  We do these in
	** a single loop.
	*/
	pcb_t *parent = victim->parent;
	pcb_t *zchild = NULL;

	// two PIDs we will look for
	uint_t vicpid = victim->pid;

	// speed up access to the process table entries
	register pcb_t *curr = ptable;

	for( int i = 0; i < N_PROCS; ++i, ++curr ) {

		// make sure this is a valid entry
		if( curr->state == STATE_UNUSED ) {
			continue;
		}

		// if this is our parent, just keep going - we continue
		// iterating to find all the children of this process.
		if( curr == parent ) {
			continue;
		}

		if( curr->parent == victim ) {

			// found a child - reparent it
			curr->parent = init_pcb;

			// see if this child is already undead
			if( curr->state == STATE_ZOMBIE ) {
				// if it's already a zombie, remember it, so we
				// can pass it on to 'init'; also, if there are
				// two or more zombie children, it doesn't matter
				// which one we pick here, as the others will be
				// collected when 'init' loops
				zchild = curr;
			}

		}
	}

	/*
	** If we found a child that was already terminated, we need to
	** wake up the init process if it's already waiting.
	**
	** Note: we only need to do this for one Zombie child process -
	** init will loop and collect the others after it finishes with
	** this one.
	**
	** Also note: it's possible that the exiting process' parent is
	** also init, which means we're letting one of zombie children
	** of the exiting process be cleaned up by init before the 
	** existing process itself is cleaned up by init. This will work,
	** because after init cleans up the zombie, it will loop and
	** call waitpid() again, by which time this exiting process will
	** be marked as a zombie.
	*/
	if( zchild != NULL && init_pcb->state == STATE_WAITING ) {

		// dequeue the zombie
		assert( pcb_queue_remove_this(zombie,zchild) == SUCCESS );

		assert( pcb_queue_remove_this(waiting,init_pcb) == SUCCESS );

		// intrinsic return value is the PID
		RET(init_pcb) = zchild->pid;

		// may also want to return the exit status
		int32_t *ptr = (int32_t *) ARG(init_pcb,2);

		if( ptr != NULL ) {
			// ********************************************************
			// ** Potential VM issue here!  This code assigns the exit
			// ** status into a variable in the parent's address space.
			// ** This works in the baseline because we aren't using
			// ** any type of memory protection.  If address space
			// ** separation is implemented, this code will very likely
			// ** STOP WORKING, and will need to be fixed.
			// ********************************************************
			*ptr = zchild->exit_status;
		}

		// all done - schedule 'init', and clean up the zombie
		schedule( init_pcb );
		pcb_cleanup( zchild );
	}

	/*
	** Now, deal with the parent of this process. If the parent is
	** already waiting, just wake it up and clean up this process.
	** Otherwise, this process becomes a zombie.
	**
	** Note: if the exiting process' parent is init and we just woke
	** init up to deal with a zombie child of the exiting process,
	** init's status won't be Waiting any more, so we don't have to
	** worry about it being scheduled twice.
	*/

	if( parent->state == STATE_WAITING ) {

		// verify that the parent is either waiting for this process
		// or is waiting for any of its children
		uint32_t target = ARG(parent,1);

		if( target == 0 || target == vicpid ) {

			// the parent is waiting for this child or is waiting
			// for any of its children, so we can wake it up.

			// intrinsic return value is the PID
			RET(parent) = vicpid;

			// may also want to return the exit status
			int32_t *ptr = (int32_t *) ARG(parent,2);

			if( ptr != NULL ) {
				// ********************************************************
				// ** Potential VM issue here!  This code assigns the exit
				// ** status into a variable in the parent's address space.
				// ** This works in the baseline because we aren't using
				// ** any type of memory protection.  If address space
				// ** separation is implemented, this code will very likely
				// ** STOP WORKING, and will need to be fixed.
				// ********************************************************
				*ptr = victim->exit_status;
			}

			// all done - schedule the parent, and clean up the zombie
			schedule( parent );
			pcb_cleanup( victim );

			return;
		}
	}

	/*
	** The parent isn't waiting OR is waiting for a specific child
	** that isn't this exiting process, so we become a Zombie.
	**
	** This code assumes that Zombie processes are *not* in
	** a queue, but instead are just in the process table with
	** a state of 'Zombie'.  This simplifies life immensely,
	** because we won't need to dequeue it when it is collected
	** by its parent.
	*/

	victim->state = STATE_ZOMBIE;
	assert( pcb_queue_insert(zombie,victim) == SUCCESS );

	/*
	** Note: we don't call _dispatch() here - we leave that for
	** the calling routine, as it's possible we don't need to
	** choose a new current process.
	*/
}

/**
** Name:	pcb_cleanup
**
** Reclaim a process' data structures
**
** @param pcb   The PCB to reclaim
*/
void pcb_cleanup( pcb_t *pcb ) {

#if TRACING_PCB
	cio_printf( "** pcb_cleanup(0x%08x)\n", (uint32_t) pcb );
#endif

	// avoid deallocating a NULL pointer
	if( pcb == NULL ) {
		// should this be an error?
		return;
	}

	// we need to release all the VM data structures and frames
	user_cleanup( pcb );

	// release the PCB itself
	pcb_free( pcb );
}

/**
** Name:	pcb_find_pid
**
** Locate the PCB for the process with the specified PID
**
** @param pid   The PID to be located
**
** @return Pointer to the PCB, or NULL
*/
pcb_t *pcb_find_pid( uint_t pid ) {

	// must be a valid PID
	if( pid < 1 ) {
		return NULL;
	}

	// scan the process table
	pcb_t *p = ptable;

	for( int i = 0; i < N_PROCS; ++i, ++p ) {
		if( p->pid == pid && p->state != STATE_UNUSED ) {
			return p;
		}
	}

	// didn't find it!
	return NULL;
}

/**
** Name:	pcb_find_ppid
**
** Locate the PCB for the process with the specified parent
**
** @param pid   The PID to be located
**
** @return Pointer to the PCB, or NULL
*/
pcb_t *pcb_find_ppid( uint_t pid ) {

	// must be a valid PID
	if( pid < 1 ) {
		return NULL;
	}

	// scan the process table
	pcb_t *p = ptable;

	for( int i = 0; i < N_PROCS; ++i, ++p ) {
		assert1( p->parent != NULL );
		if( p->parent->pid == pid && p->parent->state != STATE_UNUSED ) {
			return p;
		}
	}

	// didn't find it!
	return NULL;
}

/**
** Name:    pcb_queue_reset
**
** Initialize a PCB queue. We assume that whatever data may be
** in the queue structure can be overwritten.
**
** @param queue[out]  The queue to be initialized
** @param order[in]   The desired ordering for the queue
**
** @return status of the init request
*/
int pcb_queue_reset( pcb_queue_t queue, enum pcb_queue_order_e style ) {

	// sanity check
	assert1( queue != NULL );

	// make sure the style is valid
	if( style < O_FIRST_STYLE || style > O_LAST_STYLE ) {
		return E_BAD_PARAM;
	}

	// reset the queue
	queue->head = queue->tail = NULL;
	queue->order = style;

	return SUCCESS;
}

/**
** Name:	pcb_queue_empty
**
** Determine whether a queue is empty. Essentially just a wrapper
** for the PCB_QUEUE_EMPTY() macro, for use outside this module.
**
** @param[in] queue  The queue to check
**
** @return true if the queue is empty, else false
*/
bool_t pcb_queue_empty( pcb_queue_t queue ) {

	// if there is no queue, blow up
	assert1( queue != NULL );

	return PCB_QUEUE_EMPTY(queue);
}

/**
** Name:    pcb_queue_length
**
** Return the count of elements in the specified queue.
**
** @param[in] queue  The queue to check
**
** @return the count (0 if the queue is empty)
*/
uint_t pcb_queue_length( const pcb_queue_t queue ) {

	// sanity check
	assert1( queue != NULL );

	// this is pretty simple
	register pcb_t *tmp = queue->head;
	register int num = 0;
	
	while( tmp != NULL ) {
		++num;
		tmp = tmp->next;
	}

	return num;
}

/**
** Name:    pcb_queue_insert
**
** Inserts a PCB into the indicated queue.
**
** @param queue[in,out]  The queue to be used
** @param pcb[in]        The PCB to be inserted
**
** @return status of the insertion request
*/
int pcb_queue_insert( pcb_queue_t queue, pcb_t *pcb ) {

	// sanity checks
	assert1( queue != NULL );
	assert1( pcb != NULL );

	// if this PCB is already in a queue, we won't touch it
	if( pcb->next != NULL ) {
		// what to do? we let the caller decide
		return E_BAD_PARAM;
	}

	// is the queue empty?
	if( queue->head == NULL ) {
		queue->head = queue->tail = pcb;
		return SUCCESS;
	}
	assert1( queue->tail != NULL );

	// no, so we need to search it
	pcb_t *prev = NULL;

	// find the predecessor node
	switch( queue->order ) {
	case O_FIFO:
		prev = queue->tail;
		break;
	case O_PRIO:
		prev = find_prev_priority(queue,pcb);
		break;
	case O_PID:
		prev = find_prev_pid(queue,pcb);
		break;
	case O_WAKEUP:
		prev = find_prev_wakeup(queue,pcb);
		break;
	default:
		// do we need something more specific here?
		return E_BAD_PARAM;
	}

	// OK, we found the predecessor node; time to do the insertion

	if( prev == NULL ) {

		// there is no predecessor, so we're
		// inserting at the front of the queue
		pcb->next = queue->head;
		if( queue->head == NULL ) {
			// empty queue!?! - should we panic?
			queue->tail = pcb;
		}
		queue->head = pcb;

	} else if( prev->next == NULL ) {

		// append at end
		prev->next = pcb;
		queue->tail = pcb;

	} else {

		// insert between prev & prev->next
		pcb->next = prev->next;
		prev->next = pcb;

	}

	return SUCCESS;
}

/**
** Name:    pcb_queue_remove
**
** Remove the first PCB from the indicated queue.
**
** @param queue[in,out]  The queue to be used
** @param pcb[out]       Pointer to where the PCB pointer will be saved
**
** @return status of the removal request
*/
int pcb_queue_remove( pcb_queue_t queue, pcb_t **pcb ) {

	//sanity checks
	assert1( queue != NULL );
	assert1( pcb != NULL );

	// can't get anything if there's nothing to get!
	if( PCB_QUEUE_EMPTY(queue) ) {
		return E_EMPTY_QUEUE;
	}

	// take the first entry from the queue
	pcb_t *tmp = queue->head;
	queue->head = tmp->next;

	// disconnect it completely
	tmp->next = NULL;

	// was this the last thing in the queue?
	if( queue->head == NULL ) {
		// yes, so clear the tail pointer for consistency
		queue->tail = NULL;
	}

	// save the pointer
	*pcb = tmp;

	return SUCCESS;
}

/**
** Name:    pcb_queue_remove_this
**
** Remove the specified PCB from the indicated queue.
**
** We don't return the removed pointer, because the calling
** routine must already have it (because it was supplied
** to us in the call).
**
** @param queue[in,out]  The queue to be used
** @param pcb[in]        Pointer to the PCB to be removed
**
** @return status of the removal request
*/
int pcb_queue_remove_this( pcb_queue_t queue, pcb_t *pcb ) {

	//sanity checks
	assert1( queue != NULL );
	assert1( pcb != NULL );

	// can't get anything if there's nothing to get!
	if( PCB_QUEUE_EMPTY(queue) ) {
		return E_EMPTY_QUEUE;
	}

	// iterate through the queue until we find the desired PCB
	pcb_t *prev = NULL;
	pcb_t *curr = queue->head;

	while( curr != NULL && curr != pcb ) {
		prev = curr;
		curr = curr->next;
	}

	// case  prev  curr  next   interpretation
	// ====  ====  ====  ====   ============================
	//   1.    0     0    --    *** CANNOT HAPPEN ***
	//   2.    0    !0     0    removing only element
	//   3.    0    !0    !0    removing first element
	//   4.   !0     0    --    *** NOT FOUND ***
	//   5.   !0    !0     0    removing from end
	//   6.   !0    !0    !0    removing from middle

	if( curr == NULL ) {
		// case 1
		assert( prev != NULL );
		// case 4
		return E_NOT_FOUND;
	}

	// connect predecessor to successor
	if( prev != NULL ) {
		// not the first element
		// cases 5 and 6
		prev->next = curr->next;
	} else {
		// removing first element
		// cases 2 and 3
		queue->head = curr->next;
	}

	// if this was the last node (cases 2 and 5),
	// also need to reset the tail pointer
	if( curr->next == NULL ) {
		// if this was the only entry (2), prev is NULL,
		// so this works for that case, too
		queue->tail = prev;
	}

	// unlink current from queue
	curr->next = NULL;

	// there's a possible consistancy problem here if somehow
	// one of the queue pointers is NULL and the other one
	// is not NULL

	assert1(
		(queue->head == NULL && queue->tail == NULL) ||
		(queue->head != NULL && queue->tail != NULL)
	);

	return SUCCESS;
}

/**
** Name:    pcb_queue_peek
**
** Return the first PCB from the indicated queue, but don't
** remove it from the queue.
**
** @param queue[in]  The queue to be used
**
** @return the PCB poiner, or NULL if the queue is empty
*/
pcb_t *pcb_queue_peek( const pcb_queue_t queue ) {

	//sanity check
	assert1( queue != NULL );

	// can't get anything if there's nothing to get!
	if( PCB_QUEUE_EMPTY(queue) ) {
		return NULL;
	}

	// just return the first entry from the queue
	return queue->head;
}

/*
** Scheduler routines
*/

/**
** schedule(pcb)
**
** Schedule the supplied process
**
** @param pcb   Pointer to the PCB of the process to be scheduled
*/
void schedule( pcb_t *pcb ) {

	// sanity check
	assert1( pcb != NULL );

	// check for a killed process
	if( pcb->state == STATE_KILLED ) {
		// TODO figure out what to do now
		return;
	}

	// mark it as ready
	pcb->state = STATE_READY;

	// add it to the ready queue
	if( pcb_queue_insert(ready,pcb) != SUCCESS ) {
		PANIC( 0, "schedule insert fail" );
	}
}

/**
** dispatch()
**
** Select the next process to receive the CPU
*/
void dispatch( void ) {

	// verify that there is no current process
	assert( current == NULL );

	// grab whoever is at the head of the queue
	int status = pcb_queue_remove( ready, &current );
	if( status != SUCCESS ) {
		sprint( b256, "dispatch queue remove failed, code %d", status );
		PANIC( 0, b256 );
	}

	// set the process up for success
	current->state = STATE_RUNNING;
	current->ticks = QUANTUM_STANDARD;
}


/*
** Debugging/tracing routines
*/

/**
** ctx_dump(msg,context)
**
** Dumps the contents of this process context to the console
**
** @param msg[in]   An optional message to print before the dump
** @param c[in]     The context to dump out
*/
void ctx_dump( const char *msg, register context_t *c ) {

	// first, the message (if there is one)
	if( msg ) {
		cio_puts( msg );
	}

	// the pointer
	cio_printf( " @ %08x: ", (uint32_t) c );

	// if it's NULL, why did you bother calling me?
	if( c == NULL ) {
		cio_puts( " NULL???\n" );
		return;
	}

	// now, the contents
	cio_printf( "ss %04x gs %04x fs %04x es %04x ds %04x cs %04x\n",
				  c->ss & 0xff, c->gs & 0xff, c->fs & 0xff,
				  c->es & 0xff, c->ds & 0xff, c->cs & 0xff );
	cio_printf( "  edi %08x esi %08x ebp %08x esp %08x\n",
				  c->edi, c->esi, c->ebp, c->esp );
	cio_printf( "  ebx %08x edx %08x ecx %08x eax %08x\n",
				  c->ebx, c->edx, c->ecx, c->eax );
	cio_printf( "  vec %08x cod %08x eip %08x eflags %08x\n",
				  c->vector, c->code, c->eip, c->eflags );
}

/**
** ctx_dump_all(msg)
**
** dump the process context for all active processes
**
** @param msg[in]  Optional message to print
*/
void ctx_dump_all( const char *msg ) {

	if( msg != NULL ) {
		cio_puts( msg );
	}

	int n = 0;
	register pcb_t *pcb = ptable;
	for( int i = 0; i < N_PROCS; ++i, ++pcb ) {
		if( pcb->state != STATE_UNUSED ) {
			++n;
			cio_printf( "%2d(%d): ", n, pcb->pid );
			ctx_dump( NULL, pcb->context );
		}
	}
}

/**
** _pcb_dump(msg,pcb)
**
** Dumps the contents of this PCB to the console
**
** @param msg[in]  An optional message to print before the dump
** @param pcb[in]  The PCB to dump
** @param all[in]  Dump all the contents?
*/
void pcb_dump( const char *msg, register pcb_t *pcb, bool_t all ) {

	// first, the message (if there is one)
	if( msg ) {
		cio_puts( msg );
	}

	// the pointer
	cio_printf( " @ %08x:", (uint32_t) pcb );

	// if it's NULL, why did you bother calling me?
	if( pcb == NULL ) {
		cio_puts( " NULL???\n" );
		return;
	}

	cio_printf( " %d", pcb->pid );
	cio_printf( " %s",
			pcb->state >= N_STATES ? "???" : state_str[pcb->state] );

	if( !all ) {
		// just printing IDs and states on one line
		return;
	}

	// now, the rest of the contents
	cio_printf( " %s",
			pcb->priority >= N_PRIOS ? "???" : prio_str[pcb->priority] );

	cio_printf( " ticks %u xit %d wake %08x\n",
				pcb->ticks, pcb->exit_status, pcb->wakeup );

	cio_printf( " parent %08x", (uint32_t)pcb->parent );
	if( pcb->parent != NULL ) {
		cio_printf( " (%u)", pcb->parent->pid );
	}

	cio_printf( " next %08x context %08x pde %08x", (uint32_t) pcb->next,
			(uint32_t) pcb->context, (uint32_t) pcb->pdir );

	cio_putchar( '\n' );
}

/**
** pcb_queue_dump(msg,queue,contents)
**
** Dump the contents of the specified queue to the console
**
** @param msg[in]       Optional message to print
** @param queue[in]     The queue to dump
** @param contents[in]  Also dump (some) contents?
*/
void pcb_queue_dump( const char *msg, pcb_queue_t queue, bool_t contents ) {

	// report on this queue
	cio_printf( "%s: ", msg );
	if( queue == NULL ) {
		cio_puts( "NULL???\n" );
		return;
	}

	// first, the basic data
	cio_printf( "head %08x tail %08x",
			(uint32_t) queue->head, (uint32_t) queue->tail );

	// next, how the queue is ordered
	cio_printf( " order %s\n",
			queue->order >= N_ORDERINGS ? "????" : ord_str[queue->order] );

	// if there are members in the queue, dump the first few PIDs
	if( contents && queue->head != NULL ) {
		cio_puts( " PIDs: " );
		pcb_t *tmp = queue->head;
		for( int i = 0; i < 5 && tmp != NULL; ++i, tmp = tmp->next ) {
			cio_printf( " [%u]", tmp->pid );
		}

		if( tmp != NULL ) {
			cio_puts( " ..." );
		}

		cio_putchar( '\n' );
	}
}

/**
** ptable_dump(msg,all)
**
** dump the contents of the "active processes" table
**
** @param msg[in]  Optional message to print
** @param all[in]  Dump all or only part of the relevant data
*/
void ptable_dump( const char *msg, bool_t all ) {

	if( msg ) {
		cio_puts( msg );
	}
	cio_putchar( ' ' );

	int used = 0;
	int empty = 0;

	register pcb_t *pcb = ptable;
	for( int i = 0; i < N_PROCS; ++i ) {
		if( pcb->state == STATE_UNUSED ) {

			// an empty slot
			++empty;

		} else {

			// a non-empty slot
			++used;

			// if not dumping everything, add commas if needed
			if( !all && used ) {
				cio_putchar( ',' );
			}

			// report the table slot #
			cio_printf( " #%d:", i );

			// and dump the contents
			pcb_dump( NULL, pcb, all );
		}
	}

	// only need this if we're doing one-line output
	if( !all ) {
		cio_putchar( '\n' );
	}

	// sanity check - make sure we saw the correct number of table slots
	if( (used + empty) != N_PROCS ) {
		cio_printf( "Table size %d, used %d + empty %d = %d???\n",
					  N_PROCS, used, empty, used + empty );
	}
}

/**
** Name:    ptable_dump_counts
**
** Prints basic information about the process table (number of
** entries, number with each process state, etc.).
*/
void ptable_dump_counts( void ) {
	uint_t nstate[N_STATES] = { 0 };
	uint_t unknown = 0;

	int n = 0;
	pcb_t *ptr = ptable;
	while( n < N_PROCS ) {
		if( ptr->state < 0 || ptr->state >= N_STATES ) {
			++unknown;
		} else {
			++nstate[ptr->state];
		}
		++n;
		++ptr;
	}

	cio_printf( "Ptable: %u ***", unknown );
	for( n = 0; n < N_STATES; ++n ) {
		cio_printf( " %u %s", nstate[n],
				state_str[n] != NULL ? state_str[n] : "???" );
	}
	cio_putchar( '\n' );
}