Details of Syscall.RawSyscall() & Syscall.Syscall() in Go?

Question

I'm reading source code in package syscall now, and met some problems:

Since I'm totally a noob of syscall and assembly, so don't hesitate to share anything you know about it :)

First about func RawSyscall(trap, a1, a2, a3 uintptr) (r1, r2 uintptr, err Errno) : what does its parameter trap, a1, a2, a3 & return value r1 r2 means? I've searched documents and site but seems lack of description about this.

Second, since I'm using darwin/amd64 I searched source code and find it here: http://golang.org/src/pkg/syscall/asm_darwin_amd64.s?h=RawSyscall

Seems it's written by assemble(which I can't understand), can you explain what happened in line 61-80, and what's the meaning of ok1: part under line 76?

I also found some code in http://golang.org/src/pkg/syscall/zsyscall_darwin_amd64.go , what does zsyscall mean in its filename?

What's the difference between syscall & rawsyscall?

How and when to use them if I want to write my own syscall function(Yes, os package gave many choices but there are still some situation it doesn't cover)?

So many noob questions, thanks for your patience to read and answer :)

Answer 1

I'll share my reduced assembly knowledge with you:

61  TEXT ·RawSyscall(SB),7,$0
62      MOVQ    16(SP), DI
63      MOVQ    24(SP), SI
64      MOVQ    32(SP), DX
65      MOVQ    $0, R10
66      MOVQ    $0, R8
67      MOVQ    $0, R9
68      MOVQ    8(SP), AX   // syscall entry
69      ADDQ    $0x2000000, AX
70      SYSCALL
71      JCC ok1
72      MOVQ    $-1, 40(SP) // r1
73      MOVQ    $0, 48(SP)  // r2
74      MOVQ    AX, 56(SP)  // errno
75      RET
76  ok1:
77      MOVQ    AX, 40(SP)  // r1
78      MOVQ    DX, 48(SP)  // r2
79      MOVQ    $0, 56(SP)  // errno
80      RET
81  

• Line 61 is the routine entry point
• Line 76 is a label called ok1
• Line 71 is a conditional jump to label ok1.

The short names you see on every line on the left side are called mnemonics and stand for assembly instructions:

• MOVQ means Move Quadword (64 bits of data).
• ADDQ is Add Quadword.
• SYSCALL is kinda obvious
• JCC is Jump if Condition (condition flag set by previous instruction)
• RET is return

On the right side of the mnemonics you'll find each instruction's arguments which are basically constants and registers.

• SP is the Stack Pointer
• AX is the Accumulator
• BX is the Base register

each register can hold a certain amount of data. On 64 bit CPU architectures I believe it's in fact 64 bits per register.

The only difference between Syscall and RawSyscall is on line 14, 28 and 34 where Syscall will call runtime·entersyscall(SB) and runtime·exitsyscall(SB) whereas RawSyscall will not. I assume this means that Syscall notifies the runtime that it's switched to a blocking syscall operations and can yield CPU-time to another goroutine/thread whereas RawSyscall will just block.