ctls -- control executions This library provides Cinquecento objects and functions for manipulating program executions. Basic concepts: mux -- multiplexor for sctl connection ctl -- represent one execution ctx -- opaque context (dialects) ctx->pc, ctx->sp, ctx->fp Need terminology for the subdivision of domains within a ctl. Programming model. Event driven: - mux run loop mux.run([pred]) By default, run until there are no more executing ctls. We can leave behind a trail of snap shots, and review the executions via the snapshots. [Corresponding trail of printfs?] mksctlmux() returns: sctlmux Returns a new sctlmux backed by a freshly launched sctl server on the calling machine. ctllaunch(mux, cmd) MUX: sctlmux CMD: list of strings returns: ctl or nil MUX is a sctlmux. CMD is the list of arguments used to exec the program, i.e., CMD[0] becomes argv[0], and so on. The program is launched using the sctl launch transaction. The resulting ctl represents the new program execution, paused just before execution of its first instruction. Each ctl implements the following methods: - id() returns: cvalue Returns a numeric identifier for the ctl. - exe() returns: domain Returns a domain representing the executable of the ctl. - ctx() returns: context Returns the current context of the ctl. - detach() returns: nil Releases control of the underlying process. Future operations on the ctl are invalid. - kill() returns: nil Like detach, but also terminates execution of the process. - stat() returns: lists Returns two lists (as multiple return values). The first is a list of region records describing mapped locations of memory. The second is a list of dynamically loaded libraries within the process. - mem() returns: address space Returns an address space corresponding to the target process memory. - snap() returns: ctl Returns a ctl representing a snapshot of the target process. - trap(event[,arg,...],fn) event: symbol (specifying type of event) arg: event-dependent fn: function (event handler) returns: cvalue (trap identifier) - clear(id) id: cvalue (trap identifier) returns: nil - traps() returns: list Trap sets a trap on various events, identified by EVENT and the event-specific set of arguments, that may occur to the target. FN is a handler to be called in respond to the event. Handlers are called in the order they are registered. The return value is an identifier that may be passed to clear to prevent future triggering of the event handler. Traps returns a list of trap records describing all currently registered traps on the ctl. @record traprec { tid, /* user-visible trap identifier */ sid, /* sctl trap identifier (not for user) */ type, /* type of trap */ args, /* trap configuration arguments */ fn /* trap handler */ }; The system registers traps for its own internal state management on each ctl. These traps are visible from the traps() interface, but they should not be tampered with. The trap types are as follows: 'brk, 'snap -- trap on execution One argument: the address at which to trap. The handler is called when execution reaches the address. The handler is passed the ctl. Snap differs from brk in that a fresh ctl representing a snapshot of the trapping process is passed, instead of the original ctl. 'exit -- trap on exit No arguments. The handler is called before [FIX] the target has terminated. No further execution will occur; the target is terminated after the handler (and any others for this event) returns. The handler is passed the ctl of the exiting target. 'load, 'unload -- trap on library load or unload No arguments. The handler is called when the target has updated its address space by loading or unloading a library from its address space. Along with the ctl, the handler is passed the path and base address of the affected library. The nsmap of the ctl is updated prior to calling the handler. 'exec -- trap on exec No arguments. The handler is called when the target has successfully called the exec system call. The handler is passed the ctl of the target process. All previously registered brk and snap events on the ctl are cleared. 'syscall -- trap on syscall No arguments. The handler is called when the target has entered or exited a system call. (It is up to the handler to figure out which.) The handler is passed the ctl of the target process. 'signal -- trap on signal No arguments. The handler is called when a signal is about to be posted to the target. The handler is passed the ctl of the target process. 'fork, 'clone -- trap on process creation No arguments. The handler is called when the target has spawned a new process. The handler is passed the ctl and a new ctl representing the new process. - ldom([ctx]) Returns a local domain representing the local variables (including function parameters) defined in the control context CTX of the ctl. If CTX is omitted, the current context is used. - unwind() returns: list of contexts Unwinds the current call stack of the ctl, returning a list of contexts corresponding to each call frame. The current call frame appears first in the list, followed by its caller, and so on. - looksrc(addr) Returns a source record [link] specifying the location in source code corresponding to ADDR. Returns nil if no source location matches. - lookpc(file,line[,name]) Returns an address corresponding to the source location FILE:LINE in the name space matched by NAME. If NAME is omitted, then the exectuable is searched. - ns([idx]) If idx is a cvalue, treat as address and build dom. If idx is a string, treat as name to match. If idx is unspecified, return the executable's - dom([idx]) idx: cvalue or string Similar.