]>
Commit | Line | Data |
---|---|---|
f67539c2 TL |
1 | Contributing to intel-ipsec-mb |
2 | ============================== | |
3 | ||
4 | As an open source project, we welcome contributions of any kind. | |
5 | These can range from bug reports, code reviews and code development, | |
6 | to significant code or documentation features. | |
7 | ||
8 | Note: | |
9 | There is just one branch used in the project. All development is done on the | |
10 | master branch. Code taken from the tip of the master branch should not be | |
11 | considered fit for production. | |
12 | Refer to the releases tab for stable code versions: | |
13 | https://github.com/intel/intel-ipsec-mb/releases | |
14 | ||
15 | ||
16 | How can I contribute? | |
17 | ===================== | |
18 | ||
19 | This document specifies contributing guidelines to the intel-ipsec-mb source | |
20 | tree. It covers some general guidelines, the preferred style and formatting | |
21 | for source files, additional requirements like documentation and development | |
22 | workflow. The goal of this document is to walk you through the concepts and | |
23 | specifics that should be understood while contributing to intel-ipsec-mb. | |
24 | ||
25 | ||
26 | Reporting Bugs | |
27 | ============== | |
28 | ||
29 | Bugs should be reported via GitHub issues. The description should include | |
30 | a platform name, OS and kernel version, library version and detailed | |
31 | information on how to reproduce the bug. | |
32 | ||
33 | ||
34 | Suggesting Enhancements | |
35 | ======================= | |
36 | ||
37 | Improvements should be reported via GitHub issues or pull requests. | |
38 | ||
39 | ||
40 | Creating Pull Requests | |
41 | ====================== | |
42 | ||
43 | Pull requests should be created using standard procedure available on GitHub. | |
44 | It is important to fill in all required information into a template. For major | |
45 | modifications (e.g. adding a new feature, refactoring), for effective | |
46 | development, it is recommended to share high level document with core | |
47 | development team via GitHub issue so that one can ask questions if one foresees | |
48 | issues that may occur in existing development. | |
49 | ||
50 | ||
51 | Coding Style Guides | |
52 | =================== | |
53 | ||
54 | General Guidelines | |
55 | ================== | |
56 | ||
57 | The rules and guidelines given in this document cannot cover every situation, | |
58 | so the following general guidelines should be used as a fallback: | |
59 | ||
60 | The code style should be consistent within each individual file. | |
61 | In the case of creating new files, the style should be consistent within | |
62 | each file in a given directory or module. The primary reason for coding | |
63 | standards is to increase code readability and comprehensibility, therefore | |
64 | always use whatever option will make the code easier to read. Line length | |
65 | is recommended to be not more than 80 characters, including comments. | |
66 | ||
67 | ||
68 | C | |
69 | = | |
70 | ||
71 | Formatting using checkpatch.pl | |
72 | ============================== | |
73 | ||
74 | To format your code please use checkpatch.pl script (version 0.32) from | |
75 | Linux kernel | |
76 | (https://github.com/torvalds/linux/blob/master/scripts/checkpatch.pl). | |
77 | ||
78 | The top level Makefile contains a target "style" that can be used to check | |
79 | formatting. Please ensure the checkpatch.pl script has been added to your PATH. | |
80 | ||
81 | ||
82 | Indentation | |
83 | =========== | |
84 | ||
85 | Tabs are 8 characters and thus indentations are also 8 characters. | |
86 | It should be consistent within each part of the code. When adding a new file, | |
87 | spaces should be used over tabs. | |
88 | ||
89 | ||
90 | C Comment Style | |
91 | =============== | |
92 | ||
93 | Usual Comments | |
94 | ============== | |
95 | ||
96 | These comments should be used in normal cases. To document a public API, | |
97 | a doxygen-like format must be used: refer to Doxygen Guidelines | |
98 | (http://www.doxygen.nl/manual/docblocks.html). | |
99 | ||
100 | /* | |
101 | * VERY important single-line comments look like this. | |
102 | */ | |
103 | ||
104 | /* Most single-line comments look like this. */ | |
105 | ||
106 | /* | |
107 | * Multi-line comments look like this. Make them real sentences. Fill | |
108 | * them so they look like real paragraphs. | |
109 | */ | |
110 | ||
111 | ||
112 | License Header | |
113 | ============== | |
114 | ||
115 | Each file should begin with a special comment containing the appropriate | |
116 | copyright and license for the file. After any copyright header, a blank line | |
117 | should be left before any other contents, e.g. include statements in a C file. | |
118 | ||
119 | ||
120 | Preprocessor Directives (Header Includes) | |
121 | ========================================= | |
122 | ||
123 | Include files from the local application directory are included using quotes, | |
124 | while includes from other paths are included using angle brackets: "<>". | |
125 | ||
126 | Example: | |
127 | ||
128 | #include <stdlib.h> | |
129 | #include <string.h> | |
130 | ||
131 | #include "intel-ipsec-mb.h" | |
132 | #include "asm.h" | |
133 | ||
134 | ||
135 | Header File Guards | |
136 | ================== | |
137 | ||
138 | Headers should be protected against multiple inclusion with the usual: | |
139 | ||
140 | #ifndef _FILE_H_ | |
141 | #define _FILE_H_ | |
142 | ||
143 | /* Code */ | |
144 | ||
145 | #endif /* _FILE_H_ */ | |
146 | ||
147 | ||
148 | Macros | |
149 | ====== | |
150 | ||
151 | You can define a macro similar in C using #define preprocessor directive. | |
152 | ||
153 | For example: | |
154 | ||
155 | /** | |
156 | * --------------------------------------- | |
157 | * Local macros | |
158 | * --------------------------------------- | |
159 | */ | |
160 | ||
161 | /* | |
162 | * Custom ASSERT and DIM macros | |
163 | */ | |
164 | #ifdef DEBUG | |
165 | #include <assert.h> | |
166 | #define IMB_ASSERT(x) assert(x) | |
167 | #else | |
168 | #define IMB_ASSERT(x) | |
169 | #endif | |
170 | ||
171 | #ifndef IMB_DIM | |
172 | #define IMB_DIM(x) (sizeof(x) / sizeof(x[0])) | |
173 | #endif | |
174 | ||
175 | ||
176 | ASM | |
177 | === | |
178 | ||
179 | Syntax | |
180 | ====== | |
181 | ||
182 | Intel syntax should be used always. | |
183 | ||
184 | ||
185 | Register Naming | |
186 | =============== | |
187 | ||
188 | Virtual registers with meaningful names should be used over direct register | |
189 | names when possible. | |
190 | ||
191 | ||
192 | Indentation | |
193 | =========== | |
194 | ||
195 | Tabs are 8 characters and thus indentations are also 8 characters. | |
196 | To improve readability, instructions should be preceded by a single indent | |
197 | and followed by one or more indents in order to align the first operand. | |
198 | Spaces should be used over tabs. | |
199 | ||
200 | Example: | |
201 | vmovdqu %%T5, [%%GDATA + HashKey_6] | |
202 | vpshufd %%T2, %%XMM2, 01001110b | |
203 | vpshufd %%T3, %%T5, 01001110b | |
204 | vpclmulqdq %%T4, %%XMM2, %%T5, 0x11 | |
205 | ||
206 | ||
207 | Comment Style | |
208 | ============= | |
209 | ||
210 | Two semicolons should be used for comment lines and a single semicolon | |
211 | for end of line comments. | |
212 | ||
213 | Example: | |
214 | ;; first phase of the reduction | |
215 | vmovdqu %%T3, [rel POLY2] | |
216 | ||
217 | vpclmulqdq %%T2, %%T3, %%T7, 0x01 | |
218 | vpslldq %%T2, %%T2, 8 ; shift-L xmm2 2 DWs | |
219 | ||
220 | ||
221 | Macros | |
222 | ====== | |
223 | ||
224 | Macros should be used where possible to reduce code duplication. All macros | |
225 | should be properly documented, specifiying input/output parameters and | |
226 | their types. | |
227 | ||
228 | Example: | |
229 | %macro AESROUND_1_TO_16_BLOCKS 5 | |
230 | %define %%L0B0_3 %1 ; [in/out] ZMM; blocks 0 to 3 | |
231 | %define %%L0B4_7 %2 ; [in/out] ZMM; blocks 4 to 7 | |
232 | %define %%KEY %3 ; [in] ZMM containing round key | |
233 | %define %%ROUND %4 ; [in] numerical value containing round number | |
234 | %define %%IA0 %5 ; [clobbered] temp GP register | |
235 | ||
236 | Macros should be located within or before the .text section in the file. | |
237 | ||
238 | ||
239 | License Header | |
240 | ============== | |
241 | ||
242 | Each file should begin with a special comment containing the appropriate | |
243 | copyright and license for the file. After any copyright header, a blank line | |
244 | should be left before any other contents. | |
245 | ||
246 | ||
247 | File and Code Structure | |
248 | ======================= | |
249 | ||
250 | New files should be structured in the following layout: | |
251 | 1. License header | |
252 | 2. .data section | |
253 | 3. .text section | |
254 | ||
255 | Please see avx512/cntr_vaes_avx512.asm for an example. | |
256 | All new modules should compile to produce relocatable code. | |
257 | ||
258 | ||
259 | Public APIs in the library | |
260 | ========================== | |
261 | ||
262 | All functions that are exposed by the library must have their prototypes | |
263 | defined in intel-ipsec-mb.h and symbols added to libIPSec_MB.def. | |
264 | ||
265 | ||
266 | Documentation | |
267 | ============= | |
268 | ||
269 | Please make sure to update documentation when necessary. If not possible | |
270 | (e.g. not allowed to edit wiki), propose necessary changes. | |
271 | ||
272 | ||
273 | Git Commit Messages | |
274 | =================== | |
275 | ||
276 | Git commit messages should start with a short 50 character or less summary | |
277 | in a single paragraph. Ideally, it should start with a short prefix | |
278 | followed by a colon describing which part of the code it modifies | |
279 | e.g. "LibTestApp: extended AES-CBC tests". | |
280 | ||
281 | ||
282 | Development Workflow | |
283 | ==================== | |
284 | ||
285 | Clone a repository in the usual way, for example: | |
286 | ||
287 | git clone https://github.com/intel/intel-ipsec-mb | |
288 | ||
289 | Once your local repository is set up as above, you must use | |
290 | the following workflow. | |
291 | ||
292 | Make sure you have the latest upstream changes: | |
293 | ||
294 | git remote update | |
295 | git checkout master | |
296 | git pull origin master | |
297 | ||
298 | ||
299 | Committing a Change | |
300 | =================== | |
301 | ||
302 | Make your changes, commit them, and submit them for review: | |
303 | ||
304 | git commit -a | |
305 | ||
306 | To see how to create pull requests on GitHub, please refer to "About pull | |
307 | requests" help page (https://help.github.com/articles/about-pull-requests/). | |
308 | ||
309 | Note: Please ensure that you have your username and email address set correctly | |
310 | to let other developers know about your contribution: | |
311 | ||
312 | git config --global user.name "Firstname Lastname" | |
313 | git config --global user.email "your_email@youremail.com" | |
314 | ||
315 | ||
316 | Licenses | |
317 | ======== | |
318 | ||
319 | The code in this repository is licensed under BSD license (see LICENSE file). |