root/core/ptp.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   1 #ifndef __CHDK_PTP_H
   2 #define __CHDK_PTP_H
   3 
   4 // CHDK PTP protocol interface (can also be used in client PTP programs)
   5 
   6 // Note: used in modules and platform independent code. 
   7 // Do not add platform dependent stuff in here (#ifdef/#endif compile options or camera dependent values)
   8 
   9 #define PTP_CHDK_VERSION_MAJOR 2  // increase only with backwards incompatible changes (and reset minor)
  10 #define PTP_CHDK_VERSION_MINOR 8  // increase with extensions of functionality
  11                                   // minor > 1000 for development versions
  12 
  13 /*
  14 protocol version history
  15 0.1 - initial proposal from mweerden, + luar
  16 0.2 - Added ScriptStatus and ScriptSupport, based on work by ultimA
  17 1.0 - removed old script result code (luar), replace with message system
  18 2.0 - return PTP_CHDK_TYPE_TABLE for tables instead of TYPE_STRING, allow return of empty strings
  19 2.1 - experimental live view, not formally released
  20 2.2 - live view (work in progress)
  21 2.3 - live view - released in 1.1
  22 2.4 - live view protocol 2.1
  23 2.5 - remote capture
  24 2.6 - script execution flags
  25 2.7 - IN DEVELOPMENT live view protocol 2.2
  26 2.8 - IN DEVELOPMENT GetMemory extensions
  27 */
  28 
  29 #define PTP_OC_CHDK 0x9999
  30 
  31 // N.B.: unused parameters should be set to 0
  32 enum ptp_chdk_command {
  33   PTP_CHDK_Version = 0,     // return param1 is major version number
  34                             // return param2 is minor version number
  35   PTP_CHDK_GetMemory,       // param2 is base address (direct may fail on MMIO etc. Use buffered for those)
  36                             // param3 is size (in bytes)
  37                             // param4 is options: 0 read directly, 1 buffer. Other values reserved
  38                             // return data is memory block
  39   PTP_CHDK_SetMemory,       // param2 is address
  40                             // param3 is size (in bytes)
  41                             // data is new memory block
  42   PTP_CHDK_CallFunction,    // data is array of function pointer and 32 bit int arguments (max: 10 args prior to protocol 2.5)
  43                             // return param1 is return value
  44   PTP_CHDK_TempData,        // data is data to be stored for later
  45                             // param2 is for the TD flags below
  46   PTP_CHDK_UploadFile,      // data is 4-byte length of filename, followed by filename and contents
  47   PTP_CHDK_DownloadFile,    // preceded by PTP_CHDK_TempData with filename
  48                             // return data are file contents
  49   PTP_CHDK_ExecuteScript,   // data is script to be executed
  50                             // param2 is language of script
  51                             //  in proto 2.6 and later, language is the lower byte, rest is used for PTP_CHDK_SCRIPT_FL* flags
  52                             // return param1 is script id, like a process id
  53                             // return param2 is status from ptp_chdk_script_error_type
  54   PTP_CHDK_ScriptStatus,    // Script execution status
  55                             // return param1 bits
  56                             // PTP_CHDK_SCRIPT_STATUS_RUN is set if a script running, cleared if not
  57                             // PTP_CHDK_SCRIPT_STATUS_MSG is set if script messages from script waiting to be read
  58                             // all other bits and params are reserved for future use
  59   PTP_CHDK_ScriptSupport,   // Which scripting interfaces are supported in this build
  60                             // param1 CHDK_PTP_SUPPORT_LUA is set if lua is supported, cleared if not
  61                             // all other bits and params are reserved for future use
  62   PTP_CHDK_ReadScriptMsg,   // read next message from camera script system
  63                             // return param1 is chdk_ptp_s_msg_type
  64                             // return param2 is message subtype:
  65                             //   for script return and users this is ptp_chdk_script_data_type
  66                             //   for error ptp_chdk_script_error_type
  67                             // return param3 is script id of script that generated the message
  68                             // return param4 is length of the message data. 
  69                             // return data is message.
  70                             // A minimum of 1 bytes of zeros is returned if the message has no data (empty string or type NONE)
  71   PTP_CHDK_WriteScriptMsg,  // write a message for scripts running on camera
  72                             // input param2 is target script id, 0=don't care. Messages for a non-running script will be discarded
  73                             // data length is handled by ptp data phase
  74                             // input messages do not have type or subtype, they are always a string destined for the script (similar to USER/string)
  75                             // output param1 is ptp_chdk_script_msg_status
  76   PTP_CHDK_GetDisplayData,  // Return camera display data
  77                             // This is defined as separate sub protocol in live_view.h
  78                             // Changes to the sub-protocol will always be considered a minor change to the main protocol
  79                             //  param2 bitmask of data
  80                             //  output param1 = total size of data
  81                             //  return data is protocol information, frame buffer descriptions and selected display data
  82                             //  Currently a data phase is always returned. Future versions may define other behavior 
  83                             //  for values in currently unused parameters.
  84   // Direct image capture over USB.
  85   // Use lua get_usb_capture_support for available data types, lua init_usb_capture for setup
  86   PTP_CHDK_RemoteCaptureIsReady, // Check if data is available
  87                                  // return param1 is status 
  88                                  //  0 = not ready
  89                                  //  0x10000000 = remote capture not initialized
  90                                  //  otherwise bitmask of PTP_CHDK_CAPTURE_* datatypes
  91                                  // return param2 is image number
  92   PTP_CHDK_RemoteCaptureGetData  // retrieve data
  93                                  // param2 is bit indicating data type to get
  94                                  // return param1 is length
  95                                  // return param2 more chunks available?
  96                                  //  0 = no more chunks of selected format
  97                                  // return param3 seek required to pos (-1 = no seek)
  98 };
  99 
 100 // data types as used by ReadScriptMessage
 101 enum ptp_chdk_script_data_type {
 102   PTP_CHDK_TYPE_UNSUPPORTED = 0, // type name will be returned in data
 103   PTP_CHDK_TYPE_NIL,
 104   PTP_CHDK_TYPE_BOOLEAN,
 105   PTP_CHDK_TYPE_INTEGER,
 106   PTP_CHDK_TYPE_STRING, // Empty strings are returned with length=0
 107   PTP_CHDK_TYPE_TABLE,  // tables are converted to a string by usb_msg_table_to_string, 
 108                         // this function can be overridden in lua to change the format
 109                         // the string may be empty for an empty table
 110 };
 111 
 112 // TempData flags
 113 #define PTP_CHDK_TD_DOWNLOAD  0x1  // download data instead of upload
 114 #define PTP_CHDK_TD_CLEAR     0x2  // clear the stored data; with DOWNLOAD this
 115                                    // means first download, then clear and
 116                                    // without DOWNLOAD this means no uploading,
 117                                    // just clear
 118 
 119 // Script Languages - for execution only lua is supported for now
 120 #define PTP_CHDK_SL_LUA    0
 121 #define PTP_CHDK_SL_UBASIC 1
 122 #define PTP_CHDK_SL_MASK 0xFF
 123 
 124 // bit flags for script start
 125 #define PTP_CHDK_SCRIPT_FL_NOKILL           0x100 // if script is running return error instead of killing
 126 #define PTP_CHDK_SCRIPT_FL_FLUSH_CAM_MSGS   0x200 // discard existing cam->host messages before starting
 127 #define PTP_CHDK_SCRIPT_FL_FLUSH_HOST_MSGS  0x400 // discard existing host->cam messages before starting
 128 
 129 // bit flags for script status
 130 #define PTP_CHDK_SCRIPT_STATUS_RUN   0x1 // script running
 131 #define PTP_CHDK_SCRIPT_STATUS_MSG   0x2 // messages waiting
 132 // bit flags for scripting support
 133 #define PTP_CHDK_SCRIPT_SUPPORT_LUA  0x1
 134 
 135 
 136 // GetMemory modes
 137 #define PTP_CHDK_GETMEM_MODE_DIRECT   0x0 // default, using Canon send_data (DMA), may fail on MMIO or TCM
 138 #define PTP_CHDK_GETMEM_MODE_BUFFER   0x1 // buffered with memcpy, slower. May not be correct for MMIO but seems to work
 139 
 140 // bit flags for remote capture
 141 // used to select and also to indicate available data in PTP_CHDK_RemoteCaptureIsReady
 142 /*
 143 Full jpeg file. Note supported on all cameras, use Lua get_usb_capture_support to check
 144 */
 145 #define PTP_CHDK_CAPTURE_JPG    0x1 
 146 
 147 /*
 148 Raw framebuffer data, in camera native format.
 149 A subset of rows may be requested in init_usb_capture.
 150 */
 151 #define PTP_CHDK_CAPTURE_RAW    0x2
 152 
 153 /*
 154 DNG header. 
 155 The header will be DNG version 1.3
 156 Does not include image data, clients wanting to create a DNG file should also request RAW
 157 Raw data for all known cameras will be packed, little endian. Client is responsible for
 158 reversing the byte order if creating a DNG.
 159 Can requested without RAW to get sensor dimensions, exif values etc.
 160 
 161 ifd 0 specifies a 128x96 RGB thumbnail, 4 byte aligned following the header
 162 client is responsible for generating thumbnail data.
 163 
 164 ifd 0 subifd 0 specifies the main image
 165 The image dimensions always contain the full sensor dimensions, if a sub-image was requested
 166 with init_usb_capture, the client is responsible for padding the data to the full image or
 167 adjusting dimensions.
 168 
 169 Bad pixels will not be patched, but DNG opcodes will specify how to patch them
 170 */
 171 #define PTP_CHDK_CAPTURE_DNGHDR 0x4  
 172 
 173 // status from PTP_CHDK_RemoteCaptureIsReady if capture not enabled
 174 #define PTP_CHDK_CAPTURE_NOTSET 0x10000000
 175 
 176 // message types
 177 enum ptp_chdk_script_msg_type {
 178     PTP_CHDK_S_MSGTYPE_NONE = 0, // no messages waiting
 179     PTP_CHDK_S_MSGTYPE_ERR,      // error message
 180     PTP_CHDK_S_MSGTYPE_RET,      // script return value
 181     PTP_CHDK_S_MSGTYPE_USER,     // message queued by script
 182 // TODO chdk console data ?
 183 };
 184 
 185 // error subtypes for PTP_CHDK_S_MSGTYPE_ERR and script startup status
 186 enum ptp_chdk_script_error_type {
 187     PTP_CHDK_S_ERRTYPE_NONE = 0,
 188     PTP_CHDK_S_ERRTYPE_COMPILE,
 189     PTP_CHDK_S_ERRTYPE_RUN,
 190     // the following are for ExecuteScript status only, not message types
 191     PTP_CHDK_S_ERR_SCRIPTRUNNING = 0x1000, // script already running with NOKILL
 192 };
 193 
 194 // message status
 195 enum ptp_chdk_script_msg_status {
 196     PTP_CHDK_S_MSGSTATUS_OK = 0, // queued ok
 197     PTP_CHDK_S_MSGSTATUS_NOTRUN, // no script is running
 198     PTP_CHDK_S_MSGSTATUS_QFULL,  // queue is full
 199     PTP_CHDK_S_MSGSTATUS_BADID,  // specified ID is not running
 200 };
 201 
 202 #endif // __CHDK_PTP_H

/* [<][>][^][v][top][bottom][index][help] */