// Spawn a child process from a program image loaded from the file system.
// 执行一个从文件系统中读取的程序。
// prog: the pathname of the program to run.
// argv: pointer to null-terminated array of pointers to strings,
// 	 which will be passed to the child as its command-line arguments.
// Returns child envid on success, < 0 on failure.

// 参数说明：prog为待执行程序的路径名，argv为待执行程序所需要的参数
int
spawn(const char *prog, const char **argv)
{
	unsigned char elf_buf[512];
	struct Trapframe child_tf;
	envid_t child;

	int fd, i, r;
	struct Elf *elf;
	struct Proghdr *ph;
	int perm;

	// This code follows this procedure:
	//
	//   - Open the program file.
	//
	//   - Read the ELF header, as you have before, and sanity check its
	//     magic number.  (Check out your load_icode!)
	//
	//   - Use sys_exofork() to create a new environment.【新的Env结构】
	//
	//   - Set child_tf to an initial struct Trapframe for the child.
	//		调用系统调用sys_env_set_trapframe()
    // 		设置新的Env结构的Trapframe字段(该字段包含寄存器信息)
	//   - Call the init_stack() function above to set up
	//     the initial stack page for the child environment.
	//
	//   - Map all of the program's segments that are of p_type
	//     ELF_PROG_LOAD into the new environment's address space.
	//     Use the p_flags field in the Proghdr for each segment
	//     to determine how to map the segment:
	//		根据ELF文件中program header，将用户程序以Segment读入内存，并映射到指定的线性地址处
	//	* If the ELF flags do not include ELF_PROG_FLAG_WRITE,
	//	  then the segment contains text and read-only data.
	//	  Use read_map() to read the contents of this segment,
	//	  and map the pages it returns directly into the child
	//        so that multiple instances of the same program
	//	  will share the same copy of the program text.
	//        Be sure to map the program text read-only in the child.
	//        Read_map is like read but returns a pointer to the data in
	//        *blk rather than copying the data into another buffer.
	//
	//	* If the ELF segment flags DO include ELF_PROG_FLAG_WRITE,
	//	  then the segment contains read/write data and bss.
	//	  As with load_icode() in Lab 3, such an ELF segment
	//	  occupies p_memsz bytes in memory, but only the FIRST
	//	  p_filesz bytes of the segment are actually loaded
	//	  from the executable file - you must clear the rest to zero.
	//        For each page to be mapped for a read/write segment,
	//        allocate a page in the parent temporarily at UTEMP,
	//        read() the appropriate portion of the file into that page
	//	  and/or use memset() to zero non-loaded portions.
	//	  (You can avoid calling memset(), if you like, if
	//	  page_alloc() returns zeroed pages already.)
	//        Then insert the page mapping into the child.
	//        Look at init_stack() for inspiration.
	//        Be sure you understand why you can't use read_map() here.
	//
	//     Note: None of the segment addresses or lengths above
	//     are guaranteed to be page-aligned, so you must deal with
	//     these non-page-aligned values appropriately.
	//     The ELF linker does, however, guarantee that no two segments
	//     will overlap on the same page; and it guarantees that
	//     PGOFF(ph->p_offset) == PGOFF(ph->p_va).
	//
	//   - Call sys_env_set_trapframe(child, &child_tf) to set up the
	//     correct initial eip and esp values in the child.
	//		
	//   - Start the child process running with sys_env_set_status().
    //	调用系统调用sys_env_set_status()设置新的Env结构状态为ENV_RUNABLE。

	if ((r = open(prog, O_RDONLY)) < 0)
		return r;
	fd = r;	

	// Read elf header
    // 1.基于之前实现file system和IPC通信，读取ELF文件
	elf = (struct Elf*) elf_buf;
	if (readn(fd, elf_buf, sizeof(elf_buf)) != sizeof(elf_buf)
	    || elf->e_magic != ELF_MAGIC) {
		close(fd);
		cprintf("elf magic %08x want %08x\n", elf->e_magic, ELF_MAGIC);
		return -E_NOT_EXEC;
	}

	// Create new child environment
    // 2.调用fork，创建子进程
	if ((r = sys_exofork()) < 0)
		return r;
	child = r;

	// Set up trap frame, including initial stack.
	child_tf = envs[ENVX(child)].env_tf;
	child_tf.tf_eip = elf->e_entry;
	
    //这个函数计算了参数的字符串长度，以及指向这些字符串所需要的空间，还有argc和null-terminate的空间
    //存放在UTEMP+PGSIZE-string_len-argc*pointer_size-2的位置【这将会最终被复制到进程空间的栈帧的底部】
    //在UTEMP附近位置构建用户栈底的样式【argc、argv指针以及agrv指向的字符串】
	//之后给传入的第三个参数&child_tf.tf_esp进行赋值，设置栈顶esp为USTACK附近留足以上空间的地方。
    //最后就是把当前进程的UTEMP页映射到child进程的USTACKTOP - PGSIZE位置，从而构成child进程的栈帧
    //最最后，解除当前进程的UTEMP页映射【其实这个页就是一个中转的作用】
	if ((r = init_stack(child, argv, &child_tf.tf_esp)) < 0)
		return r;

	// Set up program segments as defined in ELF header.
    // 3.接下来就是解析ELF文件，加载type为LOAD的段
	ph = (struct Proghdr*) (elf_buf + elf->e_phoff);
	for (i = 0; i < elf->e_phnum; i++, ph++) {
		if (ph->p_type != ELF_PROG_LOAD)
			continue;
		perm = PTE_P | PTE_U;
		if (ph->p_flags & ELF_PROG_FLAG_WRITE)
			perm |= PTE_W;
		if ((r = map_segment(child, ph->p_va, ph->p_memsz,
				     fd, ph->p_filesz, ph->p_offset, perm)) < 0)
			goto error;
	}
	close(fd);	//关闭文件描述符【会把文件系统进程内存中的dirty块flush到磁盘里】
	fd = -1;	//并且设置fd = -1【避免Use after free类似的问题】

	// Copy shared library state.
    // 3.exercise 8需要实现
	if ((r = copy_shared_pages(child)) < 0)
		panic("copy_shared_pages: %e", r);

	child_tf.tf_eflags |= FL_IOPL_3;   // devious: see user/faultio.c
	if ((r = sys_env_set_trapframe(child, &child_tf)) < 0)	//exercise 7需要实现
		panic("sys_env_set_trapframe: %e", r);

	if ((r = sys_env_set_status(child, ENV_RUNNABLE)) < 0)	//设置程序状态为可执行
		panic("sys_env_set_status: %e", r);
	
    //返回spawn生成的子进程id，之后这个子进程会被调度的【因为状态是ENV_RUNNABLE
	return child;	

error:
	sys_env_destroy(child);
	close(fd);
	return r;
}

