versadac  1
versadac - Scalable Recorder Firmware
uuid.h
1 /*---------------------------------------------------------------------------*/
2 /* Copyright (C) 2006 Woodhead Software & Electonics. All rights reserved. */
3 /*---------------------------------------------------------------------------*/
4 /* This program is protected by international copyright. */
5 /* */
6 /* The use of this software including but not limited to its Source Code */
7 /* is subject to restrictions as agreed in the license agreement between */
8 /* you and Woodhead. */
9 /* Copying or distribution is not allowed unless expressly permitted */
10 /* according to your license agreement with Woodhead. */
11 /*---------------------------------------------------------------------------*/
12 /* */
13 /* Project : STACK PROFINET Controller */
14 /* Component : RPC Interface */
15 /* $Workfile:: uuid.h $*/
16 /* $Revision:: 3 $*/
17 /* $Date:: 27/04/10 11:27 $*/
18 /* */
19 /*---------------------------------------------------------------------------*/
20 /* */
21 /* D e s c r i p t i o n : */
22 /* UUID and UUID Utility functions */
23 /* */
24 /*---------------------------------------------------------------------------*/
25 
26 /* From OSF DCE 1.1
27 
28 Universal Unique Identifier
29 ---------------------------
30 This appendix specifies the syntax and semantics of the DCE variant of
31 Universal Unique Identifiers (UUIDs). A UUID is an identifier that is unique
32 across both space and time1, with respect to the space of all UUIDs.
33 A UUID can be used for multiple purposes, from tagging objects with an
34 extremely short lifetime, to reliably identifying very persistent objects
35 across a network.
36 
37 The generation of UUIDs does not require a registration authority for each
38 single identifier. Instead, it requires a unique value over space for each
39 UUID generator. This spatially unique value is specified as an IEEE 802
40 address, which is usually already applied to network-connected systems.
41 This 48-bit address can be assigned based on an address block obtained
42 through the IEEE registration authority. This UUID specification assumes
43 the availability of an IEEE 802 address.
44 
45 Format
46 UUID Format shows the format of a UUID.
47 Field NDR Data Type Octet # Note
48 time_low unsigned long 0-3 The low field of the timestamp.
49 time_mid unsigned short 4-5 The middle field of the timestamp.
50 time_hi_and_version unsigned short 6-7 The high field of the timestamp multiplexed with the version number.
51 clock_seq_hi_and_reserved unsigned small 8 The high field of the clock sequence multiplexed with the variant.
52 clock_seq_low unsigned small 9 The low field of the clock sequence.
53 node character 10-15 The spatially unique node identifier.
54 
55 
56 
57 The UUID consists of a record of 16 octets and must not contain
58 padding between fields. The total size is 128 bits.
59 
60 To minimise confusion about bit assignments within octets,
61 the UUID record definition is defined only in terms of fields that are integral
62 numbers of octets. The version number is multiplexed with the time stamp (time_high),
63 and the variant field is multiplexed with the clock sequence (clock_seq_high).
64 
65 The timestamp is a 60 bit value. For UUID version 1,
66 this is represented by Coordinated Universal Time (UTC) as a count of 100-nanosecond
67 intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar).
68 
69 The version number is multiplexed in the 4 most significant bits of the time_hi_and_version field.
70 UUID version Field lists currently defined versions of the UUID.
71 
72 Table: UUID version Field
73 msb1 msb2 msb3 msb4 Version Description
74 0 0 0 1 1 DCE version, as specified herein.
75 0 0 1 0 2 DCE Security version, with embedded POSIX UIDs.
76 
77 The variant field determines the layout of the UUID.
78 The structure of DCE UUIDs is fixed across different versions.
79 Other UUID variants may not interoperate with DCE UUIDs. Interoperability of UUIDs
80 is defined as the applicability of operations such as string conversion, comparison,
81 and lexical ordering across different systems. The variant field consists of a variable
82 number of the msbs of the clock_seq_hi_and_reserved field. UUID variant Field lists the
83 contents of the DCE variant field.
84 
85 Table: UUID variant Field
86 msb1 msb2 msb3 Description
87 0 - - Reserved, NCS backward compatibility.
88 1 0 - DCE variant.
89 1 1 0 Reserved, Microsoft Corporation GUID.
90 1 1 1 Reserved for future definition.
91 
92 
93 The clock sequence is required to detect potential losses of monotonicity of the clock.
94 Thus, this value marks discontinuities and prevents duplicates.
95 An algorithm for generating this value is outlined in Clock Sequence .
96 The clock sequence is encoded in the 6 least significant bits of the clock_seq_hi_and_reserved
97 field and in the clock_seq_low field.
98 
99 The node field consists of the IEEE address, usually the host address.
100 For systems with multiple IEEE 802 nodes, any available node address can be used.
101 The lowest addressed octet (octet number 10) contains the global/local bit and the unicast/multicast bit,
102 and is the first octet of the address transmitted on an 802.3 LAN.
103 
104 Depending on the network data representation, the multi-octet unsigned integer fields are subject to byte
105 swapping when communicated between different endian machines.
106 
107 The nil UUID is special form of UUID that is specified to have all 128 bits set to 0 (zero).
108 
109 UUID Generation
110 ---------------------------
111 
112 UUIDs are generated according to the following algorithm:
113 
114 
115 Determine the values for the UTC-based timestamp and clock sequence to be used in the UUID.
116 Format and Clock Sequence define how to determine these values.
117 For the purposes of this algorithm, consider the timestamp to be a 60-bit unsigned integer and
118 the clock sequence to be a 14-bit unsigned integer. Sequentially number the bits in a field,
119 starting from 0 (zero) for the least significant bit.
120 
121 Set the time_low field equal to the least significant
122 32-bits (bits numbered 0 to 31 inclusive) of the time stamp in the same order of significance.
123 If a DCE Security version UUID is being created, then replace the time_low field with the local
124 user security attribute as defined by the DCE: Security Services specification.
125 
126 Set the time_mid field equal to the bits numbered 32 to 47 inclusive of the time stamp
127 in the same order of significance.
128 
129 Set the 12 least significant bits (bits numbered 0 to 11 inclusive) of the time_hi_and_version
130 field equal to the bits numbered 48 to 59 inclusive of the time stamp in the same order of significance.
131 
132 Set the 4 most significant bits (bits numbered 12 to 15 inclusive) of the time_hi_and_version field
133 to the 4-bit version number corresponding to the UUID version being created, as shown in UUID version Field .
134 
135 Set the clock_seq_low field to the 8 least significant bits (bits numbered 0 to 7 inclusive)
136 of the clock sequence in the same order of significance.
137 
138 Set the 6 least significant bits (bits numbered 0 to 5 inclusive) of the clock_seq_hi_and_reserved field
139 to the 6 most significant bits (bits numbered 8 to 13 inclusive) of the clock sequence in the same order of significance.
140 
141 Set the 2 most significant bits (bits numbered 6 and 7) of the clock_seq_hi_and_reserved
142 field as shown in The 2 msb of clock_seq_hi_and_reserved .
143 
144 Table: The 2 msb of clock_seq_hi_and_reserved
145 Bit 7 Bit 6
146 1 0
147 
148 Set the node field to the 48-bit IEEE address in the same order of significance as the address.
149 
150 String Representation
151 ---------------------------
152 The following is an example of the string representation of a UUID:
153 2fac1234-31f8-11b4-a222-08002b34c003
154 
155 
156 Comparing UUIDs
157 ---------------------------
158 Field Order and Type lists the UUID fields in order of significance,
159 from most significant to least significant, for purposes of UUID comparison.
160 The table also shows the data types applicable to the fields.
161 
162 
163 Table: Field Order and Type
164 
165 Field Type
166 time_low Unsigned 32-bit integer
167 time_mid Unsigned 16-bit integer
168 time_hi_and_version Unsigned 16-bit integer
169 clock_seq_hi_and_reserved Unsigned 8-bit integer
170 clock_seq_low Unsigned 8-bit integer
171 node Unsigned 48-bit integer
172 
173 Consider each field to be an unsigned integer as shown in Field Order and Type .
174 To compare a pair of UUIDs, arithmetically compare the corresponding fields from each UUID in order
175 of significance and according to their data type. Two UUIDs are equal if and
176 only if all the corresponding fields are equal. The first of two UUIDs follows the second
177 if the most significant field in which the UUIDs differ is greater for the first UUID.
178 The first of a pair of UUIDs precedes the second if the most significant field in which the UUIDs differ
179 is greater for the second UUID.
180 
181 */
182 #ifndef __UUID_H__
183  #define __UUID_H__
184 
185 #define UUID4LEN 8
186 
187 /*********************************************** OBJECT UUID Definition*/
188 /* Data1 : DWORD in little endian*/
189 #define UUIDDATA1NULL 0xDEA00000
190 #define UUIDDATA1DEVICE 0xDEA00001
191 #define UUIDDATA1CONTRO 0xDEA00002
192 #define UUIDDATA1SUPERV 0xDEA00003
193 #define UUIDDATA1PARSER 0xDEA00004
194 /* Data 2*/
195 #define UUIDDATA2 0x6C97
196 
197 /* Data 3*/
198 #define UUIDDATA3 0x11D1
199 
200 /* Data 4*/
201 #define UUIDDATA4_0 0x82
202 #define UUIDDATA4_1 0x71
203 
204 /*---------------------------------------------------------------------------*/
205 /* STRUCTURE DEFINITION */
206 /*---------------------------------------------------------------------------*/
207 #include "os_pck.h"
208 
209 /*
210  Here the two representation of UUID DCE, PNIO
211  Depending of part of code we can used both
212 */
213 
215  ALIGNED_DWORD_DECL(Data1); /*4 - 0*/
216  APP_WORD Data2; /*2 - 4*/
217  APP_WORD Data3; /*2 - 6*/
218  APP_BYTE Data4[UUID4LEN]; /*8 - 8*/
219 }STRUCT_ALIGNEMENT; /* 16*/
220 typedef struct _ST_CLR_RPC_UUID PACK_ALIGNEMENT(ST_CLR_RPC_UUID), APP_FAR* LPST_CLR_RPC_UUID;
221 #define CLR_RPC_UUID_SIZEOF sizeof(ST_CLR_RPC_UUID)
222 
223 #include "os_unpck.h"
224 
225 /*---------------------------------------------------------------------------*/
226 /* FUNCTION DEFINITION */
227 /*---------------------------------------------------------------------------*/
228 
229 APP_VOID uuid_create_activity_dce(LPST_CLR_RPC_UUID pUUID,APP_PBYTE pbyMacAddress);
230 APP_VOID uuid_create(LPST_CLR_RPC_UUID pUUID,APP_LPBYTE lpbyMacAddress);
231 APP_VOID uuid_to_string(LPST_CLR_RPC_UUID pUUID,APP_PCHAR szUUID);
232 APP_WORD uuid_from_string(APP_PCHAR szUUID,LPST_CLR_RPC_UUID pUUID);
233 APP_WORD uuid_equal (LPST_CLR_RPC_UUID pUUID1,LPST_CLR_RPC_UUID pUUID2);
234 APP_WORD uuid_is_nil(LPST_CLR_RPC_UUID pUUID);
235 APP_VOID uuid_build_object(LPST_CLR_RPC_UUID lpuuidPROFINETIOConstantValue , LPST_CLR_RPC_UUID pRPCObjectUUID, APP_WORD wInstance, APP_WORD wDeviceId, APP_WORD wVendorId);
236 APP_VOID uuid_build_ar(LPST_CLR_RPC_UUID pArUUID,APP_LPBYTE pbyMacAddress);
237 APP_VOID uuid_build_initiator(LPST_CLR_RPC_UUID lpuuidPROFINETIOConstantValue , LPST_CLR_RPC_UUID pInitiatorUUID, APP_WORD wCtrlDeviceId, APP_WORD wCtrlVendorId);
238 APP_BOOL uuid_cmp(LPST_CLR_RPC_UUID UUID1, LPST_CLR_RPC_UUID UUID2);
239 APP_VOID uuid_cpy(LPST_CLR_RPC_UUID UUID1, LPST_CLR_RPC_UUID UUID2);
240 APP_VOID uuid_fmx(LPST_CLR_RPC_UUID UUID1, LPST_CLR_RPC_UUID UUID2);
241 #endif
Definition: uuid.h:214