Subversion Repositories openarty

////////////////////////////////////////////////////////////////////////////////
//
// Filename: 	syscall.h
//
// Project:	OpenArty, an entirely open SoC based upon the Arty platform
//
// Purpose:	User programs often need O/S support.  To get such support, they
//		call O/S functions, often named "system calls".  These functions
//	run at a different privilege level, and often even within a different
//	address space.  Therefore, making a system call usually takes a touch
//	of hardware support.  From a hardware standpoint, asking to switch to
//	a higher privilege level is called a "TRAP".
//
//	For the ZipCPU, a system call is as simple as executing the "TRAP"
//	instruction--one that just clears the GIE bit in the CC register.  This
//	can be as simple as "MOV 0,CC", or even "AND ~GIE,CC".  Of course, this
//	only works from user mode where the GIE bit is set in the first place.
//	This then transitions the CPU from user to supervisor mode, in a fashion
//	where the supervisor can now examine the user process and tell that it
//	was a trap that caused the return to supervisor mode.  To turn this
//	concept into a system call with arguments set and a potential value
//	returned, we place up to four arguments into registers R1-R4, and
//	expect R1 to have any return value.
//
//	Getting the compiler to do this (place four values into R1-R4 and issue
//	a trap instruction), however, was a nightmare.  So, instead, call a
//	function that accepts the same number of arguments (forcing GCC to
//	place them into the registers R1-R4), and we set that function up so
//	that it just does the system call assembly command listed above,
//	followed by a "JMP R0" to return from the system call.  This function,
//	because it is so tightly integrated with the compiler and system, is
//	implemented within zipsys as the assembly language routine, system().
//
//	Here, we just specify what system calls the kernel knows about, what
//	their calling conventions are, etc.  In particular, we use R1 (i.e. the
//	first argument) to reference a system call number (a.k.a. trap ID),
//	and the next three arguments can be understood in the context of the
//	system call number.
//
// Creator:	Dan Gisselquist, Ph.D.
//		Gisselquist Technology, LLC
//
////////////////////////////////////////////////////////////////////////////////
//
// Copyright (C) 2015-2016, Gisselquist Technology, LLC
//
// This program is free software (firmware): you can redistribute it and/or
// modify it under the terms of  the GNU General Public License as published
// by the Free Software Foundation, either version 3 of the License, or (at
// your option) any later version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY or
// FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
// for more details.
//
// You should have received a copy of the GNU General Public License along
// with this program.  (It's in the $(ROOT)/doc directory, run make with no
// target there if the PDF file isn't present.)  If not, see
// <http://www.gnu.org/licenses/> for a copy.
//
// License:	GPL, v3, as defined and found on www.gnu.org,
//		http://www.gnu.org/licenses/gpl.html
//
//
////////////////////////////////////////////////////////////////////////////////
//
//
#ifndef	SYSCALL_H
#define	SYSCALL_H
 
typedef	enum {
	// First two deal with interrupts:
	//	syscall(TRAPID_WAIT, intmask, timeout, ?)
	//		returns when an interrupt in intmask has taken place.
	//		May return immediately if such an interrupt has
	//		occurred between the last such syscall and this one
	//		If timeout is != 0, specifies the maximum amount of
	//			time to wait for the event to occurr.
	//		If intmask = 0, then the task will wait for a timeout
	//			alone.
	//		If the task is stalled for another reason, it may wake
	//			early from the trap when the timeout is up.
	//	syscall(TRAPID_CLEAR, intmask, timeout, ?)
	//		Same thing, except this returns immediately after
	//		clearing any potentially pending interrupts
	//		If the timeout < 0, clears any pending timeout wakeup
	//		If the timeout > 0, sets a pending timeout wakeup and
	//			returns.
	//		If the timeout == 0, it does nothing with the timeout.
	//	syscall(TRAPID_POST, intmask, ?, ?)
	//		"Posts" the events in intmask, allowing software
	//		"interrupts" to be created.  That is, if another
	//		piece of software is waiting on an event/interrupt,
	//		this can be used to wake up all such pieces of software.
	//
	TRAPID_WAIT, TRAPID_CLEAR, TRAPID_POST,
	//
	// Yield: Yields the processor until the next scheduled time slice.
	//	Takes no arguments.
	TRAPID_YIELD,
	//
	// Read/write: Implemented in much the same fashion as the Unix/Posix
	//	read/write system calls.
	TRAPID_READ, TRAPID_WRITE,
	//
	// Time: Get the 
	TRAPID_TIME,
	//
	// kreturn: Return from a kernel system call.  This is necessary if
	// ever an exception triggers a system call.  In such cases, it will be
	// impossible to return the caller back to his context in a pristine
	// manner ... without help.
	// TRAPID_KRETURN,
	//
	// Semaphore ID's.  These allow us to run the rest of the trap
	// stuffs in kernel space
	TRAPID_SEMGET, TRAPID_SEMPUT, TRAPID_SEMNEW,
	//
	TRAPID_RECV, TRAPID_SEND,
	//
	// Malloc--since we're using a system level malloc, from a system
	// heap for everything, malloc/free require system calls
	// Eventually, this call should be replaced with an sbrk() POSIX
	// system call, but not until a full MMU is implemented and passes
	// testing.
	TRAPID_MALLOC, TRAPID_FREE,
	// EXIT -- end a task
	TRAPID_EXIT
} TRAPID;
 
extern	int	syscall(const int id, const int a, const int b, const int c);
 
static inline int	read(int fid, void *buf, int ln) {
	return syscall(TRAPID_READ, fid,(int)buf,ln);
} static inline int	write(int fid, const void *buf, int ln) {
	return syscall(TRAPID_WRITE, fid, (int)buf, ln);
}
 
static inline unsigned	time(void) {
	return syscall1(TRAPID_TIME);
}
 
static inline	void	yield(void) {
	syscall(TRAPID_YIELD, 0, 0, 0);
} static inline int	wait(unsigned event_mask, int timeout) {
	return syscall(TRAPID_WAIT, (int)event_mask, timeout, 0);
} static inline int	clear(unsigned event, int timeout) {
	return syscall(TRAPID_CLEAR, (int)event, timeout, 0);
} static inline void	post(unsigned event) {
	syscall2(TRAPID_POST, (int)event);
}
 
 
// PORTS:
//	Raw ethernet
//		Just gets sent
//	Raw internet
//		(Needs to MAC via ARP, then IP)
//	UDP ports
//		Adds IP header (sip/dip/dport/sport/etc), sends to raw internet
//	TCP ports
//		Adds IP header (sip/dip/dport/sport/etc), sends to raw internet
//
static inline len	recv(unsigned port, int buflen, unsigned *buf,
			int timeout) {
	// Timeout =  0 -> wait forever
	// Port    = -1 -> system task, receive *any*/all packets
	return syscall5(TRAPID_RECV, port, buflen, buf, timeout);
}
 
static inline void	send(unsigned port, int buflen, unsigned *buf) {
	syscall(TRAPID_SEND, port, buflen, buf);
}
 
static inline	void *malloc(unsigned nbytes) {
	return (void *)syscall2(TRAPID_MALLOC, (int)nbytes0, 0);
} static inline void	free(void *buf) {
	syscall2(TRAPID_FREE,(int)buf);
}
 
static inline void	exit(int status) {
	syscall2(TRAPID_EXIT,status);
}
 
#endif