// Set envid's trap frame to 'tf'.
// tf is modified to make sure that user environments always run at code
// protection level 3 (CPL 3), interrupts enabled, and IOPL of 0.
//
// Returns 0 on success, < 0 on error.  Errors are:
//	-E_BAD_ENV if environment envid doesn't currently exist,
//		or the caller doesn't have permission to change envid.
static int
sys_env_set_trapframe(envid_t envid, struct Trapframe *tf)
{
	// LAB 5: Your code here.
	// Remember to check whether the user has supplied us with a good
	// address!
	int r;
	struct Env *e;
	if((r = envid2env(envid,&e,1)) < 0) return r;
    // The trap frame should be modified to run at Ring 3 (the lowest 2 bits of CS and SS register should set to 3)
    tf->tf_cs |= 3;
    tf->tf_ss |= 3;
    //interrupts enabled (set the IF bit in EFLAGS), and IOPL of 0 (clear the 2-bit IOPL field in EFLAGS).
	tf->tf_eflags |= FL_IF;
	tf->tf_eflags &= ~FL_IOPL_MASK;	//no need permission for IO
	e->env_tf = *tf;
	return 0;
	// panic("sys_env_set_trapframe not implemented");
}

case SYS_env_set_trapframe:
    return sys_env_set_trapframe(a1, (struct Trapframe *)a2);

