USB Serial application
Fork of USBSerial_HelloWorld by
mbed-dev/targets/TARGET_ONSEMI/TARGET_NCS36510/mib.h@10:41552d038a69, 2017-01-10 (annotated)
- Committer:
- Zaitsev
- Date:
- Tue Jan 10 20:42:26 2017 +0000
- Revision:
- 10:41552d038a69
USB Serial bi-directional bridge
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
Zaitsev | 10:41552d038a69 | 1 | /** |
Zaitsev | 10:41552d038a69 | 2 | ****************************************************************************** |
Zaitsev | 10:41552d038a69 | 3 | * @file mib.h |
Zaitsev | 10:41552d038a69 | 4 | * @brief Defines the structure of a Management Information Base (MIB) |
Zaitsev | 10:41552d038a69 | 5 | * @internal |
Zaitsev | 10:41552d038a69 | 6 | * @author ON Semiconductor |
Zaitsev | 10:41552d038a69 | 7 | * $Rev: 2284 $ |
Zaitsev | 10:41552d038a69 | 8 | * $Date: 2013-09-12 15:08:22 +0530 (Thu, 12 Sep 2013) $ |
Zaitsev | 10:41552d038a69 | 9 | ****************************************************************************** |
Zaitsev | 10:41552d038a69 | 10 | * Copyright 2016 Semiconductor Components Industries LLC (d/b/a ON Semiconductor). |
Zaitsev | 10:41552d038a69 | 11 | * All rights reserved. This software and/or documentation is licensed by ON Semiconductor |
Zaitsev | 10:41552d038a69 | 12 | * under limited terms and conditions. The terms and conditions pertaining to the software |
Zaitsev | 10:41552d038a69 | 13 | * and/or documentation are available at http://www.onsemi.com/site/pdf/ONSEMI_T&C.pdf |
Zaitsev | 10:41552d038a69 | 14 | * (ON Semiconductor Standard Terms and Conditions of Sale, Section 8 Software) and |
Zaitsev | 10:41552d038a69 | 15 | * if applicable the software license agreement. Do not use this software and/or |
Zaitsev | 10:41552d038a69 | 16 | * documentation unless you have carefully read and you agree to the limited terms and |
Zaitsev | 10:41552d038a69 | 17 | * conditions. By using this software and/or documentation, you agree to the limited |
Zaitsev | 10:41552d038a69 | 18 | * terms and conditions. |
Zaitsev | 10:41552d038a69 | 19 | * |
Zaitsev | 10:41552d038a69 | 20 | * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED |
Zaitsev | 10:41552d038a69 | 21 | * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF |
Zaitsev | 10:41552d038a69 | 22 | * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. |
Zaitsev | 10:41552d038a69 | 23 | * ON SEMICONDUCTOR SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, |
Zaitsev | 10:41552d038a69 | 24 | * INCIDENTAL, OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER. |
Zaitsev | 10:41552d038a69 | 25 | * @endinternal |
Zaitsev | 10:41552d038a69 | 26 | * |
Zaitsev | 10:41552d038a69 | 27 | * @details |
Zaitsev | 10:41552d038a69 | 28 | * This file defines the structure, as seen from the outside, of any Management |
Zaitsev | 10:41552d038a69 | 29 | * Information Base (MIB) implementation. It does not define the contents of the |
Zaitsev | 10:41552d038a69 | 30 | * MIB. |
Zaitsev | 10:41552d038a69 | 31 | * |
Zaitsev | 10:41552d038a69 | 32 | * A MIB is implemented as a map of parameters, each identified by a unique Object ID. |
Zaitsev | 10:41552d038a69 | 33 | * The contents of the map have to be filled in by the actual MIB implementation, by |
Zaitsev | 10:41552d038a69 | 34 | * assigning to the GlobMibMap variable. The mib_param_t data type defines the format |
Zaitsev | 10:41552d038a69 | 35 | * of each parameter in the map. *NOTE:* The length of the last entry in the map must |
Zaitsev | 10:41552d038a69 | 36 | * be 0. |
Zaitsev | 10:41552d038a69 | 37 | * |
Zaitsev | 10:41552d038a69 | 38 | * One parameter must always be present in the MIB map: the system revision. It has |
Zaitsev | 10:41552d038a69 | 39 | * to be set by assigning a value to the systemRevision variable. |
Zaitsev | 10:41552d038a69 | 40 | * |
Zaitsev | 10:41552d038a69 | 41 | * Parameters can be of any data type, and read / write or read only. To resemble |
Zaitsev | 10:41552d038a69 | 42 | * the hierarchical structure of an SNMP MIB, each Object ID consists of four nibbles |
Zaitsev | 10:41552d038a69 | 43 | * (uint16_t) where the more significant nibbles correspond to a higher level in the |
Zaitsev | 10:41552d038a69 | 44 | * hierarchy. |
Zaitsev | 10:41552d038a69 | 45 | * |
Zaitsev | 10:41552d038a69 | 46 | * The contents of the map can be accessed with the fMibSetBytes() and fMibGetBytes() |
Zaitsev | 10:41552d038a69 | 47 | * functions. The implementation of the MIB may also make its parameters accessible |
Zaitsev | 10:41552d038a69 | 48 | * in a more "direct" way; that is left to the implementation. The fMibSetBytes() and |
Zaitsev | 10:41552d038a69 | 49 | * fMibGetBytes() functions are made available to the user interface (see ui.h). In |
Zaitsev | 10:41552d038a69 | 50 | * order to do so, fMibUiInit() must be called during device initialization. |
Zaitsev | 10:41552d038a69 | 51 | * |
Zaitsev | 10:41552d038a69 | 52 | * Additionally, for parameters that have an array as their value, the individual |
Zaitsev | 10:41552d038a69 | 53 | * elements of the array can be accessed using the fMibIndexedSetBytes() and |
Zaitsev | 10:41552d038a69 | 54 | * fMibIndexedGetBytes() functions. The functions are similar to their non-indexed |
Zaitsev | 10:41552d038a69 | 55 | * variants (fMibSetBytes() and fMibGetBytes()), except that they expect the index of |
Zaitsev | 10:41552d038a69 | 56 | * the element as an argument. |
Zaitsev | 10:41552d038a69 | 57 | * |
Zaitsev | 10:41552d038a69 | 58 | * fMibGetBytes() and fMibSetBytes() will normally copy bytes from the MIB parameter |
Zaitsev | 10:41552d038a69 | 59 | * into a given place in memory, or from memory to the MIB parameter. This behaviour |
Zaitsev | 10:41552d038a69 | 60 | * can be overruled by assigning a function to the setAction and / or getAction |
Zaitsev | 10:41552d038a69 | 61 | * fields of the MIB parameter. |
Zaitsev | 10:41552d038a69 | 62 | * |
Zaitsev | 10:41552d038a69 | 63 | * For parameters that have an array as their value, the length field has a slightly |
Zaitsev | 10:41552d038a69 | 64 | * different meaning: the most significant 16 bits contain the length of the array; |
Zaitsev | 10:41552d038a69 | 65 | * the least significant 16 bits contain the width of the array (i.e. the size in |
Zaitsev | 10:41552d038a69 | 66 | * bytes of the array's elements). This implies that the normal fMibGetBytes() and |
Zaitsev | 10:41552d038a69 | 67 | * fMibSetBytes() cannot be used on these parameters; instead, a get and set action |
Zaitsev | 10:41552d038a69 | 68 | * needs to be provided to interpret the length field in case of a non-indexed get |
Zaitsev | 10:41552d038a69 | 69 | * or set. |
Zaitsev | 10:41552d038a69 | 70 | * |
Zaitsev | 10:41552d038a69 | 71 | * To access the MIB fields over the user interface, the module ID must be equal to |
Zaitsev | 10:41552d038a69 | 72 | * MIB_MODULE_ID or 0x01. The data in the packet must have the following structure: |
Zaitsev | 10:41552d038a69 | 73 | * <table> |
Zaitsev | 10:41552d038a69 | 74 | * <tr> |
Zaitsev | 10:41552d038a69 | 75 | * <th>Get (0x00) / Set (0x01) code</th> |
Zaitsev | 10:41552d038a69 | 76 | * <th>Object ID</th> |
Zaitsev | 10:41552d038a69 | 77 | * <th>Value (only for set)</th> |
Zaitsev | 10:41552d038a69 | 78 | * </tr> |
Zaitsev | 10:41552d038a69 | 79 | * <tr> |
Zaitsev | 10:41552d038a69 | 80 | * <td>1 Byte</td> |
Zaitsev | 10:41552d038a69 | 81 | * <td>2 Bytes</td> |
Zaitsev | 10:41552d038a69 | 82 | * <td>X bytes</td> |
Zaitsev | 10:41552d038a69 | 83 | * </tr> |
Zaitsev | 10:41552d038a69 | 84 | * </table> |
Zaitsev | 10:41552d038a69 | 85 | * |
Zaitsev | 10:41552d038a69 | 86 | * <table> |
Zaitsev | 10:41552d038a69 | 87 | * <tr> |
Zaitsev | 10:41552d038a69 | 88 | * <th>Indexed Get (0x02) / Set (0x03) code</th> |
Zaitsev | 10:41552d038a69 | 89 | * <th>Object ID</th> |
Zaitsev | 10:41552d038a69 | 90 | * <th>Index</th> |
Zaitsev | 10:41552d038a69 | 91 | * <th>Value (only for set)</th> |
Zaitsev | 10:41552d038a69 | 92 | * </tr> |
Zaitsev | 10:41552d038a69 | 93 | * <tr> |
Zaitsev | 10:41552d038a69 | 94 | * <td>1 Byte</td> |
Zaitsev | 10:41552d038a69 | 95 | * <td>2 Bytes</td> |
Zaitsev | 10:41552d038a69 | 96 | * <td>2 Bytes</td> |
Zaitsev | 10:41552d038a69 | 97 | * <td>X bytes</td> |
Zaitsev | 10:41552d038a69 | 98 | * </tr> |
Zaitsev | 10:41552d038a69 | 99 | * </table> |
Zaitsev | 10:41552d038a69 | 100 | * |
Zaitsev | 10:41552d038a69 | 101 | * The reply to this request will have the same structure, with the value always |
Zaitsev | 10:41552d038a69 | 102 | * being present (in case of a Set as well as a Get request). |
Zaitsev | 10:41552d038a69 | 103 | * |
Zaitsev | 10:41552d038a69 | 104 | * In case an error occurs during a Set or Get request, an error is returned by |
Zaitsev | 10:41552d038a69 | 105 | * fMibGetBytes(), fMibSetBytes() or the UI. See the UI Module's documentation for |
Zaitsev | 10:41552d038a69 | 106 | * the format of an error reply. The applicable error codes are: |
Zaitsev | 10:41552d038a69 | 107 | * <table> |
Zaitsev | 10:41552d038a69 | 108 | * <tr><th>0x01</th><td>Trying to set a read-only parameter.</td></tr> |
Zaitsev | 10:41552d038a69 | 109 | * <tr><th>0x02</th><td>Requested value out of range.</td></tr> |
Zaitsev | 10:41552d038a69 | 110 | * <tr><th>0x03</th><td>Object ID is unknown.</td></tr> |
Zaitsev | 10:41552d038a69 | 111 | * <tr><th>0x04</th><td>Provided index is incorrect.</td></tr> |
Zaitsev | 10:41552d038a69 | 112 | * </table> |
Zaitsev | 10:41552d038a69 | 113 | * |
Zaitsev | 10:41552d038a69 | 114 | * @ingroup mib |
Zaitsev | 10:41552d038a69 | 115 | */ |
Zaitsev | 10:41552d038a69 | 116 | |
Zaitsev | 10:41552d038a69 | 117 | #ifndef MIB_H_ |
Zaitsev | 10:41552d038a69 | 118 | #define MIB_H_ |
Zaitsev | 10:41552d038a69 | 119 | |
Zaitsev | 10:41552d038a69 | 120 | |
Zaitsev | 10:41552d038a69 | 121 | #include <stdint.h> |
Zaitsev | 10:41552d038a69 | 122 | |
Zaitsev | 10:41552d038a69 | 123 | #include "types.h" |
Zaitsev | 10:41552d038a69 | 124 | #include "error.h" |
Zaitsev | 10:41552d038a69 | 125 | |
Zaitsev | 10:41552d038a69 | 126 | /** A structure defining the format of the system revision parameter. */ |
Zaitsev | 10:41552d038a69 | 127 | typedef struct mib_systemRevision { |
Zaitsev | 10:41552d038a69 | 128 | uint8_t hardwareRevision; |
Zaitsev | 10:41552d038a69 | 129 | uint8_t patchLevel; |
Zaitsev | 10:41552d038a69 | 130 | uint8_t bugFix; |
Zaitsev | 10:41552d038a69 | 131 | uint8_t featureSet; |
Zaitsev | 10:41552d038a69 | 132 | uint8_t generation; |
Zaitsev | 10:41552d038a69 | 133 | uint8_t release; |
Zaitsev | 10:41552d038a69 | 134 | } mib_systemRevision_t, *mib_systemRevision_pt; |
Zaitsev | 10:41552d038a69 | 135 | |
Zaitsev | 10:41552d038a69 | 136 | /** The system revision. */ |
Zaitsev | 10:41552d038a69 | 137 | extern const mib_systemRevision_t systemRevision; |
Zaitsev | 10:41552d038a69 | 138 | |
Zaitsev | 10:41552d038a69 | 139 | |
Zaitsev | 10:41552d038a69 | 140 | #endif /* MIB_H_ */ |