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