addr = (void*)((uint32_t)pn*PGSIZE);
pte = uvpt[pn];
+ if(pte & PTE_SHARE){
+    r = sys_page_map(0, addr, envid, addr, pte & PTE_SYSCALL);
+    if(r != 0){
+        panic("duppage error for child! va: %08x, error:%08x\n", addr, r);
+    }
+ }
+ else if((pte & PTE_COW) || (pte & PTE_W)){

// Copy the mappings for shared pages into the child address space.
static int
copy_shared_pages(envid_t child)
{
	// LAB 5: Your code here.
	uintptr_t addr;
	for(addr = 0; addr < UXSTACKTOP; addr += PGSIZE){
		if((uvpd[PDX(addr)] & PTE_P) && (uvpt[PGNUM(addr)] & PTE_P) && 
		(uvpt[PGNUM(addr)] & PTE_U) && (uvpt[PGNUM(addr)] & PTE_SHARE)) {
			int r =sys_page_map(0, (void *)addr, child, (void *)addr, (uvpt[PGNUM(addr)] & PTE_SYSCALL));
			if(r != 0){
				panic("copy_shared_pages for child!va:%08x,error:%08x\n",addr,r);
				return r;
			}
		}
	}
	return 0;
}

static void
trap_dispatch(struct Trapframe *tf)
{
	// Handle processor exceptions.
	// LAB 3: Your code here.
	struct PushRegs *regs;
	switch (tf->tf_trapno)
	{
	/* …… */
	case IRQ_OFFSET + IRQ_KBD:
		kbd_intr();
		return;
	case IRQ_OFFSET + IRQ_SERIAL:
		serial_intr();
		return;
	default:
		break;
	}
    /* …… */   
}
//kbd_intr和serial_intr最终都调用了cons_intr来将字符输入到circular console input buffer.
// called by device interrupt routines to feed input characters
// into the circular console input buffer.
static void
cons_intr(int (*proc)(void))
{
	int c;	//对于proc
	//调用函数指针proc获取当前从设备输入的字符
    //kbd_intr和serial_intr的proc函数指针中都使用了inb指令从特定于设备的端口读取字符并返回。
	while ((c = (*proc)()) != -1) {
		if (c == 0)
			continue;
		cons.buf[cons.wpos++] = c;
		if (cons.wpos == CONSBUFSIZE)
			cons.wpos = 0;
	}
}

r = spawnl("/init", "init", "initarg1", "initarg2", (char*)0)

//↓ init.c
// being run directly from kernel, so no file descriptors open yet
close(0);
if ((r = opencons()) < 0)
    panic("opencons: %e", r);
if (r != 0)
    panic("first opencons used fd %d", r);
if ((r = dup(0, 1)) < 0)
    panic("dup: %e", r);
while (1) {
    cprintf("init: starting sh\n");
    r = spawnl("/sh", "sh", (char*)0);
    if (r < 0) {
        cprintf("init: spawn sh: %e\n", r);
        continue;
    }
    wait(r);
}
//↓ sh.c
while (1) {
    char *buf;

    buf = readline(interactive ? "$ " : NULL);
    if (buf == NULL) {
        if (debug)
            cprintf("EXITING\n");
        exit();	// end of file
    }
    if (debug)
        cprintf("LINE: %s\n", buf);
    if (buf[0] == '#')
        continue;
    if (echocmds)
        printf("# %s\n", buf);
    if (debug)
        cprintf("BEFORE FORK\n");
    if ((r = fork()) < 0)
        panic("fork: %e", r);
    if (debug)
        cprintf("FORK: %d\n", r);
    if (r == 0) {
        runcmd(buf);	//调用runcmd，解析console的参数，并执行命令
        exit();
    } else
        wait(r);
}

//user/sh.c的在runcmd函数中添加如下片段：
case '<':	// Input redirection
    // Grab the filename from the argument list
	// gettoken 负责解析命令行参数, 所以对于 command < filename，t的值会变成filename
    if (gettoken(0, &t) != 'w') {
        cprintf("syntax error: < not followed by word\n");
        exit();
    }
    // Open 't' for reading as file descriptor 0
    // (which environments use as standard input).
    // We can't open a file onto a particular descriptor,
    // so open the file as 'fd',
    // then check whether 'fd' is 0.
    // If not, dup 'fd' onto file descriptor 0,
    // then close the original 'fd'.

    // LAB 5: Your code here.
    if((fd = open(t, O_RDONLY)) < 0){
        cprintf("open %s for read: %e", t, fd);
        exit();
    }
    if(fd != 0){
        if((r = dup(fd, 0)<0)){
            panic("duplicate error!");
        }
        close(fd);
    }
    break;

struct Argstate {
    int *argc;
    const char **argv;
    const char *curarg;
    const char *argvalue;
};

// Shift arguments down one
args->curarg = args->argv[1] + 1;
memmove(args->argv + 1, args->argv + 2, sizeof(const char *) * (*args->argc - 1));
(*args->argc)--;