****************************** OPNFV FUNCTEST developer guide ****************************** .. toctree:: :numbered: :maxdepth: 2 ============ Introduction ============ Functest is a project dealing with functional testing. Functest produces its own internal test cases but can also be considered as a framework to support feature and VNF onboarding project testing. Functest developed a test API and defined a test collection framework that can be used by any OPNFV project. Therefore there are many ways to contribute to Functest. You can: * Develop new internal test cases * Integrate the tests from your feature project * Develop the framework to ease the integration of external test cases * Develop the API / Test collection framework * Develop dashboards or automatic reporting portals This document describes how, as a developer, you may interact with the Functest project. The first section details the main working areas of the project. The Second part is a list of "How to" to help you to join the Functest family whatever your field of interest is. ======================== Functest developer areas ======================== Functest High level architecture ================================ Functest is project delivering a test container dedicated to OPNFV. It includes the tools, the scripts and the test scenarios. Functest can be described as follow:: +----------------------+ | | | +--------------+ | +-------------------+ | | | | Public | | | | Tools | +------------------+ OPNFV | | | Scripts | | | System Under Test | | | Scenarios | +------------------+ | | | | | Management | | | +--------------+ | +-------------------+ | | | Functest Docker | | | +----------------------+ Functest internal test cases ============================ The internal test cases in Danube are: * healthcheck * connection_check * api_check * vping_ssh * vping_userdata * odl * snaps_smoke * tempest_smoke_serial * rally_sanity * tempest_full_parallel * rally_full * cloudify_ims By internal, we mean that this particular test cases have been developped and/or integrated by functest contributors and the associated code is hosted in the Functest repository. An internal case can be fully developped or a simple integration of upstream suites (e.g. Tempest/Rally developped in OpenStack are just integrated in Functest). The structure of this repository is detailed in `[1]`_. The main internal test cases are in the opnfv_tests subfolder of the repository, the internal test cases are: * sdn: odl, onos * openstack: healthcheck, vping_ssh, vping_userdata, tempest_*, rally_*, connection_check, api_check, snaps_smoke * vnf: cloudify_ims If you want to create a new test case you will have to create a new folder under the testcases directory. Functest external test cases ============================ The external test cases are inherited from other OPNFV projects, especially the feature projects. The external test cases are: * promise * doctor * onos * bgpvpn * copper * security_scan * sfc-odl * sfc-onos * parser * domino * multisite * opera_ims * orchestra_ims The code to run these test cases may be directly in the repository of the project. We have also a **features** sub directory under opnfv_tests directory that may be used (it can be usefull if you want to reuse Functest library). Functest framework ================== Functest can be considered as a framework. Functest is release as a docker file, including tools, scripts and a CLI to prepare the environement and run tests. It simplifies the integration of external test suites in CI pipeline and provide commodity tools to collect and display results. Since Colorado, test categories also known as tiers have been created to group similar tests, provide consistant sub-lists and at the end optimize test duration for CI (see How To section). The definition of the tiers has been agreed by the testing working group. The tiers are: * healthcheck * smoke * features * components * performance * vnf * stress Functest abstraction classes ============================ In order to harmonize test integration, 3 abstraction classes have been introduced in Danube: * testcase_base: base for any test case * feature_base: abstraction for feature project * vnf_base: abstraction for vnf onboarding The goal is to unify the way to run test from Functest. feature_base and vnf_base inherit from testcase_base. +-----------------------------------------+ | | | Testcase_base | | | | - init() | | - run() | | - publish_report() | | - check_criteria() | | | +-----------------------------------------+ | | V V +--------------------+ +--------------------------+ | | | | | feature_base | | vnf_base | | | | | | - prepare() | | - prepare() | | - post() | | - deploy_orchestrator() | | - parse_results() | | - deploy_vnf() | | | | - test_vnf() | | | | - clean() | | | | - execute() | | | | | +--------------------+ +--------------------------+ Functest util classes ===================== In order to simplify the creation of test cases, Functest develops some functions that can be used by any feature or internal test cases. Several features are supported such as logger, configuration management and Openstack capabilities (snapshot, clean, tacker,..). These functions can be found under /functest/utils and can be described as follows: functest/utils/ |-- config.py |-- constants.py |-- env.py |-- functest_constants.py |-- functest_logger.py |-- functest_utils.py |-- openstack_clean.py |-- openstack_snapshot.py |-- openstack_tacker.py `-- openstack_utils.py Note that for Openstack, keystone v3 is now deployed by default by compass, fuel and joid in Danube. All installers still support keysone v2 (deprecated in next version). Test collection framework ========================= The OPNFV testing group created a test collection database to collect the test results from CI: http://testresults.opnfv.org/test/swagger/spec.html Authentication: opnfv/api@opnfv Any test project running on any lab integrated in CI can push the results to this database. This database can be used to see the evolution of the tests and compare the results versus the installers, the scenarios or the labs. Overall Architecture -------------------- The Test result management can be summarized as follows:: +-------------+ +-------------+ +-------------+ | | | | | | | Test | | Test | | Test | | Project #1 | | Project #2 | | Project #N | | | | | | | +-------------+ +-------------+ +-------------+ | | | V V V +-----------------------------------------+ | | | Test Rest API front end | | http://testresults.opnfv.org/test | | | +-----------------------------------------+ A | | V | +-------------------------+ | | | | | Test Results DB | | | Mongo DB | | | | | +-------------------------+ | | +----------------------+ | | | test Dashboard | | | +----------------------+ Test API description -------------------- The Test API is used to declare pods, projects, test cases and test results. Pods are the pods used to run the tests. The results pushed in the database are related to pods, projects and cases. If you try to push results of test done on non referenced pod, the API will return an error message. An additional method dashboard has been added to post-process the raw results in release Brahmaputra (deprecated in Colorado). The data model is very basic, 4 objects are created: * Pods * Projects * Testcases * Results Pods:: { "id": , "details": , "creation_date": "YYYY-MM-DD HH:MM:SS", "name": , "mode": , "role": }, Projects:: { "id": , "name": , "creation_date": "YYYY-MM-DD HH:MM:SS", "description": }, Testcases:: { "id": , "name":, "project_name":, "creation_date": "YYYY-MM-DD HH:MM:SS", "description": , "url": }, Results:: { "_id": , "case_name": , "project_name": , "pod_name": , "installer": , "version": , "start_date": "YYYY-MM-DD HH:MM:SS", "stop_date": "YYYY-MM-DD HH:MM:SS", "build_tag": , "scenario": , "criteria": , "trust_indicator": { "current": 0, "histories": [] } } The API can described as follows. For detailed information, please go to http://testresults.opnfv.org/test/swagger/spec.html Authentication: opnfv/api@opnfv Version: +--------+--------------------------+-----------------------------------------+ | Method | Path | Description | +========+==========================+=========================================+ | GET | /versions | Get all supported API versions | +--------+--------------------------+-----------------------------------------+ Pods: +--------+----------------------------+-----------------------------------------+ | Method | Path | Description | +========+============================+=========================================+ | GET | /api/v1/pods | Get the list of declared Labs (PODs) | +--------+----------------------------+-----------------------------------------+ | POST | /api/v1/pods | Declare a new POD | | | | Content-Type: application/json | | | | { | | | | "name": "pod_foo", | | | | "mode": "metal", | | | | "role": "ci-pod", | | | | "details": "it is a ci pod" | | | | } | +--------+----------------------------+-----------------------------------------+ | GET | /api/v1/pods/{pod_name} | Get a declared POD | +--------+----------------------------+-----------------------------------------+ Projects: +--------+----------------------------+-----------------------------------------+ | Method | Path | Description | +========+============================+=========================================+ | GET | /api/v1/projects | Get the list of declared projects | +--------+----------------------------+-----------------------------------------+ | POST | /api/v1/projects | Declare a new test project | | | | Content-Type: application/json | | | | { | | | | "name": "project_foo", | | | | "description": "whatever you want" | | | | } | +--------+----------------------------+-----------------------------------------+ | DELETE | /api/v1/projects/{project} | Delete a test project | +--------+----------------------------+-----------------------------------------+ | GET | /api/v1/projects/{project} | Get details on a {project} | | | | | +--------+----------------------------+-----------------------------------------+ | PUT | /api/v1/projects/{project} | Update a test project | | | | | | | | Content-Type: application/json | | | | { | | | | | | | | } | +--------+----------------------------+-----------------------------------------+ Testcases: +--------+----------------------------+-----------------------------------------+ | Method | Path | Description | +========+============================+=========================================+ | GET | /api/v1/projects/{project}/| Get the list of testcases of {project} | | | cases | | +--------+----------------------------+-----------------------------------------+ | POST | /api/v1/projects/{project}/| Add a new test case to {project} | | | cases | Content-Type: application/json | | | | { | | | | "name": "case_foo", | | | | "description": "whatever you want" | | | | "url": "whatever you want" | | | | } | +--------+----------------------------+-----------------------------------------+ | DELETE | /api/v1/projects/{project}/| Delete a test case | | | cases/{case} | | +--------+----------------------------+-----------------------------------------+ | GET | /api/v1/projects/{project}/| Get a declared test case | | | cases/{case} | | +--------+----------------------------+-----------------------------------------+ | PUT | /api/v1/projects/{project}?| Modify a test case of {project} | | | cases/{case} | | | | | Content-Type: application/json | | | | { | | | | | | | | } | +--------+----------------------------+-----------------------------------------+ Results: +--------+----------------------------+------------------------------------------+ | Method | Path | Description | +========+============================+==========================================+ | GET | /api/v1/results | Get all the test results | +--------+----------------------------+------------------------------------------+ | POST | /api/v1/results | Add a new test results | | | | Content-Type: application/json | | | | { | | | | "project_name": "project_foo", | | | | "scenario": "odl-l2", | | | | "stop_date": "2016-05-28T14:42:58.384Z", | | | | "trust_indicator": 0.5, | | | | "case_name": "vPing", | | | | "build_tag": "", | | | | "version": "Colorado", | | | | "pod_name": "pod_foo", | | | | "criteria": "PASS", | | | | "installer": "fuel", | | | | "start_date": "2016-05-28T14:41:58.384Z",| | | | "details": | | | | } | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of {case} | | | case={case} | | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of build_tag | | | build_tag={tag} | {tag}. | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get last {N} records of test results | | | last={N} | | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of scenario | | | scenario={scenario} | {scenario}. | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of trust_indicator | | | trust_indicator={ind} | {ind}. | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of last days | | | period={period} | {period}. | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of {project} | | | project={project} | | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of version | | | version={version} | {version}. | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of criteria | | | criteria={criteria} | {criteria}. | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | get the results on pod {pod} | | | pod={pod} | | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the test results of installer {inst} | | | installer={inst} | | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results? | Get the results according to combined | | | | query conditions supported above | +--------+----------------------------+------------------------------------------+ | GET | /api/v1/results/{result_id}| Get the test result by result_id | +--------+----------------------------+------------------------------------------+ Scenarios: +--------+----------------------------+-----------------------------------------+ | Method | Path | Description | +========+============================+=========================================+ | GET | /api/v1/scenarios | Get the list of declared scenarios | +--------+----------------------------+-----------------------------------------+ | POST | /api/v1/scenario | Declare a new scenario | +--------+----------------------------+-----------------------------------------+ | GET | /api/v1/scenario? | Get a declared scenario | | | | | +--------+----------------------------+-----------------------------------------+ The code of the API is hosted in the releng repository `[6]`_. The static documentation of the API can be found at `[17]`_. The test API has been dockerized and may be installed locally in your lab. See `[15]`_ for details. The deployment of the test API has been automated. A jenkins job manages: * the unit tests of the test api * the creation of a new docker file * the deployment of the new test api * the archive of the old test api * the backup of the Mongo DB Test API Authorization ~~~~~~~~~~~~~~~~~~~~~~ PUT/DELETE/POST operations of the testapi now require token based authorization. The token needs to be added in the request using a header 'X-Auth-Token' for access to the database. e.g:: headers['X-Auth-Token'] The value of the header i.e the token can be accessed in the jenkins environment variable *TestApiToken*. The token value is added as a masked password. .. code-block:: python headers['X-Auth-Token'] = os.environ.get('TestApiToken') The above example is in Python. Token based authentication has been added so that only ci pods jenkins job can have access to the database. Please note that currently token authorization is implemented but is not yet enabled. Automatic reporting =================== An automatic reporting page has been created in order to provide a consistant view of the scenarios. In this page, each scenario is evaluated according to test criteria. The code for the automatic reporting is available at `[8]`_. The results are collected from the centralized database every day and, per scenario. A score is calculated based on the results from the last 10 days. This score is the addition of single test scores. Each test case has a success criteria reflected in the criteria field from the results. Considering an instance of a scenario os-odl_l2-nofeature-ha, the scoring is the addition of the scores of all the runnable tests from the categories (tiers healthcheck, smoke and features) corresponding to this scenario. +---------------------+---------+---------+---------+---------+ | Test | Apex | Compass | Fuel | Joid | +=====================+=========+=========+=========+=========+ | vPing_ssh | X | X | X | X | +---------------------+---------+---------+---------+---------+ | vPing_userdata | X | X | X | X | +---------------------+---------+---------+---------+---------+ | tempest_smoke_serial| X | X | X | X |
/*****************************************************************************
*
* Filename:      kingsun-sir.c
* Version:       0.1.1
* Description:   Irda KingSun/DonShine USB Dongle
* Status:        Experimental
* Author:        Alex Villacís Lasso <a_villacis@palosanto.com>
*
*  	Based on stir4200 and mcs7780 drivers, with (strange?) differences
*
*	This program is free software; you can redistribute it and/or modify
*	it under the terms of the GNU General Public License as published by
*	the Free Software Foundation; either version 2 of the License.
*
*	This program is distributed in the hope that it will be useful,
*	but WITHOUT ANY WARRANTY; without even the implied warranty of
*	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
*	GNU General Public License for more details.
*
*	You should have received a copy of the GNU General Public License
*	along with this program; if not, write to the Free Software
*	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*
*****************************************************************************/

/*
 * This is my current (2007-04-25) understanding of how this dongle is supposed
 * to work. This is based on reverse-engineering and examination of the packet
 * data sent and received by the WinXP driver using USBSnoopy. Feel free to
 * update here as more of this dongle is known:
 *
 * General: Unlike the other USB IrDA dongles, this particular dongle exposes,
 * not two bulk (in and out) endpoints, but two *interrupt* ones. This dongle,
 * like the bulk based ones (stir4200.c and mcs7780.c), requires polling in
 * order to receive data.
 * Transmission: Just like stir4200, this dongle uses a raw stream of data,
 * which needs to be wrapped and escaped in a similar way as in stir4200.c.
 * Reception: Poll-based, as in stir4200. Each read returns the contents of a
 * 8-byte buffer, of which the first byte (LSB) indicates the number of bytes
 * (1-7) of valid data contained within the remaining 7 bytes. For example, if
 * the buffer had the following contents:
 *  06 ff ff ff c0 01 04 aa
 * This means that (06) there are 6 bytes of valid data. The byte 0xaa at the
 * end is garbage (left over from a previous reception) and is discarded.
 * If a read returns an "impossible" value as the length of valid data (such as
 * 0x36) in the first byte, then the buffer is uninitialized (as is the case of
 * first plug-in) and its contents should be discarded. There is currently no
 * evidence that the top 5 bits of the 1st byte of the buffer can have values
 * other than 0 once reception begins.
 * Once valid bytes are collected, the assembled stream is a sequence of
 * wrapped IrDA frames that is unwrapped and unescaped as in stir4200.c.
 * BIG FAT WARNING: the dongle does *not* reset the RX buffer in any way after
 * a successful read from the host, which means that in absence of further
 * reception, repeated reads from the dongle will return the exact same
 * contents repeatedly. Attempts to be smart and cache a previous read seem
 * to result in corrupted packets, so this driver depends on the unwrap logic
 * to sort out any repeated reads.
 * Speed change: no commands observed so far to change speed, assumed fixed
 * 9600bps (SIR).
 */

#include <linux/module.h>
#include <linux/moduleparam.h>
#include <linux/kernel.h>
#include <linux/types.h>
#include <linux/errno.h>
#include <linux/slab.h>
#include <linux/usb.h>
#include <linux/device.h>
#include <linux/crc32.h>

#include <asm/unaligned.h>
#include <asm/byteorder.h>
#include <asm/uaccess.h>