sctlns.cqct -- name spaces over sctl This library provides a set of Cinquecento functions for performing transactions with a sctl server. It provides two services: (1) mapping Cinquecento data structures to and from the sctl protocol encodings, and (2) exchanging sctl messages with a sctl server. The transactions supported by this library are limited to those that query name spaces. See ctls.cqct for an interface to process control transactions. Generally, if a request draws an error from the sctl server, an error is raised. Exceptions are described in the individual functions. The procedures assume that the sctl server will answer all requests synchronously and that is will not generate Aevent messages. This behavior is consistent with a sctl server that being used to serve only name space data. A typical configuration is to use one sctl server from process control, and one or more addition sctl servers for name space access. The first argument to the transaction routines is an FD argument, which should be a file descriptor connected to a sctl server. Generally the remaining arguments are Cinquecento data to be encoded into the fields of the corresponding sctl request. Most routines return a data structure representing the payload of the corresponding reply. An oddity appears in the arguments to the sctlenumtype and sctllooktype functions, which both return type definitions. These functions require an additional name space argument. This name space is used by the underlying type definition decoder (decodetdef) to resolve two aspects of type definitions that cannot be determined from the sctl type definition reply: - the mapping from enumeration representation to a corresponding base type, passed to mkctype_enum; - the representation of the pointer type, passed to mkctype_ptr. For this argument, it is sufficient to pass a root name space that is compatible with the base type definitions of the target name space. We consider this argument a bug in the interface. The snames library (snames.cqct) uses this library for reasons that need to be sorted out. This also library defines several undocumented functions for converting buffers of encoded sctl data to and from Cinquecento data structures. atnames(path) PATH: string (name of binary) returns: name space or nil Returns a name space for the binary PATH. The name space is served by a freshly launched sctl server on the calling machine (the sctl binary must be in the path of the calling process). Returns nil if the name space does not exist. mksctlns(fd, path) FD: file descriptor (to sctl server) PATH: string (name of binary) returns: name space or nil Returns a name space for the binary PATH. The name space is served by the sctl server backed by FD. A version negotiation with the sctl server must be performed before calling this function (see sctlversion). Returns nil if the name space does not exist. sctlping(FD, CNT) FD: file descriptor (to sctl server) CNT: cvalue returns: nil Performs a ping transaction with the server, sending a ping payload of CNT zero bytes. An error is raised if the transaction fails. sctlversion(FD) FD: file descriptor (to sctl server) returns: string Performs a version transaction with the sctl server. The offered version is "sctl-2012:x86-linux-2012,x86-win-2012" The negotiated version string is returned. An error is raised if the version cannot be negotiated. sctlnames(FD, PATH) FD: file descriptor (to sctl server) PATH: string (name of binary) returns: cvalue (NSID) or nil Performs a names transaction, returning a name space identifier for the name space corresponding to binary PATH. Returns nil if the name space does not exist. sctllooktype(FD, NSID, NS, TN) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) NS: name space (see discusion above) TN: ctype (type name) returns: ctype (type definition) or nil Performs a looktype transaction, returning the definition of the type TN. The returned type is a ctype representation of the type definition returned by the sctl looktype request. Note that these are incomplete type definitions. Returns nil if there is no matching type definition. sctlenumtype(FD, NSID, NS) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) NS: name space (see discusion above) returns: table mapping type name to type definition Performs an enumtype transaction, returning a table of type definitions. The keys to the table are type names; the values are corresponding type definitions. The type definitions are incomplete. sctllooksym(FD, NSID, ID) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) ID: cid (symbol identifier) returns: symbol or nil Performs a looksym transaction, obtaining a definition for the symbol ID in the name space NSID. The result is a Cinquecento symbol. Its attribute table defines "offset" to the value returned in the looksym reply, "flags" to the flags, and "size" to the size. The symbol type is an incomplete type, as in looktype. Returns nil if there is no matching symbol. sctlenumsym(FD, NSID) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) returns: list of symbol records Performs an enumsym transaction, returning a table of symbol definitions in name space NSID. The keys are symbol identifiers; the values are corresponding symbols, constructed as in sctllooksym. sctllookaddr(FD, NSID, ADDR) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) ADDR: cvalue (symbol identifier) returns: symbol record Performs a lookaddr transaction, returning a symbol definition to which ADDR maps in name space NSID. The symbol definition is a symbol, constructed as in sctllooksym. Returns nil if there is no matching symbol. sctlunwind1(FD, NSID, ADDR) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) ADDR: cvalue (program counter) returns: list of unwind rules Performs an unwind1 transaction, returning target-dependent stack frame unwinding rules corresponding to the program counter ADDR in name space NSID. Each unwind rule is a rulerec that is based on the encoding of unwind rules specified by DWARF: @record uwrulerec { kind, /* rule kind */ r, /* register operand */ n, /* number operand */ }; The library dwarf.cqct includes functions that evaluate these rules. (NB: these require a name space to pick rules based on target arch; a ctx to get regs; a domain to get memory; and maybe other dependencies. Hard to untangle into an interface that just consumes rules.) sctllooksrc(FD, NSID, ADDR) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) ADDR: cvalue (program counter) returns: source record Performs a looksrc transaction, returning a source record corresponding to the program counter ADDR in name space NSID. The source record is defined as follows: /* source record */ @record srcrec { file, /* file name (string) */ line, /* line (cvalue) */ col, /* column (cvalue */ }; Returns nil if no source location matches. sctllookpc(FD, NSID, FILE, LINE) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) FILE: string (file name) LINE: cvalue (line) returns: cvalue (program counter) Performs a lookpc transaction, returning a program counter address corresponding to the source FILE and LINE in name space NSID. Returns nil if no source location matches. sctlenumloc(FD, NSID, PC) FD: file descriptor (to sctl server) NSID: cvalue (name space identifier) PC: cvalue (program counter) returns: list of locrecs Performs an enumloc transaction, returning a list of local variable definitions. The definition of locrec is: @record locrec { id, /* name (cid) */ sz, /* size (cvalue) (FIXME: always zero!) */ ltype, /* kind (parameter or local) (cvalue) */ loc, /* location expression (lexprrec) */ type, /* type name (ctype) */ }; The definition of lexprrec is @record lexprrec { kind, /* kind (cvalue) */ no, /* register (cvalue) */ v, /* value (cvalue) */ op1, op2, /* operands (lexprrec) */ }; Returns nil if no location information is available.