1// Defines the text format for including per-op API definition and 2// overrides for client language op code generators. 3 4syntax = "proto3"; 5 6package tensorflow; 7 8import "tensorflow/core/framework/attr_value.proto"; 9 10option cc_enable_arenas = true; 11option java_outer_classname = "ApiDefProtos"; 12option java_multiple_files = true; 13option java_package = "org.tensorflow.framework"; 14option go_package = "github.com/tensorflow/tensorflow/tensorflow/go/core/framework/api_def_go_proto"; 15 16// Used to specify and override the default API & behavior in the 17// generated code for client languages, from what you would get from 18// the OpDef alone. There will be a set of ApiDefs that are common 19// to all client languages, and another set per client language. 20// The per-client-language ApiDefs will inherit values from the 21// common ApiDefs which it can either replace or modify. 22// 23// We separate the API definition from the OpDef so we can evolve the 24// API while remaining backwards compatible when interpreting old 25// graphs. Overrides go in an "api_def.pbtxt" file with a text-format 26// ApiDefs message. 27// 28// WARNING: Be *very* careful changing the API for any existing op -- 29// you can change the semantics of existing code. These changes may 30// need to wait until a major release of TensorFlow to avoid breaking 31// our compatibility promises. 32message ApiDef { 33 // Name of the op (in the OpDef) to specify the API for. 34 string graph_op_name = 1; 35 // If this op is deprecated, set deprecation message to the message 36 // that should be logged when this op is used. 37 // The message should indicate alternative op to use, if any. 38 string deprecation_message = 12; 39 // Major version when the op will be deleted. For e.g. set this 40 // value to 2 if op API should be removed in TensorFlow 2.0 and 41 // deprecated in versions before that. 42 int32 deprecation_version = 13; 43 44 enum Visibility { 45 // Normally this is "VISIBLE" unless you are inheriting a 46 // different value from another ApiDef. 47 DEFAULT_VISIBILITY = 0; 48 // Publicly visible in the API. 49 VISIBLE = 1; 50 // Do not include this op in the generated API. If visibility is 51 // set to 'SKIP', other fields are ignored for this op. 52 SKIP = 2; 53 // Hide this op by putting it into an internal namespace (or whatever 54 // is appropriate in the target language). 55 HIDDEN = 3; 56 } 57 Visibility visibility = 2; 58 59 // If you specify any endpoint, this will replace all of the 60 // inherited endpoints. The first endpoint should be the 61 // "canonical" endpoint, and should not be deprecated (unless all 62 // endpoints are deprecated). 63 message Endpoint { 64 // Name should be either like "CamelCaseName" or 65 // "Package.CamelCaseName". Client-language-specific ApiDefs may 66 // use a snake_case convention instead of CamelCase. 67 string name = 1; 68 69 // Set if this endpoint is deprecated. If set to true, a message suggesting 70 // to use a non-deprecated endpoint instead will be printed. If all 71 // endpoints are deprecated, set deprecation_message in ApiDef instead. 72 bool deprecated = 3; 73 74 // Major version when an endpoint will be deleted. For e.g. set this 75 // value to 2 if endpoint should be removed in TensorFlow 2.0 and 76 // deprecated in versions before that. 77 int32 deprecation_version = 4; 78 } 79 repeated Endpoint endpoint = 3; 80 81 message Arg { 82 string name = 1; 83 84 // Change the name used to access this arg in the API from what 85 // is used in the GraphDef. Note that these names in `backticks` 86 // will also be replaced in the summary & description fields. 87 string rename_to = 2; 88 89 // Note: this will replace any inherited arg doc. There is no 90 // current way of modifying arg descriptions (other than replacing 91 // them entirely) as can be done with op descriptions. 92 string description = 3; 93 } 94 repeated Arg in_arg = 4; 95 repeated Arg out_arg = 5; 96 // List of original in_arg names to specify new argument order. 97 // Length of arg_order should be either empty to keep current order 98 // or match size of in_arg. 99 repeated string arg_order = 11; 100 101 // Description of the graph-construction-time configuration of this 102 // Op. That is to say, this describes the attr fields that will 103 // be specified in the NodeDef. 104 message Attr { 105 string name = 1; 106 107 // Change the name used to access this attr in the API from what 108 // is used in the GraphDef. Note that these names in `backticks` 109 // will also be replaced in the summary & description fields. 110 string rename_to = 2; 111 112 // Specify a new default value to use for this attr. This default 113 // will be used when creating new graphs, as opposed to the 114 // default in the OpDef, which will be used when interpreting old 115 // GraphDefs. 116 AttrValue default_value = 3; 117 118 // Note: this will replace any inherited attr doc, there is no current 119 // way of modifying attr descriptions as can be done with op descriptions. 120 string description = 4; 121 } 122 repeated Attr attr = 6; 123 124 // One-line human-readable description of what the Op does. 125 string summary = 7; 126 127 // Additional, longer human-readable description of what the Op does. 128 string description = 8; 129 130 // Modify an existing/inherited description by adding text to the beginning 131 // or end. 132 string description_prefix = 9; 133 string description_suffix = 10; 134} 135 136message ApiDefs { 137 repeated ApiDef op = 1; 138} 139