{"id":27940734,"url":"https://github.com/telecominfraproject/oopt-tai","last_synced_at":"2025-05-07T10:20:16.304Z","repository":{"id":30111944,"uuid":"122727969","full_name":"Telecominfraproject/oopt-tai","owner":"Telecominfraproject","description":"TIP OOPT - Transponder Abstraction Interface","archived":false,"fork":false,"pushed_at":"2023-02-07T05:43:53.000Z","size":8915,"stargazers_count":46,"open_issues_count":5,"forks_count":30,"subscribers_count":56,"default_branch":"master","last_synced_at":"2024-07-26T20:38:41.571Z","etag":null,"topics":["networking","oopt","sai","tai","tip","transport"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Telecominfraproject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-24T09:59:57.000Z","updated_at":"2024-07-04T12:38:35.000Z","dependencies_parsed_at":"2023-02-19T15:30:38.140Z","dependency_job_id":null,"html_url":"https://github.com/Telecominfraproject/oopt-tai","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Foopt-tai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Foopt-tai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Foopt-tai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Foopt-tai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Telecominfraproject","download_url":"https://codeload.github.com/Telecominfraproject/oopt-tai/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252856743,"owners_count":21814893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["networking","oopt","sai","tai","tip","transport"],"created_at":"2025-05-07T10:20:15.678Z","updated_at":"2025-05-07T10:20:16.284Z","avatar_url":"https://github.com/Telecominfraproject.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TAI (Transponder Abstraction Interface)\n\n![](https://github.com/Telecominfraproject/oopt-tai/workflows/ci/badge.svg?branch=master)\n\n\u003cimg src=\"https://github.com/Telecominfraproject/oopt-tai/raw/master/logo/logo.png\" width=\"100\"\u003e\n\n---\n\nThe Transponder Abstraction Interface, or TAI, defines the API to provide a\nform-factor/vendor independent way of controlling transponders and transceivers\nfrom various vendors and implementations in a uniform manner. It is based upon and quite common to the\nSwitch Abstraction Interface, or [SAI](https://github.com/opencomputeproject/SAI).\n\nTAI is hosted by Telecom Infra Project ([TIP](https://telecominfraproject.com/)) Open Optical and Packet Transport ([OOPT](https://telecominfraproject.com/oopt/)) working group.\n\n---\n\n## Architecture\n\nTAI is an interface specification implemented as a collection of C-language \nheader files. TAI adopts the use of many terms from SAI, including \"Adapter\" and \n\"Adapter Host\".\n\nAn Adapter is similar to a user mode driver. It translates the hardware \nindependent TAI interface to a specific hardware implementation. This is \nimplemented as a shared library, and will typically be provided by the \nmodule vendor. This shared library is called libtai.so.\nTAI library is used interchangebly with TAI adapter.\n\nIf the transponder supports multiple types of module hardware vendors, TAI multiplexer\ncan be used to multiplex several kinds of TAI adapters. For details, see [docs/TAI-MUX.pdf](https://github.com/Telecominfraproject/oopt-tai/blob/master/docs/TAI-MUX.pdf).\n\nAn Adapter Host is hardware independent software which uses the TAI interface\nto provide optical transponder functionality to other parts of the system. An \nadapter host loads the shared library adapter.\nTAI application is used interchangebly with TAI adapter host.\n\nSome TAI adapters are open sourced in the [implementation repo](https://github.com/Telecominfraproject/oopt-tai-implementations).\n\n```\n                      +------------------------+\n                      |                        |\n                      |      Adapter Host      |\n                      |                        |\n                      +------------------------+\n                -------------TAI Interface-------------\n                      +------------------------+\n                      |                        |\n                      |         Adapter        |\n                      |                        |\n                      +------------------------+\n                --------------HW Interface-------------\n                      +------------------------+\n                      |                        |\n                      |        Hardware        |\n                      |                        |\n                      +------------------------+\n```\n\n## Components\n\n- inc/ : TAI API definition\n- meta/ : TAI meta library\n    - TAI meta library provides helper methods for allocation, serialization etc..\n- tools/taish : TAI shell\n    - TAI shell works as a TAI application and provides debug features for TAI library\n- tools/framework : TAI library framework\n    - A framework to develop TAI library\n\n## The TAI Interface\n\nThe adapter host begins using TAI by invoking the `tai_api_initialize()` \nfunction. This function allows the adapter to initialize various data structures \nfor subsequent use. It does **not** initialize the underlying hardware. There \nare two parameters passed to the `tai_api_initialize()` function: `flags`, which \nis currently unused and must be set to zero, and `services`.\n\n`services` is a pointer to a structure of function pointers. This structure \nprovides the adapter with function entry points (services) in the adapter host \nwhich the adapter can call. There is currently only one member in the structure, \n`module_presence`, which the adapter calls whenever there is a change in the \npresence or absence of modules in the system. As a matter of fact, the adapter \nwill typically call the `module_presence()` function for each module in the \nsystem, perhaps even before returning from the `tai_api_initialize()` function. \nThe `module_presence()` function may be called from a different thread than the \nmain adapter host thread. And since TAI functions are not thread-safe, the \nadapter host is required make sure that it does not re-enter the TAI interface \nfrom the `module_presence()` function. This can be done by, for example, \nenqueueing the notifications for later processing on the main adapter \nhost thread.\n\nThe `tai_api_uninitialize()` function is the inverse function to \n`tai_api_initialize()` and is called when the adapter host has completed all TAI \ninterface processing. For example, just before exiting. This function will undo \nwhat was done in `tai_api_initialize()`, freeing memory, closing files, stopping \nthreads, etc, in order to gracefully wrap up execution of the adapter.\n\nAfter `tai_api_initialize()` returns successfully, the adapter host is free to \ncall the other TAI APIs. It does this by first obtaining a list of function \nentry points for each API. There are currently three APIs:\n\n* Module\n* Network Interface\n* Host Interface\n\nFor each of these APIs, a list of function entry pointers is obtained by calling \nthe `tai_api_query()` function. This function takes two parameters, \n`tai_api_id`, which identifies which of the three API's function pointers are \nbeing requested, and `api_method_table`, the address of a pointer which the \nadapter will set to point to the method table for that API.\n\nA method table contains function entry pointers to the functions which \nimplement the API. Currently, all three APIs have very similar method tables \nwhich contain six functions:\n\n* Create an object\n* Destroy an object\n* Set the value of an attribute of an object\n* Set the values for a list of attributes of an object\n* Get the value of an attribute of an object\n* Get the values for a list of attributes of an object\n\n### TAI Objects\n\nEach API allows objects to be created through the `create_xxx()` method table \nfunction. This function creates an instance of the object and initializes \nits attributes. When an object is no longer needed the adapter host can call\nthe `remove_xxx()` method table function, which will remove that object and its \nattributes. The `set_xxx_attribute()` function can be called once an object has \nbeen created to modify the value of one of the object's attributes. The \n`get_xxx_attribute()` function is used to retrieve the value of an object's \nattribute. The `set_xxx_attributes()` and `get_xxx_attributes()` functions\n(notice the 's' at the end of the function names) are provided for convenience \nto set and get a list of attributes in a single function call.\n\n#### Module Objects\n\nThe module API allows module objects to be created. A module object represents \nan optical module. Calling the `create_module()` function causes the optical \nmodule to be initialized, which typically involves resetting the module and \nbringing it into a default state. This function must be called prior to creating \nhost interface or network interface objects on a module. The `create_module()` \nfunction takes three parameters:\n\n* A pointer to a tai_object_id_t. The adapter will return a pointer to the newly \nallocated module ID object. The adapter host should treat this object as opaque. \nIt will be used in subsequent TAI function calls.\n* attr_count and attr_list. A list of attributes which will be set upon the \nmodule object when it is created. This can be used to override the default \nattribute values for a module.\n\nThe attr_list supplied on the `create_module()` function call must contain a \n`TAI_MODULE_ATTR_LOCATION` attribute. This attribute defines which module is \nbeing created. This is typically set to the value of the module_location \nparameter from the `module_presence()` function.\n\nAn adapter host will typically call `create_module()` once for each module \npresent in the system, as indicated when the adapter calls the \n`module_presence()` function.\n\nOnce the adapter host no longer needs to access the module it should call the \n`remove_module()` function. This can occur as the result of the \n`module_presence()` function being called indicating the module was removed, or \nwhen the adapter host is exiting, or whenever the adapter host feel like it. \nRemoving the module simply makes it unaccessible to the adapter host. The actual \nstate of the module is undefined. The adapter may put the module in reset, or \nmay just leave the module in the same state it was prior to the \n`remove_module()` call. After calling `remove_module()` the object ID for the \nmodule which was returned in the `create_module()` function is invalid and \nshould not be used in any subsequent TAI API calls.\n\nOnce the `create_module()` function returns with an object ID for a module, the \nadapter host can use this object ID to get and set attributes of the module with \nthe `get_module_attribute()`, `get_module_attributes()`, \n`set_module_attribute()`, and `set_module_attributes()` function calls. Most of \nthe module attributes are read-only and cannot be modified with the \n`set_module_attribute()` and `set_module_attributes()` functions.\n\nHost interface objects and network interfaces objects are associated with the \nmodule on which they exist. This association is made when a host interface or \nnetwork interface object is created, since the object ID of the associated \nmodule is a parameter of those `create_host_interface()` and \n`create_network_interface()` function calls. Because of this association, host \ninterface and network interface objects should be removed by calling \n`remove_host_interface()` or `remove_network_interface()` prior to removing the \nmodule with which they are associated.\n\nOne of the attributes of a module object is the number of host interface and \nanother attribute is the number of network interfaces. These values can be used \nwhen determining how many host interface objects and network interface objects \nexist on the module, and the index values used when calling \n`create_host_interface()` and `create_network_interface()`.\n\n#### Host Interface Objects\n\nThe host interface API allows host interface objects to be created. A host \ninterface object represents an interface between an optical module and the \nhost system, sometimes called client interfaces. Creating a host interface \nobject allows the attributes of that interface to be set and retrieved. The \n`create_host_interface()` function takes four parameters:\n\n* A pointer to a tai_object_id_t. The adapter will return a pointer to the newly \nallocated host interface ID object. The adapter host should treat this object as \nopaque. It will be used in subsequent TAI function calls. \n* The module ID. Identifies the module ID upon which the host interface exists.  \nThis object ID was returned when the module was created.\n* attr_count and attr_list. A list of attributes which will be set upon the \nhost interface object when it is created. This can be used to override the \ndefault attribute values for a host interface.\n\nThe attr_list must contain an `TAI_HOST_INTERFACE_ATTR_INDEX` attribute. This \nattribute defines which host interface is being created. This is a zero-based \nindex of the host interfaces on a module.\n\nAn adapter host will typically call `create_host_interface()` once for each \nhost interface present in the module, as indicated by the number of host \ninterfaces, which is a module object attribute.\n\nOnce the adapter host no longer needs to access the host interface it should \ncall the `remove_host_interface()` function. This can occur as the result of the \n`module_presence()` function being called indicating the module was removed, or \nwhen the adapter host is exiting, or whenever the adapter host feel like it. \nRemoving the host interface simply makes it unaccessible to the adapter host. \nThe actual state of the host interface is undefined. The adapter may put the  \nhost interface in reset, or may just leave the host interface in the same state \nit was prior to the `remove_host_interface()` call. After calling \n`remove_host_interface()` the object ID for the host interface which was \nreturned in the `create_host_interface()` function is invalid and should not be \nused in any subsequent TAI API calls.\n\nOnce the `create_host_interface()` function returns with an object ID for a \nhost interface, the adapter host can use this object ID to get and set \nattributes of the module with the `get_host_interface_attribute()`, \n`get_host_interface_attributes()`, `set_host_interface_attribute()`, and \n`set_host_interface_attributes()` function calls.\n\n#### Network Interface Objects\n\nThe network interface API allows network interface objects to be created. A \nnetwork interface object represents hardware components which transmit/receive\none wavelength. Creating a network interface object allows the \nattributes of that interface to be set and retrieved. The\n`create_network_interface()` function takes four parameters:\n\n* A pointer to a tai_object_id_t. The adapter will return a pointer to the newly \nallocated network interface ID object. The adapter host should treat this object \nas opaque. It will be used in subsequent TAI function calls. \n* The module ID. Identifies the module ID upon which the network interface \nexists. This object ID was returned when the module was created.\n* attr_count and attr_list. A list of attributes which will be set upon the \nnetwork interface object when it is created. This can be used to override the \ndefault attribute values for a network interface.\n\nThe attr_list must contain an `TAI_NETWORK_INTERFACE_ATTR_INDEX` attribute. This \nattribute defines which network interface is being created. This is a zero-based \nindex of the network interfaces on a module.\n\nAn adapter host will typically call `create_network_interface()` once for each \nnetwork interface present in the module, as indicated by the number of network \ninterfaces, which is a module object attribute.\n\nOnce the adapter host no longer needs to access the network interface it should \ncall the `remove_network_interface()` function. This can occur as the result of\nthe `module_presence()` function being called indicating the module was removed, \nor when the adapter host is exiting, or whenever the adapter host feel like it. \nRemoving the network interface simply makes it unaccessible to the adapter host. \nThe actual state of the network interface is undefined. The adapter may put the  \nnetwork interface in reset, or may just leave the network interface in the same\nstate it was prior to the `remove_network_interface()` call. After calling \n`remove_network_interface()` the object ID for the network interface which was \nreturned in the `create_network_interface()` function is invalid and should not\nbe used in any subsequent TAI API calls.\n\nOnce the `create_network_interface()` function returns with an object ID for a \nnetwork interface, the adapter host can use this object ID to get and set \nattributes of the module with the `get_network_interface_attribute()`, \n`get_network_interface_attributes()`, `set_network_interface_attribute()`, and \n`set_network_interface_attributes()` function calls.\n\n### TAI Attributes\n\nEach object has a list of attributes which are specific to that type of object. \nEach attribute is assigned an ID which is used to get or set the attribute's \nvalue. The TAI header files for each API list the attributes for each object, \nincluding descriptions of the format and access types. For example, the \ntaimodule.h header file lists the module object attributes. The \n`TAI_MODULE_ATTR_MAX_LASER_FREQ` attribute, for example, has a short description \n(The TX/RX maximum laster frequency in Hz), the data type (tai_uint64_t), and \nthe access rules (READ_ONLY). Unless otherwise stated, attributes can be set and\nretrieved at any time after the object is created and prior to its destruction. \nModifying an attribute will commonly cause a modification in the operational \nstate of a module. Refer to the taimodule.h, taihostif.h and tainetworkif.h \nfiles for a list of the attributes of each object type.\n\n### TAI Return Codes\n\nEvery TAI API function returns one of the codes in the taistatus.h file. \nSuccessful execution of the function is indicated by the TAI_STATUS_SUCCESS \ncode. A failure is indicated by any value other than TAI_STATUS_SUCCESS.\n\nWhen processing a list of attributes, the return code can indicate not just \nthat a failure occurred, but also which attribute in the list caused that \nfailure. The return codes TAI_STATUS_INVALID_ATTRIBUTE_0, \nTAI_STATUS_INVALID_ATTR_VALUE_0, TAI_STATUS_ATTR_NOT_IMPLEMENTED_0,\nTAI_STATUS_UNKNOWN_ATTRIBUTE_0, and TAI_STATUS_ATTR_NOT_SUPPORTED_0 are spaced \nout by 64K. Therefore, the least significant 16 bits of each of those error \ncodes contains the index into the attribute list of the attribute which caused \nthe error.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Foopt-tai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelecominfraproject%2Foopt-tai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Foopt-tai/lists"}