From f32a07250f9cfbe1c7c883661a3b1b49661e9eb4 Mon Sep 17 00:00:00 2001 From: Kano Date: Tue, 20 Dec 2011 16:22:18 +1100 Subject: [PATCH] DOC related updates --- README | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ main.c | 2 +- 2 files changed, 123 insertions(+), 1 deletion(-) diff --git a/README b/README index ff24cfd5..15f5e307 100644 --- a/README +++ b/README @@ -119,6 +119,10 @@ Options for both config file and command line: cryptopp Crypto++ C/C++ implementation sse2_64 SSE2 64 bit implementation for x86_64 machines sse4_64 SSE4.1 64 bit implementation for x86_64 machines (default: sse2_64) +--api-description Description placed in the API status header (default: cgminer version) +--api-listen Listen for API requests (default: disabled) +--api-network Allow API (if enabled) to listen on/for any address (default: only 127.0.0.1) +--api-port Port number of miner API (default: 4028) --auto-fan Automatically adjust all GPU fan speeds to maintain a target temperature --auto-gpu Automatically adjust all GPU engine clock speeds to maintain a target temperature --cpu-threads|-t Number of miner CPU threads (default: 4) @@ -482,6 +486,124 @@ cgminer shuts down because of this. --- +API + +If you start cgminer with the "--api-listen" option, it will listen on a +simple TCP/IP socket for single string API requests from the same machine +running cgminer and reply with a string and then close the socket each time +Also, if you add the "--api-network" option, it will accept API requests +from any network attached computer. + +The request can be either simple text or JSON. + +If the request is JSON (starts with '{'), it will reply with a JSON formatted +response, otherwise it replies with text formatted as described further below. + +The JSON request format required is '{"command":"CMD","parameter":"PARAM"}' +(though of course parameter is not required for all requests) +where "CMD" is from the "Request" column below and "PARAM" would be e.g. +the CPU/GPU number if required. + +The format of each reply (unless stated otherwise) is a STATUS section +followed by an optional detail section + +The STATUS section is: + + STATUS=X,Code=N,Msg=string,Description=string| + + STATUS=X Where X is one of: + W - Warning + I - Informational + S - Success + E - Error + F - Fatal (code bug) + + Code=N + Each unique reply has a unigue Code (See api.c - #define MSG_NNNNNN) + + Msg=string + Message matching the Code value N + + Description=string + This defaults to the cgminer version but is the value of --api-description + if it was specified at runtime. + +The list of requests and replies are: + + Request Reply Section Details + ------- ------------- ------- + version VERSION CGMiner=cgminer version + API=API version + + summary SUMMARY The status summary of the miner + e.g. Elapsed=NNN,Found Blocks=N,Getworks=N,...| + + pools POOLS The status of each pool + e.g. Pool=0,URL=http://pool.com:6311,Status=Alive,...| + + devs DEVS Each available CPU and GPU with their details + e.g. GPU=0,Accepted=NN,MHS av=NNN,...,Intensity=D| + + gpu|N GPU The details of a single GPU number N in the same + format and details as for DEVS + + cpu|N CPU The details of a single CPU number N in the same + format and details as for DEVS + + gpucount GPUS Count=N| <- the number of GPUs + + cpucount CPUS Count=N| <- the number of CPUs + + gpuenable|N none There is no reply section just the STATUS section + stating the results of the enable request + + gpudisable|N none There is no reply section just the STATUS section + stating the results of the disable request + + gpurestart|N none There is no reply section just the STATUS section + stating the results of the restart request + + quit none There is no status section but just a single "BYE|" + reply before cgminer quits + +When you enable, disable or restart a GPU, you will also get Thread messages in +the cgminer status window + +Obviously, the JSON format is simply just the names as given before the '=' +with the values after the '=' + +If you enable cgminer debug (-D or --debug) you will also get messages showing +details of the requests received and the replies + +There are included 4 program examples for accessing the API: + +api-example.php - a php script to access the API + usAge: php api-example.php command + by default it sends a 'summary' request to the miner at 127.0.0.1:4028 + If you specify a command it will send that request instead + You must modify the line "$socket = getsock('127.0.0.1', 4028);" at the + beginning of "function request($cmd)" to change where it looks for cgminer + +API.java/API.class + a java program to access the API (with source code) + usAge is: java API command address port + Any missing or blank parameters are replaced as if you entered: + java API summary 127.0.0.1 4028 + +api-example.c - a 'C' program to access the API (with source code) + usAge: api-example [command [ip/host [port]]] + again, as above, missing or blank parameters are replaced as if you entered: + api-example summary 127.0.0.1 4028 + +miner.php - an example web page to access the API + This includes buttons to enable, disable and restart the GPUs and also to + quit cgminer + You must modify the 2 lines near the top to change where it looks for cgminer + $miner = '127.0.0.1'; # hostname or IP address + $port = 4028; + +--- + FAQ Q: cgminer segfaults when I change my shell window size. diff --git a/main.c b/main.c index cd777517..fab46ef6 100644 --- a/main.c +++ b/main.c @@ -1508,7 +1508,7 @@ static struct opt_table opt_config_table[] = { ), OPT_WITH_ARG("--api-description", set_api_description, NULL, NULL, - "Description placed in the API status header, default: cgminer"), + "Description placed in the API status header, default: cgminer version"), OPT_WITHOUT_ARG("--api-listen", opt_set_bool, &opt_api_listen, "Enable API, default: disabled"),